@stigmer/server 3.23.1-dev.20260923075205 → 3.25.0

package/dist/platformtoken/envelope.js

@@ -0,0 +1,184 @@
+/**
+ * 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";
+/** 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";
+/** The claims the envelope owns; a lane may not set them. */
+const ENVELOPE_CLAIMS = new Set(["iss", "iat", "exp", "jti", "aud"]);
+/** Wire copy, byte-pinned: the cloud verifier's sentences since the Java issuer. */
+export const PLATFORM_TOKEN_REFUSAL_MESSAGES = {
+    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",
+};
+/**
+ * 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, claims, options = {}) {
+    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, token, now = new Date()) {
+    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) {
+    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) {
+    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, name) {
+    const value = payload[name];
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** A three-part JWT whose header and payload are JSON objects; anything else is undefined. */
+function decode(token) {
+    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) {
+    try {
+        const value = JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
+        return typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function audienceMatches(aud, expected) {
+    if (typeof aud === "string") {
+        return aud === expected;
+    }
+    return Array.isArray(aud) && aud.includes(expected);
+}
+function base64UrlJson(value) {
+    return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+//# sourceMappingURL=envelope.js.map

package/dist/platformtoken/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/platformtoken/envelope.ts"],"names":[],"mappings":"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"}

package/dist/platformtoken/key-ring.d.ts

@@ -0,0 +1,85 @@
+import type { KeyObject } from "node:crypto";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import type { KeyCodec, KeyLoaderOptions } from "../encryption/key-manager.js";
+/** Env var carrying open source's signing key: Base64 of a PKCS#8 PEM. */
+export declare const PLATFORM_TOKEN_KEY_ENV_VAR = "STIGMER_PLATFORM_TOKEN_KEY";
+/** Key file under ~/.stigmer for the generated signing key (PKCS#8 PEM). */
+export declare 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 declare const DEFAULT_PLATFORM_TOKEN_TTL_SECONDS = 900;
+/** The smallest RSA modulus the ring accepts (NIST SP 800-131A's floor). */
+export declare 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 declare function canSign(ring: PlatformTokenKeyRing): ring is SigningPlatformTokenKeyRing;
+/** 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 declare function platformTokenKeyRingFromPem(material: PlatformTokenKeyMaterial): PlatformTokenKeyRing;
+/**
+ * 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 declare function resolvePlatformTokenKeys(input: {
+    readonly requireAuthentication: boolean;
+    readonly supplied: PlatformTokenKeyRing | undefined;
+    readonly edition: ServerEdition;
+    readonly options?: KeyLoaderOptions;
+}): PlatformTokenKeyRing | undefined;
+/**
+ * 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 declare function openSourcePlatformTokenKeyRing(options?: KeyLoaderOptions): SigningPlatformTokenKeyRing;
+/** The ladder codec for an RSA private key stored as PKCS#8 PEM. */
+export declare const RSA_PRIVATE_KEY: KeyCodec<KeyObject>;
+//# sourceMappingURL=key-ring.d.ts.map

package/dist/platformtoken/key-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-ring.d.ts","sourceRoot":"","sources":["../../src/platformtoken/key-ring.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,uDAAuD,CAAC;AAGtF,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAE/E,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,+BAA+B,CAAC;AAEvE,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IACtC,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACpD,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,6DAA6D;AAC7D,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,GAAG;IAC/D,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACtC,CAAC;AAEF,wBAAgB,OAAO,CACrB,IAAI,EAAE,oBAAoB,GACzB,IAAI,IAAI,2BAA2B,CAErC;AAED,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,wBAAwB,GACjC,oBAAoB,CA2CtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC,GAAG,oBAAoB,GAAG,SAAS,CAanC;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,gBAAqB,GAC7B,2BAA2B,CAa7B;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,SAAS,CAuB/C,CAAC"}

package/dist/platformtoken/key-ring.js

@@ -0,0 +1,164 @@
+/**
+ * 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 { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { getOrCreateKey } 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;
+export function canSign(ring) {
+    return ring.signer !== undefined;
+}
+/**
+ * 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) {
+    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) {
+    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 = {}) {
+    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 = {
+    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) {
+    const publicKey = key.type === "private" ? createPublicKey(key) : key;
+    return createHash("sha256")
+        .update(spkiOf(publicKey))
+        .digest("base64url")
+        .slice(0, 16);
+}
+function spkiOf(publicKey) {
+    return publicKey.export({ format: "der", type: "spki" });
+}
+function parseKey(parse, what) {
+    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, what) {
+    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) {
+    return (key.asymmetricKeyType === "rsa" &&
+        (key.asymmetricKeyDetails?.modulusLength ?? 0) >= MIN_RSA_MODULUS_BITS);
+}
+//# sourceMappingURL=key-ring.js.map

package/dist/platformtoken/key-ring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-ring.js","sourceRoot":"","sources":["../../src/platformtoken/key-ring.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/server",
-  "version": "3.23.1-dev.20260923075205",
+  "version": "3.25.0",
   "description": "The Stigmer OSS control plane as a composable library: composeServer, the extension registry and the driver seams a composition builds on. The self-contained deployable of the same server is @stigmer/server-slim.",
   "license": "Apache-2.0",
   "type": "module",
@@ -62,11 +62,11 @@
     "@connectrpc/connect-node": "^2.0.0",
     "@kubernetes/client-node": "2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stigmer/outbound": "3.23.1-dev.20260923075205",
-    "@stigmer/plugin-package": "3.23.1-dev.20260923075205",
-    "@stigmer/protos": "3.23.1-dev.20260923075205",
-    "@stigmer/temporal-codecs": "3.23.1-dev.20260923075205",
-    "@stigmer/zip-structure": "3.23.1-dev.20260923075205",
+    "@stigmer/outbound": "3.25.0",
+    "@stigmer/plugin-package": "3.25.0",
+    "@stigmer/protos": "3.25.0",
+    "@stigmer/temporal-codecs": "3.25.0",
+    "@stigmer/zip-structure": "3.25.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/client": "1.16.2",
     "@temporalio/common": "1.16.2",

package/src/authorization/README.md

@@ -24,7 +24,7 @@ editions; the cloud stores what open source computes.
   (`this` with its type restrictions, `computed`, `from`, `union`), the
   builders, and `declareKind`, which refuses a transcript that cannot be right
   at module load.
-- `model/<kind>.ts` — one transcript per open-source kind (twenty-three), the
+- `model/<kind>.ts` — one transcript per open-source kind (twenty-four), the
   `.fga` file's relations in the file's order, its path in the header.
   `model/index.ts` registers them in `fga.mod` order and answers by kind or by
   FGA type name. Two relations no row carries as a `kind_meta` fact have a

package/src/authorization/__tests__/authorizer.test.ts

@@ -124,9 +124,13 @@ const SEEDED_KINDS: ReadonlyArray<ApiResourceKind> = [
 afterAll(dropPostgresFixture);
 
 describe("NOT_FOUND_EXEMPT_KINDS", () => {
-  it("is the cloud's probe exemption restricted to the kinds this edition serves — identity_account and iam_policy", () => {
+  it("is the cloud's probe exemption restricted to the kinds this edition serves — identity_account, iam_policy and platform_client", () => {
     expect([...NOT_FOUND_EXEMPT_KINDS].sort()).toEqual(
-      [ApiResourceKind.identity_account, ApiResourceKind.iam_policy].sort(),
+      [
+        ApiResourceKind.identity_account,
+        ApiResourceKind.iam_policy,
+        ApiResourceKind.platform_client,
+      ].sort(),
     );
   });
 });

package/src/authorization/__tests__/wire-permissions.test.ts

@@ -140,6 +140,7 @@ describe("every static (kind, permission) the served RPCs ask about is a declare
         "memory",
         "oauth_app",
         "organization",
+        "platform_client",
         "plugin",
         "schedule",
         "session",

package/src/authorization/authorizer.ts

@@ -78,10 +78,16 @@ import { formatObjectRef } from "./tuples.js";
 
 /**
  * Kinds whose missing row is a denial, never `not-found` (arm 4): the
- * cloud's `PROBE_EXEMPT_KINDS` restricted to the kinds this edition
- * serves — `platform`, `identity_provider`, `platform_client` and
- * `invitation` are refused by arm 2 before any row is asked about. The
- * cloud's drift test pins the two sets equal over the open-source tier.
+ * cloud's `PROBE_EXEMPT_KINDS` (stigmer-cloud
+ * src/authorizer/fga-authorizer.ts) restricted to the kinds this edition
+ * serves — `platform`, `identity_provider` and `invitation` are refused by
+ * arm 2 before any row is asked about. The cloud exempts them because
+ * their rows live in its own tables, out of its probe's reach; matching
+ * the set here keeps the wire identical across editions (an unknown
+ * platform client's id is PERMISSION_DENIED with the annotation's copy in
+ * both). The cloud's model drift test pins every kind here inside its
+ * `PROBE_EXEMPT_KINDS`, which is why this set is exported; a kind that
+ * moves into open source joins this set in the same change.
  *
  * `iam_policy` is reachable as a target through the IamPolicy RPCs' own
  * `resource.kind` (a caller may name it); the grant scope refuses such a
@@ -91,6 +97,7 @@ import { formatObjectRef } from "./tuples.js";
 export const NOT_FOUND_EXEMPT_KINDS: ReadonlySet<ApiResourceKind> = new Set([
   ApiResourceKind.identity_account,
   ApiResourceKind.iam_policy,
+  ApiResourceKind.platform_client,
 ]);
 
 /** The Java RequestAuthorizationService's pre-check copy, byte for byte (the cloud renders the same). */

package/src/authorization/model/__tests__/registry.test.ts

@@ -34,6 +34,7 @@ const DECLARED_KINDS = [
   ApiResourceKind.iam_policy,
   ApiResourceKind.api_key,
   ApiResourceKind.oauth_app,
+  ApiResourceKind.platform_client,
   ApiResourceKind.organization,
   ApiResourceKind.agent,
   ApiResourceKind.agent_channel,
@@ -94,6 +95,13 @@ const WIRE_PERMISSIONS_BY_TYPE: Readonly<
     "can_grant_access",
     "can_view_access",
   ],
+  platform_client: [
+    "can_view",
+    "can_edit",
+    "can_delete",
+    "can_grant_access",
+    "can_view_access",
+  ],
   organization: [
     "can_view",
     "can_edit",
@@ -262,7 +270,6 @@ describe("the built-in model's registry", () => {
     for (const unserved of [
       ApiResourceKind.platform,
       ApiResourceKind.identity_provider,
-      ApiResourceKind.platform_client,
       ApiResourceKind.invitation,
     ]) {
       expect(declarationFor(unserved), kindEnumName(unserved)).toBeUndefined();

package/src/authorization/model/index.ts

@@ -12,11 +12,11 @@
  * chain past the depth bound) and for the cloud's drift test, which
  * builds a model from the live `.fga` files and compares.
  *
- * Registered: every kind of the open-source tier — the twenty-three
- * `kind_meta.tier: open_source` members — and nothing else. The four
+ * Registered: every kind of the open-source tier — the twenty-four
+ * `kind_meta.tier: open_source` members — and nothing else. The three
  * files `fga.mod` lists that have no declaration here (`platform`,
- * `identity_provider`, `platform_client`, `invitation`) are kinds this
- * edition does not serve: a check that targets one is refused by the
+ * `identity_provider`, `invitation`) are kinds this edition does not
+ * serve: a check that targets one is refused by the
  * driver, and a tuple that names one (`identity_provider#platform_user`)
  * resolves to nobody. The registry test pins the list against the tier.
  */
@@ -38,6 +38,7 @@ import { mcpServerDeclaration } from "./mcp_server.js";
 import { memoryDeclaration } from "./memory.js";
 import { oauthAppDeclaration } from "./oauth_app.js";
 import { organizationDeclaration } from "./organization.js";
+import { platformClientDeclaration } from "./platform_client.js";
 import { pluginDeclaration } from "./plugin.js";
 import type { KindDeclaration } from "./rewrite.js";
 import { scheduleDeclaration } from "./schedule.js";
@@ -77,6 +78,7 @@ export const builtInModel: Model = newModel([
   iamPolicyDeclaration,
   apiKeyDeclaration,
   oauthAppDeclaration,
+  platformClientDeclaration,
   organizationDeclaration,
   agentDeclaration,
   agentChannelDeclaration,

package/src/authorization/model/oauth_app.ts

@@ -1,6 +1,7 @@
 /**
- * Transcript of fga/model/iam/oauth_app.fga — the one organization-scoped
- * kind whose `owner` has NO admin arm while its `viewer` does: the file's
+ * Transcript of fga/model/iam/oauth_app.fga — an organization-scoped kind
+ * whose `owner` has NO admin arm while its `viewer` does (platform_client
+ * shares the shape, for the same reason): the file's
  * "administrative visibility" for the organization's admins over a
  * registration that holds vendor client credentials, with change and
  * deletion the creator's (or an explicit grant's) alone, and no public