@k2b/cloud 0.47.0 → 0.48.0

package/src/services/app-admin-facts.ts

@@ -0,0 +1,160 @@
+import { sql } from "bun";
+import { managerEligibility } from "../_internal/app-access-manager-sql";
+import type { RequestAuthority } from "../server/middleware/auth";
+import { AppAccessManagementError, canRepairAppAccess } from "./app-access-management";
+
+export type AppAdminFacts = {
+  access: { people: number; groups: number; serviceAccounts: number; managers: number; configured: boolean } | null;
+  keys: {
+    active: number;
+    expired: number;
+    revoked: number;
+    lastUsedAt: string | null;
+    firstCreatedAt: string | null;
+    accountStatus: "active" | "disabled" | null;
+  };
+  tokens: { active: number; total: number };
+  events: { hears: number; sends: number | null; failedDeliveries: number; waitingDeliveries: number };
+  notifications: number | null;
+  firstKnownAt: string | null;
+};
+
+/** Core-owned administration summary: at most 500 input IDs and four batched SQL reads. */
+export const appAdminFacts = async (authority: RequestAuthority, appIds: readonly string[]): Promise<Map<string, AppAdminFacts>> => {
+  if (!canRepairAppAccess(authority)) throw new AppAccessManagementError("FORBIDDEN", "Cloud administration authority is required.");
+  if (appIds.length > 500) throw new AppAccessManagementError("TOO_MANY_APPS", "At most 500 application IDs may be read at once.", 400);
+  const ids = [...new Set(appIds)];
+  const facts = new Map<string, AppAdminFacts>(
+    ids.map((id) => [
+      id,
+      {
+        access: null,
+        keys: { active: 0, expired: 0, revoked: 0, lastUsedAt: null, firstCreatedAt: null, accountStatus: null },
+        tokens: { active: 0, total: 0 },
+        events: { hears: 0, sends: 0, failedDeliveries: 0, waitingDeliveries: 0 },
+        notifications: 0,
+        firstKnownAt: null,
+      },
+    ]),
+  );
+  if (!ids.length) return facts;
+
+  const [access, credentials, events, notifications] = await Promise.all([
+    sql<
+      {
+        app_id: string;
+        people: number;
+        groups: number;
+        service_accounts: number;
+        managers: number;
+        configured: boolean;
+        first_known_at: Date | null;
+      }[]
+    >`
+      SELECT COALESCE(aa.app_id, s.app_id) AS app_id,
+        count(a.user_id)::int AS people, count(a.group_id)::int AS groups,
+        count(a.service_account_id)::int AS service_accounts,
+        count(*) FILTER (WHERE a.permission = 'admin' AND (${managerEligibility(sql)}))::int AS managers,
+        s.configured_at IS NOT NULL AS configured,
+        LEAST(min(a.created_at), s.configured_at) AS first_known_at
+      FROM auth.app_access aa
+      FULL JOIN auth.app_access_state s ON s.app_id = aa.app_id
+      LEFT JOIN auth.access a ON a.id = aa.access_id
+      WHERE COALESCE(aa.app_id, s.app_id) IN ${sql(ids)}
+      GROUP BY aa.app_id, s.app_id, s.configured_at
+    `,
+    sql<
+      {
+        app_id: string;
+        active: number;
+        expired: number;
+        revoked: number;
+        last_used_at: Date | null;
+        first_created_at: Date | null;
+        account_status: "active" | "disabled";
+        active_tokens: number;
+        total_tokens: number;
+        first_known_at: Date;
+      }[]
+    >`
+      WITH accounts AS (
+        SELECT id, app_id, status, created_at FROM auth.service_accounts
+        WHERE kind = 'resource_bound' AND resource_type = 'cloud.app' AND resource_id = app_id
+          AND app_id IN ${sql(ids)}
+      ), canonical_accounts AS (
+        SELECT DISTINCT ON (app_id) app_id, status FROM accounts ORDER BY app_id, created_at, id
+      )
+      SELECT sa.app_id,
+        count(*) FILTER (WHERE c.kind = 'app_key' AND c.status = 'active'
+          AND (c.expires_at IS NULL OR c.expires_at > now()))::int AS active,
+        count(*) FILTER (WHERE c.kind = 'app_key' AND c.status <> 'revoked' AND c.expires_at <= now())::int AS expired,
+        count(*) FILTER (WHERE c.kind = 'app_key' AND c.status = 'revoked')::int AS revoked,
+        max(c.last_used_at) FILTER (WHERE c.kind = 'app_key') AS last_used_at,
+        min(c.created_at) FILTER (WHERE c.kind = 'app_key') AS first_created_at,
+        canonical.status AS account_status,
+        count(*) FILTER (WHERE c.kind <> 'app_key' AND c.status = 'active'
+          AND (c.expires_at IS NULL OR c.expires_at > now()))::int AS active_tokens,
+        count(*) FILTER (WHERE c.kind <> 'app_key')::int AS total_tokens,
+        LEAST(min(sa.created_at), min(c.created_at)) AS first_known_at
+      FROM accounts sa
+      JOIN canonical_accounts canonical ON canonical.app_id = sa.app_id
+      LEFT JOIN auth.service_account_credentials c ON c.service_account_id = sa.id
+      GROUP BY sa.app_id, canonical.status
+    `,
+    sql<{ app_id: string; hears: number; sends: number; failed: number; waiting: number }[]>`
+      WITH subscriptions AS (
+        SELECT app_id, count(*) FILTER (WHERE state = 'active')::int AS hears
+        FROM events.app_subscriptions WHERE app_id IN ${sql(ids)} GROUP BY app_id
+      ), declarations AS (
+        SELECT app_id, count(*)::int AS sends
+        FROM events.app_declarations WHERE app_id IN ${sql(ids)} AND retired_at IS NULL GROUP BY app_id
+      ), deliveries AS (
+        SELECT subscription.app_id, count(*) FILTER (WHERE delivery.state = 'failed')::int AS failed,
+          count(*) FILTER (WHERE delivery.state IN ('pending', 'retrying'))::int AS waiting
+        FROM events.app_subscriptions subscription
+        JOIN events.app_deliveries delivery ON delivery.subscription_id = subscription.id
+        WHERE subscription.app_id IN ${sql(ids)} AND delivery.state IN ('failed', 'pending', 'retrying')
+        GROUP BY subscription.app_id
+      )
+      SELECT COALESCE(s.app_id, d.app_id, f.app_id) AS app_id, COALESCE(s.hears, 0) AS hears,
+        COALESCE(d.sends, 0) AS sends, COALESCE(f.failed, 0) AS failed, COALESCE(f.waiting, 0) AS waiting
+      FROM subscriptions s FULL JOIN declarations d ON d.app_id = s.app_id
+      FULL JOIN deliveries f ON f.app_id = COALESCE(s.app_id, d.app_id)
+    `,
+    sql<{ app_id: string; count: number }[]>`
+      SELECT app_id, count(*)::int AS count FROM notifications.definitions
+      WHERE app_id IN ${sql(ids)} AND active = true GROUP BY app_id
+    `,
+  ]);
+
+  for (const row of access) {
+    const fact = facts.get(row.app_id)!;
+    fact.access = {
+      people: row.people,
+      groups: row.groups,
+      serviceAccounts: row.service_accounts,
+      managers: row.managers,
+      configured: row.configured,
+    };
+    fact.firstKnownAt = row.first_known_at?.toISOString() ?? null;
+  }
+  for (const row of credentials) {
+    const fact = facts.get(row.app_id)!;
+    fact.keys = {
+      active: row.active,
+      expired: row.expired,
+      revoked: row.revoked,
+      lastUsedAt: row.last_used_at?.toISOString() ?? null,
+      firstCreatedAt: row.first_created_at?.toISOString() ?? null,
+      accountStatus: row.account_status,
+    };
+    fact.tokens = { active: row.active_tokens, total: row.total_tokens };
+    const firstKnownAt = row.first_known_at.toISOString();
+    if (fact.firstKnownAt === null || firstKnownAt < fact.firstKnownAt) fact.firstKnownAt = firstKnownAt;
+  }
+  for (const row of events) {
+    facts.get(row.app_id)!.events = { hears: row.hears, sends: row.sends, failedDeliveries: row.failed, waitingDeliveries: row.waiting };
+  }
+  for (const row of notifications) facts.get(row.app_id)!.notifications = row.count;
+  return facts;
+};

