@k2b/cloud 0.6.0-rc.0

package/src/services/freeipa-config.ts

@@ -0,0 +1,179 @@
+import { X509Certificate } from "node:crypto";
+import { setFreeIpaTlsResolver } from "../server/services/freeipa/tls";
+import { coreSettings } from "./settings/api";
+
+const MAX_CA_CERT_BYTES = 256 * 1024;
+const PEM_CERTIFICATE_PATTERN = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+
+export type FreeIpaSyncGuard = {
+  maxUserChanges: number;
+  maxUserChangePercent: number;
+  maxGroupDeletions: number;
+  maxGroupDeletionPercent: number;
+};
+
+export type FreeIpaConfig = {
+  enabled: boolean;
+  configured: boolean;
+  /** Setting keys that are still empty. Empty when `configured` is true. */
+  missingSettings: string[];
+  url: string;
+  serviceUser: string;
+  servicePassword: string;
+  groupsAdmin: string[];
+  groupsBaseSync: string[];
+  groupsBaseIpaRealm: string[];
+  groupsExcluded: string[];
+  caCert: string;
+  allowInsecure: boolean;
+  syncGuard: FreeIpaSyncGuard;
+};
+
+const normalizeString = (value: unknown): string => (typeof value === "string" ? value.trim() : "");
+const normalizeNonNegativeNumber = (value: unknown, fallback: number): number => {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+};
+const normalizeNonNegativeInteger = (value: unknown, fallback: number): number => Math.floor(normalizeNonNegativeNumber(value, fallback));
+const normalizePercentage = (value: unknown, fallback: number): number => Math.min(100, normalizeNonNegativeNumber(value, fallback));
+
+export const validateFreeIpaCaCert = (value: unknown): { ok: true; value: string } | { ok: false; error: string } => {
+  if (typeof value !== "string") return { ok: false, error: "CA certificate must be PEM text" };
+  const normalized = value.trim();
+  if (!normalized) return { ok: true, value: "" };
+  if (new TextEncoder().encode(normalized).byteLength > MAX_CA_CERT_BYTES) {
+    return { ok: false, error: "CA certificate bundle must not exceed 256 KiB" };
+  }
+
+  const certificates = normalized.match(PEM_CERTIFICATE_PATTERN) ?? [];
+  const remainder = normalized.replace(PEM_CERTIFICATE_PATTERN, "").trim();
+  if (certificates.length === 0 || remainder.length > 0) {
+    return { ok: false, error: "Enter one or more complete PEM certificates" };
+  }
+
+  try {
+    for (const certificate of certificates) new X509Certificate(certificate);
+  } catch {
+    return { ok: false, error: "CA certificate contains invalid PEM data" };
+  }
+  return { ok: true, value: normalized };
+};
+
+export const resolveFreeIpaTlsOptions = (caCert: string, allowInsecure: boolean): Bun.TLSOptions => {
+  const certificate = validateFreeIpaCaCert(caCert);
+  if (!certificate.ok) throw new Error(`Invalid freeipa.ca_cert: ${certificate.error}`);
+  if (certificate.value) return { ca: certificate.value, rejectUnauthorized: true };
+  if (allowInsecure) return { rejectUnauthorized: false };
+  return { rejectUnauthorized: true };
+};
+
+/**
+ * `fallback` is only for groups that have a genuine FreeIPA-wide default.
+ *
+ * The scope groups deliberately have none: `base_sync` decides who gets a Cloud
+ * account at all and `base_ipa_realm` decides who is a full user rather than a
+ * guest, and both depend entirely on how the directory is organised. A guess
+ * either over-provisions every FreeIPA user or silently demotes everyone to
+ * guest, so an empty value has to make the config incomplete instead.
+ */
+const normalizeStringList = (value: unknown, fallback: string[] = []): string[] => {
+  if (!Array.isArray(value)) return fallback;
+  const normalized = value.map((entry) => (typeof entry === "string" ? entry.trim() : "")).filter(Boolean);
+  return normalized.length > 0 ? normalized : fallback;
+};
+
+/**
+ * Read the full FreeIPA config snapshot from settings (Redis cache-aside +
+ * Postgres fallback). Always returns within Redis-TTL fresh data — no hidden
+ * dependency on request-lifecycle middleware.
+ */
+export const getFreeIpaConfig = async (): Promise<FreeIpaConfig> => {
+  const [
+    rawUrl,
+    rawServiceUser,
+    rawServicePassword,
+    rawEnabled,
+    rawAdmin,
+    rawBaseSync,
+    rawBaseIpaRealm,
+    rawExcluded,
+    rawCaCert,
+    rawAllowInsecure,
+    rawMaxUserChanges,
+    rawMaxUserChangePercent,
+    rawMaxGroupDeletions,
+    rawMaxGroupDeletionPercent,
+  ] = await Promise.all([
+    coreSettings.get<string>("freeipa.url"),
+    coreSettings.get<string>("freeipa.service_user"),
+    coreSettings.get<string>("freeipa.service_password"),
+    coreSettings.get<boolean>("freeipa.enable"),
+    coreSettings.get<string[]>("freeipa.groups.admin"),
+    coreSettings.get<string[]>("freeipa.groups.base_sync"),
+    coreSettings.get<string[]>("freeipa.groups.base_ipa_realm"),
+    coreSettings.get<string[]>("freeipa.groups.excluded"),
+    coreSettings.get<string>("freeipa.ca_cert"),
+    coreSettings.get<boolean>("freeipa.allow_insecure"),
+    coreSettings.get<number>("freeipa.sync_guard.max_user_changes"),
+    coreSettings.get<number>("freeipa.sync_guard.max_user_change_percent"),
+    coreSettings.get<number>("freeipa.sync_guard.max_group_deletions"),
+    coreSettings.get<number>("freeipa.sync_guard.max_group_deletion_percent"),
+  ]);
+
+  const url = normalizeString(rawUrl);
+  const serviceUser = normalizeString(rawServiceUser);
+  const servicePassword = normalizeString(rawServicePassword);
+  const enabled = Boolean(rawEnabled);
+  const caCert = normalizeString(rawCaCert);
+  const caValidation = validateFreeIpaCaCert(caCert);
+
+  // "admins" and the excluded list are real FreeIPA defaults; the scope groups
+  // are not, so they stay empty and make the config incomplete.
+  const groupsAdmin = normalizeStringList(rawAdmin, ["admins"]);
+  const groupsBaseSync = normalizeStringList(rawBaseSync);
+  const groupsBaseIpaRealm = normalizeStringList(rawBaseIpaRealm);
+  const groupsExcluded = normalizeStringList(rawExcluded, ["editors", "trust admins", "admins"]);
+
+  const missingSettings = [
+    ...(url ? [] : ["freeipa.url"]),
+    ...(serviceUser ? [] : ["freeipa.service_user"]),
+    ...(servicePassword ? [] : ["freeipa.service_password"]),
+    ...(groupsBaseSync.length > 0 ? [] : ["freeipa.groups.base_sync"]),
+    ...(groupsBaseIpaRealm.length > 0 ? [] : ["freeipa.groups.base_ipa_realm"]),
+    ...(caValidation.ok ? [] : ["freeipa.ca_cert"]),
+  ];
+
+  return {
+    enabled,
+    configured: missingSettings.length === 0,
+    missingSettings,
+    url,
+    serviceUser,
+    servicePassword,
+    groupsAdmin,
+    groupsBaseSync,
+    groupsBaseIpaRealm,
+    groupsExcluded,
+    caCert,
+    allowInsecure: Boolean(rawAllowInsecure),
+    syncGuard: {
+      maxUserChanges: normalizeNonNegativeInteger(rawMaxUserChanges, 10),
+      maxUserChangePercent: normalizePercentage(rawMaxUserChangePercent, 20),
+      maxGroupDeletions: normalizeNonNegativeInteger(rawMaxGroupDeletions, 5),
+      maxGroupDeletionPercent: normalizePercentage(rawMaxGroupDeletionPercent, 20),
+    },
+  };
+};
+
+// ── TLS resolver wiring ──────────────────────────────────────────────────────
+// Register an async resolver at module load so the freeipa transport
+// (`server/services/freeipa/client.ts` + `session.ts`) can read TLS opts
+// without taking a hard dependency on settings (would create a layering cycle).
+//
+// Resolution order: ca_cert (proper, signed by your private CA) wins over
+// allow_insecure (lab/dev kill switch). Verification is explicit in every
+// secure mode so NODE_TLS_REJECT_UNAUTHORIZED cannot weaken this policy.
+setFreeIpaTlsResolver(async () => {
+  const config = await getFreeIpaConfig();
+  return resolveFreeIpaTlsOptions(config.caCert, config.allowInsecure);
+});

