@stigmer/server 3.24.0 → 3.26.0

package/src/platformtoken/__tests__/envelope.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Pins the platform-token envelope against the cloud verifier's semantics,
+ * which every token in the field was accepted under:
+ *   - a signed token round-trips with the envelope's claims and the lane's;
+ *   - a lane's own lifetime replaces the ring's default, and the expiry the
+ *     signer returns is the instant the `exp` claim names;
+ *   - a token signed by the previous key still verifies (the rotation
+ *     window), and the header's kid never selects a key;
+ *   - the forgeries a JWT verifier must refuse are refused as a bad
+ *     signature: `alg: none`, and an HMAC token keyed with the public key;
+ *   - expiry is strict (no leeway), a missing `aud` is tolerated, a wrong
+ *     one refused, and a missing `sub` refused — each with its pinned copy;
+ *   - anything that is not a three-part `iss: "stigmer"` JWT is foreign,
+ *     never refused, so the next verifier judges it;
+ *   - a lane cannot set a claim the envelope owns.
+ */
+import { createHmac, generateKeyPairSync } from "node:crypto";
+
+import { Code } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import {
+  PLATFORM_TOKEN_REFUSAL_MESSAGES,
+  decodeVerifiedPlatformTokenPayload,
+  platformTokenRefusalError,
+  signPlatformToken,
+  verifyPlatformToken,
+} from "../envelope.js";
+import { platformTokenKeyRingFromPem } from "../key-ring.js";
+import type { SigningPlatformTokenKeyRing } from "../key-ring.js";
+
+function pemPair(): { privateKeyPem: string; publicKeyPem: string } {
+  const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+  });
+  return {
+    privateKeyPem: privateKey
+      .export({ format: "pem", type: "pkcs8" })
+      .toString(),
+    publicKeyPem: publicKey.export({ format: "pem", type: "spki" }).toString(),
+  };
+}
+
+const active = pemPair();
+const previous = pemPair();
+
+function signingRing(
+  options: {
+    pair?: { privateKeyPem: string; publicKeyPem: string };
+    audience?: string;
+    ttlSeconds?: number;
+  } = {},
+): SigningPlatformTokenKeyRing {
+  const pair = options.pair ?? active;
+  const ring = platformTokenKeyRingFromPem({
+    privateKeyPem: pair.privateKeyPem,
+    kid: "stigmer-signing-key-1",
+    publicKeyPems: [pair.publicKeyPem],
+    audience: options.audience ?? "",
+    ttlSeconds: options.ttlSeconds ?? 900,
+  });
+  if (ring.signer === undefined) throw new Error("fixture ring must sign");
+  return { ...ring, signer: ring.signer };
+}
+
+const NOW = new Date("2026-09-23T10:00:00Z");
+
+function base64UrlJson(value: object): string {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+
+describe("the platform-token envelope", () => {
+  it("round-trips a signed token: the envelope's claims, then the lane's", () => {
+    const ring = signingRing({ audience: "https://api.stigmer.ai" });
+    const token = signPlatformToken(
+      ring,
+      { sub: "ida_1", platform_client_id: "pcl_1" },
+      { now: NOW },
+    ).token;
+
+    const result = verifyPlatformToken(ring, token, NOW);
+    expect(result.outcome).toBe("verified");
+    if (result.outcome !== "verified") return;
+    expect(result.token.subject).toBe("ida_1");
+    expect(result.token.tokenType).toBeUndefined();
+    expect(result.token.payload).toMatchObject({
+      iss: "stigmer",
+      iat: NOW.getTime() / 1000,
+      exp: NOW.getTime() / 1000 + 900,
+      aud: "https://api.stigmer.ai",
+      platform_client_id: "pcl_1",
+    });
+    const header = JSON.parse(
+      Buffer.from(token.split(".")[0] ?? "", "base64url").toString(),
+    );
+    expect(header).toEqual({
+      alg: "RS256",
+      typ: "JWT",
+      kid: "stigmer-signing-key-1",
+    });
+  });
+
+  it("signs with the lane's own lifetime when it names one, and returns the expiry the token carries", () => {
+    const ring = signingRing({ ttlSeconds: 900 });
+
+    const byDefault = signPlatformToken(ring, { sub: "ida_1" }, { now: NOW });
+    expect(byDefault.expiresAt).toEqual(new Date(NOW.getTime() + 900_000));
+
+    const sandbox = signPlatformToken(
+      ring,
+      { sub: "ida_1", token_type: "sandbox" },
+      { now: NOW, ttlSeconds: 14_400 },
+    );
+    expect(sandbox.expiresAt).toEqual(new Date(NOW.getTime() + 14_400_000));
+    const verified = verifyPlatformToken(ring, sandbox.token, NOW);
+    expect(verified.outcome === "verified" && verified.token.payload.exp).toBe(
+      sandbox.expiresAt.getTime() / 1000,
+    );
+    expect(
+      verifyPlatformToken(
+        ring,
+        sandbox.token,
+        new Date(NOW.getTime() + 900_000),
+      ).outcome,
+    ).toBe("verified");
+  });
+
+  it("refuses a lifetime that is not a positive whole number of seconds", () => {
+    for (const ttlSeconds of [0, -1, 1.5, Number.NaN]) {
+      expect(() =>
+        signPlatformToken(signingRing(), { sub: "ida_1" }, { ttlSeconds }),
+      ).toThrow(/positive integer number of seconds/);
+    }
+  });
+
+  it("reads token_type as the lane discriminator", () => {
+    const ring = signingRing();
+    const token = signPlatformToken(
+      ring,
+      { sub: "ida_guest", token_type: "guest" },
+      { now: NOW },
+    ).token;
+    const result = verifyPlatformToken(ring, token, NOW);
+    expect(result.outcome === "verified" && result.token.tokenType).toBe(
+      "guest",
+    );
+  });
+
+  it("verifies a token signed by the previous key while it is still accepted, whatever the kid says", () => {
+    const old = signPlatformToken(
+      signingRing({ pair: previous }),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    const ring = platformTokenKeyRingFromPem({
+      privateKeyPem: active.privateKeyPem,
+      kid: "stigmer-signing-key-1",
+      publicKeyPems: [active.publicKeyPem, previous.publicKeyPem],
+    });
+    expect(verifyPlatformToken(ring, old, NOW).outcome).toBe("verified");
+  });
+
+  it("refuses `alg: none` and an HMAC token keyed with the public key as a bad signature", () => {
+    const ring = signingRing();
+    const payload = base64UrlJson({
+      iss: "stigmer",
+      sub: "ida_1",
+      exp: NOW.getTime() / 1000 + 60,
+    });
+
+    const unsigned = `${base64UrlJson({ alg: "none", typ: "JWT" })}.${payload}.`;
+    expect(verifyPlatformToken(ring, unsigned, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "signature",
+    });
+
+    const hmacHeader = base64UrlJson({ alg: "HS256", typ: "JWT" });
+    const forged = createHmac("sha256", active.publicKeyPem)
+      .update(`${hmacHeader}.${payload}`)
+      .digest("base64url");
+    expect(
+      verifyPlatformToken(ring, `${hmacHeader}.${payload}.${forged}`, NOW),
+    ).toEqual({
+      outcome: "refused",
+      refusal: "signature",
+    });
+  });
+
+  it("refuses a token signed by a key the ring does not hold", () => {
+    const stranger = signPlatformToken(
+      signingRing({ pair: pemPair() }),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    expect(verifyPlatformToken(signingRing(), stranger, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "signature",
+    });
+  });
+
+  it("refuses an expired token strictly, with no leeway", () => {
+    const ring = signingRing({ ttlSeconds: 60 });
+    const token = signPlatformToken(ring, { sub: "ida_1" }, { now: NOW }).token;
+    const atExpiry = new Date(NOW.getTime() + 60_000);
+    expect(verifyPlatformToken(ring, token, atExpiry)).toEqual({
+      outcome: "refused",
+      refusal: "expired",
+    });
+  });
+
+  it("tolerates a missing aud and refuses one that names another audience", () => {
+    const noAudience = signPlatformToken(
+      signingRing(),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    const expecting = signingRing({ audience: "https://api.stigmer.ai" });
+    expect(verifyPlatformToken(expecting, noAudience, NOW).outcome).toBe(
+      "verified",
+    );
+
+    const elsewhere = signPlatformToken(
+      signingRing({ audience: "https://staging.stigmer.ai" }),
+      { sub: "ida_1" },
+      { now: NOW },
+    ).token;
+    expect(verifyPlatformToken(expecting, elsewhere, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "audience",
+    });
+  });
+
+  it("refuses a token with no subject", () => {
+    const ring = signingRing();
+    const token = signPlatformToken(
+      ring,
+      { platform_client_id: "pcl_1" },
+      { now: NOW },
+    ).token;
+    expect(verifyPlatformToken(ring, token, NOW)).toEqual({
+      outcome: "refused",
+      refusal: "subject",
+    });
+  });
+
+  it("answers foreign for anything that is not a stigmer-issued three-part JWT", () => {
+    const ring = signingRing();
+    expect(verifyPlatformToken(ring, "stk_an_api_key", NOW).outcome).toBe(
+      "foreign",
+    );
+    expect(verifyPlatformToken(ring, "a.b", NOW).outcome).toBe("foreign");
+    const otherIssuer = `${base64UrlJson({ alg: "RS256" })}.${base64UrlJson({ iss: "https://issuer.example", sub: "x" })}.sig`;
+    expect(verifyPlatformToken(ring, otherIssuer, NOW).outcome).toBe("foreign");
+    expect(decodeVerifiedPlatformTokenPayload(otherIssuer)).toBeUndefined();
+    expect(decodeVerifiedPlatformTokenPayload("")).toBeUndefined();
+  });
+
+  it("refuses a lane claim that collides with an envelope claim", () => {
+    expect(
+      () =>
+        signPlatformToken(signingRing(), { sub: "ida_1", exp: 1 }, { now: NOW })
+          .token,
+    ).toThrow(/belongs to the envelope/);
+  });
+
+  it("maps every refusal to UNAUTHENTICATED with the cloud verifier's copy", () => {
+    expect(PLATFORM_TOKEN_REFUSAL_MESSAGES).toEqual({
+      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",
+    });
+    const error = platformTokenRefusalError("expired");
+    expect(error.code).toBe(Code.Unauthenticated);
+    expect(error.rawMessage).toBe("platform token is expired");
+  });
+});

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