@k2b/cloud 0.47.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.47.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": {
@@ -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.0",
     "@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.1.1"
   },
   "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/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

@@ -27,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";
@@ -48,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,
@@ -68,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";
@@ -83,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";
@@ -164,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;
@@ -372,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()`
@@ -478,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);
@@ -692,6 +704,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 +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.",
@@ -751,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,
@@ -818,6 +833,7 @@ export const defineApp = <
         registry: appInstanceRegistry,
         lock: appMembershipLock,
         startedAt: entry.startedAt,
+        bootstrap: connections().bootstrap,
       });
       // Heartbeat
       const heartbeat = createHeartbeat(meta.id, entry, {
@@ -894,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))
@@ -1179,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;
@@ -1264,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");

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

package/src/_internal/registry.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import type { EphemeralConfig, MutexConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
+import { appStatusIssues } from "../contracts/app-status";
 import { calendarSourceIssues } from "../contracts/calendar-source";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
 import { discussionsIssues } from "../contracts/discussions";
@@ -16,6 +17,7 @@ import {
   WIDGET_TITLE_MAX_LENGTH,
   type WidgetSettingsDeclaration,
 } from "../contracts/widgets";
+import type { PlatformBootstrapMetadata } from "../runtime/connections";
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
 import { lazySync } from "./process-sync";
@@ -63,6 +65,8 @@ export type AppInstanceRecord = {
   hostname: string;
   startedAt: number;
   entries: Record<string, string>;
+  /** Missing on older instances means unknown, never env or successful bootstrap. */
+  bootstrap?: PlatformBootstrapMetadata;
 };
 
 // The id and owner are a cross-version contract: all replicas must use the same lock.
@@ -103,6 +107,8 @@ export type AppRegistryDetail = AppRegistryEntry & {
   updatedAt: number;
   expiresAt: number;
   version: string;
+  /** Per-process startup metadata for admin readers. null means an older/unknown producer. */
+  instances?: { instanceId: string; hostname: string; startedAt: number; bootstrap: PlatformBootstrapMetadata | null }[];
 };
 
 export type AppRegistryIssue = {
@@ -238,6 +244,7 @@ const reportLeftOutEntries = (sent: unknown, manifest: CapabilityManifest): void
   });
   if (groups.calendarSource !== undefined && !manifest.calendarSource) leftOut.push("calendarSource");
   if (groups.fileProvider !== undefined && !manifest.fileProvider) leftOut.push("fileProvider");
+  if (groups.appStatus !== undefined && !manifest.appStatus) leftOut.push("appStatus");
   if (groups.discussions !== undefined && !manifest.discussions) leftOut.push("discussions");
   if (leftOut.length === 0) return;
   console.warn(
@@ -348,6 +355,32 @@ const withValidDiscussions = (manifest: CapabilityManifest): CapabilityManifest
   return rest;
 };
 
+const checkedAppStatus = new Map<string, { manifestHash: string; valid: boolean }>();
+const withValidAppStatus = (manifest: CapabilityManifest): CapabilityManifest => {
+  if (!manifest.appStatus) return manifest;
+  const checked = checkedAppStatus.get(manifest.appId);
+  let valid = checked?.manifestHash === manifest.manifestHash ? checked.valid : undefined;
+  if (valid === undefined) {
+    const issues = appStatusIssues(manifest);
+    valid = issues.length === 0;
+    checkedAppStatus.set(manifest.appId, { manifestHash: manifest.manifestHash, valid });
+    if (!valid)
+      console.error(
+        JSON.stringify({
+          level: "error",
+          source: "capability-registry",
+          message: "Ignored an incompatible appStatus provider",
+          appId: manifest.appId,
+          manifestHash: manifest.manifestHash,
+          issues,
+        }),
+      );
+  }
+  if (valid) return manifest;
+  const { appStatus: _ignored, ...rest } = manifest;
+  return rest;
+};
+
 /** Ignores record fields from a newer release; the endpoint always comes from the live app registry. */
 export const resolveLiveCapabilityRegistryEntry = (
   key: string,
@@ -362,7 +395,7 @@ export const resolveLiveCapabilityRegistryEntry = (
   if (!endpoint) return null;
   try {
     const read = parseCapabilityManifest(record.manifest, app.id);
-    const supported = withValidDiscussions(withValidCalendarSource(withValidFileProvider(read)));
+    const supported = withValidAppStatus(withValidDiscussions(withValidCalendarSource(withValidFileProvider(read))));
     const manifest = supported.resourcePages
       ? {
           ...supported,
@@ -411,8 +444,21 @@ export const getCapability = async (appId: string): Promise<CapabilityRegistryEn
  * Same as `listApps` but returns registry metadata for admin observability.
  */
 export const listAppsDetailed = async (): Promise<AppRegistryDetail[]> => {
-  const snapshot = await readAppRegistrySnapshot();
-  return snapshot.apps;
+  const [snapshot, instances] = await Promise.all([
+    readAppRegistrySnapshot(),
+    appInstanceRegistry().snapshot({ prefix: APP_INSTANCE_PREFIX }),
+  ]);
+  return snapshot.apps.map((app) => ({
+    ...app,
+    instances: instances.entries
+      .filter(({ value }) => value.appId === app.id)
+      .map(({ value }) => ({
+        instanceId: value.instanceId,
+        hostname: value.hostname,
+        startedAt: value.startedAt,
+        bootstrap: value.bootstrap ?? null,
+      })),
+  }));
 };
 
 /**

package/src/_internal/workload-credential.ts

@@ -1,4 +1,5 @@
 import { env } from "../config/env";
+import { connections } from "../runtime/connections";
 import { getProcessApplicationId } from "./process-identity";
 import { getProcessNats } from "./process-sync";
 import {
@@ -50,7 +51,7 @@ export const createAppWorkloadCredential = (options: {
   const request =
     options.request ??
     (async (input: WorkloadRequest) => {
-      const response = await getProcessNats().request(workloadSubject(env.SYNC_NAMESPACE), JSON.stringify(input), {
+      const response = await getProcessNats().request(workloadSubject(connections().nats.namespace), JSON.stringify(input), {
         timeout: WORKLOAD_REQUEST_TIMEOUT_MS,
       });
       return response.json<unknown>();

package/src/api/admin-app-domains.ts

@@ -0,0 +1,62 @@
+import { Hono, type MiddlewareHandler } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { type AuthContext, auth, respond, v } from "../server";
+import { noTransform } from "../server/middleware/no-transform";
+import { appDomains } from "../services/app-domains";
+import { logger } from "../services/logging";
+
+const appParams = z.object({ appId: z.string().regex(/^[a-z][a-z0-9-]{0,79}$/) });
+const domainParams = appParams.extend({ host: z.string().max(1024) });
+const host = z.string().max(1024);
+const addInput = z.object({ host, redirectTo: host.optional() }).strict();
+const setInput = z.object({ redirectTo: host.nullable() }).strict();
+const describe = (summary: string) => describeRoute({ tags: ["App domains"], summary });
+
+export const createAdminAppDomainRoutes = (
+  authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin"),
+  service: typeof appDomains = appDomains,
+) =>
+  new Hono<AuthContext>()
+    .use("/:appId/domains/*", noTransform())
+    .use("/:appId/domains/*", authenticate)
+    .use("/:appId/domains/*", async (c, next) => {
+      c.header("Cache-Control", "no-store");
+      if (c.req.method !== "GET") return auth.requireOAuthScope("admin")(c, next);
+      return next();
+    })
+    .get("/:appId/domains", describe("List assigned domains and their last check"), v("param", appParams), (c) =>
+      respond(c, () => service.list({ actor: c.get("user"), ...c.req.valid("param") })),
+    )
+    .post(
+      "/:appId/domains",
+      describe("Assign a domain and start its first check in the background"),
+      v("param", appParams),
+      v("json", addInput),
+      async (c) => {
+        const input = { actor: c.get("user"), ...c.req.valid("param"), ...c.req.valid("json") };
+        const result = await service.add(input);
+        if (result.ok)
+          void service.check({ ...input, host: result.data.host }).catch((error: unknown) => {
+            logger("core:app-domains").error("Initial domain check failed; retry through the domain check endpoint", {
+              host: result.data.host,
+              error: error instanceof Error ? error.message : String(error),
+            });
+          });
+        return respond(c, result, 201);
+      },
+    )
+    .patch("/:appId/domains/:host", describe("Change or clear the domain redirect"), v("param", domainParams), v("json", setInput), (c) =>
+      respond(c, () => service.set({ actor: c.get("user"), ...c.req.valid("param"), ...c.req.valid("json") })),
+    )
+    .delete("/:appId/domains/:host", describe("Remove an unreferenced domain assignment"), v("param", domainParams), (c) =>
+      respond(c, () => service.remove({ actor: c.get("user"), ...c.req.valid("param") })),
+    )
+    .post(
+      "/:appId/domains/:host/check",
+      describe("Check DNS, certificate and gateway reachability, at most once per 60 seconds"),
+      v("param", domainParams),
+      (c) => respond(c, () => service.check({ actor: c.get("user"), ...c.req.valid("param") })),
+    );
+
+export default createAdminAppDomainRoutes();