@k2b/cloud 0.45.0 → 0.47.0

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/registry-validation.ts

@@ -160,8 +160,8 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("widgets", "an array of valid widgets");
     }
   }
-  if (value.platformPermissions !== undefined && !PlatformPermissionSchema.array().safeParse(value.platformPermissions).success)
-    return invalid("platformPermissions", "an array of platform permissions");
+  if (value.platformPermissions !== undefined && !isStringArray(value.platformPermissions))
+    return invalid("platformPermissions", "an array of permission IDs");
   if (value.settingKeys !== undefined && !isStringArray(value.settingKeys)) return invalid("settingKeys", "an array of strings");
   if (
     value.cliModules !== undefined &&
@@ -198,5 +198,18 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
   return null;
 };
 
-export const asAppRegistryEntry = (value: unknown): AppRegistryEntry | null =>
-  validateAppRegistryEntry(value) === null ? (value as AppRegistryEntry) : null;
+export const asAppRegistryEntry = (value: unknown): AppRegistryEntry | null => {
+  if (validateAppRegistryEntry(value) !== null) return null;
+  const entry = value as AppRegistryEntry;
+  return {
+    ...entry,
+    ...(entry.platformPermissions !== undefined
+      ? {
+          platformPermissions: entry.platformPermissions.flatMap((permission) => {
+            const parsed = PlatformPermissionSchema.safeParse(permission);
+            return parsed.success ? [parsed.data] : [];
+          }),
+        }
+      : {}),
+  };
+};

package/src/_internal/registry.ts

@@ -3,6 +3,7 @@ import type { EphemeralConfig, MutexConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
 import { calendarSourceIssues } from "../contracts/calendar-source";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
+import { discussionsIssues } from "../contracts/discussions";
 import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import { resourcePageIssue } from "../contracts/resource-pages";
@@ -18,7 +19,7 @@ import {
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
 import { lazySync } from "./process-sync";
-import { validateAppRegistryEntry } from "./registry-validation";
+import { asAppRegistryEntry, validateAppRegistryEntry } from "./registry-validation";
 import { watchRegistryChanges } from "./registry-watch";
 import { WidgetSettingsDeclarationSchema } from "./widget-settings";
 
@@ -150,7 +151,7 @@ export const readAppRegistrySnapshot = async (): Promise<AppRegistrySnapshot> =>
       continue;
     }
     loggedInvalidReasons.delete(entry.key);
-    const value = entry.value as AppRegistryEntry;
+    const value = asAppRegistryEntry(entry.value)!;
     const updatedAt = entry.updatedAt.getTime();
     apps.push({
       ...value,
@@ -194,7 +195,7 @@ export const getApp = async (appId: string): Promise<AppRegistryEntry | null> =>
       : validateAppRegistryEntry(entry.value);
   if (!reason) {
     loggedInvalidReasons.delete(key);
-    return entry.value;
+    return asAppRegistryEntry(entry.value);
   }
   reportInvalidEntry({ key, version: entry.revision, reason });
   return null;
@@ -237,6 +238,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.discussions !== undefined && !manifest.discussions) leftOut.push("discussions");
   if (leftOut.length === 0) return;
   console.warn(
     JSON.stringify({
@@ -320,6 +322,32 @@ const withValidCalendarSource = (manifest: CapabilityManifest): CapabilityManife
   return rest;
 };
 
+const checkedDiscussions = new Map<string, { manifestHash: string; valid: boolean }>();
+const withValidDiscussions = (manifest: CapabilityManifest): CapabilityManifest => {
+  if (!manifest.discussions) return manifest;
+  const checked = checkedDiscussions.get(manifest.appId);
+  let valid = checked?.manifestHash === manifest.manifestHash ? checked.valid : undefined;
+  if (valid === undefined) {
+    const issues = discussionsIssues(manifest);
+    valid = issues.length === 0;
+    checkedDiscussions.set(manifest.appId, { manifestHash: manifest.manifestHash, valid });
+    if (!valid)
+      console.error(
+        JSON.stringify({
+          level: "error",
+          source: "capability-registry",
+          message: "Ignored an incompatible discussions provider",
+          appId: manifest.appId,
+          manifestHash: manifest.manifestHash,
+          issues,
+        }),
+      );
+  }
+  if (valid) return manifest;
+  const { discussions: _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,
@@ -334,7 +362,7 @@ export const resolveLiveCapabilityRegistryEntry = (
   if (!endpoint) return null;
   try {
     const read = parseCapabilityManifest(record.manifest, app.id);
-    const supported = withValidCalendarSource(withValidFileProvider(read));
+    const supported = withValidDiscussions(withValidCalendarSource(withValidFileProvider(read)));
     const manifest = supported.resourcePages
       ? {
           ...supported,

package/src/_internal/resource-principals.ts

@@ -0,0 +1,6 @@
+import type { ResourcePrincipal } from "../contracts/capabilities";
+import { resolveResourceReaders } from "../services/identity/resource-readers";
+
+/** 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");

package/src/ai/capabilities.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import type { Tool, ToolContext, ToolResolver } from "@k2b/nessi";
 import { z } from "zod";
-import { resolveCapabilityActionWording, resolveCapabilityOperationTitle } from "../_internal/capabilities";
+import { isPersonVisibleCapabilityQuery, resolveCapabilityActionWording, resolveCapabilityOperationTitle } from "../_internal/capabilities";
 import { capabilityReviewView } from "../_internal/capability-reviews";
 import {
   CAPABILITY_APPROVAL_REASON_FIELD,
@@ -164,7 +164,9 @@ export const buildAiCapabilityCatalog = (apps: CapabilityRegistryEntry[], locale
         : app.appName;
       return [
         ...app.manifest.actions.map((operation) => ({ app, appName, operation, kind: "action" as const })),
-        ...app.manifest.queries.map((operation) => ({ app, appName, operation, kind: "query" as const })),
+        ...app.manifest.queries
+          .filter(isPersonVisibleCapabilityQuery)
+          .map((operation) => ({ app, appName, operation, kind: "query" as const })),
       ];
     })
     .map(