@nomosprotocol/sdk 1.3.1 → 1.3.2

package/README.md

@@ -1,24 +1,36 @@
 # @nomosprotocol/sdk
 
-Official TypeScript SDK for [NOMOS](https://www.nomosprotocol.com) — ask "can I do this?" 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
 ```
 
-## `can()` — one function, three ways to ask
+## `can()` — one function for authority
 
-Same pattern as Stripe's PaymentIntents API: one function, routed entirely by what you pass it, one verdict vocabulary back regardless of which one ran.
+`can()` is the primary query interface to NOMOS.
 
-| You ask about... | Call it as | Needs an API key? |
-|---|---|---|
-| A public authority on the [NOMOS Exchange](https://www.nomosprotocol.com/exchange) | `nomos.can({ authority, ...facts })` | No |
-| Your own sealed artifact | `client.can({ artifact_id, ...facts })` | Yes |
-| An artifact someone handed you directly — NOMOS has never seen it | `nomos.can({ artifact, key_certs, root_public_key_pem, ...facts })` | No |
+It abstracts three different authority situations behind one call and one verdict vocabulary:
 
-### Public Exchange authority (keyless)
+| 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 |
 
-No API key, no setup — this is the front door.
+The caller does not need to know which evaluation rail is being used. `can()` routes internally based on what you provide.
+
+### 1. Public authority
+
+Ask a published authority directly:
 
 ```ts
 import { nomos } from "@nomosprotocol/sdk";
@@ -28,86 +40,201 @@ 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",
 });
 ```
 
-A paid authority you haven't purchased throws `NomosPaymentRequiredError` (with price + purchase URL attached) instead of a generic failure — NOMOS never auto-charges on your behalf. See [Error handling](#error-handling).
+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.
 
-### Your own artifact (authenticated)
+### 2. Your organization's authority
 
-Same function, same verdict shape — swap `authority` for `artifact_id` and use the authenticated client:
+Use an authenticated client for artifacts belonging to your organization:
 
 ```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 verdict = await client.can({
   artifact_id: "loan_approval_v1",
   credit_score: 720,
   loan_amount: 50_000,
 });
+
+if (verdict.allowed) {
+  // proceed
+}
 ```
 
-### Chain-of-trust (keyless, prototype)
+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
 
-For an artifact you received directly — from an agent, another system, anywhere — that NOMOS has never seen or registered. You supply the artifact, the key certificates presented alongside it, and the root public key **you've** independently decided to trust (there's deliberately no default). NOMOS verifies the chain resolves to that root, then evaluates the artifact's own rules against your facts — one call, no prior lookup:
+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: theArtifactYouWereHanded,
-  key_certs: theCertificatesTheyIncluded,
+  artifact: presentedArtifact,
+  key_certs: [rootToIntermediate, intermediateToLeaf],
   root_public_key_pem: yourPinnedRootKey,
   credit_score: 720,
 });
 ```
 
-If the chain doesn't resolve — unrecognized issuer, revoked key, tampered artifact — this throws `NomosIssuerNotTrustedError` rather than a fake verdict; "the rules say no" and "we never established who's asking" are different claims that call for different next steps. See [Error handling](#error-handling).
+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
 
-This rail is a working **prototype**, not yet a numbered NOMOS spec — the primitive is in production use but hasn't been through a second independent implementation.
+A `.nomos` file is a sealed, machine-executable representation of institutional authority.
 
-### The verdict
+It can contain the rules, constraints, permissions, obligations, provenance, issuer information, version, and other governance metadata required to evaluate an action.
 
-`can()` always returns the authority's own verdict, verbatim — nothing invented, nothing paraphrased — normalized into the same shape regardless of which rail answered:
+The artifact is cryptographically sealed.
 
-| 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 transcript id — Exchange rail only; absent (not faked) elsewhere |
-| `url` | `string` | Path to the transcript's permalink page — same availability as `query_id` |
-| `authority` | `{ id, title, standing, attestation? }` | Which authority answered, its standing, and — if a regulator/auditor/issuer has co-signed this exact version — who, in what role, and their statement |
-| `version` | `string` | The artifact's own declared `meta.version`, when it has one |
-| `missing_inputs` | `string[]` | Fields the authority needed but didn't get — present on `ESCALATED` |
-| `obligations` | `Array<{ kind, rule_id, rule_name }>` | Notify/log/flag-style duties that fired alongside the verdict — can accompany an `AUTHORIZED` result, not just a denial |
-| `revoked` | `boolean` | `true` only if the issuer has revoked this exact sealed version — forces `verdict` to `DENIED` regardless of what the rules say. Absent (not `false`) when revocation doesn't apply here |
-| `revocation_reason` | `string` | Present only alongside `revoked: true` |
-| `max_age` | `number` | Recommended seconds to hold this verdict before re-checking — advisory, absent when not structurally revocable |
-| `audit` | `{ hash, timestamp }` | Present only on the private-artifact rail — a hash you can store for compliance |
+Changing the authority changes the seal.
 
-`ESCALATED` means the authority needs more facts to decide — not a flat no. Check `missing_inputs` for what to supply.
+That makes the authority:
 
-The Exchange rail mints a permanent, cryptographically sealed transcript on every call — 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. The other two rails are stateless by design (asking about your own artifact, or one NOMOS has never seen, has no transcript to point to) — `audit.hash` is the private-artifact rail's own provenance instead.
+* **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.
 
-### Error handling
+The important distinction is:
 
-A failed call rejects with a typed `NomosError` subclass — never a bare `Error` — so you can branch on `instanceof` or the stable `.code` string:
+> 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
+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 {
@@ -119,64 +246,146 @@ import {
 } 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, unpurchased — err.priceUsd / err.purchaseUrl
+    // Paid authority that has not been purchased.
+    console.log(err.priceUsd);
+    console.log(err.purchaseUrl);
   } else if (err instanceof NomosIssuerNotTrustedError) {
-    // chain-of-trust rail only — err.reason is one of
-    // ISSUER_NOT_RECOGNIZED | KEY_REVOKED | SEAL_INVALID
+    // 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);
+```
+
+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
+
+`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.
 ```
 
-## `Nomos` — authenticated client
+The simplicity comes from giving each operation one meaning.
+
+## Authenticated client
 
-Beyond `client.can()`, the authenticated client covers the rest of the platform — the raw (richer) decision-verification shape, governance generation, and webhook verification:
+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_...");
+
+// Authorization
+await client.can({
+  artifact_id: "your_artifact_id",
+  ...facts,
+});
 
-// Lower-level than client.can() — same evaluation, but returns the full raw shape
-// (evaluation counts, confidence tier, paths_to_approval) instead of the normalized verdict.
-const result = await client.decisions.verify({
+// Lower-level decision verification
+await client.decisions.verify({
   artifact_id: "your_artifact_id",
-  decision_context: { /* facts */ },
+  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.1",
+  "version": "1.3.2",
   "description": "Official TypeScript SDK for the NOMOS governance runtime",
   "publishConfig": {
     "access": "public"