@nomosprotocol/sdk 2.3.2 → 2.6.0

package/README.md

@@ -122,9 +122,55 @@ It abstracts three different authority situations behind one call and one verdic
 | 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 |
+| An act, and you don't know which laws govern it            | `nomos.can({ context, ...facts })`                                  |       No |
 
 The caller does not need to know which evaluation rail is being used. `can()` routes internally based on what you provide.
 
+### 0. Ask by context: let NOMOS find the laws (2.6.0)
+
+Naming a law lets the caller choose which law is checked, and leave out the strict one. Describe
+the act instead, and NOMOS works out which laws govern it, asks every one, and combines the answers:
+any deny denies, and a yes needs every law to say yes.
+
+```ts
+import { can } from '@nomosprotocol/sdk';
+
+const v = await can({
+  context: {
+    jurisdiction: 'AE',        // where the act takes effect
+    established_in: 'DIFC',    // where your organisation is incorporated or established
+    subjects_in: 'AE',         // where the people it concerns are
+    output_used_in: 'AE',      // where any AI output is used
+  },
+  action: 'share_customer_data_with_analytics_vendor',
+  processing_fair_and_transparent: false,
+});
+
+v.mode;            // 'resolution'
+v.verdict;         // 'DENIED': a DIFC firm acting in mainland Dubai answers to DIFC law
+v.answered_under;  // ['difc-data-protection-law-difc-law-no-5-of-2020']
+v.coverage;        // what the answer covers, in words
+v.members;         // each law's own answer, each a signed record (query_id)
+```
+
+What can come back besides a verdict:
+
+- `INSUFFICIENT_DATA` with `open_facts`: a fact that decides which law applies was not stated
+  (for example `established_in`). It is asked for, never assumed.
+- `INSUFFICIENT_DATA` for a place the registrar does not cover (Saudi Arabia, the US, an ADGM or
+  QFC firm today). "No law found" is never read as "no law applies".
+- `CONFLICT`: two registrars each claim exclusive precedence. A person decides.
+
+Which laws apply where comes from the NOMOS registrar: a signed, append-only list in the public
+log at `/.well-known/nomos-exchange-log`, verifiable offline. Each claim states the provision it
+rests on. It currently covers the EU AI Act, Qatar Law No. 13 of 2016, UAE Federal Decree-Law
+No. 45 of 2021 and DIFC Law No. 5 of 2020, and lists only its own laws, so other law may also
+apply. Only want the list of laws? `POST /api/v1/resolve { context }` returns it without asking
+them, and records nothing.
+
+`accept()` still verifies the one authority an Act carries. Resolving inside `accept()`, from
+registrars the receiving system pins, is the next step of NOMOS-SPEC-014.
+
 ### 1. Public authority
 
 Ask a published authority directly:
