@k2b/cloud 0.46.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -21,10 +21,13 @@
     "!src/**/*.test-fixture.ts",
     "!src/**/*.test-fixture.tsx",
     "!scripts/**/*.test.ts",
+    "!scripts/**/*.test-fixture.ts",
     "!scripts/runtime-recovery-*.ts"
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./app-key": "./src/app-key.ts",
+    "./start": "./src/start.ts",
     "./desktop": "./src/desktop/index.ts",
     "./desktop/solid": "./src/desktop/solid.tsx",
     "./server": "./src/server/index.ts",
@@ -127,8 +130,8 @@
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.20.1",
-    "@k2b/ui": "0.36.0",
+    "@k2b/ssr": "0.20.2",
+    "@k2b/ui": "0.38.0",
     "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.1",
     "@nats-io/jetstream": "3.4.0",
@@ -159,7 +162,8 @@
     "yjs": "13.6.33",
     "hash-wasm": "4.12.0",
     "@types/sanitize-html": "2.16.1",
-    "@types/web-push": "3.6.4"
+    "@types/web-push": "3.6.4",
+    "@k2b/editor": "0.1.1"
   },
   "devDependencies": {
     "@babel/core": "8.0.6",

package/scripts/build.ts

@@ -116,9 +116,13 @@ const { app, plugin } = await import(configPath);
 // every production app without requiring app-owned bootstrap imports.
 const serverEntry = resolve(dist, ".server-entry.ts");
 const reflectMetadata = Bun.resolveSync("reflect-metadata", frameworkDir);
+const platformStart = resolve(frameworkDir, "src/start.ts");
+const declaredAppId = app?.meta.id ?? appId;
+if (declaredAppId !== appId)
+  throw new Error(`APP_ID ${JSON.stringify(appId)} does not match declared app ${JSON.stringify(declaredAppId)}`);
 await writeFile(
   serverEntry,
-  `import ${JSON.stringify(reflectMetadata)};\nexport { default } from ${JSON.stringify(resolve(appDir, "src/index.ts"))};\n`,
+  `import ${JSON.stringify(reflectMetadata)};\nimport { startPlatform } from ${JSON.stringify(platformStart)};\nconst application = await startPlatform({ appId: ${JSON.stringify(declaredAppId)}, load: () => import(${JSON.stringify(resolve(appDir, "src/index.ts"))}) });\nexport default application.default;\n`,
 );
 let server: Awaited<ReturnType<typeof Bun.build>>;
 try {

package/scripts/preload.ts

@@ -22,6 +22,7 @@ import { cp, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import tailwind from "bun-plugin-tailwind";
+import { startPlatform } from "../src/start";
 import { writeAppFavicon } from "./app-favicon";
 import { buildBrowserPerformance } from "./browser-performance";
 import { writeInstallableIcons } from "./installable-assets";
@@ -43,7 +44,10 @@ if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DI
 // Share the resolved source directory with defineApp before importing config.
 process.env.APP_DIR = appDir;
 
-const { app, plugin } = await import(resolve(appDir, "src/config"));
+const { app, plugin } = await startPlatform({ appId, load: () => import(resolve(appDir, "src/config")) });
+if (app && app.meta.id !== appId) {
+  throw new Error(`APP_ID ${JSON.stringify(appId)} does not match declared app ${JSON.stringify(app.meta.id)}`);
+}
 Bun.plugin((app?.plugin ?? plugin)());
 
 // ── Build CSS ───────────────────────────────────────────────────────────────

package/src/_internal/app-access-manager-sql.ts

@@ -0,0 +1,10 @@
+import type { SQL } from "bun";
+import { recursiveGroupIdsSubquery } from "../services/accounts/group-sql";
+
+/** Eligibility of access entry alias `a`, shared by the last-manager guard and administration reads. */
+export 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'))
+`;

package/src/_internal/bounded-json.ts

@@ -1,7 +1,12 @@
 export type BoundedJsonResult = { ok: true; data: unknown } | { ok: false; reason: "too_large" | "invalid_json" };
 
 /** Reads JSON without allowing a missing or forged Content-Length to bypass the byte cap. */
-export const readBoundedJson = async (message: Request | Response, maxBytes: number, signal?: AbortSignal): Promise<BoundedJsonResult> => {
+export const readBoundedJson = async (
+  message: Request | Response,
+  maxBytes: number,
+  signal?: AbortSignal,
+  consumeBytes?: (bytes: number) => void,
+): Promise<BoundedJsonResult> => {
   signal?.throwIfAborted();
   const declared = message.headers.get("content-length");
   if (declared !== null) {
@@ -27,6 +32,7 @@ export const readBoundedJson = async (message: Request | Response, maxBytes: num
     while (true) {
       const next = await reader.read();
       if (next.done) break;
+      consumeBytes?.(next.value.byteLength);
       total += next.value.byteLength;
       if (total > maxBytes) {
         await reader.cancel().catch(() => undefined);

package/src/_internal/capabilities.ts

@@ -1,5 +1,7 @@
 import type { AppEventDefinition, AppEventSubscriptionDefinition } from "../contracts/app-events";
+import { appStatusIssues } from "../contracts/app-status";
 import {
+  CapabilityAppStatusManifestSchema,
   type CapabilityEventManifest,
   CapabilityEventManifestSchema,
   CapabilityQualifiedIdSchema,
@@ -108,6 +110,7 @@ const DECLARATION_FIELDS = {
   fileProvider: true,
   calendarSource: true,
   discussions: true,
+  appStatus: true,
   events: true,
   subscribes: true,
 } satisfies DefinedFields<CapabilityDefinitions>;
@@ -710,6 +713,7 @@ export const compileCapabilities = (
   }
   if (definitions.fileProvider) assertDefinedFields(definitions.fileProvider, FILE_PROVIDER_FIELDS, "fileProvider");
 
+  if (definitions.appStatus !== undefined) CapabilityAppStatusManifestSchema.parse(definitions.appStatus);
   if (definitions.discussions !== undefined) CapabilityDiscussionsManifestSchema.parse(definitions.discussions);
   for (const [localId, type] of Object.entries(definitions.types ?? {})) {
     if (type.access !== undefined) {
@@ -1037,6 +1041,7 @@ export const compileCapabilities = (
   });
   const manifestBase = {
     ...(resourceTypes.length ? { resourceTypes } : {}),
+    ...(definitions.appStatus ? { appStatus: definitions.appStatus } : {}),
     ...(definitions.discussions ? { discussions: definitions.discussions } : {}),
     ...(resourcePages.length ? { resourcePages } : {}),
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
@@ -1058,6 +1063,8 @@ export const compileCapabilities = (
     ...manifestBase,
     manifestHash: capabilityHash(manifestBase),
   });
+  const statusIssues = appStatusIssues(manifest);
+  if (statusIssues.length) throw new Error(`appStatus: ${statusIssues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
   const discussionIssues = discussionsIssues(manifest);
   if (discussionIssues.length)
     throw new Error(`discussions: ${discussionIssues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
@@ -1234,6 +1241,7 @@ export const resolveCapabilityManifestPresentation = (
         : {}),
       ...(current.subscribes ? { subscribes: current.subscribes } : {}),
       ...(current.resourceTypes ? { resourceTypes: current.resourceTypes } : {}),
+      ...(current.appStatus ? { appStatus: current.appStatus } : {}),
       ...(current.discussions ? { discussions: current.discussions } : {}),
       ...(current.resourcePages ? { resourcePages: current.resourcePages } : {}),
       ...(current.calendarSource ? { calendarSource: current.calendarSource } : {}),

package/src/_internal/define-app.ts

@@ -2,6 +2,7 @@ import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, valid
 import { createOwnedAppAccessRoutes } from "../api/app-access";
 import { createAppEventDeliveryRoutes } from "../api/app-event-delivery";
 import { createResourceAppAccessRoutes } from "../api/app-resource-access";
+import { createSettingsOpsRoutes, settingsInvocationOperation } from "../api/settings-ops";
 import { type AppAccessDeclaration, compileAppAccess } from "../contracts/app-access";
 import { startAppEventDelivery } from "../events/app-event-delivery";
 import { bindAppEvents } from "../events/app-events";
@@ -26,7 +27,7 @@ import { bindProcessApplicationId, clearProcessApplicationId } from "./process-i
 
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { HtmlFn, SsrConfig } from "@k2b/ssr";
+import type { HtmlFn, SsrConfig, SsrOptions } from "@k2b/ssr";
 import { createConfig as createSsrConfig } from "@k2b/ssr";
 import { routes } from "@k2b/ssr/hono";
 import type { Sync } from "@k2b/sync";
@@ -47,6 +48,7 @@ import type {
   CloudLifecycleContext,
   WidgetEndpoint,
 } from "../contracts/app";
+import { PUBLIC_SURFACE_PREFIX } from "../contracts/app-domains";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_REQUEST_BYTES,
@@ -67,8 +69,10 @@ import { getLocale, resolveLocale } from "../server/locale";
 import { requireAppAccess, stopAppAccessConnections } from "../server/middleware/app-access";
 import { type AuthContext, auth } from "../server/middleware/auth";
 import { requireInvocation } from "../server/middleware/invocation";
+import { createPublicSurfaceHandler, validatePublicSurfaceRoutes } from "./public-surface";
 import "../events/app-access";
 import { createNestedCapabilityQuery } from "../capabilities/nested";
+import { connections } from "../runtime/connections";
 import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-template";
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
 import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
@@ -82,6 +86,7 @@ import {
   widgetInvocationOperation,
 } from "../services/identity/invocation-operations";
 import { normalizeInvocationRequestId } from "../services/identity/invocation-token";
+import { startLinksRuntime } from "../services/links/runtime";
 import { logger } from "../services/logging";
 import { startNotificationDefinitionRegistration } from "../services/notifications/catalog";
 import { readRailSnapshot } from "../services/rail-snapshot";
@@ -119,6 +124,7 @@ import { publicFileVersion, servePublicAsset, sharedStylesheetVersion, versioned
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
 import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
 import { compileWidgetDeclarations } from "./widget-declarations";
+import { createAppWorkloadCredential } from "./workload-credential";
 
 /** Only development links use this start stamp to pick up rebuilds. */
 const developmentStamp = Date.now();
@@ -162,6 +168,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   /** Shared object-store package. Defaults to the app ID. */
   package?: string;
   access?: AppAccessDeclaration;
+  /** Serve a separate public site on domains assigned by an administrator. */
+  public?: true;
   name: string;
   icon: string;
   description: string;
@@ -370,6 +378,10 @@ export type AppDefinition<S extends AppSettingsMap = {}, N extends NotificationD
   config: SsrConfig;
   meta: AppMeta;
   baseUrl: string;
+  /** Normal Hono router for the public site. Adding routes requires `public: true`. */
+  readonly public: Hono;
+  /** Public HTML template and island assets, reusing this app's single SSR plugin/build. Call before adding page routes. */
+  publicSsr: <T extends object = object>(template: NonNullable<SsrOptions<T>["template"]>) => { html: HtmlFn<T> };
   start: (opts: StartOptions) => Promise<StartResult>;
   /**
    * The process-wide @k2b/sync instance, connected and ready once `start()`
@@ -476,6 +488,8 @@ export const defineApp = <
 >(
   opts: AppOptions<S, N, AppId>,
 ): AppDefinition<S, N, AppId> => {
+  validatePublicSurfaceRoutes(opts.routes);
+  const publicRouter = new Hono();
   const appSkills = opts.skills ? validateAppSkillCatalog(opts.skills) : undefined;
   const skillsManifestHash = appSkills ? appSkillManifestHash(appSkills) : undefined;
   configurePostgresApplicationName(opts.id);
@@ -690,7 +704,13 @@ export const defineApp = <
 
   // ── 3. start() — builds and boots the Hono server ────────────────────
   const start = async (startOpts: StartOptions): Promise<StartResult> => {
+    if (!opts.public && publicRouter.routes.length)
+      throw new Error(`App "${opts.id}" adds app.public routes without declaring public: true`);
     const port = startOpts.port ?? 3000;
+    if (env.GOTENBERG_URL)
+      console.warn("[deprecation] GOTENBERG_URL only bootstraps gotenberg.url; remove it after cld admin settings status --env succeeds.");
+    if (env.CLOUD_IDENTITY_JWKS_ORIGIN)
+      console.warn("[deprecation] CLOUD_IDENTITY_JWKS_ORIGIN is deprecated; use CLOUD_CORE_INTERNAL_ORIGIN instead.");
     const baseUrl = opts.baseUrl;
     const log = logger("app");
     const http = createHttpDrain();
@@ -699,7 +719,7 @@ export const defineApp = <
     // Settings are encrypted at rest, so every container needs the secret. It
     // is only read on the first decrypt, which meant a container without it
     // booted cleanly and failed much later with an unrelated-looking error.
-    if (!env.APP_SECRET.trim()) {
+    if (!connections().appSecret.current.trim()) {
       throw new Error(
         `APP_SECRET is not set (app "${meta.id}"). Settings are encrypted at rest and every app in the ` +
           "deployment must share the same value; without it the first settings read fails.",
@@ -745,6 +765,7 @@ export const defineApp = <
       const entry: AppRegistryEntry = {
         package: packageName,
         id: meta.id,
+        ...(opts.public ? { public: true as const } : {}),
         access: meta.access,
         name: meta.name,
         icon: meta.icon,
@@ -812,6 +833,7 @@ export const defineApp = <
         registry: appInstanceRegistry,
         lock: appMembershipLock,
         startedAt: entry.startedAt,
+        bootstrap: connections().bootstrap,
       });
       // Heartbeat
       const heartbeat = createHeartbeat(meta.id, entry, {
@@ -864,6 +886,7 @@ export const defineApp = <
         await capabilityHeartbeat?.stop();
       });
       cleanup.push(() => heartbeat.stop());
+      cleanup.push(() => membership.leave());
 
       // Runtime context — start the registry watcher so middleware.runtime() and
       // the lifecycle context below see populated cluster state. Idempotent: the
@@ -887,7 +910,10 @@ export const defineApp = <
       // app middleware cannot report their template. Without this, every hashed
       // island chunk would land in telemetry as its own route.
       const invocationApp = { getApp: async (id: string) => (id === meta.id ? meta : null) };
+      const publicSurface = createPublicSurfaceHandler(opts.public ? publicRouter : undefined, isDevelopment);
       const server = new Hono<AuthContext>()
+        .all(PUBLIC_SURFACE_PREFIX, publicSurface)
+        .all(`${PUBLIC_SURFACE_PREFIX}/*`, publicSurface)
         .use("*", routeTemplate)
         .get(APP_READINESS_PATH, () => appReadinessResponse(meta.id))
         .route(ssrMountPath, routes(config))
@@ -909,6 +935,18 @@ export const defineApp = <
           if (!c.get("user")?.roles.includes("admin")) return c.json({ message: "Insufficient permissions" }, 403);
           return next();
         })
+        .use(
+          "/_internal/settings/*",
+          requireInvocation(
+            (c) => ({
+              targetAppId: meta.id,
+              operation: settingsInvocationOperation(c.req.method, new URL(c.req.url).pathname.slice("/_internal/settings/".length)),
+              schemaHash: null,
+            }),
+            invocationApp,
+          ),
+        )
+        .route("/_internal/settings", createSettingsOpsRoutes(Object.keys(opts.settings ?? {})))
         .route("/_internal/sync", createSyncOpsRoutes(getProcessSync));
 
       if (installable) server.route("/", createInstallableRoutes(meta.id, installable));
@@ -1145,6 +1183,8 @@ export const defineApp = <
 
       let stopNotificationRegistration: (() => void) | undefined;
       cleanup.push(() => stopNotificationRegistration?.());
+      let workloadCredential: ReturnType<typeof createAppWorkloadCredential> | undefined;
+      cleanup.push(() => workloadCredential?.stop());
       const stopLifecycle = startOpts.lifecycle?.stop;
       if (stopLifecycle) cleanup.push(() => stopLifecycle(cloudCtx));
 
@@ -1158,6 +1198,8 @@ export const defineApp = <
       // Core creates it in its own setup, so it starts publishing after that.
       if (meta.id !== "core") await startOutbox();
 
+      cleanup.push(await startLinksRuntime());
+
       if (!startOpts.skipSetup && startOpts.lifecycle?.setup) {
         log.info(`Setup: ${meta.id}`);
         const setup = startOpts.lifecycle.setup;
@@ -1169,6 +1211,23 @@ export const defineApp = <
 
       await loadSettingsCache();
 
+      // The instance can obtain its credential before workers run; routes remain undiscoverable.
+      await membership.register();
+      workloadCredential = createAppWorkloadCredential({
+        appId: meta.id,
+        instanceId: membership.instanceId,
+        onRecovered: () => log.info("App workload credential refresh recovered", { appId: meta.id }),
+        onUnavailable: (reason) => {
+          if (reason === "release_unavailable") {
+            log.warn("Workload credential release was not confirmed; Core will reconcile after removal", { appId: meta.id });
+          } else {
+            log.error("App workload credential unavailable; background invocation is disabled", { appId: meta.id, reason });
+          }
+        },
+      });
+      // The NATS request has a five-second timeout; an outage leaves workers fail-closed.
+      await workloadCredential.start();
+
       if (startOpts.lifecycle?.start) {
         log.info(`Start: ${meta.id}`);
         await startOpts.lifecycle.start(cloudCtx);
@@ -1226,6 +1285,14 @@ export const defineApp = <
     config,
     meta,
     baseUrl: opts.baseUrl,
+    public: publicRouter,
+    publicSsr: <T extends object = object>(template: NonNullable<SsrOptions<T>["template"]>) => {
+      if (!opts.public) throw new Error(`App "${opts.id}" uses publicSsr without declaring public: true`);
+      const site = createSsrConfig<T>({ dev: config.dev, rootDir: config.rootDir, basePath: "", template });
+      publicRouter.route("/_ssr", routes(site.config));
+      publicRouter.all("/_ssr/*", (c) => c.notFound());
+      return { html: site.html };
+    },
     start,
     get sync() {
       return getProcessSync();

package/src/_internal/heartbeat.ts

@@ -48,6 +48,7 @@ export const createRegistryMembership = (
     instanceId?: string;
     hostname?: string;
     startedAt?: number;
+    bootstrap?: AppInstanceRecord["bootstrap"];
     writeTimeoutMs?: number;
   },
 ) => {
@@ -60,6 +61,7 @@ export const createRegistryMembership = (
     hostname: options.hostname ?? hostname(),
     startedAt: options.startedAt ?? Date.now(),
     entries: {},
+    ...(options.bootstrap ? { bootstrap: structuredClone(options.bootstrap) } : {}),
   };
   const writeTimeoutMs = options.writeTimeoutMs ?? HEARTBEAT_WRITE_TIMEOUT_MS;
   if (!Number.isFinite(writeTimeoutMs) || writeTimeoutMs <= 0) throw new RangeError("Membership write timeout must be positive and finite");
@@ -94,6 +96,25 @@ export const createRegistryMembership = (
   };
 
   return {
+    instanceId,
+    // Establish process identity before lifecycle workers start, without advertising routes yet.
+    register: async () => {
+      let timer: Timer | undefined;
+      // This runs before the ordinary heartbeat supplies its write deadline.
+      const write = upsert().finally(async () => {
+        if (left) await options.registry().delete({ key });
+      });
+      try {
+        await Promise.race([
+          write,
+          new Promise<never>((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Instance registration timed out after ${writeTimeoutMs}ms`)), writeTimeoutMs);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+    },
     join: async (sharedKey: string, sharedValue: unknown, entry: SharedEntry): Promise<void> => {
       left = false;
       await prepareShared(sharedKey);

package/src/_internal/nats-connection.ts

@@ -1,11 +1,10 @@
 /**
  * NATS connection for @k2b/sync — one connection per app process, created by
- * the app lifecycle. Configuration comes from `env` (NATS_* variables); sync
+ * the app lifecycle. Configuration comes from the platform startup snapshot; sync
  * itself reads no ENV and loads no credentials.
  */
-import { readFileSync } from "node:fs";
 import { connect, credsAuthenticator, type NatsConnection } from "@nats-io/transport-node";
-import { env } from "../config/env";
+import { connections } from "../runtime/connections";
 
 export type ConnectNatsOptions = {
   /** Connection name shown in NATS monitoring (`connz`), e.g. `cloud-<appId>-<instanceId>`. */
@@ -13,15 +12,17 @@ export type ConnectNatsOptions = {
 };
 
 /** Dial `NATS_SERVERS` once. `startProcessSync()` requires the list and retries while NATS does not answer. */
-export const connectNats = async ({ name }: ConnectNatsOptions): Promise<NatsConnection> =>
-  connect({
-    servers: env.NATS_SERVERS,
+export const connectNats = async ({ name }: ConnectNatsOptions): Promise<NatsConnection> => {
+  const nats = connections().nats;
+  return connect({
+    servers: nats.servers,
     name,
-    ignoreClusterUpdates: env.NATS_IGNORE_CLUSTER_UPDATES,
+    ignoreClusterUpdates: nats.ignoreClusterUpdates,
     // Keep reconnecting for the life of the process: sync work resumes when the cluster is back.
     reconnect: true,
     maxReconnectAttempts: -1,
     reconnectTimeWait: 2_000,
-    ...(env.NATS_CREDS_FILE ? { authenticator: credsAuthenticator(readFileSync(env.NATS_CREDS_FILE)) } : {}),
-    ...(env.NATS_TLS_CA_FILE ? { tls: { caFile: env.NATS_TLS_CA_FILE } } : {}),
+    ...(nats.creds ? { authenticator: credsAuthenticator(new TextEncoder().encode(nats.creds)) } : {}),
+    ...(nats.ca ? { tls: { ca: nats.ca } } : {}),
   });
+};

package/src/_internal/postgres-application-name.ts

@@ -1,3 +1,4 @@
+// Slice 7 removes this legacy env-URL rewrite together with Bun-global client imports.
 /** Name Bun's default pool before its first use without changing connection ownership. */
 export const configurePostgresApplicationName = (
   applicationId: string,
@@ -28,3 +29,13 @@ export const configurePostgresApplicationName = (
   url.searchParams.set("application_name", `cloud:${applicationId}`);
   environment[variable] = url.toString();
 };
+
+/** Preserve operator URL options; otherwise name every connection through native client options. */
+export const postgresApplicationOptions = (applicationId: string, connectionUrl: string): Record<string, string> => {
+  const url = new URL(connectionUrl);
+  let operatorConfigured = false;
+  url.searchParams.forEach((_value, key) => {
+    if (key.toLowerCase() === "application_name" || key.toLowerCase() === "options") operatorConfigured = true;
+  });
+  return operatorConfigured ? {} : { application_name: `cloud:${applicationId}` };
+};

package/src/_internal/process-sync.ts

@@ -11,7 +11,7 @@ import { hostname } from "node:os";
 import { createSync, type Sync, SyncError } from "@k2b/sync";
 import { expBackoff } from "@k2b/sync/retry";
 import type { NatsConnection } from "@nats-io/transport-node";
-import { env } from "../config/env";
+import { connections } from "../runtime/connections";
 import { logger } from "../services/logging";
 import { flushSyncTraceEvents, observeSyncEvent } from "../services/logging/trace";
 import { connectNats } from "./nats-connection";
@@ -19,6 +19,13 @@ import { withSyncBudgets } from "./sync-budget";
 
 let current: Sync | undefined;
 let starting = false;
+let processNats: NatsConnection | undefined;
+
+/** Existing non-retained NATS transport, owned and drained by the process lifecycle. */
+export const getProcessNats = (): NatsConnection => {
+  if (!processNats) throw new Error("NATS is not available before app.start()");
+  return processNats;
+};
 
 /** Bind the process instance. `startProcessSync()` does this; tests may bind their own. */
 export const bindProcessSync = (sync: Sync): void => {
@@ -128,12 +135,12 @@ const connectReadySync = async (application: string): Promise<{ sync: Sync; conn
     sync = withSyncBudgets(
       createSync({
         connection,
-        namespace: env.SYNC_NAMESPACE,
+        namespace: connections().nats.namespace,
         application,
-        defaults: { replicas: env.SYNC_REPLICAS },
+        defaults: { replicas: connections().nats.replicas },
         observe: (event) => observeSyncEvent(event, application),
       }),
-      { connection, namespace: env.SYNC_NAMESPACE },
+      { connection, namespace: connections().nats.namespace },
     );
     bindProcessSync(sync);
     await sync.ready();
@@ -157,13 +164,13 @@ const connectReadySync = async (application: string): Promise<{ sync: Sync; conn
  * serves readiness before this returns.
  */
 export const startProcessSync = async ({ application }: { application: string }): Promise<ProcessSync> => {
-  if (!env.SYNC_NAMESPACE.trim()) {
+  if (!connections().nats.namespace.trim()) {
     throw new Error(
       `SYNC_NAMESPACE is not set (application "${application}"). Every process of one Cloud installation ` +
         "must share the same @k2b/sync namespace.",
     );
   }
-  if (env.NATS_SERVERS.length === 0) {
+  if (connections().nats.servers.length === 0) {
     throw new Error(
       `NATS_SERVERS is not set (application "${application}"). @k2b/sync needs a comma-separated list of ` +
         "nats://host:port bootstrap servers, e.g. NATS_SERVERS=nats://ipa_nats_1:4222,nats://ipa_nats_2:4222.",
@@ -173,6 +180,7 @@ export const startProcessSync = async ({ application }: { application: string })
   starting = true;
   try {
     const { sync: active, connection } = await waitForNats(() => connectReadySync(application), { application });
+    processNats = connection;
     let stopPromise: Promise<void> | undefined;
     return {
       sync: active,
@@ -185,6 +193,7 @@ export const startProcessSync = async ({ application }: { application: string })
               await flushSyncTraceEvents();
             } finally {
               if (current === active) unbindProcessSync();
+              if (processNats === connection) processNats = undefined;
               await connection.drain();
             }
           }

package/src/_internal/public-surface.ts

@@ -0,0 +1,76 @@
+import type { Server } from "bun";
+import type { Handler, Hono } from "hono";
+import { isCloudCredentialCookie, normalizeAppDomainHost, PUBLIC_HOST_HEADER, PUBLIC_SURFACE_PREFIX } from "../contracts/app-domains";
+import { canonicalRoute } from "./app-path";
+
+type RequestServer = Pick<Server<unknown>, "upgrade" | "requestIP" | "timeout">;
+const isRequestServer = (value: unknown): value is RequestServer =>
+  typeof value === "object" &&
+  value !== null &&
+  "upgrade" in value &&
+  typeof value.upgrade === "function" &&
+  "requestIP" in value &&
+  typeof value.requestIP === "function" &&
+  "timeout" in value &&
+  typeof value.timeout === "function";
+
+/** Bun associates transport operations with its native Request, before the public-origin view is built. */
+const publicEnvironment = (environment: object | undefined, request: Request, original: Request): object | undefined => {
+  if (!environment) return environment;
+  const bindServer = (server: RequestServer) =>
+    new Proxy(server, {
+      get(target, property) {
+        const native = (candidate: Request) => (candidate === request ? original : candidate);
+        if (property === "upgrade")
+          return (candidate: Request, options: Parameters<RequestServer["upgrade"]>[1]) => target.upgrade(native(candidate), options);
+        if (property === "requestIP") return (candidate: Request) => target.requestIP(native(candidate));
+        if (property === "timeout") return (candidate: Request, seconds: number) => target.timeout(native(candidate), seconds);
+        const value: unknown = Reflect.get(target, property, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+  if (isRequestServer(environment)) return bindServer(environment);
+  if ("server" in environment && isRequestServer(environment.server)) {
+    const server = bindServer(environment.server);
+    return new Proxy(environment, {
+      get: (target, property) => (property === "server" ? server : Reflect.get(target, property, target)),
+    });
+  }
+  return environment;
+};
+
+/** Framework mounts must never be advertised as application routes. */
+export const validatePublicSurfaceRoutes = (routes: readonly string[]): void => {
+  for (const route of routes) {
+    const path = new URL(canonicalRoute(decodeURIComponent(route).replaceAll("\\", "/")), "https://cloud.invalid").pathname;
+    if (path === PUBLIC_SURFACE_PREFIX || path.startsWith(`${PUBLIC_SURFACE_PREFIX}/`)) {
+      throw new Error(`Route "${route}" uses the reserved ${PUBLIC_SURFACE_PREFIX} prefix`);
+    }
+  }
+};
+
+/** Dispatch before Cloud context/authentication, using a fresh public-origin request. */
+export const createPublicSurfaceHandler =
+  (router: Pick<Hono, "fetch"> | undefined, development: boolean): Handler =>
+  (c) => {
+    const authority = c.req.header(PUBLIC_HOST_HEADER);
+    const parts = authority?.match(/^([^:]+)(?::([0-9]{1,5}))?$/);
+    const host = parts?.[1];
+    if (!router || !authority || !host || normalizeAppDomainHost(host) !== host || (parts?.[2] && Number(parts[2]) > 65535))
+      return c.notFound();
+    const original = new URL(c.req.url);
+    const url = new URL(`${development && host.endsWith(".localhost") ? "http" : "https"}://${authority}`);
+    url.pathname = original.pathname.slice(PUBLIC_SURFACE_PREFIX.length) || "/";
+    url.search = original.search;
+    const headers = new Headers(c.req.raw.headers);
+    const cookies = headers
+      .get("cookie")
+      ?.split(";")
+      .filter((cookie) => !isCloudCredentialCookie(cookie.split("=", 1)[0]!.trim()));
+    if (cookies?.some((cookie) => cookie.trim())) headers.set("cookie", cookies.join(";").trim());
+    else headers.delete("cookie");
+    headers.delete(PUBLIC_HOST_HEADER);
+    headers.set("host", authority);
+    const request = new Request(url, new Request(c.req.raw, { headers }));
+    return router.fetch(request, publicEnvironment(c.env, request, c.req.raw));
+  };

package/src/_internal/purpose-name.ts

@@ -0,0 +1,7 @@
+const PURPOSE_NAME = /^[a-z0-9][a-z0-9.-]{0,63}$/;
+
+export const isPurposeName = (name: string): boolean => typeof name === "string" && PURPOSE_NAME.test(name);
+
+export const validatePurposeName = (name: string): void => {
+  if (!isPurposeName(name)) throw new TypeError("Purpose name must match [a-z0-9][a-z0-9.-]{0,63}");
+};

package/src/_internal/readiness.ts

@@ -3,4 +3,9 @@ import { buildMetadata } from "./build-metadata";
 export const APP_READINESS_PATH = "/_cloud/ready";
 
 export const appReadinessResponse = (appId: string): Response =>
-  Response.json({ status: "ready", appId, version: buildMetadata.version, release: buildMetadata.release });
+  Response.json({
+    status: "ready",
+    appId,
+    version: buildMetadata.version,
+    release: buildMetadata.release,
+  });

package/src/_internal/registry-validation.ts

@@ -20,6 +20,7 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
   for (const field of ["id", "name", "icon", "description", "baseUrl"] as const) {
     if (!isString(value[field]) || value[field].length === 0) return invalid(field, "a non-empty string");
   }
+  if (value.public !== undefined && value.public !== true) return invalid("public", "true when present");
   if (value.package !== undefined && (typeof value.package !== "string" || !/^[a-z][a-z0-9-]{0,79}$/.test(value.package))) {
     return invalid("package", "a lowercase package name of 1–80 characters");
   }