Skip to content

Commit 88eb5fd

Browse files
committed
Correct released config support and identity lifecycle guidance
1 parent a01363c commit 88eb5fd

4 files changed

Lines changed: 9 additions & 54 deletions

File tree

‎content/(account)/identity-connections.mdx‎

Lines changed: 4 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -109,54 +109,9 @@ A visitor who cannot open a page sees the Space's access page. It shows **Contin
109109

110110
## Build a signer
111111

112-
A `signer` connection sends visitors to your portal, and your portal vouches for them. The round trip has four steps:
112+
A signer connection lets your portal prove a visitor's identity with an Ed25519 key registered on the connection. The proof's subject must match the subject on a Space grant. Signer proofs live at most 30 minutes; the OIDC session lifetime has a separate limit.
113113

114-
1. The visitor presses **Continue with** on the access page. Spacefast redirects the browser to your `authorizeUrl` with the query parameters below.
115-
2. Your portal signs the visitor in and signs a proof token.
116-
3. Your server sends the proof to Spacefast and receives a short-lived token.
117-
4. Your portal sends the browser to `/__sf/redeem` on `host`, with the `sf_token` and `return` query parameters. The Space sets a session cookie and opens the page.
118-
119-
| Query parameter | What it holds |
120-
| --- | --- |
121-
| `spaceId` | The Space the visitor is opening |
122-
| `host` | The hostname the visitor is on. The proof's `aud` must equal it |
123-
| `return` | The path to open after sign-in |
124-
| `browserState` | A 64-character hex value that binds the sign-in to this browser. Send it back unchanged |
125-
126-
### The proof token
127-
128-
The proof is a JWT signed with one of the Ed25519 keys on the connection.
129-
130-
| Part | Requirement |
131-
| --- | --- |
132-
| `alg` header | `EdDSA` or `Ed25519` |
133-
| `kid` header | The `kid` of a key on the connection |
134-
| `iss` | The connection's issuer. A trailing slash is allowed |
135-
| `sub` | The visitor's subject. Grants match this value |
136-
| `aud` | The `host` query parameter |
137-
| `iat` | Issue time in seconds. At most 300 seconds in the future |
138-
| `exp` | Expiry in seconds. Later than `iat`. `exp` minus `iat` must not exceed the connection's `sessionTtlSeconds` or 1,800 |
139-
140-
### Exchange the proof
141-
142-
Send the proof from your server, not from the browser:
143-
144-
```bash
145-
curl https://api.spacefast.com/identity/acn_xxxxxxxx/exchange \
146-
-H "Authorization: Bearer $PROOF_JWT" \
147-
-H "Content-Type: application/json" \
148-
-d '{"spaceId":"<spaceId>","host":"<host>","resource":"<return>","browserState":"<browserState>"}'
149-
```
150-
151-
A `200` answers with `token` and `expiresAt`. A `403` means the proof failed or no grant admits that subject to `resource`.
152-
153-
Redirect the browser to `/__sf/redeem` on the same `host` within 60 seconds. The token works once, and only in the browser that started the sign-in. Encode each value as one query parameter. A `return` such as `/docs?tab=a&sort=b` holds `&` and `=`, so do not join the strings by hand:
154-
155-
```js
156-
const redeem = new URL(`https://${host}/__sf/redeem`);
157-
redeem.searchParams.set("sf_token", token);
158-
redeem.searchParams.set("return", returnPath);
159-
```
114+
The proof-exchange protocol is not part of the public API reference. Contact [support@spacefast.com](mailto:support@spacefast.com) for the current integration steps.
160115

161116
## Update a connection
162117

@@ -171,9 +126,9 @@ Leave **Replacement client secret** blank to keep the current secret. To rename
171126

172127
[`updateTeamIdentityConnection`](/api/reference/teams/updateteamidentityconnection) accepts `name`, `clientId`, `clientSecret`, `authorizeUrl`, `publicKeys`, and `sessionTtlSeconds`. It accepts `sessionTtlSeconds` from 60 to 86,400. For a signer, Spacefast lowers any value above 1,800 to 1,800. `publicKeys` replaces the whole key set. The `type` and `issuer` cannot change.
173128

174-
Grants that use the connection keep working. A change to the client ID, client secret, keys, or session lifetime sets `rotatedAt`.
129+
Grants that use the connection survive rotation. Changing the client ID, client secret, key set, or session lifetime ends sessions admitted through the connection, so those visitors sign in again. Renaming a connection does not end sessions.
175130

176-
To rotate a signer key without a sign-in gap:
131+
To keep both signing keys valid during a transition:
177132

178133
1. Send a key set that holds the old key and the new key.
179134
2. Sign new proofs with the new key.

‎content/(dynamic)/functions.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ export default {
8282
};
8383
```
8484

