@k2b/cloud 0.40.0 → 0.42.0

package/src/_internal/define-app.ts

@@ -1,9 +1,12 @@
 import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, validateAppSkillCatalog } from "../ai/app-skills";
+import { type AppAccessDeclaration, compileAppAccess } from "../contracts/app-access";
 import { startLiveOutbox } from "../events/live";
 import { registerHelp } from "../services/help";
 import { preloadLayoutHelp } from "../ssr/help";
+import { registerPageSwap } from "../ssr/page-swap";
 import { preloadPanelConsent } from "../ssr/panel-consent";
 import { invokeCapabilityStream } from "./capability-streams";
+import { withCapabilityRequestTimeout } from "./capability-timeout";
 import { bindProcessApplicationId, clearProcessApplicationId } from "./process-identity";
 /**
  * defineApp() — The single entry point for every cloud app.
@@ -49,8 +52,10 @@ import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
 import type { Role } from "../contracts/shared";
 import type { HelpDefinition } from "../server/help";
 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 "../events/app-access";
 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";
@@ -84,15 +89,17 @@ import { appRuntimeMetadata, buildMetadata } from "./build-metadata";
 import { compileCapabilities, invokeCompiledCapability, reviewCompiledCapability, serializeCapabilityProviderResult } from "./capabilities";
 import { cliPluginRoutePrefixes, createCliPluginRoutes, validateAppCliModules } from "./cli-plugins";
 import { FONT_PRELOAD_LINKS } from "./font-preloads";
-import { createHeartbeat } from "./heartbeat";
+import { createHeartbeat, createRegistryMembership } from "./heartbeat";
 import { compileHelp } from "./help";
+import { createHttpDrain } from "./http-drain";
 import { createPageResponses } from "./page-responses";
 import { configurePostgresApplicationName } from "./postgres-application-name";
 import { getProcessSync, startProcessSync } from "./process-sync";
 import { APP_READINESS_PATH, appReadinessResponse } from "./readiness";
-import { appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
+import { appInstanceRegistry, appMembershipLock, appRegistry, type CapabilityRegistryRecord, capabilityRegistry } from "./registry";
 import { canonicalRoute, isOwnAppPath } from "./registry-validation";
 import { ensureRuntimeWatcher, getCurrentRuntime, registeredCoreRelease, stopRuntimeWatcher } from "./runtime-watcher";
+import { runSetupExclusively } from "./setup-lock";
 import { publicFileVersion, servePublicAsset, sharedStylesheetVersion, versionedPublicHref } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
 import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
@@ -128,6 +135,7 @@ type ResolvedPageOptions = PageOptions & { performanceRoute?: string; themePrefe
  */
 export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefinitionMap = {}, AppId extends string = string> = {
   id: AppId;
+  access?: AppAccessDeclaration;
   name: string;
   icon: string;
   description: string;
@@ -136,6 +144,8 @@ export type AppOptions<S extends AppSettingsMap = {}, N extends NotificationDefi
   appearance?: AppAppearance;
   /** URL prefix for SSR asset isolation. Omit for the global `/_ssr/` path (core). */
   basePath?: string;
+  /** Swap Layout content within this app while keeping the rail, tab bar and panel document. Default: false; focusMode pages still load a document. */
+  pageSwap?: boolean;
   /** Base URL as seen by other containers (e.g. "http://app-notebooks:3000"). */
   baseUrl: string;
   adminHref?: string;
@@ -529,6 +539,8 @@ export const defineApp = <
   // cannot override.
   const ssr = Object.assign(
     createStatusPreservingSsrHandler<ResolvedPageOptions>(html, async (c) => {
+      if (opts.pageSwap)
+        registerPageSwap(c, isDevelopment ? String(developmentStamp) : `${buildMetadata.version}:${buildMetadata.release}`);
       c.get("page").lang = getLocale(c);
       c.get("page").themePreference = readThemePreferenceFromCookieHeader(c.req.header("Cookie"));
       const user = c.get("user");
@@ -577,13 +589,19 @@ export const defineApp = <
     openapi: opts.openapi,
     cli: opts.cli,
   };
-  const meta: AppMeta = { ...baseMeta, presentation: compileAppPresentation(baseMeta, opts.presentation) };
+  const meta: AppMeta = {
+    ...baseMeta,
+    access: compileAppAccess(opts.access),
+    presentation: compileAppPresentation(baseMeta, opts.presentation),
+  };
 
   // ── 3. start() — builds and boots the Hono server ────────────────────
   const start = async (startOpts: StartOptions): Promise<StartResult> => {
     const port = startOpts.port ?? 3000;
     const baseUrl = opts.baseUrl;
     const log = logger("app");
+    const http = createHttpDrain();
+    if (!meta.access) log.warn("Application has no access declaration; legacy entry and discovery rules remain active", { appId: meta.id });
 
     // 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
@@ -631,6 +649,7 @@ export const defineApp = <
       // Registry entry
       const entry: AppRegistryEntry = {
         id: meta.id,
+        access: meta.access,
         name: meta.name,
         icon: meta.icon,
         description: meta.description,
@@ -686,9 +705,16 @@ export const defineApp = <
         cliModules: cliModules.length > 0 ? cliModules : undefined,
       };
 
+      // Both shared entries follow one process membership; creating it touches no Sync resources.
+      const membership = createRegistryMembership(meta.id, {
+        registry: appInstanceRegistry,
+        lock: appMembershipLock,
+        startedAt: entry.startedAt,
+      });
       // Heartbeat
       const heartbeat = createHeartbeat(meta.id, entry, {
         registry: appRegistry(),
+        membership,
         beforeWrite: async () => {
           if (compiledHelp) await registerHelp(compiledHelp.corpus);
           if (appSkills && skillsManifestHash) await registerAppSkills(meta.id, appSkills, skillsManifestHash);
@@ -717,6 +743,7 @@ export const defineApp = <
         ? createHeartbeat(meta.id, capabilityEntry, {
             key: `capabilities/${meta.id}`,
             registry: capabilityRegistry(),
+            membership,
             onError: (error) =>
               log.error("Capability registry heartbeat failed", {
                 appId: meta.id,
@@ -757,6 +784,7 @@ export const defineApp = <
       // Framework-owned mounts answer before the app's router ever runs, so the
       // 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 server = new Hono<AuthContext>()
         .use("*", routeTemplate)
         .get(APP_READINESS_PATH, () => appReadinessResponse(meta.id))
@@ -765,11 +793,14 @@ export const defineApp = <
         .all("/public/*", servePublicAsset(isDevelopment, sharedStylesheetVersion(buildMetadata.release)))
         .use(
           "/_internal/sync/*",
-          requireInvocation((c) => ({
-            targetAppId: meta.id,
-            operation: syncInvocationOperation(c.req.method, new URL(c.req.url).pathname.slice("/_internal/sync".length)),
-            schemaHash: null,
-          })),
+          requireInvocation(
+            (c) => ({
+              targetAppId: meta.id,
+              operation: syncInvocationOperation(c.req.method, new URL(c.req.url).pathname.slice("/_internal/sync".length)),
+              schemaHash: null,
+            }),
+            invocationApp,
+          ),
         )
         .use("/_internal/sync/*", auth.requireOAuthScope("admin"))
         .use("/_internal/sync/*", async (c, next) => {
@@ -778,79 +809,73 @@ export const defineApp = <
         })
         .route("/_internal/sync", createSyncOpsRoutes(getProcessSync));
 
-      if (opts.cli && cliModules.length > 0) server.route(CLOUD_CLI_PLUGIN_ROUTE, createCliPluginRoutes(meta.id, opts.cli));
-
-      if (compiledHelp) {
-        const pageBase = compiledHelp.summary.pageBase;
-        const centralPageBase = `/help/apps/${encodeURIComponent(meta.id)}`;
-        server.get(pageBase, (c) => c.redirect(centralPageBase, 302));
-        server.get(`${pageBase}/:topic`, (c) => c.redirect(`${centralPageBase}/${encodeURIComponent(c.req.param("topic"))}`, 302));
-      }
-
       if (compiledCapabilities) {
-        const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") => {
-          // Framework-owned endpoints run before the app's settings middleware,
-          // so the operator default is read directly instead of via a snapshot.
-          const requestLocale = resolveLocale(c.req.raw.headers, await get<string>("app.locale"));
-          const messages = capabilityMessages(requestLocale);
-          const parsedBody = await readBoundedJson(c.req.raw, CAPABILITY_MAX_REQUEST_BYTES);
-          if (!parsedBody.ok) {
-            const message = parsedBody.reason === "too_large" ? messages.requestTooLarge : messages.requestBodyJson;
-            return c.json({ code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, message }, 400);
-          }
-          if (
-            typeof parsedBody.data !== "object" ||
-            parsedBody.data === null ||
-            Array.isArray(parsedBody.data) ||
-            !Object.hasOwn(parsedBody.data, "input") ||
-            Object.keys(parsedBody.data).length !== 1
-          ) {
-            return c.json(
-              {
-                code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed,
-                message: messages.requestInputOnly,
+        const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") =>
+          withCapabilityRequestTimeout(c, kind, async () => {
+            // Framework-owned endpoints run before the app's settings middleware,
+            // so the operator default is read directly instead of via a snapshot.
+            const requestLocale = resolveLocale(c.req.raw.headers, await get<string>("app.locale"));
+            const messages = capabilityMessages(requestLocale);
+            const parsedBody = await readBoundedJson(c.req.raw, CAPABILITY_MAX_REQUEST_BYTES);
+            if (!parsedBody.ok) {
+              const message = parsedBody.reason === "too_large" ? messages.requestTooLarge : messages.requestBodyJson;
+              return c.json({ code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, message }, 400);
+            }
+            if (
+              typeof parsedBody.data !== "object" ||
+              parsedBody.data === null ||
+              Array.isArray(parsedBody.data) ||
+              !Object.hasOwn(parsedBody.data, "input") ||
+              Object.keys(parsedBody.data).length !== 1
+            ) {
+              return c.json(
+                {
+                  code: CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed,
+                  message: messages.requestInputOnly,
+                },
+                400,
+              );
+            }
+            const body = parsedBody.data as { input: unknown };
+            const actor = c.get("actor");
+            const user = actor.kind === "user" ? actor.user : actor.delegatedUser;
+            const idempotencyKey = c.req.header("idempotency-key") || undefined;
+            const invocation = {
+              compiled: compiledCapabilities,
+              localId: c.req.param("capabilityId") ?? "",
+              input: body.input,
+              expectedSchemaHash: c.req.header("x-cloud-capability-schema-hash") ?? null,
+              context: {
+                authority: auth.getAuthority(c),
+                actor,
+                accessSubject: c.get("accessSubject"),
+                user,
+                idempotencyKey,
+                locale: requestLocale,
+                requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(),
+                origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)),
+                signal: c.req.raw.signal,
               },
-              400,
-            );
-          }
-          const body = parsedBody.data as { input: unknown };
-          const actor = c.get("actor");
-          const user = actor.kind === "user" ? actor.user : actor.delegatedUser;
-          const idempotencyKey = c.req.header("idempotency-key") || undefined;
-          const invocation = {
-            compiled: compiledCapabilities,
-            localId: c.req.param("capabilityId") ?? "",
-            input: body.input,
-            expectedSchemaHash: c.req.header("x-cloud-capability-schema-hash") ?? null,
-            context: {
-              actor,
-              accessSubject: c.get("accessSubject"),
-              user,
-              idempotencyKey,
-              locale: requestLocale,
-              requestId: normalizeInvocationRequestId(c.req.header("x-request-id")) ?? crypto.randomUUID(),
-              origin: CapabilityOriginSchema.catch("http").parse(c.req.header(CAPABILITY_ORIGIN_HEADER)),
-              signal: c.req.raw.signal,
-            },
-            onUnexpectedError: (error: unknown) =>
-              log.error(kind === "review" ? "Capability review failed" : "Capability execution failed", {
-                appId: meta.id,
-                kind,
-                capabilityId: c.req.param("capabilityId") ?? "",
-                error: error instanceof Error ? error.message : String(error),
-              }),
-          };
-          const result =
-            kind === "review" ? await reviewCompiledCapability(invocation) : await invokeCompiledCapability({ ...invocation, kind });
-          const operation = kind === "action" ? compiledCapabilities.actions.get(invocation.localId) : undefined;
-          const serialized = serializeCapabilityProviderResult(result, {
-            nonIdempotentAction: kind === "action" && operation?.manifest.idempotency === "none",
-          });
-          return new Response(serialized.body, {
-            status: serialized.status,
-            headers: { "content-type": "application/json" },
+              onUnexpectedError: (error: unknown) =>
+                log.error(kind === "review" ? "Capability review failed" : "Capability execution failed", {
+                  appId: meta.id,
+                  kind,
+                  capabilityId: c.req.param("capabilityId") ?? "",
+                  error: error instanceof Error ? error.message : String(error),
+                }),
+            };
+            const result =
+              kind === "review" ? await reviewCompiledCapability(invocation) : await invokeCompiledCapability({ ...invocation, kind });
+            const operation = kind === "action" ? compiledCapabilities.actions.get(invocation.localId) : undefined;
+            const serialized = serializeCapabilityProviderResult(result, {
+              review: kind === "review",
+              nonIdempotentAction: kind === "action" && operation?.manifest.idempotency === "none",
+            });
+            return new Response(serialized.body, {
+              status: serialized.status,
+              headers: { "content-type": "application/json" },
+            });
           });
-        };
         const capabilityAuth = (kind: "queries" | "actions", review = false) =>
           requireInvocation((c) => {
             const localId = c.req.param("capabilityId") ?? "";
@@ -869,7 +894,7 @@ export const defineApp = <
               operation: invocationOperation,
               schemaHash: operation.manifest.schemaHash,
             };
-          });
+          }, invocationApp);
         for (const kind of ["queries", "actions"] as const) {
           server.post(
             `/api/_internal/capabilities/v1/streams/${kind}/:capabilityId/:verb`,
@@ -884,6 +909,7 @@ export const defineApp = <
                 verb: c.req.param("verb") ?? "",
                 request: c.req.raw,
                 context: {
+                  authority: auth.getAuthority(c),
                   actor,
                   accessSubject: c.get("accessSubject"),
                   user: actor.kind === "user" ? actor.user : actor.delegatedUser,
@@ -923,7 +949,7 @@ export const defineApp = <
             const widgetId = c.req.param("widgetId") ?? "";
             if (!declaredWidgetIds.has(widgetId) || !startOpts.widgets?.[widgetId]) return null;
             return { targetAppId: meta.id, operation: widgetInvocationOperation(widgetId), schemaHash: null };
-          }),
+          }, invocationApp),
           auth.requireOAuthScope("read", "admin"),
           runtimeMiddleware(),
           settingsMiddleware(),
@@ -938,10 +964,31 @@ export const defineApp = <
         );
       }
 
+      cleanup.push(() => stopAppAccessConnections());
+      server.use(
+        "*",
+        requireAppAccess(meta, (c, message) =>
+          ssr.error(c, 403, {
+            title: "No access",
+            description: message,
+            layout: "minimal",
+          }),
+        ),
+      );
+
+      if (opts.cli && cliModules.length > 0) server.route(CLOUD_CLI_PLUGIN_ROUTE, createCliPluginRoutes(meta.id, opts.cli));
+
+      if (compiledHelp) {
+        const pageBase = compiledHelp.summary.pageBase;
+        const centralPageBase = `/help/apps/${encodeURIComponent(meta.id)}`;
+        server.get(pageBase, (c) => c.redirect(centralPageBase, 302));
+        server.get(`${pageBase}/:topic`, (c) => c.redirect(`${centralPageBase}/${encodeURIComponent(c.req.param("topic"))}`, 302));
+      }
+
       // OpenAPI spec mount. Registered on the framework server (before the
       // user-fetch catch-all below) so it bypasses any auth / rate-limit
       // middleware on the api router — the spec must stay reachable without
-      // a session for `app-api-docs` to render it.
+      // a session for legacy apps. Declared app access is enforced above.
       //
       // The `servers` override is load-bearing: hono-openapi walks the
       // BARE api router and emits paths relative to its own root (e.g.
@@ -997,7 +1044,8 @@ export const defineApp = <
 
       if (!startOpts.skipSetup && startOpts.lifecycle?.setup) {
         log.info(`Setup: ${meta.id}`);
-        await startOpts.lifecycle.setup(cloudCtx);
+        const setup = startOpts.lifecycle.setup;
+        await runSetupExclusively(meta.id, () => setup(cloudCtx));
       }
       if (meta.id === "core") await startOutbox();
 
@@ -1020,18 +1068,36 @@ export const defineApp = <
       log.info(`Registered "${meta.id}"`, { baseUrl });
 
       // Graceful shutdown
-      let stopping = false;
-      const shutdown = async () => {
-        if (stopping) return;
-        stopping = true;
-        log.info(`Stopping: ${meta.id}`);
-        await stopStartedResources();
-      };
+      let shutdownPromise: Promise<void> | undefined;
+      const shutdown = () =>
+        (shutdownPromise ??= (async () => {
+          const drained = http.stop();
+          log.info(`Stopping: ${meta.id}`);
+          try {
+            await drained;
+          } finally {
+            await stopStartedResources();
+          }
+        })());
 
-      process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
-      process.on("SIGINT", () => void shutdown().then(() => process.exit(0)));
+      const stopAndExit = () =>
+        void shutdown().then(
+          () => process.exit(0),
+          (error: unknown) => {
+            log.error("HTTP shutdown failed", { appId: meta.id, error: error instanceof Error ? error.message : String(error) });
+            process.exit(1);
+          },
+        );
+      process.on("SIGTERM", stopAndExit);
+      process.on("SIGINT", stopAndExit);
 
-      return { hostname: "0.0.0.0", port, development: isDevelopment, idleTimeout: REQUEST_IDLE_TIMEOUT_SECONDS, fetch: server.fetch };
+      return {
+        hostname: "0.0.0.0",
+        port,
+        development: isDevelopment,
+        idleTimeout: REQUEST_IDLE_TIMEOUT_SECONDS,
+        fetch: (request, bunServer) => http.fetch(request, bunServer, (request) => server.fetch(request, bunServer)),
+      };
     } catch (error) {
       await stopStartedResources();
       throw error;