Repository navigation
feat(server): issue relaycast ar_ws_ credentials behind /v1/relaycast #121
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -149,6 +149,40 @@ reload PostgREST config between each step. | |||||||||||||||||
| The API key and subject token travel in the request. Do not call this endpoint | ||||||||||||||||||
| over a plain-http in-cluster Service until RelayAuth has TLS. | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Relaycast credential issuance | ||||||||||||||||||
|
|
||||||||||||||||||
| RelayAuth can act as the credential authority for a relaycast deployment: it | ||||||||||||||||||
| holds the `ar_` credential tag keyring, mints `ar_ws_` workspace keys, and | ||||||||||||||||||
| pushes each minted key into relaycast through the engine's caller-minted | ||||||||||||||||||
| internal contract (`POST /internal/workspaces/:id/api-key`). It is off by | ||||||||||||||||||
| default; setting all three bindings below enables the `/v1/relaycast` routes, | ||||||||||||||||||
| and a partial set fails closed — RelayAuth refuses to start. | ||||||||||||||||||
|
|
||||||||||||||||||
| | Setting | Meaning | | ||||||||||||||||||
| | --- | --- | | ||||||||||||||||||
| | `RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING[_FILE]` | The `ar_` tag keyring as JSON `{"current":"<version>","keys":{"<version>":"<secret>"}}`. Must match the keyring relaycast verifies with. | | ||||||||||||||||||
| | `RELAYAUTH_RELAYCAST_URL` | Base URL of the relaycast engine (e.g. `http://relaycast:8080`). | | ||||||||||||||||||
| | `RELAYAUTH_RELAYCAST_INTERNAL_SECRET[_FILE]` | Bearer for relaycast's `/internal` admin API (its `RELAYCAST_INTERNAL_SECRET`). | | ||||||||||||||||||
| | `RELAYAUTH_RELAYCAST_SERVICE_API_KEY[_FILE]` | Value of the admin API key, created at boot with only the `relayauth:relaycast:manage:*` scope. Same rules as the bootstrap key above. | | ||||||||||||||||||
|
|
||||||||||||||||||
| All three routes require `x-api-key` (or a bearer token) carrying | ||||||||||||||||||
| `relayauth:relaycast:manage:*`; none is public. | ||||||||||||||||||
|
|
||||||||||||||||||
| - `POST /v1/relaycast/workspaces` — body `{ "workspace_id": "..." }` may carry | ||||||||||||||||||
| a caller-chosen 64-bit snowflake; omitted, RelayAuth allocates one. It mints | ||||||||||||||||||
| an `ar_ws_` key, pushes it at `key_generation: 1`, and answers | ||||||||||||||||||
| `{ "workspace_id", "api_key", "api_key_generation" }` — the key is revealed | ||||||||||||||||||
| in this response only and is never stored. | ||||||||||||||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P2: The key is also sent to relaycast and stored there, so “revealed in this response only and is never stored” is misleading. State that RelayAuth does not persist the key; relaycast receives and stores it. Prompt for AI agents
Suggested change
|
||||||||||||||||||
| - `GET /v1/relaycast/credential-tags/:workspaceId` — answers | ||||||||||||||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P2: Document that Prompt for AI agents
Suggested change
|
||||||||||||||||||
| `{ "workspace_id", "tags" }`: every tag the keyring signs for the workspace, | ||||||||||||||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P2: Document the Prompt for AI agents
Suggested change
|
||||||||||||||||||
| the current version first. Responses are `Cache-Control: immutable`; a tag | ||||||||||||||||||
| list stays correct because rotation only appends keyring versions. | ||||||||||||||||||
|
Comment on lines
+176
to
+179
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Correct the documented response shape of the credential-tags route. The docs say the route answers 📝 Proposed fix
Committable suggestion
|
||||||||||||||||||
| - `POST /v1/relaycast/workspaces/:id/api-key` — rotates. Body | ||||||||||||||||||
| `{ "key_generation": N, "grace_ms": ... }` pushes a freshly minted `ar_ws_` | ||||||||||||||||||
| at the caller's next generation (relaycast's CAS rejects a stale generation | ||||||||||||||||||
| with 409 `stale_key_generation`); `grace_ms` keeps the superseded key | ||||||||||||||||||
| authenticating for that many milliseconds (max 3,600,000). | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Docker | ||||||||||||||||||
|
|
||||||||||||||||||
| Release images are published for Linux amd64 and arm64 at | ||||||||||||||||||
|
|
||||||||||||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,154 @@ | ||
| import assert from "node:assert/strict"; | ||
| import test from "node:test"; | ||
|
|
||
| import { | ||
| AR_SECRET_BYTES, | ||
| createCredentialTagSigner, | ||
| encodeArCredential, | ||
| encodeArWorkspaceId, | ||
| isArWorkspaceId, | ||
| mintArWorkspaceKey, | ||
| parseArCredential, | ||
| parseCredentialKeyring, | ||
| } from "../lib/credential-keyring.js"; | ||
|
|
||
| // Golden values generated by @relaycast/types encodeArCredential and | ||
| // @relaycast/engine createCredentialTagSigner (relaycast | ||
| // packages/types/src/credentials.ts, packages/engine/src/auth/credentialTags.ts) | ||
| // for this keyring, workspace and secret. They pin the vendored codec to the | ||
| // upstream implementation byte for byte. | ||
| const KEYRING_JSON = | ||
| '{"current":"b","keys":{"a":"keyring-secret-alpha-0123456789","b":"keyring-secret-bravo-0123456789"}}'; | ||
| const WORKSPACE_ID = "1749835200000000001"; | ||
| const WORKSPACE_ID_BASE62 = "25GGLyFyLOD"; | ||
| const TAG_CURRENT = "bNH207Fkugh"; | ||
| const TAGS_ALL = ["bNH207Fkugh", "amWqslAW9zJ"]; | ||
| const GOLDEN_CREDENTIAL = | ||
| "ar_ws_25GGLyFyLOD_bNH207Fkugh_003aUlTJC7tjlCTQj2uNU3MFagCXG9LRKRcwGkBIDlf3Z4OIN"; | ||
|
|
||
| function sequentialSecret(): Uint8Array { | ||
| const secret = new Uint8Array(AR_SECRET_BYTES); | ||
| for (let index = 0; index < secret.length; index += 1) { | ||
| secret[index] = index; | ||
| } | ||
| return secret; | ||
| } | ||
|
|
||
| test("keyring parser accepts the documented shape and rejects malformed input", () => { | ||
| const keyring = parseCredentialKeyring(KEYRING_JSON); | ||
| assert.equal(keyring.current, "b"); | ||
| assert.deepEqual(Object.keys(keyring.keys).sort(), ["a", "b"]); | ||
|
|
||
| assert.throws(() => parseCredentialKeyring("not json"), /not valid JSON/); | ||
| assert.throws(() => parseCredentialKeyring("{}"), /current/); | ||
| assert.throws( | ||
| () => parseCredentialKeyring('{"current":"c","keys":{"a":"keyring-secret-alpha-0123456789"}}'), | ||
| /not in the keyring/, | ||
| ); | ||
| assert.throws( | ||
| () => parseCredentialKeyring('{"current":"a","keys":{"A":"keyring-secret-alpha-0123456789"}}'), | ||
| /one letter a-z/, | ||
| ); | ||
| assert.throws( | ||
| () => parseCredentialKeyring('{"current":"a","keys":{"a":"short"}}'), | ||
| /at least 16 characters/, | ||
| ); | ||
| }); | ||
|
|
||
| test("encodeArWorkspaceId accepts only 64-bit snowflakes", () => { | ||
| assert.equal(encodeArWorkspaceId(WORKSPACE_ID), WORKSPACE_ID_BASE62); | ||
| assert.equal(encodeArWorkspaceId("0"), "00000000000"); | ||
|
|
||
| assert.equal(isArWorkspaceId(WORKSPACE_ID), true); | ||
| assert.equal(isArWorkspaceId("0"), true); | ||
| assert.equal(isArWorkspaceId("18446744073709551615"), true); | ||
| assert.equal(isArWorkspaceId("18446744073709551616"), false); | ||
| assert.equal(isArWorkspaceId("ws_abc123"), false); | ||
| assert.equal(isArWorkspaceId("-1"), false); | ||
| assert.equal(isArWorkspaceId(""), false); | ||
| assert.equal(isArWorkspaceId("007"), false); | ||
| }); | ||
|
|
||
| test("tag signing matches the relaycast golden vectors, current version first", async () => { | ||
| const signer = createCredentialTagSigner(parseCredentialKeyring(KEYRING_JSON)); | ||
|
|
||
| assert.equal(await signer.tag(WORKSPACE_ID), TAG_CURRENT); | ||
| assert.deepEqual(await signer.tags(WORKSPACE_ID), TAGS_ALL); | ||
| }); | ||
|
|
||
| test("encodeArCredential reproduces the relaycast golden credential", () => { | ||
| const credential = encodeArCredential({ | ||
| kind: "workspace", | ||
| workspaceId: WORKSPACE_ID, | ||
| tag: TAG_CURRENT, | ||
| secret: sequentialSecret(), | ||
| }); | ||
| assert.equal(credential, GOLDEN_CREDENTIAL); | ||
|
|
||
| assert.deepEqual(parseArCredential(credential), { | ||
| kind: "workspace", | ||
| workspaceId: WORKSPACE_ID, | ||
| tag: TAG_CURRENT, | ||
| keyVersion: "b", | ||
| }); | ||
| }); | ||
|
|
||
| test("parseArCredential rejects corrupted and foreign-shaped credentials", () => { | ||
| assert.equal(parseArCredential(GOLDEN_CREDENTIAL.slice(0, -1) + "0"), undefined); | ||
| // A flipped secret character breaks the checksum. | ||
| const corrupted = `${GOLDEN_CREDENTIAL.slice(0, 40)}${GOLDEN_CREDENTIAL[40] === "0" ? "1" : "0"}${GOLDEN_CREDENTIAL.slice(41)}`; | ||
| assert.equal(parseArCredential(corrupted), undefined); | ||
| assert.equal(parseArCredential("rk_live_abcdef0123456789"), undefined); | ||
| // A tag version letter must be lowercase. | ||
| assert.equal(parseArCredential("ar_ws_25GGLyFyLOD_BNH207Fkugh_003aUlTJC7tjlCTQj2uNU3MFagCXG9LRKRcwGkBIDlf3Z4OIN"), undefined); | ||
| }); | ||
|
|
||
| test("minted ar_ws_ keys parse, verify against the keyring, and are unique", async () => { | ||
| const signer = createCredentialTagSigner(parseCredentialKeyring(KEYRING_JSON)); | ||
|
|
||
| const first = await mintArWorkspaceKey(signer, WORKSPACE_ID); | ||
| const second = await mintArWorkspaceKey(signer, WORKSPACE_ID); | ||
| assert.notEqual(first, second); | ||
| assert.match(first, /^ar_ws_[0-9A-Za-z]{11}_[a-z][0-9A-Za-z]{10}_[0-9A-Za-z]{49}$/); | ||
|
|
||
| const parsed = parseArCredential(first); | ||
| assert.equal(parsed?.kind, "workspace"); | ||
| assert.equal(parsed?.workspaceId, WORKSPACE_ID); | ||
| assert.equal(parsed?.tag, TAG_CURRENT); | ||
| assert.equal(await signer.verify(first), true); | ||
| }); | ||
|
|
||
| test("verify refuses credentials a different keyring tagged, and forged tags", async () => { | ||
| const signer = createCredentialTagSigner(parseCredentialKeyring(KEYRING_JSON)); | ||
| const foreign = createCredentialTagSigner( | ||
| parseCredentialKeyring('{"current":"a","keys":{"a":"another-keyring-secret-0123456789"}}'), | ||
| ); | ||
|
|
||
| const credential = await mintArWorkspaceKey(signer, WORKSPACE_ID); | ||
| const foreignCredential = await mintArWorkspaceKey(foreign, WORKSPACE_ID); | ||
| // A credential whose tag was minted for a different workspace is a forgery: | ||
| // the tag proves the keyring signed *this* workspace. | ||
| const forged = encodeArCredential({ | ||
| kind: "workspace", | ||
| workspaceId: WORKSPACE_ID, | ||
| tag: await signer.tag("18446744073709551615"), | ||
| secret: sequentialSecret(), | ||
| }); | ||
|
|
||
| assert.equal(await signer.verify(credential), true); | ||
| assert.equal(await signer.verify(foreignCredential), false); | ||
| assert.equal(await signer.verify(forged), false); | ||
| assert.equal(await foreign.verify(credential), false); | ||
| }); | ||
|
|
||
| test("keyring rotation keeps tags for old versions verifiable", async () => { | ||
| const before = createCredentialTagSigner( | ||
| parseCredentialKeyring('{"current":"a","keys":{"a":"keyring-secret-alpha-0123456789"}}'), | ||
| ); | ||
| const credential = await mintArWorkspaceKey(before, WORKSPACE_ID); | ||
| assert.equal(parseArCredential(credential)?.keyVersion, "a"); | ||
|
|
||
| const after = createCredentialTagSigner(parseCredentialKeyring(KEYRING_JSON)); | ||
| assert.equal(await after.verify(credential), true); | ||
| assert.equal(parseArCredential(await mintArWorkspaceKey(after, WORKSPACE_ID))?.keyVersion, "b"); | ||
| }); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P1: This example sends newly minted
ar_ws_credentials over plaintext HTTP. Use HTTPS or clearly require a protected encrypted service-to-service transport before deploying this configuration.Prompt for AI agents