package/src/services/gateway.ts

@@ -0,0 +1,186 @@
+import { lazySync } from "../_internal/process-sync";
+import { logger } from "./logging";
+
+/** Written by the gateway router, read by gateway-ops: one owner, one declaration. */
+const GATEWAY_RESOURCE_OWNER = "cloud";
+const SNAPSHOT_TTL_MS = 30_000;
+const TOPIC_ID = "cloud-gateway-telemetry";
+const TOPIC_RETENTION_MS = 24 * 60 * 60 * 1000;
+/** Hard loss boundary for the 24h request-telemetry buffer (discard-old). */
+const TOPIC_RETENTION_BYTES = 1024 * 1024 * 1024;
+/** Whole envelope; events are a few hundred bytes with 200-char text bounds. */
+const TOPIC_PAYLOAD_BYTES = 16 * 1024;
+const TOPIC_TENANT = "default";
+const DROP_LOG_INTERVAL_MS = 30_000;
+
+const log = logger("gateway:telemetry");
+
+export type GatewayRouteWarning = {
+  appId: string;
+  prefix: string;
+  reason: string;
+  detail?: string;
+};
+
+export type GatewayRouteSnapshotInput = {
+  instanceId: string;
+  baseUrl: string;
+  startedAt: number;
+  routeHash: string;
+  routeWarnings: GatewayRouteWarning[];
+  table: {
+    version: number;
+    builtAt: number;
+    routeCount: number;
+    routes: Array<{ prefix: string; appId: string }>;
+  };
+  stats: {
+    totalRequests: number;
+    noRouteCount: number;
+    byApp: Map<string, { count: number; totalMs: number; errors: number }>;
+    byRoute: Map<string, { count: number; errors: number; lastSeen: number }>;
+  };
+};
+
+export type GatewayRouteSnapshot = {
+  instanceId: string;
+  baseUrl: string;
+  startedAt: number;
+  updatedAt: number;
+  tableVersion: number;
+  tableBuiltAt: number;
+  routeCount: number;
+  routeHash: string;
+  routeWarnings: GatewayRouteWarning[];
+  routes: Array<{ prefix: string; appId: string }>;
+  stats: {
+    totalRequests: number;
+    noRouteCount: number;
+    byApp: Array<{ appId: string; count: number; totalMs: number; errors: number }>;
+    byRoute: Array<{ prefix: string; count: number; errors: number; lastSeen: number }>;
+  };
+};
+
+/**
+ * Response header an app uses to tell the gateway which route template it
+ * matched (`/api/mail/mailboxes/:mailboxId`). Set by `middleware.runtime()`
+ * / `middleware.observability()`, consumed and stripped by the gateway proxy.
+ */
+export const ROUTE_TEMPLATE_HEADER = "X-Route-Template";
+
+export type GatewayTelemetryEvent = {
+  v: 1;
+  kind: "request";
+  appId: string;
+  routePrefix: string;
+  /**
+   * Matched route template, id segments collapsed and query string dropped.
+   * `null` when neither the app nor the gateway fallback could derive one —
+   * older rows predating this field read the same way.
+   */
+  pathTemplate: string | null;
+  method: string;
+  status: number;
+  durationMs: number;
+  errorKind: "upstream_unavailable" | "unmatched_route" | null;
+  occurredAt: string;
+};
+
+const snapshots = lazySync((sync) =>
+  sync.ephemeral<GatewayRouteSnapshot>({
+    id: "gateway-route-snapshots",
+    owner: GATEWAY_RESOURCE_OWNER,
+    ttlMs: SNAPSHOT_TTL_MS,
+    maxValueBytes: 128_000,
+  }),
+);
+
+export const buildGatewayRouteSnapshot = (input: GatewayRouteSnapshotInput): GatewayRouteSnapshot => ({
+  instanceId: input.instanceId,
+  baseUrl: input.baseUrl,
+  startedAt: input.startedAt,
+  updatedAt: Date.now(),
+  tableVersion: input.table.version,
+  tableBuiltAt: input.table.builtAt,
+  routeCount: input.table.routeCount,
+  routeHash: input.routeHash,
+  routeWarnings: input.routeWarnings,
+  routes: input.table.routes,
+  stats: {
+    totalRequests: input.stats.totalRequests,
+    noRouteCount: input.stats.noRouteCount,
+    byApp: [...input.stats.byApp.entries()].map(([appId, value]) => ({ appId, ...value })),
+    byRoute: [...input.stats.byRoute.entries()].map(([prefix, value]) => ({ prefix, ...value })),
+  },
+});
+
+export const publishGatewayRouteSnapshot = async (snapshot: GatewayRouteSnapshot): Promise<void> => {
+  await snapshots().upsert({ key: `instances/${snapshot.instanceId}`, value: snapshot });
+};
+
+export const removeGatewayRouteSnapshot = async (instanceId: string): Promise<void> => {
+  await snapshots().delete({ key: `instances/${instanceId}` });
+};
+
+export const listGatewayRouteSnapshots = async (): Promise<GatewayRouteSnapshot[]> => {
+  const snap = await snapshots().snapshot({ prefix: "instances/" });
+  return snap.entries.map((entry) => entry.value).sort((a, b) => a.instanceId.localeCompare(b.instanceId));
+};
+
+export const latestGatewayRouteSnapshot = async (): Promise<GatewayRouteSnapshot | null> => {
+  const all = await listGatewayRouteSnapshots();
+  return all.sort((a, b) => b.updatedAt - a.updatedAt)[0] ?? null;
+};
+
+export const gatewayTelemetryTopic = lazySync((sync) =>
+  sync.topic<GatewayTelemetryEvent>({
+    id: TOPIC_ID,
+    owner: GATEWAY_RESOURCE_OWNER,
+    retention: { maxAgeMs: TOPIC_RETENTION_MS, maxBytes: TOPIC_RETENTION_BYTES },
+    maxPayloadBytes: TOPIC_PAYLOAD_BYTES,
+  }),
+);
+
+export const GATEWAY_TELEMETRY_TENANT = TOPIC_TENANT;
+
+const normalizeMethod = (method: string): string => method.toUpperCase().slice(0, 16);
+const normalizeStatus = (status: number): number => (Number.isFinite(status) ? Math.max(0, Math.min(999, Math.round(status))) : 0);
+const normalizeDuration = (durationMs: number): number => (Number.isFinite(durationMs) ? Math.max(0, Math.round(durationMs)) : 0);
+const normalizeText = (value: string, fallback: string): string => {
+  const trimmed = value.trim();
+  return (trimmed.length ? trimmed : fallback).slice(0, 200);
+};
+
+export const publishRequestTelemetry = (event: Omit<GatewayTelemetryEvent, "v" | "kind" | "occurredAt">): void => {
+  const payload: GatewayTelemetryEvent = {
+    v: 1,
+    kind: "request",
+    appId: normalizeText(event.appId, "unknown"),
+    routePrefix: normalizeText(event.routePrefix, "(unknown)"),
+    pathTemplate: event.pathTemplate ? normalizeText(event.pathTemplate, "(unknown)") : null,
+    method: normalizeMethod(event.method),
+    status: normalizeStatus(event.status),
+    durationMs: normalizeDuration(event.durationMs),
+    errorKind: event.errorKind,
+    occurredAt: new Date().toISOString(),
+  };
+
+  void gatewayTelemetryTopic()
+    .publish({
+      tenantId: GATEWAY_TELEMETRY_TENANT,
+      orderingKey: payload.appId,
+      data: payload,
+    })
+    .catch((error) => {
+      const now = Date.now();
+      if (now - lastPublishErrorAt < DROP_LOG_INTERVAL_MS) return;
+      lastPublishErrorAt = now;
+      log.warn("Dropped gateway telemetry event", {
+        appId: payload.appId,
+        routePrefix: payload.routePrefix,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+};
+
+let lastPublishErrorAt = 0;

package/src/services/identity/constants.ts

@@ -0,0 +1,18 @@
+export const CLOUD_SESSION_JWKS_PATH = "/.well-known/cloud-session-jwks.json";
+export const CLOUD_INVOCATION_JWKS_PATH = "/.well-known/cloud-invocation-jwks.json";
+export const CLOUD_OAUTH_JWKS_PATH = "/.well-known/jwks.json";
+export const CLOUD_SESSION_TOKEN_TYPE = "cloud-session+jwt";
+export const CLOUD_SESSION_AUDIENCE = "cloud";
+export const CLOUD_INVOCATION_TOKEN_TYPE = "cloud-invocation+jwt";
+export const CLOUD_INVOCATION_PROTOCOL_VERSION = 1 as const;
+export const CLOUD_INVOCATION_TOKEN_TTL_SECONDS = 30;
+export const CLOUD_IDENTITY_ALGORITHM = "RS256";
+
+export const IDENTITY_CLOCK_TOLERANCE_SECONDS = 30;
+export const INVOCATION_CLOCK_TOLERANCE_SECONDS = 2;
+export const IDENTITY_JWKS_MAX_AGE_SECONDS = 5 * 60;
+export const IDENTITY_ACTIVATION_LEAD_MS = 10 * 60_000;
+export const IDENTITY_SIGNING_CACHE_MS = 60_000;
+export const IDENTITY_ROTATION_AGE_MS = 30 * 24 * 60 * 60_000;
+export const IDENTITY_ROLLOUT_MARGIN_MS = 10 * 60_000;
+export const IDENTITY_MAX_COMPACT_TOKEN_BYTES = 4 * 1024;

package/src/services/identity/index.ts

@@ -0,0 +1,52 @@
+export {
+  CLOUD_INVOCATION_JWKS_PATH,
+  CLOUD_INVOCATION_PROTOCOL_VERSION,
+  CLOUD_INVOCATION_TOKEN_TTL_SECONDS,
+  CLOUD_INVOCATION_TOKEN_TYPE,
+  CLOUD_SESSION_AUDIENCE,
+  CLOUD_SESSION_JWKS_PATH,
+  CLOUD_SESSION_TOKEN_TYPE,
+} from "./constants";
+export { type ResolvedInvocationAuthority, resolveInvocationAuthority } from "./invocation-actor";
+export { invocationAuthorityFromRequest } from "./invocation-authority";
+export { capabilityInvocationOperation, searchInvocationOperation, widgetInvocationOperation } from "./invocation-operations";
+export {
+  type CloudInvocationClaims,
+  clearInvocationVerifierCachesForTest,
+  type InvocationAuthority,
+  isInvocationJwtCandidate,
+  normalizeInvocationRequestId,
+  signInvocationToken,
+  verifyInvocationToken,
+} from "./invocation-token";
+export {
+  clearIdentityKeyCachesForTest,
+  getIdentitySigningKeyStatus,
+  type IdentitySigningKeyStatus,
+  initializeIdentityAuthority,
+  invalidateIdentitySignerCache,
+  listIdentityJwks,
+  type PreparedIdentitySigner,
+  prepareIdentitySigner,
+  revokeIdentitySigningKey,
+  rewrapIdentitySigningKeys,
+  runIdentityKeyMaintenance,
+  type SigningKeyPurpose,
+  startIdentityKeyMaintenance,
+  withActiveIdentitySigner,
+} from "./key-ring";
+export { identityMetrics } from "./metrics";
+export { createIdentityPublicRoutes } from "./routes";
+export {
+  type CloudSessionClaims,
+  clearSessionVerifierCachesForTest,
+  isSessionJwtCandidate,
+  signSessionToken,
+  verifySessionToken,
+} from "./session-token";
+export {
+  type AuthenticatedWorkload,
+  authenticateWorkloadCredential,
+  WORKLOAD_SCOPES,
+  type WorkloadScope,
+} from "./workload-auth";

package/src/services/identity/invocation-actor.ts

@@ -0,0 +1,120 @@
+import { sql } from "bun";
+import type { RequestActor } from "../../server/middleware/auth";
+import type { AccessSubject } from "../../server/services/access";
+import { isAccountCategoryAllowed } from "../account-category-policy";
+import { isAccountExpired } from "../account-model";
+import type { ServiceAccount } from "../service-accounts";
+import { buildProjectedUser, loadCurrentUser, userProjectionSql } from "../session/user";
+import type { CloudInvocationClaims } from "./invocation-token";
+import { getIdentityRuntimeConfig } from "./runtime-config";
+
+type ServiceAccountRow = Record<string, unknown> & {
+  service_account_id: string;
+  service_account_name: string;
+  service_account_kind: ServiceAccount["kind"];
+  service_account_status: ServiceAccount["status"];
+  delegated_user_id: string | null;
+  app_id: string | null;
+  resource_type: string | null;
+  resource_id: string | null;
+  service_account_created_by: string | null;
+  service_account_created_at: Date | string;
+};
+
+export type ResolvedInvocationAuthority = {
+  actor: RequestActor;
+  accessSubject: AccessSubject;
+  credentialKind: "invocation";
+  scopes: string[];
+};
+
+const provenance = (claims: CloudInvocationClaims): NonNullable<RequestActor["delegation"]> => ({
+  kind: "invocation",
+  callingAppId: claims.act.sub.slice("app:".length),
+  credentialKind: claims.credential_kind,
+  invocationId: claims.jti,
+  requestId: claims.request_id ?? null,
+  ...(claims.mandate_id
+    ? {
+        mandateId: claims.mandate_id,
+        mandateRevision: claims.mandate_revision,
+        workloadType: claims.workload_type,
+        workloadId: claims.workload_id,
+      }
+    : {}),
+});
+
+const mapServiceAccount = (row: ServiceAccountRow): ServiceAccount => ({
+  id: row.service_account_id,
+  name: row.service_account_name,
+  kind: row.service_account_kind,
+  status: row.service_account_status,
+  delegatedUserId: row.delegated_user_id,
+  appId: row.app_id,
+  resourceType: row.resource_type,
+  resourceId: row.resource_id,
+  createdBy: row.service_account_created_by,
+  createdAt: new Date(row.service_account_created_at).toISOString(),
+});
+
+export const resolveInvocationAuthority = async (
+  claims: CloudInvocationClaims,
+  query: typeof sql = sql,
+  groupsAdminOverride?: string[],
+): Promise<ResolvedInvocationAuthority | null> => {
+  const groupsAdmin = groupsAdminOverride ?? (await getIdentityRuntimeConfig()).groupsAdmin;
+  const delegation = provenance(claims);
+
+  if (claims.principal_type === "user") {
+    const user = await loadCurrentUser({ userId: claims.sub, groupsAdmin }, query);
+    if (!user || isAccountExpired(user.accountExpires)) return null;
+    if (!(await isAccountCategoryAllowed(user, query))) return null;
+    return {
+      actor: { kind: "user", user, delegation },
+      accessSubject: { type: "user", userId: user.id },
+      credentialKind: "invocation",
+      scopes: [...claims.scopes],
+    };
+  }
+
+  const rows = await query<ServiceAccountRow[]>`
+    SELECT
+      sa.id AS service_account_id,
+      sa.name AS service_account_name,
+      sa.kind AS service_account_kind,
+      sa.status AS service_account_status,
+      sa.delegated_user_id,
+      sa.app_id,
+      sa.resource_type,
+      sa.resource_id,
+      sa.created_by AS service_account_created_by,
+      sa.created_at AS service_account_created_at,
+      ${userProjectionSql(groupsAdmin)}
+    FROM auth.service_accounts sa
+    LEFT JOIN auth.users u ON u.id = sa.delegated_user_id
+    LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+    WHERE sa.id = ${claims.sub}::uuid
+      AND sa.status = 'active'
+  `;
+  const row = rows[0];
+  if (!row) return null;
+
+  const serviceAccount = mapServiceAccount(row);
+  const delegatedUser = serviceAccount.delegatedUserId ? buildProjectedUser(row) : null;
+  if (serviceAccount.kind === "user_delegated" && (!delegatedUser || isAccountExpired(delegatedUser.accountExpires))) return null;
+  if (delegatedUser && !(await isAccountCategoryAllowed(delegatedUser, query))) return null;
+
+  const actor: RequestActor = {
+    kind: "service_account",
+    serviceAccount,
+    delegatedUser,
+    scopes: [...claims.scopes],
+    credentialId: claims.credential_id ?? null,
+    credentialExpiresAt: new Date(claims.exp * 1_000).toISOString(),
+    delegation,
+  };
+  const accessSubject: AccessSubject = delegatedUser
+    ? { type: "user", userId: delegatedUser.id, delegatedByServiceAccountId: serviceAccount.id }
+    : { type: "service_account", serviceAccountId: serviceAccount.id };
+  return { actor, accessSubject, credentialKind: "invocation", scopes: [...claims.scopes] };
+};

package/src/services/identity/invocation-authority.ts

@@ -0,0 +1,53 @@
+import type { RequestAuthority } from "../../server/middleware/auth";
+import type { InvocationAuthority } from "./invocation-token";
+
+export const invocationAuthorityFromRequest = (authority: RequestAuthority): InvocationAuthority => {
+  if (authority.credentialKind === "invocation") {
+    throw new Error("A Cloud invocation cannot be exchanged for another invocation");
+  }
+
+  if (authority.actor.kind === "user") {
+    if (authority.accessSubject.type !== "user" || authority.accessSubject.userId !== authority.actor.user.id) {
+      throw new Error("User request authority is inconsistent");
+    }
+    if (authority.credentialKind === "api_key") throw new Error("An API key must act through a service account");
+    return {
+      sub: authority.actor.user.id,
+      principal_type: "user",
+      access_subject_type: "user",
+      access_subject_id: authority.actor.user.id,
+      credential_kind: authority.credentialKind,
+      scopes: [...new Set(authority.scopes)].sort(),
+    };
+  }
+
+  const actor = authority.actor;
+  if (actor.delegatedUser) {
+    if (authority.accessSubject.type !== "user" || authority.accessSubject.userId !== actor.delegatedUser.id) {
+      throw new Error("Delegated request authority is inconsistent");
+    }
+    return {
+      sub: actor.serviceAccount.id,
+      principal_type: "service_account",
+      access_subject_type: "user",
+      access_subject_id: actor.delegatedUser.id,
+      delegated_user_id: actor.delegatedUser.id,
+      credential_kind: authority.credentialKind,
+      ...(actor.credentialId ? { credential_id: actor.credentialId } : {}),
+      scopes: [...new Set(authority.scopes)].sort(),
+    };
+  }
+
+  if (authority.accessSubject.type !== "service_account" || authority.accessSubject.serviceAccountId !== actor.serviceAccount.id) {
+    throw new Error("Service-account request authority is inconsistent");
+  }
+  return {
+    sub: actor.serviceAccount.id,
+    principal_type: "service_account",
+    access_subject_type: "service_account",
+    access_subject_id: actor.serviceAccount.id,
+    credential_kind: authority.credentialKind,
+    ...(actor.credentialId ? { credential_id: actor.credentialId } : {}),
+    scopes: [...new Set(authority.scopes)].sort(),
+  };
+};

package/src/services/identity/invocation-operations.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+
+export const capabilityInvocationOperation = (kind: "queries" | "actions", capabilityId: string, review = false): string =>
+  kind === "queries"
+    ? `capability.query:${capabilityId}`
+    : review
+      ? `capability.action.review:${capabilityId}`
+      : `capability.action.run:${capabilityId}`;
+
+export const searchInvocationOperation = "search.query" as const;
+export const widgetInvocationOperation = (widgetId: string): string => `widget.read:${widgetId}`;
+
+/** Bind an administrative invocation to its exact target route and HTTP method. */
+export const syncInvocationOperation = (method: string, path: string): string =>
+  `sync.operation:${createHash("sha256").update(`${method.toUpperCase()}:${path}`).digest("hex")}`;