Fix capability isolation and Unicode validation

Author: JoviDeCroock

.changeset/capability-graph.md

@@ -10,11 +10,11 @@ The capability graph: define a typed application operation once and project it t
 
 **Capability core.** The new `@pracht/capabilities` package provides `defineCapability()`: a protocol-neutral operation with a dependency-free JSON Schema subset validator (unsupported keywords are rejected at definition time so they can never silently widen an exposed contract), effect classes (`read`/`write`/`destructive`), named middleware, and explicit exposure. Capabilities register in the app manifest via `defineApp({ capabilities: { ... } })` and are private by default. The package is also the single home of the wire protocol — `capabilityHttpPath()`, the confirmation and transport header names, the `CapabilityErrorCode` union, the envelope types, the schema→TypeScript printer, and the shared static extractor (`@pracht/capabilities/static`) — consumed by the framework, the Vite plugin, and the CLI so the contract cannot drift between packages.
 
-Capability validation also enforces the JSON data model at every boundary, including unconstrained/additional properties and schema `const`, `default`, and `enum` values, so multipart files, prototype-named fields, and other JavaScript-only values cannot bypass validation or destructive-call confirmation bindings.
+Capability validation also enforces the JSON data model at every boundary, including unconstrained/additional properties and schema `const`, `default`, and `enum` values, and applies JSON Schema string lengths by Unicode code point, so multipart files, prototype-named fields, astral Unicode characters, and other JavaScript-only values cannot bypass or distort validation and destructive-call confirmation bindings.
 
-The shared static extractor used by browser codegen and `pracht verify` ignores comments, string contents, and regex literals when locating capability definitions and registrations, analyzes the module's default-exported capability, and scopes manifest extraction to the exported `defineApp()` configuration — so examples, commented-out code, or a helper capability defined earlier in the file cannot change the generated capability surface.
+The shared static extractor used by browser codegen and `pracht verify` ignores comments, string contents, and regex literals when locating capability definitions and registrations, parses both fixed-width and code-point Unicode escapes in inline literals, analyzes the module's default-exported capability, and scopes manifest extraction to the exported `defineApp()` configuration — so examples, commented-out code, or a helper capability defined earlier in the file cannot change the generated capability surface.
 
-**Projections.** `@pracht/core` resolves the registry and runs one dispatch pipeline (input validation → named middleware → `run()` → output validation) behind every surface: `invokeCapability()` for direct server use (loaders, API routes, middleware), `POST /api/capabilities/<name>` with a typed `{ ok, data | error }` envelope, CSRF protection, and production redaction (custom HTTP paths that URL parsing could reinterpret as cross-origin or as a different pathname are rejected), and — via `@pracht/vite-plugin` — the generated `virtual:pracht/capabilities` browser client (`callCapability()`, with `confirm` sugar for confirmation tokens) and `virtual:pracht/webmcp`, a feature-detected WebMCP page-tool shim (`document.modelContext.registerTool`, Chrome origin trial). Both virtual modules cost zero bytes when unused.
+**Projections.** `@pracht/core` resolves the registry and runs one dispatch pipeline (input validation → named middleware → `run()` → output validation) behind every surface: request-scoped `invokeCapability()` for direct server use (loaders, API routes, middleware), `POST /api/capabilities/<name>` with a typed `{ ok, data | error }` envelope, CSRF protection, and production redaction (custom HTTP paths that URL parsing could reinterpret as cross-origin or as a different pathname are rejected), and — via `@pracht/vite-plugin` — the generated `virtual:pracht/capabilities` browser client (`callCapability()`, with `confirm` sugar for confirmation tokens) and `virtual:pracht/webmcp`, a feature-detected WebMCP page-tool shim (`document.modelContext.registerTool`, Chrome origin trial). Direct invocation hosts are bound to their incoming `Request`, so overlapping apps or dev-server generations cannot route a call through another registry. Both virtual modules cost zero bytes when unused.
 
 **One contract for humans and agents.** `<Form capability="notes.create">` posts the framework's form component straight to the capability endpoint agents call: fields are coerced onto the input schema server-side, `onCapabilityResult` receives the typed envelope, and without JavaScript the endpoint accepts the form-encoded post and answers a successful document submission with a 303 back to the same-origin referring page. Enhanced submissions honor a clicked submitter's `formaction` and follow middleware redirects to their final browser URL, matching that no-JavaScript behavior: a redirect is handed back to the same-origin fetch as a readable target and the browser navigates itself, so an external OAuth/SSO destination is never fetched through CORS and never submitted twice, and a cross-origin form target falls back to a native document submission (after client-side schema validation, if any). Effect classes drive the client cache: after any successful non-`read` browser call (`callCapability()` or `<Form capability>`) the active route's loader data revalidates automatically — a full reload under islands hydration — and `revalidate: false` opts out per call.
 

