@k2b/cloud 0.46.0 → 0.47.0

package/src/contracts/settings-env.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const EnvSettingStatusSchema = z.object({
+  key: z.string(),
+  envVariable: z.string().nullable(),
+  storedValuePresent: z.boolean(),
+  envValuePresent: z.boolean(),
+  conflict: z.enum(["none", "differs", "unknown"]),
+  unreadableStoredValue: z.boolean(),
+  invalidEnvValue: z.boolean(),
+  needsAttention: z.boolean(),
+});
+export const EnvSettingsProcessSchema = z.object({
+  appId: z.string(),
+  instanceId: z.string().optional(),
+  sampledAt: z.number().optional(),
+  status: z.enum(["ok", "unavailable"]),
+  settings: z.array(EnvSettingStatusSchema),
+});
+export const EnvSettingsStatusSchema = z.object({ needsAttention: z.boolean(), processes: z.array(EnvSettingsProcessSchema) });
+export type EnvSettingStatus = z.infer<typeof EnvSettingStatusSchema>;

package/src/contracts/settings-types.ts

@@ -36,6 +36,12 @@ type CommonDef = {
   presentation?: AppSettingPresentation;
   envBootstrap?: EnvResolver;
   envFallback?: EnvResolver;
+  /** Environment name for migration diagnostics; values are never returned. */
+  envVariable?: string;
+  /** Discard these stored settings when this normalized value changes. */
+  resetOnChange?: readonly string[];
+  /** Additional server-side validation after kind normalization. */
+  validate?: (value: unknown) => string | undefined;
 };
 
 type StringLikeKind = "string" | "text" | "email" | "url" | "secret" | "image" | "cron" | "timezone" | "template";

package/src/index.ts

@@ -60,5 +60,14 @@ export type {
   NotificationSendInput,
 } from "./contracts/notification-types";
 export { notification } from "./contracts/notification-types";
+export { createRedis, createSql, redis, type SqlPoolOptions, sql } from "./runtime/clients";
+export {
+  type ConnectionSource,
+  connections,
+  type PlatformConnectionSources,
+  type PlatformConnections,
+  type PlatformConnectionValues,
+} from "./runtime/connections";
 export type { HelpDefinition, HelpDefinitionDocument } from "./server/help";
 export { defineHelp } from "./server/help";
+export { storage } from "./services/object-store";

package/src/runtime/clients.ts

@@ -0,0 +1,72 @@
+import { RedisClient, type RedisOptions, SQL } from "bun";
+import { postgresApplicationOptions } from "../_internal/postgres-application-name";
+import { connections, hasConnections } from "./connections";
+
+export type SqlPoolOptions = SQL.PostgresOrMySQLOptions;
+
+/** Only the pre-start placeholder is proxied; initialized clients are native Bun objects. */
+const notStarted = <T>(name: string): T => {
+  const fail = (): never => {
+    throw new Error(`${name} used before platform start`);
+  };
+  return new Proxy(fail, {
+    get: fail,
+    set: fail,
+    apply: fail,
+    construct: fail,
+    getPrototypeOf: fail,
+    defineProperty: fail,
+    deleteProperty: fail,
+    has: fail,
+    ownKeys: fail,
+    getOwnPropertyDescriptor: fail,
+    setPrototypeOf: fail,
+    isExtensible: fail,
+    preventExtensions: fail,
+  }) as T;
+};
+
+export let sql: SQL = notStarted("sql");
+export let redis: RedisClient = notStarted("redis");
+
+/** Own pool and lifecycle; defaults to the installation URL and application name. */
+export const createSql = (options: SqlPoolOptions = {}): SQL => {
+  const state = connections();
+  const url = options.url ?? state.database.url;
+  const connection = { ...postgresApplicationOptions(state.appId, url.toString()), ...options.connection };
+  return new SQL({
+    ...options,
+    url,
+    ...(Object.keys(connection).length ? { connection } : {}),
+  });
+};
+
+/** Own connection and lifecycle, using the installation's Valkey URL. */
+export const createRedis = (options?: RedisOptions): RedisClient => new RedisClient(connections().valkey.url, options);
+
+export const initializeClients = async (): Promise<void> => {
+  let database: SQL;
+  try {
+    database = createSql();
+  } catch {
+    throw new Error("Postgres client configuration is invalid; check DATABASE_URL and native SQL options");
+  }
+  try {
+    const valkey = createRedis();
+    sql = database;
+    redis = valkey;
+  } catch {
+    await database.close();
+    throw new Error("Valkey client configuration is invalid; check REDIS_URL and native Redis options");
+  }
+};
+
+/** Internal test-target teardown, before a fixture selects a different database. */
+export const closePlatformClients = async (): Promise<void> => {
+  if (hasConnections()) {
+    await sql.close();
+    redis.close();
+  }
+  sql = notStarted("sql");
+  redis = notStarted("redis");
+};

