@stigmer/server 3.23.1-dev.20260923075205 → 3.25.0

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");
+}

package/src/platformtoken/key-ring.ts

@@ -0,0 +1,266 @@
+/**
+ * The platform-token key ring: the RS256 key material every token the
+ * server signs for itself rides (the envelope in envelope.ts). One ring
+ * per server, supplied once:
+ *
+ *   - Open source composes `openSourcePlatformTokenKeyRing()`: one RSA key
+ *     on the key-manager ladder (STIGMER_PLATFORM_TOKEN_KEY, else
+ *     ~/.stigmer/platform-token.key, else generated and persisted — the
+ *     runner-token key's convention, under the ladder's own rules). It
+ *     signs and verifies with the same key; no audience; a kid derived
+ *     from the key, so two installations never claim the same kid.
+ *   - A composition supplies its own ring through the `platformTokenKeys`
+ *     driver point, built from its configured PEMs with
+ *     `platformTokenKeyRingFromPem`: the active public key first, then any
+ *     still accepted (the rotation window), an optional private key (a
+ *     ring without one verifies and never signs), its kid and audience.
+ *
+ * Only RSA keys of at least MIN_RSA_MODULUS_BITS are accepted: the
+ * envelope signs PKCS#1 v1.5 over SHA-256 (RS256) and asks the key for
+ * nothing else, so an EC key would silently change the algorithm.
+ */
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+} from "node:crypto";
+import type { KeyObject } from "node:crypto";
+
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+
+import { getOrCreateKey } from "../encryption/key-manager.js";
+import type { KeyCodec, KeyLoaderOptions } from "../encryption/key-manager.js";
+
+/** Env var carrying open source's signing key: Base64 of a PKCS#8 PEM. */
+export const PLATFORM_TOKEN_KEY_ENV_VAR = "STIGMER_PLATFORM_TOKEN_KEY";
+
+/** Key file under ~/.stigmer for the generated signing key (PKCS#8 PEM). */
+export const PLATFORM_TOKEN_KEY_FILE_NAME = "platform-token.key";
+
+/**
+ * The default lifetime of a signed token: the cloud's user-token lifetime
+ * since the Java issuer (STIGMER_JWT_USER_TOKEN_TTL_SECONDS' default). It
+ * bounds how long a user token outlives a rotated secret or a lost key; a
+ * deleted client's tokens stop at the next request regardless (the
+ * verifier's liveness).
+ */
+export const DEFAULT_PLATFORM_TOKEN_TTL_SECONDS = 900;
+
+/** The smallest RSA modulus the ring accepts (NIST SP 800-131A's floor). */
+export const MIN_RSA_MODULUS_BITS = 2048;
+
+/** The key that signs, and the kid its tokens' header names. */
+export interface PlatformTokenSigner {
+  readonly key: KeyObject;
+  readonly kid: string;
+}
+
+export interface PlatformTokenKeyRing {
+  /** Absent: the ring verifies and never signs (minting is disabled). */
+  readonly signer?: PlatformTokenSigner;
+  /** Every public key a token may verify against, the active one first. */
+  readonly verificationKeys: ReadonlyArray<KeyObject>;
+  /** Stamped as `aud` and checked when present; "" means none. */
+  readonly audience: string;
+  /**
+   * The lifetime of a token signed without one of its own: the user
+   * token's. A lane that lives longer or shorter passes its own to
+   * `signPlatformToken`.
+   */
+  readonly ttlSeconds: number;
+}
+
+/** A ring that can sign — what `signPlatformToken` takes. */
+export type SigningPlatformTokenKeyRing = PlatformTokenKeyRing & {
+  readonly signer: PlatformTokenSigner;
+};
+
+export function canSign(
+  ring: PlatformTokenKeyRing,
+): ring is SigningPlatformTokenKeyRing {
+  return ring.signer !== undefined;
+}
+
+/** A composition's configured key material, as PEM text. */
+export interface PlatformTokenKeyMaterial {
+  /** PKCS#8 or PKCS#1 private key; absent disables signing. */
+  readonly privateKeyPem?: string;
+  /** The header kid; defaults to one derived from the private key. */
+  readonly kid?: string;
+  /** SPKI public keys, the active one first; at least one. */
+  readonly publicKeyPems: ReadonlyArray<string>;
+  readonly audience?: string;
+  readonly ttlSeconds?: number;
+}
+
+/**
+ * Builds a ring from PEM text, refusing loudly at boot what would fail
+ * quietly at the first request: a non-RSA or undersized key, an empty
+ * verification set, a non-positive TTL, and a private key whose public
+ * half is not among the verification keys (it would sign tokens nothing
+ * accepts).
+ */
+export function platformTokenKeyRingFromPem(
+  material: PlatformTokenKeyMaterial,
+): PlatformTokenKeyRing {
+  if (material.publicKeyPems.length === 0) {
+    throw new Error(
+      "a platform-token key ring needs at least one public key to verify against",
+    );
+  }
+  const verificationKeys = material.publicKeyPems.map((pem, index) =>
+    requireRsa(
+      parseKey(() => createPublicKey(pem), `public key ${index + 1}`),
+      `public key ${index + 1}`,
+    ),
+  );
+  const ttlSeconds = material.ttlSeconds ?? DEFAULT_PLATFORM_TOKEN_TTL_SECONDS;
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0) {
+    throw new Error(
+      `platform-token TTL must be a positive integer number of seconds, got ${ttlSeconds}`,
+    );
+  }
+  const base = {
+    verificationKeys,
+    audience: material.audience ?? "",
+    ttlSeconds,
+  };
+  if (material.privateKeyPem === undefined) {
+    return base;
+  }
+  const privateKey = requireRsa(
+    parseKey(
+      () => createPrivateKey(material.privateKeyPem ?? ""),
+      "private key",
+    ),
+    "private key",
+  );
+  const derivedPublic = spkiOf(createPublicKey(privateKey));
+  if (!verificationKeys.some((key) => spkiOf(key).equals(derivedPublic))) {
+    throw new Error(
+      "the platform-token private key's public half is not among the verification keys — tokens it signed would verify nowhere",
+    );
+  }
+  return {
+    ...base,
+    signer: { key: privateKey, kid: material.kid ?? kidOf(privateKey) },
+  };
+}
+
+/**
+ * The ring a composition runs with, decided once at the keys stage:
+ *   - no authentication posture: none — a server that trusts every
+ *     request verifies nothing, so it signs nothing (the mint refuses);
+ *   - a supplied ring: that ring;
+ *   - none supplied, open source: open source's own ring on the ladder;
+ *   - none supplied, any other edition: a boot throw, so a hosted edition
+ *     can never sign with a key generated into a pod's home directory,
+ *     which no other replica shares and no restart keeps.
+ */
+export function resolvePlatformTokenKeys(input: {
+  readonly requireAuthentication: boolean;
+  readonly supplied: PlatformTokenKeyRing | undefined;
+  readonly edition: ServerEdition;
+  readonly options?: KeyLoaderOptions;
+}): PlatformTokenKeyRing | undefined {
+  if (!input.requireAuthentication) {
+    return undefined;
+  }
+  if (input.supplied !== undefined) {
+    return input.supplied;
+  }
+  if (input.edition !== ServerEdition.oss) {
+    throw new Error(
+      `the ${ServerEdition[input.edition]} edition requires authentication but registers no platform-token key ring — register drivers.platformTokenKeys; only open source generates its own key`,
+    );
+  }
+  return openSourcePlatformTokenKeyRing(input.options);
+}
+
+/**
+ * Open source's ring: one RSA key on the key-manager ladder, signing and
+ * verifying, no audience, the default TTL. Throws when an explicitly
+ * configured STIGMER_PLATFORM_TOKEN_KEY is unusable (the ladder's rule).
+ */
+export function openSourcePlatformTokenKeyRing(
+  options: KeyLoaderOptions = {},
+): SigningPlatformTokenKeyRing {
+  const privateKey = getOrCreateKey(
+    RSA_PRIVATE_KEY,
+    PLATFORM_TOKEN_KEY_ENV_VAR,
+    PLATFORM_TOKEN_KEY_FILE_NAME,
+    options,
+  );
+  return {
+    signer: { key: privateKey, kid: kidOf(privateKey) },
+    verificationKeys: [createPublicKey(privateKey)],
+    audience: "",
+    ttlSeconds: DEFAULT_PLATFORM_TOKEN_TTL_SECONDS,
+  };
+}
+
+/** The ladder codec for an RSA private key stored as PKCS#8 PEM. */
+export const RSA_PRIVATE_KEY: KeyCodec<KeyObject> = {
+  fromEnv(envVar, decoded) {
+    const key = parseKey(
+      () => createPrivateKey(decoded.toString("utf8")),
+      envVar,
+    );
+    return requireRsa(key, envVar);
+  },
+  fromFile(content) {
+    try {
+      const key = createPrivateKey(content.toString("utf8"));
+      return isUsableRsa(key) ? key : undefined;
+    } catch {
+      return undefined;
+    }
+  },
+  generate() {
+    return generateKeyPairSync("rsa", { modulusLength: MIN_RSA_MODULUS_BITS })
+      .privateKey;
+  },
+  toFile(key) {
+    return Buffer.from(key.export({ format: "pem", type: "pkcs8" }));
+  },
+};
+
+/** A key's kid: the first 16 characters of its public half's SHA-256. */
+function kidOf(key: KeyObject): string {
+  const publicKey = key.type === "private" ? createPublicKey(key) : key;
+  return createHash("sha256")
+    .update(spkiOf(publicKey))
+    .digest("base64url")
+    .slice(0, 16);
+}
+
+function spkiOf(publicKey: KeyObject): Buffer {
+  return publicKey.export({ format: "der", type: "spki" });
+}
+
+function parseKey(parse: () => KeyObject, what: string): KeyObject {
+  try {
+    return parse();
+  } catch (error) {
+    throw new Error(
+      `${what} is not a readable PEM key: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function requireRsa(key: KeyObject, what: string): KeyObject {
+  if (!isUsableRsa(key)) {
+    throw new Error(
+      `${what} must be an RSA key of at least ${MIN_RSA_MODULUS_BITS} bits`,
+    );
+  }
+  return key;
+}
+
+function isUsableRsa(key: KeyObject): boolean {
+  return (
+    key.asymmetricKeyType === "rsa" &&
+    (key.asymmetricKeyDetails?.modulusLength ?? 0) >= MIN_RSA_MODULUS_BITS
+  );
+}

package/src/runnerauth/__tests__/runner-subject-composed.test.ts

@@ -245,9 +245,13 @@ describe("the built-in posture (OIDC, no unit Authorizer): the runner acts as th
     );
   }
 
-  it("the chain is apikey → runner → oidc: ours claims the server's own token before the OIDC verifier can fault on it", () => {
+  it("the chain is apikey → platform-client → runner → oidc: ours claims the server's own token before the OIDC verifier can fault on it", () => {
+    // The platform-client verifier claims only `iss: "stigmer"` user tokens
+    // and a runner token carries no `iss`, so the two lanes are disjoint and
+    // both sit ahead of the OIDC verifier for the same reason.
     expect(server.identityVerifiers.map((verifier) => verifier.name)).toEqual([
       "apikey",
+      "platform-client",
       RUNNER_VERIFIER_NAME,
       "oidc",
     ]);
@@ -489,9 +493,11 @@ describe("a unit's own Authorizer: no runner verifier is composed", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 
-  it("the chain is apikey then the unit's verifiers — the composition owns its credential story", () => {
+  it("the chain is apikey, platform-client, then the unit's verifiers — the composition owns its credential story", () => {
     const names = server.identityVerifiers.map((verifier) => verifier.name);
-    expect(names).toEqual(["apikey", fakeVerifier.name]);
+    // The PlatformClient lane is core in every posture that verifies
+    // callers; the runner-subject lane is the built-in Authorizer's alone.
+    expect(names).toEqual(["apikey", "platform-client", fakeVerifier.name]);
     expect(names).not.toContain(RUNNER_VERIFIER_NAME);
   });
 });