@k2b/cloud 0.47.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -131,7 +131,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
     "@k2b/ssr": "0.20.2",
-    "@k2b/ui": "0.37.0",
+    "@k2b/ui": "0.38.1",
     "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.1",
     "@nats-io/jetstream": "3.4.0",
@@ -163,7 +163,7 @@
     "hash-wasm": "4.12.0",
     "@types/sanitize-html": "2.16.1",
     "@types/web-push": "3.6.4",
-    "@k2b/editor": "0.1.0"
+    "@k2b/editor": "0.2.0"
   },
   "devDependencies": {
     "@babel/core": "8.0.6",

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/app-access-resources.ts

@@ -1,8 +1,9 @@
 import { isDeepStrictEqual } from "node:util";
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { waitWithin } from "../api/fanout";
 import type { AppMeta } from "../contracts/app";
 import { type AppAccessDeclaration, type AppAccessRule, AppAccessRuleSchema, type ResourceAppAccessAdapter } from "../contracts/app-access";
+import { sql } from "../runtime/clients";
 import type { RequestAuthority } from "../server/middleware/auth";
 import { coreOrigin } from "../services/identity/core-origin";
 import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";

package/src/_internal/app-capabilities.ts

@@ -0,0 +1,73 @@
+import { Hono } from "hono";
+import { CAPABILITY_MAX_REQUEST_BYTES } from "../contracts/capabilities";
+import { resolveLocale } from "../server/locale";
+import { getActiveAppKey } from "../services/app-keys";
+import { verifyAppCapabilityInvocation } from "../services/identity/invocation-token";
+import { get } from "../services/settings";
+import { readBoundedJson } from "./bounded-json";
+import { type CompiledCapabilities, invokeCompiledCapability, serializeCapabilityProviderResult } from "./capabilities";
+import { withCapabilityRequestTimeout } from "./capability-timeout";
+
+/** Separate from ordinary auth: application authority never becomes a grant-bearing person. */
+export const createAppCapabilityRoutes = (compiled: CompiledCapabilities) => {
+  const router = new Hono();
+  for (const kind of ["query", "action"] as const) {
+    router.post(`/${kind === "query" ? "queries" : "actions"}/:capabilityId`, (c) =>
+      withCapabilityRequestTimeout(c, kind, async () => {
+        const operation = (kind === "query" ? compiled.queries : compiled.actions).get(c.req.param("capabilityId"));
+        const deny = () => c.json({ code: "FORBIDDEN", message: "A permitted signed app capability invocation is required" }, 403);
+        if (!operation?.manifest.appPermission || operation.manifest.stream) return deny();
+        const body = await readBoundedJson(c.req.raw, CAPABILITY_MAX_REQUEST_BYTES);
+        if (
+          !body.ok ||
+          !body.data ||
+          typeof body.data !== "object" ||
+          Array.isArray(body.data) ||
+          Object.keys(body.data).length !== 1 ||
+          !("input" in body.data)
+        )
+          return c.json({ code: "VALIDATION_FAILED", message: "Expected a bounded input object" }, 400);
+        const token = c.req.header("authorization")?.match(/^Bearer (\S+)$/)?.[1];
+        if (!token) return deny();
+        try {
+          const claims = await verifyAppCapabilityInvocation(token, {
+            appId: compiled.manifest.appId,
+            kind,
+            capabilityId: operation.manifest.localId,
+            schemaHash: operation.manifest.schemaHash,
+            permission: operation.manifest.appPermission,
+            input: body.data.input,
+          });
+          if (!claims) return deny();
+          const locale = resolveLocale(c.req.raw.headers, await get<string>("app.locale"));
+          if (!(await getActiveAppKey({ appId: claims.sub, keyId: claims.key_id }))) return deny();
+          const result = await invokeCompiledCapability({
+            compiled,
+            kind,
+            localId: operation.manifest.localId,
+            input: body.data.input,
+            expectedSchemaHash: claims.schema_hash,
+            context: {
+              actor: { kind: "app", appId: claims.sub, keyId: claims.key_id },
+              accessSubject: { type: "none" },
+              user: null,
+              locale,
+              requestId: claims.request_id,
+              origin: "app",
+              signal: c.req.raw.signal,
+              ...(c.req.header("idempotency-key") ? { idempotencyKey: c.req.header("idempotency-key") } : {}),
+            },
+          });
+          const response = serializeCapabilityProviderResult(result);
+          return new Response(response.body, {
+            status: response.status,
+            headers: { "content-type": "application/json", "cache-control": "no-store" },
+          });
+        } catch {
+          return c.json({ code: "APP_UNAVAILABLE", message: "App invocation verification unavailable" }, 503);
+        }
+      }),
+    );
+  }
+  return router;
+};

package/src/_internal/app-event-catalog.ts

@@ -1,5 +1,5 @@
-import { sql } from "bun";
 import type { CapabilityEventCatalogEntry, CapabilityManifest } from "../contracts/capabilities";
+import { sql } from "../runtime/clients";
 
 export type CatalogSubscription = CapabilityEventCatalogEntry["subscribers"][number] & { eventType: string; version: number };
 

package/src/_internal/app-queries.ts

@@ -1,6 +1,6 @@
-import { sql } from "bun";
 import { Hono } from "hono";
 import { CAPABILITY_MAX_REQUEST_BYTES } from "../contracts/capabilities";
+import { sql } from "../runtime/clients";
 import { resolveLocale } from "../server/locale";
 import { verifyAppQueryInvocation } from "../services/identity/invocation-token";
 import { get } from "../services/settings";

package/src/_internal/application-package.ts

@@ -1,4 +1,5 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
+import { sql } from "../runtime/clients";
 import { ensureSchema } from "../services/postgres";
 import builtInAppIds from "./built-in-app-ids.json";
 

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>;
@@ -130,6 +133,7 @@ const TYPE_FIELDS = {
   access: true,
 } satisfies DefinedFields<CapabilityResourceTypeDefinition>;
 const QUERY_FIELDS = {
+  app: true,
   appOnly: true,
   title: true,
   description: true,
@@ -141,6 +145,7 @@ const QUERY_FIELDS = {
   run: true,
 } satisfies DefinedFields<CapabilityQueryDefinition>;
 const ACTION_FIELDS = {
+  app: true,
   title: true,
   description: true,
   input: true,
@@ -679,6 +684,11 @@ const compileOperationSchemas = (definition: QueryDefinition | CapabilityActionD
   ) {
     throw new Error(`${label} input field "idempotencyKey" is reserved for capability transports`);
   }
+  if (definition.app !== undefined) {
+    assertDefinedFields(definition.app, { permission: true, run: true }, `${label} app`);
+    if (typeof definition.app.run !== "function") throw new Error(`${label} app.run must be a function`);
+    if (definition.stream) throw new Error(`${label} app calls cannot use streams`);
+  }
   const resultZodSchema = capabilityResultSchema(definition.data);
   const dataSchema = projectSchema(definition.data, `${label} data`, "output");
   return {
@@ -688,6 +698,7 @@ const compileOperationSchemas = (definition: QueryDefinition | CapabilityActionD
     schemaHash: capabilityHash({
       inputSchema,
       dataSchema,
+      ...(definition.app ? { appPermission: definition.app.permission } : {}),
       ...("appOnly" in definition && definition.appOnly !== undefined ? { appOnly: definition.appOnly } : {}),
       ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
     }),
@@ -710,6 +721,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) {
@@ -839,6 +851,7 @@ export const compileCapabilities = (
       inputSchema: schemas.inputSchema,
       dataSchema: schemas.dataSchema,
       schemaHash: schemas.schemaHash,
+      ...(definition.app ? { appPermission: definition.app.permission } : {}),
       ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
       openWorld: definition.openWorld,
       universalSearch: normalizeSearchTags(definition, label),
@@ -923,6 +936,7 @@ export const compileCapabilities = (
       inputSchema: schemas.inputSchema,
       dataSchema: schemas.dataSchema,
       schemaHash: schemas.schemaHash,
+      ...(definition.app ? { appPermission: definition.app.permission } : {}),
       ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
       destructive: definition.destructive,
       openWorld: definition.openWorld,
@@ -1037,6 +1051,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 +1073,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 +1251,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 } : {}),
@@ -1272,6 +1290,7 @@ const assertUsableOperation = (operation: CapabilityQueryManifest | CapabilityAc
   const expectedSchemaHash = capabilityHash({
     inputSchema: operation.inputSchema,
     dataSchema: operation.dataSchema,
+    ...(operation.appPermission ? { appPermission: operation.appPermission } : {}),
     ...("appOnly" in operation && operation.appOnly !== undefined ? { appOnly: operation.appOnly } : {}),
     ...(operation.stream ? { stream: operation.stream } : {}),
   });
@@ -1774,9 +1793,13 @@ export const invokeCompiledCapability = async (params: {
     let invoked: CapabilityInvocationResult<unknown>;
     if (isAppCapabilityContext(context)) {
       const definition = operation.definition;
-      if (params.kind !== "query" || !("appOnly" in definition) || definition.appOnly !== true)
+      if (definition.app && context.actor.keyId) {
+        invoked = await definition.app.run(input.data, context);
+      } else if (params.kind === "query" && "appOnly" in definition && definition.appOnly === true) {
+        invoked = await definition.run(input.data, context);
+      } else {
         return { ok: false, error: { code: "FORBIDDEN", message: "App caller is not allowed", status: 403 } };
-      invoked = await definition.run(input.data, context);
+      }
     } else {
       if (operation.definition.appOnly) return { ok: false, error: { code: "FORBIDDEN", message: "App authority required", status: 403 } };
       invoked = await operation.definition.run(input.data, context);

package/src/_internal/define-app.ts

@@ -13,6 +13,7 @@ import { registerPageSwap } from "../ssr/page-swap";
 import { preloadPanelConsent } from "../ssr/panel-consent";
 import { appAccessManagementPath } from "./app-access-path";
 import { bindResourceAppAccess, RESOURCE_ACCESS_PATH } from "./app-access-resources";
+import { createAppCapabilityRoutes } from "./app-capabilities";
 import { createAppQueryRoutes } from "./app-queries";
 import { registerApplicationPackage, resolveApplicationPackage } from "./application-package";
 import { invokeCapabilityStream } from "./capability-streams";
@@ -27,7 +28,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";
@@ -48,6 +49,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,
@@ -68,8 +70,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";
@@ -83,6 +87,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";
@@ -164,6 +169,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;
@@ -372,6 +379,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()`
@@ -478,6 +489,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);
@@ -692,6 +705,8 @@ 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.");
@@ -705,7 +720,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.",
@@ -751,6 +766,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,
@@ -818,6 +834,7 @@ export const defineApp = <
         registry: appInstanceRegistry,
         lock: appMembershipLock,
         startedAt: entry.startedAt,
+        bootstrap: connections().bootstrap,
       });
       // Heartbeat
       const heartbeat = createHeartbeat(meta.id, entry, {
@@ -894,7 +911,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))
@@ -937,6 +957,7 @@ export const defineApp = <
 
       if (compiledCapabilities) {
         server.route("/api/_internal/capabilities/v1/app-queries", createAppQueryRoutes(compiledCapabilities));
+        server.route("/api/_internal/capabilities/v1/app-capabilities", createAppCapabilityRoutes(compiledCapabilities));
         const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") =>
           withCapabilityRequestTimeout(c, kind, async () => {
             // Framework-owned endpoints run before the app's settings middleware,
@@ -1179,6 +1200,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;
@@ -1264,6 +1287,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");

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/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";
@@ -135,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();
@@ -164,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.",

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