@zanii/blackbox 0.1.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

@@ -76,6 +76,16 @@ export interface FlightPlan {
 }
 /** Audit S17: what the gateway says about this session right now (GET /v1/sessions/:id/state). */
 /** What `land()` found (spec/findings.md §5). */
+export interface EgressCheck {
+    url: string;
+    /** The request got any answer: the agent can reach the internet around the gateway. */
+    open: boolean;
+}
+/** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
+export declare function checkEgress(options?: {
+    url?: string;
+    timeoutMs?: number;
+}): Promise<EgressCheck>;
 export interface LandingResult {
     /** Only a `satisfied` verdict lands: `unverified` never counts as a pass. */
     landed: boolean;
@@ -115,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 {
@@ -142,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;
@@ -149,6 +166,15 @@ export declare class BlackboxSession {
         ok?: boolean;
         [key: string]: unknown;
     }): void;
+    /** spec/data.md §7: a subject's consent for a purpose. The subject is fingerprinted at capture,
+     *  so it must be an identifier the deployment knows (an e-mail, an Emirates ID, a pack's own). */
+    consent(subject: string, purpose: string, granted: boolean): void;
+    /** spec/data.md §6: tries the internet directly, outside the gateway, and records the answer.
+     *  `open: true` means the gateway isn't the only way out (EGRESS_OPEN). */
+    egressCheck(options?: {
+        url?: string;
+        timeoutMs?: number;
+    }): Promise<EgressCheck>;
     llmCall(ids: LlmCallIds): void;
     note(text: string): void;
     /** Files the flight plan (spec/findings.md §5), unless one was filed when the session opened. */
@@ -196,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

@@ -7,6 +7,17 @@ import { request as httpsRequest } from "node:https";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { attest, isReadOnly } from "../attest/index.js";
+/** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
+export async function checkEgress(options = {}) {
+    const url = options.url ?? "https://example.com";
+    try {
+        await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(options.timeoutMs ?? 5000) });
+        return { url, open: true };
+    }
+    catch {
+        return { url, open: false };
+    }
+}
 const TYPE = /^[a-z][a-z0-9_.]{0,63}$/;
 /** N4 (idea R6): a caller's logical id for an event, so a re-sent one is recorded as a duplicate. */
 const EVENT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
@@ -19,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. */
@@ -159,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++;
@@ -181,6 +214,18 @@ export class BlackboxSession {
     toolResult(name, result) {
         this.event("tool.result", name, result);
     }
+    /** spec/data.md §7: a subject's consent for a purpose. The subject is fingerprinted at capture,
+     *  so it must be an identifier the deployment knows (an e-mail, an Emirates ID, a pack's own). */
+    consent(subject, purpose, granted) {
+        this.event("consent", granted ? "granted" : "withdrawn", { subject, purpose });
+    }
+    /** spec/data.md §6: tries the internet directly, outside the gateway, and records the answer.
+     *  `open: true` means the gateway isn't the only way out (EGRESS_OPEN). */
+    async egressCheck(options = {}) {
+        const result = await checkEgress(options);
+        this.event("egress_check", result.open ? "open" : "closed", { url: result.url });
+        return result;
+    }
     llmCall(ids) {
         this.event("llm.call", ids.provider, { ...ids });
     }
@@ -268,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;
+}