@nomosprotocol/sdk 2.3.1 → 2.5.0

package/README.md

@@ -161,10 +161,44 @@ const verdict = await nomos.can({
 });
 ```
 
+Name your agent so the transcript records who asked, and mark test traffic so it stays out of the authority's public history and counts:
+
+```ts
+const verdict = await nomos.can(
+  { authority: "eu-ai-act", ai_categorises_biometric_data_for_sensitive_attributes: true },
+  { caller: { agent_id: "acme-hiring-agent", purpose: process.env.CI ? "test" : "production" } },
+);
+```
+
+The name is declared, not verified, and is shown as such. Don't know which authority applies? `GET /api/exchange/find?q=<what you're about to do>`, or the MCP tool `find_authority`.
+
 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.
 
+### 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: "data-protection-law-difc-law-no-5-of-2020", days_since_access_request: 45 },
+  { 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.
+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.1";
+var SDK_VERSION = "2.5.0";
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -215,6 +215,7 @@ var HttpClient = class {
       "User-Agent": `nomos-node/${SDK_VERSION}`,
       "NOMOS-SDK-Version": SDK_VERSION
     };
+    if (reqOpts?.headers) Object.assign(headers, reqOpts.headers);
     if (reqOpts?.idempotencyKey) {
       headers["Idempotency-Key"] = reqOpts.idempotencyKey;
     }
@@ -720,9 +721,18 @@ 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) {
+  const h = {};
+  if (c?.agent_id) h["X-Nomos-Agent"] = c.agent_id;
+  if (c?.acts_for) h["X-Nomos-Acts-For"] = c.acts_for;
+  if (c?.purpose) h["X-Nomos-Purpose"] = c.purpose;
+  return h;
+}
 async function canViaExchange(authority, facts, action, opts) {
   const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
   const url = `${base}/api/v1/can`;
@@ -730,7 +740,7 @@ async function canViaExchange(authority, facts, action, opts) {
   try {
     res = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": `nomos-node/${SDK_VERSION}`, ...callerHeaders(opts?.caller) },
       body: JSON.stringify({ artifact: authority, action, ...facts }),
       signal: opts?.signal
     });
@@ -743,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) {
-  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts });
-  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_");
@@ -841,7 +876,6 @@ async function can(params, opts) {
   return canViaExchange(params.authority, facts, action, opts);
 }
 async function canAuthenticated(http, params, opts) {
-  void opts;
   const { facts, action } = splitFacts(params);
   if (params.artifact !== void 0) {
     if (!params.key_certs || !params.root_public_key_pem) {
@@ -850,7 +884,7 @@ 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);
+  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts);
   throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), or `artifact` (chain-of-trust) is required.");
 }
 var nomos = { can };