packages/capabilities/src/schema.ts

@@ -260,10 +260,14 @@ function validateJsonAgainstSchema(
   }
 
   if (typeof value === "string") {
-    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+    // JSON Schema measures string length in Unicode code points, while
+    // JavaScript's String#length counts UTF-16 code units. Count code points so
+    // astral characters such as emoji contribute one character, not two.
+    const length = Array.from(value).length;
+    if (typeof schema.minLength === "number" && length < schema.minLength) {
       issues.push({ path, message: `must be at least ${schema.minLength} character(s) long` });
     }
-    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+    if (typeof schema.maxLength === "number" && length > schema.maxLength) {
       issues.push({ path, message: `must be at most ${schema.maxLength} character(s) long` });
     }
   }

packages/capabilities/src/static.ts

@@ -714,6 +714,17 @@ function parseStringLiteral(source: string, start: number): ParsedLiteral | null
         break;
       }
       case "u": {
+        if (body[index + 1] === "{") {
+          const close = body.indexOf("}", index + 2);
+          if (close === -1) return null;
+          const hex = body.slice(index + 2, close);
+          if (!/^[0-9a-fA-F]{1,6}$/.test(hex)) return null;
+          const codePoint = Number.parseInt(hex, 16);
+          if (codePoint > 0x10ffff) return null;
+          value += String.fromCodePoint(codePoint);
+          index = close;
+          break;
+        }
         const hex = body.slice(index + 1, index + 5);
         if (!/^[0-9a-fA-F]{4}$/.test(hex)) return null;
         value += String.fromCharCode(Number.parseInt(hex, 16));

packages/capabilities/test/schema.test.ts

@@ -104,6 +104,13 @@ describe("validateAgainstSchema", () => {
     ]);
   });
 
