@stigmer/server 3.24.0 → 3.25.0

package/src/domain/platformclient/__tests__/verifier-and-guard.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Pins the PlatformClient user-token verifier and the origin guard, the two
+ * halves of the minting client's contract on every request a token bears:
+ *   - the verifier claims only an untyped platform token, passes a foreign
+ *     or typed one, refuses a bad one with the envelope's copy, refuses a
+ *     token naming no client, refuses a deleted client's token with the
+ *     cloud's liveness copy, lets a store fault propagate (never a
+ *     revocation), and stamps the account from `sub` as a `user`;
+ *   - the guard reads no client for a request without an Origin, passes an
+ *     open allowlist and a listed origin case-insensitively, refuses an
+ *     unlisted origin and the opaque "null" with the cloud's copy, and
+ *     passes every credential that is not an untyped platform user token.
+ */
+import { generateKeyPairSync } from "node:crypto";
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it, vi } from "vitest";
+
+import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { PlatformClientSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
+import { PlatformClientQueryController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/query_pb";
+
+import { silentLogger } from "../../../extensions/__tests__/composed-support.js";
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import { signPlatformToken } from "../../../platformtoken/envelope.js";
+import { platformTokenKeyRingFromPem } from "../../../platformtoken/key-ring.js";
+import type { SigningPlatformTokenKeyRing } from "../../../platformtoken/key-ring.js";
+import { DELETED_CLIENT_MESSAGE, originRefusalMessage } from "../constants.js";
+import { newPlatformClientOriginGuard } from "../origin-guard.js";
+import { newPlatformClientTokenVerifier } from "../verifier.js";
+
+const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+});
+const built = platformTokenKeyRingFromPem({
+  privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+  publicKeyPems: [publicKey.export({ format: "pem", type: "spki" }).toString()],
+});
+if (built.signer === undefined) throw new Error("fixture ring must sign");
+const ring: SigningPlatformTokenKeyRing = { ...built, signer: built.signer };
+
+const silent = silentLogger;
+
+function client(allowedOrigins: string[] = []): PlatformClient {
+  return create(PlatformClientSchema, {
+    metadata: { id: "pcl_dashboard", org: "acme", slug: "dashboard" },
+    spec: { clientId: "stgm_cid_x", allowedOrigins },
+  });
+}
+
+function storeOf(found: PlatformClient | undefined) {
+  return { findById: vi.fn(async () => found) };
+}
+
+function userToken(claims: Record<string, string> = {}): string {
+  return signPlatformToken(ring, {
+    sub: "ida_pat",
+    email: "pat@example.com",
+    name: "Pat",
+    platform_client_id: "pcl_dashboard",
+    ...claims,
+  }).token;
+}
+
+function callerWith(rawToken: string): CallerIdentity {
+  return {
+    identityId: "ida_pat",
+    callerClass: "user",
+    issuer: "stigmer",
+    rawToken,
+  };
+}
+
+async function refusal(promise: Promise<unknown>): Promise<ConnectError> {
+  try {
+    await promise;
+  } catch (error) {
+    if (error instanceof ConnectError) return error;
+    throw error;
+  }
+  throw new Error("expected a ConnectError refusal");
+}
+
+describe("the PlatformClient user-token verifier", () => {
+  it("stamps the account the token was minted for as a user, with the asserted profile", async () => {
+    const token = userToken();
+    const identity = await newPlatformClientTokenVerifier({
+      keys: ring,
+      clients: storeOf(client()),
+    }).verify(token);
+    expect(identity).toEqual({
+      identityId: "ida_pat",
+      callerClass: "user",
+      issuer: "stigmer",
+      rawToken: token,
+      email: "pat@example.com",
+      displayName: "Pat",
+    });
+  });
+
+  it("passes a foreign token and a typed platform token to the next verifier", async () => {
+    const verifier = newPlatformClientTokenVerifier({
+      keys: ring,
+      clients: storeOf(client()),
+    });
+    expect(await verifier.verify("stk_api_key")).toBeNull();
+    expect(
+      await verifier.verify(userToken({ token_type: "guest" })),
+    ).toBeNull();
+  });
+
+  it("refuses a deleted client's token with the liveness copy, and a token naming no client", async () => {
+    const gone = await refusal(
+      newPlatformClientTokenVerifier({
+        keys: ring,
+        clients: storeOf(undefined),
+      }).verify(userToken()),
+    );
+    expect(gone.code).toBe(Code.Unauthenticated);
+    expect(gone.rawMessage).toBe(DELETED_CLIENT_MESSAGE);
+
+    const unnamed = await refusal(
+      newPlatformClientTokenVerifier({
+        keys: ring,
+        clients: storeOf(client()),
+      }).verify(signPlatformToken(ring, { sub: "ida_pat" }).token),
+    );
+    expect(unnamed.code).toBe(Code.Unauthenticated);
+  });
+
+  it("lets a store fault propagate instead of reading it as a revocation", async () => {
+    const failing = {
+      findById: vi.fn(async () => {
+        throw new Error("database down");
+      }),
+    };
+    await expect(
+      newPlatformClientTokenVerifier({ keys: ring, clients: failing }).verify(
+        userToken(),
+      ),
+    ).rejects.toThrow("database down");
+  });
+});
+
+describe("the PlatformClient origin guard", () => {
+  const method = PlatformClientQueryController.method.get;
+
+  it("reads no client for a request without an Origin header", async () => {
+    const clients = storeOf(client(["https://app.example"]));
+    const guard = newPlatformClientOriginGuard({ clients, logger: silent });
+    await guard.guard(callerWith(userToken()), method, new Headers());
+    await guard.guard(
+      callerWith(userToken()),
+      method,
+      new Headers({ origin: "  " }),
+    );
+    expect(clients.findById).not.toHaveBeenCalled();
+  });
+
+  it("passes an open allowlist and a listed origin, compared case-insensitively", async () => {
+    await newPlatformClientOriginGuard({
+      clients: storeOf(client()),
+      logger: silent,
+    }).guard(
+      callerWith(userToken()),
+      method,
+      new Headers({ origin: "https://anywhere.example" }),
+    );
+    await newPlatformClientOriginGuard({
+      clients: storeOf(client(["https://app.example"])),
+      logger: silent,
+    }).guard(
+      callerWith(userToken()),
+      method,
+      new Headers({ origin: "https://APP.example" }),
+    );
+  });
+
+  it("refuses an unlisted origin and the opaque origin with the cloud's copy", async () => {
+    const guard = newPlatformClientOriginGuard({
+      clients: storeOf(client(["https://app.example"])),
+      logger: silent,
+    });
+    for (const origin of ["https://evil.example", "null"]) {
+      const denied = await refusal(
+        guard.guard(callerWith(userToken()), method, new Headers({ origin })),
+      );
+      expect(denied.code).toBe(Code.PermissionDenied);
+      expect(denied.rawMessage).toBe(originRefusalMessage(origin));
+    }
+  });
+
+  it("passes every credential that is not an untyped platform user token", async () => {
+    const clients = storeOf(client(["https://app.example"]));
+    const guard = newPlatformClientOriginGuard({ clients, logger: silent });
+    const foreign = new Headers({ origin: "https://evil.example" });
+    await guard.guard(callerWith("stk_api_key"), method, foreign);
+    await guard.guard(callerWith(""), method, foreign);
+    await guard.guard(
+      callerWith(userToken({ token_type: "guest" })),
+      method,
+      foreign,
+    );
+    expect(clients.findById).not.toHaveBeenCalled();
+  });
+});

