@nomosprotocol/sdk 1.2.0 → 1.3.0

package/README.md

@@ -14,7 +14,7 @@ Every public authority on the [NOMOS Exchange](https://www.nomosprotocol.com/exc
 import { nomos } from "@nomosprotocol/sdk";
 
 const verdict = await nomos.can({
-  authority: "eu-ai-act-full-regulation-2024-1689",
+  authority: "eu-ai-act.nomos",
   ai_categorises_biometric_data_for_sensitive_attributes: true,
 });
 
@@ -29,7 +29,7 @@ Facts can be spread flat alongside `authority` (as above), or passed explicitly:
 
 ```ts
 const verdict = await nomos.can({
-  authority: "eu-ai-act-full-regulation-2024-1689",
+  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
 });
@@ -54,6 +54,26 @@ const verdict = await nomos.can({
 
 Every call mints a permanent, cryptographically sealed transcript — open `query_id` any time at `nomosprotocol.com/queries/<query_id>` to replay exactly what was asked and answered, bound to the exact authority version that responded.
 
+### Error handling
+
+A failed call (unknown authority, network issue, upstream error) rejects with a typed `NomosError` subclass — never a bare `Error` — so you can branch on `instanceof` or the stable `.code` string:
+
+```ts
+import { nomos, NomosNotFoundError, NomosNetworkError } from "@nomosprotocol/sdk";
+
+try {
+  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'
+  } else if (err instanceof NomosNetworkError) {
+    // request timed out or the network failed
+  } else {
+    throw err;
+  }
+}
+```
+
 ### Options
 
 ```ts

package/dist/index.cjs