85-
`sf init my-app --runtime functions` writes exactly that file plus the matching `sf.jsonc`.
85+
`sf init my-app --runtime functions` writes exactly that file plus the matching `spacefast.config.ts`.
8686

8787
Requests and responses are the standard `Request` and `Response`. There is no Spacefast wrapper around either.
8888

‎content/(reference)/config-file.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,7 @@ export default defineConfig(async () => ({
167167

168168
The CLI bundles the file and its relative imports, then runs the bundle in its own process. Package imports and Node.js built-ins are not bundled. They resolve from the project directory when the config loads.
169169

170-
`sf build`, `sf publish`, and hosted Git builds load the config before they run the install command. A package import therefore fails on a fresh checkout. Import only relative files and Node.js built-ins.
170+
`sf build`, `sf publish`, and hosted Git builds load the config before they run the install command. Package imports other than `spacefast/config` must already be installed when the config loads. For a fresh checkout, use relative files, Node.js built-ins, and `spacefast/config` so the config does not depend on that install step.
171171

172172
The resolved value must be a JSON object. Strings, numbers, booleans, `null`, arrays, and plain objects are allowed. A key set to `undefined` is dropped. Any other value, for example a `Date`, fails the load.
173173

@@ -186,7 +186,7 @@ The CLI provides the `spacefast/config` module.
186186
The CLI supplies the module when it loads the file, so the project needs no dependency for it.
187187

188188
:::note[Editor types]
189-
The `spacefast` package on npm does not include `spacefast/config` yet. TypeScript in your editor cannot resolve the import, but the CLI still loads the file.
189+
The published `spacefast` package includes `spacefast/config` and its types. For editor type checking, add it as a development dependency with `npm install --save-dev spacefast`. The CLI supplies the helper when loading the config even without that project dependency.
190190
:::
191191

192192
`defineConfig` is optional. A plain default export works the same way.
@@ -226,7 +226,7 @@ Files that the config imports are ordinary files. If they are in the published d
226226

227227
Hosted Git builds run the same CLI build, so they evaluate a committed `spacefast.config.ts` too.
228228

229-
A publish that sends individual files through the API or MCP cannot evaluate the file. If those files include `spacefast.config.ts`, the publish fails. To publish a project with a TypeScript config, run `sf publish` from the project directory.
229+
Loose-file publishing through the API or MCP does not evaluate TypeScript config. This includes local MCP publishing when a local directory becomes a file upload. If the upload includes `spacefast.config.ts`, it fails. Run `sf publish` from the project directory to evaluate the config, or run `sf build` and publish its `.spacefast/build-output.tgz` archive with `--prebuilt`. Sending the framework output directory alone does not carry the resolved project config.
230230

231231
## Migrate from sf.jsonc
232232

‎content/(serve)/routing.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ They merge into one list in that order: `_redirects` rules first, then `redirect
2222

2323
A config rule whose source is already claimed by an unconditional file rule never runs, and publish reports `redirect_shadowed_by_file`: `_redirects already routes "{source}", so this rule never runs.`
2424

25-
The config file is `sf.jsonc`. These names also work, in this precedence order: `spacefast.jsonc`, `spacefast.json`, `sf.json`, `.sf/sf.json`, `.sf/config.jsonc`, `.sf/config.json`.
25+
The project config can be `spacefast.config.ts` or `sf.jsonc`. Edit the selected file; TypeScript takes precedence over JSON config. See [Project config reference](/config-file) for discovery order.
2626

2727
`_redirects` and `_headers` are published but never served as content. Requesting one returns 404.
2828

0 commit comments

Comments
 (0)