@k2b/cloud 0.46.0 → 0.48.0

package/src/contracts/app-domains.ts

@@ -0,0 +1,91 @@
+import type { SQL } from "bun";
+import { PWA_COOKIES } from "./pwa";
+
+/**
+ * App public surface and app domains: the contract Core, the platform, and the gateway share.
+ *
+ * An app with `defineApp({ public: true })` serves `app.public`. The platform mounts that router below
+ * `PUBLIC_SURFACE_PREFIX` on the app upstream. Only the gateway sends requests there, for a host an
+ * administrator assigned to the app, and sets `PUBLIC_HOST_HEADER` to the request authority (that host plus the
+ * client's port, if its Host header had one). The gateway strips both
+ * the prefix and the header from every incoming request on every host.
+ */
+export const PUBLIC_SURFACE_PREFIX = "/_cloud/public";
+export const PUBLIC_HOST_HEADER = "X-Cloud-Public-Host";
+
+/** The only Cloud path on an app domain: `GET <prefix><nonce>` answers the nonce while Core checks the domain. */
+export const DOMAIN_CHECK_PATH_PREFIX = "/_cloud/domain-check/";
+/**
+ * Valkey key Core sets before it requests the check path, with TTL `DOMAIN_CHECK_TTL_SECONDS`. Its value is a
+ * separate random answer that never appears in the request; the gateway responds with it, so an unrelated server
+ * that echoes the path cannot pass the check.
+ */
+export const domainCheckKey = (host: string, nonce: string): string => `cloud:domain-check:${host}:${nonce}`;
+export const DOMAIN_CHECK_TTL_SECONDS = 60;
+
+export type AppDomain = {
+  /** Normalized host: lowercase ASCII (IDNA), no port, no wildcard. */
+  host: string;
+  appId: string;
+  /** Another domain of the same app; requests then answer 301 (GET/HEAD) or 308 with path and query kept. */
+  redirectTo: string | null;
+  createdAt: string;
+};
+
+/** Durable assignment, owned by Core's migration. Readers before that migration see no table and no domains. */
+export const APP_DOMAINS_DDL = `
+  CREATE TABLE IF NOT EXISTS settings.app_domains (
+    host TEXT PRIMARY KEY,
+    app_id TEXT NOT NULL,
+    redirect_to TEXT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+  )
+`;
+
+const HOST_LABEL = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/;
+
+/** Returns the normalized host, or null when `input` is not a single DNS host name without port or wildcard. */
+export const normalizeAppDomainHost = (input: string): string | null => {
+  const trimmed = input.trim().replace(/\.$/, "");
+  if (!trimmed || /[/\\:@?#*\s]/.test(trimmed)) return null;
+  let host: string;
+  try {
+    host = new URL(`http://${trimmed}`).hostname;
+  } catch {
+    return null;
+  }
+  if (host.length > 253 || /^\d+(\.\d+){3}$/.test(host) || host.startsWith("[")) return null;
+  const labels = host.split(".");
+  if (labels.length < 2 && !host.endsWith("localhost")) return null;
+  return labels.every((label) => HOST_LABEL.test(label)) ? host : null;
+};
+
+/** Reads all assignments. A database without Core's table yet has none. */
+export const readAppDomains = async (db: SQL): Promise<AppDomain[]> => {
+  try {
+    const rows = await db<{ host: string; app_id: string; redirect_to: string | null; created_at: Date }[]>`
+      SELECT host, app_id, redirect_to, created_at FROM settings.app_domains ORDER BY host
+    `;
+    return rows.map((row) => ({ host: row.host, appId: row.app_id, redirectTo: row.redirect_to, createdAt: row.created_at.toISOString() }));
+  } catch (error) {
+    const code = error && typeof error === "object" && "errno" in error ? String(error.errno) : "";
+    if (code === "42P01") return [];
+    throw error;
+  }
+};
+
+/** Whether a registry entry declares `public: true`, read structurally so older entries stay valid. */
+export const declaresPublicSurface = (entry: object): boolean => "public" in entry && entry.public === true;
+
+/** Cookies that carry a Cloud credential. The gateway removes them from every request to a public surface. */
+export const isCloudCredentialCookie = (name: string): boolean =>
+  name === "session_token" ||
+  name === PWA_COOKIES.session ||
+  name === PWA_COOKIES.device ||
+  name === PWA_COOKIES.pairing ||
+  name === "cloud_browser" ||
+  name === "__Host-cloud_browser" ||
+  name.startsWith("__Secure-cloud-app-pwa-") ||
+  // Access proofs that built-in apps set on the Cloud host.
+  name === "mail_attachment_grant" ||
+  name === "filesv2-share-access";

package/src/contracts/app-status.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { CapabilityAppIdSchema, type CapabilityManifest } from "./capabilities";
+import { type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
+
+export const AppStatusWindowSchema = z.enum(["1h", "6h", "24h", "7d", "30d"]);
+export type AppStatusWindow = z.infer<typeof AppStatusWindowSchema>;
+export const AppStatusSummaryInputSchema = z
+  .object({
+    appIds: z.array(CapabilityAppIdSchema).min(1).max(200).describe("Application IDs whose status is requested."),
+    window: AppStatusWindowSchema.describe("Traffic observation window."),
+  })
+  .strict();
+export const AppStatusDetailInputSchema = z
+  .object({
+    appId: CapabilityAppIdSchema.describe("Application ID."),
+    window: AppStatusWindowSchema.describe("Traffic observation window."),
+    cursor: z.string().min(1).max(2048).optional().describe("Opaque continuation cursor from this provider."),
+  })
+  .strict();
+export const AppStatusForgetInputSchema = z.object({ appId: CapabilityAppIdSchema.describe("Offline application ID to forget.") }).strict();
+const count = z.number().int().nonnegative();
+export const AppStatusTrafficSchema = z
+  .object({
+    requests: count,
+    errors: count,
+    avgMs: z.number().nonnegative().nullable(),
+  })
+  .strict();
+export const AppStatusLinkSchema = z
+  .object({
+    kind: z.enum(["logs", "metrics", "routes", "capabilities"]).optional(),
+    label: z.string().min(1).max(120),
+    href: z
+      .string()
+      .max(2048)
+      .regex(/^\/admin\/[^\\\s\u0000-\u001f\u007f]*$/),
+  })
+  .strict();
+export const AppStatusAppSchema = z
+  .object({
+    appId: CapabilityAppIdSchema.describe("Application ID."),
+    traffic: AppStatusTrafficSchema.nullable(),
+    links: z.array(AppStatusLinkSchema).max(4),
+    lastSeenAt: z.string().datetime({ offset: true }).nullable().optional(),
+  })
+  .strict();
+export const AppStatusSummaryDataSchema = z
+  .object({
+    // Requested apps plus the fifty provider-only apps; their rows carry lastSeenAt.
+    apps: z.array(AppStatusAppSchema).max(250),
+    otherApps: z.array(CapabilityAppIdSchema).max(50),
+  })
+  .strict();
+export const AppStatusDetailDataSchema = z
+  .object({
+    routes: z.array(z.object({ prefix: z.string().min(1).max(2048), requests: count, errors: count }).strict()).max(200),
+    failedRequests: z
+      .array(
+        z
+          .object({
+            at: z.string().datetime({ offset: true }),
+            method: z.string().min(1).max(32),
+            path: z.string().min(1).max(2048),
+            status: z.number().int().min(100).max(599),
+          })
+          .strict(),
+      )
+      .max(50),
+    totalFailedRequests: count.nullable().optional(),
+    nextCursor: z.string().min(1).max(2048).nullable(),
+  })
+  .strict();
+export const AppStatusForgetDataSchema = z.object({ forgotten: z.boolean() }).strict();
+export type AppStatusSummaryData = z.infer<typeof AppStatusSummaryDataSchema>;
+export type AppStatusDetailData = z.infer<typeof AppStatusDetailDataSchema>;
+
+/** Shared role validation at startup, registry read, and consumer discovery. */
+export const appStatusIssues = (manifest: CapabilityManifest): CapabilityContractIssue[] => {
+  const role = manifest.appStatus;
+  if (!role) return [];
+  const issues: CapabilityContractIssue[] = [];
+  for (const [localId, input, data] of [
+    [role.summary, AppStatusSummaryInputSchema, AppStatusSummaryDataSchema],
+    [role.detail, AppStatusDetailInputSchema, AppStatusDetailDataSchema],
+  ] as const) {
+    const query = manifest.queries.find((query) => query.localId === localId);
+    if (!query) issues.push({ code: "kind", path: "$", message: `Missing app-status Query ${localId}` });
+    else {
+      issues.push(...capabilityContractIssues({ kind: "query", input, data }, { kind: "query", operation: query }));
+      if (query.appOnly || query.openWorld)
+        issues.push({ code: "kind", path: "$", message: "App-status Queries must be closed-world and person-readable" });
+    }
+  }
+  const action = manifest.actions.find((action) => action.localId === role.forget);
+  if (!action) issues.push({ code: "kind", path: "$", message: `Missing app-status Action ${role.forget}` });
+  else
+    issues.push(
+      ...capabilityContractIssues(
+        { kind: "action", input: AppStatusForgetInputSchema, data: AppStatusForgetDataSchema, idempotency: "required" },
+        { kind: "action", operation: action },
+      ),
+    );
+  return issues;
+};

package/src/contracts/capabilities.ts

@@ -1039,6 +1039,8 @@ export type CapabilityFileProviderDeclaration = { list: string; read: string; sa
 
 export type CapabilityCalendarSourceDeclaration = { calendars: string; events: string; update?: string; move?: string; delete?: string };
 
+export type CapabilityAppStatusDeclaration = { summary: string; detail: string; forget: string };
+
 export type CapabilityDiscussionsDeclaration = { item: string; containers: string; activity?: string };
 
 export type CapabilityDefinitions = {
@@ -1051,6 +1053,7 @@ export type CapabilityDefinitions = {
   fileProvider?: CapabilityFileProviderDeclaration;
   calendarSource?: CapabilityCalendarSourceDeclaration;
   discussions?: CapabilityDiscussionsDeclaration;
+  appStatus?: CapabilityAppStatusDeclaration;
   events?: CapabilityDefinitionCatalog<AppEventDefinition>;
   subscribes?: CapabilityDefinitionCatalog<AppEventSubscriptionDefinition>;
 };
@@ -1179,6 +1182,14 @@ export const CapabilityResourcePageManifestSchema = z
   })
   .strict();
 
+export const CapabilityAppStatusManifestSchema = z
+  .object({
+    summary: CapabilityLocalIdSchema,
+    detail: CapabilityLocalIdSchema,
+    forget: CapabilityLocalIdSchema,
+  })
+  .strict();
+
 export const CapabilityDiscussionsManifestSchema = z
   .object({
     item: CapabilityLocalIdSchema,
@@ -1268,6 +1279,7 @@ const readableManifest = (value: unknown, personCatalog = false): unknown => {
     resourcePages: sentPages,
     resourceTypes: sentModels,
     discussions: sentDiscussions,
+    appStatus: sentAppStatus,
     ...rest
   } = sent;
   const models = readEntries(sentModels ?? [], CapabilityResourceTypeModelSchema) ?? [];
@@ -1309,6 +1321,14 @@ const readableManifest = (value: unknown, personCatalog = false): unknown => {
     (!role.data.activity || queryIds.has(role.data.activity))
       ? role.data
       : undefined;
+  const statusRole = CapabilityAppStatusManifestSchema.safeParse(sentAppStatus);
+  const appStatus =
+    statusRole.success &&
+    queryIds.has(statusRole.data.summary) &&
+    queryIds.has(statusRole.data.detail) &&
+    readableActions.some((action) => action.localId === statusRole.data.forget)
+      ? statusRole.data
+      : undefined;
   const provider = CapabilityFileProviderManifestSchema.safeParse(sentProvider);
   const calendar = CapabilityCalendarSourceManifestSchema.safeParse(sentCalendarSource);
   const pageCounts = new Map<string, number>();
@@ -1328,6 +1348,7 @@ const readableManifest = (value: unknown, personCatalog = false): unknown => {
     ...rest,
     ...(sentModels !== undefined ? { resourceTypes } : {}),
     ...(discussions ? { discussions } : {}),
+    ...(appStatus ? { appStatus } : {}),
     ...(sentPages !== undefined ? { resourcePages } : {}),
     ...(provider.success ? { fileProvider: provider.data } : {}),
     ...(calendar.success ? { calendarSource: calendar.data } : {}),
@@ -1371,6 +1392,7 @@ export const CapabilityManifestSchema = z.preprocess(
     fileProvider: CapabilityFileProviderManifestSchema.optional(),
     calendarSource: CapabilityCalendarSourceManifestSchema.optional(),
     discussions: CapabilityDiscussionsManifestSchema.optional(),
+    appStatus: CapabilityAppStatusManifestSchema.optional(),
     resourceTypes: z.array(CapabilityResourceTypeModelSchema).max(MAX_MANIFEST_ENTRIES).optional(),
     policies: z.record(CapabilityLocalIdSchema, CapabilityActionPolicySchema).optional(),
     events: z.array(CapabilityEventManifestSchema).max(MAX_MANIFEST_ENTRIES).optional(),

package/src/contracts/index.ts

@@ -3,6 +3,7 @@ export * from "./announcements";
 export * from "./app";
 export * from "./app-approval";
 export * from "./app-details";
+export * from "./app-status";
 export * from "./avatar";
 export * from "./calendar-source";
 export * from "./calendar-view";

package/src/contracts/registry.ts

@@ -83,6 +83,8 @@ export type AppRuntimeMetadata = {
 };
 
 export type AppRegistryEntry = {
+  /** Opt-in public site, served only through the app public router. */
+  public?: true;
   access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;

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,15 @@ 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 PlatformBootstrapMetadata,
+  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/bootstrap-client.ts

@@ -0,0 +1,195 @@
+import type { AppKey } from "../app-key";
+import {
+  BOOTSTRAP_ATTEMPT_MS,
+  BOOTSTRAP_BODY,
+  BOOTSTRAP_BUDGET_MS,
+  BOOTSTRAP_PATH,
+  BOOTSTRAP_RESPONSE_BYTES,
+  type BootstrapResponse,
+  BootstrapResponseSchema,
+  signBootstrapProof,
+} from "./bootstrap-protocol";
+
+export class BootstrapError extends Error {
+  constructor(
+    readonly kind: "transient" | "permanent",
+    readonly reason: string,
+    readonly retryAfterMs = 0,
+  ) {
+    super(`Core bootstrap ${kind}: ${reason}`);
+    this.name = "BootstrapError";
+  }
+}
+
+const originUrl = (origin: string | undefined): URL => {
+  try {
+    if (!origin) throw new Error();
+    const url = new URL(origin);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+      throw new Error();
+    return new URL(BOOTSTRAP_PATH, url);
+  } catch {
+    throw new BootstrapError("permanent", "CLOUD_CORE_INTERNAL_ORIGIN must be a direct http(s) Core origin");
+  }
+};
+const httpReason = (status: number): string => {
+  if (status === 401) return "HTTP 401: unknown, revoked, expired or invalid app key/proof";
+  if (status === 403) return "HTTP 403: connections_not_permitted, app/installation mismatch or replayed proof";
+  if (status === 404) return "HTTP 404: bootstrap route unavailable; check the direct Core origin and version";
+  return `HTTP ${status}`;
+};
+const retryAfter = (header: string | null, now: number): number => {
+  if (!header) return 0;
+  if (/^\d+$/.test(header)) return Number(header) * 1000;
+  const date = Date.parse(header);
+  return Number.isFinite(date) ? Math.max(0, date - now) : 0;
+};
+// Keep transport read failures separate from invalid JSON: only transport failures retry.
+const readResponse = async (response: Response, signal: AbortSignal): Promise<unknown> => {
+  const tooLarge = () => new BootstrapError("permanent", "response too_large");
+  if (Number(response.headers.get("Content-Length")) > BOOTSTRAP_RESPONSE_BYTES) {
+    void response.body?.cancel().catch(() => undefined);
+    throw tooLarge();
+  }
+  const reader = response.body?.getReader();
+  if (!reader) throw new BootstrapError("permanent", "response invalid_json");
+  const abort = () => {
+    void reader.cancel().catch(() => undefined);
+  };
+  signal.addEventListener("abort", abort, { once: true });
+  if (signal.aborted) abort();
+  const bytes = new Uint8Array(BOOTSTRAP_RESPONSE_BYTES);
+  let length = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      if (length + chunk.value.byteLength > bytes.byteLength) {
+        void reader.cancel().catch(() => undefined);
+        throw tooLarge();
+      }
+      bytes.set(chunk.value, length);
+      length += chunk.value.byteLength;
+    }
+  } finally {
+    signal.removeEventListener("abort", abort);
+    reader.releaseLock();
+  }
+  signal.throwIfAborted();
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length)));
+  } catch {
+    throw new BootstrapError("permanent", "response invalid_json");
+  }
+};
+// Dependency injection keeps retry-budget tests fast and deterministic; not a public startup option.
+type Dependencies = {
+  fetch: (url: URL, init: RequestInit) => Promise<Response>;
+  now: () => number;
+  wallNow: () => number;
+  sleep: (ms: number) => Promise<unknown>;
+  random: () => number;
+  log: (entry: { appId: string; attempt: number; errorClass: "transient" | "permanent" }) => void;
+};
+const defaults: Dependencies = {
+  fetch: (url, init) => fetch(url, init),
+  now: () => performance.now(),
+  wallNow: () => Date.now(),
+  sleep: (ms) => Bun.sleep(ms),
+  random: Math.random,
+  log: (entry) => console.warn("Core bootstrap attempt failed", entry),
+};
+
+/** No application imports or listeners exist while this bounded startup request waits. */
+export const bootstrapConnections = async (
+  key: AppKey,
+  origin: string | undefined,
+  dependencies: Partial<Dependencies> = {},
+): Promise<BootstrapResponse> => {
+  const url = originUrl(origin);
+  const deps = { ...defaults, ...dependencies };
+  const deadline = deps.now() + BOOTSTRAP_BUDGET_MS;
+  let attempt = 0;
+  while (deps.now() < deadline) {
+    attempt++;
+    const controller = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let failure: BootstrapError;
+    let httpFailure: BootstrapError | undefined;
+    try {
+      const transmission = async (): Promise<BootstrapResponse> => {
+        const proof = await signBootstrapProof(key, deps.wallNow()).catch(() => {
+          throw new BootstrapError("permanent", "could not create Ed25519 startup proof");
+        });
+        controller.signal.throwIfAborted();
+        const response = await deps.fetch(url, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${proof}`, "Content-Type": "application/json", Accept: "application/json" },
+          body: BOOTSTRAP_BODY,
+          redirect: "error",
+          signal: controller.signal,
+        });
+        if (response.status !== 200) {
+          // A failed transmission may already have consumed its jti.
+          httpFailure = new BootstrapError(
+            response.status === 429 || response.status === 503 ? "transient" : "permanent",
+            httpReason(response.status),
+            retryAfter(response.headers.get("retry-after"), deps.wallNow()),
+          );
+          if (response.status === 403) {
+            try {
+              // Recognize only the stable permission code; never retain or log raw error payloads.
+              const body = await readResponse(response, controller.signal);
+              if (typeof body === "object" && body !== null && "code" in body && body.code === "connections_not_permitted")
+                httpFailure = new BootstrapError("permanent", "HTTP 403: connections_not_permitted; this key cannot receive connections");
+            } catch {
+              // A broken or stalled error body cannot turn a permanent HTTP status into a retry.
+            }
+          } else void response.body?.cancel().catch(() => undefined);
+          throw httpFailure;
+        }
+        const parsed = await readResponse(response, controller.signal);
+        const checked = BootstrapResponseSchema.safeParse(parsed);
+        if (!checked.success) throw new BootstrapError("permanent", "invalid response schema");
+        const { identity } = checked.data;
+        if (identity.installationId !== key.installationId) throw new BootstrapError("permanent", "wrong installation");
+        if (identity.appId !== key.appId) throw new BootstrapError("permanent", "wrong app");
+        if (identity.keyId !== key.keyId) throw new BootstrapError("permanent", "wrong key");
+        return checked.data;
+      };
+      return await Promise.race([
+        transmission(),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => {
+              controller.abort();
+              reject(new BootstrapError("transient", "attempt deadline exceeded"));
+            },
+            Math.min(BOOTSTRAP_ATTEMPT_MS, Math.max(0, deadline - deps.now())),
+          );
+        }),
+      ]);
+    } catch (error) {
+      // Network/TLS/CA errors may embed credentials or destinations; never retain their text or cause.
+      const redirect = error instanceof TypeError && "code" in error && error.code === "UnexpectedRedirect";
+      failure =
+        httpFailure ??
+        (error instanceof BootstrapError
+          ? error
+          : redirect
+            ? new BootstrapError("permanent", "redirect refused; check the direct Core origin")
+            : new BootstrapError("transient", "network or TLS failure"));
+      deps.log({ appId: key.appId, attempt, errorClass: failure.kind });
+      if (failure.kind === "permanent") throw failure;
+    } finally {
+      clearTimeout(timer);
+      controller.abort();
+    }
+    // Full jitter, capped at the per-attempt deadline. Retry-After remains a minimum wait.
+    const delay = Math.max(failure.retryAfterMs, deps.random() * Math.min(BOOTSTRAP_ATTEMPT_MS, 250 * 2 ** Math.min(attempt - 1, 6)));
+    const remaining = deadline - deps.now();
+    if (delay >= remaining) break;
+    await deps.sleep(delay);
+  }
+  throw new BootstrapError("transient", "five-minute startup budget exhausted");
+};

package/src/runtime/bootstrap-protocol.ts

@@ -0,0 +1,60 @@
+/** Bootstrap v1 has no platform barrel or application dependencies. */
+import { SignJWT } from "jose";
+import { z } from "zod";
+import { type AppKey, importAppKeySeed } from "../app-key";
+import type { PlatformConnectionValues } from "./connections";
+
+export const BOOTSTRAP_PATH = "/_internal/apps/bootstrap";
+export const BOOTSTRAP_TYPE = "cloud-app+jwt";
+export const BOOTSTRAP_BODY = "{}";
+export const BOOTSTRAP_RESPONSE_BYTES = 64 * 1024;
+// Same compact-token budget as Cloud's identity protocols.
+export const BOOTSTRAP_PROOF_BYTES = 4 * 1024;
+export const BOOTSTRAP_BUDGET_MS = 5 * 60_000;
+export const BOOTSTRAP_ATTEMPT_MS = 10_000;
+export const BOOTSTRAP_PROOF_SECONDS = 30;
+export const BOOTSTRAP_REPLAY_RETENTION_SECONDS = 5 * 60;
+
+const nonempty = z.string().refine((value) => value.trim().length > 0);
+export const BootstrapIdentitySchema = z.object({ installationId: z.uuid(), appId: z.string(), keyId: z.uuid() }).strict();
+export type BootstrapIdentity = z.infer<typeof BootstrapIdentitySchema>;
+export const BootstrapConnectionsSchema = z
+  .object({
+    database: z.object({ url: nonempty }).strict(),
+    valkey: z.object({ url: nonempty }).strict(),
+    nats: z
+      .object({
+        servers: z.array(nonempty).nonempty(),
+        namespace: nonempty,
+        replicas: z.union([z.literal(1), z.literal(3), z.literal(5)]),
+        ignoreClusterUpdates: z.boolean(),
+        creds: nonempty.optional(),
+        ca: nonempty.optional(),
+      })
+      .strict(),
+    appSecret: z.object({ current: nonempty, previous: nonempty.optional(), next: nonempty.optional() }).strict(),
+  })
+  .strict() satisfies z.ZodType<PlatformConnectionValues>;
+export const BootstrapResponseSchema = z.object({ identity: BootstrapIdentitySchema, connections: BootstrapConnectionsSchema }).strict();
+export type BootstrapResponse = z.infer<typeof BootstrapResponseSchema>;
+
+export const bootstrapBodyDigest = async (body: Uint8Array<ArrayBuffer>): Promise<string> =>
+  Buffer.from(await crypto.subtle.digest("SHA-256", body)).toString("base64url");
+
+/** Call at the HTTP transmission seam, including every retry. */
+export const signBootstrapProof = async (key: AppKey, now = Date.now()): Promise<string> => {
+  const iat = Math.floor(now / 1000);
+  return new SignJWT({
+    htm: "POST",
+    htu: BOOTSTRAP_PATH,
+    bdh: await bootstrapBodyDigest(new TextEncoder().encode(BOOTSTRAP_BODY)),
+  })
+    .setProtectedHeader({ alg: "EdDSA", typ: BOOTSTRAP_TYPE, kid: key.keyId })
+    .setIssuer(key.appId)
+    .setSubject(key.appId)
+    .setAudience(`cloud-core:${key.installationId}`)
+    .setIssuedAt(iat)
+    .setExpirationTime(iat + BOOTSTRAP_PROOF_SECONDS)
+    .setJti(crypto.randomUUID())
+    .sign(await importAppKeySeed(key.seed));
+};

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