@k2b/cloud 0.47.0 → 0.49.0

package/src/services/app-bootstrap.ts

@@ -0,0 +1,217 @@
+import type { SQL } from "bun";
+import { decodeJwt, decodeProtectedHeader, type JWTPayload, jwtVerify } from "jose";
+import { importAppPublicKey, validateAppKeyAppId } from "../app-key";
+import {
+  BOOTSTRAP_PATH,
+  BOOTSTRAP_PROOF_BYTES,
+  BOOTSTRAP_PROOF_SECONDS,
+  BOOTSTRAP_REPLAY_RETENTION_SECONDS,
+  BOOTSTRAP_TYPE,
+  type BootstrapIdentity,
+  BootstrapIdentitySchema,
+  bootstrapBodyDigest,
+} from "../runtime/bootstrap-protocol";
+import { sql } from "../runtime/clients";
+import { getActiveAppKey, getInstallationId, getStoredAppKey, type LastRejectedStart } 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";
+  }
+}
+/** Evidence attached only after signature and every request claim have been verified. */
+export class RejectedBootstrapStart extends BootstrapProofError {
+  constructor(
+    readonly identity: BootstrapIdentity,
+    readonly jti: string,
+    readonly reason: LastRejectedStart["reason"],
+  ) {
+    super(reason === "connections_not_permitted" ? reason : "invalid_proof");
+  }
+}
+const invalid = () => new BootstrapProofError("invalid_proof");
+
+/** A refused proof is never consumed. Already-consumed proofs cannot change administrator state. */
+export const recordRejectedBootstrapStart = async (rejection: RejectedBootstrapStart, db: SQL = sql): Promise<void> => {
+  const { identity, jti, reason } = rejection;
+  await db`
+    INSERT INTO auth.app_start_rejections (app_id, rejected_at, reason, key_id)
+    SELECT ${identity.appId}, clock_timestamp(), ${reason}, ${identity.keyId}::uuid
+    WHERE NOT EXISTS (SELECT 1 FROM auth.app_proof_replays WHERE key_id = ${identity.keyId}::uuid AND jti = ${jti})
+    ON CONFLICT (app_id) DO UPDATE
+      SET rejected_at = EXCLUDED.rejected_at, reason = EXCLUDED.reason, key_id = EXCLUDED.key_id
+  `;
+};
+
+export const clearRejectedBootstrapStart = async (appId: string, db: SQL = sql): Promise<void> => {
+  await db`DELETE FROM auth.app_start_rejections WHERE app_id = ${appId}`;
+};
+
+/** 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 };
+};
+
+/** Reject malformed or expired envelopes before allocating or reading a signed request body. Not authentication. */
+export const inspectAppProof = (proof: string, now = Date.now()): { appId: string; keyId: string } => {
+  if (Buffer.byteLength(proof) > BOOTSTRAP_PROOF_BYTES || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{86}$/.test(proof))
+    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();
+    validateAppKeyAppId(claims.iss);
+    if (!BootstrapIdentitySchema.shape.keyId.safeParse(header.kid).success) throw invalid();
+    const seconds = Math.floor(now / 1000);
+    if (
+      !Number.isSafeInteger(claims.iat) ||
+      !Number.isSafeInteger(claims.exp) ||
+      claims.iat! > seconds + 2 ||
+      claims.exp! <= seconds ||
+      claims.exp! <= claims.iat! ||
+      claims.exp! - claims.iat! > BOOTSTRAP_PROOF_SECONDS
+    )
+      throw invalid();
+    appId = claims.iss;
+    keyId = header.kid;
+  } catch {
+    throw invalid();
+  }
+  return { appId, keyId };
+};
+
+/** No caches: every HTTP transmission rechecks revocation, expiry and account state in Postgres. */
+export const authenticateAppProof = async (
+  proof: string,
+  request: { method: string; path: string; body: Uint8Array<ArrayBuffer> },
+  db: SQL = sql,
+  now = Date.now(),
+): Promise<{ identity: BootstrapIdentity; key: NonNullable<Awaited<ReturnType<typeof getActiveAppKey>>>; jti: string; exp: number }> => {
+  const { appId, keyId } = inspectAppProof(proof, now);
+  // 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();
+  return verifyAppProof(proof, request, key, db, now);
+};
+
+const verifyAppProof = async (
+  proof: string,
+  request: { method: string; path: string; body: Uint8Array<ArrayBuffer> },
+  key: NonNullable<Awaited<ReturnType<typeof getStoredAppKey>>>,
+  db: SQL,
+  now: number,
+) => {
+  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();
+  }
+  if (
+    typeof claims.jti !== "string" ||
+    claims.jti.length === 0 ||
+    claims.jti.length > 64 ||
+    claims.jti.includes("\0") ||
+    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");
+  // Admission must succeed before the route atomically consumes this verified nonce.
+  return { identity: { installationId, appId: key.appId, keyId: key.keyId }, key, jti: claims.jti, exp: claims.exp! };
+};
+
+/** Only connection delivery requires connections_allowed; runners can still sign requests. */
+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 }> => {
+  const ids = inspectAppProof(proof, now);
+  const key = await getStoredAppKey(ids, db);
+  if (!key) throw invalid();
+  const inactive = key.status !== "active" || key.accountStatus !== "active";
+  let verified: Awaited<ReturnType<typeof verifyAppProof>>;
+  try {
+    verified = await verifyAppProof(proof, request, key, db, now);
+  } catch (error) {
+    // Inactive keys have always returned invalid_proof, regardless of their claims.
+    if (inactive) throw invalid();
+    throw error;
+  }
+  if (request.method !== "POST" || request.path !== BOOTSTRAP_PATH) throw invalid();
+  const reason =
+    key.status === "revoked"
+      ? "revoked"
+      : key.status === "expired"
+        ? "expired"
+        : key.accountStatus === "disabled"
+          ? "disabled"
+          : !key.connectionsAllowed
+            ? "connections_not_permitted"
+            : null;
+  if (reason) throw new RejectedBootstrapStart(verified.identity, verified.jti, reason);
+  const { identity, jti, exp } = verified;
+  return { identity, jti, exp };
+};

