@k2b/cloud 0.46.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.46.0",
+  "version": "0.47.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.37.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.0"
   },
   "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/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";
@@ -119,6 +120,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();
@@ -691,6 +693,10 @@ export const defineApp = <
   // ── 3. start() — builds and boots the Hono server ────────────────────
   const start = async (startOpts: StartOptions): Promise<StartResult> => {
     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();
@@ -864,6 +870,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
@@ -909,6 +916,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 +1164,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));
 
@@ -1169,6 +1190,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);

package/src/_internal/heartbeat.ts

@@ -94,6 +94,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/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

@@ -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 => {
@@ -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/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/resource-principals.ts

@@ -1,36 +1,6 @@
-import { sql } from "bun";
 import type { ResourcePrincipal } from "../contracts/capabilities";
-import { decodeAccountCategoryEnabled } from "../services/account-category-policy";
-import { toPgTextArray } from "../services/postgres";
+import { resolveResourceReaders } from "../services/identity/resource-readers";
 
-/** One bounded identity lookup before any provider-owned readability check. */
-export const activeResourcePrincipals = async (principals: ResourcePrincipal[]): Promise<ResourcePrincipal[]> => {
-  if (!principals.length) return [];
-  const users = principals.flatMap((principal) => (principal.type === "user" ? [principal.userId] : []));
-  const accounts = principals.flatMap((principal) => (principal.type === "service_account" ? [principal.serviceAccountId] : []));
-  const rows = await sql<{ type: ResourcePrincipal["type"]; id: string; category_enabled: string | null }[]>`
-    SELECT 'user' AS type, u.id, category.value AS category_enabled
-    FROM auth.users u
-    LEFT JOIN settings.entries category ON category.key = 'user.category.' ||
-      CASE WHEN u.provider = 'ipa' THEN 'freeipa' WHEN u.profile = 'guest' THEN 'guest' ELSE 'login' END || '.enabled'
-    WHERE u.id = ANY(${toPgTextArray(users)}::uuid[])
-      AND (u.account_expires IS NULL OR u.account_expires > clock_timestamp())
-    UNION ALL
-    SELECT 'service_account', sa.id, category.value
-    FROM auth.service_accounts sa
-    LEFT JOIN auth.users du ON du.id = sa.delegated_user_id
-    LEFT JOIN settings.entries category ON sa.kind = 'user_delegated' AND category.key = 'user.category.' ||
-      CASE WHEN du.provider = 'ipa' THEN 'freeipa' WHEN du.profile = 'guest' THEN 'guest' ELSE 'login' END || '.enabled'
-    WHERE sa.id = ANY(${toPgTextArray(accounts)}::uuid[]) AND sa.status = 'active'
-      AND (sa.kind <> 'user_delegated' OR (du.id IS NOT NULL AND (du.account_expires IS NULL OR du.account_expires > clock_timestamp())))
-  `;
-  const enabled = new Map<string | null, boolean>();
-  const active = new Set<string>();
-  for (const row of rows) {
-    if (!enabled.has(row.category_enabled)) enabled.set(row.category_enabled, await decodeAccountCategoryEnabled(row.category_enabled));
-    if (enabled.get(row.category_enabled)) active.add(`${row.type}:${row.id}`);
-  }
-  return principals.filter((principal) =>
-    active.has(`${principal.type}:${(principal.type === "user" ? principal.userId : principal.serviceAccountId).toLowerCase()}`),
-  );
-};
+/** Apply the same current-account rules as provider-owned readability checks. */
+export const activeResourcePrincipals = async (principals: ResourcePrincipal[]): Promise<ResourcePrincipal[]> =>
+  (await resolveResourceReaders(principals)).map((reader) => reader.principal);

package/src/_internal/workload-credential.ts

@@ -0,0 +1,153 @@
+import { env } from "../config/env";
+import { getProcessApplicationId } from "./process-identity";
+import { getProcessNats } from "./process-sync";
+import {
+  WORKLOAD_CHECK_INTERVAL_MS,
+  WORKLOAD_REQUEST_TIMEOUT_MS,
+  type WorkloadRequest,
+  WorkloadResponseSchema,
+  workloadSubject,
+} from "./workload-protocol";
+
+export type WorkloadCredentialHealth = { status: "ready"; source: "runtime" | "override" } | { status: "unavailable"; reason: string };
+let active: { appId: string; token: string; expiresAt: number } | undefined;
+let health: WorkloadCredentialHealth | undefined;
+let refreshRuntime: { appId: string; refresh: () => Promise<void> } | undefined;
+
+/** Refresh only this process's app authority; concurrent broker rejections share one request. */
+export const refreshAppWorkloadCredential = async (appId: string): Promise<string | undefined> => {
+  if (appId !== getProcessApplicationId()) return undefined;
+  if (refreshRuntime?.appId === appId) await refreshRuntime.refresh();
+  return getAppWorkloadCredential();
+};
+
+/** One server-side accessor for workers and app-authority invocation clients. Never send to a target app. */
+export const getAppWorkloadCredential = (): string | undefined => {
+  const override = env.CLOUD_APP_CREDENTIAL?.trim();
+  if (override) return override;
+  if (active && active.appId === getProcessApplicationId() && active.expiresAt > Date.now()) return active.token;
+  return undefined;
+};
+
+export const getAppWorkloadCredentialHealth = (): WorkloadCredentialHealth | undefined => {
+  if (env.CLOUD_APP_CREDENTIAL?.trim()) return { status: "ready", source: "override" };
+  if (active && active.expiresAt <= Date.now()) return { status: "unavailable", reason: "expired" };
+  return health;
+};
+
+export const createAppWorkloadCredential = (options: {
+  appId: string;
+  instanceId: string;
+  request?: (request: WorkloadRequest) => Promise<unknown>;
+  onUnavailable?: (reason: string) => void;
+  onRecovered?: () => void;
+}) => {
+  let credentialId: string | null = null;
+  let running = false;
+  let refreshFailed = false;
+  let timer: Timer | undefined;
+  let inFlight: Promise<void> | undefined;
+  const request =
+    options.request ??
+    (async (input: WorkloadRequest) => {
+      const response = await getProcessNats().request(workloadSubject(env.SYNC_NAMESPACE), JSON.stringify(input), {
+        timeout: WORKLOAD_REQUEST_TIMEOUT_MS,
+      });
+      return response.json<unknown>();
+    });
+  const unavailable = (reason: string, preserve = false) => {
+    refreshFailed = true;
+    if (preserve && active && active.expiresAt > Date.now()) return;
+    if (!preserve) {
+      active = undefined;
+      credentialId = null;
+    }
+    const changed = health?.status !== "unavailable" || health.reason !== reason;
+    health = { status: "unavailable", reason };
+    if (changed) options.onUnavailable?.(reason);
+  };
+  const recovered = () => {
+    health = { status: "ready", source: "runtime" };
+    if (refreshFailed) options.onRecovered?.();
+    refreshFailed = false;
+  };
+  const refresh = async (): Promise<void> => {
+    if (env.CLOUD_APP_CREDENTIAL?.trim()) {
+      active = undefined;
+      health = { status: "ready", source: "override" };
+      return;
+    }
+    try {
+      const response = WorkloadResponseSchema.parse(
+        await request({ operation: "refresh", appId: options.appId, instanceId: options.instanceId, credentialId }),
+      );
+      if (!running) return;
+      if (response.status === "issued") {
+        if (
+          response.appId !== options.appId ||
+          response.instanceId !== options.instanceId ||
+          Date.parse(response.expiresAt) <= Date.now()
+        ) {
+          unavailable("invalid_response");
+          return;
+        }
+        credentialId = response.credentialId;
+        active = { appId: options.appId, token: response.token, expiresAt: Date.parse(response.expiresAt) };
+        recovered();
+      } else if (response.status === "current" && response.credentialId === credentialId && active && active.expiresAt > Date.now()) {
+        recovered();
+      } else {
+        unavailable(response.status === "current" ? "invalid_response" : response.status, response.status === "unavailable");
+      }
+    } catch {
+      if (running) {
+        unavailable("issuance_unavailable", true);
+      }
+    }
+  };
+  const refreshOnce = (): Promise<void> => {
+    if (inFlight) return inFlight;
+    const operation = refresh().finally(() => {
+      if (inFlight === operation) inFlight = undefined;
+    });
+    inFlight = operation;
+    return operation;
+  };
+  const schedule = () => {
+    if (!running) return;
+    timer = setTimeout(
+      () => {
+        void refreshOnce().finally(schedule);
+      },
+      refreshFailed || health?.status === "unavailable" ? 5_000 : WORKLOAD_CHECK_INTERVAL_MS,
+    );
+  };
+  return {
+    start: async () => {
+      if (running) {
+        await inFlight;
+        return;
+      }
+      running = true;
+      refreshRuntime = { appId: options.appId, refresh: refreshOnce };
+      health = { status: "unavailable", reason: "starting" };
+      await refreshOnce();
+      schedule();
+    },
+    refresh: refreshOnce,
+    stop: async () => {
+      running = false;
+      if (refreshRuntime?.refresh === refreshOnce) refreshRuntime = undefined;
+      clearTimeout(timer);
+      await inFlight;
+      if (!env.CLOUD_APP_CREDENTIAL?.trim()) {
+        await request({ operation: "release", appId: options.appId, instanceId: options.instanceId, credentialId }).catch(() => {
+          // Core's registry reconciliation revokes after disappearance even when this reply is lost.
+          options.onUnavailable?.("release_unavailable");
+        });
+      }
+      active = undefined;
+      health = undefined;
+    },
+  };
+};

package/src/_internal/workload-protocol.ts

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { CapabilityAppIdSchema } from "../contracts/capabilities";
+
+// Core NATS request/reply only: no JetStream subject, KV value, or retained raw token.
+export const workloadSubject = (namespace: string): string => `cloud.workload.${createHash("sha256").update(namespace).digest("hex")}.v1`;
+export const WORKLOAD_CHECK_INTERVAL_MS = 60_000;
+export const WORKLOAD_REQUEST_TIMEOUT_MS = 5_000;
+export const WORKLOAD_LIFETIME_MS = 60 * 60_000;
+export const WORKLOAD_ROTATE_BEFORE_MS = WORKLOAD_LIFETIME_MS / 2;
+
+export const WorkloadRequestSchema = z
+  .object({
+    operation: z.enum(["refresh", "release"]),
+    appId: CapabilityAppIdSchema,
+    instanceId: z.string().regex(/^[A-Za-z0-9_-]{16}$/),
+    credentialId: z.uuid().nullable(),
+  })
+  .strict();
+export type WorkloadRequest = z.infer<typeof WorkloadRequestSchema>;
+
+export const WorkloadResponseSchema = z.discriminatedUnion("status", [
+  z
+    .object({
+      status: z.literal("issued"),
+      appId: CapabilityAppIdSchema,
+      instanceId: z.string(),
+      credentialId: z.uuid(),
+      token: z.string().regex(/^cld_[a-f0-9]{24}_[a-f0-9]{64}$/),
+      expiresAt: z.iso.datetime(),
+    })
+    .strict(),
+  z.object({ status: z.literal("current"), credentialId: z.uuid() }).strict(),
+  z.object({ status: z.enum(["unavailable", "revoked", "unregistered"]) }).strict(),
+]);
+export type WorkloadResponse = z.infer<typeof WorkloadResponseSchema>;

package/src/ai/application-tasks.ts

@@ -1,6 +1,6 @@
 import type { SQL } from "bun";
-import { env } from "../config/env";
 import type { AccessSubject } from "../server/services/access";
+import { coreSettings } from "../services/settings/api";
 import { WorkflowAiAdmissionError, type WorkflowAiScope, workflowAiHash, workflowAiModelHash } from "../workflows/ai/policy";
 import { submitWorkflowAiTask } from "../workflows/ai/runtime";
 import {
@@ -56,7 +56,10 @@ export const runApplicationAiTask = async (input: ApplicationAiTaskInput) => {
   let task = await getWorkflowAiTaskByEffectKey(effectKey);
   if (!task) {
     const resolved = await resolveApplicationAiTaskModel(input.usageSubject, input.request.model);
-    const admissionSignal = AbortSignal.any([input.signal, AbortSignal.timeout(env.WORKFLOW_AI_QUEUE_TIMEOUT_MS)]);
+    const admissionSignal = AbortSignal.any([
+      input.signal,
+      AbortSignal.timeout(await coreSettings.get<number>("ai.workflow_queue_timeout_ms")),
+    ]);
     for (;;) {
       input.signal.throwIfAborted();
       if (admissionSignal.aborted) throw new WorkflowAiAdmissionError("WORKFLOW_AI_QUEUE_TIMEOUT");