@k2b/cloud 0.43.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -39,7 +39,9 @@
     "./browser/pwa-drafts": "./src/browser/pwa-drafts.ts",
     "./browser/reload": "./src/browser/reload.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
+    "./browser/resource-links": "./src/browser/resource-links.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
+    "./browser/cloud-id": "./src/browser/cloud-id.ts",
     "./browser/commands": "./src/browser/commands.ts",
     "./browser/panel": "./src/browser/panel.ts",
     "./browser/search": "./src/browser/search.ts",
@@ -57,6 +59,7 @@
     "./cli/account": "./src/cli/account.ts",
     "./cli/apps": "./src/cli/apps.ts",
     "./cli/capabilities": "./src/cli/capabilities.ts",
+    "./cli/events": "./src/cli/events.ts",
     "./cli/admin": "./src/cli/admin/index.ts",
     "./shared": "./src/shared/index.ts",
     "./shared-text": "./src/shared-text/index.ts",
@@ -68,6 +71,7 @@
     "./services/*": "./src/services/*",
     "./ai": "./src/ai/index.ts",
     "./ai/admin": "./src/ai/admin.ts",
+    "./ai/app-frame": "./src/ai/app-frame.ts",
     "./ai/browser": "./src/ai/browser.ts",
     "./ai/question-text": "./src/ai/question-text.ts",
     "./ai/live": "./src/ai/live.ts",
@@ -119,7 +123,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
     "@k2b/ssr": "0.20.1",
-    "@k2b/ui": "0.33.0",
+    "@k2b/ui": "0.34.0",
     "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.1",
     "@nats-io/jetstream": "3.4.0",
@@ -127,6 +131,7 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.3",
+    "diff": "9.0.0",
     "entities": "8.0.0",
     "htmlparser2": "12.0.0",
     "jose": "6.2.12",

package/src/_internal/app-access-request.ts

@@ -0,0 +1,13 @@
+import type { RequestAuthority } from "../server/middleware/auth";
+
+// Request lifetime only. Never put reusable credentials on serializable authority.
+const requests = new WeakMap<RequestAuthority, Request>();
+const credentials = new WeakMap<RequestAuthority, string>();
+export const bindAppAccessRequest = (authority: RequestAuthority, request: Request, selectedCredential?: string): RequestAuthority => {
+  requests.set(authority, request);
+  if (selectedCredential) credentials.set(authority, selectedCredential);
+  return authority;
+};
+export const appAccessRequest = (authority: RequestAuthority): Request | undefined => requests.get(authority);
+
+export const appAccessCredential = (authority: RequestAuthority): string | undefined => credentials.get(authority);

package/src/_internal/app-access-resources.ts

