@sanoma-ai/workflows 0.10.3 → 0.10.7

package/src/identity-broker.ts

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import type { IdentityEnrollment, IdentityEnrollments, IdentityAudit } from "./cloud-identity.ts";
+
+const CREDENTIAL = /^[A-Za-z0-9_-]{43}$/;
+const ACCOUNT = /^[a-z][a-z0-9-]+@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/;
+const credentialHash = (credential: string) => createHash("sha256").update(credential).digest("hex");
+
+const validEnrollment = (e: IdentityEnrollment | undefined): e is IdentityEnrollment =>
+  !!e &&
+  [e.deployment, e.company, e.environment].every((v) => typeof v === "string" && v.length > 0 && v.length <= 256) &&
+  ACCOUNT.test(e.serviceAccount) &&
+  Number.isSafeInteger(e.generation) &&
+  e.generation > 0;
+const reply = (status: number, body: unknown) =>
+  Response.json(body, {
+    status,
+    headers: { "Cache-Control": "no-store", Pragma: "no-cache" },
+  });
+
+// Node/edge adapters can represent an empty POST as a stream. Reject actual bytes,
+// without buffering attacker-controlled input or waiting indefinitely for its end.
+async function hasBody(request: Request): Promise<boolean> {
+  if (!request.body) return false;
+  const reader = request.body.getReader();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const first = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new Error("Invalid broker request")), 5_000);
+      }),
+    ]);
+    return !first.done;
+  } finally {
+    clearTimeout(timeout);
+    void reader.cancel().catch(() => {});
+  }
+}
+
+/** Shared server-only issuance boundary. Public factories fix the route, audience and token kind. */
+export function enrollmentBroker<T extends { expiresAt: number }>(options: {
+  path: string;
+  method: "GET" | "POST";
+  enrollments: IdentityEnrollments;
+  accept(enrollment: IdentityEnrollment): boolean;
+  issue(enrollment: IdentityEnrollment): Promise<T>;
+  valid(token: T, now: number): boolean;
+  body(token: T): unknown;
+  audit(event: IdentityAudit): Promise<void>;
+}): (request: Request) => Promise<Response> {
+  return async (request) => {
+    let enrollment: IdentityEnrollment | undefined;
+    try {
+      const url = new URL(request.url);
+      if (url.pathname !== options.path || request.method !== options.method) return reply(404, { error: "not_found" });
+      if (url.search || (await hasBody(request))) return reply(400, { error: "invalid_request" });
+      const authorization = request.headers.get("authorization") ?? "";
+      const credential = authorization.startsWith("Bearer ") ? authorization.slice(7) : "";
+      const hash = CREDENTIAL.test(credential) ? credentialHash(credential) : undefined;
+      enrollment = hash ? await options.enrollments.active(hash) : undefined;
+      if (!validEnrollment(enrollment) || !options.accept(enrollment)) {
+        await options.audit({ result: "denied" });
+        return reply(401, { error: "unauthorized" });
+      }
+      // Copy authoritative values before any awaits; caller fields never select a target or lifetime.
+      enrollment = {
+        deployment: enrollment.deployment,
+        company: enrollment.company,
+        environment: enrollment.environment,
+        serviceAccount: enrollment.serviceAccount,
+        generation: enrollment.generation,
+      };
+      const token = await options.issue(enrollment);
+      if (!options.valid(token, Date.now())) throw new Error("Invalid issued token");
+      const current = await options.enrollments.active(hash!);
+      if (
+        !current ||
+        (Object.keys(enrollment) as (keyof IdentityEnrollment)[]).some((key) => current[key] !== enrollment![key])
+      ) {
+        await options.audit({ result: "denied", enrollment });
+        return reply(401, { error: "unauthorized" });
+      }
+      await options.audit({ result: "issued", enrollment, expiresAt: token.expiresAt });
+      return reply(200, options.body(token));
+    } catch {
+      try {
+        await options.audit({ result: "unavailable", ...(enrollment && { enrollment }) });
+      } catch {
+        /* fail closed */
+      }
+      return reply(503, { error: "unavailable" });
+    }
+  };
+}