package/src/domain/platformclient/constants.ts

@@ -0,0 +1,120 @@
+/**
+ * The platform-client domain's pinned vocabulary: reserved names, the
+ * user-token claim names and every refusal sentence.
+ *
+ * Most copy is wire contract inherited from Stigmer Cloud, which has
+ * answered integrators with these exact sentences since the Java service:
+ * the mint's credential, expiry, organization and provisioning refusals,
+ * the system-managed and reserved-slug refusals, and the minting client's
+ * liveness and origin refusals on every request its tokens bear (pinned
+ * cross-edition by platformclient-enforcement.conformance.test.ts). The
+ * sentences open source adds — a server that cannot mint, the guest
+ * method's edition refusal, the mismatched-account guard — follow the
+ * house style (single-quoted handles).
+ */
+
+/** The kind's name as the shared error constructors render it. */
+export const PLATFORM_CLIENT_KIND_NAME = "PlatformClient";
+
+/**
+ * The slug of an organization's system-managed share client: the client
+ * an edition that hosts shared-agent pages names in the tokens it signs
+ * for guests and schedule fires, so every platform token names a real
+ * client. A user client holding it would be adopted by those lanes.
+ */
+export const SYSTEM_SHARE_CLIENT_SLUG = "system-share-client";
+
+/**
+ * Slugs the platform keeps for its own clients: the create chain refuses
+ * them, and newSystemManagedPlatformClient builds only under them.
+ */
+export const RESERVED_PLATFORM_CLIENT_SLUGS: ReadonlySet<string> = new Set([
+  SYSTEM_SHARE_CLIENT_SLUG,
+]);
+
+/** The claims the PlatformClient user token carries beside the envelope's. */
+export const USER_TOKEN_CLAIMS = {
+  subject: "sub",
+  externalUserId: "ext_user_id",
+  email: "email",
+  name: "name",
+  org: "org",
+  platformClientId: "platform_client_id",
+} as const;
+
+/** The mint response's token_type. */
+export const BEARER_TOKEN_TYPE = "Bearer";
+
+export function reservedSlugMessage(slug: string): string {
+  return `The slug '${slug}' is reserved for the platform's system-managed resources and cannot be used. If you did not provide a slug explicitly, it was derived from the resource name — choose a different name or provide an explicit slug.`;
+}
+
+/** The three mutations a system-managed client refuses. */
+export type SystemManagedMutation = "updated" | "deleted" | "rotated";
+
+export function systemManagedMessage(verb: SystemManagedMutation): string {
+  return `This platform client is system-managed and cannot be ${verb}`;
+}
+
+export function referenceNotFoundMessage(org: string, slug: string): string {
+  return `PlatformClient '${org}/${slug}' not found`;
+}
+
+export const INVALID_CLIENT_CREDENTIALS_MESSAGE =
+  "Invalid client_id or client_secret";
+
+export const EXPIRED_CLIENT_SECRET_MESSAGE =
+  "PlatformClient secret has expired. Use rotateSecret to generate a new one.";
+
+export function organizationMismatchMessage(owningOrg: string): string {
+  return `org_id must be empty or the PlatformClient's owning organization ('${owningOrg}'); cross-organization minting is not supported`;
+}
+
+export function noAccountMessage(externalUserId: string, org: string): string {
+  return `User '${externalUserId}' has no Stigmer account in organization '${org}'. Enable auto_provision_accounts on the PlatformClient or create the account first.`;
+}
+
+export const OWNER_AUTO_GRANT_MESSAGE =
+  "auto_grant_role cannot be 'owner'; organization ownership must be assigned explicitly.";
+
+export const PROVISIONING_FAILED_MESSAGE =
+  "Account provisioning failed. No partial account was left behind; the request is safe to retry.";
+
+export function blankSubjectPartMessage(
+  part: "org" | "externalUserId",
+): string {
+  return `${part} must not be null or blank`;
+}
+
+export function subjectSeparatorMessage(
+  part: "org" | "externalUserId",
+  value: string,
+): string {
+  return `${part} must not contain the separator character '|': ${value}`;
+}
+
+export function foreignAccountMessage(
+  externalUserId: string,
+  org: string,
+): string {
+  return `User '${externalUserId}' in organization '${org}' resolves to an account no platform client provisioned — refusing to mint a token for it`;
+}
+
+export const MINTING_REQUIRES_AUTHENTICATION_MESSAGE =
+  "mintUserToken requires a server that authenticates its callers: this server trusts every request, so nothing would verify the token — configure an identity provider (STIGMER_OIDC_ISSUER) to enable PlatformClient token minting";
+
+export const MINTING_DISABLED_MESSAGE =
+  "mintUserToken is disabled: this server's platform-token key ring holds no signing key";
+
+export const GUEST_MINT_UNIMPLEMENTED_MESSAGE =
+  "PlatformClientTokenController.mintGuestToken is not implemented: guest tokens for shared agents are served by the Cloud edition";
+
+export const TOKEN_NAMES_NO_CLIENT_MESSAGE =
+  "platform token names no platform client";
+
+export const DELETED_CLIENT_MESSAGE =
+  "The platform client that minted this token has been deleted, so the token is no longer accepted. Mint a new user token from an active platform client.";
+
+export function originRefusalMessage(origin: string): string {
+  return `Request origin '${origin}' is not in this platform client's allowed_origins. Add it to the PlatformClient's allowed_origins to permit browser requests from this origin.`;
+}