package/src/services/app-bootstrap.ts

@@ -0,0 +1,134 @@
+import { type SQL, sql } from "bun";
+import { decodeJwt, decodeProtectedHeader, type JWTPayload, jwtVerify } from "jose";
+import { importAppPublicKey } from "../app-key";
+import {
+  BOOTSTRAP_PATH,
+  BOOTSTRAP_PROOF_BYTES,
+  BOOTSTRAP_PROOF_SECONDS,
+  BOOTSTRAP_REPLAY_RETENTION_SECONDS,
+  BOOTSTRAP_TYPE,
+  type BootstrapIdentity,
+  bootstrapBodyDigest,
+} from "../runtime/bootstrap-protocol";
+import { getActiveAppKey, getInstallationId } from "./app-keys";
+import { get } from "./settings";
+
+export class BootstrapProofError extends Error {
+  constructor(readonly code: "invalid_proof" | "wrong_app" | "wrong_installation" | "replayed_proof" | "connections_not_permitted") {
+    super(code);
+    this.name = "BootstrapProofError";
+  }
+}
+const invalid = () => new BootstrapProofError("invalid_proof");
+
+/** Shared Postgres uniqueness rejects a proof used concurrently on different Core replicas. */
+export const consumeBootstrapProof = async (keyId: string, jti: string, exp: number, db: SQL = sql): Promise<boolean> => {
+  const rows = await db`
+    INSERT INTO auth.app_proof_replays (key_id, jti, retain_until)
+    VALUES (${keyId}::uuid, ${jti}, ${new Date((exp + BOOTSTRAP_REPLAY_RETENTION_SECONDS) * 1000)})
+    ON CONFLICT (key_id, jti) DO NOTHING RETURNING jti
+  `;
+  return rows.length === 1;
+};
+
+/** The ingress, per-key admission and minute maintenance share this installation budget. */
+export const bootstrapRateLimit = async (): Promise<number> => Math.max(1, Math.floor(await get<number>("security.rate_limit_per_second")));
+
+/** Drain expired pages, with two minutes of per-key admission capacity to catch up after missed runs. */
+export const cleanupBootstrapProofs = async (
+  db: SQL = sql,
+  { signal }: { signal?: AbortSignal } = {},
+): Promise<{ deleted: number; remaining: number }> => {
+  signal?.throwIfAborted();
+  // Include revoked keys: their retained evidence still needs cleaning after revocation.
+  const [keys] = await db<{ count: number }[]>`SELECT count(*)::int AS count FROM auth.service_account_credentials WHERE kind = 'app_key'`;
+  const maxRows = Math.max(1, keys?.count ?? 0) * (await bootstrapRateLimit()) * 60 * 2;
+  let deleted = 0;
+  while (deleted < maxRows) {
+    signal?.throwIfAborted();
+    const batchSize = Math.min(100, maxRows - deleted);
+    const query = db`
+      WITH batch AS MATERIALIZED (
+        SELECT key_id, jti FROM auth.app_proof_replays WHERE retain_until <= now()
+        ORDER BY retain_until LIMIT ${batchSize} FOR UPDATE SKIP LOCKED
+      )
+      DELETE FROM auth.app_proof_replays replay USING batch
+      WHERE replay.key_id = batch.key_id AND replay.jti = batch.jti AND replay.retain_until <= now()
+      RETURNING replay.jti
+    `;
+    const abort = () => query.cancel();
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      signal?.throwIfAborted();
+      const rows = await query;
+      deleted += rows.length;
+      if (rows.length < batchSize) break;
+    } finally {
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+  signal?.throwIfAborted();
+  const [backlog] = await db<{ count: number }[]>`SELECT count(*)::int AS count FROM auth.app_proof_replays WHERE retain_until <= now()`;
+  return { deleted, remaining: backlog?.count ?? 0 };
+};
+
+/** No caches: every HTTP transmission rechecks revocation, expiry and account state in Postgres. */
+export const authenticateBootstrap = async (
+  proof: string,
+  request: { method: string; path: string; body: Uint8Array<ArrayBuffer> },
+  db: SQL = sql,
+  now = Date.now(),
+): Promise<{ identity: BootstrapIdentity; jti: string; exp: number }> => {
+  if (Buffer.byteLength(proof) > BOOTSTRAP_PROOF_BYTES) throw invalid();
+  let appId: string;
+  let keyId: string;
+  try {
+    const header = decodeProtectedHeader(proof);
+    const claims = decodeJwt(proof);
+    if (header.alg !== "EdDSA" || header.typ !== BOOTSTRAP_TYPE || typeof header.kid !== "string" || typeof claims.iss !== "string")
+      throw invalid();
+    appId = claims.iss;
+    keyId = header.kid;
+  } catch {
+    throw invalid();
+  }
+  // Only validated IDs reach SQL, and the app identity must own this active credential.
+  const key = await getActiveAppKey({ appId, keyId }, db);
+  if (!key) throw invalid();
+  let claims: JWTPayload;
+  try {
+    const verified = await jwtVerify(proof, await importAppPublicKey(key.publicKey), {
+      algorithms: ["EdDSA"],
+      typ: BOOTSTRAP_TYPE,
+      currentDate: new Date(now),
+      requiredClaims: ["iss", "sub", "aud", "iat", "exp", "jti", "htm", "htu", "bdh"],
+    });
+    claims = verified.payload;
+  } catch {
+    throw invalid();
+  }
+  const seconds = Math.floor(now / 1000);
+  if (
+    !Number.isSafeInteger(claims.iat) ||
+    !Number.isSafeInteger(claims.exp) ||
+    claims.iat! > seconds + 2 ||
+    claims.exp! <= claims.iat! ||
+    claims.exp! - claims.iat! > BOOTSTRAP_PROOF_SECONDS ||
+    typeof claims.jti !== "string" ||
+    claims.jti.length === 0 ||
+    claims.jti.length > 64 ||
+    claims.jti.includes("\0") ||
+    request.method !== "POST" ||
+    request.path !== BOOTSTRAP_PATH ||
+    claims.htm !== request.method ||
+    claims.htu !== request.path ||
+    claims.bdh !== (await bootstrapBodyDigest(request.body))
+  )
+    throw invalid();
+  if (claims.iss !== key.appId || claims.sub !== key.appId) throw new BootstrapProofError("wrong_app");
+  const installationId = await getInstallationId(db);
+  if (claims.aud !== `cloud-core:${installationId}`) throw new BootstrapProofError("wrong_installation");
+  if (!key.connectionsAllowed) throw new BootstrapProofError("connections_not_permitted");
+  // Admission must succeed before the route atomically consumes this verified nonce.
+  return { identity: { installationId, appId, keyId }, jti: claims.jti, exp: claims.exp! };
+};

package/src/services/app-domain-check.ts

@@ -0,0 +1,152 @@
+import { request } from "node:https";
+import { connect } from "node:tls";
+import { DOMAIN_CHECK_PATH_PREFIX, DOMAIN_CHECK_TTL_SECONDS, domainCheckKey } from "../contracts/app-domains";
+import { redis } from "../runtime/clients";
+import { type PublicNetworkAddress, pinnedNetworkLookup, resolveAllowedNetworkAddresses } from "./network-security";
+import { awaitNetworkOperation, readNetworkResponse, withNetworkDeadline } from "./network-transport";
+
+export type AppDomainCheckStep = { ok: boolean; detail: string };
+export type AppDomainStatus = {
+  checkedAt: string;
+  dns: AppDomainCheckStep;
+  certificate: AppDomainCheckStep | null;
+  reachable: AppDomainCheckStep | null;
+};
+
+// Each network stage gets the platform resolver's five-second budget. The challenge lives longer than all stages combined.
+const STEP_TIMEOUT_MS = 5000;
+const deadline = <T>(work: (signal: AbortSignal) => Promise<T>) =>
+  withNetworkDeadline(STEP_TIMEOUT_MS, undefined, new Error("Domain check timed out"), work);
+
+const certificate = (host: string, addresses: PublicNetworkAddress[], signal: AbortSignal): Promise<void> =>
+  new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    // Connect to the checked IP directly; SNI and certificate identity still use the assigned host.
+    const socket = connect({ host: addresses[0]!.address, port: 443, servername: host, rejectUnauthorized: true });
+    const finish = (error?: Error) => {
+      signal.removeEventListener("abort", abort);
+      socket.destroy();
+      if (error) reject(error);
+      else resolve();
+    };
+    const abort = () => finish(signal.reason);
+    socket.once("error", finish);
+    socket.once("secureConnect", () => finish());
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+  });
+
+const reachable = (host: string, addresses: PublicNetworkAddress[], nonce: string, answer: string, signal: AbortSignal): Promise<void> =>
+  readNetworkResponse({
+    request,
+    options: {
+      hostname: host,
+      port: 443,
+      servername: host,
+      method: "GET",
+      path: `${DOMAIN_CHECK_PATH_PREFIX}${nonce}`,
+      headers: { accept: "text/plain", "accept-encoding": "identity" },
+      lookup: pinnedNetworkLookup(addresses),
+      agent: false,
+    },
+    signal,
+    read: (response, resolve, reject) => {
+      if (response.statusCode !== 200) {
+        reject(new Error(`Gateway check returned HTTP ${response.statusCode}`));
+        return;
+      }
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk: string) => {
+        body += chunk;
+        if (body.length > answer.length) reject(new Error("Gateway check returned an unexpected response"));
+      });
+      response.once("end", () => (body === answer ? resolve() : reject(new Error("Gateway check did not return the challenge answer"))));
+    },
+  });
+
+type DomainCheckDependencies = {
+  resolve: (host: string, signal: AbortSignal) => Promise<PublicNetworkAddress[]>;
+  certificate: typeof certificate;
+  reachable: typeof reachable;
+  challenge: (host: string, nonce: string, answer: string) => Promise<() => Promise<void>>;
+  now: () => Date;
+  nonce: () => string;
+};
+const dependencies: DomainCheckDependencies = {
+  // Assignment is administrator-only. Its exact host is the operator-controlled allowlist, restricted to TLS port 443.
+  resolve: (host, signal) =>
+    awaitNetworkOperation(
+      resolveAllowedNetworkAddresses(
+        host,
+        {
+          hosts: new Set(),
+          networks: [],
+          hostPorts: new Map([[host, new Set([443])]]),
+        },
+        undefined,
+        443,
+      ),
+      signal,
+    ),
+  certificate,
+  reachable,
+  challenge: async (host, nonce, answer) => {
+    const key = domainCheckKey(host, nonce);
+    await redis.set(key, answer, "EX", DOMAIN_CHECK_TTL_SECONDS);
+    return async () => {
+      await redis.del(key);
+    };
+  },
+  now: () => new Date(),
+  nonce: () => crypto.randomUUID(),
+};
+const failure = (error: unknown): AppDomainCheckStep => ({
+  ok: false,
+  detail: error instanceof Error ? error.message : "Domain check failed",
+});
+
+/** Stop at the first failure. No redirect is followed and no response body can exceed the challenge answer. */
+export const checkAppDomain = async (host: string, overrides: Partial<DomainCheckDependencies> = {}): Promise<AppDomainStatus> => {
+  const deps = { ...dependencies, ...overrides };
+  const status: AppDomainStatus = {
+    checkedAt: deps.now().toISOString(),
+    dns: { ok: false, detail: "DNS lookup failed" },
+    certificate: null,
+    reachable: null,
+  };
+  let addresses: PublicNetworkAddress[];
+  try {
+    addresses = await deadline((signal) => deps.resolve(host, signal));
+    if (!addresses.length) throw new Error("No A or AAAA records found");
+    status.dns = { ok: true, detail: addresses.map((address) => address.address).join(", ") };
+  } catch (error) {
+    status.dns = failure(error);
+    return status;
+  }
+  try {
+    await deadline((signal) => deps.certificate(host, addresses, signal));
+    status.certificate = { ok: true, detail: "Valid TLS certificate for this host" };
+  } catch (error) {
+    status.certificate = failure(error);
+    return status;
+  }
+  let cleanup: (() => Promise<void>) | undefined;
+  try {
+    // The answer stays in Valkey; only this installation's gateway can return it for the nonce in the path.
+    const nonce = deps.nonce();
+    const answer = deps.nonce();
+    await deadline(async (signal) => {
+      cleanup = await awaitNetworkOperation(deps.challenge(host, nonce, answer), signal);
+      await deps.reachable(host, addresses, nonce, answer, signal);
+    });
+    status.reachable = { ok: true, detail: "Cloud gateway returned the challenge" };
+  } catch (error) {
+    status.reachable = failure(error);
+  } finally {
+    // Expiry also removes a challenge if Valkey becomes unavailable during cleanup.
+    const removeChallenge = cleanup;
+    if (removeChallenge) await deadline(() => removeChallenge()).catch(() => undefined);
+  }
+  return status;
+};

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

@@ -269,7 +269,10 @@ export const revokeAppKey = async (params: { actor: AdminActor; appId: string; k
 };
 
 /** 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> => {
+export const getActiveAppKey = async (
+  params: { appId: string; keyId: string },
+  db: SQL = sql,
+): Promise<(AppKeyMetadata & { connectionsAllowed: boolean }) | null> => {
   try {
     validateAppKeyAppId(params.appId);
   } catch {
@@ -277,14 +280,14 @@ export const getActiveAppKey = async (params: { appId: string; keyId: string },
   }
   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[]>`
+  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) : null;
+  return row ? { ...map(row), connectionsAllowed: row.connections_allowed } : null;
 };
 
 /** Call only after successful authentication; a late touch cannot revive a key. */

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();