@nomosprotocol/sdk 1.4.0 → 2.3.0

package/README.md

@@ -14,6 +14,103 @@ Give `can()` an authority, an action, and the relevant facts. NOMOS verifies the
 npm install @nomosprotocol/sdk
 ```
 
+## Acts: your first verified, committed change in five minutes
+
+An **Act** carries an exact change together with its proof: the sealed rules it acts under, facts
+signed by the systems that know them, and the approvals of the people who must approve. The system
+that makes the change verifies all of it itself, locally, and commits exactly that change or
+nothing (NOMOS-SPEC-008, NOMOS-SPEC-009).
+
+**1. Start a complete local world.** It includes a shop, a purchasing policy, a finance system that
+states budgets, and a manager who approves. Every key is a labelled test key.
+
+```bash
+npx @nomosprotocol/cli dev
+```
+
+**2. Act as an agent.** One call discovers the shop, gathers the signed budget from finance,
+submits, and returns the shop's verdict:
+
+```ts
+import { act } from '@nomosprotocol/sdk';
+
+const r = await act({
+  to: 'http://localhost:4747',
+  action: { type: 'purchase', subject: 'DEPT-17', params: { amount: 500, vendor: 'paperco' } },
+});
+console.log(r.status, r.summary);   // committed Committed by shop.local.
+```
+
+Try `amount: 2000`: the manager must approve, and the approval link prints in the sandbox window.
+Try `amount: 9000` (over budget), `vendor: 'shadyco'` (blocked), or `subject: 'DEPT-99'` (finance
+knows nothing). `r.missing` then names exactly the fact that is missing, and why.
+
+**3. Be the system that makes the change.** Wrap your existing handler with `accept()`. It runs the
+verifier locally and then, in one transaction, records the nonce, re-reads your own facts, hands
+`commit` exactly the verified action, and stores the receipt:
+
+```ts
+import pg from 'pg';
+import { accept, postgresStore } from '@nomosprotocol/sdk';
+
+const store = postgresStore(new pg.Pool({ connectionString: process.env.DATABASE_URL }));
+await store.migrate();                                       // once: creates the nomos_acts table
+
+const rp = accept({
+  relyingPartyId: 'orders.acme.example',
+  root: ACME_ROOT_PEM,                                       // the root you pin; there is no default
+  actEndpoint: 'https://orders.acme.example/nomos/acts',
+  authorities: [{ artifactId: 'acme-purchasing', issuer: 'https://policy.acme.example',
+                  actions: ['purchase'], currencyPolicy: 'record', inForceSealHash: POLICY_SEAL_HASH }],
+  localFacts: async (act) => ({ vendor_blocked: await isBlocked(act.action.params.vendor) }),
+  commit: async (action, { tx }) => createOrder(tx, action),  // your existing code, on the same transaction
+  store,                                                     // nonces, receipts and the Acts themselves
+});
+
+app.use(rp.express());          // Express, Connect, node:http
+// or: export default { fetch: rp.fetch }   — Hono, Next.js, Cloudflare Workers, Deno, Bun
+```
+
+`accept()` serves your discovery document at `/.well-known/nomos-relying-party`, generated from this
+same configuration, and answers every Act with the status NOMOS-SPEC-009 assigns.
+
+`postgresStore()` records the nonce, your change and the receipt in one transaction: `commit`
+receives `tx`, the same client. Under any number of concurrent submissions of one Act exactly one
+commits and the rest get `409` with its receipt, and the exact Act is kept beside its receipt so
+an auditor can re-verify it later. It takes a node-postgres `Pool` or anything with the same
+`query`/`connect` methods (Neon's serverless driver on edge runtimes, for example) and depends on
+no driver itself. `memoryStore()`, the default, is for development only.
+
+| Verdict | Status |
+|---|---|
+| AUTHORIZED, committed | 201 |
+| ESCALATED | 202 |
+| INCOMPLETE | 422 |
+| DENIED | 403 |
+| REPLAYED | 409, with the original receipt |
+| any other refusal | 400 |
+
+**Certificates and revocations.** `act()` presents exactly the certificates an Act relies on
+(NOMOS-SPEC-009 0.2.0), so an issuer can certify any number of approvers. Witnesses and approvers
+can return their own chains with what they sign (`keyCerts`). On the relying party,
+`revocations: revocationSource({ url, root, maxAgeSeconds })` reads the issuer's signed list
+(NOMOS-SPEC-007 rev. 1.10). Revocations are never forgotten, and without a current list
+`accept()` answers 503 instead of committing.
+
+**The other roles** are one call each:
+- `issuer()` publishes your sealed policies and certificates;
+- `witness()` turns an existing lookup into signed statements;
+- `approver()` shows a person the exact change and signs their consent; `passkeyApprover()` has them
+  sign it with Face ID, Touch ID or a security key, enrolled through a single-use link
+  (`nomos enroll`), so no server can approve for them.
+
+Keys are `Signer`s, so they can live in your KMS or HSM: [`@nomosprotocol/signers`](../packages/signers) has adapters for AWS KMS, Google Cloud KMS, Azure Key Vault and any other HSM.
+
+**Any MCP agent** can carry Acts with no code: the `nomos-mcp` server has an `act` tool.
+
+Verification is `@nomosprotocol/verify`, re-exported here as `verifyAct`, `verifyArtifact` and
+`verifySeal`. It runs entirely offline, in Node, browsers and edge runtimes.
+
 ## `can()` — one function for authority
 
 `can()` is the primary query interface to NOMOS.
@@ -434,7 +531,7 @@ The long-term goal is simple:
 
 ## Requirements
 
-* Node.js 18+
+* Node.js 20+
 * TypeScript supported
 * ESM and CommonJS builds
 * Full TypeScript declarations