@@ -176,6 +222,41 @@ If a paid authority has not been purchased, NOMOS throws `NomosPaymentRequiredEr
 
 NOMOS never auto-charges on your behalf.
 
+### Escalations that reach a person
+
+Click **Use this law** on an authority's Exchange page (signed in). From then on, when that law
+answers ESCALATED to a call made with your API key, your approvers get an email and approve on a
+page. An API key can never approve, so an agent can't approve itself. Your code can wait for the answer:
+
+```ts
+import { Nomos } from "@nomosprotocol/sdk";
+
+const client = new Nomos(process.env.NOMOS_API_KEY!);
+const r = await client.can(
+  { authority: "difc-data-protection-law-difc-law-no-5-of-2020",
+    ...allTwelveNo,                 // the law's intake questions, listed on its page
+    q_individual_request: true,     // "yes": a request from a person
+    access_request_received: true, days_since_access_request: 45,
+    identity_doubt_unresolved: false, response_period_extended_with_notice: false },
+  { awaitApproval: { timeoutMs: 10 * 60_000, onApproval: (a) => console.log("waiting on", a.url) } },
+);
+
+if (r.allowed) proceed();      // AUTHORIZED, or a person approved this exact call (spent once)
+else console.log(r.verdict, r.approval?.status); // DENIED, or rejected / timed_out
+```
+
+The approval is bound to the authority, the action and the facts: different facts need a new one.
+
+A large law carries a few yes/no **intake questions** (listed on its page). Each "no" rules out the
+articles it covers, so an ordinary action gets a firm answer in one call: on the DIFC Data Protection
+Law, all twelve "no" is `AUTHORIZED`.
+
+When a listing is replaced by a newer version and retired, calls to the old address throw a
+`NomosAPIError` with status 410: the message names the new version's address. Move to it; the old
+address is never answered from the old rules.
+When the law gets a new version, you get an email with what changed. Turn either email off on the
+same page.
+
 ### 2. Your organization's authority
 
 Use an authenticated client for artifacts belonging to your organization:

package/dist/index.cjs

@@ -191,7 +191,7 @@ function isRetryable(status) {
 }
 
 // src/http-client.ts
-var SDK_VERSION = "2.3.2";
+var SDK_VERSION = "2.6.0";
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -721,7 +721,9 @@ function normalizeAuthorityQueryResult(data, authority) {
     // NOMOS-SPEC-006 — present only when the issuer has actually revoked this exact sealed
     // version; omitted (not false) when revocation doesn't structurally apply here, so "checked
     // and clean" and "couldn't check" never look the same to a caller.
-    ...data.revoked === true ? { revoked: true, revocation_reason: data.revocation_reason } : {}
+    ...data.revoked === true ? { revoked: true, revocation_reason: data.revocation_reason } : {},
+    ...data.signature ? { signature: data.signature } : {},
+    ...data.evaluator_version ? { evaluator_version: data.evaluator_version } : {}
   };
 }
 function callerHeaders(c) {
@@ -751,9 +753,34 @@ async function canViaExchange(authority, facts, action, opts) {
   if (!res.ok) mapHttpError(res.status, data, requestId);
   return normalizeAuthorityQueryResult(data, authority);
 }
-async function canViaExchangeAuthenticated(http, authority, facts, action, caller) {
-  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts }, { headers: callerHeaders(caller) });
-  return normalizeAuthorityQueryResult(data, authority);
+async function canViaExchangeAuthenticated(http, authority, facts, action, opts) {
+  const ask = async () => (await http.post("/api/v1/can", { artifact: authority, action, ...facts }, { headers: callerHeaders(opts?.caller) })).data;
+  const data = await ask();
+  const result = normalizeAuthorityQueryResult(data, authority);
+  const approval = data?.approval;
+  if (!approval) return result;
+  result.approval = { id: approval.id, url: approval.url, status: approval.status };
+  if (!opts?.awaitApproval || result.verdict !== "ESCALATED") return result;
+  return awaitApproval(http, result, typeof opts.awaitApproval === "object" ? opts.awaitApproval : {});
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function awaitApproval(http, result, o) {
+  const a = result.approval;
+  o.onApproval?.({ id: a.id, url: a.url });
+  const deadline = Date.now() + (o.timeoutMs ?? 6e5);
+  let status = a.status;
+  while (status === "pending" && Date.now() < deadline) {
+    await sleep2(Math.max(500, o.pollMs ?? 3e3));
+    status = (await http.get(`/api/v1/approvals/${a.id}`)).data?.status ?? "pending";
+  }
+  if (status === "pending") return { ...result, approval: { ...a, status: "timed_out" } };
+  if (status !== "approved") return { ...result, approval: { ...a, status: "rejected" } };
+  try {
+    await http.post(`/api/v1/approvals/${a.id}/consume`, {});
+  } catch {
+    return { ...result, approval: { ...a, status: "not_usable" } };
+  }
+  return { ...result, allowed: true, approval: { ...a, status: "approved" } };
 }
 async function canViaArtifact(http, artifactId, facts, action) {
   const isPublic = artifactId.startsWith("pub_");
@@ -831,6 +858,50 @@ async function canViaChain(artifact, keyCerts, rootPublicKeyPem, facts, action,
   if (data?.decision === "MALFORMED") throw new NomosValidationError(message, data, requestId);
   mapHttpError(res.status, data, requestId);
 }
+function normalizeResolutionResult(data) {
+  return {
+    mode: "resolution",
+    allowed: data.verdict === "AUTHORIZED",
+    verdict: data.verdict,
+    reason: data.reason ?? "",
+    resolution: data.resolution ?? { status: "INCOMPLETE", proof: null },
+    members: Array.isArray(data.members) ? data.members : [],
+    deciding_authorities: Array.isArray(data.deciding_authorities) ? data.deciding_authorities : [],
+    escalations: Array.isArray(data.escalations) ? data.escalations : [],
+    open_facts: Array.isArray(data.open_facts) ? data.open_facts : [],
+    ...Array.isArray(data.answered_under) ? { answered_under: data.answered_under } : {},
+    ...typeof data.coverage === "string" ? { coverage: data.coverage } : {}
+  };
+}
+function resolutionBody(params) {
+  const { authority, artifact_id, artifact, key_certs, root_public_key_pem, action, inputs, context, ...flat } = params;
+  void authority;
+  void artifact_id;
+  void artifact;
+  void key_certs;
+  void root_public_key_pem;
+  const facts = inputs && typeof inputs === "object" ? inputs : flat;
+  return { context, ...action ? { action } : {}, ...facts };
+}
+async function canViaResolution(params, opts) {
+  const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
+  let res;
+  try {
+    res = await fetch(`${base}/api/v1/can`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "User-Agent": `nomos-node/${SDK_VERSION}`, ...callerHeaders(opts?.caller) },
+      body: JSON.stringify(resolutionBody(params)),
+      signal: opts?.signal
+    });
+  } catch (err) {
+    if (err?.name === "AbortError") throw new NomosNetworkError("Request aborted");
+    throw new NomosNetworkError(err?.message ?? "Network error");
+  }
+  const requestId = res.headers.get("x-request-id") ?? "";
+  const data = await res.json().catch(() => null);
+  if (!res.ok) mapHttpError(res.status, data, requestId);
+  return normalizeResolutionResult(data);
+}
 async function can(params, opts) {
   if (params.artifact !== void 0) {
     if (!params.key_certs || !params.root_public_key_pem) {
@@ -842,8 +913,11 @@ async function can(params, opts) {
   if (params.artifact_id) {
     throw new Error("can(): `artifact_id` requires an API key \u2014 use `client.can(...)` on an authenticated Nomos instance, not the free `can()` export.");
   }
+  if (!params.authority && params.context && typeof params.context === "object" && !Array.isArray(params.context)) {
+    return canViaResolution(params, opts);
+  }
   if (!params.authority || typeof params.authority !== "string") {
-    throw new Error("can(): `authority` (an Exchange artifact id or slug), `artifact_id` (via client.can()), or `artifact` (chain-of-trust) is required.");
+    throw new Error("can(): `authority` (an Exchange artifact id or slug), `artifact_id` (via client.can()), `artifact` (chain-of-trust), or `context` (resolution, NOMOS-SPEC-014) is required.");
   }
   const { facts, action } = splitFacts(params);
   return canViaExchange(params.authority, facts, action, opts);
@@ -857,8 +931,12 @@ async function canAuthenticated(http, params, opts) {
     return canViaChain(params.artifact, params.key_certs, params.root_public_key_pem, facts, action, opts);
   }
   if (params.artifact_id) return canViaArtifact(http, params.artifact_id, facts, action);
-  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts?.caller);
-  throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), or `artifact` (chain-of-trust) is required.");
+  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts);
+  if (params.context && typeof params.context === "object" && !Array.isArray(params.context)) {
+    const data = (await http.post("/api/v1/can", resolutionBody(params), { headers: callerHeaders(opts?.caller) })).data;
+    return normalizeResolutionResult(data);
+  }
+  throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), `artifact` (chain-of-trust), or `context` (resolution, NOMOS-SPEC-014) is required.");
 }
 var nomos = { can };
 

package/dist/index.d.cts

@@ -80,9 +80,77 @@ interface CanParams {
     /** The facts to evaluate. Either pass this explicitly, or spread the facts flat alongside
      *  `authority`/`action` — both shapes are accepted (explicit `inputs` wins if both given). */
     inputs?: Record<string, unknown>;
+    /** Resolution rail (NOMOS-SPEC-014 Draft): the properties that attach law to an act —
+     *  e.g. { jurisdiction: 'EU', sector: 'ai' }. With `context` and NO `authority`/`artifact_id`/
+     *  `artifact`, the server first resolves WHICH authorities govern this context (from its own
+     *  signed registrar chain — never from anything you present), asks every one of them, and
+     *  combines strictly. Returns a CanResolutionResult instead of a CanResult. Keyless. */
+    context?: Record<string, unknown>;
     /** Flat-facts convenience: any extra keys are treated as inputs when `inputs` is omitted. */
     [key: string]: unknown;
 }
+/** One governing authority the resolver found for a context (NOMOS-SPEC-014). */
+interface ResolvedAuthorityRef {
+    authority: string;
+    version: string | null;
+    registrar: string;
+    scope: string;
+}
+/** One resolved authority's answer inside a resolution-rail can() call. `verdict` is null with
+ *  `unavailable` set when the member could not be consulted — which holds the WHOLE combined
+ *  answer open (INSUFFICIENT_DATA), never acts as a permit. */
+interface CanResolutionMember {
+    authority: string;
+    verdict: string | null;
+    unavailable: string | null;
+    query_id?: string | null;
+    rule?: string | null;
+    reason?: string | null;
+    escalation_id?: string | null;
+    revoked?: boolean;
+    missing_facts?: string[];
+}
+/** The resolution rail's answer (NOMOS-SPEC-014): which authorities govern, each one's own
+ *  sealed answer, and the strict combination. `verdict` adds two values CanResult never has:
+ *  INSUFFICIENT_DATA (resolution or a member held open — named in `open_facts`/`resolution`)
+ *  and CONFLICT (two registrars assert exclusive precedence; a person settles it). */
+interface CanResolutionResult {
+    mode: 'resolution';
+    allowed: boolean;
+    verdict: 'AUTHORIZED' | 'DENIED' | 'ESCALATED' | 'INSUFFICIENT_DATA' | 'CONFLICT';
+    reason: string;
+    resolution: {
+        status: 'RESOLVED' | 'CONFLICT' | 'INCOMPLETE';
+        applicable?: ResolvedAuthorityRef[];
+        missing?: {
+            context_facts: string[];
+            unreachable_registrars: string[];
+            stale_closures: string[];
+            /** SPEC-014 0.2.0: a current closure names law the registrar's log no longer claims, or the reverse */
+            closure_disagreements?: Array<{
+                registrar: string;
+                authority: string;
+                reason: 'closed_but_not_claimed' | 'claimed_but_not_closed';
+            }>;
+            /** SPEC-014 0.2.0: registrars whose log copy is older than the relying party's bound */
+            stale_heads?: string[];
+        };
+        conflicts?: unknown[];
+        proof: unknown;
+    };
+    members: CanResolutionMember[];
+    deciding_authorities: string[];
+    escalations: Array<{
+        authority: string;
+        escalation_id: string | null;
+    }>;
+    open_facts: string[];
+    /** The laws this answer was computed under (the resolved set). */
+    answered_under?: string[];
+    /** What the answer covers, in words: the registrar lists only its own authorities, so other law
+     *  may also apply. An empty set is never AUTHORIZED. */
+    coverage?: string;
+}
 interface CanOptions {
     /** Override the API host (defaults to the public NOMOS Exchange). */
     baseUrl?: string;
@@ -92,6 +160,32 @@ interface CanOptions {
      *  `purpose: 'test'` queries are answered and sealed but kept out of the authority's public
      *  history and counts — set it from tests and CI. Exchange authorities only. */
     caller?: CanCaller;
+    /**
+     * Wait for a person when the answer is ESCALATED (client.can() with an API key, on a law you
+     * follow with "Use this law" on the Exchange). Your approvers get an email; when one approves this
+     * exact action and these facts, the approval is spent once and the result comes back with
+     * `allowed: true`. A rejection or the timeout returns `allowed: false`. `true` waits up to 10 minutes.
+     */
+    awaitApproval?: boolean | AwaitApprovalOptions;
+}
+interface AwaitApprovalOptions {
+    /** How long to wait for an answer, ms. Default 600000 (10 minutes). */
+    timeoutMs?: number;
+    /** How often to check, ms. Default 3000. */
+    pollMs?: number;
+    /** Called once when the request is made, with the page your approver answers on. */
+    onApproval?: (approval: {
+        id: number;
+        url: string;
+    }) => void;
+}
+/** A person's decision on an ESCALATED answer (see CanOptions.awaitApproval). */
+interface CanApproval {
+    id: number;
+    /** The page a signed-in approver answers on. */
+    url: string;
+    /** pending until answered; approved means spent for this call; timed_out means nobody answered in time. */
+    status: 'pending' | 'approved' | 'rejected' | 'timed_out' | 'not_usable';
 }
 interface CanCaller {
     /** A stable name for your agent, e.g. "acme-credit-agent". */
@@ -101,8 +195,11 @@ interface CanCaller {
     purpose?: 'production' | 'test';
 }
 interface CanResult {
-    /** True only for an AUTHORIZED verdict. DENIED and ESCALATED are both `false`. */
+    /** True for an AUTHORIZED verdict, or for an ESCALATED one a person approved for this exact call
+     *  (awaitApproval; the approval is then spent). Otherwise `false`. */
     allowed: boolean;
+    /** Present when an ESCALATED answer became an approval request (a law you follow, with a key). */
+    approval?: CanApproval;
     /** The authority's own verdict, verbatim, in ONE consistent vocabulary regardless of which
      *  rail answered it — the public Exchange or your own authenticated artifact. */
     verdict: CanVerdict;
@@ -167,6 +264,18 @@ interface CanResult {
      *  `"unchecked"` (neither — e.g. the pinned root, which nothing else can vouch for). Omitted
      *  (not a guess) on the Exchange/private-artifact rails, where this concept doesn't apply. */
     revocation_checked?: 'live' | 'staple' | 'unchecked';
+    /** Exchange rail: the platform's Ed25519 signature over what was decided, made when the query was
+     *  answered (docs/design-notes/signed-query-records.md). Check the full record offline with
+     *  `node verify-nomos.mjs <record.json> --pubkey <key.pem>` (record from `url`). Absent on records
+     *  answered by a deployment with no signing key. */
+    signature?: {
+        algorithm: 'Ed25519';
+        kid: string;
+        value: string;
+        statement: Record<string, unknown>;
+    };
+    /** Exchange rail: the evaluator version that decided this, as named in the signed statement. */
+    evaluator_version?: string;
 }
 interface ConservedStateInfo {
     artifact_id: string;
@@ -795,6 +904,12 @@ declare class Nomos {
     can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
 }
 
+declare function can(params: CanParams & {
+    context: Record<string, unknown>;
+    authority?: undefined;
+    artifact_id?: undefined;
+    artifact?: undefined;
+}, opts?: CanOptions): Promise<CanResolutionResult>;
 declare function can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
 /**
  * Ready-to-use, keyless entry point matching the canonical `nomos.can(...)` form.
@@ -1635,4 +1750,4 @@ declare function approver(o: ApproverOptions): {
     pending: Map<string, Pending>;
 };
 
-export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type BindingProposal, type BindingSuggestion, type BuildActOptions, type CanCaller, type CanOptions, type CanParams, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type FactBinding, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PolicyField, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type ToolBindings, type ToolDescription, type UnresolvedFact, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, applyToolBindings, approver, buildAct, can, certificateRegistry, certify, describeSuggestion, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, parseToolBindings, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, suggestToolBindings, verifyChain, verifyEnrolmentToken, witness };
+export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type AwaitApprovalOptions, type BindingProposal, type BindingSuggestion, type BuildActOptions, type CanApproval, type CanCaller, type CanOptions, type CanParams, type CanResolutionMember, type CanResolutionResult, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type FactBinding, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PolicyField, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type ResolvedAuthorityRef, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type ToolBindings, type ToolDescription, type UnresolvedFact, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, applyToolBindings, approver, buildAct, can, certificateRegistry, certify, describeSuggestion, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, parseToolBindings, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, suggestToolBindings, verifyChain, verifyEnrolmentToken, witness };

package/dist/index.d.ts

@@ -80,9 +80,77 @@ interface CanParams {
     /** The facts to evaluate. Either pass this explicitly, or spread the facts flat alongside
      *  `authority`/`action` — both shapes are accepted (explicit `inputs` wins if both given). */
     inputs?: Record<string, unknown>;
+    /** Resolution rail (NOMOS-SPEC-014 Draft): the properties that attach law to an act —
+     *  e.g. { jurisdiction: 'EU', sector: 'ai' }. With `context` and NO `authority`/`artifact_id`/
+     *  `artifact`, the server first resolves WHICH authorities govern this context (from its own
+     *  signed registrar chain — never from anything you present), asks every one of them, and
+     *  combines strictly. Returns a CanResolutionResult instead of a CanResult. Keyless. */
+    context?: Record<string, unknown>;
     /** Flat-facts convenience: any extra keys are treated as inputs when `inputs` is omitted. */
     [key: string]: unknown;
 }
+/** One governing authority the resolver found for a context (NOMOS-SPEC-014). */
+interface ResolvedAuthorityRef {
+    authority: string;
+    version: string | null;
+    registrar: string;
+    scope: string;
+}
+/** One resolved authority's answer inside a resolution-rail can() call. `verdict` is null with
+ *  `unavailable` set when the member could not be consulted — which holds the WHOLE combined
+ *  answer open (INSUFFICIENT_DATA), never acts as a permit. */
+interface CanResolutionMember {
+    authority: string;
+    verdict: string | null;
+    unavailable: string | null;
+    query_id?: string | null;
+    rule?: string | null;
+    reason?: string | null;
+    escalation_id?: string | null;
+    revoked?: boolean;
+    missing_facts?: string[];
+}
+/** The resolution rail's answer (NOMOS-SPEC-014): which authorities govern, each one's own
+ *  sealed answer, and the strict combination. `verdict` adds two values CanResult never has:
+ *  INSUFFICIENT_DATA (resolution or a member held open — named in `open_facts`/`resolution`)
+ *  and CONFLICT (two registrars assert exclusive precedence; a person settles it). */
+interface CanResolutionResult {
+    mode: 'resolution';
+    allowed: boolean;
+    verdict: 'AUTHORIZED' | 'DENIED' | 'ESCALATED' | 'INSUFFICIENT_DATA' | 'CONFLICT';
+    reason: string;
+    resolution: {
+        status: 'RESOLVED' | 'CONFLICT' | 'INCOMPLETE';
+        applicable?: ResolvedAuthorityRef[];
+        missing?: {
+            context_facts: string[];
+            unreachable_registrars: string[];
+            stale_closures: string[];
+            /** SPEC-014 0.2.0: a current closure names law the registrar's log no longer claims, or the reverse */
+            closure_disagreements?: Array<{
+                registrar: string;
+                authority: string;
+                reason: 'closed_but_not_claimed' | 'claimed_but_not_closed';
+            }>;
+            /** SPEC-014 0.2.0: registrars whose log copy is older than the relying party's bound */
+            stale_heads?: string[];
+        };
+        conflicts?: unknown[];
+        proof: unknown;
+    };
+    members: CanResolutionMember[];
+    deciding_authorities: string[];
+    escalations: Array<{
+        authority: string;
+        escalation_id: string | null;
+    }>;
+    open_facts: string[];
+    /** The laws this answer was computed under (the resolved set). */
+    answered_under?: string[];
+    /** What the answer covers, in words: the registrar lists only its own authorities, so other law
+     *  may also apply. An empty set is never AUTHORIZED. */
+    coverage?: string;
+}
 interface CanOptions {
     /** Override the API host (defaults to the public NOMOS Exchange). */
     baseUrl?: string;
@@ -92,6 +160,32 @@ interface CanOptions {
      *  `purpose: 'test'` queries are answered and sealed but kept out of the authority's public
      *  history and counts — set it from tests and CI. Exchange authorities only. */
     caller?: CanCaller;
+    /**
+     * Wait for a person when the answer is ESCALATED (client.can() with an API key, on a law you
+     * follow with "Use this law" on the Exchange). Your approvers get an email; when one approves this
+     * exact action and these facts, the approval is spent once and the result comes back with
+     * `allowed: true`. A rejection or the timeout returns `allowed: false`. `true` waits up to 10 minutes.
+     */
+    awaitApproval?: boolean | AwaitApprovalOptions;
+}
+interface AwaitApprovalOptions {
+    /** How long to wait for an answer, ms. Default 600000 (10 minutes). */
+    timeoutMs?: number;
+    /** How often to check, ms. Default 3000. */
+    pollMs?: number;
+    /** Called once when the request is made, with the page your approver answers on. */
+    onApproval?: (approval: {
+        id: number;
+        url: string;
+    }) => void;
+}
+/** A person's decision on an ESCALATED answer (see CanOptions.awaitApproval). */
+interface CanApproval {
+    id: number;
+    /** The page a signed-in approver answers on. */
+    url: string;
+    /** pending until answered; approved means spent for this call; timed_out means nobody answered in time. */
+    status: 'pending' | 'approved' | 'rejected' | 'timed_out' | 'not_usable';
 }
 interface CanCaller {
     /** A stable name for your agent, e.g. "acme-credit-agent". */
@@ -101,8 +195,11 @@ interface CanCaller {
     purpose?: 'production' | 'test';
 }
 interface CanResult {
-    /** True only for an AUTHORIZED verdict. DENIED and ESCALATED are both `false`. */
+    /** True for an AUTHORIZED verdict, or for an ESCALATED one a person approved for this exact call
+     *  (awaitApproval; the approval is then spent). Otherwise `false`. */
     allowed: boolean;
+    /** Present when an ESCALATED answer became an approval request (a law you follow, with a key). */
+    approval?: CanApproval;
     /** The authority's own verdict, verbatim, in ONE consistent vocabulary regardless of which
      *  rail answered it — the public Exchange or your own authenticated artifact. */
     verdict: CanVerdict;
@@ -167,6 +264,18 @@ interface CanResult {
      *  `"unchecked"` (neither — e.g. the pinned root, which nothing else can vouch for). Omitted
      *  (not a guess) on the Exchange/private-artifact rails, where this concept doesn't apply. */
     revocation_checked?: 'live' | 'staple' | 'unchecked';
+    /** Exchange rail: the platform's Ed25519 signature over what was decided, made when the query was
+     *  answered (docs/design-notes/signed-query-records.md). Check the full record offline with
+     *  `node verify-nomos.mjs <record.json> --pubkey <key.pem>` (record from `url`). Absent on records
+     *  answered by a deployment with no signing key. */
+    signature?: {
+        algorithm: 'Ed25519';
+        kid: string;
+        value: string;
+        statement: Record<string, unknown>;
+    };
+    /** Exchange rail: the evaluator version that decided this, as named in the signed statement. */
+    evaluator_version?: string;
 }
 interface ConservedStateInfo {
     artifact_id: string;
@@ -795,6 +904,12 @@ declare class Nomos {
     can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
 }
 
+declare function can(params: CanParams & {
+    context: Record<string, unknown>;
+    authority?: undefined;
+    artifact_id?: undefined;
+    artifact?: undefined;
+}, opts?: CanOptions): Promise<CanResolutionResult>;
 declare function can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
 /**
  * Ready-to-use, keyless entry point matching the canonical `nomos.can(...)` form.
@@ -1635,4 +1750,4 @@ declare function approver(o: ApproverOptions): {
     pending: Map<string, Pending>;
 };
 
-export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type BindingProposal, type BindingSuggestion, type BuildActOptions, type CanCaller, type CanOptions, type CanParams, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type FactBinding, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PolicyField, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type ToolBindings, type ToolDescription, type UnresolvedFact, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, applyToolBindings, approver, buildAct, can, certificateRegistry, certify, describeSuggestion, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, parseToolBindings, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, suggestToolBindings, verifyChain, verifyEnrolmentToken, witness };
+export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type AwaitApprovalOptions, type BindingProposal, type BindingSuggestion, type BuildActOptions, type CanApproval, type CanCaller, type CanOptions, type CanParams, type CanResolutionMember, type CanResolutionResult, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type FactBinding, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PolicyField, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type ResolvedAuthorityRef, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type ToolBindings, type ToolDescription, type UnresolvedFact, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, applyToolBindings, approver, buildAct, can, certificateRegistry, certify, describeSuggestion, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, parseToolBindings, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, suggestToolBindings, verifyChain, verifyEnrolmentToken, witness };

package/dist/index.js

@@ -107,7 +107,7 @@ function isRetryable(status) {
 }
 
 // src/http-client.ts
-var SDK_VERSION = "2.3.2";
+var SDK_VERSION = "2.6.0";
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -637,7 +637,9 @@ function normalizeAuthorityQueryResult(data, authority) {
     // NOMOS-SPEC-006 — present only when the issuer has actually revoked this exact sealed
     // version; omitted (not false) when revocation doesn't structurally apply here, so "checked
     // and clean" and "couldn't check" never look the same to a caller.
-    ...data.revoked === true ? { revoked: true, revocation_reason: data.revocation_reason } : {}
+    ...data.revoked === true ? { revoked: true, revocation_reason: data.revocation_reason } : {},
+    ...data.signature ? { signature: data.signature } : {},
+    ...data.evaluator_version ? { evaluator_version: data.evaluator_version } : {}
   };
 }
 function callerHeaders(c) {
@@ -667,9 +669,34 @@ async function canViaExchange(authority, facts, action, opts) {
   if (!res.ok) mapHttpError(res.status, data, requestId);
   return normalizeAuthorityQueryResult(data, authority);
 }
-async function canViaExchangeAuthenticated(http, authority, facts, action, caller) {
-  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts }, { headers: callerHeaders(caller) });
-  return normalizeAuthorityQueryResult(data, authority);
+async function canViaExchangeAuthenticated(http, authority, facts, action, opts) {
+  const ask = async () => (await http.post("/api/v1/can", { artifact: authority, action, ...facts }, { headers: callerHeaders(opts?.caller) })).data;
+  const data = await ask();
+  const result = normalizeAuthorityQueryResult(data, authority);
+  const approval = data?.approval;
+  if (!approval) return result;
+  result.approval = { id: approval.id, url: approval.url, status: approval.status };
+  if (!opts?.awaitApproval || result.verdict !== "ESCALATED") return result;
+  return awaitApproval(http, result, typeof opts.awaitApproval === "object" ? opts.awaitApproval : {});
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function awaitApproval(http, result, o) {
+  const a = result.approval;
+  o.onApproval?.({ id: a.id, url: a.url });
+  const deadline = Date.now() + (o.timeoutMs ?? 6e5);
+  let status = a.status;
+  while (status === "pending" && Date.now() < deadline) {
+    await sleep2(Math.max(500, o.pollMs ?? 3e3));
+    status = (await http.get(`/api/v1/approvals/${a.id}`)).data?.status ?? "pending";
+  }
+  if (status === "pending") return { ...result, approval: { ...a, status: "timed_out" } };
+  if (status !== "approved") return { ...result, approval: { ...a, status: "rejected" } };
+  try {
+    await http.post(`/api/v1/approvals/${a.id}/consume`, {});
+  } catch {
+    return { ...result, approval: { ...a, status: "not_usable" } };
+  }
+  return { ...result, allowed: true, approval: { ...a, status: "approved" } };
 }
 async function canViaArtifact(http, artifactId, facts, action) {
   const isPublic = artifactId.startsWith("pub_");
@@ -747,6 +774,50 @@ async function canViaChain(artifact, keyCerts, rootPublicKeyPem, facts, action,
   if (data?.decision === "MALFORMED") throw new NomosValidationError(message, data, requestId);
   mapHttpError(res.status, data, requestId);
 }
+function normalizeResolutionResult(data) {
+  return {
+    mode: "resolution",
+    allowed: data.verdict === "AUTHORIZED",
+    verdict: data.verdict,
+    reason: data.reason ?? "",
+    resolution: data.resolution ?? { status: "INCOMPLETE", proof: null },
+    members: Array.isArray(data.members) ? data.members : [],
+    deciding_authorities: Array.isArray(data.deciding_authorities) ? data.deciding_authorities : [],
+    escalations: Array.isArray(data.escalations) ? data.escalations : [],
+    open_facts: Array.isArray(data.open_facts) ? data.open_facts : [],
+    ...Array.isArray(data.answered_under) ? { answered_under: data.answered_under } : {},
+    ...typeof data.coverage === "string" ? { coverage: data.coverage } : {}
+  };
+}
+function resolutionBody(params) {
+  const { authority, artifact_id, artifact, key_certs, root_public_key_pem, action, inputs, context, ...flat } = params;
+  void authority;
+  void artifact_id;
+  void artifact;
+  void key_certs;
+  void root_public_key_pem;
+  const facts = inputs && typeof inputs === "object" ? inputs : flat;
+  return { context, ...action ? { action } : {}, ...facts };
+}
+async function canViaResolution(params, opts) {
+  const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
+  let res;
+  try {
+    res = await fetch(`${base}/api/v1/can`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "User-Agent": `nomos-node/${SDK_VERSION}`, ...callerHeaders(opts?.caller) },
+      body: JSON.stringify(resolutionBody(params)),
+      signal: opts?.signal
+    });
+  } catch (err) {
+    if (err?.name === "AbortError") throw new NomosNetworkError("Request aborted");
+    throw new NomosNetworkError(err?.message ?? "Network error");
+  }
+  const requestId = res.headers.get("x-request-id") ?? "";
+  const data = await res.json().catch(() => null);
+  if (!res.ok) mapHttpError(res.status, data, requestId);
+  return normalizeResolutionResult(data);
+}
 async function can(params, opts) {
   if (params.artifact !== void 0) {
     if (!params.key_certs || !params.root_public_key_pem) {
@@ -758,8 +829,11 @@ async function can(params, opts) {
   if (params.artifact_id) {
     throw new Error("can(): `artifact_id` requires an API key \u2014 use `client.can(...)` on an authenticated Nomos instance, not the free `can()` export.");
   }
+  if (!params.authority && params.context && typeof params.context === "object" && !Array.isArray(params.context)) {
+    return canViaResolution(params, opts);
+  }
   if (!params.authority || typeof params.authority !== "string") {
-    throw new Error("can(): `authority` (an Exchange artifact id or slug), `artifact_id` (via client.can()), or `artifact` (chain-of-trust) is required.");
+    throw new Error("can(): `authority` (an Exchange artifact id or slug), `artifact_id` (via client.can()), `artifact` (chain-of-trust), or `context` (resolution, NOMOS-SPEC-014) is required.");
   }
   const { facts, action } = splitFacts(params);
   return canViaExchange(params.authority, facts, action, opts);
@@ -773,8 +847,12 @@ async function canAuthenticated(http, params, opts) {
     return canViaChain(params.artifact, params.key_certs, params.root_public_key_pem, facts, action, opts);
   }
   if (params.artifact_id) return canViaArtifact(http, params.artifact_id, facts, action);
-  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts?.caller);
-  throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), or `artifact` (chain-of-trust) is required.");
+  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts);
+  if (params.context && typeof params.context === "object" && !Array.isArray(params.context)) {
+    const data = (await http.post("/api/v1/can", resolutionBody(params), { headers: callerHeaders(opts?.caller) })).data;
+    return normalizeResolutionResult(data);
+  }
+  throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), `artifact` (chain-of-trust), or `context` (resolution, NOMOS-SPEC-014) is required.");
 }
 var nomos = { can };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomosprotocol/sdk",
-  "version": "2.3.2",
+  "version": "2.6.0",
   "description": "NOMOS for TypeScript: accept() for the system that makes a change, act() for the agent that asks, the issuer, witness and approver roles, and the Exchange client. Verification is local (@nomosprotocol/verify).",
   "publishConfig": {
     "access": "public"
@@ -32,7 +32,9 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "check:verify": "npm --prefix ../packages/verify run build && node scripts/check-bundled-verify.mjs",
+    "prepublishOnly": "npm run check:verify && npm run build"
   },
   "tsup": {
     "entry": [