package/src/identity-provisioning.ts

@@ -0,0 +1,208 @@
+import type { Pool, PoolClient } from "pg";
+import type { IdentityEnrollment } from "./cloud-identity.ts";
+
+export type DeploymentIdentity = Omit<IdentityEnrollment, "generation">;
+export interface EnrollIdentity extends IdentityEnrollment {
+  hash: string;
+  validUntil: string;
+}
+
+/** Provisioning authority only. The serving broker receives the separate read-only interface. */
+export interface IdentityProvisioning {
+  enroll(input: EnrollIdentity): Promise<void>;
+  retire(input: DeploymentIdentity & { generation: number; validUntil: string }): Promise<void>;
+  revoke(input: DeploymentIdentity): Promise<void>;
+}
+
+export class IdentityProvisioningError extends Error {
+  readonly retryable: boolean;
+  readonly code: "invalid" | "conflict" | "unavailable";
+  constructor(code: "invalid" | "conflict" | "unavailable") {
+    super(`Identity provisioning: ${code}`);
+    this.name = "IdentityProvisioningError";
+    this.code = code;
+    this.retryable = code === "unavailable";
+  }
+}
+
+/** Recognize another package copy without ever forwarding arbitrary messages or code strings. */
+export function identityProvisioningCode(error: unknown): IdentityProvisioningError["code"] | undefined {
+  if (!error || typeof error !== "object" || !("name" in error) || error.name !== "IdentityProvisioningError") return;
+  if (!("code" in error)) return;
+  switch (error.code) {
+    case "invalid":
+      return "invalid";
+    case "conflict":
+      return "conflict";
+    case "unavailable":
+      return "unavailable";
+  }
+}
+
+function fail(code: "invalid" | "conflict"): never {
+  throw new IdentityProvisioningError(code);
+}
+const sameIdentity = (a: DeploymentIdentity, b: DeploymentIdentity) =>
+  a.deployment === b.deployment &&
+  a.company === b.company &&
+  a.environment === b.environment &&
+  a.serviceAccount === b.serviceAccount;
+const checkIdentity = (input: DeploymentIdentity) => {
+  if (
+    ![input.deployment, input.company, input.environment].every(
+      (s) => typeof s === "string" && s.length > 0 && s.length <= 256 && !s.includes("\0"),
+    ) ||
+    !/^[a-z][a-z0-9-]+@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/.test(input.serviceAccount)
+  )
+    fail("invalid");
+};
+const generationOf = (generation: number) => {
+  if (!Number.isSafeInteger(generation) || generation <= 0) fail("invalid");
+};
+const deadlineOf = (value: string) => {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time)) fail("invalid");
+  return time;
+};
+
+/** Caller owns a dedicated writer pool; never give this pool to the broker or company code. */
+export function postgresIdentityProvisioning(
+  database: () => Promise<Pick<Pool, "connect">>,
+  options: { maxValidityMs: number },
+): IdentityProvisioning {
+  const maximum = options.maxValidityMs;
+  if (!Number.isSafeInteger(maximum) || maximum <= 0) fail("invalid");
+  async function transaction(
+    input: DeploymentIdentity,
+    create: boolean,
+    run: (db: PoolClient, enabled: boolean, now: number) => Promise<void>,
+  ) {
+    checkIdentity(input);
+    let db: PoolClient | undefined;
+    try {
+      db = await (await database()).connect();
+      await db.query("BEGIN");
+      if (create)
+        await db.query(
+          `INSERT INTO sanoma_identity.deployments (id, company, environment, service_account)
+          VALUES ($1,$2,$3,$4) ON CONFLICT (id) DO NOTHING`,
+          [input.deployment, input.company, input.environment, input.serviceAccount],
+        );
+      // Every writer takes the deployment row lock: enrollment cannot race revocation/retirement.
+      const { rows } = await db.query<DeploymentIdentity & { enabled: boolean }>(
+        `SELECT id AS deployment, company, environment, service_account AS "serviceAccount", enabled
+          FROM sanoma_identity.deployments WHERE id=$1 FOR UPDATE`,
+        [input.deployment],
+      );
+      const row = rows[0];
+      if (!row || !sameIdentity(row, input)) fail("conflict");
+      const clock = await db.query<{ now: Date }>("SELECT clock_timestamp() AS now");
+      await run(db, row.enabled, clock.rows[0]!.now.getTime());
+      await db.query("COMMIT");
+    } catch (error) {
+      await db?.query("ROLLBACK").catch(() => {});
+      const code = identityProvisioningCode(error);
+      if (code) throw new IdentityProvisioningError(code);
+      if ((error as { code?: string })?.code === "23505") throw new IdentityProvisioningError("conflict");
+      throw new IdentityProvisioningError("unavailable");
+    } finally {
+      db?.release();
+    }
+  }
+  return {
+    async enroll(input) {
+      generationOf(input.generation);
+      const until = deadlineOf(input.validUntil);
+      if (!/^[0-9a-f]{64}$/.test(input.hash)) fail("invalid");
+      await transaction(input, true, async (db, enabled, now) => {
+        if (!enabled) fail("conflict");
+        if (until <= now || until - now > maximum) fail("invalid");
+        const { rows } = await db.query<{ generation: string; hash: string; valid_until: Date; revoked: boolean }>(
+          `SELECT generation, hash, valid_until, revoked FROM sanoma_identity.credentials
+            WHERE deployment=$1 ORDER BY generation DESC`,
+          [input.deployment],
+        );
+        const existing = rows.find((r) => Number(r.generation) === input.generation);
+        if (existing) {
+          // An exact retry is safe. Never extend a retired generation or revive a revoked one.
+          if (existing.hash !== input.hash || existing.revoked || existing.valid_until.getTime() !== until)
+            fail("conflict");
+          return;
+        }
+        if (rows[0] && Number(rows[0].generation) >= input.generation) fail("conflict");
+        await db.query(
+          `INSERT INTO sanoma_identity.credentials (hash, deployment, generation, valid_until)
+            VALUES ($1,$2,$3,$4)`,
+          [input.hash, input.deployment, input.generation, new Date(until)],
+        );
+      });
+    },
+    async retire(input) {
+      generationOf(input.generation);
+      const until = deadlineOf(input.validUntil);
+      await transaction(input, false, async (db) => {
+        // Retirement only shortens access. The predicate protects the schema's finite interval.
+        const result = await db.query(
+          `UPDATE sanoma_identity.credentials SET
+            revoked=revoked OR $3::timestamptz <= clock_timestamp(),
+            valid_until=CASE WHEN $3::timestamptz > valid_from THEN LEAST(valid_until,$3::timestamptz) ELSE valid_until END
+            WHERE deployment=$1 AND generation=$2`,
+          [input.deployment, input.generation, new Date(until)],
+        );
+        if (!result.rowCount) fail("conflict");
+      });
+    },
+    async revoke(input) {
+      await transaction(input, false, async (db) => {
+        // Terminal for this deployment id. A new enrollment cannot silently re-enable it.
+        await db.query("UPDATE sanoma_identity.deployments SET enabled=false WHERE id=$1", [input.deployment]);
+      });
+    },
+  };
+}
+
+/** Run-local sandbox authority: never reads or mutates the live enrollment database. */
+export function memoryIdentityProvisioning(): IdentityProvisioning {
+  const deployments = new Map<
+    string,
+    { identity: DeploymentIdentity; enabled: boolean; credentials: Map<number, EnrollIdentity> }
+  >();
+  const hashes = new Set<string>();
+  const find = (input: DeploymentIdentity) => {
+    checkIdentity(input);
+    const found = deployments.get(input.deployment);
+    if (!found || !sameIdentity(found.identity, input)) return fail("conflict");
+    return found;
+  };
+  return {
+    async enroll(input) {
+      checkIdentity(input);
+      generationOf(input.generation);
+      if (deadlineOf(input.validUntil) <= Date.now() || !/^[0-9a-f]{64}$/.test(input.hash)) fail("invalid");
+      const found = deployments.get(input.deployment);
+      if (found && (!sameIdentity(found.identity, input) || !found.enabled)) fail("conflict");
+      const current = found?.credentials.get(input.generation);
+      if (current) {
+        if (current.hash !== input.hash || deadlineOf(current.validUntil) !== deadlineOf(input.validUntil))
+          fail("conflict");
+        return;
+      }
+      if (hashes.has(input.hash) || (found && [...found.credentials.keys()].some((g) => g >= input.generation)))
+        fail("conflict");
+      const row = found ?? { identity: { ...input }, enabled: true, credentials: new Map<number, EnrollIdentity>() };
+      row.credentials.set(input.generation, { ...input });
+      hashes.add(input.hash);
+      deployments.set(input.deployment, row);
+    },
+    async retire(input) {
+      generationOf(input.generation);
+      const deadline = deadlineOf(input.validUntil);
+      const current = find(input).credentials.get(input.generation);
+      if (!current) return fail("conflict");
+      current.validUntil = new Date(Math.min(deadlineOf(current.validUntil), deadline)).toISOString();
+    },
+    async revoke(input) {
+      find(input).enabled = false;
+    },
+  };
+}

