@zanii/blackbox 0.2.0 → 0.4.0

package/dist/sla/index.js

@@ -0,0 +1,197 @@
+// Service agreements proven from receipts (spec/anchoring.md §14): Zanii's SLA, co-signed terms
+// whose compliance is computed from the provider's consecutive receipt chain, the same verdict for
+// everyone (@zanii/sla). Pure; mirrors sdks/python/src/zanii_blackbox/sla.py; pinned by
+// spec/vectors/sla.json.
+import { canonicalBytes, jcsHash, publicKeyFromDid, receiptHash, scopeCovers, verifyReceipt, } from "@zanii/core";
+import { parseMoney } from "../finance/index.js";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const ms = (ts) => {
+    if (typeof ts !== "string")
+        return null;
+    const t = Date.parse(ts);
+    return Number.isNaN(t) ? null : t;
+};
+const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
+/** Zanii's SLA terms. `commitments` holds at least one of min_actions, max_actions, max_gap_ms. */
+export function buildSlaBody(o) {
+    if (!o.provider || !o.client)
+        throw new Error("provider and client are required");
+    if (o.provider === o.client)
+        throw new Error("provider and client must differ");
+    if (!o.scope)
+        throw new Error("scope is required (the target pattern the service receipts match)");
+    const start = ms(o.window.start);
+    const end = ms(o.window.end);
+    if (start === null || end === null)
+        throw new Error("window start/end must be ISO timestamps");
+    if (start >= end)
+        throw new Error("window start must be before end");
+    if (ms(o.createdAt) === null)
+        throw new Error("created_at must be an ISO timestamp");
+    const c = { ...o.commitments };
+    for (const [k, v] of Object.entries(c))
+        if (v !== undefined && v !== null && !isCount(v))
+            throw new Error(`commitment ${k} must be a non-negative integer`);
+    if (c.min_actions == null && c.max_actions == null && c.max_gap_ms == null)
+        throw new Error("an SLA with no commitments commits to nothing");
+    if (c.min_actions != null && c.max_actions != null && c.min_actions > c.max_actions)
+        throw new Error("min_actions must not exceed max_actions");
+    return {
+        v: 1,
+        type: "sla",
+        provider: o.provider,
+        client: o.client,
+        scope: o.scope,
+        window: { start: o.window.start, end: o.window.end },
+        commitments: c,
+        created_at: o.createdAt,
+        ...(o.price ? { price: parseMoney(o.price.amount, o.price.currency) } : {}),
+        ...(o.ref !== undefined ? { ref: o.ref } : {}),
+    };
+}
+/** One party signs the terms. Collect the provider's and the client's. */
+export const signSla = (body, did, privateKey) => ({
+    did,
+    sig: `ed25519:${Buffer.from(ed25519Sign(privateKey, canonicalBytes(body))).toString("hex")}`,
+});
+export const assembleSla = (body, signatures) => ({
+    body,
+    signatures,
+});
+export const slaHash = (sla) => jcsHash(sla);
+const sigValid = (body, did, sig) => {
+    const pub = publicKeyFromDid(did);
+    const m = typeof sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sig) : null;
+    return Boolean(pub && m && ed25519Verify(pub, canonicalBytes(body), Buffer.from(m[1], "hex")));
+};
+/** Zanii's check: sane terms, and BOTH provider and client signed exactly these. */
+export function verifySla(sla) {
+    const reasons = [];
+    const e = (sla ?? {});
+    const b = e.body ?? {};
+    if (b.v !== 1 || b.type !== "sla")
+        reasons.push("not an sla (v1)");
+    const { provider, client } = b;
+    if (!provider || !client || provider === client)
+        reasons.push("missing/invalid parties");
+    if (!b.scope)
+        reasons.push("missing scope");
+    const w = (b.window ?? {});
+    const start = ms(w.start);
+    const end = ms(w.end);
+    if (start === null || end === null || start >= end)
+        reasons.push("invalid window");
+    const c = (b.commitments ?? {});
+    if (c.min_actions == null && c.max_actions == null && c.max_gap_ms == null)
+        reasons.push("no commitments");
+    if (reasons.length === 0)
+        for (const [party, role] of [
+            [provider, "provider"],
+            [client, "client"],
+        ]) {
+            const s = (e.signatures ?? []).find((x) => x.did === party);
+            if (!s)
+                reasons.push(`missing signature from ${role}`);
+            else if (!sigValid(b, String(s.did), s.sig))
+                reasons.push(`invalid signature from ${role}`);
+        }
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Zanii's verdict over the provider's consecutive receipt chain for the window. Breaches:
+ * INVALID_RECEIPT, INCOMPLETE_RECORD (a seam: something recorded was left out), TOO_FEW_ACTIONS,
+ * TOO_MANY_ACTIONS, MAX_GAP_EXCEEDED. `asOf` (default the window's end) caps the trailing gap.
+ */
+export function assessCompliance(sla, receipts, asOf) {
+    const agreement = verifySla(sla);
+    if (!agreement.ok)
+        return {
+            ok: false,
+            breaches: agreement.reasons.map((r) => ({ kind: "INVALID_RECEIPT", detail: `sla: ${r}` })),
+            metrics: { actions: 0, max_gap_ms: null },
+        };
+    const b = sla.body;
+    const breaches = [];
+    const winStart = ms(b.window.start);
+    const winEnd = ms(b.window.end);
+    if (asOf !== undefined && ms(asOf) === null)
+        throw new Error("as_of must be an ISO timestamp");
+    const asOfMs = Math.min(asOf !== undefined ? ms(asOf) : winEnd, winEnd);
+    // a stable sort, as Python's sorted
+    const sorted = receipts
+        .map((r, i) => ({ r, i, t: ms(r.ts) ?? 0 }))
+        .sort((x, y) => x.t - y.t || x.i - y.i)
+        .map((x) => x.r);
+    for (const r of sorted) {
+        let check;
+        try {
+            check = verifyReceipt(r);
+        }
+        catch (error) {
+            check = { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+        if (!check.ok)
+            breaches.push({
+                kind: "INVALID_RECEIPT",
+                detail: check.error || "invalid receipt",
+                receipt: receiptHash(r),
+            });
+        else if (r.agent_id !== b.provider)
+            breaches.push({
+                kind: "INVALID_RECEIPT",
+                detail: `receipt by ${r.agent_id}, not the provider`,
+                receipt: receiptHash(r),
+            });
+    }
+    for (let i = 1; i < sorted.length; i++)
+        if (sorted[i].prev !== receiptHash(sorted[i - 1]))
+            breaches.push({
+                kind: "INCOMPLETE_RECORD",
+                detail: `chain break between receipts #${i - 1} and #${i} — the slice is not the provider's consecutive record`,
+                receipt: receiptHash(sorted[i]),
+            });
+    const matching = sorted.filter((r) => {
+        const t = ms(r.ts);
+        return (t !== null && winStart <= t && t <= winEnd && scopeCovers(String(b.scope), r.target || ""));
+    });
+    const c = b.commitments;
+    if (c.min_actions != null && matching.length < c.min_actions)
+        breaches.push({
+            kind: "TOO_FEW_ACTIONS",
+            detail: `${matching.length} matching actions < committed minimum ${c.min_actions}`,
+        });
+    if (c.max_actions != null && matching.length > c.max_actions)
+        breaches.push({
+            kind: "TOO_MANY_ACTIONS",
+            detail: `${matching.length} matching actions > committed maximum ${c.max_actions}`,
+        });
+    let maxGap = null;
+    if (matching.length > 0) {
+        const times = matching.map((r) => ms(r.ts));
+        const gaps = [[times[0] - winStart, null]];
+        for (let i = 1; i < times.length; i++)
+            gaps.push([times[i] - times[i - 1], matching[i - 1]]);
+        const last = times[times.length - 1];
+        if (asOfMs > last)
+            gaps.push([asOfMs - last, matching[matching.length - 1]]);
+        maxGap = Math.max(...gaps.map(([g]) => g));
+        if (c.max_gap_ms != null)
+            for (const [g, after] of gaps)
+                if (g > c.max_gap_ms)
+                    breaches.push({
+                        kind: "MAX_GAP_EXCEEDED",
+                        detail: `${g}ms of silence > committed max ${c.max_gap_ms}ms`,
+                        ...(after ? { receipt: receiptHash(after) } : {}),
+                    });
+    }
+    else if (c.max_gap_ms != null && asOfMs - winStart > c.max_gap_ms)
+        breaches.push({
+            kind: "MAX_GAP_EXCEEDED",
+            detail: `no matching actions for ${asOfMs - winStart}ms > committed max ${c.max_gap_ms}ms`,
+        });
+    return {
+        ok: breaches.length === 0,
+        breaches,
+        metrics: { actions: matching.length, max_gap_ms: maxGap },
+    };
+}

package/dist/succession/index.d.ts

@@ -0,0 +1,50 @@
+export type SuccessionReason = "rotation" | "compromise" | "retirement";
+export interface SuccessionBody {
+    v: 1;
+    type: "succession";
+    predecessor: string;
+    successor: string;
+    owner: string;
+    reason: SuccessionReason;
+    ts: string;
+    compromised_at?: string;
+    note?: string;
+}
+export interface Succession {
+    body: SuccessionBody;
+    signatures: Array<{
+        did: string;
+        sig: string;
+    }>;
+}
+export declare function buildSuccessionBody(input: {
+    predecessor: string;
+    successor: string;
+    owner: string;
+    reason: string;
+    ts: string;
+    compromised_at?: string;
+    note?: string;
+}): SuccessionBody;
+/** Signs as the owner (required) or the predecessor (optional: a planned handover). */
+export declare const signSuccession: (body: SuccessionBody, did: string, seed: Uint8Array) => {
+    did: string;
+    sig: string;
+};
+export declare const assembleSuccession: (body: SuccessionBody, signatures: Succession["signatures"]) => Succession;
+export declare const successionHash: (s: Succession) => string;
+/** Structure sane and the owner signed; `cosigned` when the predecessor countersigned too. */
+export declare function verifySuccession(s: unknown): {
+    ok: boolean;
+    reasons: string[];
+    cosigned: boolean;
+};
+/**
+ * Walks the successions back from `did`: every link verifies, links connect, one owner throughout
+ * (a change of owner is a sale, not a succession). `lineage` is oldest first.
+ */
+export declare function verifyLineage(successions: unknown[], did: string): {
+    ok: boolean;
+    reasons: string[];
+    lineage: string[];
+};

package/dist/succession/index.js

@@ -0,0 +1,123 @@
+// Owner-signed succession of the gateway identity (spec/anchoring.md §7), in Zanii's format:
+// byte-identical bodies, signatures and hashes to `@zanii/succession` / `zanii.succession`
+// (vectors: spec/vectors/succession.json). The Python SDK re-exports zanii.succession.
+//
+// Succession proves continuity of authority (the owner says B follows A), not which code ran.
+// After a compromise the predecessor's signature isn't asked for (the attacker holds that key), and
+// `compromised_at` brackets the window its old receipts can be trusted in.
+import { canonicalBytes, jcsHash, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const REASONS = new Set(["rotation", "compromise", "retirement"]);
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+export function buildSuccessionBody(input) {
+    const { predecessor, successor, owner, reason, ts, compromised_at, note } = input;
+    if (!predecessor || !successor || !owner)
+        throw new Error("predecessor, successor, and owner are required");
+    if (predecessor === successor)
+        throw new Error("an agent cannot succeed itself");
+    if (!REASONS.has(reason))
+        throw new Error(`invalid reason '${reason}'`);
+    if (!validTs(ts))
+        throw new Error("ts must be an ISO timestamp");
+    if (reason === "compromise") {
+        if (!validTs(compromised_at))
+            throw new Error("a 'compromise' succession requires compromised_at");
+    }
+    else if (compromised_at !== undefined)
+        throw new Error("compromised_at is only meaningful with reason 'compromise'");
+    return {
+        v: 1,
+        type: "succession",
+        predecessor,
+        successor,
+        owner,
+        reason: reason,
+        ts,
+        ...(compromised_at !== undefined ? { compromised_at } : {}),
+        ...(note !== undefined ? { note } : {}),
+    };
+}
+/** Signs as the owner (required) or the predecessor (optional: a planned handover). */
+export const signSuccession = (body, did, seed) => ({
+    did,
+    sig: `ed25519:${Buffer.from(ed25519Sign(seed, canonicalBytes(body))).toString("hex")}`,
+});
+export const assembleSuccession = (body, signatures) => ({ body, signatures });
+export const successionHash = (s) => jcsHash(s);
+function sigValid(body, did, sig) {
+    const pub = publicKeyFromDid(did);
+    const m = typeof sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sig) : null;
+    if (!pub || !m)
+        return false;
+    return ed25519Verify(pub, canonicalBytes(body), Buffer.from(m[1], "hex"));
+}
+/** Structure sane and the owner signed; `cosigned` when the predecessor countersigned too. */
+export function verifySuccession(s) {
+    const reasons = [];
+    const e = (s ?? {});
+    const b = (e.body ?? {});
+    if (b.v !== 1 || b.type !== "succession")
+        reasons.push("not a succession (v1)");
+    const { predecessor: pred, successor: succ, owner } = b;
+    if (!pred || !succ || !owner || pred === succ)
+        reasons.push("missing/invalid parties");
+    if (!REASONS.has(String(b.reason)))
+        reasons.push("invalid reason");
+    if (b.reason === "compromise" && !validTs(b.compromised_at))
+        reasons.push("a 'compromise' succession requires a valid compromised_at");
+    if (!validTs(b.ts))
+        reasons.push("missing/invalid ts");
+    let cosigned = false;
+    if (reasons.length === 0) {
+        const sigs = Array.isArray(e.signatures) ? e.signatures : [];
+        const ownerSig = sigs.find((x) => x?.did === owner);
+        if (!ownerSig || !sigValid(b, ownerSig.did, ownerSig.sig))
+            reasons.push("missing/invalid OWNER signature");
+        const predSig = sigs.find((x) => x?.did === pred);
+        cosigned = predSig !== undefined && sigValid(b, predSig.did, predSig.sig);
+    }
+    return { ok: reasons.length === 0, reasons, cosigned };
+}
+/**
+ * Walks the successions back from `did`: every link verifies, links connect, one owner throughout
+ * (a change of owner is a sale, not a succession). `lineage` is oldest first.
+ */
+export function verifyLineage(successions, did) {
+    if (successions.length === 0)
+        return { ok: true, reasons: [], lineage: [did] };
+    const bySuccessor = new Map();
+    for (const s of successions) {
+        const check = verifySuccession(s);
+        if (!check.ok) {
+            const label = s?.body?.successor ?? "?";
+            return { ok: false, reasons: check.reasons.map((r) => `link ${label}: ${r}`), lineage: [] };
+        }
+        const link = s;
+        if (bySuccessor.has(link.body.successor))
+            return {
+                ok: false,
+                reasons: [`two successions claim successor ${link.body.successor}`],
+                lineage: [],
+            };
+        bySuccessor.set(link.body.successor, link);
+    }
+    const links = successions;
+    const owner = links[0]?.body.owner;
+    if (!links.every((s) => s.body.owner === owner))
+        return { ok: false, reasons: ["lineage spans multiple owners"], lineage: [] };
+    const lineage = [did];
+    const seen = new Set([did]);
+    let cursor = did;
+    for (let link = bySuccessor.get(cursor); link; link = bySuccessor.get(cursor)) {
+        const prev = link.body.predecessor;
+        if (seen.has(prev))
+            return { ok: false, reasons: ["succession cycle detected"], lineage: [] };
+        seen.add(prev);
+        lineage.unshift(prev);
+        cursor = prev;
+    }
+    const reasons = lineage.length === links.length + 1
+        ? []
+        : [`${links.length + 1 - lineage.length} succession(s) do not connect to ${did}'s lineage`];
+    return { ok: reasons.length === 0, reasons, lineage };
+}

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/tokens/index.d.ts

@@ -0,0 +1,6 @@
+/** The token for one value: `<kind_tok:base64url(nonce ‖ AES-256-GCM(value, aad=kind))>`. */
+export declare function tokenFor(kind: string, value: string, key: Uint8Array): string;
+/** A token's value, or null when it isn't one, or isn't this key's. */
+export declare function resolveToken(token: string, key: Uint8Array): string | null;
+/** Every token in `text` this key resolves, put back; any other is left as it is. */
+export declare function resolveTokens(text: string, key: Uint8Array): string;