From d4c7f36e457ba8e0a63df3adb468359a8d3e5925 Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Mon, 2 Nov 2026 16:05:44 -0800 Subject: [PATCH] feat(server): issue relaycast ar_ws_ credentials behind /v1/relaycast RelayAuth becomes the credential authority for relaycast (model B): it holds the ar_ credential tag keyring, mints ar_ws_ workspace keys, and pushes them into relaycast's caller-minted POST /internal/workspaces/:id/api-key contract. - lib/credential-keyring.ts vendors the ar_ codec (base62, crc32, keyring parse, HMAC tag signer) from @relaycast/types and @relaycast/engine; golden vectors pin it to the upstream byte format. - lib/snowflake.ts vendors relaycast's generator (same epoch/layout) for server-allocated workspace ids. - lib/relaycast.ts resolves the three new bindings fail-closed, defines the injectable RelaycastWorkspaceKeyPusher boundary, and ships the fetch implementation that maps relaycast's error envelope. - routes/relaycast.ts adds three scoped routes behind relayauth:relaycast:manage:* (the design's admin:* is not a valid scope action under the sdk parser; manage is the equivalent verb): POST /v1/relaycast/workspaces mint + push at generation 1 GET /v1/relaycast/credential-tags/:id all keyring tags, immutable POST /v1/relaycast/workspaces/:id/api-key rotate at caller generation - server.ts mounts apiKeyAuth + routes, reads the new env bindings (with _FILE variants), asserts config at boot, and seeds RELAYAUTH_RELAYCAST_SERVICE_API_KEY through the bootstrap-key path. --- docs/self-hosting.md | 34 ++ .../src/__tests__/credential-keyring.test.ts | 154 ++++++++ .../src/__tests__/relaycast-routes.test.ts | 329 ++++++++++++++++++ packages/server/src/__tests__/test-helpers.ts | 10 + packages/server/src/env.ts | 15 + packages/server/src/lib/credential-keyring.ts | 264 ++++++++++++++ packages/server/src/lib/relaycast.ts | 189 ++++++++++ packages/server/src/lib/snowflake.ts | 88 +++++ packages/server/src/routes/relaycast.ts | 214 ++++++++++++ packages/server/src/server.ts | 31 ++ 10 files changed, 1328 insertions(+) create mode 100644 packages/server/src/__tests__/credential-keyring.test.ts create mode 100644 packages/server/src/__tests__/relaycast-routes.test.ts create mode 100644 packages/server/src/lib/credential-keyring.ts create mode 100644 packages/server/src/lib/relaycast.ts create mode 100644 packages/server/src/lib/snowflake.ts create mode 100644 packages/server/src/routes/relaycast.ts diff --git a/docs/self-hosting.md b/docs/self-hosting.md index 49c263a6..4f0b1d2d 100644 --- a/docs/self-hosting.md +++ b/docs/self-hosting.md @@ -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":"","keys":{"":""}}`. 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. +- `GET /v1/relaycast/credential-tags/:workspaceId` — answers + `{ "workspace_id", "tags" }`: every tag the keyring signs for the workspace, + the current version first. Responses are `Cache-Control: immutable`; a tag + list stays correct because rotation only appends keyring versions. +- `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 diff --git a/packages/server/src/__tests__/credential-keyring.test.ts b/packages/server/src/__tests__/credential-keyring.test.ts new file mode 100644 index 00000000..b7543ba1 --- /dev/null +++ b/packages/server/src/__tests__/credential-keyring.test.ts @@ -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"); +}); diff --git a/packages/server/src/__tests__/relaycast-routes.test.ts b/packages/server/src/__tests__/relaycast-routes.test.ts new file mode 100644 index 00000000..22bae5f5 --- /dev/null +++ b/packages/server/src/__tests__/relaycast-routes.test.ts @@ -0,0 +1,329 @@ +import assert from "node:assert/strict"; +import test from "node:test"; + +import { + createCredentialTagSigner, + encodeArWorkspaceId, + isArWorkspaceId, + parseArCredential, + parseCredentialKeyring, +} from "../lib/credential-keyring.js"; +import { RelaycastPushError, type RelaycastWorkspaceKeyPusher } from "../lib/relaycast.js"; +import { + createTestApp, + createTestRequest, + seedPlainApiKey, +} from "./test-helpers.js"; + +const KEYRING_JSON = + '{"current":"b","keys":{"a":"keyring-secret-alpha-0123456789","b":"keyring-secret-bravo-0123456789"}}'; +const RELAYCAST_BINDINGS = { + RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING: KEYRING_JSON, + RELAYAUTH_RELAYCAST_URL: "http://relaycast.internal", + RELAYAUTH_RELAYCAST_INTERNAL_SECRET: "relaycast-internal-secret-0123456789", +}; +const WORKSPACE_ID = "1749835200000000001"; +const ADMIN_SCOPE = "relayauth:relaycast:manage:*"; + +type PushCall = { + workspaceId: string; + input: { apiKey: string; keyGeneration?: number; graceMs?: number }; +}; + +function recordingPusher( + respond?: (workspaceId: string, input: PushCall["input"]) => { + workspaceId: string; + apiKeyGeneration: number; + created: boolean; + }, +): { pusher: RelaycastWorkspaceKeyPusher; calls: PushCall[] } { + const calls: PushCall[] = []; + const pusher: RelaycastWorkspaceKeyPusher = { + async pushWorkspaceKey(workspaceId, input) { + calls.push({ workspaceId, input }); + return ( + respond?.(workspaceId, input) ?? { + workspaceId, + apiKeyGeneration: input.keyGeneration ?? 0, + created: true, + } + ); + }, + }; + return { pusher, calls }; +} + +async function seedAdminKey(app: ReturnType, scopes = [ADMIN_SCOPE]) { + return seedPlainApiKey(app, { orgId: "org_test", name: "relaycast-admin", scopes }); +} + +function signer() { + return createCredentialTagSigner(parseCredentialKeyring(KEYRING_JSON)); +} + +test("relaycast routes reject missing and insufficient credentials", async () => { + const { pusher } = recordingPusher(); + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: pusher }); + try { + const missing = await app.request( + createTestRequest("POST", "/v1/relaycast/workspaces", { workspace_id: WORKSPACE_ID }), + ); + assert.equal(missing.status, 401); + + const { key: otherKey } = await seedAdminKey(app, ["relayauth:api-key:manage:*"]); + const denied = await app.request( + createTestRequest( + "POST", + "/v1/relaycast/workspaces", + { workspace_id: WORKSPACE_ID }, + { "x-api-key": otherKey }, + ), + ); + assert.equal(denied.status, 403); + } finally { + await app.close(); + } +}); + +test("relaycast routes answer 503 when issuance is not configured or partially configured", async () => { + for (const bindings of [ + {}, + { RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING: KEYRING_JSON }, + { + RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING: KEYRING_JSON, + RELAYAUTH_RELAYCAST_URL: "http://relaycast.internal", + }, + ]) { + const { pusher, calls } = recordingPusher(); + const app = createTestApp(bindings, { relaycastKeyPusher: pusher }); + try { + const { key } = await seedAdminKey(app); + const response = await app.request( + createTestRequest( + "POST", + "/v1/relaycast/workspaces", + { workspace_id: WORKSPACE_ID }, + { "x-api-key": key }, + ), + ); + assert.equal(response.status, 503); + const body = (await response.json()) as { code?: string }; + assert.equal(body.code, "relaycast_not_configured"); + assert.equal(calls.length, 0, "a misconfigured deployment must never push a key"); + } finally { + await app.close(); + } + } +}); + +test("POST /v1/relaycast/workspaces mints an ar_ws_ key for a caller-supplied snowflake and pushes it at generation 1", async () => { + const { pusher, calls } = recordingPusher(); + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: pusher }); + try { + const { key } = await seedAdminKey(app); + const response = await app.request( + createTestRequest( + "POST", + "/v1/relaycast/workspaces", + { workspace_id: WORKSPACE_ID }, + { "x-api-key": key }, + ), + ); + assert.equal(response.status, 201); + const body = (await response.json()) as { + workspace_id: string; + api_key: string; + api_key_generation: number; + }; + assert.equal(body.workspace_id, WORKSPACE_ID); + assert.equal(body.api_key_generation, 1); + + const parsed = parseArCredential(body.api_key); + assert.equal(parsed?.kind, "workspace"); + assert.equal(parsed?.workspaceId, WORKSPACE_ID); + assert.equal(await signer().verify(body.api_key), true); + + assert.equal(calls.length, 1); + assert.equal(calls[0]?.workspaceId, WORKSPACE_ID); + assert.equal(calls[0]?.input.apiKey, body.api_key); + assert.equal(calls[0]?.input.keyGeneration, 1); + } finally { + await app.close(); + } +}); + +test("POST /v1/relaycast/workspaces allocates a snowflake workspace id when none is supplied", async () => { + const { pusher, calls } = recordingPusher(); + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: pusher }); + try { + const { key } = await seedAdminKey(app); + const first = await app.request( + createTestRequest("POST", "/v1/relaycast/workspaces", {}, { "x-api-key": key }), + ); + assert.equal(first.status, 201); + const firstBody = (await first.json()) as { workspace_id: string; api_key: string }; + assert.equal(isArWorkspaceId(firstBody.workspace_id), true); + + const second = await app.request( + createTestRequest("POST", "/v1/relaycast/workspaces", {}, { "x-api-key": key }), + ); + const secondBody = (await second.json()) as { workspace_id: string }; + assert.notEqual(firstBody.workspace_id, secondBody.workspace_id); + + assert.equal(calls.every((call) => isArWorkspaceId(call.workspaceId)), true); + } finally { + await app.close(); + } +}); + +test("POST /v1/relaycast/workspaces refuses a workspace id that is not a snowflake", async () => { + const { pusher, calls } = recordingPusher(); + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: pusher }); + try { + const { key } = await seedAdminKey(app); + for (const workspaceId of ["ws_abc", "18446744073709551616", "-1", "", 123] as const) { + const response = await app.request( + createTestRequest( + "POST", + "/v1/relaycast/workspaces", + { workspace_id: workspaceId }, + { "x-api-key": key }, + ), + ); + assert.equal(response.status, 400, String(workspaceId)); + } + assert.equal(calls.length, 0); + } finally { + await app.close(); + } +}); + +test("GET /v1/relaycast/credential-tags/:workspaceId returns every keyring tag, current first, cacheable", async () => { + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: recordingPusher().pusher }); + try { + const { key } = await seedAdminKey(app); + const wsid = encodeArWorkspaceId(WORKSPACE_ID); + const response = await app.request( + createTestRequest("GET", `/v1/relaycast/credential-tags/${wsid}`, undefined, { + "x-api-key": key, + }), + ); + assert.equal(response.status, 200); + const body = (await response.json()) as { ok: boolean; data: { workspace_id: string; tags: string[] } }; + assert.equal(body.ok, true); + assert.equal(body.data.workspace_id, WORKSPACE_ID); + assert.deepEqual(body.data.tags, await signer().tags(WORKSPACE_ID)); + assert.equal(body.data.tags[0]?.[0], "b"); + assert.match(response.headers.get("cache-control") ?? "", /max-age/); + } finally { + await app.close(); + } +}); + +test("GET /v1/relaycast/credential-tags/:workspaceId refuses non-snowflake ids", async () => { + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: recordingPusher().pusher }); + try { + const { key } = await seedAdminKey(app); + const response = await app.request( + createTestRequest("GET", "/v1/relaycast/credential-tags/ws_abc", undefined, { + "x-api-key": key, + }), + ); + assert.equal(response.status, 400); + } finally { + await app.close(); + } +}); + +test("POST /v1/relaycast/workspaces/:id/api-key rotates with the caller's generation and grace", async () => { + const { pusher, calls } = recordingPusher((workspaceId, input) => ({ + workspaceId, + apiKeyGeneration: input.keyGeneration ?? 0, + created: false, + })); + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: pusher }); + try { + const { key } = await seedAdminKey(app); + const response = await app.request( + createTestRequest( + "POST", + `/v1/relaycast/workspaces/${WORKSPACE_ID}/api-key`, + { key_generation: 2, grace_ms: 60_000 }, + { "x-api-key": key }, + ), + ); + assert.equal(response.status, 200); + const body = (await response.json()) as { + workspace_id: string; + api_key: string; + api_key_generation: number; + }; + assert.equal(body.workspace_id, WORKSPACE_ID); + assert.equal(body.api_key_generation, 2); + assert.equal(await signer().verify(body.api_key), true); + + assert.equal(calls.length, 1); + assert.equal(calls[0]?.input.keyGeneration, 2); + assert.equal(calls[0]?.input.graceMs, 60_000); + assert.equal(calls[0]?.input.apiKey, body.api_key); + } finally { + await app.close(); + } +}); + +test("POST /v1/relaycast/workspaces/:id/api-key requires key_generation and a snowflake id", async () => { + const { pusher, calls } = recordingPusher(); + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: pusher }); + try { + const { key } = await seedAdminKey(app); + const missingGeneration = await app.request( + createTestRequest( + "POST", + `/v1/relaycast/workspaces/${WORKSPACE_ID}/api-key`, + {}, + { "x-api-key": key }, + ), + ); + assert.equal(missingGeneration.status, 400); + + const badId = await app.request( + createTestRequest( + "POST", + "/v1/relaycast/workspaces/ws_abc/api-key", + { key_generation: 2 }, + { "x-api-key": key }, + ), + ); + assert.equal(badId.status, 400); + assert.equal(calls.length, 0); + } finally { + await app.close(); + } +}); + +test("a stale generation push surfaces relaycast's 409 instead of minting success", async () => { + const { pusher } = recordingPusher(() => { + throw new RelaycastPushError( + "key_generation 2 does not beat the stored generation 5", + "stale_key_generation", + 409, + ); + }); + const app = createTestApp(RELAYCAST_BINDINGS, { relaycastKeyPusher: pusher }); + try { + const { key } = await seedAdminKey(app); + const response = await app.request( + createTestRequest( + "POST", + `/v1/relaycast/workspaces/${WORKSPACE_ID}/api-key`, + { key_generation: 2 }, + { "x-api-key": key }, + ), + ); + assert.equal(response.status, 409); + const body = (await response.json()) as { code?: string }; + assert.equal(body.code, "stale_key_generation"); + } finally { + await app.close(); + } +}); diff --git a/packages/server/src/__tests__/test-helpers.ts b/packages/server/src/__tests__/test-helpers.ts index 233a2211..82043cac 100644 --- a/packages/server/src/__tests__/test-helpers.ts +++ b/packages/server/src/__tests__/test-helpers.ts @@ -9,6 +9,7 @@ import type { import type { Hono } from "hono"; import type { AppEnv } from "../env.js"; import type { DeferredTaskScheduler } from "../lib/deferred.js"; +import type { CreateAppOptions } from "../server.js"; import { FixedWindowRateLimiter, FixedWindowSketchRateLimiter, @@ -45,6 +46,9 @@ type TestBindings = Pick< | "RELAYAUTH_SESSION_DIRECTORY_SIGNING_KEY_PEM_PREVIOUS" | "RELAYAUTH_SESSION_DIRECTORY_SUBJECT_AUDIENCES" | "RELAYAUTH_OBSERVER_ENABLED" + | "RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING" + | "RELAYAUTH_RELAYCAST_URL" + | "RELAYAUTH_RELAYCAST_INTERNAL_SECRET" | "BASE_URL" >; @@ -65,6 +69,9 @@ const PASS_THROUGH_TEST_BINDINGS = [ "RELAYAUTH_SESSION_DIRECTORY_SIGNING_KEY_PEM_PREVIOUS", "RELAYAUTH_SESSION_DIRECTORY_SUBJECT_AUDIENCES", "RELAYAUTH_OBSERVER_ENABLED", + "RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING", + "RELAYAUTH_RELAYCAST_URL", + "RELAYAUTH_RELAYCAST_INTERNAL_SECRET", "BASE_URL", ] as const satisfies readonly (keyof TestBindings)[]; @@ -91,6 +98,8 @@ type TestAppOptions = { * the helper's deliberately generous per-test limiter. */ useBindingRevocationCheckRateLimiter?: boolean; + /** Replace the relaycast key push (an effectful boundary) with a test double. */ + relaycastKeyPusher?: CreateAppOptions["relaycastKeyPusher"]; }; type TestApp = Hono & { @@ -342,6 +351,7 @@ export function createTestApp( ...(identityCreatePreAuthRateLimiter ? { identityCreatePreAuthRateLimiter } : {}), ...(identityCreateRateLimiter ? { identityCreateRateLimiter } : {}), ...(revocationCheckRateLimiter ? { revocationCheckRateLimiter } : {}), + ...(options.relaycastKeyPusher ? { relaycastKeyPusher: options.relaycastKeyPusher } : {}), }); const testApp = app as TestApp; diff --git a/packages/server/src/env.ts b/packages/server/src/env.ts index 9a5fe732..cae0bb96 100644 --- a/packages/server/src/env.ts +++ b/packages/server/src/env.ts @@ -1,6 +1,7 @@ import type { RelayAuthTokenClaims } from "@relayauth/types"; import type { DeferredTaskScheduler } from "./lib/deferred.js"; import type { RequestRateLimiter } from "./lib/rate-limit.js"; +import type { RelaycastWorkspaceKeyPusher } from "./lib/relaycast.js"; import type { AuthStorage } from "./storage/index.js"; import type { SponsorOidcService } from "./lib/sponsor-binding.js"; @@ -103,6 +104,17 @@ export type AppConfig = { * requires a fresh capacity sample; without one it stays off. */ RELAYAUTH_STORAGE_CAPACITY_SHED_RATIO?: string; + /** + * The `ar_` credential tag keyring RelayAuth signs relaycast tags with, as + * JSON `{"current":"","keys":{"":""}}`. Together + * with RELAYAUTH_RELAYCAST_URL and RELAYAUTH_RELAYCAST_INTERNAL_SECRET it + * enables the /v1/relaycast issuance routes; a partial set fails closed. + */ + RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING?: string; + /** Base URL of the relaycast engine that receives pushed `ar_ws_` keys. */ + RELAYAUTH_RELAYCAST_URL?: string; + /** Bearer for relaycast's `/internal` admin API (its RELAYCAST_INTERNAL_SECRET). */ + RELAYAUTH_RELAYCAST_INTERNAL_SECRET?: string; }; export type AppEnv = { @@ -123,5 +135,8 @@ export type AppEnv = { apiKeyClaims?: RelayAuthTokenClaims; apiKeyVia?: "api_key"; identityCreateRateLimitChecked?: boolean; + // Injected test double for the relaycast key push (see CreateAppOptions); + // absent, the routes build the fetch-based pusher from the bindings. + relaycastKeyPusher?: RelaycastWorkspaceKeyPusher; }; }; diff --git a/packages/server/src/lib/credential-keyring.ts b/packages/server/src/lib/credential-keyring.ts new file mode 100644 index 00000000..3d9b9565 --- /dev/null +++ b/packages/server/src/lib/credential-keyring.ts @@ -0,0 +1,264 @@ +/** + * Relaycast `ar_` credential codec, vendored from `@relaycast/types` + * (packages/types/src/credentials.ts) and `@relaycast/engine` + * (packages/engine/src/auth/credentialTags.ts) so RelayAuth can act as the + * credential authority — holding the tag keyring and minting `ar_ws_` + * workspace keys — without a runtime dependency on either package. + * + * The golden vectors in `__tests__/credential-keyring.test.ts` were generated + * by those upstream sources; keep this file byte-compatible with them. + */ + +export type ArCredentialKind = "workspace" | "agent" | "node" | "observer" | "webhook"; + +export type ParsedArCredential = { + kind: ArCredentialKind; + /** The workspace snowflake, in decimal. */ + workspaceId: string; + /** The routing tag: key version letter plus 10 base62 characters. */ + tag: string; + /** The keyring version that signed the tag. */ + keyVersion: string; +}; + +const AR_KIND_CODES: Readonly> = { + workspace: "ws", + agent: "ag", + node: "nd", + observer: "ob", + webhook: "wh", +}; + +const KIND_BY_CODE = Object.fromEntries( + Object.entries(AR_KIND_CODES).map(([kind, code]) => [code, kind]), +) as Record; + +export const AR_WORKSPACE_ID_LENGTH = 11; +export const AR_TAG_LENGTH = 11; +export const AR_SECRET_LENGTH = 43; +export const AR_CHECKSUM_LENGTH = 6; +/** Secret bytes an `ar_` credential carries. */ +export const AR_SECRET_BYTES = 32; + +const AR = /^ar_(ws|ag|nd|ob|wh)_([0-9A-Za-z]{11})_([a-z][0-9A-Za-z]{10})_([0-9A-Za-z]{43})([0-9A-Za-z]{6})$/; +const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; +const MAX_SNOWFLAKE = (1n << 64n) - 1n; + +/** `value` in base62, left-padded with `0` to `width` characters. */ +export function base62Encode(value: bigint, width: number): string { + if (value < 0n) throw new Error("base62 encodes non-negative integers"); + let out = ""; + for (let rest = value; rest > 0n; rest /= 62n) out = BASE62[Number(rest % 62n)] + out; + if (out.length > width) throw new Error(`Value does not fit ${width} base62 characters`); + return out.padStart(width, "0"); +} + +function base62Decode(text: string): bigint { + let value = 0n; + for (const char of text) { + const digit = BASE62.indexOf(char); + if (digit < 0) throw new Error("Not base62"); + value = value * 62n + BigInt(digit); + } + return value; +} + +function bytesToBigInt(bytes: Uint8Array): bigint { + let value = 0n; + for (const byte of bytes) value = (value << 8n) | BigInt(byte); + return value; +} + +/** The 11-character base62 form of a workspace snowflake (decimal, 64-bit). */ +export function encodeArWorkspaceId(workspaceId: string): string { + const value = /^(0|[1-9][0-9]{0,19})$/.test(workspaceId) ? BigInt(workspaceId) : -1n; + if (value < 0n || value > MAX_SNOWFLAKE) { + throw new Error(`Workspace id ${JSON.stringify(workspaceId)} is not a 64-bit snowflake`); + } + return base62Encode(value, AR_WORKSPACE_ID_LENGTH); +} + +/** Whether `workspaceId` is a 64-bit snowflake an `ar_` credential can carry. */ +export function isArWorkspaceId(workspaceId: string): boolean { + try { + encodeArWorkspaceId(workspaceId); + return true; + } catch { + return false; + } +} + +/** The base62 workspace segment a credential or tag request carries. */ +export function isArWorkspaceSegment(segment: string): boolean { + return /^[0-9A-Za-z]{11}$/.test(segment); +} + +/** Decode an 11-char base62 workspace segment back to its snowflake. */ +export function decodeArWorkspaceSegment(segment: string): string { + return base62Decode(segment).toString(); +} + +const CRC_TABLE = (() => { + const table = new Uint32Array(256); + for (let n = 0; n < 256; n += 1) { + let c = n; + for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; + table[n] = c >>> 0; + } + return table; +})(); + +/** CRC-32 (IEEE 802.3) of an ASCII string. */ +export function crc32(text: string): number { + let crc = 0xffffffff; + for (let i = 0; i < text.length; i += 1) crc = CRC_TABLE[(crc ^ text.charCodeAt(i)) & 0xff] ^ (crc >>> 8); + return (crc ^ 0xffffffff) >>> 0; +} + +function arChecksum(body: string): string { + return base62Encode(BigInt(crc32(body)), AR_CHECKSUM_LENGTH); +} + +/** + * Assemble an `ar_` credential: `ar____`. `tag` + * comes from the deployment keyring ({@link createCredentialTagSigner}); + * `secret` is exactly {@link AR_SECRET_BYTES} bytes. + */ +export function encodeArCredential(args: { + kind: ArCredentialKind; + workspaceId: string; + tag: string; + secret: Uint8Array; +}): string { + if (!/^[a-z][0-9A-Za-z]{10}$/.test(args.tag)) throw new Error("A credential tag is a key version letter plus 10 base62 characters"); + if (args.secret.length !== AR_SECRET_BYTES) throw new Error(`A credential secret is ${AR_SECRET_BYTES} bytes`); + const body = `ar_${AR_KIND_CODES[args.kind]}_${encodeArWorkspaceId(args.workspaceId)}_${args.tag}_` + + base62Encode(bytesToBigInt(args.secret), AR_SECRET_LENGTH); + return body + arChecksum(body); +} + +/** + * Parse an `ar_` credential into kind, workspace, tag and key version. Proves + * only shape and checksum; verify the tag with a {@link CredentialTagSigner}. + * `legacy` (`rk_live_…`) credentials return `undefined`. + */ +export function parseArCredential(token: string): ParsedArCredential | undefined { + const ar = AR.exec(token); + if (!ar) return undefined; + if (arChecksum(token.slice(0, -AR_CHECKSUM_LENGTH)) !== ar[5]) return undefined; + const workspace = base62Decode(ar[2]); + if (workspace > MAX_SNOWFLAKE) return undefined; + return { kind: KIND_BY_CODE[ar[1]], workspaceId: workspace.toString(), tag: ar[3], keyVersion: ar[3][0] }; +} + +/** Shortest key secret a keyring accepts. */ +const MIN_SECRET_LENGTH = 16; + +/** + * The keys `ar_` credential tags are signed with: one secret per version letter + * (`a`-`z`) and the version that signs new tags. Credentials outlive key + * changes, so rotation adds a version and makes it current; it never drops + * one. Removing a version locks out every credential tagged under it. + */ +export type CredentialKeyring = { + current: string; + keys: Readonly>; +}; + +/** Parse a keyring from configuration: `{"current":"b","keys":{"a":"","b":""}}`. */ +export function parseCredentialKeyring(json: string): CredentialKeyring { + let value: unknown; + try { + value = JSON.parse(json); + } catch { + throw new Error("The credential keyring is not valid JSON"); + } + const { current, keys } = (value ?? {}) as { current?: unknown; keys?: unknown }; + if (typeof current !== "string" || !keys || typeof keys !== "object" || Array.isArray(keys)) { + throw new Error('The credential keyring is {"current": "", "keys": {"": ""}}'); + } + const entries = Object.entries(keys as Record); + for (const [version, secret] of entries) { + if (!/^[a-z]$/.test(version)) throw new Error(`Credential key version ${JSON.stringify(version)} is not one letter a-z`); + if (typeof secret !== "string" || secret.length < MIN_SECRET_LENGTH) { + throw new Error(`Credential key ${version} needs a secret of at least ${MIN_SECRET_LENGTH} characters`); + } + } + if (!Object.hasOwn(keys, current)) throw new Error(`The current credential key version ${JSON.stringify(current)} is not in the keyring`); + return { current, keys: Object.fromEntries(entries) as Record }; +} + +export type CredentialTagSigner = { + /** The tag new credentials for `workspaceId` carry. */ + tag(workspaceId: string): Promise; + /** Every tag a credential for `workspaceId` may carry, the current one first. */ + tags(workspaceId: string): Promise; + /** Whether an `ar_` credential's tag was signed for its workspace by a version in the keyring. */ + verify(token: string): Promise; +}; + +const TAG_BODY_LENGTH = 10; +const TAG_MODULUS = 62n ** BigInt(TAG_BODY_LENGTH); +const encoder = new TextEncoder(); + +/** + * Tags from a keyring: `<10 base62 of HMAC-SHA256(key, wsid)>`, where + * `wsid` is the credential's 11-character workspace segment. A gateway + * verifies a credential's tag with the version it names, so a credential for + * a workspace this deployment never tagged is refused without a lookup. + */ +export function createCredentialTagSigner(keyring: CredentialKeyring): CredentialTagSigner { + const keys = new Map>(); + for (const [version, secret] of Object.entries(keyring.keys)) { + if (!/^[a-z]$/.test(version)) throw new Error("A credential key version is one letter a-z"); + if (typeof secret !== "string" || secret.length < MIN_SECRET_LENGTH) { + throw new Error(`Credential key ${version} needs a secret of at least ${MIN_SECRET_LENGTH} characters`); + } + keys.set(version, crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"])); + } + if (!keys.has(keyring.current)) throw new Error("The current credential key version is not in the keyring"); + const versions = [keyring.current, ...[...keys.keys()].filter((version) => version !== keyring.current)]; + + const tagFor = async (version: string, wsid: string): Promise => { + const key = keys.get(version); + if (!key) return undefined; + const mac = new Uint8Array(await crypto.subtle.sign("HMAC", await key, encoder.encode(wsid))); + let value = 0n; + for (const byte of mac.subarray(0, 8)) value = (value << 8n) | BigInt(byte); + return version + base62Encode(value % TAG_MODULUS, TAG_BODY_LENGTH); + }; + + return { + tag(workspaceId) { + return tagFor(keyring.current, encodeArWorkspaceId(workspaceId)) as Promise; + }, + tags(workspaceId) { + const wsid = encodeArWorkspaceId(workspaceId); + return Promise.all(versions.map(async (version) => (await tagFor(version, wsid))!)); + }, + async verify(token) { + const parsed = parseArCredential(token); + if (!parsed) return false; + const expected = await tagFor(parsed.keyVersion, encodeArWorkspaceId(parsed.workspaceId)); + if (!expected) return false; + let diff = 0; + for (let i = 0; i < expected.length; i += 1) diff |= expected.charCodeAt(i) ^ parsed.tag.charCodeAt(i); + return diff === 0; + }, + }; +} + +/** Mint a fresh `ar_ws_` workspace key under the keyring's current tag. */ +export async function mintArWorkspaceKey( + signer: CredentialTagSigner, + workspaceId: string, +): Promise { + const secret = new Uint8Array(AR_SECRET_BYTES); + crypto.getRandomValues(secret); + return encodeArCredential({ + kind: "workspace", + workspaceId, + tag: await signer.tag(workspaceId), + secret, + }); +} diff --git a/packages/server/src/lib/relaycast.ts b/packages/server/src/lib/relaycast.ts new file mode 100644 index 00000000..7c6e6aa8 --- /dev/null +++ b/packages/server/src/lib/relaycast.ts @@ -0,0 +1,189 @@ +import type { AppConfig } from "../env.js"; +import { parseCredentialKeyring, type CredentialKeyring } from "./credential-keyring.js"; + +/** + * Relaycast credential issuance ("model B"): RelayAuth holds the `ar_` + * credential tag keyring, mints `ar_ws_` workspace keys, and pushes them into + * relaycast through its caller-minted internal contract + * (`POST /internal/workspaces/:id/api-key` with `{api_key, key_generation}`). + */ + +export const RELAYCAST_ADMIN_SCOPE = "relayauth:relaycast:manage:*"; +export const RELAYCAST_SERVICE_API_KEY_NAME = "bootstrap-relaycast-admin"; +const PUSH_TIMEOUT_MS = 10_000; + +type RelaycastEnv = Pick< + AppConfig, + | "RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING" + | "RELAYAUTH_RELAYCAST_URL" + | "RELAYAUTH_RELAYCAST_INTERNAL_SECRET" +>; + +export class RelaycastConfigError extends Error { + readonly code = "relaycast_not_configured"; + constructor(message: string) { + super(message); + this.name = "RelaycastConfigError"; + } +} + +export type RelaycastConfig = { + keyring: CredentialKeyring; + url: string; + internalSecret: string; +}; + +/** + * The issuance configuration, or `undefined` when no relaycast binding is set + * at all (the feature is simply off). A partially set or invalid configuration + * throws — a deployment that asked for the feature must never mint with + * defaults guessed for it. + */ +export function resolveRelaycastConfig(env: RelaycastEnv): RelaycastConfig | undefined { + const keyringJson = env.RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING?.trim(); + const url = env.RELAYAUTH_RELAYCAST_URL?.trim(); + const internalSecret = env.RELAYAUTH_RELAYCAST_INTERNAL_SECRET?.trim(); + if (!keyringJson && !url && !internalSecret) { + return undefined; + } + + const missing = [ + ["RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING", keyringJson], + ["RELAYAUTH_RELAYCAST_URL", url], + ["RELAYAUTH_RELAYCAST_INTERNAL_SECRET", internalSecret], + ] + .filter(([, value]) => !value) + .map(([name]) => name); + if (missing.length > 0) { + throw new RelaycastConfigError( + `relaycast credential issuance is partially configured; missing ${missing.join(", ")}`, + ); + } + + let keyring: CredentialKeyring; + try { + keyring = parseCredentialKeyring(keyringJson!); + } catch (error) { + throw new RelaycastConfigError( + `RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING is invalid: ${error instanceof Error ? error.message : String(error)}`, + ); + } + try { + new URL(url!); + } catch { + throw new RelaycastConfigError("RELAYAUTH_RELAYCAST_URL is not a valid URL"); + } + + return { keyring, url: url!, internalSecret: internalSecret! }; +} + +/** + * Boot-time config check, in the `assertSigningKeyConfig` family: refuse to + * start when issuance is half-configured rather than serving 503s later. + * Called before every route resolution too, because Worker deployments have + * no boot step. + */ +export function assertRelaycastConfig(env: RelaycastEnv): void { + resolveRelaycastConfig(env); +} + +export type RelaycastKeyPushInput = { + apiKey: string; + keyGeneration?: number; + graceMs?: number; +}; + +export type RelaycastKeyPushResult = { + workspaceId: string; + apiKeyGeneration: number; + /** True when the push created the workspace row in relaycast. */ + created: boolean; +}; + +/** The effectful boundary a test can replace: pushing a minted key into relaycast. */ +export type RelaycastWorkspaceKeyPusher = { + pushWorkspaceKey(workspaceId: string, input: RelaycastKeyPushInput): Promise; +}; + +/** + * A failed push, carrying relaycast's own `{code, message}` so the route can + * pass 4xx answers (e.g. `stale_key_generation` from the generation CAS) + * through to the caller. Network failures use `relaycast_unreachable` at 502. + */ +export class RelaycastPushError extends Error { + constructor( + message: string, + readonly code: string, + readonly status: number, + ) { + super(message); + this.name = "RelaycastPushError"; + } +} + +type FetchLike = (input: string, init?: RequestInit) => Promise; + +/** The production pusher: relaycast's `POST /internal/workspaces/:id/api-key` with the internal-secret bearer. */ +export function createRelaycastKeyPusher( + config: { url: string; internalSecret: string }, + fetchImpl: FetchLike = globalThis.fetch.bind(globalThis), +): RelaycastWorkspaceKeyPusher { + const base = config.url.replace(/\/+$/, ""); + return { + async pushWorkspaceKey(workspaceId, input) { + let response: Response; + try { + response = await fetchImpl( + `${base}/internal/workspaces/${encodeURIComponent(workspaceId)}/api-key`, + { + method: "POST", + headers: { + authorization: `Bearer ${config.internalSecret}`, + "content-type": "application/json", + }, + body: JSON.stringify({ + api_key: input.apiKey, + ...(input.keyGeneration === undefined ? {} : { key_generation: input.keyGeneration }), + ...(input.graceMs === undefined ? {} : { grace_ms: input.graceMs }), + }), + signal: AbortSignal.timeout(PUSH_TIMEOUT_MS), + }, + ); + } catch (error) { + throw new RelaycastPushError( + `relaycast is unreachable: ${error instanceof Error ? error.message : String(error)}`, + "relaycast_unreachable", + 502, + ); + } + + // Relaycast answers the `{ ok, data }` / `{ ok, error: {code, message} }` + // envelope; tolerate a bare `{workspace_id, api_key_generation}` too. + const body = (await response.json().catch(() => undefined)) as + | { + ok?: boolean; + data?: { workspace_id?: string; api_key_generation?: number }; + error?: { code?: string; message?: string }; + workspace_id?: string; + api_key_generation?: number; + } + | undefined; + + if (!response.ok || body?.ok === false) { + const status = response.status >= 400 && response.status < 500 ? response.status : 502; + throw new RelaycastPushError( + body?.error?.message ?? `relaycast answered HTTP ${response.status}`, + body?.error?.code ?? "relaycast_push_failed", + status, + ); + } + + const data = body?.data ?? body; + return { + workspaceId: data?.workspace_id ?? workspaceId, + apiKeyGeneration: data?.api_key_generation ?? input.keyGeneration ?? 0, + created: response.status === 201, + }; + }, + }; +} diff --git a/packages/server/src/lib/snowflake.ts b/packages/server/src/lib/snowflake.ts new file mode 100644 index 00000000..678c00a9 --- /dev/null +++ b/packages/server/src/lib/snowflake.ts @@ -0,0 +1,88 @@ +/** + * Snowflake id allocation, vendored from `@relaycast/engine` + * (packages/engine/src/engine/snowflake.ts) so a workspace id RelayAuth + * allocates is interchangeable with one relaycast's `generateId` would mint: + * same epoch (2025-01-01), same layout — 41-bit ms timestamp, 10-bit worker, + * 12-bit sequence. The worker id is an FNV-1a hash of a per-process UUID, so + * two allocators could in principle draw the same worker id; the collision + * space (worker × millisecond × sequence) is the same one relaycast accepts + * between its own isolates. + */ + +const EPOCH_MS = Date.UTC(2025, 0, 1); // 2025-01-01T00:00:00Z + +const WORKER_ID_BITS = 10n; +const SEQUENCE_BITS = 12n; +const SEQUENCE_MASK = (1n << SEQUENCE_BITS) - 1n; // 0..4095 +const WORKER_ID_MASK = (1n << WORKER_ID_BITS) - 1n; // 0..1023 +const WORKER_ID_SHIFT = SEQUENCE_BITS; +const TIMESTAMP_SHIFT = SEQUENCE_BITS + WORKER_ID_BITS; + +let _processId: string | undefined; +function getProcessId(): string { + if (!_processId) _processId = crypto.randomUUID(); + return _processId; +} + +function fnv1a10Bits(input: string): number { + let hash = 0x811c9dc5; + for (let i = 0; i < input.length; i++) { + hash ^= input.charCodeAt(i); + hash = Math.imul(hash, 0x01000193); + } + return hash & 0x3ff; +} + +export class SnowflakeGenerator { + private workerId?: number; + private lastTimestamp = -1; + private sequence = 0; + + constructor(workerId?: number) { + this.workerId = workerId; + } + + private getWorkerId(): number { + if (typeof this.workerId === "number") { + return this.workerId & 0x3ff; + } + return fnv1a10Bits(getProcessId()); + } + + generate(): string { + const wid = this.getWorkerId(); + let now = Date.now(); + if (now < this.lastTimestamp) { + now = this.lastTimestamp; + } + + if (now === this.lastTimestamp) { + this.sequence = (this.sequence + 1) & Number(SEQUENCE_MASK); + if (this.sequence === 0) { + while (now <= this.lastTimestamp) now = Date.now(); + } + } else { + this.sequence = 0; + } + + this.lastTimestamp = now; + + const ts = BigInt(now - EPOCH_MS); + const id = + (ts << TIMESTAMP_SHIFT) + | ((BigInt(wid) & WORKER_ID_MASK) << WORKER_ID_SHIFT) + | (BigInt(this.sequence) & SEQUENCE_MASK); + + return id.toString(); + } +} + +let defaultGenerator: SnowflakeGenerator | null = null; + +/** A fresh 64-bit snowflake as decimal text — a valid `ar_` workspace id. */ +export function generateSnowflakeId(): string { + if (!defaultGenerator) { + defaultGenerator = new SnowflakeGenerator(); + } + return defaultGenerator.generate(); +} diff --git a/packages/server/src/routes/relaycast.ts b/packages/server/src/routes/relaycast.ts new file mode 100644 index 00000000..34b219fe --- /dev/null +++ b/packages/server/src/routes/relaycast.ts @@ -0,0 +1,214 @@ +import { matchScope } from "@relayauth/sdk"; +import { Hono, type Context } from "hono"; + +import type { AppEnv } from "../env.js"; +import { authenticateAndAuthorizeFromContext } from "../lib/auth.js"; +import { + createCredentialTagSigner, + decodeArWorkspaceSegment, + isArWorkspaceId, + isArWorkspaceSegment, + mintArWorkspaceKey, +} from "../lib/credential-keyring.js"; +import { + createRelaycastKeyPusher, + RELAYCAST_ADMIN_SCOPE, + RelaycastConfigError, + RelaycastPushError, + resolveRelaycastConfig, + type RelaycastConfig, + type RelaycastWorkspaceKeyPusher, +} from "../lib/relaycast.js"; +import { generateSnowflakeId } from "../lib/snowflake.js"; + +/** + * Relaycast credential issuance ("model B"). RelayAuth holds the `ar_` + * credential tag keyring and mints `ar_ws_` workspace keys; each mint is pushed + * into relaycast's caller-minted internal contract before it is revealed here. + * The `ar_ws_` key is returned in exactly one response and is never stored. + * + * Wire fields are snake_case to mirror relaycast's internal API. + */ + +// Relaycast's WORKSPACE_KEY_MAX_GRACE_MS (engine tokenRotate.ts). +const RELAYCAST_MAX_GRACE_MS = 3_600_000; +const CREDENTIAL_TAGS_CACHE_CONTROL = "public, max-age=31536000, immutable"; + +const relaycast = new Hono(); + +relaycast.post("/workspaces", async (c) => { + const auth = await authorize(c); + if (auth instanceof Response) return auth; + const config = relaycastConfig(c); + if (config instanceof Response) return config; + + const body = await parseJsonObjectBody(c.req.raw); + if (!body.ok) { + return c.json({ error: "Invalid JSON body", code: "invalid_request" }, 400); + } + + const requestedRaw = body.value?.workspace_id; + const requested = normalizeOptionalString(requestedRaw); + if ((requestedRaw !== undefined && requested === undefined) || (requested !== undefined && !isArWorkspaceId(requested))) { + return c.json({ error: "workspace_id must be a 64-bit snowflake", code: "invalid_request" }, 400); + } + const workspaceId = requested ?? generateSnowflakeId(); + + return mintAndPush(c, config, workspaceId, { keyGeneration: 1 }); +}); + +relaycast.get("/credential-tags/:workspaceId", async (c) => { + const auth = await authorize(c); + if (auth instanceof Response) return auth; + const config = relaycastConfig(c); + if (config instanceof Response) return config; + + // Relaycast's remote tagger requests the 11-char base62 workspace segment + // (`encodeArWorkspaceId`), not the snowflake. + const segment = c.req.param("workspaceId"); + if (!isArWorkspaceSegment(segment)) { + return c.json({ error: "workspace id must be an 11-character base62 segment", code: "invalid_request" }, 400); + } + const workspaceId = decodeArWorkspaceSegment(segment); + + const tags = await createCredentialTagSigner(config.keyring).tags(workspaceId); + // Tags are pure routing data derived from the keyring: a cached list stays + // correct forever because keyring rotation only appends versions — a client + // that meets a tag it does not know refetches. + c.header("Cache-Control", CREDENTIAL_TAGS_CACHE_CONTROL); + return c.json({ ok: true, data: { workspace_id: workspaceId, tags: [...tags] } }, 200); +}); + +relaycast.post("/workspaces/:id/api-key", async (c) => { + const auth = await authorize(c); + if (auth instanceof Response) return auth; + const config = relaycastConfig(c); + if (config instanceof Response) return config; + + const workspaceId = c.req.param("id"); + if (!isArWorkspaceId(workspaceId)) { + return c.json({ error: "workspace id must be a 64-bit snowflake", code: "invalid_request" }, 400); + } + + const body = await parseJsonObjectBody(c.req.raw); + if (!body.ok) { + return c.json({ error: "Invalid JSON body", code: "invalid_request" }, 400); + } + + // Relaycast's generation CAS rejects anything that does not beat the stored + // generation, so the caller tracks generations and must state the next one. + const keyGeneration = body.value?.key_generation; + if (!Number.isSafeInteger(keyGeneration) || keyGeneration < 1) { + return c.json({ error: "key_generation must be a positive integer", code: "invalid_request" }, 400); + } + const graceMs = body.value?.grace_ms; + if ( + graceMs !== undefined + && (typeof graceMs !== "number" || !Number.isInteger(graceMs) || graceMs < 0 || graceMs > RELAYCAST_MAX_GRACE_MS) + ) { + return c.json( + { error: `grace_ms must be an integer between 0 and ${RELAYCAST_MAX_GRACE_MS}`, code: "invalid_request" }, + 400, + ); + } + + return mintAndPush(c, config, workspaceId, { + keyGeneration, + ...(graceMs === undefined ? {} : { graceMs }), + }); +}); + +export default relaycast; + +async function authorize(c: Context): Promise { + const auth = await authenticateAndAuthorizeFromContext(c, RELAYCAST_ADMIN_SCOPE, matchScope); + if (!auth.ok) { + return c.json({ error: auth.error, code: auth.code }, auth.status); + } +} + +function relaycastConfig(c: Context): RelaycastConfig | Response { + try { + const config = resolveRelaycastConfig(c.env); + if (config) return config; + } catch (error) { + if (error instanceof RelaycastConfigError) { + return c.json({ error: error.message, code: error.code }, 503); + } + throw error; + } + return c.json( + { error: "relaycast credential issuance is not configured", code: "relaycast_not_configured" }, + 503, + ); +} + +function keyPusher(c: Context, config: RelaycastConfig): RelaycastWorkspaceKeyPusher { + return c.get("relaycastKeyPusher") ?? createRelaycastKeyPusher(config); +} + +async function mintAndPush( + c: Context, + config: RelaycastConfig, + workspaceId: string, + input: { keyGeneration: number; graceMs?: number }, +): Promise { + const signer = createCredentialTagSigner(config.keyring); + const apiKey = await mintArWorkspaceKey(signer, workspaceId); + + let pushed: { workspaceId: string; apiKeyGeneration: number; created: boolean }; + try { + pushed = await keyPusher(c, config).pushWorkspaceKey(workspaceId, { + apiKey, + keyGeneration: input.keyGeneration, + ...(input.graceMs === undefined ? {} : { graceMs: input.graceMs }), + }); + } catch (error) { + if (error instanceof RelaycastPushError) { + return c.json( + { error: error.message, code: error.code }, + error.status as 400 | 401 | 403 | 404 | 409 | 502, + ); + } + throw error; + } + + // The minted key is revealed here and nowhere else; it is never persisted. + return c.json( + { + workspace_id: pushed.workspaceId, + api_key: apiKey, + api_key_generation: pushed.apiKeyGeneration, + }, + pushed.created ? 201 : 200, + ); +} + +type JsonObjectBody = + | { ok: true; value: Record } + | { ok: false }; + +async function parseJsonObjectBody(request: Request): Promise { + const text = await request.text(); + if (text.trim() === "") { + return { ok: true, value: {} }; + } + let body: unknown; + try { + body = JSON.parse(text); + } catch { + return { ok: false }; + } + if (!body || typeof body !== "object" || Array.isArray(body)) { + return { ok: false }; + } + return { ok: true, value: body as Record }; +} + +function normalizeOptionalString(value: unknown): string | undefined { + if (typeof value !== "string") { + return undefined; + } + const normalized = value.trim(); + return normalized.length > 0 ? normalized : undefined; +} diff --git a/packages/server/src/server.ts b/packages/server/src/server.ts index 46fd954c..a88d73ca 100644 --- a/packages/server/src/server.ts +++ b/packages/server/src/server.ts @@ -25,6 +25,12 @@ import { ensureBootstrapApiKey, SESSION_DIRECTORY_BOOTSTRAP_API_KEY_NAME, } from "./lib/bootstrap-api-key.js"; +import { + assertRelaycastConfig, + RELAYCAST_ADMIN_SCOPE, + RELAYCAST_SERVICE_API_KEY_NAME, + type RelaycastWorkspaceKeyPusher, +} from "./lib/relaycast.js"; import { assertSessionDirectoryIssuerConfig, SESSION_DIRECTORY_SEARCH_MINT_SCOPE, @@ -44,6 +50,7 @@ import identityActivity from "./routes/identity-activity.js"; import identities from "./routes/identities.js"; import observerApp from "./routes/observer.js"; import policies from "./routes/policies.js"; +import relaycast from "./routes/relaycast.js"; import roleAssignments from "./routes/role-assignments.js"; import roles from "./routes/roles.js"; import tokens from "./routes/tokens.js"; @@ -240,6 +247,7 @@ export type CreateAppOptions = { identityCreateRateLimiter?: RequestRateLimiter; revocationCheckRateLimiter?: RequestRateLimiter; sponsorOidcService?: SponsorOidcService; + relaycastKeyPusher?: RelaycastWorkspaceKeyPusher; }; export type StartServerOptions = { @@ -339,6 +347,9 @@ export function createApp(options: CreateAppOptions = {}): Hono { c.set("identityCreatePreAuthRateLimiter", identityCreatePreAuthRateLimiter); c.set("identityCreateRateLimiter", identityCreateRateLimiter); c.set("sponsorOidcService", sponsorOidcService); + if (options.relaycastKeyPusher) { + c.set("relaycastKeyPusher", options.relaycastKeyPusher); + } await next(); }); @@ -383,6 +394,8 @@ export function createApp(options: CreateAppOptions = {}): Hono { app.use("/v1/tokens/*", apiKeyAuth()); app.use("/v1/api-keys", apiKeyAuth()); app.use("/v1/api-keys/*", apiKeyAuth()); + app.use("/v1/relaycast", apiKeyAuth()); + app.use("/v1/relaycast/*", apiKeyAuth()); // Finalization deliberately authenticates only with its one-time bearer // capability. API-key middleware belongs on grant creation alone so a // capability is never interpreted as an API key. @@ -463,6 +476,7 @@ export function createApp(options: CreateAppOptions = {}): Hono { app.route("/v1/identities", roleAssignments); app.route("/v1/observer", observerApp); app.route("/v1/policies", policies); + app.route("/v1/relaycast", relaycast); app.route("/v1/roles", roles); app.route("/v1/stats", dashboardStats); app.route("/v1/sponsors", sponsors); @@ -568,6 +582,14 @@ export async function startServer(options: StartServerOptions = {}) { RELAYAUTH_REVOCATION_CHECK_RATE_WINDOW_MS: options.config?.RELAYAUTH_REVOCATION_CHECK_RATE_WINDOW_MS ?? process.env.RELAYAUTH_REVOCATION_CHECK_RATE_WINDOW_MS, + RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING: + options.config?.RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING + ?? readEnvOrFile("RELAYAUTH_RELAYCAST_CREDENTIAL_KEYRING"), + RELAYAUTH_RELAYCAST_URL: + options.config?.RELAYAUTH_RELAYCAST_URL ?? process.env.RELAYAUTH_RELAYCAST_URL, + RELAYAUTH_RELAYCAST_INTERNAL_SECRET: + options.config?.RELAYAUTH_RELAYCAST_INTERNAL_SECRET + ?? readEnvOrFile("RELAYAUTH_RELAYCAST_INTERNAL_SECRET"), }; // Refuse to start on a bad signing-key configuration (unsupported PEM type, @@ -575,6 +597,7 @@ export async function startServer(options: StartServerOptions = {}) { // than signing with one key while advertising another. await assertSigningKeyConfig(config); await assertSessionDirectoryIssuerConfig(config); + assertRelaycastConfig(config); const requestedBootstrapOrg = (options.bootstrapApiKeyOrgId ?? process.env.RELAYAUTH_BOOTSTRAP_API_KEY_ORG)?.trim() || DEFAULT_BOOTSTRAP_API_KEY_ORG; @@ -592,6 +615,14 @@ export async function startServer(options: StartServerOptions = {}) { name: SESSION_DIRECTORY_BOOTSTRAP_API_KEY_NAME, exactScope: true, }, + { + label: "relaycast service api key", + setting: "RELAYAUTH_RELAYCAST_SERVICE_API_KEY", + value: readEnvOrFile("RELAYAUTH_RELAYCAST_SERVICE_API_KEY"), + scope: RELAYCAST_ADMIN_SCOPE, + name: RELAYCAST_SERVICE_API_KEY_NAME, + exactScope: true, + }, ]; for (const { label, setting, value, scope, name, exactScope } of bootstrapKeys) { if (!value) continue;