@nomosprotocol/sdk 1.4.0 → 2.0.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { CurrencyPolicy, ActVerdict } from '@nomosprotocol/verify';
+export { bindingDigest, verifyAct, verifyArtifact, verifySeal } from '@nomosprotocol/verify';
+
 interface VerifyDecisionParams {
     /** Artifact ID from NOMOS Studio or the Exchange */
     artifact_id: string;
@@ -68,7 +71,7 @@ interface CanParams {
      *  both `nomos.can()` and `client.can()`. */
     artifact?: unknown;
     /** The key certificates presented alongside `artifact` — order never affects the result. */
-    key_certs?: KeyCertificate[];
+    key_certs?: KeyCertificate$1[];
     /** 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;
@@ -214,7 +217,7 @@ interface ConservedStateReceipt {
     reference?: string;
 }
 type ChainVerdictDecision = 'ALLOWED' | 'ISSUER_NOT_RECOGNIZED' | 'KEY_REVOKED' | 'CERTIFICATE_REVOKED' | 'OUT_OF_SCOPE' | 'SEAL_INVALID' | 'MALFORMED';
-interface KeyCertificate {
+interface KeyCertificate$1 {
     parent_kid: string;
     child_kid: string;
     child_public_key_pem: string;
@@ -228,13 +231,15 @@ 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[];
+    key_certs: KeyCertificate$1[];
     /** 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). */
+    /** Ask the hosted platform instead of verifying locally. Off by default. */
+    remote?: boolean;
+    /** With `remote`: override the API host (defaults to the public NOMOS platform). */
     baseUrl?: string;
     signal?: AbortSignal;
 }
@@ -789,24 +794,412 @@ declare const 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).
+ * NOMOS-SPEC-007 rev. 1.9 chain verification: does this artifact's signing key resolve, through the
+ * presented key certificates, to a root you have decided to trust, and was it delegated this artifact?
  *
- * 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.
+ * Computed locally by @nomosprotocol/verify: no network call, no account, and no dependence on any
+ * NOMOS service being up or honest. There is no default root: `root_public_key_pem` is required, so
+ * the trust decision stays with you. Pass `{ remote: true }` only to ask the hosted platform instead.
  *
  * @example