package/src/identity-service.ts

@@ -0,0 +1,179 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { Pool } from "pg";
+import { NodeRequest, sendNodeResponse } from "srvx/node";
+import {
+  identityBroker,
+  postgresIdentityEnrollments,
+  attachedGoogleTokenIssuer,
+  provisioningIdentityBroker,
+  attachedGoogleIdTokenIssuer,
+  type ProvisioningIdentity,
+  type IdentityAudit,
+} from "./cloud-identity.ts";
+
+/** Install with administrative authority in the audit database, separately from the serving process. */
+export const CLOUD_IDENTITY_AUDIT_SQL = `
+CREATE SCHEMA IF NOT EXISTS sanoma_identity;
+REVOKE ALL ON SCHEMA sanoma_identity FROM PUBLIC;
+CREATE TABLE IF NOT EXISTS sanoma_identity.audit_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  recorded_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  result text NOT NULL CHECK (result IN ('issued', 'denied', 'unavailable')),
+  deployment text, company text, environment text, service_account text,
+  generation bigint, expires_at timestamptz
+);
+REVOKE ALL ON sanoma_identity.audit_events FROM PUBLIC;
+`;
+
+export interface IdentityServiceOptions {
+  /** Explicit broker database login with SELECT only on the enrollment tables. */
+  enrollmentDatabaseUrl: string;
+  /** Explicit audit database login with INSERT only on audit_events. */
+  auditDatabaseUrl: string;
+  mode: { type: "runtime" } | { type: "provisioning"; identity: ProvisioningIdentity };
+  /** Cloud Run terminates TLS. Keep this service behind the deployment's HTTPS ingress. */
+  host?: string;
+  port?: number;
+  /** Bound in-flight issuance work and database waiters; excess requests receive 429. */
+  maxConcurrentRequests?: number;
+}
+
+const unavailable = () => new Error("Identity service unavailable");
+const poolFor = (connectionString: string) => {
+  if (!connectionString) throw unavailable();
+  const pool = new Pool({
+    connectionString,
+    max: 5,
+    connectionTimeoutMillis: 10_000,
+    query_timeout: 10_000,
+    statement_timeout: 10_000,
+  });
+  // Never forward database diagnostics: they can contain connection information.
+  pool.on("error", () => {});
+  return pool;
+};
+
+async function checkRoles(reader: Pool, audit: Pool): Promise<void> {
+  const read = await reader.query<{ allowed: boolean }>(`SELECT
+    has_schema_privilege('sanoma_identity', 'USAGE') AND
+    NOT has_schema_privilege('sanoma_identity', 'CREATE') AND
+    NOT EXISTS (SELECT FROM pg_roles WHERE rolname = current_user AND (rolsuper OR rolcreaterole OR rolcreatedb OR rolbypassrls)) AND
+    has_table_privilege('sanoma_identity.deployments', 'SELECT') AND
+    has_table_privilege('sanoma_identity.credentials', 'SELECT') AND
+    NOT has_table_privilege('sanoma_identity.deployments', 'INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER') AND
+    NOT has_table_privilege('sanoma_identity.credentials', 'INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER') AS allowed`);
+  const write = await audit.query<{ allowed: boolean }>(`SELECT
+    has_schema_privilege('sanoma_identity', 'USAGE') AND
+    NOT has_schema_privilege('sanoma_identity', 'CREATE') AND
+    NOT EXISTS (SELECT FROM pg_roles WHERE rolname = current_user AND (rolsuper OR rolcreaterole OR rolcreatedb OR rolbypassrls)) AND
+    has_table_privilege('sanoma_identity.audit_events', 'INSERT') AND
+    NOT has_table_privilege('sanoma_identity.audit_events', 'SELECT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER') AS allowed`);
+  if (read.rows[0]?.allowed !== true || write.rows[0]?.allowed !== true) throw unavailable();
+}
+
+/** Starts a standalone broker without loading company code, starting a worker or installing schemas. */
+export async function startIdentityService(options: IdentityServiceOptions): Promise<{
+  url: string;
+  stop(): Promise<void>;
+}> {
+  let reader: Pool | undefined, audit: Pool | undefined;
+  const server = createServer();
+  let closing: Promise<void> | undefined;
+  const close = () =>
+    (closing ??= (async () => {
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+        server.closeAllConnections();
+      });
+      await Promise.all([reader?.end(), audit?.end()]);
+    })());
+  try {
+    const limit = options.maxConcurrentRequests ?? 32;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 256) throw unavailable();
+    let active = 0;
+    reader = poolFor(options.enrollmentDatabaseUrl);
+    audit = poolFor(options.auditDatabaseUrl);
+    await checkRoles(reader, audit);
+    const record = async (event: IdentityAudit) => {
+      const e = event.enrollment;
+      // Fixed columns only: no tokens, hashes, headers or arbitrary caller fields.
+      await audit!.query(
+        `INSERT INTO sanoma_identity.audit_events
+        (result, deployment, company, environment, service_account, generation, expires_at)
+        VALUES ($1,$2,$3,$4,$5,$6,$7)`,
+        [
+          event.result,
+          e?.deployment ?? null,
+          e?.company ?? null,
+          e?.environment ?? null,
+          e?.serviceAccount ?? null,
+          e?.generation ?? null,
+          event.expiresAt === undefined ? null : new Date(event.expiresAt),
+        ],
+      );
+    };
+    const enrollments = postgresIdentityEnrollments(async () => reader!);
+    const handle =
+      options.mode.type === "runtime"
+        ? identityBroker({ enrollments, issue: attachedGoogleTokenIssuer(), audit: record })
+        : options.mode.type === "provisioning"
+          ? provisioningIdentityBroker({
+              identity: options.mode.identity,
+              enrollments,
+              issue: attachedGoogleIdTokenIssuer(options.mode.identity),
+              audit: record,
+            })
+          : (() => {
+              throw unavailable();
+            })();
+    server.requestTimeout = 15_000;
+    server.headersTimeout = 10_000;
+    server.on("request", (req, res) => {
+      // Fetch Request adapters may hide a GET body. Refuse it at the HTTP boundary.
+      if (
+        req.method === "GET" &&
+        (req.headers["transfer-encoding"] || (req.headers["content-length"] ?? "0") !== "0")
+      ) {
+        res.writeHead(400, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+        res.end('{"error":"invalid_request"}');
+        return;
+      }
+      if (req.url === "/healthz" && (req.method === "GET" || req.method === "HEAD")) {
+        res.writeHead(200, { "Content-Type": "text/plain", "Cache-Control": "no-store" });
+        res.end("ok\n");
+        return;
+      }
+      if (active >= limit) {
+        res.writeHead(429, { "Content-Type": "application/json", "Cache-Control": "no-store", "Retry-After": "1" });
+        res.end('{"error":"busy"}');
+        return;
+      }
+      active++;
+      Promise.resolve()
+        .then(() => handle(new NodeRequest({ req, res })))
+        .then((response) => sendNodeResponse(res, response))
+        .catch(() => {
+          if (res.headersSent) res.destroy();
+          else {
+            res.writeHead(503, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+            res.end('{"error":"unavailable"}');
+          }
+        })
+        .finally(() => {
+          active--;
+        });
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(options.port ?? 8080, options.host ?? "127.0.0.1", resolve);
+    });
+    const { address, family, port } = server.address() as AddressInfo;
+    const hostname =
+      address === "0.0.0.0" || address === "::" ? "localhost" : family === "IPv6" ? `[${address}]` : address;
+    return { url: `http://${hostname}:${port}`, stop: close };
+  } catch {
+    await close().catch(() => {});
+    throw unavailable();
+  }
+}

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   type ResourceGroup,
   retryableStatus,
   type SignInMethod,
