@nomosprotocol/sdk 1.3.4 → 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;
@@ -128,7 +131,10 @@ interface CanResult {
     }>;
     /** 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." */
+     *  structurally revocable on this deployment — treat absence as "unknown," not "safe forever."
+     *  Disclosed gap: only ever set on the public authority rail today — client.can() and the
+     *  presented-artifact rail don't emit it yet, so apply the same "don't hold a stale verdict
+     *  across a meaningful delay" discipline manually on those two until that's closed. */
     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`. */
@@ -151,8 +157,67 @@ interface CanResult {
      *  (not a guess) on the Exchange/private-artifact rails, where this concept doesn't apply. */
     revocation_checked?: 'live' | 'staple' | 'unchecked';
 }
+interface ConservedStateInfo {
+    artifact_id: string;
+    scope: string;
+    limit_amount: number;
+    consumed: number;
+    reserved: number;
+    available: number;
+    /** The raw ledger fact to pass into `can()` as `consumed_before` — already consumed+reserved
+     *  (outstanding reservations count as spoken-for), not consumed alone. */
+    consumed_before: number;
+    version: number;
+    state_digest: string;
+}
+/** Reserve against a ledger using a real `can()` decision. */
+interface ReserveByQueryParams {
+    artifact_id: string;
+    scope: string;
+    amount: number;
+    /** The `query_id` from a real `can()`/`nomos.can()` call that returned AUTHORIZED.
+     *  `reserve()` looks that decision up itself and derives its own binding from it — this is a
+     *  lookup key, not a claim you're asserting, and a made-up or already-used one is rejected. */
+    query_id: string;
+    action: string;
+    /** Optimistic-concurrency check: reject unless the ledger's state still matches what you last
+     *  read via `conservedState.get()`. Omit only when you have no prior read to compare against. */
+    expected_state_digest?: string;
+    ttl_seconds?: number;
+}
+/** Reserve against a ledger using a NOMOS-SPEC-008 Act: the ledger verifies the Act itself (its
+ *  own pinned root and audience id, its own `consumed_before`, single-use nonce) and holds exactly
+ *  `act.action.params.amount` for `act.action.type === 'conserved_state.reserve'`, or nothing. */
+interface ReserveByActParams {
+    artifact_id: string;
+    scope: string;
+    act: Record<string, unknown>;
+    ttl_seconds?: number;
+}
+type ReserveParams = ReserveByQueryParams | ReserveByActParams;
+/** The cryptographically-bound reservation object — R-12 §5. */
+interface Reservation {
+    reservation_id: string;
+    authority_seal: string;
+    decision_digest: string;
+    agent: string;
+    action: string;
+    scope: string;
+    amount: number;
+    state_digest: string;
+    expires_at: string;
+    status: 'held' | 'settled' | 'released' | 'expired';
+}
+interface ConservedStateReceipt {
+    reservation_id: string;
+    outcome: 'settled' | 'released';
+    amount: number;
+    ledger_key: string;
+    resolved_at: string;
+    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;
@@ -166,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;
 }
@@ -525,32 +592,107 @@ declare class Webhooks {
     verifySignature(payload: string | Uint8Array, signature: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
 }
 
+/**
+ * The state layer for a conserved (depleting) budget — R-12, a design in progress
+ * (docs/design-notes/conserved-state-authority.md in the platform repo; public mirror:
+ * computableauthority.com/research/conserved-state-authority). PROTOTYPE, not a numbered spec.
+ *
+ * `can()` stays exactly what it always was: pure, stateless, given facts and returning a
+ * verdict. Nothing here changes that. This resource is what a caller consults BEFORE calling
+ * `can()` (to build the `consumed_before` fact) and commits to AFTER `can()` returns AUTHORIZED
+ * and the caller has actually decided to act — never at `can()` time itself (repeatedly calling
+ * `can()` while deciding must never itself burn the budget).
+ *
+ * @example
+ * const state = await client.conservedState.get('supplier-budget-2026', 'supplier:acme');
+ * const verdict = await client.can({ artifact_id: 'supplier-budget-2026', consumed_before: state.consumed_before });
+ * if (verdict.allowed) {
+ *   const reservation = await client.conservedState.reserve({
+ *     artifact_id: 'supplier-budget-2026', scope: 'supplier:acme',
+ *     amount: 5000, query_id: verdict.query_id!, action: 'payments.transfer',
+ *   });
+ *   try {
+ *     // ... perform the real action ...
+ *     await client.conservedState.settle(reservation.reservation_id);
+ *   } catch {
+ *     await client.conservedState.release(reservation.reservation_id);
+ *   }
+ * }
+ */
+declare class ConservedState {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Read a ledger's current balance — no auth required, same posture as `can()`'s own keyless
+     * rail (reading how much budget remains is no more sensitive than reading a verdict).
+     */
+    get(artifactId: string, scope: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateInfo>>;
+    /**
+     * Commit capacity against a REAL, AUTHORIZED `can()` decision. Authenticated — unlike `can()`,
+     * spending against a shared budget requires an API key or session; `agent` on the returned
+     * reservation traces to that authenticated identity, never a value you pass in.
+     *
+     * Throws (via the SDK's standard NomosError hierarchy; `err.details?.code` carries the
+     * server's own code): `DECISION_NOT_FOUND` (the query_id names no real query), `DECISION_NOT
+     * _AUTHORIZED` (that decision didn't verdict AUTHORIZED for this artifact), `DECISION_ALREADY
+     * _USED` (already bound to a reservation — one decision authorizes one, ever), `STATE_CONFLICT`
+     * (a stale `expected_state_digest`), `INSUFFICIENT_CAPACITY` (`err.details.requested`/
+     * `.available` carry the numbers), or `NO_LEDGER` (nobody has declared this budget yet).
+     *
+     * Passing `{ artifact_id, scope, act }` instead authorizes the hold with a NOMOS-SPEC-008 Act.
+     * Extra codes: `ACT_NOT_ACCEPTED` (the ledger has no Act binding) and `ACT_REJECTED`, with the
+     * verifier's full answer in `err.details.result` — for `INCOMPLETE` it names the open rules and
+     * the facts whose testimony would decide them.
+     */
+    reserve(params: ReserveParams, opts?: RequestOptions): Promise<WithLastResponse<Reservation>>;
+    /**
+     * The reserved action succeeded — moves the hold into real, settled spend. Idempotent when
+     * you pass the same `reference` again for a retry (e.g. after a network timeout): you get the
+     * ORIGINAL receipt back, never a double-charge.
+     */
+    settle(reservationId: string, reference?: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateReceipt>>;
+    /**
+     * The reserved action failed, or you decided not to act — gives the hold's capacity back
+     * without ever touching what's actually been spent.
+     */
+    release(reservationId: string, reference?: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateReceipt>>;
+}
+
 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;
     readonly requestId?: string;
-    constructor(message: string, code: NomosErrorCode, status?: number, requestId?: string);
+    /** The full parsed JSON response body, when the server sent one — every field it put there
+     *  (its own `code`, and anything endpoint-specific like `requested`/`available` on a
+     *  conserved-state capacity rejection, or `price_usd`/`purchase_url` before those got a
+     *  dedicated error class). `NomosError`'s own `code` above is the SDK's fixed HTTP-status
+     *  taxonomy; `details?.code` is the SERVER's own, finer-grained application code — the two
+     *  are deliberately not conflated into one field. */
+    readonly details?: unknown;
+    constructor(message: string, code: NomosErrorCode, status?: number, requestId?: string, details?: unknown);
 }
 declare class NomosAuthenticationError extends NomosError {
-    constructor(message?: string, requestId?: string);
+    constructor(message?: string, requestId?: string, details?: unknown);
 }
 declare class NomosAuthorizationError extends NomosError {
-    constructor(message?: string, requestId?: string);
+    constructor(message?: string, requestId?: string, details?: unknown);
 }
 declare class NomosRateLimitError extends NomosError {
     readonly retryAfter?: number;
-    constructor(message?: string, retryAfter?: number, requestId?: string);
+    constructor(message?: string, retryAfter?: number, requestId?: string, details?: unknown);
 }
+/** `details` is the parsed response body — kept as its own constructor param (rather than just
+ *  relying on the base class field) since it long predates NomosError.details and every caller
+ *  already passes it positionally in this slot; unchanged for backward compatibility. */
 declare class NomosValidationError extends NomosError {
-    readonly details?: unknown;
     constructor(message: string, details?: unknown, requestId?: string);
 }
 declare class NomosNotFoundError extends NomosError {
-    constructor(message: string, requestId?: string);
+    constructor(message: string, requestId?: string, details?: unknown);
 }
 declare class NomosAPIError extends NomosError {
-    constructor(message: string, status: number, requestId?: string);
+    constructor(message: string, status: number, requestId?: string, details?: unknown);
 }
 declare class NomosNetworkError extends NomosError {
     constructor(message: string);
@@ -620,6 +762,9 @@ declare class Nomos {
     readonly artifacts: Artifacts;
     readonly governance: Governance;
     readonly webhooks: Webhooks;
+    /** The R-12 conserved-state (depleting-budget) state layer — PROTOTYPE, not a numbered spec.
+     *  See resources/conserved-state.ts for the full reserve/settle/release lifecycle. */
+    readonly conservedState: ConservedState;
     /** Whether this instance is using a live or test API key. */
     readonly mode: 'live' | 'test';
     static readonly errors: typeof errors;
@@ -649,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 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 };
+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 };