signafaide 0.0.0-stage → 0.3.0

package/dist/core-BTJGPYVW.d.cts

@@ -0,0 +1,652 @@
+/**
+ * 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>;
+
+/**
+ * Tool declarations (SPEC §2.6) and the coverage they give (§7): which of an agent's tools are
+ * recorded, read from envelopes alone (kind, name, seq), so it holds for hash-only records.
+ * Pure: no I/O. The same names, rules and wording as the Rust core and the Python SDK.
+ *
+ * Coverage is a note, never a failure, and never a claim of completeness: a declaration is the
+ * client's own signed statement of the tools the agent has.
+ */
+/** The name of the note that starts a new tool declaration for the agent's chain. */
+declare const TOOLS = "signafaide.tools";
+/** `signafaide.tool/<tool name>`: the agent has this tool and calls to it are recorded. */
+declare const TOOL_PREFIX = "signafaide.tool/";
+/** `signafaide.tool_unrecorded/<tool name>`: the agent has this tool and calls to it are not recorded. */
+declare const TOOL_UNRECORDED_PREFIX = "signafaide.tool_unrecorded/";
+/** The longest tool name a declaration holds as it is, in characters (Unicode code points): an
+ * envelope name is at most 128 and the longer prefix takes 27. */
+declare const MAX_DECLARED_NAME = 101;
+/** A tool's name as a declaration holds it: the name itself when it has at most 101 characters,
+ * else its first 92 characters, `~`, and the first 8 hex characters of sha256(UTF-8 tool name).
+ * A name that is already short maps to itself. */
+declare function declaredName(tool: string): string;
+/** The envelope name of the note that declares `tool`. */
+declare function toolNoteName(tool: string, recorded: boolean): string;
+/** What a record says about the agent's tool list, from its kind and name alone: `"header"`,
+ * a tool, or null when it is not a tool-declaration note. */
+declare function toolNote(kind: unknown, name: unknown): "header" | {
+    name: string;
+    recorded: boolean;
+} | null;
+interface DeclaredTool {
+    name: string;
+    recorded: boolean;
+}
+/** What one agent's records show about its tools (§7 tool coverage). */
+interface Coverage {
+    /** The tools of the agent's current declaration, in name order; empty when there is none. */
+    declared: DeclaredTool[];
+    /** The names of decision records that are not in the current declaration, in name order. */
+    undeclared_recorded: string[];
+    /** The seq of the `signafaide.tools` note that starts the current declaration, or null. */
+    declared_at_seq: number | null;
+}
+/** The coverage of one agent's records, given in seq order. The current declaration is the one
+ * started by the last `signafaide.tools` note; tool notes before the first such note belong to a
+ * declaration the records do not hold and are ignored. Inside a declaration a later note for the
+ * same tool replaces an earlier one. A `decision` counts as a recorded tool unless its name
+ * starts with `signafaide.`; it is compared by its declared name. */
+declare function coverage(records: Iterable<{
+    seq: number;
+    kind: unknown;
+    name: unknown;
+}>): Coverage;
+/** The coverage of `agent` in words (§7), one line each: what was declared, then the recorded
+ * tools the declaration does not list. */
+declare function coverageLines(agent: string, c: Coverage): string[];
+
+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;
+    /** Tool coverage per agent (§7; per chain for local state): the agent's current tool
+     * declaration and the recorded tools it does not list. A note, never a failure. */
+    coverage: Record<string, Coverage>;
+    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;
+    /** Tool coverage in words (§7), agent by agent: what each agent declared, then the recorded
+     * tools its declaration does not list. */
+    coverageLines(): string[];
+    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.3.0";
+
+export { checkHeader as $, type AgentKeyEntry as A, type BlockHeader as B, Client as C, DEFAULT_TIMESTAMP_URL as D, type Envelope as E, TOOL_UNRECORDED_PREFIX as F, agentName as G, HEADER as H, assertPortableNumbers as I, JsonNumber as J, type Kind as K, type LocalContent as L, MAX_DECLARED_NAME as M, NOT_INDEPENDENT as N, auditPath as O, type PackFilter as P, b64url as Q, type Receipt as R, SigningKey as S, TOOLS as T, b64urlDecode as U, VERSION as V, blockAttestations as W, blockHeader as X, canonicalBytes as Y, canonicalize as Z, checkContent as _, type SignedRecord as a, checkRoundTime as a0, clampTime as a1, clientHeader as a2, contentFromText as a3, contentHash as a4, countsText as a5, coverage as a6, coverageLines as a7, declaredName as a8, detectAgent as a9, recordHash as aA, recordsHash as aB, registration as aC, resultLine as aD, rootsFromVector as aE, scopeText as aF, serviceKeysHash as aG, sha256Hex as aH, signDraft as aI, signedMessage as aJ, target as aK, telemetryEnabled as aL, timestampHeights as aM, toolNote as aN, toolNoteName as aO, validProjectId as aP, validTime as aQ, verifyInclusion as aR, verifyLocalState as aS, verifyPack as aT, verifySig as aU, wireRecord as aV, withWallTime as aW, draftErrors as aa, envelopeErrors as ab, exportStatement as ac, fetchJson as ad, hashJson as ae, isLoopbackUrl as af, keyEntryErrors as ag, keyId as ah, leafHash as ai, loadDrandVerifier as aj, lookupTimestamps as ak, makeDraft as al, makeRecord as am, manifestEntry as an, manifestErrors as ao, merkleRoot as ap, newSalt as aq, now as ar, otsStatus as as, parseAgentKeys as at, parseHeadFile as au, parseJson as av, parseOts as aw, parseServiceKeys as ax, receiptErrors as ay, recordErrors 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, type Coverage as k, DEFAULT_URL as l, type DeclaredTool as m, type Domain as n, type DrandBeacon as o, type DrandVerifier as p, type KeySource as q, KeysRequired as r, MAX_NODES as s, MAX_PROOF_BYTES as t, MAX_ROUND as u, type PackOptions as v, type RecordFields as w, type SignedHeadDoc as x, type Status as y, TOOL_PREFIX as z };