@k2b/cloud 0.46.0 → 0.48.0

package/src/services/app-domains.ts

@@ -0,0 +1,172 @@
+import { err, fail, ok, type Result } from "@k2b/stdlib";
+import type { SQL } from "bun";
+import { getApp } from "../_internal/registry";
+import { declaresPublicSurface, normalizeAppDomainHost } from "../contracts/app-domains";
+import type { User } from "../contracts/shared";
+import { sql } from "../runtime/clients";
+import { publicCloudOrigin } from "../shared/app-url";
+import { type AppDomainStatus, checkAppDomain } from "./app-domain-check";
+import { audit } from "./audit";
+import { get } from "./settings";
+
+export type AdminAppDomain = {
+  host: string;
+  redirectTo: string | null;
+  createdAt: string;
+  active: boolean;
+  status: AppDomainStatus | null;
+};
+type AdminActor = Pick<User, "id" | "uid" | "provider" | "roles">;
+type AppInput = { actor: AdminActor; appId: string };
+type DomainInput = AppInput & { host: string };
+type Row = { host: string; app_id: string; redirect_to: string | null; created_at: Date; status: AppDomainStatus | null };
+type Dependencies = { db?: SQL; getApp?: typeof getApp; cloudUrl?: () => string | Promise<string>; probe?: typeof checkAppDomain };
+const normalizeHost = (value: string) => (value.includes("\\") ? null : normalizeAppDomainHost(value));
+const invalid = (code: string, message: string) => fail({ ...err.badInput(message), code });
+const conflict = (code: string, message: string) => fail({ ...err.conflict("App domain"), code, message });
+const notFound = () => fail({ ...err.notFound("App domain"), code: "APP_DOMAIN_NOT_FOUND" });
+const authorized = (input: AppInput): Result<void> => {
+  if (!input.actor.roles.includes("admin")) return fail(err.forbidden("Administrator access required"));
+  if (!/^[a-z][a-z0-9-]{0,79}$/.test(input.appId)) return invalid("APP_DOMAIN_INVALID_APP", "Invalid app ID");
+  return ok();
+};
+const domain = (row: Row, active: boolean): AdminAppDomain => ({
+  host: row.host,
+  redirectTo: row.redirect_to,
+  createdAt: row.created_at.toISOString(),
+  active,
+  status: row.status,
+});
+
+/** All domain mutations share one transaction lock; the host primary key also enforces unique ownership. */
+export const createAppDomainService = (dependencies: Dependencies = {}) => {
+  const app = dependencies.getApp ?? getApp;
+  const database = () => dependencies.db ?? sql;
+  const active = async (appId: string) => {
+    const entry = await app(appId);
+    return entry !== null && declaresPublicSurface(entry);
+  };
+  const record = (db: SQL, input: DomainInput, action: string, redirectTo?: string | null) =>
+    audit.record(
+      {
+        action: `app_domain.${action}`,
+        outcome: "allowed",
+        actor: { userId: input.actor.id, uid: input.actor.uid, provider: input.actor.provider, roles: input.actor.roles },
+        target: { type: "app_domain", id: input.host, label: input.host },
+        metadata: { appId: input.appId, ...(redirectTo !== undefined ? { redirectTo } : {}) },
+      },
+      db,
+    );
+  const references = (db: SQL, appId: string, host: string) => db<{ host: string }[]>`
+    SELECT host FROM settings.app_domains WHERE app_id = ${appId} AND redirect_to = ${host} ORDER BY host`;
+  const validateRedirect = async (db: SQL, appId: string, host: string, target: string): Promise<Result<void>> => {
+    if (host === target) return invalid("APP_DOMAIN_REDIRECT_TARGET", "A domain cannot redirect to itself");
+    const refs = await references(db, appId, host);
+    if (refs.length) return conflict("APP_DOMAIN_REFERENCED", `Domains redirect to ${host}: ${refs.map((row) => row.host).join(", ")}`);
+    const [row] = await db<Row[]>`SELECT * FROM settings.app_domains WHERE host = ${target} AND app_id = ${appId}`;
+    if (!row || row.redirect_to)
+      return invalid("APP_DOMAIN_REDIRECT_TARGET", "Redirect target must be a domain of this app without a redirect");
+    return ok();
+  };
+
+  return {
+    async list(input: AppInput): Promise<Result<{ domains: AdminAppDomain[] }>> {
+      const permission = authorized(input);
+      if (!permission.ok) return permission;
+      const [rows, isActive] = await Promise.all([
+        database()<Row[]>`SELECT * FROM settings.app_domains WHERE app_id = ${input.appId} ORDER BY host`,
+        active(input.appId),
+      ]);
+      return ok({ domains: rows.map((row) => domain(row, isActive)) });
+    },
+    async add(input: DomainInput & { redirectTo?: string }): Promise<Result<AdminAppDomain>> {
+      const permission = authorized(input);
+      if (!permission.ok) return permission;
+      const host = normalizeHost(input.host);
+      if (!host) return invalid("APP_DOMAIN_INVALID_HOST", "Expected a DNS host name without a port, path or wildcard");
+      const cloudHost = normalizeAppDomainHost(
+        new URL(publicCloudOrigin(await (dependencies.cloudUrl ?? (() => get<string>("app.url")))())).hostname,
+      );
+      if (host === cloudHost) return invalid("APP_DOMAIN_CLOUD_HOST", "The Cloud host cannot be assigned to an app");
+      const isActive = await active(input.appId);
+      const redirectTo = input.redirectTo === undefined ? null : normalizeHost(input.redirectTo);
+      if (input.redirectTo !== undefined && !redirectTo) return invalid("APP_DOMAIN_INVALID_HOST", "Invalid redirect host");
+      return database().begin(async (db) => {
+        await db`SELECT pg_advisory_xact_lock(hashtextextended('core.app-domains', 0))`;
+        const [known] = await db<{ app_id: string }[]>`SELECT app_id FROM platform.application_packages WHERE app_id = ${input.appId}`;
+        if (!known) return invalid("APP_DOMAIN_UNKNOWN_APP", "Unknown app ID; the app must have registered its package at least once");
+        const existing = await db`SELECT host FROM settings.app_domains WHERE host = ${host}`;
+        if (existing.length) return conflict("APP_DOMAIN_ASSIGNED", `Domain ${host} is already assigned`);
+        if (redirectTo) {
+          const valid = await validateRedirect(db, input.appId, host, redirectTo);
+          if (!valid.ok) return valid;
+        }
+        const [row] = await db<Row[]>`INSERT INTO settings.app_domains(host, app_id, redirect_to)
+          VALUES (${host}, ${input.appId}, ${redirectTo}) ON CONFLICT (host) DO NOTHING RETURNING *`;
+        if (!row) return conflict("APP_DOMAIN_ASSIGNED", `Domain ${host} is already assigned`);
+        await record(db, { ...input, host }, "add", redirectTo);
+        return ok(domain(row, isActive));
+      });
+    },
+    async set(input: DomainInput & { redirectTo: string | null }): Promise<Result<AdminAppDomain>> {
+      const permission = authorized(input);
+      if (!permission.ok) return permission;
+      const host = normalizeHost(input.host);
+      if (!host) return invalid("APP_DOMAIN_INVALID_HOST", "Invalid domain host");
+      const redirectTo = input.redirectTo === null ? null : normalizeHost(input.redirectTo);
+      if (input.redirectTo !== null && !redirectTo) return invalid("APP_DOMAIN_INVALID_HOST", "Invalid redirect host");
+      const isActive = await active(input.appId);
+      return database().begin(async (db) => {
+        await db`SELECT pg_advisory_xact_lock(hashtextextended('core.app-domains', 0))`;
+        const [existing] = await db<Row[]>`SELECT * FROM settings.app_domains WHERE host = ${host} AND app_id = ${input.appId}`;
+        if (!existing) return notFound();
+        if (redirectTo) {
+          const valid = await validateRedirect(db, input.appId, host, redirectTo);
+          if (!valid.ok) return valid;
+        }
+        const [row] = await db<
+          Row[]
+        >`UPDATE settings.app_domains SET redirect_to = ${redirectTo} WHERE host = ${host} AND app_id = ${input.appId} RETURNING *`;
+        if (!row) return notFound();
+        await record(db, { ...input, host }, "set", redirectTo);
+        return ok(domain(row, isActive));
+      });
+    },
+    async remove(input: DomainInput): Promise<Result<{ deleted: true }>> {
+      const permission = authorized(input);
+      if (!permission.ok) return permission;
+      const host = normalizeHost(input.host);
+      if (!host) return invalid("APP_DOMAIN_INVALID_HOST", "Invalid domain host");
+      return database().begin(async (db) => {
+        await db`SELECT pg_advisory_xact_lock(hashtextextended('core.app-domains', 0))`;
+        const refs = await references(db, input.appId, host);
+        if (refs.length) return conflict("APP_DOMAIN_REFERENCED", `Domains redirect to ${host}: ${refs.map((row) => row.host).join(", ")}`);
+        const rows = await db`DELETE FROM settings.app_domains WHERE host = ${host} AND app_id = ${input.appId} RETURNING host`;
+        if (!rows.length) return notFound();
+        await record(db, { ...input, host }, "remove");
+        return ok({ deleted: true as const });
+      });
+    },
+    async check(input: DomainInput): Promise<Result<{ status: AppDomainStatus | null }>> {
+      const permission = authorized(input);
+      if (!permission.ok) return permission;
+      const host = normalizeHost(input.host);
+      if (!host) return invalid("APP_DOMAIN_INVALID_HOST", "Invalid domain host");
+      const db = database();
+      const [claimed] = await db<{ check_started_at: string }[]>`UPDATE settings.app_domains SET check_started_at = now()
+        WHERE host = ${host} AND app_id = ${input.appId} AND (check_started_at IS NULL OR check_started_at <= now() - interval '60 seconds')
+        RETURNING check_started_at::text`;
+      if (!claimed) {
+        const [row] = await db<Row[]>`SELECT * FROM settings.app_domains WHERE host = ${host} AND app_id = ${input.appId}`;
+        return row ? ok({ status: row.status }) : notFound();
+      }
+      const status = await (dependencies.probe ?? checkAppDomain)(host);
+      // A removed/reassigned domain must never inherit an earlier owner's in-flight result.
+      await db`UPDATE settings.app_domains SET status = (${JSON.stringify(status)}::text)::jsonb
+        WHERE host = ${host} AND app_id = ${input.appId} AND check_started_at = ${claimed.check_started_at}::timestamptz`;
+      return ok({ status });
+    },
+  };
+};
+
+export const appDomains = createAppDomainService();

