Skip to content

Commit 4e0ada1

Browse files
committed
Initial release
0 parents  commit 4e0ada1

30 files changed

Lines changed: 2247 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
check:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
16+
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
17+
with:
18+
bun-version: 1.3.14
19+
- run: bun install --frozen-lockfile
20+
- run: bun run check

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules/
2+
.bun-tmp/
3+
dist/
4+
build/
5+
*.tsbuildinfo
6+
*.zip
7+
.DS_Store

‎CONTRIBUTING.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Contributing
2+
3+
Install dependencies with `bun install`, then run `bun run check` before opening a pull request.
4+
5+
Keep credentials and durable Spacefast Link tokens on the server. Browser code may receive only short-lived frame sessions or host-signed grants.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Spacefast
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Spacefast Frames
2+
3+
Secure Spacefast embeds for websites, WordPress, dashboards, and MCP Apps.
4+
5+
This repository contains two maintained integrations:
6+
7+
- [`@spacefast/frames`](packages/frames) — a small browser library that mounts a Spacefast iframe and renews its short-lived frame session.
8+
- [`Spacefast Frames for WordPress`](packages/wordpress-plugin) — a native dynamic Gutenberg block with OAuth PKCE, multi-space page selection, path and capability controls, and server-side session minting.
9+
10+
The durable OAuth credential and Frame Link token stay on the host server. The browser receives only an origin-bound, short-lived frame session. Public Spaces can use the same embed path without requiring a viewer login; the Link still defines the allowed origin and capabilities.
11+
12+
## Develop
13+
14+
Requirements: [Bun](https://bun.sh/) 1.3.14 or newer and PHP 8.1 or newer.
15+
16+
```sh
17+
bun install
18+
bun run check
19+
```
20+
21+
Build the WordPress plugin, then create an installable ZIP:
22+
23+
```sh
24+
bun run build:wordpress
25+
cd packages/wordpress-plugin
26+
zip -r spacefast-frames.zip spacefast-frames.php includes build README.md
27+
```
28+
29+
## License
30+
31+
MIT

‎bun.lock‎

Lines changed: 43 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"name": "spacefast-frames",
3+
"private": true,
4+
"type": "module",
5+
"packageManager": "bun@1.3.14",
6+
"engines": {
7+
"bun": ">=1.3.14",
8+
"node": ">=20"
9+
},
10+
"workspaces": [
11+
"packages/*"
12+
],
13+
"scripts": {
14+
"build": "bun run build:frames && bun run build:wordpress",
15+
"build:frames": "bun --filter @spacefast/frames build",
16+
"build:wordpress": "bun --filter @spacefast/wordpress-plugin build",
17+
"test": "bun --filter @spacefast/frames test && bun --filter @spacefast/wordpress-plugin test",
18+
"typecheck": "bun --filter @spacefast/frames typecheck && bun --filter @spacefast/wordpress-plugin typecheck",
19+
"check": "bun run typecheck && bun run test && bun run build"
20+
},
21+
"devDependencies": {
22+
"bun-types": "1.3.14",
23+
"typescript": "^6.0.3"
24+
}
25+
}

‎packages/frames/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# @spacefast/frames
2+
3+
Embed a Spacefast page without putting a Spacefast OAuth token in the browser.
4+
The host application mints a short-lived, origin-bound frame session on its
5+
server; this library mounts the iframe and renews that session before it expires.
6+
7+
```ts
8+
import { createSpacefastFrame } from "@spacefast/frames";
9+
10+
createSpacefastFrame(document.querySelector("#demo")!, {
11+
path: "/pricing",
12+
title: "Pricing calculator",
13+
permissions: ["clipboard-write", "fullscreen"],
14+
session: async ({ path, signal }) => {
15+
const response = await fetch("/api/spacefast/frame-session", {
16+
method: "POST",
17+
headers: { "content-type": "application/json" },
18+
body: JSON.stringify({ path }),
19+
signal,
20+
});
21+
if (!response.ok) throw new Error(`Frame session failed (${response.status}).`);
22+
return response.json();
23+
},
24+
});
25+
```
26+
27+
Create a Spacefast Link with `constraints.frameOrigin`, then launch sessions
28+
from `/v1/spaces/{spaceId}/share-links/{linkId}/frame-session`. The launch
29+
derives its origin, resources, capabilities, expiry, and revocation state from
30+
that Link. The host server keeps its OAuth credential and Link token private.
31+
Spacefast frame URLs are HTTPS-only except on loopback development hosts.

