@nomosprotocol/sdk 1.3.0 → 1.3.2

package/README.md

@@ -1,14 +1,36 @@
 # @nomosprotocol/sdk
 
-Official TypeScript SDK for [NOMOS](https://www.nomosprotocol.com) — ask a public authority a question from your code and get back a deterministic, cryptographically verifiable verdict.
+Official TypeScript SDK for [NOMOS](https://www.nomosprotocol.com/) — a programmable authority layer for AI agents and software.
+
+NOMOS lets software ask a simple question:
+
+> **Can I do this?**
+
+Give `can()` an authority, an action, and the relevant facts. NOMOS verifies the authority, evaluates its rules, and returns a deterministic verdict:
+
+**AUTHORIZED · DENIED · ESCALATED**
 
 ```bash
 npm install @nomosprotocol/sdk
 ```
 
-## `nomos.can()` — the keyless primitive
+## `can()` — one function for authority
+
+`can()` is the primary query interface to NOMOS.
+
+It abstracts three different authority situations behind one call and one verdict vocabulary:
+
+| You have...                                                | Call                                                                | API key? |
+| ---------------------------------------------------------- | ------------------------------------------------------------------- | -------: |
+| A public authority published on the NOMOS Exchange         | `nomos.can({ authority, ...facts })`                                |       No |
+| Your organization's sealed artifact                        | `client.can({ artifact_id, ...facts })`                             |      Yes |
+| A sealed artifact presented directly by an agent or system | `nomos.can({ artifact, key_certs, root_public_key_pem, ...facts })` |       No |
+
+The caller does not need to know which evaluation rail is being used. `can()` routes internally based on what you provide.
 
-Every public authority on the [NOMOS Exchange](https://www.nomosprotocol.com/exchange) is queryable with one call. No API key, no setup — this is the front door.
+### 1. Public authority
+
+Ask a published authority directly:
 
 ```ts
 import { nomos } from "@nomosprotocol/sdk";
@@ -18,101 +40,352 @@ const verdict = await nomos.can({
   ai_categorises_biometric_data_for_sensitive_attributes: true,
 });
 
-if (!verdict.allowed) {
-  console.log(verdict.verdict);   // "DENIED"
-  console.log(verdict.reason);    // why
-  console.log(verdict.query_id);  // permanent transcript id
-}
+console.log(verdict.verdict);
+// "DENIED"
+
+console.log(verdict.reason);
+// explanation from the authority
+
+console.log(verdict.query_id);
+// permanent transcript ID
 ```
 
-Facts can be spread flat alongside `authority` (as above), or passed explicitly:
+No API key or account is required for public Exchange authorities.
+
+Facts can also be passed explicitly:
 
 ```ts
 const verdict = await nomos.can({
   authority: "eu-ai-act.nomos",
-  inputs: { ai_categorises_biometric_data_for_sensitive_attributes: true },
-  action: "screen a new feature before launch", // optional, recorded in the transcript
+  inputs: {
+    ai_categorises_biometric_data_for_sensitive_attributes: true,
+  },
+  action: "screen a new feature before launch",
+});
+```
+
+If a paid authority has not been purchased, NOMOS throws `NomosPaymentRequiredError` with the price and purchase URL attached.
+
+NOMOS never auto-charges on your behalf.
+
+### 2. Your organization's authority
+
+Use an authenticated client for artifacts belonging to your organization:
+
+```ts
+import { Nomos } from "@nomosprotocol/sdk";
+
+const client = new Nomos("nms_live_...");
+
+const verdict = await client.can({
+  artifact_id: "loan_approval_v1",
+  credit_score: 720,
+  loan_amount: 50_000,
+});
+
+if (verdict.allowed) {
+  // proceed
+}
+```
+
+The same verdict vocabulary is returned.
+
+The difference is that the artifact is private and accessed through your authenticated NOMOS account.
+
+### 3. A portable authority presented by an agent
+
+This is the keyless, portable authority rail.
+
+An agent can carry a sealed `.nomos` artifact with it and present that authority to another system — even if NOMOS has never seen or registered the artifact.
+
+```ts
+const verdict = await nomos.can({
+  artifact: presentedArtifact,
+  key_certs: [rootToIntermediate, intermediateToLeaf],
+  root_public_key_pem: yourPinnedRootKey,
+  credit_score: 720,
 });
 ```
 
-### The verdict
+NOMOS performs the entire verification locally:
+
+1. Walk the presented certificate chain from the root key you've pinned.
+2. Verify each link's signature and check it hasn't expired.
+3. Check that no key in the chain has been revoked.
+4. Verify the artifact's own cryptographic seal against the resolved key.
+5. Evaluate the artifact's rules against the supplied facts.
+6. Return `AUTHORIZED`, `DENIED`, or `ESCALATED`.
+
+(NOMOS-SPEC-006 artifact-version revocation — an issuer withdrawing one specific sealed version — is checked on the Exchange rail today; wiring the same check into this rail is a known gap, not yet done.)
+
+No prior artifact lookup is required.
+
+This means authority can **travel with the agent**.
+
+The relying party does not have to trust the AI vendor, the model, or a pre-existing NOMOS registry entry. It can independently verify the authority presented to it.
+
+The root key is deliberately supplied by the relying party. NOMOS does not define a universal default root of trust.
+
+This rail is currently a working prototype and is not yet a numbered NOMOS specification. A second independent implementation is still required before treating the wire format as interoperable infrastructure.
+
+## `.nomos` — the portable authority artifact
 
-`nomos.can()` always returns the authority's own verdict, verbatim — nothing invented, nothing paraphrased:
+A `.nomos` file is a sealed, machine-executable representation of institutional authority.
 
-| Field | Type | Meaning |
-|---|---|---|
-| `allowed` | `boolean` | `true` only when `verdict === "AUTHORIZED"` |
-| `verdict` | `"AUTHORIZED" \| "DENIED" \| "ESCALATED"` | The authority's own answer |
-| `reason` | `string` | Human-readable explanation |
-| `rule` | `string \| null` | The rule id that decided it, if any |
-| `query_id` | `string` | Permanent, addressable transcript id |
-| `url` | `string` | Path to the transcript's permalink page |
-| `authority` | `{ id, title, standing }` | Which authority answered, and its standing |
-| `missing_inputs` | `string[]` | Fields the authority needed but didn't get — present on `ESCALATED` |
+It can contain the rules, constraints, permissions, obligations, provenance, issuer information, version, and other governance metadata required to evaluate an action.
 
-`ESCALATED` means the authority needs more facts to decide — not a flat no. Check `missing_inputs` for what to supply.
+The artifact is cryptographically sealed.
 
-Every call mints a permanent, cryptographically sealed transcript — open `query_id` any time at `nomosprotocol.com/queries/<query_id>` to replay exactly what was asked and answered, bound to the exact authority version that responded.
+Changing the authority changes the seal.
 
-### Error handling
+That makes the authority:
 
-A failed call (unknown authority, network issue, upstream error) rejects with a typed `NomosError` subclass — never a bare `Error` — so you can branch on `instanceof` or the stable `.code` string:
+* **machine-executable** — software can evaluate it;
+* **portable** — it can move between systems;
+* **verifiable** — another party can check its authenticity;
+* **versioned** — the exact authority being evaluated can be identified;
+* **auditable** — decisions can be tied back to the authority that produced them.
+
+The important distinction is:
+
+> The AI does not have to carry the policy in its prompt and be trusted to obey it.
+
+The authority can exist outside the model as a verifiable artifact.
+
+The model reasons.
+
+**NOMOS determines what the authority permits.**
+
+## The verdict
+
+`can()` normalizes every rail into the same core result:
+
+| Field               | Type                                | Meaning                                                  |
+| ------------------- | ------------------------------------ | -------------------------------------------------------- |
+| `allowed`           | `boolean`                           | `true` only when the verdict is `AUTHORIZED`             |
+| `verdict`           | `AUTHORIZED \| DENIED \| ESCALATED` | The authority's decision                                 |
+| `reason`            | `string`                            | Human-readable explanation                               |
+| `rule`              | `string \| null`                    | Rule that determined the result, when applicable         |
+| `authority`         | `{ id, title, standing, attestation? }` | The authority that answered, its standing, and — when a regulator/auditor/issuer has co-signed this exact version — who, in what role, and their statement |
+| `version`           | `string`                            | Authority version, when declared                         |
+| `missing_inputs`    | `string[]`                          | Facts required for an `ESCALATED` decision               |
+| `obligations`       | array                               | Additional duties triggered alongside the verdict        |
+| `revoked`           | `boolean`                           | Whether the evaluated authority version has been revoked |
+| `revocation_reason` | `string`                            | Reason for revocation, when applicable                   |
+| `max_age`           | `number`                            | Recommended period before re-checking the verdict        |
+| `audit`             | `{ hash, timestamp }`               | Present only on your own artifact rail — your own provenance record, distinct from the Exchange rail's public transcript |
+
+### `ESCALATED` is not `DENIED`
+
+An escalation means the authority does not yet have enough information to decide.
 
 ```ts
-import { nomos, NomosNotFoundError, NomosNetworkError } from "@nomosprotocol/sdk";
+if (verdict.verdict === "ESCALATED") {
+  console.log(verdict.missing_inputs);
+}
+```
+
+This distinction matters in institutional workflows.
+
+A missing fact is different from a prohibition.
+
+An untrusted issuer is different from a rule saying "no."
+
+NOMOS keeps those failure classes separate.
+
+## Authority trust is separate from authorization
+
+The portable-authority rail deliberately distinguishes two questions:
+
+**"Do I trust this authority?"**
+
+and
+
+**"Does this authority permit this action?"**
+
+If the presented chain cannot be established, NOMOS throws `NomosIssuerNotTrustedError`.
+
+It does **not** return `DENIED`.
+
+```ts
+try {
+  const verdict = await nomos.can({
+    artifact,
+    key_certs,
+    root_public_key_pem,
+    credit_score: 720,
+  });
+} catch (err) {
+  if (err instanceof NomosIssuerNotTrustedError) {
+    // The authority itself was not established as trustworthy.
+  }
+}
+```
+
+A `DENIED` verdict means:
+
+> **The authority was established, and its rules said no.**
+
+An issuer-trust error means:
+
+> **The authority itself was not established.**
+
+Those are fundamentally different claims.
+
+## Errors
+
+NOMOS uses typed errors rather than generic failures:
+
+```ts
+import {
+  nomos,
+  NomosNotFoundError,
+  NomosNetworkError,
+  NomosPaymentRequiredError,
+  NomosIssuerNotTrustedError,
+} from "@nomosprotocol/sdk";
 
 try {
-  const verdict = await nomos.can({ authority: "eu-ai-act.nomos", ...facts });
+  const verdict = await nomos.can({
+    authority: "eu-ai-act.nomos",
+    ...facts,
+  });
 } catch (err) {
   if (err instanceof NomosNotFoundError) {
-    // authority slug/id doesn't exist — err.code === 'not_found'
+    // Authority does not exist.
+  } else if (err instanceof NomosPaymentRequiredError) {
+    // Paid authority that has not been purchased.
+    console.log(err.priceUsd);
+    console.log(err.purchaseUrl);
+  } else if (err instanceof NomosIssuerNotTrustedError) {
+    // Portable authority could not be established.
+    console.log(err.reason);
+    // ISSUER_NOT_RECOGNIZED
+    // KEY_REVOKED
+    // SEAL_INVALID
   } else if (err instanceof NomosNetworkError) {
-    // request timed out or the network failed
+    // Network failure or timeout.
   } else {
     throw err;
   }
 }
 ```
 
-### Options
+## Permanent decision transcripts
+
+For public Exchange authorities, every `can()` request produces a permanent transcript.
+
+The transcript records what was asked, which authority version answered, and what it decided.
+
+The returned `query_id` can be used to retrieve the transcript:
 
 ```ts
-await nomos.can(
-  { authority: "...", ...facts },
-  {
-    baseUrl: "https://www.nomosprotocol.com", // override for local/staging use
-    signal: abortController.signal,           // cancel the request
-  },
-);
+console.log(verdict.query_id);
+console.log(verdict.url);
 ```
 
-## `Nomos` — authenticated client
+The portable and private artifact rails are stateless by design and do not invent a server-side transcript ID.
+
+## What `can()` does — and does not do
 
-For private/custom artifacts, governance generation, and webhook verification, use the authenticated client:
+`can()` answers one question:
+
+> **Is this action authorized under this authority, given these facts, right now?**
+
+It deliberately does not become the interface for everything NOMOS does. Other capabilities stay on the authenticated client, because they answer different questions:
+
+```ts
+await client.can({ artifact_id, ...facts })                     // Is this action authorized?
+await verifyChain({ artifact, key_certs, root_public_key_pem })  // Is this artifact's chain of custody genuine?
+await client.artifacts.list({ band, sort })                      // What artifacts are available?
+await client.artifacts.retrieve(id)                              // What is inside this artifact?
+await client.governance.generate({ policies, decision_logs })    // Create a new sealed artifact.
+await client.governance.detectContradictions({ rules })          // Find conflicts in a rule set.
+```
+
+The simplicity comes from giving each operation one meaning.
+
+## Authenticated client
+
+The authenticated `Nomos` client exposes the broader platform:
 
 ```ts
 import { Nomos } from "@nomosprotocol/sdk";
 
-const client = new Nomos("nms_live_..."); // or "nms_test_..." for test mode
+const client = new Nomos("nms_live_...");
 
-const result = await client.decisions.verify({
+// Authorization
+await client.can({
   artifact_id: "your_artifact_id",
-  decision_context: { /* facts */ },
+  ...facts,
 });
 
+// Lower-level decision verification
+await client.decisions.verify({
+  artifact_id: "your_artifact_id",
+  decision_context: { ...facts },
+});
+
+// Discover artifacts
 for await (const artifact of client.artifacts.listAutoPaging()) {
   console.log(artifact.id);
 }
 
-const event = await client.webhooks.constructEvent(payload, signatureHeader, webhookSecret);
+// Verify webhook events
+const event = await client.webhooks.constructEvent(
+  payload,
+  signatureHeader,
+  webhookSecret,
+);
 ```
 
-See [nomosprotocol.com/docs](https://www.nomosprotocol.com/docs) for full API reference, error types, and webhook event shapes.
+`client.decisions.verify()` remains available when the caller needs the lower-level evaluation response rather than the normalized `can()` result.
+
+## Why this exists
+
+AI agents can reason.
+
+They can plan.
+
+They can call tools.
+
+But reasoning about authority is not the same thing as possessing authority.
+
+A system prompt can tell an agent:
+
+> "You may approve loans below this threshold."
+
+That does not independently prove that the instruction is authentic, current, untampered with, or actually authoritative.
+
+NOMOS moves that authority outside the model.
+
+The authority becomes a machine-readable artifact.
+
+The artifact can be verified.
+
+The rules can be evaluated deterministically.
+
+And the result can be checked independently of the model that requested the action.
+
+The long-term goal is simple:
+
+> **AI agents should not have to be trusted to understand their authority. Their authority should be something other systems can verify.**
 
 ## Requirements
 
-Node.js 18+. Ships as dual ESM/CJS with full TypeScript types.
+* Node.js 18+
+* TypeScript supported
+* ESM and CommonJS builds
+* Full TypeScript declarations
 
 ## License
 
 MIT
+
+## Links
+
+* [NOMOS Protocol](https://www.nomosprotocol.com/)
+* [Documentation](https://www.nomosprotocol.com/docs)
+* [NOMOS Exchange](https://www.nomosprotocol.com/exchange)
+* [NOMOS Specification](https://www.nomosprotocol.com/spec)
+* [GitHub](https://github.com/nomos-spec/spec)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomosprotocol/sdk",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Official TypeScript SDK for the NOMOS governance runtime",
   "publishConfig": {
     "access": "public"