@k2b/cloud 0.46.0 → 0.48.0

package/src/runtime/connections.ts

@@ -0,0 +1,46 @@
+/** 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 };
+};
+/** Credential-free capability metadata; absent on older processes means unknown. */
+export type PlatformBootstrapMetadata = {
+  keyId?: string;
+  mode: "core" | "env";
+  sources: PlatformConnectionSources;
+  keyFormat: "cloud-app-key-v1";
+  protocol: 1;
+};
+export type PlatformConnections = PlatformConnectionValues & {
+  appId: string;
+  sources: PlatformConnectionSources;
+  bootstrap?: PlatformBootstrapMetadata;
+};
+
+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/app-key.ts

@@ -0,0 +1,14 @@
+import { hkdfSync } from "node:crypto";
+import { getProcessApplicationId } from "../_internal/process-identity";
+import { validatePurposeName } from "../_internal/purpose-name";
+import { connections } from "../runtime/connections";
+
+/** Derive a purpose-specific signing key from this installation's current secret. */
+export const appKey = (name: string): string => {
+  validatePurposeName(name);
+  const appId = getProcessApplicationId();
+  if (!appId) throw new Error("Start the application before using appKey()");
+  const secret = connections().appSecret.current;
+  if (!secret.trim()) throw new Error("APP_SECRET is required to derive application signing keys");
+  return Buffer.from(hkdfSync("sha256", secret, appId, name, 32)).toString("base64url");
+};

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/server/index.ts

@@ -8,6 +8,7 @@ export type { CreateApiClientConfig } from "./api-client";
 export { api as apiClient } from "./api-client";
 export { appAssetPath } from "./app-assets";
 export type { AppContext } from "./app-context";
+export { appKey } from "./app-key";
 export { clientIp, clientIpBucket } from "./client-ip";
 export { defineHelp, defineHelpCollection, type HelpCollection, type HelpDefinition, type HelpDefinitionDocument } from "./help";
 export { DEFAULT_LOCALE, getLocale, LOCALE_COOKIE, LOCALE_HEADER, locale, preferredLocale, resolveLocale } from "./locale";

package/src/services/app-access-management.ts

@@ -1,4 +1,5 @@
 import { type SQL, sql } from "bun";
+import { managerEligibility } from "../_internal/app-access-manager-sql";
 import type { AppMeta } from "../contracts/app";
 import type { AppAccessDeclaration, AppAccessSnapshot } from "../contracts/app-access";
 import { publishAppAccessChanged, wakeAppAccessChanged } from "../events/app-access";
@@ -107,14 +108,6 @@ const listEntries = async (appId: string, db: SQL = sql): Promise<AccessEntry[]>
             : { type: "public" },
   }));
 };
-/** Shared eligibility predicate for the last-manager guard and its presentation. */
-const managerEligibility = (db: SQL) => db`
-  EXISTS (SELECT 1 FROM auth.users u WHERE (u.account_expires IS NULL OR u.account_expires > now()) AND
-    (u.id = a.user_id OR (a.group_id IS NOT NULL AND a.group_id IN (${recursiveGroupIdsSubquery(db`u.id`)}))))
-  OR EXISTS (SELECT 1 FROM auth.service_accounts sa WHERE sa.id = a.service_account_id
-    AND sa.status = 'active' AND sa.kind IN ('standalone', 'agent'))
-`;
-
 const entryPresentation = async (appId: string): Promise<Map<string, { groupMemberCount?: number; effectiveManager: boolean }>> => {
   const rows = await sql<{ id: string; group_member_count: number | null; effective_manager: boolean }[]>`
     SELECT a.id,

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;
+};