@@ -0,0 +1,141 @@
+import { isDeepStrictEqual } from "node:util";
+import { type SQL, sql } from "bun";
+import { waitWithin } from "../api/fanout";
+import type { AppMeta } from "../contracts/app";
+import { type AppAccessDeclaration, type AppAccessRule, AppAccessRuleSchema, type ResourceAppAccessAdapter } from "../contracts/app-access";
+import type { RequestAuthority } from "../server/middleware/auth";
+import { coreOrigin } from "../services/identity/core-origin";
+import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
+import { type InvocationAuthority, signAppAccessProbe } from "../services/identity/invocation-token";
+import { appAccessCredential, appAccessRequest } from "./app-access-request";
+import { getProcessApplicationId } from "./process-identity";
+import { getApp } from "./registry";
+
+export const RESOURCE_ACCESS_PATH = "/api/_internal/app-access/v1";
+// Same budget as the app-entry live revalidation deadline. No retries.
+export const RESOURCE_ACCESS_TIMEOUT_MS = 10_000;
+const localAdapters = new Map<string, Readonly<Record<string, ResourceAppAccessAdapter>>>();
+const requestDecisions = new WeakMap<Request, Map<string, Promise<boolean>>>();
+type ResourceRule = Extract<AppAccessRule, { kind: "resources" }>;
+
+/** Called only for the running application, never populated from registry data. */
+export const bindResourceAppAccess = (appId: string, declaration?: AppAccessDeclaration): (() => void) => {
+  if (declaration?.kind !== "resources" || Array.isArray(declaration.adapters)) return () => {};
+  const adapters = declaration.adapters;
+  localAdapters.set(appId, adapters);
+  return () => {
+    if (localAdapters.get(appId) === adapters) localAdapters.delete(appId);
+  };
+};
+
+// This probe authorizes only a boolean existence check, never an app operation.
+// Retain the original credential ceilings and mandate provenance when Core probes.
+export const probeAuthority = (authority: RequestAuthority): InvocationAuthority => {
+  if (authority.credentialKind !== "invocation") return invocationAuthorityFromRequest(authority);
+  const provenance = authority.actor.delegation;
+  if (!provenance) throw new Error("Missing invocation provenance");
+  const actor = authority.actor;
+  const subject = authority.accessSubject;
+  return {
+    sub: actor.kind === "user" ? actor.user.id : actor.serviceAccount.id,
+    principal_type: actor.kind,
+    access_subject_type: subject.type,
+    access_subject_id: subject.type === "user" ? subject.userId : subject.serviceAccountId,
+    ...(actor.kind === "service_account" && actor.delegatedUser ? { delegated_user_id: actor.delegatedUser.id } : {}),
+    credential_kind: provenance.credentialKind,
+    ...(actor.kind === "user" && actor.sessionKind === "app" ? { session_kind: "app" as const } : {}),
+    ...(actor.kind === "service_account" && actor.credentialId ? { credential_id: actor.credentialId } : {}),
+    scopes: authority.scopes,
+    ...(provenance.mandateId
+      ? {
+          mandate_id: provenance.mandateId,
+          mandate_revision: provenance.mandateRevision,
+          workload_type: provenance.workloadType,
+          workload_id: provenance.workloadId,
+        }
+      : {}),
+  };
+};
+
+export const hasLocalResourceAppAccess = (appId: string): boolean => localAdapters.has(appId);
+
+export const resourceAppAccess = async (
+  authority: RequestAuthority,
+  app: Pick<AppMeta, "id" | "access">,
+  options: { db?: SQL; signal?: AbortSignal } = {},
+): Promise<boolean> => {
+  const parsed = AppAccessRuleSchema.safeParse(app.access);
+  if (!parsed.success || parsed.data.kind !== "resources") return false;
+  const rule = parsed.data;
+  const request = appAccessRequest(authority);
+  // A transaction can see uncommitted rights. Never reuse a request's earlier decision inside it.
+  const cache = request && !options.db ? (requestDecisions.get(request) ?? new Map<string, Promise<boolean>>()) : undefined;
+  if (request && cache) requestDecisions.set(request, cache);
+  const key = JSON.stringify([app.id, rule, authority]);
+  const previous = cache?.get(key);
+  if (previous) return options.signal ? waitWithin(previous, options.signal) : previous;
+  const deadline = options.signal ?? AbortSignal.timeout(RESOURCE_ACCESS_TIMEOUT_MS);
+  const signal = request ? AbortSignal.any([deadline, request.signal]) : deadline;
+  signal.throwIfAborted();
+  const pending = waitWithin(resolveResourceAccess(authority, app.id, rule, options.db ?? sql, signal), signal);
+  cache?.set(key, pending);
+  return pending;
+};
+
+const resolveResourceAccess = async (
+  authority: RequestAuthority,
+  appId: string,
+  rule: ResourceRule,
+  db: SQL,
+  signal: AbortSignal,
+): Promise<boolean> => {
+  const adapters = localAdapters.get(appId);
+  if (adapters) {
+    const bound =
+      authority.actor.kind === "service_account" && authority.actor.serviceAccount.kind === "resource_bound"
+        ? authority.actor.serviceAccount
+        : null;
+    for (const name of rule.adapters) {
+      if (bound && bound.resourceType !== name) continue;
+      signal.throwIfAborted();
+      const adapter = adapters[name];
+      if (!adapter) throw new Error("Resource adapter declaration changed");
+      if ((await adapter.hasAnyRight(authority.accessSubject, { authority, db, signal })) === true) return true;
+    }
+    return false;
+  }
+  if (getProcessApplicationId() === "core") {
+    const target = await getApp(appId);
+    if (!target || target.access?.kind !== "resources" || !isDeepStrictEqual(target.access, rule)) return false;
+    signal.throwIfAborted();
+    const token = await signAppAccessProbe({
+      appId,
+      authority: probeAuthority(authority),
+    });
+    signal.throwIfAborted();
+    const response = await fetch(new URL(`${RESOURCE_ACCESS_PATH}/check`, target.baseUrl), {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}` },
+      signal,
+      redirect: "error",
+    });
+    await response.body?.cancel();
+    if (response.status !== 204 && response.status !== 403) throw new Error("Resource app-access probe unavailable");
+    return response.status === 204;
+  }
+  // Invocations and probe tokens cannot be exchanged for further probes.
+  if (authority.credentialKind === "invocation") return false;
+  const credential = appAccessCredential(authority);
+  if (!credential) return false;
+  // Forward exactly the credential admitted on the source route, never a second cookie.
+  // Reusable credentials go only to Core; the owner receives only a dedicated probe.
+  const response = await fetch(new URL(`${RESOURCE_ACCESS_PATH}/apps/${encodeURIComponent(appId)}`, await coreOrigin(true)), {
+    method: "POST",
+    headers: { authorization: `Bearer ${credential}` },
+    signal,
+    redirect: "error",
+  });
+  await response.body?.cancel();
+  if (response.status !== 204 && response.status !== 403) throw new Error("Core app-access probe unavailable");
+  return response.status === 204;
+};

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

@@ -0,0 +1,40 @@
+import { sql } from "bun";
+import type { CapabilityEventCatalogEntry, CapabilityManifest } from "../contracts/capabilities";
+
+export type CatalogSubscription = CapabilityEventCatalogEntry["subscribers"][number] & { eventType: string; version: number };
+
+export const readCatalogSubscriptions = async (): Promise<CatalogSubscription[]> => {
+  const rows = await sql<(Omit<CatalogSubscription, "firstSeenAt"> & { firstSeenAt: Date })[]>`
+    SELECT app_id AS "appId", id AS "subscriptionId", event_type AS "eventType", version, state, reason,
+      first_seen_at AS "firstSeenAt" FROM events.app_subscriptions ORDER BY id
+  `;
+  return rows.map((row) => ({ ...row, firstSeenAt: row.firstSeenAt.toISOString() }));
+};
+
+export const readEventCatalogSubscriptions = async (type: string, version: number): Promise<CatalogSubscription[]> => {
+  const rows = await sql<(Omit<CatalogSubscription, "firstSeenAt"> & { firstSeenAt: Date })[]>`
+    SELECT app_id AS "appId", id AS "subscriptionId", event_type AS "eventType", version, state, reason,
+      first_seen_at AS "firstSeenAt" FROM events.app_subscriptions
+      WHERE event_type = ${type} AND version = ${version} ORDER BY id
+  `;
+  return rows.map((row) => ({ ...row, firstSeenAt: row.firstSeenAt.toISOString() }));
+};
+
+/** Callers filter persisted subscription states to applications their discovery surface may expose. */
+export const projectAppEventCatalog = (
+  manifest: CapabilityManifest,
+  subscribers: readonly CatalogSubscription[],
+): CapabilityEventCatalogEntry[] =>
+  (manifest.events ?? []).map((event) => ({
+    type: `${manifest.appId}.${event.localId}`,
+    version: event.version,
+    title: event.title,
+    description: event.description,
+    subject: `${manifest.appId}.${event.subject}`,
+    place: event.place ? `${manifest.appId}.${event.place}` : null,
+    automation: event.automation !== false,
+    dataSchema: event.dataSchema,
+    subscribers: subscribers
+      .filter((subscription) => subscription.eventType === `${manifest.appId}.${event.localId}` && subscription.version === event.version)
+      .map(({ eventType: _eventType, version: _version, ...subscription }) => subscription),
+  }));

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

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { APP_EVENT_MAX_BYTES } from "../contracts/app-events";
+import { capabilityHash, projectSchema } from "./capability-schemas";
+
+/** Closed objects, finite strings and bounded arrays; no recursive refs or open records. */
+export const assertBoundedAppEventSchema = (schema: Record<string, unknown>): void => {
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) throw new Error("Event data needs a bounded JSON schema");
+    const value = node as Record<string, unknown>;
+    if (value.$ref || value.$dynamicRef) throw new Error("Event data cannot contain recursive or referenced schemas");
+    if (value.const !== undefined || Array.isArray(value.enum)) return;
+    if (Array.isArray(value.anyOf) || Array.isArray(value.oneOf)) {
+      for (const branch of (value.anyOf ?? value.oneOf) as unknown[]) visit(branch);
+      return;
+    }
+    if (value.type === "object") {
+      if (value.additionalProperties !== false) throw new Error("Event objects must reject unknown properties");
+      for (const property of Object.values(value.properties ?? {})) visit(property);
+    } else if (value.type === "array") {
+      if (!Number.isSafeInteger(value.maxItems) || Number(value.maxItems) < 0) throw new Error("Event arrays need maxItems");
+      visit(value.items);
+    } else if (value.type === "string") {
+      if ((!Number.isSafeInteger(value.maxLength) || Number(value.maxLength) < 0) && value.format !== "uuid") {
+        throw new Error("Event strings need maxLength (UUIDs have a fixed bound)");
+      }
+    } else if (!["number", "integer", "boolean", "null"].includes(String(value.type))) {
+      throw new Error("Event data needs a bounded JSON schema");
+    }
+  };
+  if (schema.type !== "object") throw new Error("Event data must be a closed object");
+  visit(schema);
+  z.fromJSONSchema(structuredClone(schema));
+};
+
+export const compileAppEventSchema = (schema: z.ZodType, label: string, mode: "producer" | "reader" = "producer") => {
+  const dataSchema = projectSchema(schema, label, mode === "reader" ? "output" : "input");
+  const output = projectSchema(schema, label, "output");
+  if (capabilityHash(dataSchema) !== capabilityHash(output)) throw new Error(`${label} must preserve its JSON shape`);
+  assertBoundedAppEventSchema(dataSchema);
+  return { dataSchema, schemaHash: capabilityHash({ dataSchema }) };
+};
+
+type JsonValue = z.infer<ReturnType<typeof z.json>>;
+
+const decimalNumber = (value: number): string => {
+  const text = String(value);
+  const match = /^(-?)(\d+)(?:\.(\d+))?e([+-]?\d+)$/.exec(text);
+  if (!match) return text;
+  const [, sign = "", whole = "", fraction = "", exponent = "0"] = match;
+  const digits = whole + fraction;
+  const point = whole.length + Number(exponent);
+  return (
+    sign +
+    (point <= 0
+      ? `0.${"0".repeat(-point)}${digits}`
+      : point >= digits.length
+        ? digits + "0".repeat(point - digits.length)
+        : `${digits.slice(0, point)}.${digits.slice(point)}`)
+  );
+};
+
+/** PostgreSQL jsonb::text uses spaces after separators and expands numeric exponents. */
+export const appEventJsonbBytes = (value: JsonValue): number => {
+  const text = (entry: JsonValue): string => {
+    if (Array.isArray(entry)) return `[${entry.map(text).join(", ")}]`;
+    if (entry !== null && typeof entry === "object")
+      return `{${Object.entries(entry)
+        .map(([key, child]) => `${JSON.stringify(key)}: ${text(child)}`)
+        .join(", ")}}`;
+    return typeof entry === "number" ? decimalNumber(entry) : JSON.stringify(entry);
+  };
+  return new TextEncoder().encode(text(value)).byteLength;
+};
+
+export const assertAppEventSize = (value: JsonValue): void => {
+  if (appEventJsonbBytes(value) > APP_EVENT_MAX_BYTES)
+    throw new Error(`App event exceeds ${APP_EVENT_MAX_BYTES} PostgreSQL jsonb-text bytes`);
+};
+
+/** Lower bound for required data; no allocation proportional to maxItems/maxLength. */
+export const minimumAppEventDataBytes = (schema: Record<string, unknown>): number => {
+  if (schema.const !== undefined) return appEventJsonbBytes(z.json().parse(schema.const));
+  if (Array.isArray(schema.enum)) return Math.min(...schema.enum.map((value) => appEventJsonbBytes(z.json().parse(value))));
+  const alternatives = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(alternatives))
+    return Math.min(...alternatives.map((value) => minimumAppEventDataBytes(z.record(z.string(), z.unknown()).parse(value))));
+  if (schema.type === "string") return 2 + (schema.format === "uuid" ? 36 : Number(schema.minLength ?? 0));
+  if (schema.type === "null") return 4;
+  if (schema.type === "boolean") return 4;
+  if (schema.type === "number" || schema.type === "integer") return 1;
+  if (schema.type === "array") {
+    const count = Number(schema.minItems ?? 0);
+    return 2 + count * minimumAppEventDataBytes(z.record(z.string(), z.unknown()).parse(schema.items)) + Math.max(0, count - 1) * 2;
+  }
+  const properties = z.record(z.string(), z.unknown()).parse(schema.properties ?? {});
+  const keys = z.array(z.string()).parse(schema.required ?? []);
+  return (
+    2 +
+    Math.max(0, keys.length - 1) * 2 +
+    keys.reduce(
+      (bytes, key) =>
+        bytes + appEventJsonbBytes(key) + 2 + minimumAppEventDataBytes(z.record(z.string(), z.unknown()).parse(properties[key])),
+      0,
+    )
+  );
+};
+
+export const assertAppEventDeclarationSize = (
+  appId: string,
+  localId: string,
+  definition: { version: number; subject: string; place?: string },
+  dataSchema: Record<string, unknown>,
+): void => {
+  const id = "00000000-0000-4000-8000-000000000001";
+  const shell = {
+    id,
+    type: `${appId}.${localId}`,
+    version: definition.version,
+    source: appId,
+    time: "2000-01-01T00:00:00.000Z",
+    subject: { type: `${appId}.${definition.subject}`, id },
+    ...(definition.place ? { place: { type: `${appId}.${definition.place}`, id } } : {}),
+    data: null,
+  };
+  if (appEventJsonbBytes(shell) - 4 + minimumAppEventDataBytes(dataSchema) > APP_EVENT_MAX_BYTES)
+    throw new Error(`Event ${localId} required envelope cannot fit ${APP_EVENT_MAX_BYTES} bytes`);
+};

package/src/_internal/application-package.ts

@@ -0,0 +1,40 @@
+import { type SQL, sql } from "bun";
+import { ensureSchema } from "../services/postgres";
+import builtInAppIds from "./built-in-app-ids.json";
+
+export const resolveApplicationPackage = (appId: string, declared?: string): string => {
+  const packageName = declared ?? appId;
+  if (!/^[a-z][a-z0-9-]{0,79}$/.test(appId) || typeof packageName !== "string" || !/^[a-z][a-z0-9-]{0,79}$/.test(packageName)) {
+    throw new TypeError("Application IDs and packages must be lowercase names of 1–80 characters.");
+  }
+  if (appId === "storage" || packageName === "storage")
+    throw new Error("Application ID and package storage are reserved for public storage routing.");
+  if (packageName !== appId && builtInAppIds.includes(packageName)) {
+    throw new Error(`Package "${packageName}" is reserved for its built-in application.`);
+  }
+  return packageName;
+};
+
+/** Durable reservations survive app registry expiry. Serialize checks and writes across replicas. */
+export const registerApplicationPackage = async (appId: string, declared?: string, db: SQL = sql): Promise<void> => {
+  const packageName = resolveApplicationPackage(appId, declared);
+  await db.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtext('cloud.application-packages'))`;
+    await ensureSchema(tx, "platform");
+    await tx`CREATE TABLE IF NOT EXISTS platform.application_packages (
+      app_id TEXT PRIMARY KEY, package_name TEXT NOT NULL
+    )`.simple();
+    const conflicts = await tx<{ app_id: string; package_name: string }[]>`
+      SELECT app_id, package_name FROM platform.application_packages
+      WHERE (app_id <> ${appId} AND (app_id = ${packageName} OR package_name = ${appId}))
+         OR (app_id = ${appId} AND package_name <> ${packageName})
+      LIMIT 1
+    `;
+    if (conflicts.length) {
+      throw new Error(
+        `Application "${appId}" cannot claim package "${packageName}": an application ID or existing package assignment is reserved.`,
+      );
+    }
+    await tx`INSERT INTO platform.application_packages (app_id, package_name) VALUES (${appId}, ${packageName}) ON CONFLICT DO NOTHING`;
+  });
+};

package/src/_internal/built-in-app-ids.json

@@ -0,0 +1,27 @@
+[
+  "accounts",
+  "api-docs",
+  "assistant",
+  "capabilities",
+  "chat",
+  "contacts",
+  "core",
+  "dashboard",
+  "faq",
+  "filesv2",
+  "gateway",
+  "gateway-ops",
+  "grids",
+  "ipa-hosts",
+  "mail",
+  "notebooks",
+  "oauth",
+  "proxy-auth",
+  "pulse",
+  "pwa",
+  "quotes",
+  "spaces",
+  "tools",
+  "venue",
+  "weather"
+]