@@ -25,13 +25,16 @@ __export(index_exports, {
   NomosAuthenticationError: () => NomosAuthenticationError,
   NomosAuthorizationError: () => NomosAuthorizationError,
   NomosError: () => NomosError,
+  NomosIssuerNotTrustedError: () => NomosIssuerNotTrustedError,
   NomosNetworkError: () => NomosNetworkError,
   NomosNotFoundError: () => NomosNotFoundError,
+  NomosPaymentRequiredError: () => NomosPaymentRequiredError,
   NomosRateLimitError: () => NomosRateLimitError,
   NomosValidationError: () => NomosValidationError,
   NomosWebhookSignatureError: () => NomosWebhookSignatureError,
   can: () => can,
-  nomos: () => nomos
+  nomos: () => nomos,
+  verifyChain: () => verifyChain
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -42,8 +45,10 @@ __export(errors_exports, {
   NomosAuthenticationError: () => NomosAuthenticationError,
   NomosAuthorizationError: () => NomosAuthorizationError,
   NomosError: () => NomosError,
+  NomosIssuerNotTrustedError: () => NomosIssuerNotTrustedError,
   NomosNetworkError: () => NomosNetworkError,
   NomosNotFoundError: () => NomosNotFoundError,
+  NomosPaymentRequiredError: () => NomosPaymentRequiredError,
   NomosRateLimitError: () => NomosRateLimitError,
   NomosValidationError: () => NomosValidationError,
   NomosWebhookSignatureError: () => NomosWebhookSignatureError
@@ -107,6 +112,21 @@ var NomosWebhookSignatureError = class extends NomosError {
     this.name = "NomosWebhookSignatureError";
   }
 };
+var NomosPaymentRequiredError = class extends NomosError {
+  constructor(message, priceUsd, purchaseUrl, requestId) {
+    super(message, "payment_required", 402, requestId);
+    this.name = "NomosPaymentRequiredError";
+    this.priceUsd = priceUsd;
+    this.purchaseUrl = purchaseUrl;
+  }
+};
+var NomosIssuerNotTrustedError = class extends NomosError {
+  constructor(message, reason, requestId) {
+    super(message, "issuer_not_trusted", 403, requestId);
+    this.name = "NomosIssuerNotTrustedError";
+    this.reason = reason;
+  }
+};
 
 // src/util.ts
 async function sleep(ms) {
@@ -526,6 +546,192 @@ var Webhooks = class {
   }
 };
 
+// src/can.ts
+var CHAIN_PROTOCOL_VERSION = "1";
+var DEFAULT_EXCHANGE_BASE = "https://www.nomosprotocol.com";
+function splitFacts(params) {
+  const { authority, artifact_id, action, inputs, ...flat } = params;
+  void authority;
+  void artifact_id;
+  const facts = inputs && typeof inputs === "object" ? inputs : flat;
+  return { facts, action };
+}
+function mapHttpError(status, data, requestId) {
+  const message = data?.error ?? data?.message ?? `NOMOS query failed (HTTP ${status})`;
+  if (data?.code === "PURCHASE_REQUIRED") {
+    throw new NomosPaymentRequiredError(message, data.price_usd ?? 0, data.purchase_url ?? "", requestId);
+  }
+  switch (status) {
+    case 401:
+      throw new NomosAuthenticationError(message, requestId);
+    case 403:
+      throw new NomosAuthorizationError(message, requestId);
+    case 404:
+      throw new NomosNotFoundError(message, requestId);
+    case 422:
+    case 400:
+      throw new NomosValidationError(message, data?.details, requestId);
+    case 429:
+      throw new NomosRateLimitError(message, void 0, requestId);
+    default:
+      throw new NomosAPIError(message, status, requestId);
+  }
+}
+function normalizeAuthorityQueryResult(data, authority) {
+  return {
+    allowed: data.verdict === "AUTHORIZED",
+    verdict: data.verdict,
+    reason: data.verdict_description,
+    rule: data.matched_rule_id ?? null,
+    query_id: data.query_id,
+    url: data.url,
+    authority: {
+      id: data.artifact?.id ?? authority,
+      title: data.artifact?.title ?? "",
+      standing: data.artifact?.standing ?? "",
+      ...data.artifact?.attestation ? { attestation: data.artifact.attestation } : {}
+    },
+    ...data.artifact?.version ? { version: data.artifact.version } : {},
+    missing_inputs: data.missing_inputs ?? [],
+    ...typeof data.max_age === "number" ? { max_age: data.max_age } : {},
+    // authority-query.ts already returns { kind, rule_id, rule_name } — the public-safe shape
+    // CanResult uses directly.
+    ...Array.isArray(data.obligations) && data.obligations.length > 0 ? { obligations: data.obligations } : {},
+    // 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 } : {}
+  };
+}
+async function canViaExchange(authority, facts, action, opts) {
+  const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
+  const url = `${base}/api/v1/can`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ artifact: authority, action, ...facts }),
+      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 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 canViaArtifact(http, artifactId, facts, action) {
+  const isPublic = artifactId.startsWith("pub_");
+  const path = isPublic ? "/api/v1/verify" : "/api/v1/verify-decision";
+  const body = isPublic ? { artifact_id: artifactId, decision: action ?? "evaluate", inputs: facts } : { artifact_id: artifactId, decision: action ?? "evaluate", inputs: facts, caller: { correlation_id: globalThis.crypto.randomUUID() } };
+  const { data: raw } = await http.post(path, body);
+  const verdict = raw.verdict === "approved" ? "AUTHORIZED" : raw.verdict === "rejected" ? "DENIED" : raw.outcome === "auto_approved" ? "AUTHORIZED" : raw.outcome === "auto_rejected" ? "DENIED" : "ESCALATED";
+  return {
+    allowed: raw.allowed ?? verdict === "AUTHORIZED",
+    verdict,
+    reason: raw.verdict_description ?? "",
+    rule: raw.rule?.id ?? null,
+    authority: {
+      id: raw.artifact_id ?? artifactId,
+      title: raw.artifact_name ?? "",
+      standing: raw.confidence?.tier ?? ""
+    },
+    ...raw.artifact_version ? { version: raw.artifact_version } : {},
+    missing_inputs: raw.incomplete_inputs?.fields ?? [],
+    ...raw.audit ? { audit: { hash: raw.audit.hash ?? raw.audit_hash ?? "", timestamp: raw.audit.timestamp ?? raw.ts ?? (/* @__PURE__ */ new Date()).toISOString() } } : {},
+    // This rail's obligations are RuleEffect objects (authority-types.ts) — a richer, INTERNAL
+    // shape ({ effect_type, value, provenance: { rule_id, rule_name } }), NOT the same shape the
+    // Exchange rail already returns ({ kind, rule_id, rule_name }). Mapped explicitly here rather
+    // than passed through raw — the two rails' server-side representations genuinely differ, and
+    // assuming they matched would have been the actual bug.
+    ...Array.isArray(raw.obligations) && raw.obligations.length > 0 ? { obligations: raw.obligations.map((o) => ({
+      kind: o.kind ?? o.value ?? "obligation",
+      rule_id: o.rule_id ?? o.provenance?.rule_id ?? null,
+      rule_name: o.rule_name ?? o.provenance?.rule_name ?? null,
+      ...o.reason ? { reason: o.reason } : {}
+    })) } : {}
+  };
+}
+async function canViaChain(artifact, keyCerts, rootPublicKeyPem, facts, action, opts) {
+  const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
+  const url = `${base}/api/v1/chain-of-trust/verify`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ version: CHAIN_PROTOCOL_VERSION, artifact, key_certs: keyCerts, root_public_key_pem: rootPublicKeyPem, facts, action }),
+      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 (data?.decision === "AUTHORIZED" || data?.decision === "DENIED" || data?.decision === "ESCALATED") {
+    return {
+      allowed: data.decision === "AUTHORIZED",
+      verdict: data.decision,
+      reason: data.reason ?? "",
+      rule: data.rule ?? null,
+      authority: { id: "presented-artifact", title: "", standing: "" },
+      // Read directly off the artifact the caller already has — no server round-trip needed for
+      // data the caller is already holding.
+      ...artifact?.meta?.version ? { version: artifact.meta.version } : {},
+      missing_inputs: data.missing_inputs ?? [],
+      ...Array.isArray(data.obligations) && data.obligations.length > 0 ? { obligations: data.obligations } : {}
+      // Deliberately no query_id/url/audit — this evaluation is stateless by design (the whole
+      // point is answering without NOMOS needing to have seen this artifact before); there is no
+      // permanent transcript to point to, and faking one would misrepresent what just happened.
+    };
+  }
+  const message = data?.detail ?? `Chain verification failed (HTTP ${res.status})`;
+  if (data?.decision === "ISSUER_NOT_RECOGNIZED" || data?.decision === "KEY_REVOKED" || data?.decision === "SEAL_INVALID" || data?.decision === "ALLOWED") {
+    throw new NomosIssuerNotTrustedError(message, data.decision, requestId);
+  }
+  if (data?.decision === "MALFORMED") throw new NomosValidationError(message, data, requestId);
+  mapHttpError(res.status, data, requestId);
+}
+async function can(params, opts) {
+  if (params.artifact !== void 0) {
+    if (!params.key_certs || !params.root_public_key_pem) {
+      throw new Error("can(): `artifact` requires `key_certs` and `root_public_key_pem` alongside it.");
+    }
+    const { facts: facts2, action: action2 } = splitFacts(params);
+    return canViaChain(params.artifact, params.key_certs, params.root_public_key_pem, facts2, action2, 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 || 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.");
+  }
+  const { facts, action } = splitFacts(params);
+  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) {
+      throw new Error("can(): `artifact` requires `key_certs` and `root_public_key_pem` alongside it.");
+    }
+    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);
+  throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), or `artifact` (chain-of-trust) is required.");
+}
+var nomos = { can };
+
 // src/nomos.ts
 var DEFAULT_BASE_URL = "https://nomos.ai";
 var DEFAULT_MAX_RETRIES = 3;
