@nomosprotocol/sdk 1.4.0 → 2.3.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { CurrencyPolicy, ActVerdict, KeyCertificate as KeyCertificate$2, RevocationStatement, RevocationList, ScopeTerms } 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,752 @@ 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>;
+}
+/** The key id of a canonical Ed25519 or P-256 public key (NOMOS-SPEC-010 §3.1–§3.2). Throws for
+ *  any other key: a non-canonical key has no key id, because no verifier would accept it. */
+declare function kidOf(publicKeyPem: string): string;
+/** A signer over a private key held in this process: PKCS#8 PEM (or SEC1 for P-256). 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>;
+    /** Stores the receipt, and the exact Act it verified (SPEC-008 §9: the receipt plus a retained
+     *  copy of the Act let a third party re-run the verification). */
+    putReceipt(nonce: string, receipt: Receipt, act?: unknown): 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 once per Act. Use revocationSource()
+     *  for an issuer's published list. If it throws, the Act is refused with 503 and nothing is
+     *  committed: revocations that cannot be checked are never treated as "nothing revoked"
+     *  (SPEC-007 rev. 1.10 §5.6). */
+    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. In production use postgresStore() or your own AcceptStore. */
+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>;
+};
+
+/**
+ * postgresStore() — the production store for accept(): nonces, receipts and the Acts themselves,
+ * in your own Postgres, in the same transaction as your own change.
+ *
+ *   import pg from 'pg';
+ *   const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+ *   const store = postgresStore(pool);
+ *   await store.migrate();                                  // once; or apply store.schema yourself
+ *   accept({ ..., store, commit: async (action, { tx }) => tx.query('INSERT INTO orders …', […]) });
+ *
+ * What it guarantees (NOMOS-SPEC-008 §8, NOMOS-SPEC-009 §6.3–§6.4):
+ *  - One transaction. `commit` receives `tx`, the very client the nonce is recorded on, so your
+ *    change, the nonce and the receipt commit together or not at all.
+ *  - One commit per Act, under any concurrency. The nonce is the table's primary key; a second
+ *    submission of the same Act waits for the first transaction and then finds the nonce taken,
+ *    so it is answered REPLAYED with the first receipt. If the first rolled back, the second
+ *    commits instead: a nonce is recorded only when the change is.
+ *  - An audit trail. Each row keeps the receipt and the exact Act it verified, so a third party
+ *    can re-run SPEC-008 §6 later (SPEC-008 §9). Rows are never deleted by this store: how long
+ *    to retain them is your policy. They must outlive the Acts' validity windows at least, or a
+ *    replayed Act could commit twice.
+ *
+ * It depends on no driver: pass a `pg` Pool (node-postgres) or anything with the same two
+ * methods, for example a pool adapter over postgres.js, Neon's serverless driver or PGlite.
+ */
+
+/** The part of a node-postgres client this store uses. */
+interface PgClient {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+}
+/** The part of a node-postgres Pool this store uses. */
+interface PgPool extends PgClient {
+    connect(): Promise<PgClient & {
+        release(err?: unknown): void;
+    }>;
+}
+interface PostgresStoreOptions {
+    /** Table name, optionally schema-qualified. Default `nomos_acts`. */
+    table?: string;
+}
+declare function postgresStore(pool: PgPool, opts?: PostgresStoreOptions): AcceptStore<PgClient> & {
+    schema: string;
+    migrate(): Promise<void>;
+};
+
+/**
+ * Certificates and revocations, as the carrier and the relying party need them.
+ *
+ *   presentedCertificates(available, act)   NOMOS-SPEC-009 0.2.0 §6.5: exactly the certificates an Act presents
+ *   signRevocation(parent, target, reason)  NOMOS-SPEC-007 rev. 1.10 §5.1: revoke a key or one certificate
+ *   signRevocationList(signer, …)           rev. 1.10 §5.3: a list a relying party can check for itself
+ *   revocationSource({ url, root, … })      rev. 1.10 §5.3a, §5.6: current revocations for accept(), fail closed when stale
+ */
+
+declare const MAX_PRESENTED = 20;
+/** The kids an Act relies on: its seal's key, every witness's and every approver's. */
+declare function reliedKids(act: any): string[];
+/** NOMOS-SPEC-009 0.2.0 §6.5: the closure of `available` over the kids `act` relies on, each
+ *  certificate once. Deterministic, so two carriers with the same certificates present the same set. */
+declare function presentedCertificates(available: KeyCertificate$2[], act: any): KeyCertificate$2[];
+/** NOMOS-SPEC-007 rev. 1.10 §5.1: `parent` revokes a key it certified, or one certificate it issued. */
+declare function signRevocation(parent: Signer, target: {
+    kid: string;
+} | {
+    certificate: KeyCertificate$2;
+}, reason: string, issuedAt?: Date): Promise<RevocationStatement>;
+/** NOMOS-SPEC-007 rev. 1.10 §5.3: a signed, dated list. `keyCerts` should be the closure over
+ *  the signers and what they revoke (and the list signer), so any relying party can check it. */
+declare function signRevocationList(signer: Signer, statements: RevocationStatement[], keyCerts?: KeyCertificate$2[], generatedAt?: Date): Promise<RevocationList>;
+/** The certificates a revocation list should carry (rev. 1.10 §5.3): the closure over every
+ *  statement's signer and target, and the list's own signer, within the publisher's certificates. */
+declare function revocationListCertificates(available: KeyCertificate$2[], statements: RevocationStatement[], listSignerKid: string): KeyCertificate$2[];
+declare class RevocationUnavailable extends Error {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number);
+}
+interface RevocationSourceOptions {
+    /** The issuer's revocation list (its NOMOS-SPEC-009 `revocations_url`). */
+    url: string;
+    /** The root you pin: statements count only from parents it reaches; the list's date only from a signer it reaches. */
+    root: string;
+    /** How old the newest current list may be before accept() refuses to commit (rev. 1.10 §5.6). Policy, not protocol. Default 3600. */
+    maxAgeSeconds?: number;
+    /** Your own certificates, for statements whose certificates the list does not carry. */
+    ownCerts?: KeyCertificate$2[];
+    /** How long to reuse a fetched list before fetching again. Default 60 s, as the reference deployment publishes. */
+    refreshSeconds?: number;
+    fetch?: typeof fetch;
+    now?: () => Date;
+}
+/**
+ * Current revocations from an issuer's list, for accept({ revocations }).
+ *
+ * Every counted statement is kept for good: a later fetch that fails, or a list that omits it,
+ * never un-revokes a key (rev. 1.10 §5.6). When the newest list with an established `as_of` is
+ * older than `maxAgeSeconds`, it throws RevocationUnavailable, and accept() refuses to commit
+ * with 503 and Retry-After rather than acting as if nothing were revoked.
+ */
+declare function revocationSource(o: RevocationSourceOptions): () => Promise<{
+    kids: Set<string>;
+    certs: Set<string>;
+}>;
+
+/**
+ * certificateRegistry() — an institution's certificates and revocations, managed rather than
+ * minted in code.
+ *
+ *   const registry = certificateRegistry({ root: ROOT_PUBLIC_PEM, store: postgresRegistryStore(pool) });
+ *   await registry.issue({ parent: rootSigner, child: finance, scope: 'claim:budget_remaining', days: 365 });
+ *   await registry.revokeKey({ parent: rootSigner, kid: lostPhone.kid, reason: 'Phone lost' });
+ *   issuer({ …, keyCerts: () => registry.pool(), revocations: () => registry.revocationList(listSigner) });
+ *   witness({ …, keyCerts: await registry.chainFor(finance.kid) });
+ *
+ * Everything it writes is exactly NOMOS-SPEC-007: certificates (§3), revocation statements and
+ * lists (rev. 1.10 §5). It refuses, at issue time, what a relying party would refuse later: a
+ * parent the root does not reach, a scope wider than the parent's, a suite the parent may not
+ * sign under, a malformed scope. Nothing it publishes is trusted because the registry published
+ * it: every relying party checks it again.
+ */
+
+/** Where a registry keeps its certificates and revocation statements. Append-only. */
+interface RegistryStore {
+    certificates(): Promise<KeyCertificate$2[]>;
+    addCertificate(c: KeyCertificate$2): Promise<void>;
+    statements(): Promise<RevocationStatement[]>;
+    addStatement(s: RevocationStatement): Promise<void>;
+}
+/** In memory, for tests and development. */
+declare function memoryRegistryStore(): RegistryStore;
+declare class RegistryError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+interface IssueOptions {
+    parent: Signer;
+    child: {
+        kid: string;
+        publicKeyPem: string;
+    };
+    scope?: string;
+    /** Validity: `expiresAt`, or `days` from now. */
+    expiresAt?: Date;
+    days?: number;
+    issuedAt?: Date;
+}
+declare function certificateRegistry(o: {
+    root: string;
+    store: RegistryStore;
+    now?: () => Date;
+}): {
+    rootKid: string;
+    pool: (filter?: (c: KeyCertificate$2) => boolean) => Promise<KeyCertificate$2[]>;
+    /** NOMOS-SPEC-007 §3: certify `child` under `parent`. Refuses anything a verifier would refuse. */
+    issue(io: IssueOptions): Promise<KeyCertificate$2>;
+    /** rev. 1.10 §5.1: `parent` revokes a key it certified. The key is dead on every path. */
+    revokeKey(io: {
+        parent: Signer;
+        kid: string;
+        reason: string;
+    }): Promise<RevocationStatement>;
+    /** rev. 1.10 §5.1: withdraw one certificate; the key stays valid under any other. */
+    revokeCertificate(io: {
+        parent: Signer;
+        fingerprint: string;
+        reason: string;
+    }): Promise<RevocationStatement>;
+    /** The certificates that connect `kid` to the root: what a witness or approver returns with
+     *  what it signs (SPEC-009 0.2.0 §4, §5). */
+    chainFor(kid: string): Promise<KeyCertificate$2[]>;
+    /** How `kid` is reached from the root, and with which effective scopes, or why it is not. */
+    check(kid: string): Promise<{
+        ok: true;
+        scopes: ScopeTerms[];
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    certificates: () => Promise<KeyCertificate$2[]>;
+    statements: () => Promise<RevocationStatement[]>;
+    /** rev. 1.10 §5.3: the signed list, carrying the certificates that make it checkable. The
+     *  signer should be reached from the root, or the list establishes no date (§5.3). */
+    revocationList(signer: Signer): Promise<RevocationList>;
+};
+type CertificateRegistry = ReturnType<typeof certificateRegistry>;
+/** The registry in your own Postgres (two append-only tables), for an issuer that runs on more
+ *  than one instance. Same structural pool as postgresStore(). */
+declare function postgresRegistryStore(pool: {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}, opts?: {
+    prefix?: string;
+}): RegistryStore & {
+    schema: string;
+    migrate(): Promise<void>;
+};
+
+/** A registration's authenticator data, and the passkey's public key as canonical SPKI PEM. */
+declare function readAttestation(attestationObject: Uint8Array): {
+    authData: Uint8Array;
+    flags: number;
+    credentialId: Uint8Array;
+    publicKeyPem: string;
+};
+interface EnrolmentClaims {
+    approver: string;
+    roles: string[];
+    origin: string;
+    expires_at: string;
+    nonce: string;
+}
+/** Sign a single-use enrolment link for one person (`nomos enroll` does this). */
+declare function signEnrolmentToken(authority: Signer, c: {
+    approver: string;
+    roles: string[];
+    origin: string;
+    expiresAt: Date;
+}): Promise<string>;
+/** The claims of a valid, unexpired link for this origin, or the reason it is not one. */
+declare function verifyEnrolmentToken(token: string, authorityPem: string, origin: string, now: Date): EnrolmentClaims | {
+    error: string;
+};
+interface PasskeyCredential {
+    credential_id: string;
+    approver: string;
+    roles: string[];
+    kid: string;
+    public_key_pem: string;
+    label: string;
+    created_at: string;
+}
+interface PendingApproval {
+    id: string;
+    role: string;
+    act: any;
+    status: 'pending' | 'approved' | 'refused';
+    created_at: string;
+    /** Every ceremony offered, by its challenge: the consent fields fixed before the person was
+     *  asked (§4.5). Append-only, so asking again never invalidates a ceremony already in flight. */
+    attempts: Record<string, Attempt>;
+    consent?: any;
+    key_certs?: KeyCertificate[];
+}
+interface Attempt {
+    credential_id: string;
+    signed_at: string;
+    expires_at: string;
+}
+interface PasskeyStore {
+    /** Marks an enrolment link used. false if it already was: a link works once. */
+    claimToken(nonce: string): Promise<boolean>;
+    tokenUsed(nonce: string): Promise<boolean>;
+    saveEnrolmentChallenge(nonce: string, challenge: string): Promise<void>;
+    enrolmentChallenge(nonce: string): Promise<string | null>;
+    addCredential(c: PasskeyCredential): Promise<void>;
+    credentials(): Promise<PasskeyCredential[]>;
+    /** A new request. */
+    createPending(p: PendingApproval): Promise<void>;
+    pending(id: string): Promise<PendingApproval | null>;
+    /** Adds one ceremony, only while the request is pending. false otherwise. */
+    addAttempt(id: string, challenge: string, a: Attempt): Promise<boolean>;
+    /** pending → approved or refused, exactly once: false if the request was no longer pending.
+     *  The only transition out of pending, so no stale write can undo an approval. */
+    resolvePending(id: string, outcome: {
+        status: 'approved';
+        consent: any;
+        key_certs: KeyCertificate[];
+    } | {
+        status: 'refused';
+    }): Promise<boolean>;
+}
+declare function memoryPasskeyStore(): PasskeyStore;
+/** The same store in Postgres, for an approval service on more than one instance. */
+declare function postgresPasskeyStore(pool: {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+}, opts?: {
+    prefix?: string;
+}): PasskeyStore & {
+    schema: string;
+    migrate(): Promise<void>;
+};
+interface PasskeyApproverOptions {
+    origin: string;
+    roles: string[];
+    registry: CertificateRegistry;
+    /** Certifies passkeys. Certified with `consent:<the roles it may enrol>` and no `approver` term. */
+    enroller: Signer;
+    /** The public key whose signed enrolment links this service honours (an administrator's). */
+    enrolmentAuthority: string;
+    store?: PasskeyStore;
+    /** WebAuthn relying-party id. Default: the origin's hostname. */
+    rpId?: string;
+    rpName?: string;
+    /** How long a passkey's certificate is valid. Default 365 days. */
+    certificateDays?: number;
+    /** List the people who may approve, by name and device, on the approval page. Default false: the
+     *  approval link goes to the carrier, which is not trusted with your roster, so the person types
+     *  their approver id and is shown only their own devices. */
+    listApprovers?: boolean;
+    /** Called for every new request, e.g. to notify the people who can approve it (email, chat). */
+    onPending?: (request: {
+        id: string;
+        role: string;
+        act: any;
+        approvalUrl: string;
+    }) => void | Promise<void>;
+    now?: () => Date;
+}
+declare function passkeyApprover(o: PasskeyApproverOptions): {
+    store: PasskeyStore;
+    fetch: (request: Request) => Promise<Response>;
+    express: () => (req: any, res: any, next?: () => void) => Promise<any>;
+    node: () => (req: any, res: any, next?: () => void) => Promise<any>;
+};
+
+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 pool carriers select from (SPEC-009 0.2.0 §3.2, §6.5): at least the certificates for your
+     *  sealing keys. May hold more than 20. A function is read on every request, so a certificate
+     *  registry can change it without a restart. */
+    keyCerts: KeyCertificate[] | (() => KeyCertificate[] | Promise<KeyCertificate[]>);
+    /** Your signed revocation list (SPEC-007 rev. 1.10 §5.3), served at /nomos/revocations and
+     *  advertised as revocations_url. */
+    revocations?: () => RevocationList | Promise<RevocationList>;
+    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;
+    resolveDocument: () => Promise<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>;
+    /** The certificates connecting your key toward the roots, returned with every statement
+     *  (SPEC-009 0.2.0 §4) so the issuer document need not list them. */
+    keyCerts?: KeyCertificate[];
+    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[];
+    /** The certificates connecting the person's key toward the roots, returned with every consent
+     *  (SPEC-009 0.2.0 §5) so the issuer document need not list every approver. */
+    keyCerts?: KeyCertificate[];
+    /** '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 CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, approver, buildAct, can, certificateRegistry, certify, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, verifyChain, verifyEnrolmentToken, witness };