- * import { verifyChain } from '@nomosprotocol/sdk';
- *
- * const result = await verifyChain({
- *   artifact: sealedArtifact,
- *   key_certs: [rootToIntermediate, intermediateToLeaf],
- *   root_public_key_pem: myPinnedRootPem,
- * });
+ * const result = await verifyChain({ artifact, key_certs, 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 ConservedStateInfo, type ConservedStateReceipt, 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 Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse, can, nomos, verifyChain };
+type SignatureSuite = 'Ed25519' | 'ES256';
+interface Signer {
+    /** NOMOS-SPEC-001 §8.4 key id of the public key. */
+    kid: string;
+    /** The public key, canonical SPKI PEM (NOMOS-SPEC-010 §3.1). */
+    publicKeyPem: string;
+    /** The suite this key signs under. */
+    algorithm: SignatureSuite;
+    /** Signs the exact payload bytes. Returns the signature in the suite's encoding, base64. */
+    sign(payload: Uint8Array): Promise<string>;
+}
+declare function kidOf(publicKeyPem: string): string;
+/** A signer over a private key held in this process: PKCS#8 PEM. For development and tests;
+ *  in production pass a Signer backed by your KMS or HSM. */
+declare function localSigner(privateKeyPem: string): Signer;
+/** A fresh in-memory key. For development and tests only. */
+declare function generateSigner(algorithm?: SignatureSuite): Signer & {
+    privateKeyPem: string;
+};
+/** A deterministic Ed25519 key from a seed string: the same test key on every machine. Never for
+ *  anything real — the seed is the key. */
+declare function seededSigner(seed: string): Signer;
+
+interface Action {
+    type: string;
+    subject?: string;
+    params?: Record<string, unknown>;
+}
+interface KeyCertificate {
+    parent_kid: string;
+    child_kid: string;
+    child_public_key_pem: string;
+    scope?: string | null;
+    issued_at: string;
+    expires_at: string;
+    algorithm: 'Ed25519' | 'ES256';
+    signature: string;
+}
+/** NOMOS-SPEC-007 §3: `parent` certifies `child` within `scope` until `expiresAt`. */
+declare function certify(parent: Signer, child: {
+    kid: string;
+    publicKeyPem: string;
+}, opts: {
+    scope?: string;
+    issuedAt?: Date;
+    expiresAt: Date;
+}): Promise<KeyCertificate>;
+/** NOMOS-SPEC-001 §8: seal an artifact body with the issuer's key. */
+declare function seal(body: Record<string, unknown>, issuer: Signer, signedBy: Record<string, unknown> | string): Promise<any>;
+/** NOMOS-SPEC-008 §3: a witness's signed statement of one fact about one subject. */
+declare function signTestimony(witness: Signer, t: {
+    claim: string;
+    value: unknown;
+    about?: string | null;
+    asOf?: Date;
+    validUntil: Date;
+}): Promise<any>;
+/** NOMOS-SPEC-008 §4: an approver's consent to exactly this Act, in this role. */
+declare function signConsent(approver: Signer, act: any, role: string, decision?: 'approve' | 'refuse'): Promise<any>;
+/** NOMOS-SPEC-008 §5.4: the issuer's statement that this exact version is in force, for a day at most. */
+declare function signInForce(issuer: Signer, artifact: any, opts: {
+    asOf?: Date;
+    validUntil: Date;
+}): Promise<any>;
+interface BuildActOptions {
+    relyingParty: string;
+    action: Action;
+    artifact: any;
+    keyCerts: KeyCertificate[];
+    testimony?: any[];
+    presenterFacts?: Record<string, unknown>;
+    inForce?: any;
+    /** Validity window in seconds (SPEC-008 §5.1). Longer windows leave a person time to approve. */
+    windowSeconds?: number;
+    now?: Date;
+}
+/** NOMOS-SPEC-008 §2: assemble an Act. It needs no key: what makes it valid is what it carries. */
+declare function buildAct(o: BuildActOptions): any;
+
+/**
+ * NOMOS-SPEC-009 §3 discovery documents. A document tells a carrier where to go and what to bring;
+ * it never decides anything (§2), so nothing here is trusted beyond what the verifier rechecks.
+ */
+
+interface RelyingPartyDocument {
+    nomos_document: 'relying-party';
+    version: '1';
+    relying_party_id: string;
+    act_endpoint: string;
+    roots: Array<{
+        kid: string;
+        public_key_pem: string;
+    }>;
+    authorities: Array<{
+        artifact_id: string;
+        issuer?: string;
+        actions: string[];
+        currency_policy: 'record' | 'record_or_statement';
+        in_force_seal_hash?: string;
+    }>;
+    local_facts?: string[];
+    max_window_seconds: number;
+    max_act_bytes?: number;
+    consent_suites?: string[];
+    valid_until?: string;
+}
+interface IssuerDocument {
+    nomos_document: 'issuer';
+    version: '1';
+    issuer_id: string;
+    authorities: Array<{
+        artifact_id: string;
+        version: string;
+        seal_hash: string;
+        artifact_url: string;
+        in_force_url?: string;
+    }>;
+    key_certs: KeyCertificate[];
+    witnesses?: string[];
+    approvals?: Array<{
+        role: string;
+        endpoint: string;
+    }>;
+    revocations_url?: string;
+    valid_until?: string;
+}
+interface WitnessDocument {
+    nomos_document: 'witness';
+    version: '1';
+    witness_id: string;
+    kid: string;
+    claims: string[];
+    statement_endpoint: string;
+    access?: string;
+    valid_until?: string;
+}
+declare const PATH: {
+    readonly 'relying-party': "/.well-known/nomos-relying-party";
+    readonly issuer: "/.well-known/nomos-issuer";
+    readonly witness: "/.well-known/nomos-witness";
+};
+type Kind = keyof typeof PATH;
+type DocOf<K extends Kind> = K extends 'relying-party' ? RelyingPartyDocument : K extends 'issuer' ? IssuerDocument : WitnessDocument;
+declare class NomosDiscoveryError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+/** The origin of a URL or bare origin: `https://shop.example/anything` → `https://shop.example`. */
+declare function originOf(to: string): string;
+/** Fetches and checks one discovery document (§2 rule 4, §3). */
+declare function fetchDocument<K extends Kind>(kind: K, origin: string, fetchImpl?: typeof fetch): Promise<DocOf<K>>;
+declare const WELL_KNOWN: {
+    readonly 'relying-party': "/.well-known/nomos-relying-party";
+    readonly issuer: "/.well-known/nomos-issuer";
+    readonly witness: "/.well-known/nomos-witness";
+};
+
+/**
+ * accept() — the relying party: the system that makes the change.
+ *
+ *   const rp = accept({ relyingPartyId, root, authorities, commit });
+ *   app.use(rp.express());                       // Express, Connect, node:http
+ *   export default { fetch: rp.fetch };          // Hono, Next.js, Cloudflare, Deno, Bun
+ *
+ * For every Act it receives it runs NOMOS-SPEC-008 §6 with @nomosprotocol/verify, locally, and on
+ * AUTHORIZED applies §8 exactly, in one transaction: record the nonce, re-read its own facts
+ * (re-verifying if they moved), hand `commit` a copy of exactly the verified action, and store the
+ * receipt. It answers with the NOMOS-SPEC-009 §6.2 status codes and serves its own discovery
+ * document (§3.1), generated from this same configuration so the two can never disagree (§2).
+ */
+
+interface AcceptedAuthority {
+    /** The sealed artifact's meta.artifact_id. */
+    artifactId: string;
+    /** Origin of the issuer document (NOMOS-SPEC-009 §3.2), advertised so carriers can find it. */
+    issuer?: string;
+    /** The action types this system commits under this authority. Anything else is refused. */
+    actions: string[];
+    /** SPEC-008 §5.5. `record` (RECOMMENDED) needs `inForceSealHash`. */
+    currencyPolicy: CurrencyPolicy;
+    /** Your record of the version in force: the seal hash of the version you accept. */
+    inForceSealHash?: string;
+}
+interface Receipt {
+    act_id: string;
+    act_digest: string;
+    decision: string;
+    rule: string | null;
+    by_consent?: boolean;
+    verified_at: string;
+    committed_at?: string;
+    relying_party_facts: Record<string, unknown>;
+    in_force_source?: string;
+    currency_policy: CurrencyPolicy;
+    consent_origins?: string[];
+}
+/** One atomic operation (SPEC-008 §8). `tx` is passed to `commit` and `localFacts` so your own
+ *  writes and reads share it. */
+interface AcceptTransaction<Tx = unknown> {
+    /** Records the nonce. false if it was already recorded (a concurrent duplicate). */
+    claimNonce(nonce: string): Promise<boolean>;
+    putReceipt(nonce: string, receipt: Receipt): Promise<void>;
+    tx: Tx;
+}
+interface AcceptStore<Tx = unknown> {
+    hasNonce(nonce: string): Promise<boolean>;
+    receiptFor(nonce: string): Promise<Receipt | null>;
+    transaction<T>(fn: (t: AcceptTransaction<Tx>) => Promise<T>): Promise<T>;
+}
+interface AcceptOptions<Tx = unknown> {
+    /** Your identifier. Acts addressed to anything else are refused (SPEC-008 §5.3). */
+    relyingPartyId: string;
+    /** The root you pin (PEM). There is no default root. */
+    root: string;
+    authorities: AcceptedAuthority[];
+    /** Applies the change. Receives a deep copy of exactly the verified action, and nothing else
+     *  from the request (SPEC-009 §6.4). Its return value is sent back as `result`. */
+    commit: (action: {
+        type: string;
+        subject?: string;
+        params: Record<string, unknown>;
+    }, ctx: {
+        tx: Tx;
+        actId: string;
+    }) => Promise<unknown> | unknown;
+    /** Facts you supply from your own state (inputs with source `relying_party`). Called once to
+     *  verify, and again inside the transaction to check nothing moved (SPEC-008 §8 step 3). */
+    localFacts?: (act: any, tx?: Tx) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /** Where nonces and receipts live. Defaults to memory, for development only. */
+    store?: AcceptStore<Tx>;
+    /** The absolute URL carriers POST Acts to, as advertised in your discovery document. */
+    actEndpoint: string;
+    /** SPEC-008 §5.1 / SPEC-009 §6.3. Long enough for a person to approve. Default 900. */
+    maxWindowSeconds?: number;
+    maxActBytes?: number;
+    /** Current revocation state (SPEC-006, SPEC-007 §5). Read on every verification. */
+    revocations?: () => Promise<{
+        kids?: Set<string>;
+        certs?: Set<string>;
+        artifacts?: Set<string>;
+    }> | {
+        kids?: Set<string>;
+        certs?: Set<string>;
+        artifacts?: Set<string>;
+    };
+    /** `shadow`: verify and record every verdict, never commit. For pilots. */
+    mode?: 'enforce' | 'shadow';
+    /** Every verdict, committed or not (SPEC-008 §9: a receipt for every verification). */
+    onVerdict?: (verdict: ActVerdict, receipt: Receipt) => void | Promise<void>;
+    /** How long this document is valid for, in seconds. Default one day. */
+    documentTtlSeconds?: number;
+    now?: () => Date;
+}
+interface Answer {
+    status: number;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+}
+declare const statusFor: (decision: string) => number;
+declare const ACT_MEDIA_TYPE = "application/nomos-act+json";
+/** Nonces and receipts in memory, one transaction at a time. Lost on restart, single process:
+ *  for development and tests only. Use a database-backed store in production. */
+declare function memoryStore(): AcceptStore<null>;
+declare function accept<Tx = unknown>(o: AcceptOptions<Tx>): {
+    handle: (req: {
+        method?: string;
+        headers: Record<string, string | string[] | undefined>;
+        body: string | Uint8Array;
+    }) => Promise<Answer>;
+    document: () => RelyingPartyDocument;
+    fetch: (request: Request) => Promise<Response>;
+    express: () => (req: any, res: any, next?: () => void) => Promise<void>;
+    node: () => (req: any, res: any, next?: () => void) => Promise<void>;
+};
+
+type ActStatus = 'committed' | 'escalated' | 'incomplete' | 'denied' | 'refused' | 'replayed';
+interface ActResult {
+    status: ActStatus;
+    /** The relying party's verdict, exactly as it returned it (SPEC-009 §6.2). */
+    verdict: Record<string, any>;
+    /** When committed: the receipt, and what the relying party's commit returned. */
+    receipt?: Record<string, any>;
+    result?: unknown;
+    /** When incomplete: the facts that could still change the outcome, and why each is missing. */
+    missing?: Array<{
+        fact: string;
+        source: string | null;
+        why: string;
+    }>;
+    /** When escalated and not approved in time: where a person can approve. */
+    approvalUrl?: string;
+    /** The Act as submitted, for your records. */
+    act: any;
+    /** What happened, in one sentence. */
+    summary: string;
+}
+interface ActOptions {
+    /** The relying party: its origin or any URL on it. */
+    to: string;
+    action: Action;
+    /** Which authority to act under, when the relying party accepts several for this action type. */
+    authority?: string;
+    /** Facts the carrier supplies itself (inputs whose declared source is `presenter`). */
+    presenterFacts?: Record<string, unknown>;
+    /** Credentials for witnesses that need them: origin → headers (SPEC-009 §3.3 `access`). */
+    witnessHeaders?: Record<string, Record<string, string>>;
+    /** Wait up to this long for a person to approve, in ms. Default: until the Act expires. */
+    approvalTimeoutMs?: number;
+    /** Called once per pending approval with the page a person can approve on. */
+    onApproval?: (approval: {
+        role: string;
+        url?: string;
+        actDigest: string;
+    }) => void;
+    /** Use a specific fetch (tests, proxies). */
+    fetch?: typeof fetch;
+    /** Poll interval for pending approvals, ms. Default 1000. */
+    pollMs?: number;
+}
+declare class NomosActError extends Error {
+    constructor(message: string);
+}
+declare function act(o: ActOptions): Promise<ActResult>;
+
+interface IssuerOptions {
+    /** Your public origin, e.g. https://policy.acme.example */
+    origin: string;
+    issuerId: string;
+    /** The key that sealed the authorities; it also signs in-force statements (SPEC-008 §5.4). */
+    signer: Signer;
+    /** Sealed artifacts, each the version currently in force. */
+    authorities: any[];
+    /** The certificate pool carriers present: your sealing key, witnesses, approvers (SPEC-007). */
+    keyCerts: KeyCertificate[];
+    witnesses?: string[];
+    approvals?: Array<{
+        role: string;
+        endpoint: string;
+    }>;
+    revocationsUrl?: string;
+}
+declare function issuer(o: IssuerOptions): {
+    fetch: (request: Request) => Promise<Response>;
+    express: () => (req: any, res: any, next?: () => void) => Promise<any>;
+    node: () => (req: any, res: any, next?: () => void) => Promise<any>;
+    document: () => IssuerDocument;
+};
+interface WitnessOptions {
+    origin: string;
+    witnessId: string;
+    /** A key certified for exactly these claims (SPEC-007 rev. 1.8 §3.4.1). */
+    signer: Signer;
+    /** Each claim this witness states, and how to read its current value for a subject. Return
+     *  undefined when the subject is unknown. */
+    claims: Record<string, (about: string | null) => unknown | Promise<unknown>>;
+    /** How long a statement stays true, at most, in seconds. Default 900. */
+    maxValiditySeconds?: number;
+    /** Your access control (SPEC-009 §3.3): return false to refuse a requester. */
+    authorize?: (request: {
+        claim: string;
+        about: string | null;
+    }) => boolean | Promise<boolean>;
+    access?: string;
+}
+declare function witness(o: WitnessOptions): {
+    fetch: (request: Request) => Promise<Response>;
+    express: () => (req: any, res: any, next?: () => void) => Promise<any>;
+    node: () => (req: any, res: any, next?: () => void) => Promise<any>;
+    document: () => WitnessDocument;
+};
+interface ApproverOptions {
+    origin: string;
+    /** The person's key, certified with `consent:<role> approver:<their id>` (SPEC-007 rev. 1.9 §3.7). */
+    signer: Signer;
+    roles: string[];
+    /** 'page' (default): a person approves on a page this handler serves. 'auto': approve every
+     *  request at once — development only. Or a function that decides. */
+    decide?: 'page' | 'auto' | ((request: {
+        role: string;
+        act: any;
+    }) => boolean | Promise<boolean>);
+}
+interface Pending {
+    role: string;
+    act: any;
+    status: 'pending' | 'approved' | 'refused' | 'expired';
+    consent?: any;
+}
+declare function approver(o: ApproverOptions): {
+    fetch: (request: Request) => Promise<Response>;
+    express: () => (req: any, res: any, next?: () => void) => Promise<any>;
+    node: () => (req: any, res: any, next?: () => void) => Promise<any>;
+    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 BuildActOptions, type CanOptions, type CanParams, type CanResult, type CanVerdict, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, 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 Receipt, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type SignatureSuite, type Signer, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, approver, buildAct, can, certify, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryStore, nomos, originOf, seal, seededSigner, signConsent, signInForce, signTestimony, statusFor, verifyChain, witness };