@zanii/blackbox 0.2.0 → 0.3.0

package/dist/policy/index.js

@@ -2,6 +2,25 @@
 import { callsOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
 import { checkCompensations } from "../undo/index.js";
+const HINTS = ["read_only", "destructive", "idempotent", "open_world"];
+/**
+ * spec/policy.md §1: a tool's annotations (MCP `readOnlyHint`, `destructiveHint`, `idempotentHint`,
+ * `openWorldHint`) as hints. Missing ones take MCP's defaults: not read-only, destructive, not
+ * idempotent, open-world; destructive and idempotent only mean something for a tool that writes.
+ * An unknown tool gets the defaults too. Hints are the server's word, not proof.
+ */
+export function mcpToolHints(annotations) {
+    const a = (typeof annotations === "object" && annotations !== null ? annotations : {});
+    const readOnly = a.readOnlyHint === true;
+    return {
+        read_only: readOnly,
+        destructive: !readOnly && a.destructiveHint !== false,
+        idempotent: !readOnly && a.idempotentHint === true,
+        open_world: a.openWorldHint !== false,
+    };
+}
+const hintsMatch = (want, have) => want === undefined ||
+    (have !== undefined && Object.entries(want).every(([k, v]) => have[k] === v));
 const MAX_ARGS = 64 * 1024;
 /** Escapes a string for use inside a regular expression. */
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -26,6 +45,15 @@ export function loadPolicy(bytes) {
         }
         if (r.audit !== undefined && typeof r.audit !== "boolean")
             throw new Error(`policy ${r.id}: audit must be true or false`);
+        if (r.hints !== undefined) {
+            const h = r.hints;
+            if (typeof h !== "object" ||
+                h === null ||
+                Array.isArray(h) ||
+                Object.keys(h).length === 0 ||
+                !Object.entries(h).every(([k, v]) => HINTS.includes(k) && typeof v === "boolean"))
+                throw new Error(`policy ${r.id}: hints must set some of read_only, destructive, idempotent, open_world to true or false`);
+        }
     }
     const ids = doc.rules.map((r) => r.id);
     const twice = ids.find((id, i) => ids.indexOf(id) !== i);
@@ -45,7 +73,10 @@ function checkShadowed(rules) {
             .slice(0, j)
             .find((e) => glob(e.tool).test(later.tool) &&
             (e.args_match === undefined ||
-                (e.args_match === later.args_match && !!e.ignore_case === !!later.ignore_case)));
+                (e.args_match === later.args_match && !!e.ignore_case === !!later.ignore_case)) &&
+            (e.hints === undefined ||
+                (later.hints !== undefined &&
+                    Object.entries(e.hints).every(([k, v]) => later.hints[k] === v))));
         if (first && first.action !== later.action)
             throw new Error(`policy ${later.id}: never applies: ${first.id} matches the same calls first (${first.action})`);
     });
@@ -59,12 +90,15 @@ export function compilePolicy(policy) {
             : new RegExp(rule.args_match, rule.ignore_case ? "i" : ""),
     }));
 }
