@nomosprotocol/sdk 1.3.4 → 2.0.0

package/README.md

@@ -14,6 +14,83 @@ 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 { accept } from '@nomosprotocol/sdk';
+
+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
+  store: myPostgresStore,                                    // nonces and receipts; memoryStore() for development
+});
+
+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.
+
+| Verdict | Status |
+|---|---|
+| AUTHORIZED, committed | 201 |
+| ESCALATED | 202 |
+| INCOMPLETE | 422 |
+| DENIED | 403 |
+| REPLAYED | 409, with the original receipt |
+| any other refusal | 400 |
+
+**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.
+
+Keys are `Signer`s, so they can live in your KMS or 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.
@@ -227,6 +304,31 @@ An untrusted issuer is different from a rule saying "no."
 
 NOMOS keeps those failure classes separate.
 
+### `max_age` — how long a verdict should be trusted
+
+```ts
+verdict.max_age; // 300, or absent
+```
+
+`AUTHORIZED` is true of a moment, not forever. Between your `can()` call and whatever
+the agent actually does, the authority could be amended, the fact set could go stale, or
+the artifact could be revoked. A caller that treats a cached verdict as valid indefinitely
+has quietly reintroduced the gap `can()` exists to close.
+
+`max_age` (seconds) is NOMOS's answer: re-run `can()` if more than this many seconds have
+passed since the decision you're about to act on. Today it is present — always `300` —
+**only** on the public authority rail (`nomos.can({ authority, ...facts })`), and only
+when the evaluated artifact is structurally revocable (Ed25519-sealed with a `kid`, on a
+deployment with revocation configured). It is **absent** otherwise, on purpose: an
+artifact NOMOS cannot meaningfully re-check should never look as trustworthy as one it
+can, so absence is a signal to re-verify more, not less. Treat a missing `max_age` as "no
+guidance was possible," never as "safe to cache indefinitely."
+
+**Disclosed gap:** `client.can({ artifact_id, ... })` and the presented-artifact rail
+don't emit `max_age` yet — the field exists only on the query path that backs the public
+rail. Until that's closed, apply the same discipline manually on those two rails: don't
+hold a verdict across a meaningful delay before acting on it without re-checking.
+
 ## Authority trust is separate from authorization
 
 The portable-authority rail deliberately distinguishes two questions:
@@ -409,7 +511,7 @@ The long-term goal is simple:
 
 ## Requirements
 
-* Node.js 18+
+* Node.js 20+
 * TypeScript supported
 * ESM and CommonJS builds
 * Full TypeScript declarations