‎packages/frames/package.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"name": "@spacefast/frames",
3+
"version": "0.0.27",
4+
"license": "MIT",
5+
"description": "Securely embed authenticated Spacefast pages in third-party applications.",
6+
"repository": {
7+
"type": "git",
8+
"url": "git+https://github.com/spacefast/frames.git",
9+
"directory": "packages/frames"
10+
},
11+
"homepage": "https://github.com/spacefast/frames/tree/main/packages/frames#readme",
12+
"bugs": {
13+
"url": "https://github.com/spacefast/frames/issues"
14+
},
15+
"type": "module",
16+
"files": [
17+
"dist",
18+
"README.md"
19+
],
20+
"engines": {
21+
"node": ">=20"
22+
},
23+
"publishConfig": {
24+
"access": "public"
25+
},
26+
"scripts": {
27+
"build": "tsc -b tsconfig.build.json",
28+
"prepack": "bun run build",
29+
"test": "bun test ./src/*.test.ts",
30+
"typecheck": "tsc --project tsconfig.json --noEmit"
31+
},
32+
"exports": {
33+
".": {
34+
"types": "./dist/index.d.ts",
35+
"import": "./dist/index.js"
36+
}
37+
},
38+
"devDependencies": {
39+
"typescript": "^6.0.3"
40+
}
41+
}

‎packages/frames/src/index.test.ts‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import { describe, expect, test } from "bun:test";
2+
3+
import { assertFrameSession, frameAllowPolicy, normalizeFramePath } from "./index.js";
4+
5+
describe("normalizeFramePath", () => {
6+
test("canonicalizes page paths", () => {
7+
expect(normalizeFramePath("/guides/./start/index.html")).toBe("/guides/start");
8+
expect(normalizeFramePath("/guides/next/../start")).toBe("/guides/start");
9+
expect(normalizeFramePath("/")).toBe("/");
10+
});
11+
12+
test("rejects URL-shaped and root-escaping input", () => {
13+
for (const path of [
14+
"https://example.com/page",
15+
"//example.com",
16+
"/../../secret",
17+
"/a%2Fb",
18+
"/a?b=1",
19+
]) {
20+
expect(() => normalizeFramePath(path)).toThrow();
21+
}
22+
});
23+
});
24+
25+
test("frameAllowPolicy emits only supported, unique permissions", () => {
26+
expect(frameAllowPolicy(["fullscreen", "camera", "fullscreen"])).toBe("camera; fullscreen");
27+
});
28+
29+
test("assertFrameSession requires a live HTTPS session", () => {
30+
const expiresAt = new Date(Date.now() + 60_000).toISOString();
31+
expect(assertFrameSession({ url: "https://demo.view.fast/?__=sfv_token", expiresAt })).toEqual({
32+
url: "https://demo.view.fast/?__=sfv_token",
33+
expiresAt,
34+
});
35+
expect(() => assertFrameSession({ url: "http://demo.example/page", expiresAt })).toThrow(
36+
"must use HTTPS",
37+
);
38+
expect(() =>
39+
assertFrameSession({
40+
url: "https://demo.view.fast/",
41+
expiresAt: new Date(Date.now() - 1_000).toISOString(),
42+
}),
43+
).toThrow("already expired");
44+
});

0 commit comments

Comments
 (0)