@@ -541,55 +747,69 @@ var Nomos = class {
       );
     }
     this.mode = apiKey.startsWith("nms_test_") ? "test" : "live";
-    const http = new HttpClient({
+    this.http = new HttpClient({
       apiKey,
       baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
       maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
       timeout: config.timeout ?? DEFAULT_TIMEOUT
     });
-    this.decisions = new Decisions(http);
-    this.artifacts = new Artifacts(http);
-    this.governance = new Governance(http);
+    this.decisions = new Decisions(this.http);
+    this.artifacts = new Artifacts(this.http);
+    this.governance = new Governance(this.http);
     this.webhooks = new Webhooks();
   }
+  /**
+   * "Can I do this?" — the one verb, now covering your own artifacts too. Pass `authority` for a
+   * public Exchange artifact, or `artifact_id` for your own (Studio or the Exchange) — same
+   * return shape either way, so calling code never needs to know which rail answered.
+   *
+   * @example
+   * const client = new Nomos('nms_live_...');
+   * const verdict = await client.can({ artifact_id: 'loan_approval_v1', credit_score: 720 });
+   */
+  async can(params, opts) {
+    return canAuthenticated(this.http, params, opts);
+  }
 };
 
-// src/can.ts
-var DEFAULT_EXCHANGE_BASE = "https://www.nomosprotocol.com";
-async function can(params, opts) {
-  const { authority, action, inputs, ...flat } = params;
-  if (!authority || typeof authority !== "string") {
-    throw new Error("can(): `authority` (an Exchange artifact id or slug) is required.");
+// src/verify-chain.ts
+var CHAIN_PROTOCOL_VERSION2 = "1";
+var DEFAULT_BASE = "https://www.nomosprotocol.com";
+async function verifyChain(params, opts) {
+  if (!params.root_public_key_pem) {
+    throw new Error("verifyChain(): `root_public_key_pem` is required \u2014 there is no default root.");
   }
-  const facts = inputs && typeof inputs === "object" ? inputs : flat;
-  const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
-  const url = `${base}/api/exchange/artifacts/${encodeURIComponent(authority)}/query`;
-  const res = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ inputs: facts, action }),
-    signal: opts?.signal
-  });
+  const base = (opts?.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+  const url = `${base}/api/v1/chain-of-trust/verify`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        version: CHAIN_PROTOCOL_VERSION2,
+        artifact: params.artifact,
+        key_certs: params.key_certs,
+        root_public_key_pem: params.root_public_key_pem
+      }),
+      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) {
-    throw new Error(data?.error ?? `NOMOS query failed (HTTP ${res.status})`);
+  if (data && typeof data.decision === "string") {
+    return data;
   }
-  return {
-    allowed: data.verdict === "AUTHORIZED",
-    verdict: data.verdict,
-    reason: data.verdict_description,
-    rule: data.matched_rule_id ?? null,
-    query_id: data.query_id,
-    url: data.url,
-    authority: {
-      id: data.artifact?.id ?? authority,
-      title: data.artifact?.title ?? "",
-      standing: data.artifact?.standing ?? ""
-    },
-    missing_inputs: data.missing_inputs ?? []
-  };
+  const message = data?.error ?? `Chain verification request failed (HTTP ${res.status})`;
+  if (res.status === 429) {
+    throw new NomosRateLimitError(message, res.headers.get("retry-after") ? parseInt(res.headers.get("retry-after"), 10) : void 0, requestId);
+  }
+  if (res.status === 400) throw new NomosValidationError(message, data?.details, requestId);
+  throw new NomosAPIError(message, res.status, requestId);
 }
-var nomos = { can };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Nomos,
@@ -597,12 +817,15 @@ var nomos = { can };
   NomosAuthenticationError,
   NomosAuthorizationError,
   NomosError,
+  NomosIssuerNotTrustedError,
   NomosNetworkError,
   NomosNotFoundError,
+  NomosPaymentRequiredError,
   NomosRateLimitError,
   NomosValidationError,
   NomosWebhookSignatureError,
   can,
-  nomos
+  nomos,
+  verifyChain
 });
 //# sourceMappingURL=index.cjs.map