-/** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool has two). */
-export function decide(compiled, names, args) {
+/** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool
+ * has two). `hints`: an MCP tool's annotations; a rule with `hints` never matches a call without. */
+export function decide(compiled, names, args, hints) {
     let text = null;
     for (const c of compiled) {
         if (c.rule.audit === true || !names.some((n) => c.tool.test(n)))
             continue;
+        if (!hintsMatch(c.rule.hints, hints))
+            continue;
         if (c.args) {
             text ??= canonical(args ?? null).slice(0, MAX_ARGS);
             if (!c.args.test(text))
@@ -79,10 +113,11 @@ export function decide(compiled, names, args) {
     return null;
 }
 /** N3 (idea C5): every audit rule this call matches, and what it would do if it were enforced. */
-export function audited(compiled, names, args) {
+export function audited(compiled, names, args, hints) {
     const text = canonical(args ?? null).slice(0, MAX_ARGS);
     return compiled
         .filter((c) => c.rule.audit === true && names.some((n) => c.tool.test(n)))
+        .filter((c) => hintsMatch(c.rule.hints, hints))
         .filter((c) => !c.args || c.args.test(text))
         .map((c) => ({ rule: c.rule.id, would: c.rule.action }));
 }

package/dist/session/index.d.ts

@@ -125,6 +125,8 @@ export interface LlmCallIds {
 }
 /** N4 (idea R6): the same parts always give the same event id (sha256, 128 bits). */
 export declare function stableEventId(...parts: readonly string[]): string;
+/** The image type of a screenshot, by its first bytes: PNG, JPEG or WebP. */
+export declare function imageType(image: Uint8Array): "image/png" | "image/jpeg" | "image/webp" | null;
 /** Opens (or joins) a session. Never throws: on failure it returns a disabled session and logs why. */
 export declare function session(options: SessionOptions): Promise<BlackboxSession>;
 export declare class BlackboxSession {
@@ -152,6 +154,11 @@ export declare class BlackboxSession {
     keepToken?: boolean);
     event(type: string, name?: string, data?: Record<string, unknown>, options?: {
         eventId?: string;
+        /** spec/sdk.md §1.1: an image the event's body is (see `screen`). */
+        attachment?: {
+            contentType: string;
+            bytes: Uint8Array;
+        };
     }): void;
     step(name: string, data?: Record<string, unknown>): void;
     toolCall(name: string, args?: unknown): void;
@@ -215,6 +222,17 @@ export declare class BlackboxSession {
     nearMiss(description: string): void;
     /** spec/attestation.md: re-runs a read-only command and records whether the output matches. */
     attest(argv: string[], claimed: string, cwd?: string, claimedExit?: number): Attestation | undefined;
+    /**
+     * spec/sdk.md §1.1: a computer-use screenshot (PNG, JPEG or WebP, at most 2 MB), recorded as the
+     * body of a `screen` event, so its hash is in the chain. `action` says what the agent did or is
+     * about to do (≤ 500 characters). Mask what mustn't be kept before calling: the image isn't
+     * redacted. One that's too big or not an image is dropped, and the event says why.
+     */
+    screen(image: Uint8Array, options?: {
+        action?: string;
+        width?: number;
+        height?: number;
+    }): void;
     /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
     memoryWrite(memoryId: string, summary?: string): void;
     memoryRevoke(memoryId: string, reason?: string): void;

package/dist/session/index.js

@@ -30,6 +30,20 @@ const MAX_DATA = 64 * 1024;
 const PREVIEW = 4096;
 const BATCH = 500;
 const READ_CHUNK = 4 * 1024 * 1024;
+/** spec/sdk.md §1.1: a screenshot's bytes at most; base64 in its spool line, it stays under READ_CHUNK. */
+const MAX_ATTACHMENT = 2 * 1024 * 1024;
+/** The image type of a screenshot, by its first bytes: PNG, JPEG or WebP. */
+export function imageType(image) {
+    const b = Buffer.from(image.buffer, image.byteOffset, image.byteLength);
+    if (b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return "image/png";
+    if (b.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff])))
+        return "image/jpeg";
+    if (b.subarray(0, 4).toString("latin1") === "RIFF" &&
+        b.subarray(8, 12).toString("latin1") === "WEBP")
+        return "image/webp";
+    return null;
+}
 const LOCK_WAIT_MS = 2_000;
 const LOCK_STALE_MS = 10_000;
 /** Opens (or joins) a session. Never throws: on failure it returns a disabled session and logs why. */
@@ -170,6 +184,14 @@ export class BlackboxSession {
                         ...(eventId === undefined ? {} : { event_id: eventId }),
                         ts: new Date().toISOString(),
                         ...(kept === undefined ? {} : { data: kept }),
+                        ...(options.attachment
+                            ? {
+                                attachment: {
+                                    content_type: options.attachment.contentType,
+                                    data: Buffer.from(options.attachment.bytes).toString("base64"),
+                                },
+                            }
+                            : {}),
                     });
                     appendFileSync(this.spool, `${line}\n`);
                     this.nextSeq++;
@@ -291,6 +313,30 @@ export class BlackboxSession {
         this.event("attestation", argv[0], { ...result });
         return result;
     }
+    /**
+     * spec/sdk.md §1.1: a computer-use screenshot (PNG, JPEG or WebP, at most 2 MB), recorded as the
+     * body of a `screen` event, so its hash is in the chain. `action` says what the agent did or is
+     * about to do (≤ 500 characters). Mask what mustn't be kept before calling: the image isn't
+     * redacted. One that's too big or not an image is dropped, and the event says why.
+     */
+    screen(image, options = {}) {
+        const data = {
+            ...(options.action ? { action: options.action.slice(0, 500) } : {}),
+            ...(Number.isSafeInteger(options.width) ? { width: options.width } : {}),
+            ...(Number.isSafeInteger(options.height) ? { height: options.height } : {}),
+        };
+        const type = imageType(image);
+        if (!type || image.length > MAX_ATTACHMENT) {
+            this.event("screen", undefined, {
+                ...data,
+                attachment_dropped: type
+                    ? `${image.length} bytes, over 2 MB`
+                    : "not a PNG, JPEG or WebP image",
+            });
+            return;
+        }
+        this.event("screen", undefined, data, { attachment: { contentType: type, bytes: image } });
+    }
     /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
     memoryWrite(memoryId, summary) {
         this.event("memory.write", undefined, { memory_id: memoryId, ...(summary ? { summary } : {}) });

package/dist/timestamp/index.d.ts

@@ -0,0 +1,24 @@
+/** A DER TimeStampReq for a SHA-256 digest, asking for the TSA's certificate; with a nonce when given. */
+export declare function timestampRequest(digest: Uint8Array, nonce?: Uint8Array): Uint8Array;
+export interface TimestampReport {
+    ok: boolean;
+    /** ISO-8601, from the token's GeneralizedTime as written. */
+    gen_time: string | null;
+    serial: string | null;
+    policy: string | null;
+    /** SHA-256 of the TSA certificate that signed it. */
+    signer: string | null;
+    /** True when the signer chains to one of the trust anchors given; null when none were given. */
+    chain: boolean | null;
+    problems: string[];
+}
+/**
+ * Checks an RFC 3161 TimeStampResp (or its token, the ContentInfo) offline against the SHA-256
+ * `digest` that was timestamped. `roots`: PEM trust anchors; without them the chain isn't checked
+ * (`chain: null`) and the report says only that the token is well-formed and signed by its own cert.
+ */
+export declare function verifyTimestamp(token: Uint8Array, options: {
+    digest: Uint8Array;
+    nonce?: Uint8Array;
+    roots?: readonly string[];
+}): TimestampReport;

package/dist/timestamp/index.js

@@ -0,0 +1,274 @@
+// RFC 3161 timestamps (spec/timestamp.md): the request a gateway sends a Time-Stamp Authority, and an
+// offline check of the token it gets back: the imprint, the CMS signature (RSA PKCS#1 v1.5 or ECDSA,
+// SHA-256/384/512), the signer certificate (ESSCertID v1 or v2), its timeStamping EKU and validity,
+// and the chain to trust anchors you give. node:crypto only. Mirrors zanii_blackbox/timestamp.py.
+import { createHash, verify as cryptoVerify, X509Certificate } from "node:crypto";
+function parse(buf, depth = 0) {
+    const nodes = parseAll(buf, depth);
+    if (nodes.length !== 1)
+        throw new Error("der: expected one element");
+    return nodes[0];
+}
+function parseAll(buf, depth) {
+    if (depth > 40)
+        throw new Error("der: too deep");
+    const out = [];
+    let at = 0;
+    while (at < buf.length) {
+        const start = at;
+        const tag = buf[at++];
+        if ((tag & 0x1f) === 0x1f)
+            throw new Error("der: high tag numbers aren't used here");
+        let len = buf[at++];
+        if (len === undefined)
+            throw new Error("der: truncated");
+        if (len === 0x80)
+            throw new Error("der: indefinite length");
+        if (len > 0x80) {
+            const n = len & 0x7f;
+            if (n > 4 || at + n > buf.length)
+                throw new Error("der: bad length");
+            len = 0;
+            for (let i = 0; i < n; i++)
+                len = len * 256 + buf[at++];
+        }
+        if (at + len > buf.length)
+            throw new Error("der: truncated");
+        const value = buf.subarray(at, at + len);
+        at += len;
+        const constructed = (tag & 0x20) !== 0;
+        out.push({
+            tag,
+            raw: buf.subarray(start, at),
+            value,
+            children: constructed ? parseAll(value, depth + 1) : [],
+        });
+    }
+    return out;
+}
+/** OID content bytes as dotted text. */
+function oid(n) {
+    if (n.tag !== 0x06)
+        throw new Error("der: expected an OID");
+    const b = n.value;
+    const first = b[0];
+    const parts = [Math.floor(first / 40), first % 40];
+    let v = 0;
+    for (let i = 1; i < b.length; i++) {
+        v = v * 128 + (b[i] & 0x7f);
+        if ((b[i] & 0x80) === 0) {
+            parts.push(v);
+            v = 0;
+        }
+    }
+    return parts.join(".");
+}
+const child = (n, i) => {
+    const c = n?.children[i];
+    if (!c)
+        throw new Error("der: missing element");
+    return c;
+};
+const hex = (b) => Buffer.from(b).toString("hex");
+// ---------------------------------------------------------------- OIDs
+const SIGNED_DATA = "1.2.840.113549.1.7.2";
+const TST_INFO = "1.2.840.113549.1.9.16.1.4";
+const CONTENT_TYPE = "1.2.840.113549.1.9.3";
+const MESSAGE_DIGEST = "1.2.840.113549.1.9.4";
+const SIGNING_CERT = "1.2.840.113549.1.9.16.2.12";
+const SIGNING_CERT_V2 = "1.2.840.113549.1.9.16.2.47";
+const TIME_STAMPING = "1.3.6.1.5.5.7.3.8";
+const HASHES = {
+    "2.16.840.1.101.3.4.2.1": "sha256",
+    "2.16.840.1.101.3.4.2.2": "sha384",
+    "2.16.840.1.101.3.4.2.3": "sha512",
+    "1.3.14.3.2.26": "sha1",
+};
+const SIGNATURES = {
+    "1.2.840.113549.1.1.1": null, // rsaEncryption: the signer's digest algorithm
+    "1.2.840.113549.1.1.11": "sha256",
+    "1.2.840.113549.1.1.12": "sha384",
+    "1.2.840.113549.1.1.13": "sha512",
+    "1.2.840.10045.4.3.2": "sha256",
+    "1.2.840.10045.4.3.3": "sha384",
+    "1.2.840.10045.4.3.4": "sha512",
+};
+// ---------------------------------------------------------------- the request
+const der = (tag, content) => {
+    const n = content.length;
+    const len = n < 0x80 ? [n] : n < 0x100 ? [0x81, n] : [0x82, n >> 8, n & 0xff];
+    return new Uint8Array(Buffer.concat([Buffer.from([tag, ...len]), Buffer.from(content)]));
+};
+/** A DER TimeStampReq for a SHA-256 digest, asking for the TSA's certificate; with a nonce when given. */
+export function timestampRequest(digest, nonce) {
+    if (digest.length !== 32)
+        throw new Error("a SHA-256 digest is 32 bytes");
+    const algId = Buffer.from("300d06096086480165030402010500", "hex");
+    const imprint = der(0x30, new Uint8Array(Buffer.concat([algId, Buffer.from(der(0x04, digest))])));
+    let n = null;
+    if (nonce) {
+        let i = 0;
+        while (i < nonce.length - 1 && nonce[i] === 0)
+            i++;
+        const trimmed = nonce.subarray(i);
+        n = der(0x02, trimmed[0] & 0x80 ? new Uint8Array([0, ...trimmed]) : trimmed);
+    }
+    return der(0x30, new Uint8Array(Buffer.concat([
+        Buffer.from([0x02, 0x01, 0x01]),
+        Buffer.from(imprint),
+        ...(n ? [Buffer.from(n)] : []),
+        Buffer.from([0x01, 0x01, 0xff]),
+    ])));
+}
+const isoOf = (generalized) => {
+    const m = /^([0-9]{4})([0-9]{2})([0-9]{2})([0-9]{2})([0-9]{2})([0-9]{2})(\.[0-9]+)?Z$/.exec(generalized);
+    return m ? `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}${m[7] ?? ""}Z` : null;
+};
+/** The TSTInfo's fields we check. */
+function tstInfo(bytes) {
+    const t = parse(bytes);
+    const imprint = child(t, 2);
+    const genTime = Buffer.from(child(t, 4).value).toString("latin1");
+    let nonce = null;
+    for (const c of t.children.slice(5))
+        if (c.tag === 0x02)
+            nonce = hex(c.value).replace(/^00(?=[0-9a-f]{2})/, "");
+    return {
+        policy: oid(child(t, 1)),
+        hashAlg: oid(child(child(imprint, 0), 0)),
+        hashed: child(imprint, 1).value,
+        serial: hex(child(t, 3).value),
+        genTime,
+        nonce,
+    };
+}
+/**
+ * Checks an RFC 3161 TimeStampResp (or its token, the ContentInfo) offline against the SHA-256
+ * `digest` that was timestamped. `roots`: PEM trust anchors; without them the chain isn't checked
+ * (`chain: null`) and the report says only that the token is well-formed and signed by its own cert.
+ */
+export function verifyTimestamp(token, options) {
+    const report = {
+        ok: false,
+        gen_time: null,
+        serial: null,
+        policy: null,
+        signer: null,
+        chain: null,
+        problems: [],
+    };
+    const fail = (why) => {
+        report.problems.push(why);
+        return report;
+    };
+    try {
+        let top = parse(token);
+        // A TimeStampResp: [PKIStatusInfo, token]; a token: [OID signedData, [0] SignedData]
+        if (child(top, 0).tag === 0x30) {
+            const status = child(child(top, 0), 0).value;
+            if (status.length !== 1 || (status[0] !== 0 && status[0] !== 1))
+                return fail("the TSA didn't grant the timestamp");
+            top = child(top, 1);
+        }
+        if (oid(child(top, 0)) !== SIGNED_DATA)
+            return fail("not a CMS SignedData token");
+        const sd = child(child(top, 1), 0);
+        const encap = child(sd, 2);
+        if (oid(child(encap, 0)) !== TST_INFO)
+            return fail("the token doesn't carry a TSTInfo");
+        const tstBytes = child(child(encap, 1), 0).value;
+        const info = tstInfo(tstBytes);
+        report.gen_time = isoOf(info.genTime);
+        report.serial = info.serial;
+        report.policy = info.policy;
+        if (info.hashAlg !== "2.16.840.1.101.3.4.2.1" || hex(info.hashed) !== hex(options.digest))
+            fail("the token is for another digest");
+        if (options.nonce && info.nonce !== hex(options.nonce).replace(/^(00)+(?=[0-9a-f]{2})/, ""))
+            fail("the nonce isn't the one sent");
+        const certs = sd.children.find((c) => c.tag === 0xa0)?.children.map((c) => c.raw) ?? [];
+        const signerInfos = sd.children.at(-1);
+        if (signerInfos?.tag !== 0x31 || signerInfos.children.length !== 1)
+            return fail("a token has exactly one signer");
+        const si = child(signerInfos, 0);
+        const digestAlg = HASHES[oid(child(child(si, 2), 0))];
+        const attrs = child(si, 3);
+        if (attrs.tag !== 0xa0 || !digestAlg)
+            return fail("the signer's attributes or digest aren't supported");
+        const sigAlgOid = oid(child(child(si, 4), 0));
+        const sig = child(si, 5).value;
+        // signed attributes: contentType, messageDigest over the TSTInfo, and the signing certificate
+        const attr = (id) => attrs.children.find((a) => oid(child(a, 0)) === id);
+        const ct = attr(CONTENT_TYPE);
+        if (!ct || oid(child(child(ct, 1), 0)) !== TST_INFO)
+            fail("the signed content type isn't TSTInfo");
+        const md = attr(MESSAGE_DIGEST);
+        if (!md ||
+            hex(child(child(md, 1), 0).value) !== createHash(digestAlg).update(tstBytes).digest("hex"))
+            fail("the signed message digest isn't the TSTInfo's");
+        const v1 = attr(SIGNING_CERT);
+        const v2 = attr(SIGNING_CERT_V2);
+        let want = null;
+        if (v2) {
+            const id = child(child(child(child(v2, 1), 0), 0), 0); // SigningCertificateV2.certs[0]
+            const first = child(id, 0);
+            want =
+                first.tag === 0x30
+                    ? { alg: HASHES[oid(child(first, 0))] ?? "unknown", hash: hex(child(id, 1).value) }
+                    : { alg: "sha256", hash: hex(first.value) };
+        }
+        else if (v1) {
+            const id = child(child(child(child(v1, 1), 0), 0), 0);
+            want = { alg: "sha1", hash: hex(child(id, 0).value) };
+        }
+        if (!want)
+            return fail("the token doesn't name its signing certificate");
+        const signerDer = certs.find((c) => createHash(want.alg).update(c).digest("hex") === want.hash);
+        if (!signerDer)
+            return fail("the signing certificate isn't in the token");
+        const cert = new X509Certificate(Buffer.from(signerDer));
+        report.signer = createHash("sha256").update(signerDer).digest("hex");
+        // the signature over the DER of the signed attributes, re-tagged as a SET
+        const signed = Buffer.from(attrs.raw);
+        signed[0] = 0x31;
+        if (!(sigAlgOid in SIGNATURES))
+            return fail(`the signature algorithm ${sigAlgOid} isn't supported`);
+        const hashName = SIGNATURES[sigAlgOid] ?? digestAlg;
+        const key = cert.publicKey;
+        const good = key.asymmetricKeyType === "ec"
+            ? cryptoVerify(hashName, signed, { key, dsaEncoding: "der" }, sig)
+            : cryptoVerify(hashName, signed, key, sig);
+        if (!good)
+            fail("the TSA's signature doesn't verify");
+        if (!(cert.keyUsage ?? []).includes(TIME_STAMPING))
+            fail("the signing certificate isn't for time-stamping");
+        const at = report.gen_time ? Date.parse(report.gen_time) : Number.NaN;
+        if (!(Date.parse(cert.validFrom) <= at && at <= Date.parse(cert.validTo)))
+            fail("the signing certificate wasn't valid at the stamped time");
+        if (options.roots?.length)
+            report.chain = chains(cert, certs, options.roots);
+        if (report.chain === false)
+            fail("the signing certificate doesn't chain to a trusted root");
+    }
+    catch {
+        return fail("not a well-formed timestamp");
+    }
+    report.ok = report.problems.length === 0;
+    return report;
+}
+/** Walks issuer links from the signer through the token's certificates to a root (at most 6 hops). */
+function chains(signer, certs, roots) {
+    const anchors = roots.map((r) => new X509Certificate(r));
+    const pool = certs.map((c) => new X509Certificate(Buffer.from(c)));
+    let current = signer;
+    for (let hop = 0; hop < 6; hop++) {
+        if (anchors.some((a) => current.checkIssued(a) && current.verify(a.publicKey)))
+            return true;
+        const next = pool.find((c) => c.fingerprint256 !== current.fingerprint256 &&
+            current.checkIssued(c) &&
+            current.verify(c.publicKey));
+        if (!next)
+            return false;
+        current = next;
+    }
+    return false;
+}

package/dist/transparency/index.d.ts

@@ -0,0 +1,188 @@
+/** A CBOR value: integers, byte and text strings, arrays, maps (Map, for integer keys), tags, null and booleans. */
+export type Cbor = number | string | Uint8Array | boolean | null | Cbor[] | Map<Cbor, Cbor> | {
+    tag: number;
+    value: Cbor;
+};
+export declare const tagged: (tag: number, value: Cbor) => Cbor;
+export declare function cborEncode(v: Cbor): Buffer;
+/** Decodes one deterministic CBOR item; throws on anything else (indefinite lengths, floats, extra bytes). */
+export declare function cborDecode(bytes: Uint8Array): Cbor;
+export declare const ed25519Sign: (seed: Uint8Array, msg: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare function ed25519Verify(publicKey: Uint8Array, msg: Uint8Array, sig: Uint8Array): boolean;
+export declare const ed25519PublicKey: (seed: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare const ALG_ED25519 = -19;
+export interface StatementInput {
+    /** The payload's media type. */
+    contentType: string;
+    payload: Uint8Array;
+    /** CWT claims (RFC 9597): who issued it and what it's about. */
+    iss: string;
+    sub: string;
+    /** Unix seconds. */
+    iat: number;
+    /** The key id (bstr), e.g. the first 8 bytes of SHA-256(public key). */
+    kid: Uint8Array;
+}
+/** A SCITT Signed Statement: tagged COSE_Sign1, Ed25519 (alg -19), empty unprotected header, payload attached. */
+export declare function signStatement(input: StatementInput, seed: Uint8Array): Uint8Array;
+export interface CoseSign1 {
+    protectedBytes: Uint8Array;
+    protected: Map<Cbor, Cbor>;
+    unprotected: Map<Cbor, Cbor>;
+    payload: Uint8Array | null;
+    signature: Uint8Array;
+}
+/** Parses a tagged COSE_Sign1; throws if it isn't one. */
+export declare function parseCoseSign1(bytes: Uint8Array): CoseSign1;
+/** Does a COSE_Sign1 verify with this Ed25519 key? `detached`: the payload, when it isn't attached. */
+export declare function verifyCoseSign1(bytes: Uint8Array, publicKey: Uint8Array, detached?: Uint8Array): boolean;
+/** The bytes a log entry is: the statement with its unprotected header emptied (RFC 9943 §6.3). */
+export declare function statementEntry(statement: Uint8Array): Uint8Array;
+export declare const leafHash: (entry: Uint8Array) => Uint8Array<ArrayBuffer>;
+/** MTH over leaf hashes (already `leafHash`ed). */
+export declare function merkleRoot(leaves: readonly Uint8Array[]): Uint8Array;
+/** The audit path for leaf `m` in a tree of these leaf hashes, leaf to root. */
+export declare function inclusionProof(m: number, leaves: readonly Uint8Array[]): Uint8Array[];
+/** RFC 9162 §2.1.3.2: does `path` prove leaf `index` (its hash) in a tree of `size` with `root`? */
+export declare function verifyInclusion(leaf: Uint8Array, index: number, size: number, path: readonly Uint8Array[], root: Uint8Array): boolean;
+/** RFC 9162 §2.1.4.1: proof that the tree of the first `m` leaves is a prefix of all of them. */
+export declare function consistencyProof(m: number, leaves: readonly Uint8Array[]): Uint8Array[];
+/** RFC 9162 §2.1.4.2, with the trivial cases: an empty first tree, and equal sizes. */
+export declare function verifyConsistency(first: number, second: number, firstRoot: Uint8Array, secondRoot: Uint8Array, proof: readonly Uint8Array[]): boolean;
+export interface ReceiptSigner {
+    iss: string;
+    sub: string;
+    kid: Uint8Array;
+    seed: Uint8Array;
+}
+/** A receipt of inclusion (vds RFC9162_SHA256): signed over the root, payload detached. */
+export declare function makeReceipt(proof: {
+    size: number;
+    index: number;
+    path: readonly Uint8Array[];
+    root: Uint8Array;
+}, signer: ReceiptSigner): Uint8Array;
+/** RFC 9942 §5.2.1: does the receipt prove this entry (the statement, unprotected emptied) under this key?
+ * Returns the tree size and leaf index it proves, or null. Accepts a size-1 tree's empty path. */
+export declare function verifyReceipt(receipt: Uint8Array, entry: Uint8Array, publicKey: Uint8Array): {
+    size: number;
+    index: number;
+} | null;
+/** A Transparent Statement: the statement with its receipts in unprotected header 394. */
+export declare function transparentStatement(statement: Uint8Array, receipts: readonly Uint8Array[]): Uint8Array;
+/** c2sp.org/signed-note: SHA-256(name || "\n" || type || public key)[:4]. Type 0x01 note, 0x04 cosignature. */
+export declare const noteKeyId: (name: string, type: number, publicKey: Uint8Array) => Uint8Array<ArrayBuffer>;
+/** A verifier key string: `name+hex(keyID)+base64(type || public key)`. */
+export declare const noteVkey: (name: string, type: number, publicKey: Uint8Array) => string;
+export declare function parseVkey(vkey: string): {
+    name: string;
+    type: number;
+    keyId: Uint8Array;
+    publicKey: Uint8Array;
+} | null;
+/** Signs a note's text (which ends in "\n") as `name`; returns the note with its signature line. */
+export declare function signNote(text: string, name: string, seed: Uint8Array): string;
+/** Splits a signed note into its text and signature lines. */
+export declare function splitNote(note: string): {
+    text: string;
+    signatures: Array<{
+        name: string;
+        keyId: Uint8Array;
+        sig: Uint8Array;
+    }>;
+} | null;
+/** Is the note signed (type 0x01) by this vkey? */
+export declare function verifyNote(note: string, vkey: string): boolean;
+/**
+ * §9: a log key rotation, as a note signed by the old key and the new one: the new key's vkey, the
+ * tree size it takes over at, and when. A verifier that pinned the old key follows it to the new.
+ */
+export declare function keyRotationNote(old: {
+    seed: Uint8Array;
+    origin: string;
+}, next: {
+    seed: Uint8Array;
+    origin: string;
+}, size: number, time: number): string;
+/** §9: the new key, size and time a rotation note names, if the old key and the new one both signed it. */
+export declare function verifyKeyRotation(note: string, oldVkey: string): {
+    new_vkey: string;
+    size: number;
+    time: number;
+} | null;
+/** c2sp.org/tlog-checkpoint: origin, size, base64 root, each on its own line. */
+export declare const checkpointText: (origin: string, size: number, root: Uint8Array) => string;
+export declare function parseCheckpoint(text: string): {
+    origin: string;
+    size: number;
+    root: Uint8Array;
+} | null;
+/** c2sp.org/tlog-cosignature: the witness's timestamped Ed25519 cosignature (type 0x04) on a checkpoint. */
+export declare function cosign(checkpoint: string, name: string, seed: Uint8Array, time: number): string;
+/** The raw ML-DSA-44 public key (1312 bytes) for a 32-byte seed. Needs Node ≥ 24.6. */
+export declare const mldsaPublicKey: (seed: Uint8Array) => Uint8Array;
+/** Whether this runtime has ML-DSA (Node ≥ 24.6 with OpenSSL ≥ 3.5). */
+export declare function mldsaAvailable(): boolean;
+/** c2sp.org/tlog-cosignature v1.1 (type 0x06): what an ML-DSA-44 subtree cosignature signs. */
+export declare function subtreeMessage(name: string, time: number, origin: string, start: number, end: number, hash: Uint8Array): Uint8Array;
+/** An ML-DSA-44 cosignature line (type 0x06) on a checkpoint: what a log or witness adds for post-quantum. */
+export declare function cosignMldsa(checkpoint: string, name: string, seed: Uint8Array, time: number): string;
+/**
+ * The time a cosignature (in a note's signature lines) says it saw the checkpoint, or null. Takes a
+ * witness's Ed25519 vkey (type 0x04) or an ML-DSA-44 one (type 0x06).
+ */
+export declare function verifyCosignature(note: string, vkey: string): number | null;
+/** c2sp.org/tlog-witness: the body of `POST add-checkpoint`. */
+export declare const addCheckpointBody: (old: number, proof: readonly Uint8Array[], signedCheckpoint: string) => string;
+export declare function parseAddCheckpoint(body: string): {
+    old: number;
+    proof: Uint8Array[];
+    note: string;
+} | null;
+export declare const SESSION_CONTENT_TYPE = "application/vnd.zanii.blackbox.session+json";
+export declare const RECEIPT_SUB = "transparency-log";
+/** spec/transparency.md §1: the first 8 bytes of SHA-256(public key). */
+export declare const logKid: (publicKey: Uint8Array) => Uint8Array<ArrayBuffer>;
+export interface SessionHead {
+    session_id: string;
+    tenant: string;
+    count: number;
+    head: string;
+    closed_at: string;
+}
+/** spec/transparency.md §2: the Signed Statement a closed session gets. `iat` is `closed_at` in seconds. */
+export declare function sessionStatement(head: SessionHead, origin: string, seed: Uint8Array): Uint8Array;
+export interface TransparencyReport {
+    ok: boolean;
+    statement: boolean;
+    receipt: {
+        size: number;
+        index: number;
+    } | null;
+    checkpoint: {
+        origin: string;
+        size: number;
+    } | null;
+    witnessed: string[];
+    /** The RFC 3161 time of the checkpoint (spec/timestamp.md §3), when the bundle carries a token. */
+    timestamp: string | null;
+    /** §8: the checkpoint's ML-DSA-44 signature verifies under `logPqKey`; null when none was given. */
+    pq: boolean | null;
+    problems: string[];
+}
+/**
+ * spec/transparency.md §6: checks a bundle's `transparency` offline, against a log key the verifier
+ * pins (a C2SP vkey, type 0x01) and the witnesses it trusts (vkeys, type 0x04).
+ */
+export declare function verifyTransparency(bundle: {
+    session: {
+        session_id: string;
+    };
+    lines: readonly string[];
+    transparency?: unknown;
+}, options: {
+    logKey: string;
+    witnesses?: readonly string[];
+    tsaRoots?: readonly string[];
+    logPqKey?: string;
+}): TransparencyReport;