yichus 0.2.0 → 0.3.1

package/dist/studio-reference/worker-authority.md

@@ -0,0 +1,159 @@
+# Worker authority in generated APIs
+
+A worker is trusted deployment code, but its network caller still needs an
+identity. `worker_route` declares that identity separately from a user's roles.
+The declaration participates in the same typed route, permission and access
+analysis as other service routes:
+
+```bosatsu
+worker_route("/complete", handler("complete", complete),
+  "judgment", ["job-manager"], [WritePerm("results")])
+```
+
+Import `worker_route`, `handler` and `WritePerm` from `Yichus/Service`.
+The named handler takes the usual `Db`, injected `Principal` and typed inputs,
+and returns `IO`. The name and role list must be statically readable, nonblank
+literals or aliases; roles are nonempty and distinct. A matching
+`GuardedOrRoles` or `PublicReadRoleWrite` resource policy still governs the
+handler's effects. Shared `Table` and `TxTable` helper parameters retain the
+calling route's exact resource and authority; a dynamic table or an ordinary
+unprivileged caller does not inherit another route's grants.
+
+The name `judgment` is a logical deployment binding. It is not a credential,
+a client-supplied field or a session claim. A user session with `job-manager`
+cannot call this route. The server adapter maps a verified machine subject to
+the declared logical name and deployment-owned role grants. Worker credentials
+can call only worker routes for that name; they cannot impersonate users on
+ordinary routes. Worker principals have an opaque namespaced identity, derived
+from the logical name and verified subject; application code must not parse it.
+
+## Secret bootstrap
+
+A deployment without a machine identity provider can give each worker a long
+random secret instead. The worker sends it as its Bearer token, and the API
+holds the same secrets in its environment. The generated engine exports the
+verifier:
+
+```js
+import {
+  attachYichusWorkerVerifier, yichusSecretWorkerVerifier, startYichusApiEngine,
+} from './engine.mjs';
+
+attachYichusWorkerVerifier(yichusSecretWorkerVerifier([
+  { name: 'ingest', secret: process.env.INGEST_WORKER_SECRET, roles: ['ingest'] },
+]));
+await startYichusApiEngine(8080);
+```
+
+Each secret is at least 32 characters, and no two workers share one. Make it with
+`openssl rand -base64 48`, or with any other source of random bytes. A token is
+compared by its SHA-256 digest against every worker's in full. Rotating a secret
+means restarting the engine with the new one. Unlike Clerk M2M tokens, a secret
+does not expire on its own, so keep it on servers only.
+
+This fits a page host such as Vercel that receives a provider's webhook or a
+public form. Its route handler checks the provider's signature, or the form's
+bot check, and then calls the engine's worker route with the secret.
+
+## Clerk bootstrap
+
+The workspace package `@yichus/clerk-worker-auth` verifies **opaque Clerk M2M
+tokens** online. It does not accept session JWTs or M2M JWTs. Configure a
+receiving machine for the API and a sending machine for the judgment worker;
+the token's scopes must include the receiving machine. Keep the receiving
+machine's secret on the API server and the sending credential on the worker.
+Grant creation and token issuance are deployment setup, not frontend actions.
+
+With Node 20 or newer, first set the listener's authentication environment
+using the [session configuration](hosted-sessions.md), then attach the adapter
+before starting the generated engine:
+
+```js
+import {
+  attachYichusWorkerVerifier, attachYichusStore, startYichusApiEngine,
+} from './engine.mjs';
+import { createClerkWorkerVerifier } from '@yichus/clerk-worker-auth';
+
+attachYichusWorkerVerifier(createClerkWorkerVerifier({
+  machineSecretKey: process.env.CLERK_API_MACHINE_SECRET,
+  targetMachine: process.env.CLERK_API_MACHINE_ID,
+  workers: [{
+    name: 'judgment',
+    subject: process.env.CLERK_JUDGMENT_MACHINE_ID,
+    roles: ['job-manager'],
+  }],
+}));
+await attachYichusStore('memory'); // Local example; configure the production store separately.
+await startYichusApiEngine(8080);
+```
+
+These are illustrative environment variable names. No Clerk resource or
+secret is provisioned by this example. The package is currently a workspace
+package; deployment packaging must include it, rather than assuming a registry
+release. The listener always requires a supported `YICHUS_AUTH` mode, even when all
+routes are worker routes; the worker verifier supplements that configuration.
+The engine refuses to start with worker routes but no worker verifier.
+
+A worker sends its opaque token as `Authorization: Bearer <token>` on the
+worker route and supplies an `Idempotency-Key` for a mutation it may retry.
+Body and result JSON come from the generated OpenAPI operation. Its
+`x-yichus-worker` extension identifies the required worker; the operation
+description lists every required grant.
+The user-authenticated `/mcp` tool list excludes worker operations. This change
+does not introduce machine authentication for that MCP endpoint. Generated
+user frontends refuse worker routes as views rather than suggesting that a
+user session could supply their authority; ordinary user views can coexist
+with separately authenticated worker routes in the same API.
+
+The in-process counterpart is
+`yichusApiEngine.handleWithWorkerToken(path, token, args, { idempotencyKey })`.
+Direct `handle`, raw role arrays and forged proof objects cannot obtain worker
+authority. Installing a verifier is a trusted host capability: client code
+running its own local engine cannot confer authority on the deployed API.
+Never ship the Clerk adapter configured with a secret into a browser.
+
+## Refusals, retries and trust limits
+
+Each request, including an idempotent replay, calls Clerk's
+`POST /v1/m2m_tokens/verify` with the receiving machine's secret. The adapter
+checks the provider's subject, target scopes, revocation and expiry. Custom
+claims never select a worker name or role. The Clerk adapter copies configured grants at construction; attaching it stores
+the verifier reference. Replacing the verifier invalidates earlier and pending
+authority proofs.
+The runtime preserves its private proof through async dispatch and rechecks
+route authority before reading an idempotency record and before executing.
+A restart during authentication refuses the in-flight request.
+
+Invalid credentials return 401; an unconfigured sender, wrong target or
+insufficient route grant returns 403. Provider outages, malformed provider
+responses and verifier failures return 503 without returning credentials or
+provider error bodies. Verification defaults to a five-second timeout and
+has no successful-authentication cache. An outage therefore prevents even a
+previously completed request from being replayed through this entry.
+
+Revocation is checked at request authentication, not continuously throughout
+an already executing request. A worker is trusted to implement its program;
+its credential does not prove that its result is correct. The handler must
+still enforce leases, fences, current revisions, payload validation and atomic
+state transitions. Static access verification covers declared service entries;
+it does not certify every exported function a custom host could invoke.
+
+## Executed evidence and Icetakes integration
+
+`ApiWorkerAuthorityTest` compiles the real Bosatsu fixture, reads its authority
+through API MCP, and exercises the generated HTTP and in-process engine with
+the actual adapter and a local Clerk stand-in. It covers forged/user authority,
+wrong sender/target, revoked retry, outage, restart and role loss before replay.
+Runtime tests also cover proof replacement and malformed verifier results;
+adapter tests cover timeout, provider failures and ignored custom grants.
+The CLI proves all nine API properties for the fixture; negative variants
+reject dynamic tables and an unprivileged caller to its shared helper.
+
+These are local fixtures, not a live Clerk deployment. Icetakes still needs
+its worker entry wired and audited against the actual stage protocol, live
+machine provisioning, token rotation and outage/retry checks. Keep its combined
+provider-dispatch path until that conversion is validated. The whole-product
+G34 deployment verification work remains separate.
+
+Provider contracts: [Clerk M2M verification](https://clerk.com/docs/reference/backend/m2m-tokens/verify)
+and [M2M tokens](https://clerk.com/docs/guides/development/machine-auth/m2m-tokens).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yichus",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Local Bosatsu compilation, Yichus analysis, and generated apps using the WebMCP engine",
   "license": "MIT",
   "homepage": "https://yich.us",
@@ -20,7 +20,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@yichus/api-mcp": "0.1.1"
+    "@yichus/api-mcp": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",