package/src/services/app-keys.ts

@@ -0,0 +1,301 @@
+import { err, fail, ok, type Result } from "@k2b/stdlib";
+import { type SQL, sql } from "bun";
+import { appKeyFingerprint, validateAppKeyAppId } from "../app-key";
+import type { User } from "../contracts/shared";
+import { audit } from "./audit";
+import { serviceAccounts } from "./service-accounts";
+
+type AdminActor = Pick<User, "id" | "uid" | "provider" | "roles">;
+export type AppKeyMetadata = {
+  keyId: string;
+  appId: string;
+  serviceAccountId: string;
+  kind: "app_key";
+  name: string;
+  publicKey: string;
+  fingerprint: string;
+  status: "active" | "expired" | "revoked";
+  accountStatus: "active" | "disabled";
+  createdAt: string;
+  createdBy: string | null;
+  expiresAt: string | null;
+  revokedAt: string | null;
+  revokedBy: string | null;
+  lastUsedAt: string | null;
+};
+type Row = {
+  id: string;
+  app_id: string;
+  service_account_id: string;
+  name: string;
+  public_key: string;
+  fingerprint: string;
+  key_status: AppKeyMetadata["status"];
+  account_status: AppKeyMetadata["accountStatus"];
+  created_at: Date;
+  created_by: string | null;
+  expires_at: Date | null;
+  revoked_at: Date | null;
+  revoked_by: string | null;
+  last_used_at: Date | null;
+};
+const map = (row: Row): AppKeyMetadata => ({
+  keyId: row.id,
+  appId: row.app_id,
+  serviceAccountId: row.service_account_id,
+  kind: "app_key",
+  name: row.name,
+  publicKey: row.public_key,
+  fingerprint: row.fingerprint,
+  status: row.key_status,
+  accountStatus: row.account_status,
+  createdAt: row.created_at.toISOString(),
+  createdBy: row.created_by,
+  expiresAt: row.expires_at?.toISOString() ?? null,
+  revokedAt: row.revoked_at?.toISOString() ?? null,
+  revokedBy: row.revoked_by,
+  lastUsedAt: row.last_used_at?.toISOString() ?? null,
+});
+const columns = `c.*, sa.app_id, sa.status AS account_status,
+  CASE WHEN c.status = 'revoked' THEN 'revoked' WHEN c.expires_at <= now() THEN 'expired' ELSE 'active' END AS key_status`;
+const actorForAudit = (actor: AdminActor) => ({ userId: actor.id, uid: actor.uid, provider: actor.provider, roles: actor.roles });
+const validateAdmin = (actor: AdminActor, appId?: string): Result<void> => {
+  if (!actor.roles.includes("admin")) return fail(err.forbidden("Administrator access required"));
+  if (appId !== undefined) {
+    try {
+      validateAppKeyAppId(appId);
+    } catch {
+      return fail(err.badInput("Invalid or reserved app ID"));
+    }
+  }
+  return ok();
+};
+const pageParams = (params: { page?: number; perPage?: number }) => ({
+  page: Math.max(1, Math.trunc(params.page ?? 1)),
+  perPage: Math.min(500, Math.max(1, Math.trunc(params.perPage ?? 100))),
+});
+
+/** Durable DB identity, initialized transactionally by Core's migration; never cached or read from env. */
+export const getInstallationId = async (db: SQL = sql): Promise<string> => {
+  const [row] = await db<{ id: string }[]>`SELECT id FROM auth.installation WHERE singleton = true`;
+  if (!row) throw new Error("Core installation identity is not initialized; run Core migrations");
+  return row.id;
+};
+
+export const registerAppKey = async (params: {
+  actor: AdminActor;
+  appId: string;
+  publicKey: string;
+  name?: string;
+  expiresAt?: string;
+}): Promise<
+  Result<{
+    keyId: string;
+    installationId: string;
+    fingerprint: string;
+    status: AppKeyMetadata["status"];
+    accountStatus: AppKeyMetadata["accountStatus"];
+  }>
+> => {
+  const valid = validateAdmin(params.actor, params.appId);
+  if (!valid.ok) return valid;
+  const name = params.name?.trim() ?? "App key";
+  if (!name || name.length > 120) return fail(err.badInput("Key name must contain 1 to 120 characters"));
+  let fingerprint: string;
+  try {
+    fingerprint = await appKeyFingerprint(params.publicKey);
+  } catch {
+    return fail(err.badInput("Invalid Ed25519 public key: expected a canonical 32-byte base64url point"));
+  }
+  const expiresAt = params.expiresAt ? new Date(params.expiresAt) : null;
+  if (expiresAt && !Number.isFinite(expiresAt.getTime())) return fail(err.badInput("Expiry must be in the future"));
+  const account = await serviceAccounts.getOrCreateResourceBound({
+    name: `${params.appId} workload`,
+    appId: params.appId,
+    resourceType: "cloud.app",
+    resourceId: params.appId,
+    createdBy: params.actor.id,
+  });
+  if (!account.ok) return account;
+  return sql.begin(async (db) => {
+    // Resource-bound accounts carry no unique index, so concurrent first enrollments can
+    // create more than one account for an app. One transaction lock per app serializes
+    // enrollment across Core replicas; keys count and land on the oldest account, the
+    // same one getByResource returns.
+    await db`SELECT pg_advisory_xact_lock(hashtextextended(${`app_key:${params.appId}`}, 0))`;
+    const [locked] = await db<{ id: string; status: AppKeyMetadata["accountStatus"] }[]>`
+      SELECT id, status FROM auth.service_accounts
+      WHERE kind = 'resource_bound' AND app_id = ${params.appId} AND resource_type = 'cloud.app' AND resource_id = ${params.appId}
+      ORDER BY created_at ASC
+      LIMIT 1
+      FOR UPDATE`;
+    if (!locked) return fail(err.notFound("Service account"));
+    const accountId = locked.id;
+    const accountStatus = locked.status;
+    const installationId = await getInstallationId(db);
+    const [existing] = await db<{ id: string; fingerprint: string; status: AppKeyMetadata["status"] }[]>`
+      SELECT c.id, c.fingerprint,
+        CASE WHEN c.status = 'revoked' THEN 'revoked' WHEN c.expires_at <= now() THEN 'expired' ELSE 'active' END AS status
+      FROM auth.service_account_credentials c
+      JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+      WHERE sa.kind = 'resource_bound' AND sa.app_id = ${params.appId} AND sa.resource_type = 'cloud.app'
+        AND sa.resource_id = ${params.appId} AND c.kind = 'app_key' AND c.public_key = ${params.publicKey}
+    `;
+    // Revoked/expired keys remain idempotent and are never reactivated.
+    if (existing)
+      return ok({ keyId: existing.id, installationId, fingerprint: existing.fingerprint, status: existing.status, accountStatus });
+    if (accountStatus !== "active")
+      return fail({
+        ...err.conflict("Service account"),
+        message: "The app service account is disabled; enable it before enrolling a new key",
+      });
+    if (expiresAt && expiresAt.getTime() <= Date.now()) return fail(err.badInput("Expiry must be in the future"));
+    const [count] = await db<{ active: number }[]>`
+      SELECT count(*)::int AS active FROM auth.service_account_credentials c
+      JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+      WHERE sa.kind = 'resource_bound' AND sa.app_id = ${params.appId} AND sa.resource_type = 'cloud.app'
+        AND sa.resource_id = ${params.appId} AND c.kind = 'app_key' AND c.status = 'active'
+        AND (c.expires_at IS NULL OR c.expires_at > now())
+    `;
+    if ((count?.active ?? 0) >= 2)
+      return fail({ ...err.conflict("App key"), message: "An app can have at most two active keys; revoke an old key first" });
+    const [row] = await db<{ id: string }[]>`
+      INSERT INTO auth.service_account_credentials
+        (service_account_id, name, kind, public_key, fingerprint, created_by, expires_at)
+      VALUES (${accountId}::uuid, ${name}, 'app_key', ${params.publicKey}, ${fingerprint}, ${params.actor.id}::uuid, ${expiresAt})
+      RETURNING id
+    `;
+    if (!row) throw new Error("App key registration returned no key");
+    await audit.record(
+      {
+        action: "app_key.create",
+        outcome: "allowed",
+        actor: actorForAudit(params.actor),
+        target: { type: "service_account_credential", id: row.id, label: name },
+        metadata: { appId: params.appId, serviceAccountId: accountId, fingerprint },
+      },
+      db,
+    );
+    return ok({ keyId: row.id, installationId, fingerprint, status: "active" as const, accountStatus });
+  });
+};
+
+export const listAppKeys = async (params: { actor: AdminActor; appId: string; page?: number; perPage?: number }) => {
+  const valid = validateAdmin(params.actor, params.appId);
+  if (!valid.ok) return valid;
+  const { page, perPage } = pageParams(params);
+  const rows = await sql<(Row & { total: number })[]>`
+    SELECT ${sql.unsafe(columns)}, count(*) OVER()::int AS total FROM auth.service_account_credentials c
+    JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+    WHERE c.kind = 'app_key' AND sa.kind = 'resource_bound' AND sa.app_id = ${params.appId}
+      AND sa.resource_type = 'cloud.app' AND sa.resource_id = ${params.appId}
+    ORDER BY c.created_at DESC, c.id DESC LIMIT ${perPage} OFFSET ${(page - 1) * perPage}
+  `;
+  let total = rows[0]?.total ?? 0;
+  if (rows.length === 0 && page > 1) {
+    const [count] = await sql<{ total: number }[]>`
+      SELECT count(*)::int AS total FROM auth.service_account_credentials c
+      JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+      WHERE c.kind = 'app_key' AND sa.kind = 'resource_bound' AND sa.app_id = ${params.appId}
+        AND sa.resource_type = 'cloud.app' AND sa.resource_id = ${params.appId}
+    `;
+    total = count?.total ?? 0;
+  }
+  return ok({ installationId: await getInstallationId(), items: rows.map(map), page, perPage, total, hasNext: page * perPage < total });
+};
+
+export const listAppsWithKeys = async (params: { actor: AdminActor; page?: number; perPage?: number }) => {
+  const valid = validateAdmin(params.actor);
+  if (!valid.ok) return valid;
+  const { page, perPage } = pageParams(params);
+  const rows = await sql<
+    { appId: string; accountStatus: AppKeyMetadata["accountStatus"]; totalKeys: number; activeKeys: number; total: number }[]
+  >`
+    SELECT sa.app_id AS "appId", sa.status AS "accountStatus", count(*)::int AS "totalKeys",
+      count(*) FILTER (WHERE c.status = 'active' AND (c.expires_at IS NULL OR c.expires_at > now()))::int AS "activeKeys",
+      count(*) OVER()::int AS total
+    FROM auth.service_account_credentials c JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+    WHERE c.kind = 'app_key' AND sa.kind = 'resource_bound' AND sa.resource_type = 'cloud.app' AND sa.resource_id = sa.app_id
+    GROUP BY sa.app_id, sa.status ORDER BY sa.app_id LIMIT ${perPage} OFFSET ${(page - 1) * perPage}
+  `;
+  let total = rows[0]?.total ?? 0;
+  if (rows.length === 0 && page > 1) {
+    const [count] = await sql<{ total: number }[]>`
+      SELECT count(DISTINCT sa.app_id)::int AS total FROM auth.service_account_credentials c
+      JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+      WHERE c.kind = 'app_key' AND sa.kind = 'resource_bound' AND sa.resource_type = 'cloud.app' AND sa.resource_id = sa.app_id
+    `;
+    total = count?.total ?? 0;
+  }
+  return ok({
+    installationId: await getInstallationId(),
+    items: rows.map(({ total: _, ...row }) => row),
+    page,
+    perPage,
+    total,
+    hasNext: page * perPage < total,
+  });
+};
+
+export const revokeAppKey = async (params: { actor: AdminActor; appId: string; keyId: string }): Promise<Result<void>> => {
+  const valid = validateAdmin(params.actor, params.appId);
+  if (!valid.ok) return valid;
+  if (params.keyId.length !== 36 || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(params.keyId))
+    return fail(err.notFound("App key"));
+  return sql.begin(async (db) => {
+    const [key] = await db<{ id: string; service_account_id: string; status: string; name: string; fingerprint: string }[]>`
+      SELECT c.id, c.service_account_id, c.status, c.name, c.fingerprint FROM auth.service_account_credentials c
+      JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+      WHERE c.id = ${params.keyId}::uuid AND c.kind = 'app_key' AND sa.app_id = ${params.appId}
+        AND sa.kind = 'resource_bound' AND sa.resource_type = 'cloud.app' AND sa.resource_id = ${params.appId}
+      FOR UPDATE OF sa, c
+    `;
+    if (!key) return fail(err.notFound("App key"));
+    if (key.status === "revoked") return ok();
+    await db`UPDATE auth.service_account_credentials SET status = 'revoked', revoked_at = now(), revoked_by = ${params.actor.id}::uuid
+      WHERE id = ${key.id}::uuid`;
+    await audit.record(
+      {
+        action: "app_key.revoke",
+        outcome: "allowed",
+        actor: actorForAudit(params.actor),
+        target: { type: "service_account_credential", id: key.id, label: key.name },
+        metadata: { appId: params.appId, serviceAccountId: key.service_account_id, fingerprint: key.fingerprint },
+      },
+      db,
+    );
+    return ok();
+  });
+};
+
+/** Bootstrap and signed workload requests must query this directly; no cache. */
+export const getActiveAppKey = async (
+  params: { appId: string; keyId: string },
+  db: SQL = sql,
+): Promise<(AppKeyMetadata & { connectionsAllowed: boolean }) | null> => {
+  try {
+    validateAppKeyAppId(params.appId);
+  } catch {
+    return null;
+  }
+  if (params.keyId.length !== 36 || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(params.keyId))
+    return null;
+  const [row] = await db<(Row & { connections_allowed: boolean })[]>`
+    SELECT ${db.unsafe(columns)} FROM auth.service_account_credentials c
+    JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+    WHERE c.kind = 'app_key' AND c.id = ${params.keyId}::uuid AND c.status = 'active'
+      AND (c.expires_at IS NULL OR c.expires_at > now()) AND sa.status = 'active'
+      AND sa.kind = 'resource_bound' AND sa.app_id = ${params.appId} AND sa.resource_type = 'cloud.app' AND sa.resource_id = ${params.appId}
+  `;
+  return row ? { ...map(row), connectionsAllowed: row.connections_allowed } : null;
+};
+
+/** Call only after successful authentication; a late touch cannot revive a key. */
+export const touchAppKey = async (params: { appId: string; keyId: string }, db: SQL = sql): Promise<void> => {
+  const key = await getActiveAppKey(params, db);
+  if (!key) return;
+  await db`UPDATE auth.service_account_credentials SET last_used_at = now() WHERE id = ${key.keyId}::uuid AND status = 'active'
+    AND (expires_at IS NULL OR expires_at > now())`;
+};
+
+export const appKeys = { register: registerAppKey, list: listAppKeys, listApps: listAppsWithKeys, revoke: revokeAppKey };