+  it("counts Unicode code points for minLength and maxLength", () => {
+    expect(validateAgainstSchema({ type: "string", minLength: 2 }, "😀")).toEqual([
+      { path: "", message: "must be at least 2 character(s) long" },
+    ]);
+    expect(validateAgainstSchema({ type: "string", maxLength: 1 }, "😀")).toEqual([]);
+  });
+
   it("rejects unknown properties when additionalProperties is false", () => {
     expect(validateAgainstSchema(schema, { query: "x", bogus: 1 })).toEqual([
       { path: "/bogus", message: "is not an allowed property" },

packages/capabilities/test/static.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 
-import { extractCapabilityRegistrations, extractDefineCapabilityArgs } from "../src/static.ts";
+import {
+  evaluateLiteral,
+  extractCapabilityRegistrations,
+  extractDefineCapabilityArgs,
+  scanTopLevelProperties,
+} from "../src/static.ts";
 
 describe("capability static extraction", () => {
   it("ignores defineCapability examples in comments and strings", () => {
@@ -140,6 +145,25 @@ describe("capability static extraction", () => {
     expect(extractDefineCapabilityArgs(source)).toContain('effect: "read"');
   });
 
+  it("parses Unicode code-point escapes in inline schemas", () => {
+    const source = String.raw`
+      export default defineCapability({
+        title: "Emoji",
+        description: "Accept one emoji.",
+        input: { type: "string", enum: ["\u{1F600}"] },
+        output: { type: "string" },
+        effect: "read",
+        expose: { http: true, webmcp: true },
+        run() {},
+      });
+    `;
+
+    const args = extractDefineCapabilityArgs(source);
+    expect(args).not.toBeNull();
+    const input = scanTopLevelProperties(args!).get("input");
+    expect(evaluateLiteral(input!)).toEqual({ type: "string", enum: ["😀"] });
+  });
+
   it("ignores commented-out manifest registrations", () => {
     const source = `
       export const app = defineApp({

packages/framework/src/runtime-capabilities.ts

@@ -734,13 +734,19 @@ export interface CapabilityHost {
   registry: ModuleRegistry;
 }
 
-// The app manifest and module registry are process-level constants, so a
-// single slot is safe under concurrent requests. `handlePrachtRequest`
-// refreshes it on every request (dev re-evaluates the server module).
-let activeCapabilityHost: CapabilityHost | null = null;
-
-export function setActiveCapabilityHost(app: CapabilityHostApp, registry: ModuleRegistry): void {
-  activeCapabilityHost = { app, registry };
+// Bind each host to the incoming Request rather than a process-global slot.
+// Custom servers may serve multiple Pracht apps from one process, and dev HMR
+// can replace a registry while an older request is still awaiting its loader.
+// A WeakMap keeps those overlapping invocations isolated on every Web runtime
+// without retaining completed requests.
+const activeCapabilityHosts = new WeakMap<Request, CapabilityHost>();
+
+export function setActiveCapabilityHost(
+  request: Request,
+  app: CapabilityHostApp,
+  registry: ModuleRegistry,
+): void {
+  activeCapabilityHosts.set(request, { app, registry });
 }
 
 export interface InvokeCapabilityContext<TContext = unknown> {
@@ -777,10 +783,10 @@ export async function invokeCapability<T = unknown>(
   input: unknown,
   ctx: InvokeCapabilityContext,
 ): Promise<CapabilityEnvelope<T>> {
-  const host = activeCapabilityHost;
+  const host = activeCapabilityHosts.get(ctx.request);
   if (!host) {
     throw new Error(
-      "invokeCapability() has no capability host yet. It is only available while " +
+      "invokeCapability() has no capability host for this request. It is only available while " +
         "handlePrachtRequest() is serving requests (loaders, API routes, middleware). " +
         "In tests, build a standalone host with createCapabilityTestHost() instead.",
     );
@@ -790,7 +796,7 @@ export async function invokeCapability<T = unknown>(
 
 /**
  * Run one capability through the full dispatch pipeline against an explicit
- * host. Shared by `invokeCapability()` (the process-level host installed by
+ * host. Shared by `invokeCapability()` (the request-bound host installed by
  * `handlePrachtRequest`) and `createCapabilityTestHost()` (a synthetic host
  * for tests).
  */

packages/framework/src/runtime.ts

@@ -232,7 +232,7 @@ export async function handlePrachtRequest<TContext>(
   // Register the capability host so `invokeCapability()` works from loaders,
   // API routes, and middleware during this request. One assignment — free
   // for apps without capabilities.
-  setActiveCapabilityHost(options.app, registry);
+  setActiveCapabilityHost(options.request, options.app, registry);
 
   // Web Bot Auth: verify the agent signature once per request when the app
   // opted in via `defineApp({ agents: { webBotAuth } })`. The result (identity

packages/framework/test/capabilities.test.ts

@@ -578,6 +578,69 @@ describe("invokeCapability", () => {
     });
   });
 
+  it("keeps each capability host scoped to its originating request", async () => {
+    const createNamedCapability = (name: string) =>
+      createSearchCapability({
+        async run() {
+          return { notes: [name] };
+        },
+      });
+    const appOptions = {
+      routes: [route("/notes", "./routes/notes.tsx", { id: "notes" })],
+    };
+    const first = createApp(createNamedCapability("first"), appOptions);
+    const second = createApp(createNamedCapability("second"), appOptions);
+
+    let releaseFirst!: () => void;
+    const firstMayContinue = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    let markFirstStarted!: () => void;
+    const firstStarted = new Promise<void>((resolve) => {
+      markFirstStarted = resolve;
+    });
+
+    first.registry.routeModules = {
+      "./routes/notes.tsx": async () => ({
+        loader: async ({ request, context, signal }: LoaderArgs) => {
+          markFirstStarted();
+          await firstMayContinue;
+          return invokeCapability("notes.search", { query: "first" }, { request, context, signal });
+        },
+        Component: () => null,
+      }),
+    };
+    second.registry.routeModules = {
+      "./routes/notes.tsx": async () => ({
+        loader: async ({ request, context, signal }: LoaderArgs) =>
+          invokeCapability("notes.search", { query: "second" }, { request, context, signal }),
+        Component: () => null,
+      }),
+    };
+
+    const firstResponsePromise = handlePrachtRequest({
+      app: first.app,
+      registry: first.registry,
+      request: new Request("http://first.local/notes?_data=1"),
+    });
+    await firstStarted;
+
+    const secondResponse = await handlePrachtRequest({
+      app: second.app,
+      registry: second.registry,
+      request: new Request("http://second.local/notes?_data=1"),
+    });
+    releaseFirst();
+    const firstResponse = await firstResponsePromise;
+
+    expect(await firstResponse.json()).toEqual({
+      data: { ok: true, data: { notes: ["first"] } },
+    });
+    expect(await secondResponse.json()).toEqual({
+      data: { ok: true, data: { notes: ["second"] } },
+    });
+  });
+
   it("works for private capabilities and returns validation envelopes", async () => {
     const { app, registry } = createApp(createSearchCapability({ expose: undefined }), {
       routes: [route("/notes", "./routes/notes.tsx", { id: "notes" })],