@zanii/blackbox 0.2.0 → 0.4.0

package/dist/tokens/index.js

@@ -0,0 +1,46 @@
+// Keyed redaction tokens (spec/data.md §12, L9): a redacted value as `<kind_tok:…>`, AES-256-GCM
+// under the deployment's token key, so a tool that holds the key resolves it and nothing in between
+// (the model, the gateway's memory) has the value. Deterministic: the nonce is an HMAC of the kind
+// and value, so the same value always reads the same. Mirrors sdks/python/src/zanii_blackbox/
+// tokens.py; pinned by spec/vectors/tokens.json.
+import { createCipheriv, createDecipheriv, createHmac } from "node:crypto";
+const TOKEN = /<([a-z_]{1,32})_tok:([A-Za-z0-9_-]{24,4096})>/g;
+const check = (key) => {
+    if (key.length !== 32)
+        throw new Error("a token key is 32 bytes");
+};
+/** The token for one value: `<kind_tok:base64url(nonce ‖ AES-256-GCM(value, aad=kind))>`. */
+export function tokenFor(kind, value, key) {
+    check(key);
+    if (!/^[a-z_]{1,32}$/.test(kind))
+        throw new Error("kind must be 1-32 of a-z _");
+    const nonce = createHmac("sha256", key).update(`${kind}\0${value}`).digest().subarray(0, 12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    cipher.setAAD(Buffer.from(kind));
+    const sealed = Buffer.concat([cipher.update(value, "utf8"), cipher.final(), cipher.getAuthTag()]);
+    return `<${kind}_tok:${Buffer.concat([nonce, sealed]).toString("base64url")}>`;
+}
+/** A token's value, or null when it isn't one, or isn't this key's. */
+export function resolveToken(token, key) {
+    check(key);
+    const m = new RegExp(`^${TOKEN.source}$`).exec(token);
+    if (!m)
+        return null;
+    try {
+        const raw = Buffer.from(m[2], "base64url");
+        if (raw.length < 12 + 16)
+            return null;
+        const d = createDecipheriv("aes-256-gcm", key, raw.subarray(0, 12));
+        d.setAAD(Buffer.from(m[1]));
+        d.setAuthTag(raw.subarray(raw.length - 16));
+        return Buffer.concat([d.update(raw.subarray(12, raw.length - 16)), d.final()]).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Every token in `text` this key resolves, put back; any other is left as it is. */
+export function resolveTokens(text, key) {
+    check(key);
+    return text.replace(TOKEN, (t) => resolveToken(t, key) ?? t);
+}

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;