@k2b/cloud 0.39.0 → 0.41.0

package/README.md

@@ -83,6 +83,14 @@ Application setup, public contracts, and deployment guidance:
 - **[Create the first application](https://github.com/k2b-dev/cloud/blob/main/docs-site/docs/en/build/getting-started.md)** — standalone project setup and a verified API endpoint
 - **[github.com/k2b-dev/cloud](https://github.com/k2b-dev/cloud)** — the platform monorepo (gateway, core, all platform apps)
 
+## Security
+
+Report a vulnerability privately through
+[GitHub Security Advisories](https://github.com/k2b-dev/cloud/security/advisories/new),
+never in a public issue. Security fixes appear in this package's changelog,
+and a published advisory names the first patched version. See the
+[security policy](https://github.com/k2b-dev/cloud/blob/main/SECURITY.md).
+
 ## License
 
 GNU Affero General Public License v3.0 or later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -34,6 +34,7 @@
     "./browser/app-badges": "./src/browser/app-badges.ts",
     "./browser/live": "./src/browser/live.ts",
     "./browser/mermaid": "./src/browser/mermaid.ts",
+    "./browser/hints": "./src/browser/hints.ts",
     "./browser/reload": "./src/browser/reload.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
@@ -56,6 +57,7 @@
     "./cli/capabilities": "./src/cli/capabilities.ts",
     "./cli/admin": "./src/cli/admin/index.ts",
     "./shared": "./src/shared/index.ts",
+    "./shared-text": "./src/shared-text/index.ts",
     "./services": "./src/services/index.ts",
     "./services/image-metadata": "./src/services/image-metadata.ts",
     "./services/document-extraction": "./src/services/document-extraction.ts",
@@ -65,10 +67,12 @@
     "./ai": "./src/ai/index.ts",
     "./ai/admin": "./src/ai/admin.ts",
     "./ai/browser": "./src/ai/browser.ts",
+    "./ai/question-text": "./src/ai/question-text.ts",
     "./ai/live": "./src/ai/live.ts",
     "./ai/live-events": "./src/ai/live-events.ts",
     "./ai/runtime": "./src/ai/runtime.ts",
     "./ai/solid": "./src/ai/solid.ts",
+    "./ai/testing": "./src/ai/testing.ts",
     "./ai/tools": "./src/ai/runtime-tools.ts",
     "./ai/ui": "./src/ai/ui.tsx",
     "./account/ui": "./src/account/ui.ts",
@@ -110,21 +114,23 @@
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.17.0",
-    "@k2b/ui": "0.29.0",
-    "@k2b/stdlib": "0.29.0",
+    "@k2b/ssr": "0.19.0",
+    "@k2b/ui": "0.31.0",
+    "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",
     "@nats-io/transport-node": "3.4.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.3",
+    "entities": "8.0.0",
     "htmlparser2": "12.0.0",
     "jose": "6.2.12",
     "katex": "0.18.9",
     "liquidjs": "10.29.0",
     "marked": "18.0.14",
     "mermaid": "12.0.0",
+    "mmdb-lib": "3.0.3",
     "nodemailer": "10.0.10",
     "postcss": "8.5.28",
     "reflect-metadata": "0.2.2",
@@ -134,6 +140,7 @@
     "web-push": "3.6.7",
     "web-vitals": "6.2.2",
     "yaml": "2.9.1",
+    "yjs": "13.6.33",
     "hash-wasm": "4.12.0",
     "@types/sanitize-html": "2.16.1",
     "@types/web-push": "3.6.4"

package/src/_internal/app-favicon.ts

@@ -1,2 +1,4 @@
-export const appFaviconHref = (appId: string, version: number): string =>
-  appId === "core" ? "/branding/favicon" : `/public/${appId}/favicon.svg?v=${version}`;
+export const appFaviconHref = (appId: string, version: string | number | undefined): string =>
+  appId === "core"
+    ? "/branding/favicon"
+    : `/public/${appId}/favicon.svg${version === undefined ? "" : `?v=${encodeURIComponent(version)}`}`;

package/src/_internal/capabilities.ts

@@ -1,4 +1,7 @@
-import { createHash } from "node:crypto";
+import { capabilityHash, projectSchema, stableJsonValue } from "./capability-schemas";
+
+export { capabilityHash } from "./capability-schemas";
+
 import { isServiceError, type Result, type ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
 import {
@@ -8,8 +11,8 @@ import {
   CAPABILITY_PROTOCOL_VERSION,
   type CapabilityActionDefinition,
   type CapabilityActionManifest,
+  CapabilityActionPolicySchema,
   type CapabilityActionReviewResult,
-  CapabilityActionReviewSchema,
   type CapabilityActionSentences,
   type CapabilityCommandDefinition,
   type CapabilityCommandManifest,
@@ -33,12 +36,14 @@ import {
   type CapabilitySearchTagDefinition,
   type CapabilityStreamDefinition,
   type CapabilityUniversalSearchDefinition,
+  capabilityActionPolicy,
   capabilityResultSchema,
   UniversalSearchDataSchema,
   UniversalSearchInputSchema,
 } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
 import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../shared/locale";
+import { capabilityActionReceiptIssues, capabilityActionReviewIssues, capabilityQueryChecksActionOutcome } from "./capability-reviews";
 import {
   CAPABILITY_SENTENCE_KEYS,
   CAPABILITY_SENTENCE_MAX_CHARS,
@@ -94,6 +99,7 @@ const ACTION_FIELDS = {
   stream: true,
   idempotency: true,
   approval: true,
+  policy: true,
   review: true,
   run: true,
 } satisfies DefinedFields<CapabilityActionDefinition>;
@@ -221,21 +227,6 @@ export const serializeCapabilityProviderResult = (
   return { body: JSON.stringify(fallback), status: options.nonIdempotentAction ? 502 : 500 };
 };
 
-const stableJsonValue = (value: unknown): unknown => {
-  if (Array.isArray(value)) return value.map(stableJsonValue);
-  if (typeof value !== "object" || value === null) return value;
-  return Object.fromEntries(
-    Object.entries(value as Record<string, unknown>)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, entry]) => [key, stableJsonValue(entry)]),
-  );
-};
-
-export const capabilityHash = (value: unknown): string =>
-  createHash("sha256")
-    .update(JSON.stringify(stableJsonValue(value)))
-    .digest("hex");
-
 const assertText = (value: string, label: string, max: number): void => {
   if (!value.trim()) throw new Error(`${label} is required`);
   if (value.length > max) throw new Error(`${label} must be at most ${max} characters`);
@@ -338,12 +329,12 @@ const compileOperationPresentation = (
   operation: CapabilityQueryManifest | CapabilityActionManifest | CapabilityCommandManifest,
   label: string,
   strict = true,
-): CapabilityOperationPresentationTranslation => {
+): CapabilityOperationPresentationTranslation & { keywords?: readonly string[] } => {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
   const translation = value as Record<string, unknown>;
   const allowed = new Set(
     "path" in operation
-      ? ["title", "description", "input"]
+      ? ["title", "description", "input", "keywords"]
       : ["title", "description", "input", "data", "searchTags", ...(isAction(operation) ? ["sentences"] : [])],
   );
   const extra = Object.keys(translation).find((key) => !allowed.has(key));
@@ -356,6 +347,10 @@ const compileOperationPresentation = (
     if (typeof translation.description !== "string") throw new Error(`${label}.description must be text`);
     assertText(translation.description, `${label}.description`, 1000);
   }
+  const keywords =
+    "path" in operation && translation.keywords !== undefined
+      ? CapabilityCommandManifestSchema.shape.keywords.parse(translation.keywords)
+      : undefined;
   let searchTags: CapabilityOperationPresentationTranslation["searchTags"];
   const universalSearch = "universalSearch" in operation ? operation.universalSearch : undefined;
   // A reader skips search-tag copy for an operation without Universal Search instead of losing its other copy.
@@ -398,6 +393,7 @@ const compileOperationPresentation = (
   return {
     ...(typeof translation.title === "string" ? { title: translation.title.trim() } : {}),
     ...(typeof translation.description === "string" ? { description: translation.description.trim() } : {}),
+    ...(keywords ? { keywords } : {}),
     ...(input ? { input } : {}),
     ...(data ? { data } : {}),
     ...(searchTags ? { searchTags } : {}),
@@ -517,17 +513,6 @@ export const compileCapabilityPresentation = (
   return { baseLocale, ...(sentences && Object.keys(sentences).length > 0 ? { sentences } : {}), translations };
 };
 
-const projectSchema = (schema: z.ZodType, label: string, io: "input" | "output"): JsonSchema => {
-  try {
-    const projected = z.toJSONSchema(schema, { io }) as JsonSchema;
-    z.fromJSONSchema(projected);
-    return projected;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`${label} is not JSON-Schema-round-trippable: ${message}`);
-  }
-};
-
 const assertPropertyDescriptions = (schema: unknown, label: string, path: readonly string[] = []): void => {
   if (!schema || typeof schema !== "object" || Array.isArray(schema)) return;
   const value = schema as Record<string, unknown>;
@@ -720,6 +705,20 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     const label = `Action ${localId}`;
     assertDefinedFields(definition, ACTION_FIELDS, label);
     assertDefinedStreamFields(definition.stream, label);
+    if (definition.policy !== undefined) {
+      const parsedPolicy = CapabilityActionPolicySchema.safeParse(definition.policy);
+      if (!parsedPolicy.success) throw new Error(`${label} has invalid policy: ${parsedPolicy.error.message}`);
+      if (definition.approval !== undefined) throw new Error(`${label} policy and approval are mutually exclusive`);
+      if (!definition.review) throw new Error(`${label} policy requires review()`);
+      if ("silent" in parsedPolicy.data && (definition.destructive || definition.openWorld))
+        throw new Error(`${label} destructive or open-world policy must ask`);
+      if (
+        "ask" in parsedPolicy.data &&
+        (parsedPolicy.data.ask === "sends" || parsedPolicy.data.ask === "deletes") &&
+        definition.idempotency !== "required"
+      )
+        throw new Error(`${label} sends or deletes policy requires idempotency: "required"`);
+    }
     // Declaration rule, documented in docs/platform/capabilities.md:
     // destructive means irreversible or externally visible. An irreversible or
     // open-world effect must always be reviewable and safely repeatable, and
@@ -767,7 +766,13 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       destructive: definition.destructive,
       openWorld: definition.openWorld,
       idempotency: definition.idempotency,
-      ...(definition.approval ? { approval: definition.approval } : {}),
+      ...(definition.policy
+        ? "silent" in definition.policy
+          ? { approval: "rememberable" as const }
+          : {}
+        : definition.approval
+          ? { approval: definition.approval }
+          : {}),
       ...(definition.review ? { review: true as const } : {}),
     } satisfies CapabilityActionManifest;
     actions.set(localId, {
@@ -795,6 +800,9 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
       });
     });
 
+  const policies = Object.fromEntries(
+    [...actions].flatMap(([localId, action]) => (action.definition.policy ? [[localId, action.definition.policy]] : [])),
+  );
   const fileProvider = definitions.fileProvider;
   const manifestBase = {
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
@@ -803,6 +811,7 @@ export const compileCapabilities = (appId: string, definitions: CapabilityDefini
     queries: [...queries.values()].map((entry) => entry.manifest),
     actions: [...actions.values()].map((entry) => entry.manifest),
     commands,
+    ...(Object.keys(policies).length ? { policies } : {}),
     // Omitted when unused so manifests without a provider keep their earlier hash.
     ...(fileProvider
       ? { fileProvider: { list: fileProvider.list, read: fileProvider.read, ...(fileProvider.save ? { save: fileProvider.save } : {}) } }
@@ -954,6 +963,7 @@ export const resolveCapabilityManifestPresentation = (
               title: copy.title ?? operation.title,
               description: copy.description ?? operation.description,
               inputSchema: applySchemaPresentation(operation.inputSchema, copy.input),
+              keywords: copy.keywords ? [...copy.keywords] : operation.keywords,
             }
           : operation;
       }),
@@ -970,6 +980,7 @@ export const resolveCapabilityManifestPresentation = (
           : operation;
       }),
       ...(current.fileProvider ? { fileProvider: current.fileProvider } : {}),
+      ...(current.policies ? { policies: current.policies } : {}),
     };
     current = CapabilityManifestSchema.parse({ ...manifestBase, manifestHash: capabilityHash(manifestBase) });
   }
@@ -1213,6 +1224,15 @@ const resultRefs = (result: unknown): Array<{ type: string; id: string }> => {
   }>;
 };
 
+const compiledReviewContext = (compiled: CompiledCapabilities, localId: string) => ({
+  policy: capabilityActionPolicy(compiled.manifest, localId),
+  approval: compiled.actions.get(localId)?.manifest.approval,
+  queries: compiled.manifest.queries,
+  validateQueryInput: (query: CapabilityQueryManifest, input: Record<string, unknown>) =>
+    compiled.queries.get(query.localId)?.definition.input.safeParse(input).success === true,
+  ...(compiled.presentation ? { locales: [compiled.presentation.baseLocale, ...Object.keys(compiled.presentation.translations)] } : {}),
+});
+
 export const validateCapabilityResult = (
   compiled: CompiledCapabilities,
   operation: CompiledCapabilityQuery | CompiledCapabilityAction,
@@ -1220,12 +1240,25 @@ export const validateCapabilityResult = (
   onInvalidResult?: (error: unknown) => void,
 ): Result<unknown, ServiceError> => {
   const parsed = operation.resultSchema.safeParse(result);
-  if (!parsed.success) {
+  const field = (value: unknown, key: string): unknown =>
+    value !== null && typeof value === "object" ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+  const receipt = field(result, "receipt");
+  const links = field(result, "links");
+  const receiptIssues =
+    receipt === undefined
+      ? []
+      : "idempotency" in operation.manifest
+        ? capabilityActionReceiptIssues(receipt, links)
+        : ["Queries cannot return a receipt"];
+  const nestedReceipt = field(field(result, "data"), "receipt");
+  if (!("idempotency" in operation.manifest) && nestedReceipt !== undefined && capabilityQueryChecksActionOutcome(operation.manifest))
+    receiptIssues.push(...capabilityActionReceiptIssues(nestedReceipt, links));
+  if (!parsed.success || receiptIssues.length > 0) {
     try {
       onInvalidResult?.(
         new Error(
           `Capability ${operation.manifest.localId} returned data outside its registered schema: ${JSON.stringify(
-            parsed.error.issues.map(({ code, path, message }) => ({ code, path, message })),
+            parsed.success ? receiptIssues : parsed.error.issues.map(({ code, path, message }) => ({ code, path, message })),
           )}`,
         ),
       );
@@ -1468,27 +1501,18 @@ export const reviewCompiledCapability = async (params: {
     if (!reviewed.ok) {
       return normalizeProviderError(reviewed.error, "Capability review returned an invalid error", params.onUnexpectedError);
     }
-    const parsed = CapabilityActionReviewSchema.safeParse(reviewed.data);
-    // A rememberable Action may leave out its scope for arguments that should ask every time; any other Action has none.
-    const approvalScopeIsValid =
-      parsed.success && (operation.manifest.approval === "rememberable" || parsed.data.approvalScope === undefined);
-    if (!parsed.success || !approvalScopeIsValid) {
+    const issues = capabilityActionReviewIssues(reviewed.data, compiledReviewContext(params.compiled, params.localId));
+    if (issues.length > 0) {
       try {
         params.onUnexpectedError?.(
-          new Error(
-            parsed.success
-              ? `Capability ${operation.manifest.localId} review returned an approval scope inconsistent with its manifest`
-              : `Capability ${operation.manifest.localId} review returned data outside its registered schema: ${JSON.stringify(
-                  parsed.error.issues.map(({ code, path, message }) => ({ code, path, message })),
-                )}`,
-          ),
+          new Error(`Capability ${operation.manifest.localId} review returned an invalid result: ${issues.join("; ")}`),
         );
       } catch {
-        // Observability must not change the public failure contract.
+        /* Observability must not change the public failure contract. */
       }
     }
-    return parsed.success && approvalScopeIsValid
-      ? { ok: true, data: parsed.data }
+    return issues.length === 0
+      ? { ok: true, data: reviewed.data }
       : {
           ok: false,
           error: {

package/src/_internal/capability-reviews.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { capabilityPreviewIssues, capabilityReviewFormIssues } from "../capabilities/reviews";
+import {
+  CAPABILITY_REACHES,
+  CapabilityActionCheckSchema,
+  type CapabilityActionPolicy,
+  CapabilityActionReceiptSchema,
+  CapabilityActionReviewDataSchema,
+  type CapabilityQueryManifest,
+  CapabilitySemanticLinkSchema,
+} from "../contracts/capabilities";
+import { localeFallbackChain } from "../shared/locale";
+import { capabilityHash, projectSchema } from "./capability-schemas";
+
+export {
+  actionReview,
+  type CapabilityReviewForms,
+  capabilityReviewFormIssues,
+  capabilityReviewRememberScope,
+  capabilityReviewView,
+  type SlotNames,
+} from "../capabilities/reviews";
+
+export { CAPABILITY_MAX_REVIEW_BYTES } from "../contracts/capabilities";
+export type CapabilityReviewContext = {
+  policy?: CapabilityActionPolicy;
+  approval?: "rememberable" | "none";
+  queries: readonly CapabilityQueryManifest[];
+  validateQueryInput: (query: CapabilityQueryManifest, input: Record<string, unknown>) => boolean;
+  locales?: readonly string[];
+};
+const schemaIssues = (error: z.ZodError): string[] => error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+let actionCheckDataHash: string | undefined;
+/** Whether a Query answers an Action's `check`: its data schema is exactly the projected `CapabilityActionCheckSchema`. */
+export const capabilityQueryChecksActionOutcome = (query: CapabilityQueryManifest): boolean => {
+  actionCheckDataHash ??= capabilityHash(projectSchema(CapabilityActionCheckSchema, "Action check", "output"));
+  return capabilityHash(query.dataSchema) === actionCheckDataHash;
+};
+
+export const capabilityActionReviewIssues = (review: unknown, context: CapabilityReviewContext): string[] => {
+  const parsed = CapabilityActionReviewDataSchema.safeParse(review);
+  if (!parsed.success) return schemaIssues(parsed.error);
+  const data = parsed.data;
+  if (!("sentence" in data))
+    return context.policy
+      ? ["A policy Action must return a new review"]
+      : data.approvalScope !== undefined && context.approval !== "rememberable"
+        ? ["approvalScope requires rememberable approval"]
+        : [];
+  if (!context.policy) return ["An Action without policy must return a legacy review"];
+  const issues = capabilityReviewFormIssues(data);
+  if (
+    data.reach !== undefined &&
+    (!("silent" in context.policy) || CAPABILITY_REACHES.indexOf(data.reach) > CAPABILITY_REACHES.indexOf(context.policy.silent))
+  )
+    issues.push("reach exceeds the declared silent reach");
+  if (context.locales && !localeFallbackChain(data.locale, data.locale).some((locale) => context.locales?.includes(locale)))
+    issues.push("locale is not supported by the app");
+  if (data.check) {
+    const query = context.queries.find((query) => query.localId === data.check?.query);
+    if (!query || !capabilityQueryChecksActionOutcome(query)) issues.push("check.query must return CapabilityActionCheckSchema");
+    else if (!context.validateQueryInput(query, data.check.input)) issues.push("check.input does not match the Query");
+  }
+  issues.push(
+    ...capabilityPreviewIssues(
+      data.preview,
+      data.links,
+      // A per-call reason never lifts the declared `sends` completeness rule.
+      data.ask === "sends" || ("ask" in context.policy && context.policy.ask === "sends"),
+    ),
+  );
+  return [...new Set(issues)];
+};
+/** A receipt's own rules; completeness links are the result envelope's top-level `links`. */
+export const capabilityActionReceiptIssues = (receipt: unknown, links: unknown): string[] => {
+  const parsed = CapabilityActionReceiptSchema.safeParse(receipt);
+  const resultLinks = z.array(CapabilitySemanticLinkSchema).safeParse(links);
+  return parsed.success
+    ? capabilityPreviewIssues(parsed.data.preview, resultLinks.success ? resultLinks.data : undefined)
+    : schemaIssues(parsed.error);
+};

package/src/_internal/capability-schemas.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+type JsonSchema = Record<string, unknown>;
+export const stableJsonValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(stableJsonValue);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, stableJsonValue(entry)]),
+  );
+};
+
+export const capabilityHash = (value: unknown): string =>
+  createHash("sha256")
+    .update(JSON.stringify(stableJsonValue(value)))
+    .digest("hex");
+
+export const projectSchema = (schema: z.ZodType, label: string, io: "input" | "output"): JsonSchema => {
+  try {
+    const projected = z.toJSONSchema(schema, { io });
+    z.fromJSONSchema(projected);
+    return projected;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${label} is not JSON-Schema-round-trippable: ${message}`);
+  }
+};