package/src/services/app-details.ts

@@ -1,4 +1,4 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { getApp, listCapabilities } from "../_internal/registry";
 import {
@@ -9,6 +9,7 @@ import {
 } from "../contracts/app-details";
 import { type NotificationDefinitionPresentationCatalog, resolveNotificationDefinitionPresentation } from "../contracts/notification-types";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
+import { sql } from "../runtime/clients";
 import type { RequestAuthority } from "../server/middleware/auth";
 import { resolveAppIdentityPresentation } from "../shared/app-presentation";
 import { AppAccessManagementError, appAccessGrantCounts, canRepairAppAccess } from "./app-access-management";
@@ -48,8 +49,8 @@ type Dependencies = {
 
 /** Core-owned administration read shared by SSR and HTTP; app access is not administrator authority. */
 export function createAppDetailsService(dependencies: Dependencies = {}) {
-  const db = dependencies.db ?? sql;
   return async (appId: string, options: { authority: RequestAuthority; locale?: string }): Promise<AppDetails | null> => {
+    const db = dependencies.db ?? sql;
     if (!canRepairAppAccess(options.authority))
       throw new AppAccessManagementError("FORBIDDEN", "Cloud administration authority is required.");
     const locale = options.locale ?? "en";

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-events/accept.ts

@@ -15,8 +15,8 @@ const Metadata = z.object({
   version: Envelope.shape.version.catch(1),
 });
 
-export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
-  const markSeen = async (sequence: number, tx: SQL = db) => {
+export function createEventAcceptance(db: () => SQL, reconcile: () => Promise<void>) {
+  const markSeen = async (sequence: number, tx: SQL = db()) => {
     // Keep holes until replay or the periodic DLQ/retention check accounts for them.
     // Advancing the high watermark alone would hide eviction before the next tick.
     await tx`
@@ -36,7 +36,7 @@ export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
       return;
     }
     const { id, type, source, version } = metadata.data;
-    await db.begin(async (tx) => {
+    await db().begin(async (tx) => {
       // Invalid or oversized input is represented by metadata only, never a second failing payload insert.
       await tx`
         INSERT INTO events.app_events(id, type, version, source, subject_key, envelope, state, code)
@@ -61,7 +61,7 @@ export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
     } catch {
       log.warn("Declaration refresh failed; accepting against persisted declarations", { sequence });
     }
-    const [declaration] = await db<StoredDeclaration[]>`
+    const [declaration] = await db()<StoredDeclaration[]>`
       SELECT * FROM events.app_declarations
       WHERE app_id = ${envelope.source} AND type = ${envelope.type} AND version = ${envelope.version}
     `;
@@ -85,7 +85,7 @@ export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
     }
     const subjectKey = `${envelope.subject.type}:${envelope.subject.id}`;
     try {
-      await db.begin(async (tx) => {
+      await db().begin(async (tx) => {
         const inserted = await tx`
           INSERT INTO events.app_events(id, type, version, source, subject_key, envelope, state, code)
           VALUES (${envelope.id}::uuid, ${envelope.type}, ${envelope.version}, ${envelope.source}, ${subjectKey},