signafaide 0.0.0-stage → 0.2.1

package/dist/core-BMfko_ex.d.ts

@@ -0,0 +1,590 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme (JCS).
+ *
+ * Numbers use ECMAScript Number serialization, object keys are sorted by UTF-16
+ * code units, strings are escaped like JSON.stringify. Lone surrogates, NaN and
+ * Infinity are rejected. Object properties whose value is `undefined` are skipped,
+ * as in JSON. Values the SDK signs itself also pass `assertPortableNumbers` (SPEC §1).
+ */
+/**
+ * A number literal that a plain JS number would misrepresent, from {@link parseJson}:
+ * an integer literal beyond ±(2^53−1) (JCS rejects it, as Rust and Python do), or a float
+ * literal with an integral value such as `1.0` (JCS writes the double; schema checks
+ * that need an integer reject it, as Rust and Python do).
+ */
+declare class JsonNumber {
+    readonly text: string;
+    readonly value: number;
+    readonly unsafeInteger: boolean;
+    constructor(text: string, value: number, unsafeInteger: boolean);
+    toJSON(): number;
+}
+declare function canonicalize(value: unknown): string;
+declare function canonicalBytes(value: unknown): Uint8Array;
+/**
+ * SPEC §1: JavaScript cannot see literals, so content it canonicalizes itself must not
+ * hold integer-valued numbers with 2^53 <= |x| < 1e21 (JSON.stringify writes them as
+ * integer literals, which other implementations reject). Throws on the first one.
+ */
+declare function assertPortableNumbers(value: unknown): void;
+/**
+ * Parse JSON keeping what each number literal was (SPEC §1): integer literals beyond
+ * ±(2^53−1) and integral float literals become {@link JsonNumber}; every other number is a
+ * plain number. Verifiers parse packs with this, so they judge literals like Rust and Python.
+ * NaN, Infinity and trailing text are rejected, as in JSON.parse.
+ */
+declare function parseJson(text: string): any;
+
+/** Hashes, domain-separated Ed25519 and RFC 6962 Merkle proofs (SPEC §1, §3.2). */
+declare const DOMAINS: readonly ["record", "batch", "head", "anchor", "register", "rotate", "agent_key", "export", "draft"];
+type Domain = (typeof DOMAINS)[number];
+declare function sha256Hex(data: Uint8Array): string;
+/** sha256(JCS(value)) as 64 lowercase hex. */
+declare function hashJson(value: unknown): string;
+/** A fresh content salt (SPEC §2.1): 16 random bytes as 32 lowercase hex. */
+declare function newSalt(): string;
+/** sha256(salt || JCS(content)) as 64 lowercase hex (SPEC §2.1); content is a JSON object. */
+declare function contentHash(content: unknown, salt: string): string;
+/** The §2.3 content rule: `content` and `salt` together or not at all. Returns null when they
+ * match `expected` (or are both absent); throws when they cannot be checked; returns the actual
+ * hash on a mismatch. */
+declare function checkContent(content: unknown, salt: unknown, expected: string): string | null;
+declare function b64url(data: Uint8Array): string;
+declare function b64urlDecode(s: string): Uint8Array;
+/** First 16 hex characters of SHA-256 of the raw 32-byte public key. */
+declare function keyId(publicKey: Uint8Array): string;
+declare function signedMessage(domain: Domain, hashHex: string): Uint8Array;
+/** An Ed25519 private key. Only `sign` touches the private half. */
+declare class SigningKey {
+    #private;
+    readonly publicKey: Uint8Array;
+    readonly keyId: string;
+    constructor(seed: Uint8Array);
+    static generate(random?: (n: number) => Uint8Array): SigningKey;
+    seed(): Uint8Array;
+    /** base64url Ed25519 signature over `signafaide/v1/<domain>\n` + raw hash. */
+    sign(domain: Domain, hashHex: string): string;
+}
+declare function verifySig(publicKeyB64: string, domain: Domain, hashHex: string, sigB64: string): boolean;
+declare function leafHash(hashHex: string): Uint8Array;
+/** Root of the RFC 6962 tree over `hashes` (hex). */
+declare function merkleRoot(hashes: string[]): string;
+/** Audit path for leaf `index`, from the leaf upward (hex). */
+declare function auditPath(hashes: string[], index: number): string[];
+/** RFC 9162 §2.1.3.2 inclusion check of `hashHex` at `index` in a tree of `size`. */
+declare function verifyInclusion(hashHex: string, index: unknown, size: unknown, path: unknown, rootHex: unknown): boolean;
+
+/** Envelopes and signed records (SPEC §2). */
+
+type Kind = "decision" | "outcome" | "note";
+declare const AGENT_RE: RegExp;
+interface Envelope {
+    v: 1;
+    kind: Kind;
+    project: string;
+    env: "test" | "live";
+    agent: string;
+    seq: number;
+    prev: string | null;
+    time: string;
+    name: string;
+    content_hash: string;
+    ref: string | null;
+}
+interface SignedRecord {
+    envelope: Envelope;
+    key_id: string;
+    sig: string;
+    /** A draft (§8): the envelope has no project and env yet; `sig` is over domain `draft`. */
+    draft?: true;
+    store_content?: boolean;
+    content?: Record<string, unknown>;
+    /** The content's salt (§2.1): kept with the content, sent only with stored content. */
+    salt?: string;
+    receipt?: Receipt;
+}
+interface Receipt {
+    record_hash: string;
+    index: number;
+    proof: string[];
+    batch: Record<string, any>;
+    batch_hash: string;
+    batch_sig: string;
+    service_key_id: string;
+    head: Record<string, any>;
+    head_sig: string;
+}
+/** Current time as RFC 3339 UTC with milliseconds. */
+declare function now(): string;
+/** §2.2 monotonic time: the machine's clock (`wall`), raised to the previous record's time in
+ * the chain and to the signing key's valid_from when it reads earlier (an NTP step back, a VM
+ * resumed). Returns [time, raised]. When raised, the SDK keeps `wall` in the content's
+ * `meta.wall_time`. A chain written this way never goes back in time. */
+declare function clampTime(wall: string, prev?: string | null, validFrom?: string | null): [string, boolean];
+/** `content` with the clock's own reading kept in `meta.wall_time` (when the record's time was raised). */
+declare function withWallTime(content: Record<string, unknown>, wall: string): Record<string, unknown>;
+declare function validTime(s: unknown): boolean;
+/** Turn a folder or free-form name into a valid agent id. */
+declare function agentName(raw: string): string;
+/** `prj_` + a 26-character ULID in Crockford base32. */
+declare function validProjectId(s: unknown): boolean;
+/** Schema problems with a receipt (§3.4): exact fields and types; signatures are only
+ * checked to be strings (their validity is checks 6 and 8). */
+declare function receiptErrors(rc: unknown): string[];
+/** Schema problems with an envelope; empty when valid (§2.2). */
+declare function envelopeErrors(env: unknown, fields?: readonly string[]): string[];
+/** Schema problems with a signed record (§2.3); `receipt` is allowed. */
+declare function recordErrors(rec: unknown): string[];
+interface RecordFields {
+    kind: Kind;
+    project: string;
+    env: "test" | "live";
+    agent: string;
+    seq: number;
+    prev: string | null;
+    name: string;
+    content: Record<string, unknown>;
+    ref?: string | null;
+    time?: string;
+    /** The content salt (§2.1); a fresh random one when not given. */
+    salt?: string;
+}
+/** Build and sign `{envelope, key_id, sig, content, salt}`: the content hash is salted (SPEC
+ * §2.1). Throws on a bad envelope or on content numbers other implementations could not re-read
+ * (SPEC §1). */
+declare function makeRecord(key: SigningKey, f: RecordFields): SignedRecord;
+declare function recordHash(rec: {
+    envelope: unknown;
+}): string;
+/** The record as sent to the service: content and its salt only when stored there (§2.3). */
+declare function wireRecord(rec: SignedRecord, storeContent: boolean): SignedRecord;
+/** A draft (§8) for a chain whose project is not known yet (no API key, or the key's project
+ * not learned): the envelope without project and env, signed by the agent's key over domain
+ * `draft`, so a local chain verifies before anything is sent. `recordHash` of a draft is its
+ * draft hash. */
+declare function makeDraft(key: SigningKey, f: Omit<RecordFields, "project" | "env">, storeContent: boolean): SignedRecord;
+/** Schema problems with a draft line (§8); empty when valid. */
+declare function draftErrors(rec: unknown): string[];
+/** The signed record for a draft once its project is known (§8). */
+declare function signDraft(key: SigningKey, draft: SignedRecord, project: string, env: "test" | "live", prev: string | null, ref: string | null, seq?: number): SignedRecord;
+/** A service key (§5) or, with `agent`, a pack's agent key: exact fields, valid times. */
+declare function keyEntryErrors(k: unknown, agent?: boolean): string[];
+declare function registration(project: string, env: string, agent: string, publicKey: string, validFrom: string): {
+    project: string;
+    env: string;
+    agent: string;
+    public_key: string;
+    valid_from: string;
+};
+interface AgentKeyEntry {
+    agent: string;
+    key_id: string;
+    public_key: string;
+    valid_from: string;
+    /** When a retired key was retired (the service's time, §2.4); null for a current key. */
+    valid_to: string | null;
+    sig: string;
+}
+/** A self-signed agent-key manifest entry (§2.5). */
+declare function manifestEntry(agent: string, key: SigningKey, validFrom: string, validTo?: string | null): AgentKeyEntry;
+/** Problems with an agent-key manifest (§2.5), self-signatures included. */
+declare function manifestErrors(doc: any): string[];
+
+/** Minimal JSON client for the signafAIde HTTP API (SPEC §6). Built-in fetch only. */
+/** The hosted witness. Configurable with SIGNAFAIDE_URL (a self-hosted witness, or a local dev
+ * server such as http://127.0.0.1:7474); a release test fails if this is ever a loopback address. */
+declare const DEFAULT_URL = "https://api.signafaide.co.uk";
+/** A response, as the transport hands it to the client. */
+interface TransportResponse {
+    status: number;
+    contentType: string;
+    text: string;
+}
+/** How a request is made. The default is `fetch`; the Node runtime passes one whose idle
+ * sockets do not keep the process alive. `signal` aborts it. */
+type Transport = (req: {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<TransportResponse>;
+/**
+ * An error from the service or the SDK. `message` is the one-sentence fix.
+ * `code` is the service error code (`chain_conflict`, `invalid_key`...), or
+ * `network` when the service could not be reached.
+ */
+declare class SignafaideError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly docs?: string;
+    readonly body: Record<string, any>;
+    constructor(message: string, opts?: {
+        code?: string;
+        status?: number;
+        docs?: string;
+        body?: Record<string, any>;
+    });
+    get retryable(): boolean;
+    /** The service refused for a reason retrying cannot change (quota, key, revoked agent key...). */
+    get permanent(): boolean;
+}
+declare class Client {
+    readonly apiKey?: string | undefined;
+    readonly timeoutMs: number;
+    readonly url: string;
+    readonly clientId: string;
+    readonly transport: Transport;
+    readonly signal?: AbortSignal;
+    constructor(url?: string, apiKey?: string | undefined, timeoutMs?: number, clientId?: string, opts?: {
+        transport?: Transport;
+        signal?: AbortSignal;
+        timeoutLabel?: string;
+    });
+    /** Said instead of "no answer within <timeout> s" when the request shares a larger limit. */
+    readonly timeoutLabel?: string;
+    request(method: string, path: string, opts?: {
+        body?: unknown;
+        auth?: boolean;
+        query?: Record<string, string | undefined>;
+    }): Promise<any>;
+    sandbox(): Promise<{
+        project: string;
+        api_key: string;
+        claim_url: string;
+        free_quota: number;
+        terms_url?: string;
+        privacy_url?: string;
+    }>;
+    /** §2.4: the registration with its proof of possession (and rotation signature). */
+    registerAgent(name: string, publicKey: string, validFrom: string, proof: string, rotation?: {
+        key_id: string;
+        sig: string;
+    }): Promise<{
+        agent: string;
+        key_id: string;
+        retired?: {
+            key_id: string;
+            valid_to: string;
+        }[];
+    }>;
+    /** `{project, env}` of this API key (§6). */
+    project(): Promise<{
+        project: string;
+        env: string;
+        claimed?: boolean;
+        name?: string | null;
+    }>;
+    submit(records: unknown[]): Promise<{
+        receipts: any[];
+        heads: any[];
+    }>;
+    head(agent: string): Promise<any>;
+    /** `{record, receipt, anchor}` of one record of the key's project. */
+    record(recordHash: string): Promise<any>;
+    /** A verification pack (§7) of the whole project, or of one agent. */
+    export(agent?: string, from?: string, to?: string): Promise<any>;
+    usage(): Promise<{
+        period: string;
+        used: number;
+        quota: number | null;
+        plan?: string;
+    }>;
+    /** Usage event (`verify`, `export`). Not part of SPEC §6 yet. */
+    event(name: string): Promise<void>;
+    serviceKeys(): Promise<{
+        keys: any[];
+    }>;
+}
+/** GET a JSON document (used for `--keys <url>`). */
+declare function fetchJson(url: string, timeoutMs?: number): Promise<any>;
+
+declare const MAX_PROOF_BYTES = 65536;
+declare const MAX_NODES = 1024;
+type Attestation = ({
+    kind: "bitcoin";
+    height: number;
+} | {
+    kind: "pending";
+    uri: string;
+} | {
+    kind: "unknown";
+    tag: string;
+}) & {
+    msg: Uint8Array;
+};
+/** Digest and attestations of a detached proof. Throws on a malformed proof. */
+declare function parseOts(data: Uint8Array): {
+    digest: string;
+    attestations: Attestation[];
+};
+/** Digest and lowest attested block height (null while pending). Throws for a
+ * malformed proof or one with no attestation at all. */
+declare function otsStatus(data: Uint8Array): {
+    digest: string;
+    height: number | null;
+};
+/** (height, Merkle root hex in header byte order) of each block attestation. */
+declare function blockAttestations(data: Uint8Array): [number, string][];
+
+/**
+ * Public-timestamp confirmation for §7 check 11: the raw 80-byte header of a block from an
+ * Esplora-style explorer API (`GET {base}/block-height/{h}`, then `GET {base}/block/{hash}/header`).
+ * mempool.space and blockstream.info serve this API. The header is trusted only when it hashes to
+ * that block hash and meets its own proof of work (`checkHeader`). Uses built-in fetch; no
+ * redirects. An explorer over plain http is never asked: anyone on the path could answer.
+ */
+declare const DEFAULT_TIMESTAMP_URL = "https://mempool.space/api";
+/** A block as an explorer serves it: its hash (display hex) and raw header (hex). */
+interface BlockHeader {
+    hash: string;
+    header: string;
+}
+/** height -> [fetched, the block header | why it could not be fetched] */
+type BlockRoots = Map<number, [true, BlockHeader] | [false, string]>;
+/** The target of a compact `nBits`; null when it is negative, zero or overflows. */
+declare function target(bits: number): bigint | null;
+/** The Merkle root (header byte order, hex) of a header that hashes to `hash` (display hex) and
+ * meets its own proof of work. Throws saying why the header is not trusted. */
+declare function checkHeader(hash: string, headerHex: string): string;
+/** The hash and raw header of block `height` as the explorer serves them. Throws with the reason. */
+declare function blockHeader(base: string, height: number, timeoutMs?: number): Promise<BlockHeader>;
+/** Look up every height; a failure is kept with its reason (the check then says NOT CHECKED).
+ * A plain-http explorer is not asked. */
+declare function lookupTimestamps(base: string, heights: number[]): Promise<BlockRoots>;
+/** The `bitcoin` object of a test vector: height -> {hash, header}. */
+declare function rootsFromVector(m: Record<string, unknown>): BlockRoots;
+
+/**
+ * The §7 verifier, in pure TypeScript (runs in Node, browsers and edge runtimes).
+ * Same check ids, statuses, text and JSON as the reference verifier (`signafaide-verify`).
+ *
+ * The drand BLS12-381 signature (check 9) is verified only when a `drand` verifier is
+ * passed; `loadDrandVerifier()` builds one from `@noble/curves` (a dependency).
+ * Without it the check is "not checked", never "pass".
+ */
+
+declare const CHECKS: readonly [readonly ["schema", "Envelope schema"], readonly ["record_hash", "Record hashes"], readonly ["record_sig", "Client signatures"], readonly ["chain", "Agent chains"], readonly ["merkle", "Merkle proofs"], readonly ["batch_sig", "Batch hashes and signatures"], readonly ["batch_chain", "Batch chain"], readonly ["head_sig", "Signed heads"], readonly ["drand", "drand rounds"], readonly ["anchor", "Anchors"], readonly ["ots", "OpenTimestamps"], readonly ["content", "Content hashes"]];
+/** Check 3 without independent agent keys (§7). */
+declare const NOT_INDEPENDENT = "NOT INDEPENDENT: agent keys came from the pack; pass --agent-keys <file|url> (the customer's `signafaide keys export`), or --trust-embedded-agent-keys";
+/** The highest drand round whose publication time is a protocol time (year 9999 at most). */
+declare const MAX_ROUND: number;
+/** A batch is anchored within this time of its server_time (§4); an older batch no anchor covers is "not timestamped". */
+declare const ANCHOR_WINDOW_MS = 7200000;
+/** Where keys came from, when not from an independent source (§7 result line). */
+type KeySource = "independent" | "taken from the pack" | "fetched over plain http";
+interface PackFilter {
+    agents: string[] | null;
+    from: string | null;
+    to: string | null;
+}
+type CheckId = (typeof CHECKS)[number][0];
+/** `pending`: ran, found nothing wrong, and waits for an anchor or public timestamp not confirmed yet (§7); never counted as passed. */
+type Status = "pass" | "fail" | "not_checked" | "pending";
+interface Failure {
+    item: string;
+    message: string;
+}
+interface Check {
+    n: number;
+    id: CheckId;
+    title: string;
+    status: Status;
+    checked: number;
+    detail: string;
+    value?: string;
+    failures: Failure[];
+}
+interface KeyDoc {
+    key_id: string;
+    public_key: string;
+    valid_from?: string | null;
+    valid_to?: string | null;
+    agent?: string;
+}
+interface DrandBeacon {
+    chain: string;
+    round: number;
+    randomness: string;
+    signature: string;
+}
+/** Verifies a quicknet beacon's BLS signature over its round. */
+type DrandVerifier = (beacon: DrandBeacon) => boolean;
+/** No independent service keys and `trustEmbeddedKeys` not set: an input error (exit 2). */
+declare class KeysRequired extends Error {
+    name: string;
+}
+/** What a pack covers (§7 result line): `export of every agent, all records, generated <t>`. */
+declare function scopeText(filter: PackFilter, generated: string): string;
+/** How many checks passed, failed, are pending and were not checked (§7 result line). */
+declare function countsText(checks: {
+    id: string;
+    status: Status;
+}[], nothingCosigned?: boolean): string;
+/** `PASS` or `FAIL`; on PASS, why keys were not independent; then how many checks ran and what
+ * the pack covers (§7). */
+declare function resultLine(result: string, service?: KeySource, agent?: KeySource, byService?: boolean, scope?: string | null, counts?: string): string;
+/** A record's content held locally (`--content`), with its salt when the file has one. */
+interface LocalContent {
+    content: Record<string, unknown>;
+    salt: string | undefined;
+}
+interface ReportScope {
+    generated: string;
+    filter: PackFilter;
+    sources: [KeySource, KeySource];
+    byService: boolean;
+}
+declare class Report {
+    readonly checks: Check[];
+    readonly project: string | null;
+    readonly env: string | null;
+    readonly records: number;
+    readonly warnings: string[];
+    readonly notes: string[];
+    readonly independent: {
+        service_keys: boolean;
+        agent_keys: boolean;
+    };
+    readonly scope: ReportScope | null;
+    /** Lines shown after the checks, before the result line: for local state, what still needs
+     * the witness (co-signature, public timestamp). */
+    readonly after: string[];
+    /** Local state with no record co-signed yet: the result line says so (§7). */
+    nothingCosigned: boolean;
+    /** Local state: chains that cannot ship (refused by the witness, or wedged here), as
+     * `<chain>: <reason>`. Any makes the result BLOCKED, which always fails (§7). */
+    readonly blocked: string[];
+    /** Local state with --fail-on-pending-send: records not co-signed yet, which then fail. */
+    notSent: number;
+    /** The project's name from the signed export statement, when the pack has one. */
+    projectName: string | null;
+    constructor(checks: Check[], project?: string | null, env?: string | null, records?: number, warnings?: string[], notes?: string[], independent?: {
+        service_keys: boolean;
+        agent_keys: boolean;
+    }, scope?: ReportScope | null);
+    /** e.g. `PASS: export of every agent, all records, generated <t>`, or
+     * `PASS (agent keys taken from the pack, not independent): export of ...` (§7). */
+    get resultLine(): string;
+    get ok(): boolean;
+    get result(): "PASS" | "FAIL" | "BLOCKED";
+    check(id: CheckId): Check;
+    firstFailed(): CheckId | null;
+    lines(): string[];
+    toString(): string;
+    toJSON(): object;
+}
+/** Service keys from `{"keys": [...]}` (the well-known document) or a bare list. */
+declare function parseServiceKeys(doc: unknown): KeyDoc[];
+/** The customer's agent-key manifest (§2.5); every entry's self-signature is checked. */
+declare function parseAgentKeys(doc: unknown): AgentKeyEntry[];
+interface SignedHeadDoc {
+    head: {
+        project: string;
+        env: string;
+        agent: string;
+        seq: number;
+        record_hash: string;
+        server_time: string;
+    };
+    head_sig: string;
+}
+/** The client's head file (§8 `head.json`) as a list of signed heads. */
+declare function parseHeadFile(doc: unknown): SignedHeadDoc[];
+/** record_hash -> content from JSON lines, or a JSON array, of `{envelope, content}` (§7). */
+declare function contentFromText(text: string, into?: Map<string, LocalContent>): Map<string, LocalContent>;
+/** The block heights the pack's public timestamps claim, to look up before verifying. */
+declare function timestampHeights(pack: any): number[];
+interface PackOptions {
+    trustEmbeddedKeys?: boolean;
+    /** The customer's agent-key manifest entries (`--agent-keys`, §2.5). */
+    agentKeys?: AgentKeyEntry[] | {
+        agent: string;
+        key_id: string;
+        public_key: string;
+        valid_from: string;
+    }[] | null;
+    trustEmbeddedAgentKeys?: boolean;
+    /** The client's head file (`--head`). */
+    heads?: SignedHeadDoc[] | null;
+    /** Block headers looked up for the public timestamps; null/undefined: offline. */
+    timestamps?: BlockRoots | null;
+    /** record_hash -> content, e.g. from the local chain. */
+    contents?: Map<string, LocalContent>;
+    drand?: DrandVerifier | null;
+    /** The service keys came over plain http from this machine (warned; not independent). */
+    serviceKeysPlainHttp?: boolean;
+    /** The agent keys came over plain http from this machine (warned; not independent). */
+    agentKeysPlainHttp?: boolean;
+    /** The service checks its own pack with its own key registry (never independent). */
+    byService?: boolean;
+}
+/** `records_hash` (§7): sha256(JCS(list)) of every record's `receipt.record_hash`, in pack order. */
+declare function recordsHash(records: any[]): string;
+/** The export statement the service signs (§7, domain `export`). */
+declare function exportStatement(pack: any): object;
+/** True for `http://localhost` and loopback addresses: the only hosts plain http is accepted from. */
+declare function isLoopbackUrl(url: string): boolean;
+/** Verify a pack. Throws `KeysRequired` when `serviceKeys` is null and embedded keys are not
+ * trusted. Parse pack text with `parseJson` (not JSON.parse) so number literals are judged as written. */
+declare function verifyPack(pack: any, serviceKeys: KeyDoc[] | null, opts?: PackOptions): Report;
+interface LocalInput {
+    records: any[];
+    /** The chain id (`<project>/<env>/<agent>`) of each record. */
+    chainIds: string[];
+    agentKeys: KeyDoc[];
+    /** Newest signed head per chain id. */
+    heads: Record<string, {
+        head: any;
+        head_sig: string;
+    }>;
+    /** Drafts waiting for the project (§8): not a reason for "no records". */
+    drafts?: number;
+    /** Per chain id, the witness's signed head the chain continues after (§8: a chain this
+     * machine started on an empty disk). */
+    bases?: Record<string, {
+        head: any;
+        head_sig: string;
+        stop?: any;
+    }>;
+}
+/** Verify local state chain by chain. Unshipped records are fine; a chain must be
+ * complete from seq 1 and reach the newest signed head. */
+declare function verifyLocalState(local: LocalInput, serviceKeys: KeyDoc[], drand?: DrandVerifier | null, serviceKeysPlainHttp?: boolean): Report;
+/** `keys_hash` (§4): service keys with `valid_from <= created`, as `{key_id, public_key, valid_from}`,
+ * ordered by `valid_from` then `key_id`. */
+declare function serviceKeysHash(keys: KeyDoc[], createdMs: number): string;
+/** §3.1: why `serverMs` does not fit drand round `round`, or null. */
+declare function checkRoundTime(serverMs: number, round: number): string | null;
+/** A drand quicknet verifier from `@noble/curves`, or null when that dependency is missing
+ * (a pruned install); the drand check then says `DRAND_NOT_CHECKED`. */
+declare function loadDrandVerifier(): Promise<DrandVerifier | null>;
+
+/**
+ * The `X-Signafaide-Client` header and usage events.
+ *
+ * Sent: the SDK name and version, the runtime and its version, the framework adapter
+ * in use, the coding agent that set the project up, and how the request was made
+ * (sdk, cli or mcp). CLI `verify` and `export` also send one event naming the command.
+ * Never sent: content, file paths, hostnames or user names.
+ * `SIGNAFAIDE_TELEMETRY=0` drops the adapter, the agent, the strict flag and the events.
+ */
+declare const HEADER = "X-Signafaide-Client";
+type Env = Record<string, string | undefined>;
+/** The coding agent whose environment this is, or `unknown`. */
+declare function detectAgent(env?: Env): string;
+declare function telemetryEnabled(env?: Env): boolean;
+/** `signafaide-js/<v> (node <v>; adapter=<a>; agent=<a>; via=<v>[; strict=1])`; with
+ * telemetry off, adapter, agent and strict are left out. */
+declare function clientHeader(opts?: {
+    via?: string;
+    adapter?: string;
+    agent?: string;
+    strict?: boolean;
+    env?: Env;
+}): string;
+
+declare const VERSION = "0.2.1";
+
+export { countsText as $, type AgentKeyEntry as A, type BlockHeader as B, Client as C, DEFAULT_TIMESTAMP_URL as D, type Envelope as E, b64urlDecode as F, blockAttestations as G, HEADER as H, blockHeader as I, JsonNumber as J, type Kind as K, type LocalContent as L, MAX_NODES as M, NOT_INDEPENDENT as N, canonicalBytes as O, type PackFilter as P, canonicalize as Q, type Receipt as R, SigningKey as S, checkContent as T, checkHeader as U, VERSION as V, checkRoundTime as W, clampTime as X, clientHeader as Y, contentFromText as Z, contentHash as _, type SignedRecord as a, detectAgent as a0, draftErrors as a1, envelopeErrors as a2, exportStatement as a3, fetchJson as a4, hashJson as a5, isLoopbackUrl as a6, keyEntryErrors as a7, keyId as a8, leafHash as a9, signedMessage as aA, target as aB, telemetryEnabled as aC, timestampHeights as aD, validProjectId as aE, validTime as aF, verifyInclusion as aG, verifyLocalState as aH, verifyPack as aI, verifySig as aJ, wireRecord as aK, withWallTime as aL, loadDrandVerifier as aa, lookupTimestamps as ab, makeDraft as ac, makeRecord as ad, manifestEntry as ae, manifestErrors as af, merkleRoot as ag, newSalt as ah, now as ai, otsStatus as aj, parseAgentKeys as ak, parseHeadFile as al, parseJson as am, parseOts as an, parseServiceKeys as ao, receiptErrors as ap, recordErrors as aq, recordHash as ar, recordsHash as as, registration as at, resultLine as au, rootsFromVector as av, scopeText as aw, serviceKeysHash as ax, sha256Hex as ay, signDraft as az, SignafaideError as b, Report as c, type KeyDoc as d, AGENT_RE as e, ANCHOR_WINDOW_MS as f, type BlockRoots as g, CHECKS as h, type Check as i, type CheckId as j, DEFAULT_URL as k, type Domain as l, type DrandBeacon as m, type DrandVerifier as n, type KeySource as o, KeysRequired as p, MAX_PROOF_BYTES as q, MAX_ROUND as r, type PackOptions as s, type RecordFields as t, type SignedHeadDoc as u, type Status as v, agentName as w, assertPortableNumbers as x, auditPath as y, b64url as z };