package/src/runtime/connections.ts

@@ -0,0 +1,37 @@
+/** Startup snapshot. Connection credentials never flow back into the process environment. */
+export type ConnectionSource = "env" | "core";
+export type PlatformConnectionValues = {
+  database: { url: string };
+  valkey: { url: string };
+  nats: {
+    servers: string[];
+    namespace: string;
+    replicas: 1 | 3 | 5;
+    ignoreClusterUpdates: boolean;
+    /** Mounted credentials and CA files are read once; these are contents, not paths. */
+    creds?: string;
+    ca?: string;
+  };
+  appSecret: { current: string; previous?: string; next?: string };
+};
+export type PlatformConnectionSources = {
+  [Group in keyof PlatformConnectionValues]: { [Key in keyof PlatformConnectionValues[Group]]: ConnectionSource };
+};
+export type PlatformConnections = PlatformConnectionValues & {
+  appId: string;
+  sources: PlatformConnectionSources;
+};
+
+let current: PlatformConnections | undefined;
+
+export const connections = (): PlatformConnections => {
+  if (!current)
+    throw new Error("connections() used before platform start; use @k2b/cloud/start, the Cloud build entry or development preload");
+  return current;
+};
+
+/** Internal startup binding; tests replace it only after closing their previous clients. */
+export const bindConnections = (value: PlatformConnections | undefined): void => {
+  current = value;
+};
+export const hasConnections = (): boolean => current !== undefined;

package/src/runtime/resolve-connections.ts