+  type SocialClients,
   type VendorInfo,
   withSetup,
 } from "./op.ts";
@@ -60,6 +61,7 @@ export {
   type ResourceSpec,
   withoutWriteOnly,
 } from "./resource.ts";
+export { type DnsRecord, dnsRecord } from "./dns.ts";
 export {
   declaredWakeup,
   defineConfig,

package/src/op.ts

@@ -376,6 +376,11 @@ export type LoginMethod = "code" | "github" | "invite" | "password";
 /** How a person signed in to the staff login, which the ledger records (`signin.recorded`): all but a password. */
 export type SignInMethod = Exclude<LoginMethod, "password">;
 
+/** The company's own OAuth clients, as a login takes them: GitHub's is its GitHub App's client. */
+export interface SocialClients {
+  github?: { clientId: string; clientSecret: string };
+}
+
 /**
  * What the app gives a connector's login half (`ConnectorSetup.login`) when it makes it: for a
  * public site, once per site; for the staff login, once, with `staff`.
@@ -405,12 +410,17 @@ export interface LoginContext {
    * sender, and then the login offers no code.
    */
   sendCode?(email: string, code: string): Promise<void>;
+  /**
+   * For a public site's login: the company's own OAuth clients (its GitHub App's), each a method
+   * when given, by which a visitor signs in or, signed in, links that account (`LoginIdentity.github`).
+   */
+  social?: SocialClients;
   /** For the staff login only: who it may let in, the company's social clients, and where it tells of a sign-in. */
   staff?: {
     /** Whether the people files declare the person `identity` names; a login never makes a user for anyone else. */
     admits(identity: LoginIdentity): boolean;
     /** The company's own OAuth clients, each a method when given. */
-    social: { github?: { clientId: string; clientSecret: string } };
+    social: SocialClients;
     /** Tells the app of a sign-in by `method` of the person `identity` names, which the ledger records. Must not throw. */
     record(method: SignInMethod, identity: LoginIdentity): Promise<void>;
   };
@@ -453,8 +463,8 @@ export function sameOrigin(request: Request): boolean {
 export interface LoginHalf {
   /**
    * Who signed in, as the provider's stable subject, with their email when the provider verified
-   * it and their GitHub login when they signed in with GitHub; null for a missing or bad cookie,
-   * for which it never throws.
+   * it and their GitHub login when they signed in with GitHub or linked it; null for a missing or
+   * bad cookie, for which it never throws.
    */
   verify(request: Request): Promise<{ subject: string; email?: string; github?: string } | null>;
   /** Answers its own routes, `/auth/<vendor>/*`; undefined for any other request. */

package/src/provisioning-identity.ts

@@ -0,0 +1,106 @@
+import { Compute } from "google-auth-library";
+import { enrollmentBroker } from "./identity-broker.ts";
+import type { IdentityAudit, IdentityEnrollments } from "./cloud-identity.ts";
+
+/** Fixed by the trusted provisioning issuer deployment, never by a request or company config. */
+export interface ProvisioningIdentity {
+  serviceAccount: string;
+  /** Google's immutable numeric uniqueId for the source service account. */
+  subject: string;
+  /** Exact WIF provider audience whose trust condition pins this subject. */
+  audience: string;
+}
+export interface ProvisioningIdToken {
+  idToken: string;
+  expiresAt: number;
+}
+
+const ACCOUNT = /^[a-z][a-z0-9-]+@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/;
+const AUDIENCE =
+  /^\/\/iam\.googleapis\.com\/projects\/[1-9][0-9]+\/locations\/global\/workloadIdentityPools\/[a-z][a-z0-9-]+\/providers\/[a-z][a-z0-9-]+$/;
+const SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const fail = () => new Error("Provisioning identity unavailable");
+
+function identityOf(identity: ProvisioningIdentity): ProvisioningIdentity {
+  if (
+    !ACCOUNT.test(identity.serviceAccount) ||
+    !/^[1-9][0-9]+$/.test(identity.subject) ||
+    !AUDIENCE.test(identity.audience)
+  )
+    throw fail();
+  return { serviceAccount: identity.serviceAccount, subject: identity.subject, audience: identity.audience };
+}
+
+// The issuer calls Google's authenticated HTTPS endpoint. Check its fixed claims and expiry;
+// signature verification of the returned Google token remains Google's STS responsibility.
+function tokenExpiry(idToken: string, identity: ProvisioningIdentity, now: number): number {
+  try {
+    if (typeof idToken !== "string" || idToken.length > 8192) throw fail();
+    const parts = idToken.split(".");
+    if (parts.length !== 3 || !parts.every((part) => /^[A-Za-z0-9_-]+$/.test(part))) throw fail();
+    const claims = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8"));
+    if (
+      claims.iss !== "https://accounts.google.com" ||
+      claims.sub !== identity.subject ||
+      claims.aud !== identity.audience ||
+      claims.email !== identity.serviceAccount ||
+      claims.email_verified !== true ||
+      !Number.isSafeInteger(claims.iat) ||
+      !Number.isSafeInteger(claims.exp) ||
+      claims.iat * 1000 > now + 30_000 ||
+      claims.exp <= claims.iat ||
+      claims.exp - claims.iat > 3600 ||
+      claims.exp * 1000 <= now + 60_000 ||
+      claims.exp * 1000 > now + 3_630_000
+    )
+      throw fail();
+    return claims.exp * 1000;
+  } catch {
+    throw fail();
+  }
+}
+
+/** Dedicated Cloud Run attached identity with getOpenIdToken on the fixed source account only. */
+export function attachedGoogleIdTokenIssuer(configuration: ProvisioningIdentity): () => Promise<ProvisioningIdToken> {
+  const identity = identityOf(configuration);
+  const auth = new Compute({ scopes: [SCOPE] });
+  return async () => {
+    try {
+      const response = await auth.request<{ token: string }>({
+        url: `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${identity.serviceAccount}:generateIdToken`,
+        method: "POST",
+        data: { audience: identity.audience, includeEmail: true },
+        timeout: 10_000,
+      });
+      const idToken = response.data.token;
+      return { idToken, expiresAt: tokenExpiry(idToken, identity, Date.now()) };
+    } catch {
+      throw fail();
+    }
+  };
+}
+
+/**
+ * GET /identity for a separate provisioning credential source. Deploy with its own enrollment
+ * reader and attached issuer, outside the runtime broker. OIDC tokens last up to one hour:
+ * revocation must remove federation/impersonation trust as well as stopping new issuance.
+ */
+export function provisioningIdentityBroker(options: {
+  identity: ProvisioningIdentity;
+  enrollments: IdentityEnrollments;
+  /** Trusted Google issuer. The request cannot select subject, audience or token lifetime. */
+  issue(): Promise<ProvisioningIdToken>;
+  audit(event: IdentityAudit): Promise<void>;
+}): (request: Request) => Promise<Response> {
+  const identity = identityOf(options.identity);
+  return enrollmentBroker({
+    path: "/identity",
+    method: "GET",
+    enrollments: options.enrollments,
+    accept: (enrollment) => enrollment.serviceAccount === identity.serviceAccount,
+    issue: () => options.issue(),
+    valid: (token, now) => token.expiresAt === tokenExpiry(token.idToken, identity, now),
+    body: (token) => ({ idToken: token.idToken, expiresAt: token.expiresAt }),
+    audit: options.audit,
+  });
+}