package/src/services/downstream-budget.ts

@@ -1,4 +1,4 @@
-import { env } from "../config/env";
+import { connections } from "../runtime/connections";
 import { logger } from "./logging";
 import { requestCacheRedis } from "./request-cache-redis";
 
@@ -31,7 +31,7 @@ export const createDownstreamBudget = (options: { client?: () => Promise<Client>
   async acquire(input: { downstream: Downstream; timeoutMs: number; signal: AbortSignal }): Promise<() => void> {
     input.signal.throwIfAborted();
     if (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0) throw new RangeError("Downstream timeout must be positive and finite");
-    const namespace = options.namespace?.() ?? env.SYNC_NAMESPACE;
+    const namespace = options.namespace?.() ?? connections().nats.namespace;
     if (!namespace.trim()) throw new Error("SYNC_NAMESPACE is required for shared downstream budgets");
     const key = `cloud:downstream:{${namespace}}:${input.downstream}`;
     const token = crypto.randomUUID();

package/src/services/gateway.ts

@@ -1,4 +1,5 @@
 import { lazySync } from "../_internal/process-sync";
+import type { EnvSettingStatus } from "../contracts/settings-env";
 import { logger } from "./logging";
 
 /** Written by the gateway router, read by gateway-ops: one owner, one declaration. */
@@ -24,6 +25,8 @@ export type GatewayRouteWarning = {
 
 export type GatewayRouteSnapshotInput = {
   instanceId: string;
+  /** Sanitized migration diagnostics; omitted by pre-migration gateways. */
+  envSettings?: EnvSettingStatus[];
   baseUrl: string;
   startedAt: number;
   routeHash: string;
@@ -44,6 +47,8 @@ export type GatewayRouteSnapshotInput = {
 
 export type GatewayRouteSnapshot = {
   instanceId: string;
+  /** Sanitized migration diagnostics; omitted by pre-migration gateways. */
+  envSettings?: EnvSettingStatus[];
   baseUrl: string;
   startedAt: number;
   updatedAt: number;
@@ -97,6 +102,7 @@ const snapshots = lazySync((sync) =>
 
 export const buildGatewayRouteSnapshot = (input: GatewayRouteSnapshotInput): GatewayRouteSnapshot => ({
   instanceId: input.instanceId,
+  ...(input.envSettings ? { envSettings: input.envSettings } : {}),
   baseUrl: input.baseUrl,
   startedAt: input.startedAt,
   updatedAt: Date.now(),

package/src/services/identity/index.ts

@@ -1,3 +1,4 @@
+export { getAppWorkloadCredential } from "../../_internal/workload-credential";
 export {
   CLOUD_INVOCATION_JWKS_PATH,
   CLOUD_INVOCATION_PROTOCOL_VERSION,
@@ -37,6 +38,7 @@ export {
 } from "./key-ring";
 export { identityMetrics } from "./metrics";
 export { isNestedSourceCurrent, type NestedInvocationLease, nestedInvocationLeases } from "./nested-invocation";
+export { type ResourceReader, resolveResourceReaders } from "./resource-readers";
 export { createIdentityPublicRoutes } from "./routes";
 export {
   type CloudSessionClaims,
@@ -51,3 +53,4 @@ export {
   WORKLOAD_SCOPES,
   type WorkloadScope,
 } from "./workload-auth";
+export { startAppWorkloadBroker } from "./workload-runtime";

package/src/services/identity/resource-readers.ts

@@ -0,0 +1,80 @@
+import { sql } from "bun";
+import { z } from "zod";
+import { type ResourcePrincipal, ResourcePrincipalSchema } from "../../contracts/capabilities";
+import type { AccessSubject } from "../../contracts/shared";
+import { decodeAccountCategoryEnabled } from "../account-category-policy";
+import { toPgUuidArray } from "../postgres";
+import type { ServiceAccount } from "../service-accounts";
+
+/** Account authority only: no session, credential scopes, or content authority. */
+export type ResourceReader = {
+  principal: ResourcePrincipal;
+  subject: AccessSubject;
+  binding: Pick<ServiceAccount, "appId" | "resourceType" | "resourceId"> | null;
+};
+
+type UserRow = { id: string; category_enabled: string | null };
+type AccountRow = {
+  id: string;
+  kind: ServiceAccount["kind"];
+  delegated_user_id: string | null;
+  app_id: string | null;
+  resource_type: string | null;
+  resource_id: string | null;
+};
+
+/** Resolve at most 500 current accounts, including delegated users and account-category policy.
+ * Grants and resource bindings remain the resource provider's responsibility.
+ */
+export const resolveResourceReaders = async (principals: readonly ResourcePrincipal[]): Promise<ResourceReader[]> => {
+  const input = z.array(ResourcePrincipalSchema).max(500).parse(principals);
+  if (!input.length) return [];
+  const userIds = input.flatMap((principal) => (principal.type === "user" ? [principal.userId] : []));
+  const accountIds = input.flatMap((principal) => (principal.type === "service_account" ? [principal.serviceAccountId] : []));
+  const accounts = await sql<AccountRow[]>`
+    SELECT id, kind, delegated_user_id, app_id, resource_type, resource_id
+    FROM auth.service_accounts WHERE id = ANY(${toPgUuidArray(accountIds)}::uuid[]) AND status = 'active'
+  `;
+  const users = await sql<UserRow[]>`
+    SELECT u.id, category.value AS category_enabled FROM auth.users u
+    LEFT JOIN settings.entries category ON category.key = 'user.category.' ||
+      CASE WHEN u.provider = 'ipa' THEN 'freeipa' WHEN u.profile = 'guest' THEN 'guest' ELSE 'login' END || '.enabled'
+    WHERE u.id = ANY(${toPgUuidArray([...userIds, ...accounts.flatMap((account) => (account.delegated_user_id ? [account.delegated_user_id] : []))])}::uuid[])
+      AND (u.account_expires IS NULL OR u.account_expires > clock_timestamp())
+  `;
+  const enabled = new Map<string | null, boolean>();
+  const allowedUsers = new Set<string>();
+  for (const user of users) {
+    if (!enabled.has(user.category_enabled)) enabled.set(user.category_enabled, await decodeAccountCategoryEnabled(user.category_enabled));
+    if (enabled.get(user.category_enabled)) allowedUsers.add(user.id);
+  }
+  const accountsById = new Map(accounts.map((account) => [account.id, account]));
+  return input.flatMap((principal): ResourceReader[] => {
+    if (principal.type === "user") {
+      const userId = principal.userId.toLowerCase();
+      return allowedUsers.has(userId) ? [{ principal, subject: { type: "user", userId }, binding: null }] : [];
+    }
+    const account = accountsById.get(principal.serviceAccountId.toLowerCase());
+    if (!account) return [];
+    if (account.kind === "user_delegated")
+      return account.delegated_user_id && allowedUsers.has(account.delegated_user_id)
+        ? [
+            {
+              principal,
+              subject: { type: "user", userId: account.delegated_user_id, delegatedByServiceAccountId: account.id },
+              binding: null,
+            },
+          ]
+        : [];
+    return [
+      {
+        principal,
+        subject: { type: "service_account", serviceAccountId: account.id },
+        binding:
+          account.kind === "resource_bound"
+            ? { appId: account.app_id, resourceType: account.resource_type, resourceId: account.resource_id }
+            : null,
+      },
+    ];
+  });
+};

package/src/services/identity/runtime-config.ts

@@ -52,20 +52,28 @@ export const readIdentityGroupsAdmin = async (db: SQL): Promise<readonly string[
   return Object.freeze(normalizeGroups(groups));
 };
 
-const resolveCoreJwksUrl = (issuer: string, path: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL => {
+const resolveCoreJwksUrl = (
+  issuer: string,
+  path: string,
+  transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN ?? env.CLOUD_CORE_INTERNAL_ORIGIN,
+): URL => {
   if (!transportOrigin) return new URL(path, issuer);
   const origin = new URL(transportOrigin);
   if (origin.protocol !== "http:" && origin.protocol !== "https:") {
-    throw new Error("CLOUD_IDENTITY_JWKS_ORIGIN must use http or https");
+    throw new Error("Core JWKS origin (CLOUD_CORE_INTERNAL_ORIGIN or legacy CLOUD_IDENTITY_JWKS_ORIGIN) must use http or https");
   }
   return new URL(path, origin);
 };
 
-export const resolveSessionJwksUrl = (issuer: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL =>
-  resolveCoreJwksUrl(issuer, CLOUD_SESSION_JWKS_PATH, transportOrigin);
+export const resolveSessionJwksUrl = (
+  issuer: string,
+  transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN ?? env.CLOUD_CORE_INTERNAL_ORIGIN,
+): URL => resolveCoreJwksUrl(issuer, CLOUD_SESSION_JWKS_PATH, transportOrigin);
 
-export const resolveInvocationJwksUrl = (issuer: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL =>
-  resolveCoreJwksUrl(issuer, CLOUD_INVOCATION_JWKS_PATH, transportOrigin);
+export const resolveInvocationJwksUrl = (
+  issuer: string,
+  transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN ?? env.CLOUD_CORE_INTERNAL_ORIGIN,
+): URL => resolveCoreJwksUrl(issuer, CLOUD_INVOCATION_JWKS_PATH, transportOrigin);
 
 export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = env.CLOUD_OAUTH_JWKS_ORIGIN): URL => {
   if (!transportOrigin) return new URL(CLOUD_OAUTH_JWKS_PATH, issuer);