capability-worker 0.1.0

package/README.md

@@ -0,0 +1,1012 @@
+# capability-worker
+
+`capability-worker` is the shared toolkit for building Cloudflare Workers that expose a CLI-like capability over HTTP.
+
+Use this package when you are building a capability worker and want the common platform mechanics handled in one place:
+
+- public capability contract assets
+- `capability-signature-v1` verification
+- public key lookup and caching
+- first-party browser auth-cookie verification
+- JSON, text, redirect, and error responses
+- crypto helpers for Workers
+- encrypted credential fields
+- multipart file parsing and file validation
+- R2/S3-compatible presigned URLs
+- Worker-proxied signed download URLs
+- contract validation
+- test helpers for signed requests
+
+The package lets each worker focus on provider or product behavior: mail, calendar, meetings, invoices, files, or another domain.
+
+## Install
+
+```sh
+pnpm add capability-worker
+```
+
+The package is ESM-only and usable from Cloudflare Workers.
+
+Runtime imports use subpaths so the worker only imports the modules it needs:
+
+```ts
+import { requireCapabilitySignature } from "capability-worker/auth";
+import { jsonResponse, errorResponse } from "capability-worker/http";
+```
+
+Node-only tools, such as the asset builder CLI, are exposed through package binaries:
+
+```sh
+pnpm exec capability-build-assets --validate
+pnpm exec capability-validate
+```
+
+## Mental Model
+
+A capability worker has two parts:
+
+1. Static public contract assets that describe the CLI and HTTP mapping.
+2. Dynamic API routes that execute account-scoped operations.
+
+The static assets live at the installed capability URL:
+
+```text
+<capability-url>/info
+<capability-url>/definition
+<capability-url>/mapping
+<capability-url>/skill/SKILL.md
+```
+
+For a capability installed at `https://meeting.example.com/api`, the files are:
+
+```text
+https://meeting.example.com/api/info
+https://meeting.example.com/api/definition
+https://meeting.example.com/api/mapping
+https://meeting.example.com/api/skill/SKILL.md
+```
+
+The dynamic API also lives under `apiBaseUrl`. Account-scoped routes must verify the capability signature before reading or writing account data.
+
+## Recommended Worker Layout
+
+```text
+worker/
+  capability/
+    info.template.json
+  public/
+    api/
+      info
+      definition
+      mapping
+      skill/
+        SKILL.md
+    _headers
+  scripts/
+  src/
+    worker.ts
+cli/
+  definition.json
+  mapping.json
+skills/
+  meeting/
+    SKILL.md
+```
+
+The package helps generate `worker/public/...` from the source files in `capability/`, `cli/`, and `skills/`.
+
+## Exports
+
+Available exports:
+
+```ts
+import {} from "capability-worker";
+import {} from "capability-worker/auth";
+import {} from "capability-worker/crypto";
+import {} from "capability-worker/credentials";
+import {} from "capability-worker/files";
+import {} from "capability-worker/http";
+import {} from "capability-worker/storage";
+import {} from "capability-worker/testing";
+import {} from "capability-worker/validation";
+import {} from "capability-worker/node";
+```
+
+Use runtime exports from Worker code. Use `testing` from tests. Use `node` or the package CLIs from Node scripts only.
+
+## 1. Generate Capability Assets
+
+Use `capability-build-assets` to create the public files that a capability client installs and reads.
+
+```sh
+CAPABILITY_BASE_URL=https://meeting.example.com/api \
+APP_ASSET_VERSION=0.1.0 \
+pnpm exec capability-build-assets --validate
+```
+
+Common package script:
+
+```json
+{
+  "scripts": {
+    "build:capability-assets": "capability-build-assets --validate"
+  }
+}
+```
+
+Worker-specific script:
+
+```json
+{
+  "scripts": {
+    "build:capability-assets": "CAPABILITY_BASE_URL=https://meeting.example.com/api APP_ASSET_VERSION=0.1.0 capability-build-assets --validate"
+  }
+}
+```
+
+Useful flags:
+
+```sh
+capability-build-assets \
+  --worker-root worker \
+  --repo-root . \
+  --public-root worker/public \
+  --validate
+```
+
+Useful environment variables:
+
+```text
+CAPABILITY_BASE_URL
+APP_ASSET_VERSION
+CAPABILITY_INFO_TEMPLATE_PATH
+CAPABILITY_DEFINITION_PATH
+CAPABILITY_MAPPING_PATH
+CAPABILITY_SKILL_ENTRYPOINT
+```
+
+The generated layout looks like this:
+
+```text
+worker/public/
+  api/
+    info
+    definition
+    mapping
+    skill/
+      SKILL.md
+  _headers
+```
+
+Configure Wrangler static assets:
+
+```jsonc
+{
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS",
+    "html_handling": "none",
+    "not_found_handling": "none"
+  }
+}
+```
+
+The builder:
+
+- normalize `CAPABILITY_BASE_URL`
+- generate files under the URL path prefix, such as `/api`
+- replace template variables such as `${CAPABILITY_BASE_URL}` and `${APP_ASSET_VERSION}`
+- copy the skill entrypoint and skill resources
+- reject unsafe paths such as `../secret`
+- write `_headers` with JSON and Markdown content types
+- optionally validate generated assets
+
+## 2. Verify Signed Capability Requests
+
+Use `capability-signature-v1` for agent or server-to-server account-scoped routes.
+
+Required headers:
+
+```text
+x-capability-account-id: <account-id>
+x-capability-timestamp: <unix-seconds>
+x-capability-key-id: <key-id>
+x-capability-signature: v1=<base64url-signature>
+```
+
+Canonical string:
+
+```text
+CAPABILITY-SIGNATURE-V1
+<METHOD>
+<PATH_WITH_QUERY>
+<TIMESTAMP>
+<ACCOUNT_ID>
+<SHA256_HEX_BODY>
+```
+
+Use `requireCapabilitySignature` when route handlers prefer exception flow:
+
+```ts
+import { requireCapabilitySignature } from "capability-worker/auth";
+import { errorResponse, jsonResponse } from "capability-worker/http";
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      const { accountId } = await requireCapabilitySignature(request, env);
+
+      const rows = await env.DB.prepare(
+        "SELECT * FROM meetings WHERE account_id = ? ORDER BY starts_at DESC"
+      )
+        .bind(accountId)
+        .all();
+
+      return jsonResponse({ ok: true, data: rows.results });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }
+};
+```
+
+Use `verifyCapabilitySignature` when route handlers prefer explicit result handling:
+
+```ts
+import { verifyCapabilitySignature } from "capability-worker/auth";
+import { errorJson, jsonResponse } from "capability-worker/http";
+
+const auth = await verifyCapabilitySignature(request, env);
+
+if (!auth.ok) {
+  return errorJson(auth.code, auth.message, auth.status);
+}
+
+return jsonResponse({
+  ok: true,
+  accountId: auth.accountId
+});
+```
+
+Rules for signed routes:
+
+- verify before account-scoped reads or writes
+- use the verified account id as the only tenant scope
+- include query strings in the canonical path
+- hash the exact raw request body bytes
+- never accept account id from the body or query string
+- return `404` when a resource does not exist inside the verified account scope
+
+## 3. Fetch And Cache Public Keys
+
+Use the public key store behind signature and auth-cookie verification.
+
+```ts
+import { PublicKeyStore } from "capability-worker/auth";
+
+const keyStore = new PublicKeyStore(env, {
+  cacheTtlMs: 300_000
+});
+
+const key = await keyStore.getKey("key_123");
+```
+
+Supported key sources, in priority order:
+
+1. `CAPABILITY_PUBLIC_KEYS_JSON`
+2. `CAPABILITY_PUBLIC_KEYS`
+3. `CAPABILITY_PUBLIC_KEYS_SERVICE.fetch(CAPABILITY_PUBLIC_KEYS_URL)`
+4. `fetch(CAPABILITY_PUBLIC_KEYS_URL)`
+
+Recommended Wrangler variables:
+
+```toml
+[vars]
+CAPABILITY_PUBLIC_KEYS_URL = "https://host.example.com/capability/public-keys"
+```
+
+When the public-key endpoint is another Worker on the same Cloudflare zone, also use a service binding in production:
+
+```toml
+[[services]]
+binding = "CAPABILITY_PUBLIC_KEYS_SERVICE"
+service = "public-keys-worker"
+```
+
+Public key rules:
+
+- accept `{ "keys": [...] }` and raw `[...]` payloads
+- reject private key material such as `d`
+- refetch keys once when a key id is unknown
+- clear caches in tests with `clearGlobalPublicKeyCache`
+
+## 4. Verify First-Party Browser Auth Cookies
+
+Use browser auth cookie helpers when the capability also has a first-party site.
+
+Example:
+
+```ts
+import { verifyAuthCookie } from "capability-worker/auth";
+import { errorJson, jsonResponse } from "capability-worker/http";
+
+const auth = await verifyAuthCookie(request, env, {
+  cookieName: "auth"
+});
+
+if (!auth.ok) {
+  return errorJson(auth.code, auth.message, auth.status);
+}
+
+const meeting = await env.DB.prepare(
+  "SELECT * FROM meetings WHERE id = ? AND account_id = ?"
+)
+  .bind(meetingId, auth.accountId)
+  .first();
+
+if (!meeting) {
+  return errorJson("meeting_not_found", "Meeting not found.", 404);
+}
+
+return jsonResponse({ ok: true, data: meeting });
+```
+
+Use browser auth for site-origin requests such as creator/admin views. Use capability signatures for agent/server-to-server management calls.
+
+Browser auth rules:
+
+- verify the JWT with keys from `CAPABILITY_PUBLIC_KEYS_URL`
+- accept only configured asymmetric algorithms, normally `ES256`
+- use `sub` as the verified account id
+- treat `email` as trusted only when `email_verified === true`
+- protect unsafe methods with an `Origin` allowlist
+- never accept admin status, creator id, or account id from the browser body, query string, local storage, or unsigned headers
+
+For routes that can accept either a capability signature or browser cookie, use `accountAuthFromRequest`:
+
+```ts
+import { accountAuthFromRequest } from "capability-worker/auth";
+
+const auth = await accountAuthFromRequest(request, env, {
+  cookieName: "auth"
+});
+```
+
+## 5. Return Consistent HTTP Responses
+
+Use the HTTP helpers to keep response shape consistent without adopting a router.
+
+```ts
+import {
+  HttpError,
+  errorJson,
+  errorResponse,
+  jsonResponse,
+  textResponse
+} from "capability-worker/http";
+
+export async function readMeeting(request: Request, env: Env) {
+  const meeting = await loadMeeting(request, env);
+
+  if (!meeting) {
+    throw new HttpError(404, "meeting_not_found", "Meeting not found.");
+  }
+
+  return jsonResponse({ ok: true, data: meeting });
+}
+```
+
+Error shape:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "invalid_request",
+    "message": "Invalid request."
+  }
+}
+```
+
+Useful helpers:
+
+```ts
+jsonResponse(value, init);
+textResponse(value, init);
+htmlResponse(value, init);
+redirectResponse(location, status);
+errorJson(code, message, status, extra);
+errorResponse(error);
+parseJsonBody(request);
+readJsonObject(request);
+isJsonRequested(url, body);
+stringParam(value);
+stringArrayParam(value);
+booleanParam(value);
+limitParam(value, defaultValue, max);
+getRepeated(url, key);
+```
+
+Return text command output exactly as the agent or user sees it:
+
+```ts
+return textResponse(
+  [
+    "ID      Starts              Title",
+    "mtg_1   2026-07-06 10:00   Intro call"
+  ].join("\n")
+);
+```
+
+If a command supports JSON output, expose a normal `--json` option in the definition asset and return `application/json` only when requested.
+
+## 6. Use Worker-Safe Crypto Helpers
+
+Use `capability-worker/crypto` for common Web Crypto and encoding work.
+
+```ts
+import {
+  base64UrlDecode,
+  base64UrlEncode,
+  randomBase64Url,
+  sha256Hex,
+  timingSafeEqual
+} from "capability-worker/crypto";
+
+const id = `file_${randomBase64Url(12)}`;
+const bodyHash = await sha256Hex(await request.arrayBuffer());
+const token = base64UrlEncode(new TextEncoder().encode("hello"));
+const bytes = base64UrlDecode(token);
+const matches = timingSafeEqual("a", "a");
+```
+
+Available helpers:
+
+```ts
+utf8(value);
+decodeUtf8(value);
+toArrayBuffer(bytes);
+base64UrlEncode(value);
+base64UrlDecode(value);
+base64Encode(value);
+base64Decode(value);
+sha256Hex(value);
+hmacSha256Base64Url(secret, payload);
+randomBytes(byteLength);
+randomBase64Url(byteLength);
+timingSafeEqual(a, b);
+```
+
+Use these instead of copying base64url, hashing, HMAC, random token, and timing-safe comparison code across workers.
+
+## 7. Encrypt Credential Fields
+
+Use credential helpers for account-owned secrets such as refresh tokens, app passwords, SMTP credentials, API keys, or provider tokens.
+
+```ts
+import {
+  decryptCredentialField,
+  encryptCredentialField
+} from "capability-worker/credentials";
+
+const encrypted = await encryptCredentialField({
+  env,
+  accountId,
+  rowId: connectionId,
+  fieldName: "refresh_token",
+  plaintext: refreshToken
+});
+
+await env.DB.prepare(
+  "UPDATE google_connections SET refresh_token_encrypted = ? WHERE id = ? AND account_id = ?"
+)
+  .bind(JSON.stringify(encrypted), connectionId, accountId)
+  .run();
+```
+
+Decrypt later using the same account id, row id, and field name:
+
+```ts
+const refreshToken = await decryptCredentialField({
+  env,
+  accountId,
+  rowId: connectionId,
+  fieldName: "refresh_token",
+  encrypted: JSON.parse(row.refresh_token_encrypted)
+});
+```
+
+Environment convention:
+
+```text
+CREDENTIAL_ENCRYPTION_KEYS={"v1":"<base64url-32-byte-key>"}
+CREDENTIAL_ACTIVE_KEY_ID=v1
+```
+
+Credential rules:
+
+- store one encrypted field as `{ keyId, nonce, ciphertext }`
+- use AES-GCM with a 12-byte random nonce
+- use AAD that includes account id, row id, field name, and key id
+- do not log plaintext, ciphertext, nonces, or full secret values
+- fail in production when no keyring is configured
+- rotate keys by changing `CREDENTIAL_ACTIVE_KEY_ID`; old fields continue to decrypt while their key remains in the keyring
+
+The package does not own your database schema. It only encrypts and decrypts values.
+
+## 8. Parse Multipart Requests And Validate Files
+
+Use file helpers when commands accept local files from the host.
+
+Expected multipart shape:
+
+```text
+payload=<JSON object string>
+attachments=<raw bytes>
+attachments=<raw bytes>
+```
+
+Route example:
+
+```ts
+import {
+  parseMultipartRequest,
+  validateCapabilityFiles
+} from "capability-worker/files";
+import { requireCapabilitySignature } from "capability-worker/auth";
+import { errorJson, jsonResponse } from "capability-worker/http";
+
+const rawBody = await request.arrayBuffer();
+
+const { accountId } = await requireCapabilitySignature(request, env, {
+  rawBody
+});
+
+const parsed = await parseMultipartRequest(
+  new Request(request, { body: rawBody }),
+  {
+    payloadFieldName: "payload",
+    fileFieldNames: ["attachments"],
+    maxTotalBytes: 20 * 1024 * 1024
+  }
+);
+
+const fileValidation = validateCapabilityFiles(parsed.files, {
+  allowedExtensions: [".pdf", ".png", ".jpg"],
+  allowedMimeTypes: ["application/pdf", "image/png", "image/jpeg"],
+  maxBytes: 10 * 1024 * 1024,
+  maxCount: 5,
+  maxTotalBytes: 20 * 1024 * 1024
+});
+
+if (!fileValidation.ok) {
+  return errorJson(
+    fileValidation.code,
+    fileValidation.message,
+    fileValidation.status
+  );
+}
+
+return jsonResponse({
+  ok: true,
+  accountId,
+  payload: parsed.payload,
+  fileCount: parsed.files.length
+});
+```
+
+Important: verify the signature before parsing multipart, but use the same raw bytes for both verification and parsing.
+
+File rules:
+
+- normalize and sanitize filenames
+- reject slashes, nulls, carriage returns, and line feeds in filenames
+- validate extension and MIME type server-side
+- enforce per-file byte limit, file count, and total byte limit
+- make file fields match the capability mapping
+
+## 9. Create R2 Or S3-Compatible Presigned URLs
+
+Use storage helpers when a worker writes generated files to a private bucket and returns a temporary download URL.
+
+For Cloudflare R2:
+
+```ts
+import { presignR2ObjectUrl } from "capability-worker/storage";
+
+const downloadUrl = await presignR2ObjectUrl(env, {
+  method: "GET",
+  key: `accounts/${accountId}/exports/${exportId}.pdf`,
+  expiresInSeconds: 3600,
+  query: {
+    "response-content-disposition": `attachment; filename="${filename}"`,
+    "response-content-type": "application/pdf"
+  }
+});
+```
+
+R2 environment:
+
+```text
+R2_PUBLIC_BASE_URL
+R2_ACCOUNT_ID
+R2_BUCKET_NAME
+R2_ACCESS_KEY_ID
+R2_SECRET_ACCESS_KEY
+```
+
+For generic S3-compatible storage:
+
+```ts
+import { presignS3ObjectUrl } from "capability-worker/storage";
+
+const url = await presignS3ObjectUrl({
+  method: "GET",
+  key: `accounts/${accountId}/exports/${exportId}.zip`,
+  expiresInSeconds: 3600,
+  config: {
+    baseUrl: "https://storage.example.com/bucket",
+    region: "auto",
+    service: "s3",
+    credentials: {
+      accessKeyId: env.S3_ACCESS_KEY_ID,
+      secretAccessKey: env.S3_SECRET_ACCESS_KEY
+    }
+  }
+});
+```
+
+Presigned URL rules:
+
+- default to read-only `GET` URLs
+- cap expiry in worker code, usually at 24 hours or less
+- keep buckets private
+- include the verified account id in object keys
+- never return access keys, secret keys, or signing keys
+- only use response override query params for presentation metadata
+- do not accept arbitrary object keys from request bodies without account-scope checks
+
+## 10. Create Worker-Proxied Signed Download URLs
+
+Use Worker-proxied signed download URLs for local development or when the Worker streams private R2 objects itself.
+
+```ts
+import {
+  createSignedDownloadUrl,
+  r2DownloadResponse,
+  verifySignedDownloadToken
+} from "capability-worker/storage";
+
+const url = await createSignedDownloadUrl({
+  env,
+  payload: {
+    accountId,
+    storageKey: `accounts/${accountId}/exports/${exportId}.pdf`,
+    filename: "invoice.pdf",
+    contentType: "application/pdf",
+    expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
+    disposition: "attachment"
+  },
+  routePrefix: "/__dev/r2-download"
+});
+```
+
+Handle the download route:
+
+```ts
+const url = new URL(request.url);
+
+if (url.pathname === "/__dev/r2-download") {
+  const token = url.searchParams.get("token");
+  if (!token) {
+    return new Response("Missing token.", { status: 400 });
+  }
+
+  const payload = await verifySignedDownloadToken(env, token);
+  return r2DownloadResponse({
+    bucket: env.PDFS,
+    payload
+  });
+}
+```
+
+Signed download rules:
+
+- sign payloads with HMAC-SHA256
+- use timing-safe comparison
+- return `403` for expired tokens
+- return `404` for missing R2 objects
+- include account id in the signed payload
+- use `cache-control: no-store` for private proxy downloads
+
+## 11. Validate Capability Contracts
+
+Use validation before deploy and in tests.
+
+```ts
+import { validateCapabilityAssets } from "capability-worker/validation";
+
+const issues = validateCapabilityAssets({
+  info,
+  definition,
+  mapping,
+  skillFiles: [
+    {
+      path: "SKILL.md",
+      content: skillMarkdown
+    }
+  ]
+});
+
+const errors = issues.filter((issue) => issue.severity === "error");
+
+if (errors.length > 0) {
+  throw new Error(errors.map((issue) => issue.message).join("\n"));
+}
+```
+
+The validator checks:
+
+- `info.schemaVersion`
+- required `info` fields
+- safe command names
+- `definition.schemaVersion`
+- `definition.cli.name === info.name`
+- stable and unique command ids
+- mapping keys exist in the definition
+- mapping paths are relative
+- path params exist in route paths
+- mapped fields exist in command arguments or options
+- file fields have constraints
+- skill paths are safe relative paths
+- public assets do not contain obvious secrets
+- production `apiBaseUrl` uses HTTPS
+
+CLI use:
+
+```sh
+pnpm exec capability-validate
+```
+
+Or validate during asset generation:
+
+```sh
+pnpm exec capability-build-assets --validate
+```
+
+## 12. Route Static Capability Assets
+
+Most workers use Cloudflare Workers Static Assets to serve contract files directly.
+
+If the worker must route assets itself, use the routing helper to detect capability asset paths and delegate to `env.ASSETS`.
+
+```ts
+import { isCapabilityAssetPath } from "capability-worker";
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (isCapabilityAssetPath(url.pathname, { basePath: "/api" })) {
+      return env.ASSETS.fetch(request);
+    }
+
+    return handleApi(request, env);
+  }
+};
+```
+
+The helper recognizes paths like:
+
+```text
+/info
+/definition
+/mapping
+/skill/SKILL.md
+/api/info
+/api/definition
+/api/mapping
+/api/skill/SKILL.md
+```
+
+This helper is only for identifying contract assets. It is not a full router.
+
+## 13. Test Signed Routes
+
+Use `capability-worker/testing` to remove repeated signing boilerplate while still testing the real Worker entrypoint.
+
+```ts
+import {
+  createCapabilityTestKeyPair,
+  publicKeysResponse,
+  withCapabilitySignature
+} from "capability-worker/testing";
+import worker from "../src/worker";
+
+test("lists meetings for the signed account", async () => {
+  const key = await createCapabilityTestKeyPair({ alg: "ES256" });
+
+  const env = {
+    ...testEnv,
+    CAPABILITY_PUBLIC_KEYS_JSON: JSON.stringify({
+      keys: [key.publicJwk]
+    })
+  };
+
+  const request = await withCapabilitySignature({
+    request: new Request("https://meeting.example.com/api/meetings"),
+    accountId: "acct_123",
+    keyId: key.keyId,
+    privateJwk: key.privateJwk
+  });
+
+  const response = await worker.fetch(request, env);
+
+  expect(response.status).toBe(200);
+});
+```
+
+Available helpers:
+
+```ts
+createCapabilityTestKeyPair(options);
+signCapabilityRequest(input);
+withCapabilitySignature(input);
+publicKeysResponse(keys);
+```
+
+Test cases every worker covers:
+
+- valid signatures
+- missing signatures
+- stale timestamps
+- wrong body hashes
+- unknown key ids and public-key refresh
+- account isolation
+- multipart body signatures
+- generated contract assets
+- text output mode
+- JSON output mode when a command supports `--json`
+
+Use Cloudflare's Workers Vitest integration for Worker tests. Do not replace D1, R2, KV, Durable Objects, assets, or bindings with hand-written mocks as proof that the Worker works.
+
+## Environment Variables
+
+Common worker variables:
+
+```text
+CAPABILITY_BASE_URL
+APP_ASSET_VERSION
+CAPABILITY_PUBLIC_KEYS_URL
+CAPABILITY_PUBLIC_KEYS_JSON
+CAPABILITY_PUBLIC_KEYS
+CREDENTIAL_ENCRYPTION_KEYS
+CREDENTIAL_ACTIVE_KEY_ID
+R2_PUBLIC_BASE_URL
+R2_ACCOUNT_ID
+R2_BUCKET_NAME
+R2_ACCESS_KEY_ID
+R2_SECRET_ACCESS_KEY
+S3_PUBLIC_BASE_URL
+S3_ENDPOINT
+S3_REGION
+S3_BUCKET_NAME
+S3_ACCESS_KEY_ID
+S3_SECRET_ACCESS_KEY
+DEV_DOWNLOAD_SECRET
+```
+
+Use Wrangler secrets for secret values:
+
+```sh
+wrangler secret put CREDENTIAL_ENCRYPTION_KEYS
+wrangler secret put R2_ACCESS_KEY_ID
+wrangler secret put R2_SECRET_ACCESS_KEY
+```
+
+Use Wrangler vars for public or non-secret values:
+
+```toml
+[vars]
+CAPABILITY_BASE_URL = "https://meeting.example.com/api"
+APP_ASSET_VERSION = "0.1.0"
+CAPABILITY_PUBLIC_KEYS_URL = "https://host.example.com/capability/public-keys"
+```
+
+## New Capability Worker Recipe
+
+1. Create `cli/definition.json`.
+2. Create `cli/mapping.json`.
+3. Create `skills/<capability-name>/SKILL.md`.
+4. Create `worker/capability/info.template.json`.
+5. Configure Wrangler static assets.
+6. Add `build:capability-assets`.
+7. Implement dynamic API routes.
+8. Verify signed account-scoped routes with `requireCapabilitySignature` or `verifyCapabilitySignature`.
+9. Scope every account-owned query and object key by verified account id.
+10. Return final command output from the worker as text or JSON.
+11. Validate assets with `capability-build-assets --validate`.
+12. Test through Cloudflare Workers Vitest or Wrangler-backed tooling.
+
+Minimal route skeleton:
+
+```ts
+import { requireCapabilitySignature } from "capability-worker/auth";
+import { errorResponse, jsonResponse, textResponse } from "capability-worker/http";
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      const url = new URL(request.url);
+
+      if (url.pathname === "/api/health") {
+        return jsonResponse({ ok: true });
+      }
+
+      if (url.pathname === "/api/meetings" && request.method === "GET") {
+        const { accountId } = await requireCapabilitySignature(request, env);
+        const wantsJson = url.searchParams.get("json") === "true";
+
+        const rows = await env.DB.prepare(
+          "SELECT id, title, starts_at FROM meetings WHERE account_id = ?"
+        )
+          .bind(accountId)
+          .all();
+
+        if (wantsJson) {
+          return jsonResponse({ ok: true, data: rows.results });
+        }
+
+        return textResponse(formatMeetingsTable(rows.results));
+      }
+
+      return jsonResponse(
+        {
+          ok: false,
+          error: {
+            code: "not_found",
+            message: "Not found."
+          }
+        },
+        404
+      );
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }
+};
+```
+
+## What Stays Local To Each Worker
+
+Keep these in the worker, not in `capability-worker`:
+
+- provider API clients
+- OAuth flows and provider-specific token refresh
+- product database schema
+- product domain validation
+- command-specific output formatting
+- email, calendar, invoice, or meeting business logic
+- public site UI
+- webhooks and provider-specific verification
+- deployment-specific route ownership
+
+The shared package owns repeated mechanics. The worker owns the product.
+
+## Compatibility Checklist
+
+Before shipping a worker that uses this package:
+
+- `/info`, `/definition`, `/mapping`, and `/skill/SKILL.md` are static assets
+- `info.name` matches `definition.cli.name`
+- command ids are stable and unique
+- every mapping key exists in the definition
+- mapping paths are relative under `apiBaseUrl`
+- public contract and skill assets contain no secrets or account data
+- production `apiBaseUrl` uses HTTPS
+- account-scoped routes verify `capability-signature-v1`
+- browser creator/admin routes verify the auth cookie and compare verified account id to stored ownership
+- every account-owned database query is scoped by verified account id
+- every account-owned object key includes verified account id
+- text and JSON output modes are documented and tested when both exist
+- tests use Wrangler-backed Cloudflare runtime tooling and configured bindings