@@ -5051,9 +5085,14 @@ var TIE_ORDERS = {
 function evaluate(artifact, facts) {
   const logic = artifact.logic;
   const res = logic.resolution ?? {};
-  const decisions = logic.decisions;
-  if (!Array.isArray(decisions))
+  if (!Array.isArray(logic.decisions))
     throw new Error("logic.decisions missing");
+  const declared = new Set(Object.keys(artifact.execution?.actions ?? {}));
+  const isObligation = (d) => {
+    const t = d?.then?.[0];
+    return t?.type === "emit" || t?.type === "action" && declared.has(t?.action_name);
+  };
+  const decisions = logic.decisions.filter((d) => !isObligation(d));
   const order = TIE_ORDERS[res.tie_breaker ?? "deny_wins"];
   if (!order)
     throw new Error("unknown tie_breaker");

package/dist/index.d.cts

@@ -88,10 +88,50 @@ interface CanOptions {
     baseUrl?: string;
     /** AbortSignal to cancel the request. */
     signal?: AbortSignal;
+    /** Who is asking, recorded on the transcript (sent as X-Nomos-Agent / -Acts-For / -Purpose).
+     *  `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". */
+    agent_id?: string;
+    /** The organisation it acts for. Ignored when the request carries an API key (the key's account is used). */
+    acts_for?: string;
+    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;
@@ -156,6 +196,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;
@@ -411,6 +463,8 @@ interface RequestOptions {
     idempotencyKey?: string;
     /** Per-request API key — useful for multi-tenant platforms */
     apiKey?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
 }
 interface NomosRawResponse {
     /** x-request-id header value — include in support tickets */
@@ -1622,4 +1676,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 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 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 };

package/dist/index.d.ts

@@ -88,10 +88,50 @@ interface CanOptions {
     baseUrl?: string;
     /** AbortSignal to cancel the request. */
     signal?: AbortSignal;
+    /** Who is asking, recorded on the transcript (sent as X-Nomos-Agent / -Acts-For / -Purpose).
+     *  `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". */
+    agent_id?: string;
+    /** The organisation it acts for. Ignored when the request carries an API key (the key's account is used). */
+    acts_for?: string;
+    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;
@@ -156,6 +196,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;
@@ -411,6 +463,8 @@ interface RequestOptions {
     idempotencyKey?: string;
     /** Per-request API key — useful for multi-tenant platforms */
     apiKey?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
 }
 interface NomosRawResponse {
     /** x-request-id header value — include in support tickets */
@@ -1622,4 +1676,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 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 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 };

package/dist/index.js

@@ -107,7 +107,7 @@ function isRetryable(status) {
 }
 
 // src/http-client.ts
-var SDK_VERSION = "2.3.1";
+var SDK_VERSION = "2.5.0";
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -131,6 +131,7 @@ var HttpClient = class {
       "User-Agent": `nomos-node/${SDK_VERSION}`,
       "NOMOS-SDK-Version": SDK_VERSION
     };
+    if (reqOpts?.headers) Object.assign(headers, reqOpts.headers);
     if (reqOpts?.idempotencyKey) {
       headers["Idempotency-Key"] = reqOpts.idempotencyKey;
     }
@@ -636,9 +637,18 @@ 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) {
+  const h = {};
+  if (c?.agent_id) h["X-Nomos-Agent"] = c.agent_id;
+  if (c?.acts_for) h["X-Nomos-Acts-For"] = c.acts_for;
+  if (c?.purpose) h["X-Nomos-Purpose"] = c.purpose;
+  return h;
+}
 async function canViaExchange(authority, facts, action, opts) {
   const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
   const url = `${base}/api/v1/can`;
@@ -646,7 +656,7 @@ async function canViaExchange(authority, facts, action, opts) {
   try {
     res = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": `nomos-node/${SDK_VERSION}`, ...callerHeaders(opts?.caller) },
       body: JSON.stringify({ artifact: authority, action, ...facts }),
       signal: opts?.signal
     });
@@ -659,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) {
-  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts });
-  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_");
@@ -757,7 +792,6 @@ async function can(params, opts) {
   return canViaExchange(params.authority, facts, action, opts);
 }
 async function canAuthenticated(http, params, opts) {
-  void opts;
   const { facts, action } = splitFacts(params);
   if (params.artifact !== void 0) {
     if (!params.key_certs || !params.root_public_key_pem) {
@@ -766,7 +800,7 @@ 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);
+  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts);
   throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), or `artifact` (chain-of-trust) is required.");
 }
 var nomos = { can };
@@ -4967,9 +5001,14 @@ var TIE_ORDERS = {
 function evaluate(artifact, facts) {
   const logic = artifact.logic;
   const res = logic.resolution ?? {};
-  const decisions = logic.decisions;
-  if (!Array.isArray(decisions))
+  if (!Array.isArray(logic.decisions))
     throw new Error("logic.decisions missing");
+  const declared = new Set(Object.keys(artifact.execution?.actions ?? {}));
+  const isObligation = (d) => {
+    const t = d?.then?.[0];
+    return t?.type === "emit" || t?.type === "action" && declared.has(t?.action_name);
+  };
+  const decisions = logic.decisions.filter((d) => !isObligation(d));
   const order = TIE_ORDERS[res.tie_breaker ?? "deny_wins"];
   if (!order)
     throw new Error("unknown tie_breaker");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomosprotocol/sdk",
-  "version": "2.3.1",
+  "version": "2.5.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": [
@@ -64,6 +66,13 @@
   ],
   "author": "NOMOS",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nomos-spec/spec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nomos-spec/spec/issues"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -74,6 +83,6 @@
   "dependencies": {
     "@noble/curves": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@nomosprotocol/verify": "^1.2.0"
+    "@nomosprotocol/verify": "^1.3.0"
   }
 }