@stigmer/server 3.24.0 → 3.25.0

package/src/platformtoken/__tests__/key-ring.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Pins the platform-token key ring:
+ *   - a composition's ring from PEM refuses at build time what would fail
+ *     quietly later: no public key, a non-RSA or undersized key, a private
+ *     key whose public half no verification key matches, a bad TTL; a ring
+ *     without a private key verifies and never signs;
+ *   - open source's ring rides the key-manager ladder under its rules: the
+ *     env key wins, an unusable env key is a throw, a generated key is
+ *     persisted 0600 and reused, a file the codec refuses is replaced;
+ *   - the four arms of resolvePlatformTokenKeys: no posture, a supplied
+ *     ring, open source's own, and the refusal for any other edition.
+ */
+import { generateKeyPairSync } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import {
+  PLATFORM_TOKEN_KEY_ENV_VAR,
+  PLATFORM_TOKEN_KEY_FILE_NAME,
+  canSign,
+  openSourcePlatformTokenKeyRing,
+  platformTokenKeyRingFromPem,
+  resolvePlatformTokenKeys,
+} from "../key-ring.js";
+import { signPlatformToken, verifyPlatformToken } from "../envelope.js";
+
+function rsaPem(bits = 2048): { privateKeyPem: string; publicKeyPem: string } {
+  const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+    modulusLength: bits,
+  });
+  return {
+    privateKeyPem: privateKey
+      .export({ format: "pem", type: "pkcs8" })
+      .toString(),
+    publicKeyPem: publicKey.export({ format: "pem", type: "spki" }).toString(),
+  };
+}
+
+const pair = rsaPem();
+const homes: string[] = [];
+
+function tempHome(): string {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "platform-token-"));
+  homes.push(home);
+  return home;
+}
+
+afterEach(() => {
+  for (const home of homes.splice(0)) {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+describe("platformTokenKeyRingFromPem", () => {
+  it("builds a signing ring whose tokens verify, and a verify-only ring without a private key", () => {
+    const ring = platformTokenKeyRingFromPem({
+      privateKeyPem: pair.privateKeyPem,
+      publicKeyPems: [pair.publicKeyPem],
+    });
+    expect(canSign(ring)).toBe(true);
+    if (!canSign(ring)) return;
+    const token = signPlatformToken(ring, { sub: "ida_1" }).token;
+
+    const verifyOnly = platformTokenKeyRingFromPem({
+      publicKeyPems: [pair.publicKeyPem],
+    });
+    expect(canSign(verifyOnly)).toBe(false);
+    expect(verifyPlatformToken(verifyOnly, token).outcome).toBe("verified");
+  });
+
+  it("refuses an empty verification set, a non-RSA key, an undersized key and a bad TTL", () => {
+    expect(() => platformTokenKeyRingFromPem({ publicKeyPems: [] })).toThrow(
+      /at least one public key/,
+    );
+
+    const ec = generateKeyPairSync("ec", { namedCurve: "P-256" })
+      .publicKey.export({ format: "pem", type: "spki" })
+      .toString();
+    expect(() => platformTokenKeyRingFromPem({ publicKeyPems: [ec] })).toThrow(
+      /must be an RSA key/,
+    );
+
+    const small = rsaPem(1024);
+    expect(() =>
+      platformTokenKeyRingFromPem({ publicKeyPems: [small.publicKeyPem] }),
+    ).toThrow(/at least 2048 bits/);
+
+    expect(() =>
+      platformTokenKeyRingFromPem({
+        publicKeyPems: [pair.publicKeyPem],
+        ttlSeconds: 0,
+      }),
+    ).toThrow(/positive integer/);
+  });
+
+  it("refuses a private key whose public half is not among the verification keys", () => {
+    expect(() =>
+      platformTokenKeyRingFromPem({
+        privateKeyPem: pair.privateKeyPem,
+        publicKeyPems: [rsaPem().publicKeyPem],
+      }),
+    ).toThrow(/would verify nowhere/);
+  });
+});
+
+describe("openSourcePlatformTokenKeyRing (the key-manager ladder)", () => {
+  it("uses the env key when set, and refuses an env value that is not an RSA private key", () => {
+    const env = {
+      [PLATFORM_TOKEN_KEY_ENV_VAR]: Buffer.from(pair.privateKeyPem).toString(
+        "base64",
+      ),
+    };
+    const ring = openSourcePlatformTokenKeyRing({ env, homeDir: tempHome() });
+    const token = signPlatformToken(ring, { sub: "ida_1" }).token;
+    const expected = platformTokenKeyRingFromPem({
+      publicKeyPems: [pair.publicKeyPem],
+    });
+    expect(verifyPlatformToken(expected, token).outcome).toBe("verified");
+
+    expect(() =>
+      openSourcePlatformTokenKeyRing({
+        env: {
+          [PLATFORM_TOKEN_KEY_ENV_VAR]:
+            Buffer.from("not a key").toString("base64"),
+        },
+        homeDir: tempHome(),
+      }),
+    ).toThrow(PLATFORM_TOKEN_KEY_ENV_VAR);
+  });
+
+  it("generates a key once, persists it 0600, and signs with the same key on the next boot", () => {
+    const home = tempHome();
+    const first = openSourcePlatformTokenKeyRing({ env: {}, homeDir: home });
+    const file = path.join(home, ".stigmer", PLATFORM_TOKEN_KEY_FILE_NAME);
+    expect(fs.existsSync(file)).toBe(true);
+    if (process.platform !== "win32") {
+      expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+    }
+    const second = openSourcePlatformTokenKeyRing({ env: {}, homeDir: home });
+    expect(second.signer.kid).toBe(first.signer.kid);
+    const token = signPlatformToken(first, { sub: "ida_1" }).token;
+    expect(verifyPlatformToken(second, token).outcome).toBe("verified");
+  });
+
+  it("replaces a key file the codec does not accept, as the ladder does for every key", () => {
+    const home = tempHome();
+    const file = path.join(home, ".stigmer", PLATFORM_TOKEN_KEY_FILE_NAME);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, "garbage", { mode: 0o600 });
+    const ring = openSourcePlatformTokenKeyRing({ env: {}, homeDir: home });
+    expect(ring.signer.key.asymmetricKeyType).toBe("rsa");
+    expect(fs.readFileSync(file, "utf8")).toContain("BEGIN PRIVATE KEY");
+  });
+});
+
+describe("resolvePlatformTokenKeys", () => {
+  const supplied = platformTokenKeyRingFromPem({
+    publicKeyPems: [pair.publicKeyPem],
+  });
+
+  it("composes no ring without an authentication posture, whatever is supplied", () => {
+    expect(
+      resolvePlatformTokenKeys({
+        requireAuthentication: false,
+        supplied,
+        edition: ServerEdition.cloud,
+      }),
+    ).toBeUndefined();
+  });
+
+  it("uses a supplied ring under the posture", () => {
+    expect(
+      resolvePlatformTokenKeys({
+        requireAuthentication: true,
+        supplied,
+        edition: ServerEdition.cloud,
+      }),
+    ).toBe(supplied);
+  });
+
+  it("composes open source's own ring when open source supplies none", () => {
+    const ring = resolvePlatformTokenKeys({
+      requireAuthentication: true,
+      supplied: undefined,
+      edition: ServerEdition.oss,
+      options: { env: {}, homeDir: tempHome() },
+    });
+    expect(ring !== undefined && canSign(ring)).toBe(true);
+  });
+
+  it("refuses to boot any other edition that supplies no ring", () => {
+    expect(() =>
+      resolvePlatformTokenKeys({
+        requireAuthentication: true,
+        supplied: undefined,
+        edition: ServerEdition.cloud,
+      }),
+    ).toThrow(/registers no platform-token key ring/);
+  });
+});

package/src/platformtoken/envelope.ts

@@ -0,0 +1,276 @@
+/**
+ * The platform-token envelope: the RS256 JWT every token the server signs
+ * for itself rides — the PlatformClient user token in open source, and in
+ * the cloud its typed lanes (guest, schedule, channel, the sandbox family)
+ * as well. One envelope, byte-compatible with the tokens Stigmer Cloud has
+ * signed since the Java issuer, so a token minted before the cloud serves
+ * this code verifies after it.
+ *
+ * The envelope knows the issuer, the four claims it owns (`iss`, `iat`,
+ * `exp`, `jti`, plus `aud` when the ring carries an audience) and the
+ * signature. It does not know lanes: a lane's vocabulary (its claims, its
+ * `token_type`, the caller class it stamps) belongs to the verifier that
+ * claims it — open source verifies only the untyped PlatformClient lane
+ * (domain/platformclient/verifier.ts); the typed lanes stay the cloud's.
+ *
+ * A token's lifetime is the lane's to choose: the ring carries the default
+ * (the user token's), and a lane that lives longer or shorter — the cloud's
+ * sandbox tokens outlive a user token sixteen-fold — says so per token.
+ * Either way the envelope alone computes `exp` and hands the expiry back,
+ * so no lane re-derives it beside the claim it signed.
+ *
+ * Verification is the cloud verifier's, exactly (its verifiers/jwt.ts and
+ * platform-token.ts), because the tokens in the field were accepted by it:
+ *   - A token that is not a three-part JWT with `iss: "stigmer"` is
+ *     `foreign` — some other verifier's to judge, never refused here.
+ *   - The signature is RS256 over every key in the ring; the header's
+ *     `alg` and `kid` are never read to choose (so neither `alg: none` nor
+ *     an HMAC-with-the-public-key forgery can pass, and a constant kid
+ *     across a rotation still verifies).
+ *   - Then `exp` (required, a number, strictly in the future; no leeway),
+ *     then `aud` (tolerated when absent, refused when it names another
+ *     audience), then `sub` (a non-empty string) — in that order, each with
+ *     its pinned copy.
+ * The refusals are returned, not thrown: the envelope has no transport,
+ * and a verifier turns a refusal into the wire error with
+ * `platformTokenRefusalError`.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import { randomUUID, sign, verify } from "node:crypto";
+
+import type {
+  PlatformTokenKeyRing,
+  SigningPlatformTokenKeyRing,
+} from "./key-ring.js";
+
+/** The `iss` of every platform token (the cloud's STIGMER_ISSUER). */
+export const PLATFORM_TOKEN_ISSUER = "stigmer";
+
+/** The claim a typed lane names itself by; absent on the PlatformClient user token. */
+export const TOKEN_TYPE_CLAIM = "token_type";
+
+/** A lane claim's value: the token carries JSON scalars only. */
+export type PlatformTokenClaimValue = string | number | boolean;
+
+/** The claims the envelope owns; a lane may not set them. */
+const ENVELOPE_CLAIMS = new Set(["iss", "iat", "exp", "jti", "aud"]);
+
+export type PlatformTokenRefusal =
+  | "signature"
+  | "expired"
+  | "audience"
+  | "subject";
+
+/** Wire copy, byte-pinned: the cloud verifier's sentences since the Java issuer. */
+export const PLATFORM_TOKEN_REFUSAL_MESSAGES: Readonly<
+  Record<PlatformTokenRefusal, string>
+> = {
+  signature: "platform token signature verification failed",
+  expired: "platform token is expired",
+  audience: "platform token was minted for another environment",
+  subject: "platform token carries no subject",
+};
+
+/** A verified token: its subject, its lane discriminator, its payload. */
+export interface VerifiedPlatformToken {
+  readonly subject: string;
+  /** The `token_type` claim when it is a non-empty string; undefined for the untyped lane. */
+  readonly tokenType: string | undefined;
+  readonly payload: Readonly<Record<string, unknown>>;
+}
+
+export type PlatformTokenVerification =
+  | { readonly outcome: "foreign" }
+  | { readonly outcome: "refused"; readonly refusal: PlatformTokenRefusal }
+  | { readonly outcome: "verified"; readonly token: VerifiedPlatformToken };
+
+/** How one token is signed; every field defaults to the ring's answer. */
+export interface PlatformTokenSigningOptions {
+  /** The signing instant (`iat`); defaults to the wall clock. */
+  readonly now?: Date;
+  /** This token's lifetime in whole seconds; defaults to the ring's `ttlSeconds`. */
+  readonly ttlSeconds?: number;
+}
+
+/** A signed token and the instant its `exp` claim names. */
+export interface SignedPlatformToken {
+  readonly token: string;
+  readonly expiresAt: Date;
+}
+
+/**
+ * Signs `claims` inside the envelope: header `{alg, typ, kid}`, then `iss`,
+ * `iat`, `exp` (iat + the lifetime), `jti` and `aud` when the ring has one,
+ * then the lane's claims. Throws when a lane claim collides with an
+ * envelope claim, or when a lifetime is not a positive whole number of
+ * seconds — programming errors, never a request's.
+ */
+export function signPlatformToken(
+  ring: SigningPlatformTokenKeyRing,
+  claims: Readonly<Record<string, PlatformTokenClaimValue>>,
+  options: PlatformTokenSigningOptions = {},
+): SignedPlatformToken {
+  for (const name of Object.keys(claims)) {
+    if (ENVELOPE_CLAIMS.has(name)) {
+      throw new Error(
+        `platform-token claim '${name}' belongs to the envelope and cannot be set by a lane`,
+      );
+    }
+  }
+  const ttlSeconds = options.ttlSeconds ?? ring.ttlSeconds;
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0) {
+    throw new Error(
+      `platform-token lifetime must be a positive integer number of seconds, got ${ttlSeconds}`,
+    );
+  }
+  const issuedAt = Math.floor((options.now ?? new Date()).getTime() / 1000);
+  const expiresAtSeconds = issuedAt + ttlSeconds;
+  const header = { alg: "RS256", typ: "JWT", kid: ring.signer.kid };
+  const payload = {
+    iss: PLATFORM_TOKEN_ISSUER,
+    iat: issuedAt,
+    exp: expiresAtSeconds,
+    jti: randomUUID(),
+    ...(ring.audience !== "" ? { aud: ring.audience } : {}),
+    ...claims,
+  };
+  const signingInput = `${base64UrlJson(header)}.${base64UrlJson(payload)}`;
+  const signature = sign("sha256", Buffer.from(signingInput), ring.signer.key);
+  return {
+    token: `${signingInput}.${signature.toString("base64url")}`,
+    expiresAt: new Date(expiresAtSeconds * 1000),
+  };
+}
+
+/** Verifies a bearer token against the ring (see the header for the order). */
+export function verifyPlatformToken(
+  ring: PlatformTokenKeyRing,
+  token: string,
+  now: Date = new Date(),
+): PlatformTokenVerification {
+  const decoded = decode(token);
+  if (decoded === undefined || decoded.payload.iss !== PLATFORM_TOKEN_ISSUER) {
+    return { outcome: "foreign" };
+  }
+  const signingInput = Buffer.from(
+    `${decoded.encodedHeader}.${decoded.encodedPayload}`,
+  );
+  const signatureValid = ring.verificationKeys.some((key) =>
+    verify("sha256", signingInput, key, decoded.signature),
+  );
+  if (!signatureValid) {
+    return { outcome: "refused", refusal: "signature" };
+  }
+  const exp = decoded.payload.exp;
+  if (typeof exp !== "number" || exp * 1000 <= now.getTime()) {
+    return { outcome: "refused", refusal: "expired" };
+  }
+  const aud = decoded.payload.aud;
+  if (
+    ring.audience !== "" &&
+    aud !== undefined &&
+    !audienceMatches(aud, ring.audience)
+  ) {
+    return { outcome: "refused", refusal: "audience" };
+  }
+  const sub = decoded.payload.sub;
+  if (typeof sub !== "string" || sub === "") {
+    return { outcome: "refused", refusal: "subject" };
+  }
+  return {
+    outcome: "verified",
+    token: {
+      subject: sub,
+      tokenType: stringClaim(decoded.payload, TOKEN_TYPE_CLAIM),
+      payload: decoded.payload,
+    },
+  };
+}
+
+/** The UNAUTHENTICATED error a verifier answers for a refused platform token. */
+export function platformTokenRefusalError(
+  refusal: PlatformTokenRefusal,
+): ConnectError {
+  return new ConnectError(
+    PLATFORM_TOKEN_REFUSAL_MESSAGES[refusal],
+    Code.Unauthenticated,
+  );
+}
+
+/**
+ * The payload of a platform token WITHOUT verifying it — for a caller
+ * guard reading the claims of a token the verifier chain already verified
+ * on this request (caller-guards.ts: guards decode `rawToken`). Undefined
+ * for anything that is not a platform token, an API key or an empty
+ * trusted-local token included. Never a substitute for
+ * `verifyPlatformToken`.
+ */
+export function decodeVerifiedPlatformTokenPayload(
+  token: string,
+): Readonly<Record<string, unknown>> | undefined {
+  const decoded = decode(token);
+  return decoded !== undefined && decoded.payload.iss === PLATFORM_TOKEN_ISSUER
+    ? decoded.payload
+    : undefined;
+}
+
+/** A payload claim when it is a non-empty string; undefined otherwise. */
+export function stringClaim(
+  payload: Readonly<Record<string, unknown>>,
+  name: string,
+): string | undefined {
+  const value = payload[name];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+interface DecodedToken {
+  readonly encodedHeader: string;
+  readonly encodedPayload: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  readonly signature: Buffer;
+}
+
+/** A three-part JWT whose header and payload are JSON objects; anything else is undefined. */
+function decode(token: string): DecodedToken | undefined {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return undefined;
+  }
+  const [encodedHeader = "", encodedPayload = "", encodedSignature = ""] =
+    parts;
+  const header = parseJsonObject(encodedHeader);
+  const payload = parseJsonObject(encodedPayload);
+  if (header === undefined || payload === undefined) {
+    return undefined;
+  }
+  return {
+    encodedHeader,
+    encodedPayload,
+    payload,
+    signature: Buffer.from(encodedSignature, "base64url"),
+  };
+}
+
+function parseJsonObject(segment: string): Record<string, unknown> | undefined {
+  try {
+    const value: unknown = JSON.parse(
+      Buffer.from(segment, "base64url").toString("utf8"),
+    );
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function audienceMatches(aud: unknown, expected: string): boolean {
+  if (typeof aud === "string") {
+    return aud === expected;
+  }
+  return Array.isArray(aud) && aud.includes(expected);
+}
+
+function base64UrlJson(value: object): string {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}