@@ -0,0 +1,91 @@
+import { readFileSync } from "node:fs";
+import { envSource } from "../config/define-env";
+import { env } from "../config/env";
+import type { ConnectionSource, PlatformConnections, PlatformConnectionValues } from "./connections";
+
+type EnvKey = keyof typeof env.$specs;
+const explicitlySet = (key: EnvKey): boolean => ["env", "alias", "file"].includes(envSource(env, key));
+
+/** URL diagnostics deliberately omit both the input and underlying parser errors. */
+const url = (key: string, value: string | undefined, bareHost = false): string => {
+  if (!value) throw new Error(`${key} is required for platform start`);
+  try {
+    const parsed = new URL(bareHost && !value.includes("://") ? `nats://${value}` : value);
+    if (bareHost && !parsed.hostname) throw new Error();
+  } catch {
+    throw new Error(`${key} must be a valid URL${bareHost ? " or host:port" : ""}`);
+  }
+  return value;
+};
+const contents = (key: "NATS_CREDS_FILE" | "NATS_TLS_CA_FILE"): string | undefined => {
+  const path = env[key];
+  if (!path) return undefined;
+  try {
+    const value = readFileSync(path, "utf8");
+    if (!value.trim()) throw new Error();
+    return value;
+  } catch {
+    throw new Error(`${key} must name a readable, non-empty file`);
+  }
+};
+
+/**
+ * Explicit environment values always win, including aliases, files and false.
+ * The Core bootstrap client supplies `core` in key mode; required values then
+ * never fall through to environment defaults. Optional values may use defaults.
+ */
+export const resolveConnections = ({ appId, core }: { appId: string; core?: PlatformConnectionValues }): PlatformConnections => {
+  const source = (key: EnvKey): ConnectionSource => (!core || explicitlySet(key) ? "env" : "core");
+  const choose = <T>(key: EnvKey, fromEnv: () => T, fromCore: T): T => (!core || explicitlySet(key) ? fromEnv() : fromCore);
+  // Keep value reads lazy: an absent env value must not evaluate its default in key mode.
+  const database = url(
+    "DATABASE_URL",
+    choose("DATABASE_URL", () => env.DATABASE_URL, core?.database.url),
+  );
+  const valkey = url(
+    "REDIS_URL",
+    choose("REDIS_URL", () => env.REDIS_URL, core?.valkey.url),
+  );
+  const servers = choose("NATS_SERVERS", () => env.NATS_SERVERS, core?.nats.servers) ?? [];
+  for (const server of servers) url("NATS_SERVERS", server, true);
+  const namespace = choose("SYNC_NAMESPACE", () => env.SYNC_NAMESPACE, core?.nats.namespace) ?? "";
+  const replicas = choose("SYNC_REPLICAS", () => env.SYNC_REPLICAS, core?.nats.replicas) ?? env.SYNC_REPLICAS;
+  const ignoreClusterUpdates =
+    choose("NATS_IGNORE_CLUSTER_UPDATES", () => env.NATS_IGNORE_CLUSTER_UPDATES, core?.nats.ignoreClusterUpdates) ??
+    env.NATS_IGNORE_CLUSTER_UPDATES;
+  const creds = choose("NATS_CREDS_FILE", () => contents("NATS_CREDS_FILE"), core?.nats.creds);
+  const ca = choose("NATS_TLS_CA_FILE", () => contents("NATS_TLS_CA_FILE"), core?.nats.ca);
+  const secret = choose("APP_SECRET", () => env.APP_SECRET, core?.appSecret.current) ?? "";
+  const rotation = core && !explicitlySet("APP_SECRET") ? core.appSecret : undefined;
+  if (core) {
+    if (servers.length === 0) throw new Error("NATS_SERVERS is required for platform start");
+    if (!namespace.trim()) throw new Error("SYNC_NAMESPACE is required for platform start");
+    if (!secret.trim()) throw new Error("APP_SECRET is required for platform start");
+  }
+  if (![1, 3, 5].includes(replicas)) throw new Error("SYNC_REPLICAS must be 1, 3, or 5");
+  if (typeof ignoreClusterUpdates !== "boolean") throw new Error("NATS_IGNORE_CLUSTER_UPDATES must be a boolean");
+  return {
+    appId,
+    database: { url: database },
+    valkey: { url: valkey },
+    nats: { servers: [...servers], namespace, replicas, ignoreClusterUpdates, creds, ca },
+    appSecret: { current: secret, previous: rotation?.previous, next: rotation?.next },
+    sources: {
+      database: { url: source("DATABASE_URL") },
+      valkey: { url: source("REDIS_URL") },
+      nats: {
+        servers: source("NATS_SERVERS"),
+        namespace: source("SYNC_NAMESPACE"),
+        replicas: source("SYNC_REPLICAS"),
+        ignoreClusterUpdates: source("NATS_IGNORE_CLUSTER_UPDATES"),
+        creds: source("NATS_CREDS_FILE"),
+        ca: source("NATS_TLS_CA_FILE"),
+      },
+      appSecret: {
+        current: source("APP_SECRET"),
+        ...(rotation?.previous ? { previous: "core" as const } : {}),
+        ...(rotation?.next ? { next: "core" as const } : {}),
+      },
+    },
+  };
+};

package/src/server/client-ip.ts

@@ -1,7 +1,7 @@
 import { isIP } from "node:net";
 import type { Context } from "hono";
 
-// The gateway (packages/gateway/src/client-address.ts) resolves this address using GATEWAY_TRUSTED_PROXIES.
+// The gateway (packages/gateway/src/client-address.ts) resolves this address using the gateway.trusted_proxies setting.
 export const clientIp = (c: Context): string =>
   c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.req.header("x-real-ip") ?? "unknown";
 

package/src/services/app-keys.ts

@@ -0,0 +1,298 @@
+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 | 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[]>`
+    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) : 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/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";