@nomosprotocol/sdk 1.2.1 → 1.3.1

package/dist/index.d.ts

@@ -43,9 +43,35 @@ interface DetectContradictionsParams {
 }
 type Verdict = 'approved' | 'rejected' | 'escalated';
 type CanVerdict = 'AUTHORIZED' | 'DENIED' | 'ESCALATED';
+/** Structured form of "who stands behind this artifact" — role, statement, and when, not just
+ *  a name buried in `authority.standing`'s free text. Present only when a live (unrevoked,
+ *  seal-bound) attestation exists on the exact sealed version that answered. Exchange rail only —
+ *  the private-artifact and chain-of-trust rails have no equivalent concept today. */
+interface AttestationInfo {
+    attester_name: string;
+    attester_org_id: string;
+    role: string;
+    statement: string;
+    attested_at: string;
+}
 interface CanParams {
-    /** Exchange artifact's standard name — slug (optionally ".nomos"-suffixed) or raw id, e.g. "eu-ai-act.nomos" */
-    authority: string;
+    /** A public Exchange artifact's standard name — slug (optionally ".nomos"-suffixed) or raw id,
+     *  e.g. "eu-ai-act.nomos". Keyless. Mutually exclusive with `artifact_id`. */
+    authority?: string;
+    /** Your own artifact's id (from Studio or the Exchange). Requires an API key — only valid via
+     *  `client.can()` on an authenticated `Nomos` instance, not the free `can()` export. Mutually
+     *  exclusive with `authority`. */
+    artifact_id?: string;
+    /** Chain-of-trust rail (PROTOTYPE, not a numbered spec): a self-contained sealed artifact you
+     *  received directly — from an agent, another system, anywhere — that NOMOS has never seen or
+     *  registered. Requires `key_certs` and `root_public_key_pem` alongside it. Keyless, works on
+     *  both `nomos.can()` and `client.can()`. */
+    artifact?: unknown;
+    /** The key certificates presented alongside `artifact` — order never affects the result. */
+    key_certs?: KeyCertificate[];
+    /** The root public key (PEM) YOU have independently decided to trust. There is deliberately no
+     *  default — see the chain-of-trust design note for why. Required alongside `artifact`. */
+    root_public_key_pem?: string;
     /** Optional human-readable label for what's being asked (recorded in the transcript) */
     action?: string;
     /** The facts to evaluate. Either pass this explicitly, or spread the facts flat alongside
@@ -63,24 +89,98 @@ interface CanOptions {
 interface CanResult {
     /** True only for an AUTHORIZED verdict. DENIED and ESCALATED are both `false`. */
     allowed: boolean;
-    /** The authority's own verdict, verbatim. */
+    /** 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;
     /** Human-readable explanation of the verdict. */
     reason: string;
     /** The rule id that decided it, if any. */
     rule: string | null;
-    /** Permanent, addressable transcript id — open it any time. */
-    query_id: string;
-    /** Relative URL of the transcript. */
-    url: string;
+    /** Permanent, addressable transcript id — open it any time. Present only when the Exchange rail
+     *  answered (it mints a permanent public transcript for every query). Absent, not faked, when
+     *  your own authenticated artifact answered instead — see `audit` for that rail's provenance. */
+    query_id?: string;
+    /** Relative URL of the transcript. Same availability as `query_id`. */
+    url?: string;
     /** Which authority answered, and its standing. */
     authority: {
         id: string;
         title: string;
         standing: string;
+        attestation?: AttestationInfo;
     };
+    /** The authority's own declared version — its sealed meta.version, not administrative
+     *  metadata that can drift from what's actually embedded in the artifact. Present whenever the
+     *  answering artifact declares one; omitted (not a guess) when it doesn't. */
+    version?: string;
     /** On ESCALATED: the facts the authority still needs to reach a verdict. */
     missing_inputs: string[];
+    /** Notify/log/audit/flag-style duties that fired alongside the verdict — e.g. "must inform the
+     *  affected person" — distinct from the verdict itself: an obligation can accompany an
+     *  AUTHORIZED result, it doesn't only apply to denials. Present on both rails; omitted (not an
+     *  empty array) when none fired, since "no obligations" and "we didn't check" should stay
+     *  distinguishable. */
+    obligations?: Array<{
+        kind: string;
+        rule_id: string | null;
+        rule_name: string | null;
+        reason?: string;
+    }>;
+    /** RECOMMENDED maximum seconds to hold this verdict before re-querying or re-checking the
+     *  issuer's revocation list (NOMOS-SPEC-006 §6.2). Advisory; absent when the artifact isn't
+     *  structurally revocable on this deployment — treat absence as "unknown," not "safe forever." */
+    max_age?: number;
+    /** Present only when your own authenticated artifact answered — that rail's own provenance
+     *  (a hash you can store for compliance), not a permanent public transcript like `query_id`. */
+    audit?: {
+        hash: string;
+        timestamp: string;
+    };
+    /** NOMOS-SPEC-006 — true only when the issuer has revoked this exact sealed version; forces
+     *  `verdict` to DENIED regardless of what the artifact's own rules would otherwise have said.
+     *  Omitted (not `false`) when revocation doesn't structurally apply on this deployment — "no
+     *  revocation" and "couldn't check" must never look identical. */
+    revoked?: boolean;
+    /** Present only alongside `revoked: true` — the issuer's stated reason. */
+    revocation_reason?: string;
+}
+type ChainVerdictDecision = 'ALLOWED' | 'ISSUER_NOT_RECOGNIZED' | 'KEY_REVOKED' | 'SEAL_INVALID' | 'MALFORMED';
+interface KeyCertificate {
+    parent_kid: string;
+    child_kid: string;
+    child_public_key_pem: string;
+    scope?: string;
+    issued_at: string;
+    expires_at: string;
+    algorithm: 'Ed25519';
+    signature: string;
+}
+interface VerifyChainParams {
+    /** The sealed .nomos artifact being presented. */
+    artifact: unknown;
+    /** The set of key certificates presented alongside it — order never affects the result. */
+    key_certs: KeyCertificate[];
+    /** The root public key (PEM) the CALLER has independently decided to trust. There is
+     *  deliberately no default — see the chain-of-trust design note for why. */
+    root_public_key_pem: string;
+}
+interface VerifyChainOptions {
+    /** Override the API host (defaults to the public NOMOS platform). */
+    baseUrl?: string;
+    signal?: AbortSignal;
+}
+interface VerifyChainResult {
+    decision: ChainVerdictDecision;
+    /** Present only when decision === 'ALLOWED'. */
+    leaf_kid?: string;
+    /** Present only when decision === 'ALLOWED' — the resolved kid path from root to leaf. */
+    path?: string[];
+    /** Present only when decision === 'ISSUER_NOT_RECOGNIZED'. */
+    reason?: string;
+    /** Present only when decision === 'KEY_REVOKED'. */
+    revoked_kid?: string;
+    /** Human-readable detail for any non-ALLOWED decision. */
+    detail?: string;
 }
 interface VerifyDecisionResult {
     /** Unique request ID — include in support tickets */
@@ -239,7 +339,7 @@ interface NomosRawResponse {
 type WithLastResponse<T> = T & {
     lastResponse: NomosRawResponse;
 };
-type NomosWebhookEventType = 'artifact.sealed' | 'artifact.published' | 'decision.verified' | 'decision.escalated' | 'exchange.purchased' | 'exchange.reviewed' | 'drift.detected';
+type NomosWebhookEventType = 'artifact.sealed' | 'artifact.published' | 'artifact.revoked' | 'decision.verified' | 'decision.escalated' | 'exchange.purchased' | 'exchange.reviewed' | 'drift.detected';
 interface NomosWebhookEvent {
     id: string;
     type: NomosWebhookEventType;
@@ -409,7 +509,7 @@ declare class Webhooks {
     verifySignature(payload: string | Uint8Array, signature: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
 }
 
-type NomosErrorCode = 'authentication_error' | 'authorization_error' | 'rate_limit_error' | 'validation_error' | 'not_found' | 'api_error' | 'network_error' | 'webhook_signature_error';
+type NomosErrorCode = 'authentication_error' | 'authorization_error' | 'rate_limit_error' | 'validation_error' | 'not_found' | 'api_error' | 'network_error' | 'webhook_signature_error' | 'payment_required' | 'issuer_not_trusted';
 declare class NomosError extends Error {
     readonly code: NomosErrorCode;
     readonly status?: number;
@@ -442,6 +542,27 @@ declare class NomosNetworkError extends NomosError {
 declare class NomosWebhookSignatureError extends NomosError {
     constructor(message: string);
 }
+/** can() asked about a paid authority the caller hasn't purchased or licensed. Distinct from a
+ *  generic 403 on purpose: this isn't "you're not allowed," it's "here's exactly what unlocks
+ *  it" — price and a URL to complete the purchase. NOMOS never auto-charges on your behalf;
+ *  this is the seam where a caller decides to buy, not where a payment silently happens. */
+declare class NomosPaymentRequiredError extends NomosError {
+    readonly priceUsd: number;
+    readonly purchaseUrl: string;
+    constructor(message: string, priceUsd: number, purchaseUrl: string, requestId?: string);
+}
+/** can()'s chain-of-trust rail couldn't establish that the presented artifact is trustworthy —
+ *  an unrecognized issuer, a revoked key, a tampered seal, or a malformed presentation. This is
+ *  deliberately NOT a DENIED verdict: "the rules say no" and "we never got far enough to ask the
+ *  rules anything" are different claims, and collapsing them would tell the caller the wrong
+ *  thing to do next (re-presenting a better chain can fix the first case; it can never fix a
+ *  genuinely tampered artifact). `reason` is the underlying chain decision
+ *  (ISSUER_NOT_RECOGNIZED / KEY_REVOKED / SEAL_INVALID / MALFORMED) for callers that need to
+ *  distinguish them. */
+declare class NomosIssuerNotTrustedError extends NomosError {
+    readonly reason: string;
+    constructor(message: string, reason: string, requestId?: string);
+}
 
 type errors_NomosAPIError = NomosAPIError;
 declare const errors_NomosAPIError: typeof NomosAPIError;
@@ -452,10 +573,14 @@ declare const errors_NomosAuthorizationError: typeof NomosAuthorizationError;
 type errors_NomosError = NomosError;
 declare const errors_NomosError: typeof NomosError;
 type errors_NomosErrorCode = NomosErrorCode;
+type errors_NomosIssuerNotTrustedError = NomosIssuerNotTrustedError;
+declare const errors_NomosIssuerNotTrustedError: typeof NomosIssuerNotTrustedError;
 type errors_NomosNetworkError = NomosNetworkError;
 declare const errors_NomosNetworkError: typeof NomosNetworkError;
 type errors_NomosNotFoundError = NomosNotFoundError;
 declare const errors_NomosNotFoundError: typeof NomosNotFoundError;
+type errors_NomosPaymentRequiredError = NomosPaymentRequiredError;
+declare const errors_NomosPaymentRequiredError: typeof NomosPaymentRequiredError;
 type errors_NomosRateLimitError = NomosRateLimitError;
 declare const errors_NomosRateLimitError: typeof NomosRateLimitError;
 type errors_NomosValidationError = NomosValidationError;
@@ -463,7 +588,7 @@ declare const errors_NomosValidationError: typeof NomosValidationError;
 type errors_NomosWebhookSignatureError = NomosWebhookSignatureError;
 declare const errors_NomosWebhookSignatureError: typeof NomosWebhookSignatureError;
 declare namespace errors {
-  export { errors_NomosAPIError as NomosAPIError, errors_NomosAuthenticationError as NomosAuthenticationError, errors_NomosAuthorizationError as NomosAuthorizationError, errors_NomosError as NomosError, type errors_NomosErrorCode as NomosErrorCode, errors_NomosNetworkError as NomosNetworkError, errors_NomosNotFoundError as NomosNotFoundError, errors_NomosRateLimitError as NomosRateLimitError, errors_NomosValidationError as NomosValidationError, errors_NomosWebhookSignatureError as NomosWebhookSignatureError };
+  export { errors_NomosAPIError as NomosAPIError, errors_NomosAuthenticationError as NomosAuthenticationError, errors_NomosAuthorizationError as NomosAuthorizationError, errors_NomosError as NomosError, type errors_NomosErrorCode as NomosErrorCode, errors_NomosIssuerNotTrustedError as NomosIssuerNotTrustedError, errors_NomosNetworkError as NomosNetworkError, errors_NomosNotFoundError as NomosNotFoundError, errors_NomosPaymentRequiredError as NomosPaymentRequiredError, errors_NomosRateLimitError as NomosRateLimitError, errors_NomosValidationError as NomosValidationError, errors_NomosWebhookSignatureError as NomosWebhookSignatureError };
 }
 
 declare class Nomos {
@@ -474,16 +599,50 @@ declare class Nomos {
     /** Whether this instance is using a live or test API key. */
     readonly mode: 'live' | 'test';
     static readonly errors: typeof errors;
+    private readonly http;
     constructor(apiKey: string, config?: NomosConfig);
+    /**
+     * "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 });
+     */
+    can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
 }
 
 declare function can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
 /**
  * Ready-to-use, keyless entry point matching the canonical `nomos.can(...)` form.
- * For authenticated, key-scoped operations use the `Nomos` class instead.
+ * For paid artifacts or your own artifacts, use `client.can(...)` on an authenticated `Nomos`
+ * instance instead — same function name, same verdict shape, the only difference is which rail
+ * answers and what it can unlock.
  */
 declare const nomos: {
     can: typeof can;
 };
 
-export { type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type CanOptions, type CanParams, type CanResult, type CanVerdict, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type ListArtifactsParams, Nomos, NomosAPIError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosError, type NomosErrorCode, NomosNetworkError, NomosNotFoundError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type RequestOptions, type Verdict, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse, can, nomos };
+/**
+ * Chain-of-trust verification (PROTOTYPE — not a numbered spec). Checks whether a presented
+ * artifact's signing key resolves, through the presented key certificates, back to a root you
+ * have independently decided to trust — entirely server-side against nomos-chain.ts's pure
+ * verifier, with no account or API key required (keyless, matching `nomos.can()`'s precedent).
+ *
+ * There is no default root anywhere in this call — `root_public_key_pem` is required. That's
+ * deliberate: it keeps the trust decision with the caller, not with this SDK or the platform.
+ *
+ * @example
+ * import { verifyChain } from '@nomosprotocol/sdk';
+ *
+ * const result = await verifyChain({
+ *   artifact: sealedArtifact,
+ *   key_certs: [rootToIntermediate, intermediateToLeaf],
+ *   root_public_key_pem: myPinnedRootPem,
+ * });
+ * if (result.decision === 'ALLOWED') { ... }
+ */
+declare function verifyChain(params: VerifyChainParams, opts?: VerifyChainOptions): Promise<VerifyChainResult>;
+
+export { type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type CanOptions, type CanParams, type CanResult, type CanVerdict, type ChainVerdictDecision, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type KeyCertificate, type ListArtifactsParams, Nomos, NomosAPIError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type RequestOptions, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse, can, nomos, verifyChain };

package/dist/index.js

@@ -11,8 +11,10 @@ __export(errors_exports, {
   NomosAuthenticationError: () => NomosAuthenticationError,
   NomosAuthorizationError: () => NomosAuthorizationError,
   NomosError: () => NomosError,
+  NomosIssuerNotTrustedError: () => NomosIssuerNotTrustedError,
   NomosNetworkError: () => NomosNetworkError,
   NomosNotFoundError: () => NomosNotFoundError,
+  NomosPaymentRequiredError: () => NomosPaymentRequiredError,
   NomosRateLimitError: () => NomosRateLimitError,
   NomosValidationError: () => NomosValidationError,
   NomosWebhookSignatureError: () => NomosWebhookSignatureError
@@ -76,6 +78,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) {
@@ -495,6 +512,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;
@@ -510,35 +713,51 @@ 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 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({ inputs: facts, action }),
+      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) {
@@ -547,56 +766,31 @@ async function can(params, opts) {
   }
   const requestId = res.headers.get("x-request-id") ?? "";
   const data = await res.json().catch(() => null);
-  if (!res.ok) {
-    const message = data?.error ?? data?.message ?? `NOMOS query failed (HTTP ${res.status})`;
-    switch (res.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,
-          res.headers.get("retry-after") ? parseInt(res.headers.get("retry-after"), 10) : void 0,
-          requestId
-        );
-      default:
-        throw new NomosAPIError(message, res.status, requestId);
-    }
+  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 };
 export {
   Nomos,
   NomosAPIError,
   NomosAuthenticationError,
   NomosAuthorizationError,
   NomosError,
+  NomosIssuerNotTrustedError,
   NomosNetworkError,
   NomosNotFoundError,
+  NomosPaymentRequiredError,
   NomosRateLimitError,
   NomosValidationError,
   NomosWebhookSignatureError,
   can,
-  nomos
+  nomos,
+  verifyChain
 };
 //# sourceMappingURL=index.js.map