diff --git a/.agents/skills/redacted-circuit-maintenance/SKILL.md b/.agents/skills/redacted-circuit-maintenance/SKILL.md index f5e2872..71c8624 100644 --- a/.agents/skills/redacted-circuit-maintenance/SKILL.md +++ b/.agents/skills/redacted-circuit-maintenance/SKILL.md @@ -78,3 +78,14 @@ Each section below is a rule plus the incident that produced it (2026-09-27, PR - Check that an old v1 link still verifies (legacy warning; CLI exit 4). - Run `yarn test`: soundness plus exact decoding. Any change to the circuit's outputs must keep it green. + +## DKIM key lookup and the archive rate limit +- Keys come from `src/utils/dkimKeys.ts` (a copy lives in the CLI). It tries Google + Cloudflare + DoH first, then every archived key for the selector. `@zk-email/helpers` alone tries one DNS + key, and only the first archived key, and only if the DNS lookup fails. That missed 12 of 132 + corpus emails whose keys were rotated under the same selector (mostly Amazon/SES). +- archive.prove.email allows **10 requests/min per IP**. On a 429 it returns an error object, and + the helper's own fallback crashes ("data.find is not a function"). An unpaced corpus + DKIM sweep therefore misreports ~30 emails as failures. When sweeping, space archive calls + ≥6.5 s apart (wrap `fetch`), or interleave them with proving. Always compare before and after + runs under the same pacing. diff --git a/skills/redacted-email-proof/scripts/package.json b/skills/redacted-email-proof/scripts/package.json index f635d5a..149c725 100644 --- a/skills/redacted-email-proof/scripts/package.json +++ b/skills/redacted-email-proof/scripts/package.json @@ -14,6 +14,7 @@ "@aztec/bb.js": "5.0.0", "@mach-34/noir-bignum-paramgen": "^1.1.2", "@noir-lang/noir_js": "1.0.0-rc.3", + "@zk-email/helpers": "6.4.2", "@zk-email/zkemail-nr": "2.0.0", "bb-legacy": "npm:@aztec/bb.js@0.84.0", "circomlibjs": "^0.1.7" diff --git a/skills/redacted-email-proof/scripts/redacted.mjs b/skills/redacted-email-proof/scripts/redacted.mjs index e0d534b..01e77c7 100755 --- a/skills/redacted-email-proof/scripts/redacted.mjs +++ b/skills/redacted-email-proof/scripts/redacted.mjs @@ -216,12 +216,178 @@ export async function verifyWithSignerFallback(raw, verify, domain) { throw firstError; } +// REASON: @zk-email/helpers' verifyDKIMSignature resolves the key once (Google DoH; only if that +// lookup FAILS, the first archive record for the selector). A sender that rotated its key but +// reused the selector, or an archive with several keys per selector (amazon.com: 8 of 23), gave +// "bad signature" although the signing key is known. Try every candidate: Google + Cloudflare DoH, +// then all archived keys for the selector (most recently seen first). Keep in sync with +// src/utils/dkimKeys.ts (tests/dkim-keys.test.ts checks both). +export const DKIM_ARCHIVE_API = "https://archive.prove.email/api/key"; + +async function helpers() { + try { + const [verifier, tools, sanitizers, doh] = await Promise.all([ + import("@zk-email/helpers/dist/lib/mailauth/dkim-verifier.js"), + import("@zk-email/helpers/dist/lib/mailauth/tools.js"), + import("@zk-email/helpers/dist/dkim/sanitizers.js"), + import("@zk-email/helpers/dist/dkim/dns-over-http.js"), + ]); + const d = (m) => m.default ?? m; + return { DkimVerifier: d(verifier).DkimVerifier, writeToStream: d(tools).writeToStream, sanitizers: d(sanitizers).default ?? d(sanitizers), DoH: d(doh).DoH, DoHServer: d(doh).DoHServer }; + } catch (e) { + die(`dependencies missing (${e.message}).\nRun \`npm install\` in ${HERE} first.`); + } +} + +const pOf = (record) => /(?:^|;)\s*p\s*=\s*([^;]*)/i.exec(record)?.[1]?.replace(/\s+/g, "") ?? ""; + +// NOTE: archive.prove.email allows 10 requests/min per IP and answers 429 with a JSON error object +// (the helper's own fallback crashes on it: "data.find is not a function"). Retry once after the +// server's retryAfterSeconds (capped at 15 s), then report it instead of a misleading "bad signature". +async function archiveKeys(domain, selector) { + const url = new URL(DKIM_ARCHIVE_API); + url.searchParams.set("domain", domain); + for (let attempt = 0; ; attempt++) { + const resp = await fetch(url); + const body = await resp.json().catch(() => null); + if (Array.isArray(body)) { + return body + .filter((r) => r.selector === selector && typeof r.value === "string") + .sort((a, b) => String(b.lastSeenAt ?? "").localeCompare(String(a.lastSeenAt ?? ""))) + .map((r) => ({ source: "archive", record: r.value, lastSeenAt: r.lastSeenAt })); + } + const wait = Number(body?.details?.retryAfterSeconds); + if (resp.status === 429 && attempt === 0 && wait > 0 && wait <= 15) { + await new Promise((r) => setTimeout(r, wait * 1000)); + continue; + } + throw new Error(resp.status === 429 ? "archive.prove.email rate limit (10/min per IP); retry in a minute" : `archive.prove.email HTTP ${resp.status}`); + } +} + +/** Candidate keys: Google + Cloudflare DoH, plus (withArchive) every archived key; dedup by p=, revoked dropped. */ +export async function dkimKeyCandidates(name, withArchive = true) { + const { DoH, DoHServer } = await helpers(); + const [selector, , ...rest] = name.split("."); + const domain = rest.join("."); + const dns = async (server, source) => { + try { + const record = await DoH.resolveDKIMPublicKey(name, server); + return record ? [{ source, record }] : []; + } catch { + return []; // one resolver being down must not hide keys the other sources have + } + }; + let archiveError; + const archive = async () => + withArchive + ? archiveKeys(domain, selector).catch((e) => { + archiveError = e.message; + return []; + }) + : []; + const all = (await Promise.all([dns(DoHServer.Google, "dns:google"), dns(DoHServer.Cloudflare, "dns:cloudflare"), archive()])).flat(); + const seen = new Set(); + const out = all.filter((c) => { + const p = pOf(c.record); + if (!p || seen.has(p)) return false; + seen.add(p); + return true; + }); + out.archiveError = archiveError; + return out; +} + +async function runVerifier(h, email, domain, skipBodyHash, resolver) { + const v = new h.DkimVerifier({ resolver: async (name) => resolver(name), skipBodyHash }); + await h.writeToStream(v, email); + let d = domain; + if (!d) { + if (v.headerFrom.length > 1) throw new Error("Multiple From header in email and domain for verification not specified"); + d = v.headerFrom[0].split("@")[1]; + } + const r = v.results.find((x) => x.signingDomain === d); + if (!r) throw new Error(`DKIM signature not found for domain ${d}`); + return r; +} + +/** Same result shape as verifyDKIMSignature plus keySource; same error message when nothing verifies. */ +export async function verifyDkimWithKeyCandidates(email, domain = "", enableSanitization = true, skipBodyHash = false, resolveKeys = dkimKeyCandidates) { + const h = await helpers(); + const emailStr = Buffer.isBuffer(email) || email instanceof Uint8Array ? Buffer.from(email).toString("latin1") : String(email); + let failure; + let archiveError; + // Phase 1: DNS keys only. Phase 2: archived keys, only when DNS keys fail for a key-related + // reason (the archive's 10 req/min limit; no key can fix a body-hash mismatch). + for (const withArchive of [false, true]) { + if (withArchive && failure && /body hash/i.test(failure.status.comment ?? "")) break; + const cache = new Map(); + const keys = (name) => { + if (!cache.has(name)) { + cache.set( + name, + resolveKeys(name, withArchive).then((list) => { + archiveError ??= list.archiveError; + return withArchive ? list.filter((c) => c.source === "archive") : list; + }), + ); + } + return cache.get(name); + }; + // Round i serves candidate i for every selector in the message; stop past the longest list. + let rounds = 1; + let served = 0; + for (let i = 0; i < rounds; i++) { + const sourceOf = new Map(); + const resolver = async (name) => { + const c = await keys(name); + rounds = Math.max(rounds, c.length); + if (!c.length) throw Object.assign(new Error(`No DKIM key found for ${name}`), { code: "ENODATA" }); + const pick = c[Math.min(i, c.length - 1)]; + sourceOf.set(name.toLowerCase(), pick.source); + served++; + return [pick.record]; + }; + let r = await runVerifier(h, email, domain, skipBodyHash, resolver); + let appliedSanitization; + if (r.status.comment === "bad signature" && enableSanitization) { + for (const sanitize of h.sanitizers) { + const s = await runVerifier(h, sanitize(emailStr), domain, skipBodyHash, resolver); + if (s.status.result === "pass") { + r = s; + appliedSanitization = sanitize.name; + break; + } + } + } + if (r.status.result === "pass") { + const n = createPublicKey(r.publicKey.toString()).export({ format: "jwk" }).n; + return { + signature: BigInt("0x" + Buffer.from(r.signature.replace(/\s+/g, ""), "base64").toString("hex")), + headers: r.status.signedHeaders, + body: r.body, + bodyHash: r.bodyHash, + signingDomain: r.signingDomain, + publicKey: BigInt("0x" + Buffer.from(n, "base64url").toString("hex")), + selector: r.selector, + algo: r.algo, + format: r.format, + modulusLength: r.modulusLength, + appliedSanitization, + keySource: sourceOf.get(`${r.selector}._domainkey.${r.signingDomain}`.toLowerCase()) ?? "unknown", + }; + } + // report the DNS attempt unless an archived key was actually tried + if (!failure || (withArchive && served > 0)) failure = r; + } + } + const note = archiveError ? ` (${archiveError})` : ""; + throw new Error(`DKIM signature verification failed for domain ${failure.signingDomain}. Reason: ${failure.status.comment}${note}`); +} + async function dkimOf(emailBuf, domain) { - const { zk } = await lib(); try { - // (email, domain, enableSanitization, fallbackToZKEmailDNSArchive) — the archive fallback - // lets old emails prove after the sender rotated its DKIM key. - return await verifyWithSignerFallback(emailBuf, (raw, d) => zk.verifyDKIMSignature(raw, d, true, true), domain); + return await verifyWithSignerFallback(emailBuf, (raw, d) => verifyDkimWithKeyCandidates(raw, d), domain); } catch (e) { die( `DKIM verification failed: ${e.message}\n` + @@ -718,6 +884,7 @@ async function cmdInspect(file, opts) { selector: dkim.selector, keyBits: dkim.modulusLength, sanitization: dkim.appliedSanitization || null, + keySource: dkim.keySource, headerBytes: dkim.headers.length, bodyBytes: dkim.body.length, bodyView: qp ? "quoted-printable (shown decoded; --hide/--reveal match decoded text)" : "raw", @@ -744,7 +911,8 @@ async function cmdProve(file, opts) { const c = pickCircuit(dkim.modulusLength, dkim.headers.length, dkim.body.length); const m = buildMasks(dkim, opts); - log(`DKIM ok: d=${dkim.signingDomain} s=${dkim.selector} (${dkim.modulusLength}-bit) → circuit ${c.name}`); + log(`DKIM ok: d=${dkim.signingDomain} s=${dkim.selector} (${dkim.modulusLength}-bit, key from ${dkim.keySource}) → circuit ${c.name}`); + if (dkim.keySource === "archive") log("Note: the signing key is no longer served by DNS; it came from archive.prove.email."); log(`\n===== what the proof will reveal (${BLOCK} = hidden) =====\n`); log(render(m.h, m.headerMask)); // quoted-printable bodies are previewed decoded, exactly as the verify page will show them diff --git a/src/lib.ts b/src/lib.ts index 5cb5552..6daae2d 100644 --- a/src/lib.ts +++ b/src/lib.ts @@ -220,11 +220,9 @@ export const handleGenerateProof = async ( ) => { let dkimResult = existingDkimResult; if (!dkimResult) { - const { verifyDKIMSignature } = await import("@zk-email/helpers/dist/dkim"); + const { verifyDkimWithKeyCandidates } = await import("./utils/dkimKeys"); const { verifyWithSignerFallback } = await import("./utils/dkimSigner"); - dkimResult = await verifyWithSignerFallback(email, (raw, domain) => - verifyDKIMSignature(raw as string, domain) - ); + dkimResult = await verifyWithSignerFallback(email, (raw, domain) => verifyDkimWithKeyCandidates(raw, domain)); } // The UI's body mask is per character of the displayed body, which is decoded for diff --git a/src/utils/dkimKeys.ts b/src/utils/dkimKeys.ts new file mode 100644 index 0000000..3ee3b61 --- /dev/null +++ b/src/utils/dkimKeys.ts @@ -0,0 +1,231 @@ +/** + * DKIM verification that tries every plausible public key for the signature's selector. + * + * REASON: @zk-email/helpers' verifyDKIMSignature resolves the key once: Google DNS-over-HTTPS, + * and only if that lookup *fails*, the FIRST archive.prove.email record for the selector. Two + * common cases then fail with "bad signature" although the signing key is known: + * - the sender rotated the key but reused the selector (DNS answers with the new key, so the + * archive is never consulted), and + * - the archive holds several keys for the selector (amazon.com: 8 of 23 selectors have 2-3) + * and the one that signed isn't the first. + * So we collect candidates (Google DoH, Cloudflare DoH, then every archived key for the selector, + * most recently seen first) and try them in order. The first key that verifies wins; its source + * is reported so callers can say "key from the archive, no longer in DNS". + * + * Accepting an archived key doesn't weaken anything the old code accepted: the archive was + * already a fallback, and the verifier (CLI `verify`) checks the proof's key hash against DNS and + * the archive independently. + * + * Keep in sync with the copy in skills/redacted-email-proof/scripts/redacted.mjs + * (tests/dkim-keys.test.ts checks both). + */ +import { DkimVerifier } from "@zk-email/helpers/dist/lib/mailauth/dkim-verifier"; +import { writeToStream } from "@zk-email/helpers/dist/lib/mailauth/tools"; +import sanitizersModule from "@zk-email/helpers/dist/dkim/sanitizers"; +import { DoH, DoHServer } from "@zk-email/helpers/dist/dkim/dns-over-http"; +import type { DKIMVerificationResult } from "@zk-email/helpers/dist/dkim"; + +// NOTE: CJS interop differs by loader: Vite gives the array, Node/tsx the exports object +// ({ default: [...] }). Without this, Node throws "sanitizers is not iterable". +const sanitizers: ((email: string) => string)[] = Array.isArray(sanitizersModule) + ? sanitizersModule + : (sanitizersModule as unknown as { default: ((email: string) => string)[] }).default; + +export const DKIM_ARCHIVE_API = "https://archive.prove.email/api/key"; + +export interface KeyCandidate { + /** "dns:google" | "dns:cloudflare" | "archive" */ + source: string; + /** the TXT record, "v=DKIM1; k=rsa; p=…" */ + record: string; + /** archive only: when the archive last saw this key in DNS */ + lastSeenAt?: string; +} + +export type DkimKeyResult = DKIMVerificationResult & { keySource: string }; + +const pOf = (record: string) => /(?:^|;)\s*p\s*=\s*([^;]*)/i.exec(record)?.[1]?.replace(/\s+/g, "") ?? ""; + +export type KeyCandidates = KeyCandidate[] & { archiveError?: string }; + +const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); + +/** + * Archived keys for `selector` at `domain`, most recently seen first. + * NOTE: archive.prove.email allows 10 requests/min per IP and answers 429 with a JSON error + * object (not an array); the helper's own fallback crashes on that ("data.find is not a + * function"). Retry once after the server's retryAfterSeconds (capped at 15 s), then give up and + * say so in the error, rather than reporting a misleading "bad signature". + */ +async function archiveKeys(domain: string, selector: string): Promise { + const url = new URL(DKIM_ARCHIVE_API); + url.searchParams.set("domain", domain); + for (let attempt = 0; ; attempt++) { + const resp = await fetch(url); + const body = await resp.json().catch(() => null); + if (Array.isArray(body)) { + return (body as { selector: string; value: string; lastSeenAt?: string }[]) + .filter((r) => r.selector === selector && typeof r.value === "string") + .sort((a, b) => String(b.lastSeenAt ?? "").localeCompare(String(a.lastSeenAt ?? ""))) + .map((r) => ({ source: "archive", record: r.value, lastSeenAt: r.lastSeenAt })); + } + const wait = Number(body?.details?.retryAfterSeconds); + if (resp.status === 429 && attempt === 0 && wait > 0 && wait <= 15) { + await sleep(wait * 1000); + continue; + } + throw new Error(resp.status === 429 ? "archive.prove.email rate limit (10/min per IP); retry in a minute" : `archive.prove.email HTTP ${resp.status}`); + } +} + +/** + * Candidate keys for `._domainkey.`: Google and Cloudflare DoH, plus (with + * `withArchive`) every archived key for the selector. Deduplicated by p=; revoked (empty p=) + * records dropped. + */ +export async function dkimKeyCandidates(name: string, withArchive = true): Promise { + const [selector, , ...rest] = name.split("."); + const domain = rest.join("."); + const dns = async (server: string, source: string): Promise => { + try { + const record = await DoH.resolveDKIMPublicKey(name, server); + return record ? [{ source, record }] : []; + } catch { + return []; // REASON: one resolver being down must not hide keys the other sources have + } + }; + let archiveError: string | undefined; + const archive = async () => + withArchive + ? archiveKeys(domain, selector).catch((e: Error) => { + archiveError = e.message; + return [] as KeyCandidate[]; + }) + : []; + const all = (await Promise.all([dns(DoHServer.Google, "dns:google"), dns(DoHServer.Cloudflare, "dns:cloudflare"), archive()])).flat(); + const seen = new Set(); + const out: KeyCandidates = all.filter((c) => { + const p = pOf(c.record); + if (!p || seen.has(p)) return false; + seen.add(p); + return true; + }); + out.archiveError = archiveError; + return out; +} + +type ResolveKeys = (name: string, withArchive: boolean) => Promise; +// eslint-disable-next-line @typescript-eslint/no-explicit-any +type RawResult = { [key: string]: any }; + +async function runVerifier(email: string | Uint8Array, domain: string, skipBodyHash: boolean, resolver: (name: string) => Promise) { + const v = new DkimVerifier({ resolver: async (name: string) => resolver(name), skipBodyHash } as never); + await writeToStream(v, email as never); + let d = domain; + if (!d) { + if (v.headerFrom.length > 1) throw new Error("Multiple From header in email and domain for verification not specified"); + d = v.headerFrom[0].split("@")[1]; + } + const r = v.results.find((x) => x.signingDomain === d) as RawResult | undefined; + if (!r) throw new Error(`DKIM signature not found for domain ${d}`); + return r; +} + +const b64ToBytes = (b64: string) => Uint8Array.from(atob(b64.replace(/\s+/g, "")), (c) => c.charCodeAt(0)); +/** + * SPKI PEM -> RSA modulus, via WebCrypto (browser and Node 20+), so no node-forge dependency. + * mailauth's getPublicKey always hands back "BEGIN PUBLIC KEY" (SPKI), so no PKCS#1 path. + */ +async function modulusOf(pem: string): Promise { + const der = b64ToBytes(pem.replace(/-----[^-]+-----/g, "")); + const key = await crypto.subtle.importKey("spki", der, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, true, ["verify"]); + const n = (await crypto.subtle.exportKey("jwk", key)).n!; + const b64 = n.replace(/-/g, "+").replace(/_/g, "/"); + const hex = Array.from(b64ToBytes(b64 + "=".repeat((4 - (b64.length % 4)) % 4)), (b) => b.toString(16).padStart(2, "0")).join(""); + return BigInt("0x" + hex); +} + +/** + * Drop-in for verifyDKIMSignature(email, domain, enableSanitization, _, skipBodyHash): same result + * shape plus `keySource`. Throws the same "DKIM signature verification failed for domain …" + * message (from the first candidate's attempt) when no key verifies. + */ +export async function verifyDkimWithKeyCandidates( + email: string | Uint8Array, + domain = "", + enableSanitization = true, + skipBodyHash = false, + resolveKeys: ResolveKeys = dkimKeyCandidates +): Promise { + const emailStr = typeof email === "string" ? email : new TextDecoder("latin1").decode(email); + let failure: RawResult | undefined; + let archiveError: string | undefined; + // Phase 1: DNS keys only. Phase 2: archived keys, fetched only when DNS keys fail for a + // key-related reason. REASON: the archive allows 10 requests/min per IP; querying it for every + // email (or for body-hash failures, which no key can fix) would exhaust that quickly. + for (const withArchive of [false, true]) { + if (withArchive && failure && /body hash/i.test(failure.status.comment ?? "")) break; + const cache = new Map>(); + const keys = (name: string) => { + if (!cache.has(name)) { + cache.set( + name, + resolveKeys(name, withArchive).then((list) => { + archiveError ??= list.archiveError; + const kept: KeyCandidates = withArchive ? list.filter((c) => c.source === "archive") : list; + return kept; + }) + ); + } + return cache.get(name)!; + }; + // Round i serves candidate i for every selector in the message (a message can carry several + // signatures); stop once i passes the longest candidate list. + let rounds = 1; + let served = 0; + for (let i = 0; i < rounds; i++) { + const sourceOf = new Map(); + const resolver = async (name: string) => { + const c = await keys(name); + rounds = Math.max(rounds, c.length); + if (!c.length) throw Object.assign(new Error(`No DKIM key found for ${name}`), { code: "ENODATA" }); + const pick = c[Math.min(i, c.length - 1)]; + sourceOf.set(name.toLowerCase(), pick.source); + served++; + return [pick.record]; + }; + let r = await runVerifier(email, domain, skipBodyHash, resolver); + let appliedSanitization: string | undefined; + if (r.status.comment === "bad signature" && enableSanitization) { + for (const sanitize of sanitizers) { + const s = await runVerifier(sanitize(emailStr), domain, skipBodyHash, resolver); + if (s.status.result === "pass") { + r = s; + appliedSanitization = sanitize.name; + break; + } + } + } + if (r.status.result === "pass") { + return { + signature: BigInt(`0x${Array.from(b64ToBytes(r.signature), (b) => b.toString(16).padStart(2, "0")).join("")}`), + headers: r.status.signedHeaders, + body: r.body, + bodyHash: r.bodyHash, + signingDomain: r.signingDomain, + publicKey: await modulusOf(r.publicKey.toString()), + selector: r.selector, + algo: r.algo, + format: r.format, + modulusLength: r.modulusLength, + appliedSanitization, + keySource: sourceOf.get(`${r.selector}._domainkey.${r.signingDomain}`.toLowerCase()) ?? "unknown", + }; + } + // report the DNS attempt unless an archived key was actually tried + if (!failure || (withArchive && served > 0)) failure = r; + } + } + const note = archiveError ? ` (${archiveError})` : ""; + throw new Error(`DKIM signature verification failed for domain ${failure!.signingDomain}. Reason: ${failure!.status.comment}${note}`); +} diff --git a/src/utils/emlParser.ts b/src/utils/emlParser.ts index 0876d78..55b96ca 100644 --- a/src/utils/emlParser.ts +++ b/src/utils/emlParser.ts @@ -1,5 +1,5 @@ import PostalMime, { type Address } from 'postal-mime'; -import { verifyDKIMSignature } from '@zk-email/zkemail-nr'; +import { verifyDkimWithKeyCandidates } from './dkimKeys'; import { verifyWithSignerFallback } from './dkimSigner'; import { bodyViewFor } from './qp'; @@ -11,7 +11,7 @@ export interface EmailFieldRange { } // Type for DKIM verification result from the SDK -export type DKIMResult = Awaited>; +export type DKIMResult = Awaited>; export interface ParsedEmail { from: string; @@ -198,7 +198,8 @@ export async function parseEmlFile(emlContent: string): Promise { // Also store full DKIM result to reuse during proof generation (Phase 2 optimization) try { dkimResult = await verifyWithSignerFallback(emlContent, (raw, domain) => - verifyDKIMSignature(raw as string, domain, undefined, true) + // DNS (Google + Cloudflare), then every archived key for the selector (see dkimKeys.ts) + verifyDkimWithKeyCandidates(raw, domain) ); // Convert Buffers to strings for storage dkimCanonicalizedHeaders = dkimResult.headers.toString('utf-8'); diff --git a/tests/dkim-keys.test.ts b/tests/dkim-keys.test.ts new file mode 100644 index 0000000..494eb71 --- /dev/null +++ b/tests/dkim-keys.test.ts @@ -0,0 +1,143 @@ +/** + * DKIM key candidates: an email must verify when its signing key is only in the archive, even if + * DNS now serves a different key under the same selector, or the archive holds several keys for + * that selector. Synthetic email + ephemeral keys; DNS and archive answered by + * tests/fixtures/doh-stub.mjs (no network). + */ +import { test, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { createHash, generateKeyPairSync, sign } from "node:crypto"; +import { execFileSync } from "node:child_process"; +import { mkdtempSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { verifyDKIMSignature } from "@zk-email/helpers/dist/dkim"; +import { verifyDkimWithKeyCandidates } from "../src/utils/dkimKeys"; +// @ts-expect-error - plain JS module without types +import { verifyDkimWithKeyCandidates as cliVerify } from "../skills/redacted-email-proof/scripts/redacted.mjs"; +// @ts-expect-error - plain JS module without types +import { installStub, restoreFetch, archiveCalls } from "./fixtures/doh-stub.mjs"; + +const ROOT = join(import.meta.dirname, ".."); +const NAME = "sel._domainkey.example.test"; + +const newKey = () => { + const { privateKey, publicKey } = generateKeyPairSync("rsa", { modulusLength: 2048 }); + return { privateKey, record: `v=DKIM1; k=rsa; p=${publicKey.export({ format: "der", type: "spki" }).toString("base64")}` }; +}; + +// Minimal relaxed/relaxed DKIM signer (RFC 6376 §3.4.2/§3.4.4) for simple one-line headers. +function signedEmail(privateKey: ReturnType["privateKey"]) { + const headers = [["From", "Alice "], ["To", "bob@example.test"], ["Subject", "Key rotation test"]]; + const body = "Hello from a synthetic email.\r\n"; + const bh = createHash("sha256").update(body).digest("base64"); + const dkimValue = `v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.test; s=sel; h=from:to:subject; bh=${bh}; b=`; + const canon = (n: string, v: string) => `${n.toLowerCase()}:${v.replace(/\s+/g, " ").trim()}`; + const signingInput = headers.map(([n, v]) => canon(n, v) + "\r\n").join("") + canon("DKIM-Signature", dkimValue); + const b = sign("RSA-SHA256", Buffer.from(signingInput), privateKey).toString("base64"); + return `DKIM-Signature: ${dkimValue}${b}\r\n` + headers.map(([n, v]) => `${n}: ${v}\r\n`).join("") + "\r\n" + body; +} + +const archiveRows = (...records: string[]) => + records.map((value, i) => ({ domain: "example.test", selector: "sel", value, lastSeenAt: `2026-0${9 - i}-01T00:00:00Z` })); + +function cliInspect(eml: string, dns: Record, archive: Record) { + const file = join(mkdtempSync(join(tmpdir(), "redacted-keys-")), "mail.eml"); + writeFileSync(file, eml); + try { + const out = execFileSync( + "node", + ["--import", join(ROOT, "tests/fixtures/doh-stub.mjs"), join(ROOT, "skills/redacted-email-proof/scripts/redacted.mjs"), "inspect", file, "--json"], + { + encoding: "utf8", + stdio: ["ignore", "pipe", "pipe"], + env: { ...process.env, DOH_STUB_RECORDS: JSON.stringify(dns), ARCHIVE_STUB_RECORDS: JSON.stringify(archive) }, + } + ); + return { code: 0, json: JSON.parse(out.slice(out.indexOf("{"))) }; + } catch (e) { + const err = e as { status: number; stderr: string }; + return { code: err.status, stderr: err.stderr }; + } +} + +afterEach(() => restoreFetch()); + +test("REGRESSION: key rotated under the same selector — old helper fails, site + CLI verify via the archive", async () => { + const old = newKey(); + const current = newKey(); + const eml = signedEmail(old.privateKey); + const dns = { [NAME]: current.record }; + const archive = { "example.test": archiveRows(current.record, old.record) }; + installStub(dns, archive); + + // before: DNS answers (with the new key), so the helper never consults the archive + await assert.rejects(verifyDKIMSignature(eml, "", true, true), /bad signature/); + + // after + const site = await verifyDkimWithKeyCandidates(eml); + assert.equal(site.keySource, "archive"); + const cli = await cliVerify(Buffer.from(eml)); + assert.equal(cli.keySource, "archive"); + assert.equal(cli.publicKey, site.publicKey); + assert.equal(cli.signature, site.signature); + assert.equal(Buffer.from(cli.headers).toString("latin1"), Buffer.from(site.headers).toString("latin1")); + const expectedModulus = BigInt("0x" + Buffer.from(old.privateKey.export({ format: "jwk" }).n!, "base64url").toString("hex")); + assert.equal(site.publicKey, expectedModulus); + + restoreFetch(); + const r = cliInspect(eml, dns, archive); + assert.equal(r.code, 0, r.stderr); + assert.equal(r.json.keySource, "archive"); +}); + +test("REGRESSION: selector gone from DNS and the signing key is not the archive's first record", async () => { + const [a, b, signer] = [newKey(), newKey(), newKey()]; + const eml = signedEmail(signer.privateKey); + const archive = { "example.test": archiveRows(a.record, b.record, signer.record) }; + installStub({}, archive); + + await assert.rejects(verifyDKIMSignature(eml, "", true, true), /bad signature/); + const site = await verifyDkimWithKeyCandidates(eml); + assert.equal(site.keySource, "archive"); +}); + +test("current DNS key verifies first and the archive is not queried (10 req/min limit)", async () => { + const k = newKey(); + const eml = signedEmail(k.privateKey); + installStub({ [NAME]: k.record }, { "example.test": archiveRows(newKey().record) }); + const site = await verifyDkimWithKeyCandidates(eml); + assert.equal(site.keySource, "dns:google"); + const cli = await cliVerify(Buffer.from(eml)); + assert.equal(cli.keySource, "dns:google"); + assert.equal(archiveCalls.count, 0); +}); + +test("body hash mismatch: no key can fix it, so the archive is not queried", async () => { + const k = newKey(); + const eml = signedEmail(k.privateKey).replace("Hello from", "Hullo from"); + installStub({ [NAME]: k.record }, { "example.test": archiveRows(newKey().record) }); + await assert.rejects(verifyDkimWithKeyCandidates(eml), /body hash did not verify/); + await assert.rejects(cliVerify(Buffer.from(eml)), /body hash did not verify/); + assert.equal(archiveCalls.count, 0); +}); + +test("archive 429 is retried once after retryAfterSeconds (site and CLI)", async () => { + const old = newKey(); + const eml = signedEmail(old.privateKey); + const dns = { [NAME]: newKey().record }; + const archive = { "example.test": archiveRows(old.record) }; + installStub(dns, archive, { rateLimitFirst: true }); + assert.equal((await verifyDkimWithKeyCandidates(eml)).keySource, "archive"); + assert.equal(archiveCalls.count, 2); + installStub(dns, archive, { rateLimitFirst: true }); + assert.equal((await cliVerify(Buffer.from(eml))).keySource, "archive"); + assert.equal(archiveCalls.count, 2); +}); + +test("no candidate verifies: same error as before; revoked (empty p=) records are ignored", async () => { + const eml = signedEmail(newKey().privateKey); + installStub({ [NAME]: newKey().record }, { "example.test": archiveRows("v=DKIM1; k=rsa; p=", newKey().record) }); + await assert.rejects(verifyDkimWithKeyCandidates(eml), /DKIM signature verification failed for domain example\.test\. Reason: bad signature/); + await assert.rejects(cliVerify(Buffer.from(eml)), /DKIM signature verification failed for domain example\.test\. Reason: bad signature/); +}); diff --git a/tests/fixtures/doh-stub.mjs b/tests/fixtures/doh-stub.mjs index 1650f0a..200e3ee 100644 --- a/tests/fixtures/doh-stub.mjs +++ b/tests/fixtures/doh-stub.mjs @@ -1,13 +1,33 @@ -// Preloaded with `node --import` in tests: answers DNS-over-HTTPS TXT queries from -// DOH_STUB_RECORDS (JSON { "._domainkey.": "v=DKIM1; k=rsa; p=…" }) and fails every -// other request, so tests never touch the network. -const records = JSON.parse(process.env.DOH_STUB_RECORDS || "{}"); -globalThis.fetch = async (input) => { - const url = new URL(String(input)); - const name = url.searchParams.get("name"); - if (name && name in records) { - return new Response(JSON.stringify({ Status: 0, Answer: [{ name, type: 16, data: records[name] }] }), { status: 200 }); - } - if (name) return new Response(JSON.stringify({ Status: 3, Answer: [] }), { status: 200 }); - return new Response("offline test", { status: 404 }); -}; +// Preloaded with `node --import` in tests (or imported in-process): answers DNS-over-HTTPS TXT +// queries from DOH_STUB_RECORDS (JSON { "._domainkey.": "v=DKIM1; k=rsa; p=…" }) and +// archive.prove.email key queries from ARCHIVE_STUB_RECORDS (JSON { "": [{ selector, +// value, lastSeenAt }] }), and fails every other request, so tests never touch the network. +const realFetch = globalThis.fetch; +/** archive requests seen since the last installStub (tests assert the archive isn't hammered) */ +export const archiveCalls = { count: 0 }; +// opts.rateLimitFirst: answer the first archive request like the real API's 429 (1 s retry-after) +export function installStub(records = {}, archive = {}, opts = {}) { + archiveCalls.count = 0; + globalThis.fetch = async (input) => { + const url = new URL(String(input)); + if (url.pathname === "/api/key") { + archiveCalls.count++; + if (opts.rateLimitFirst && archiveCalls.count === 1) { + const err = { error: "rate_limit_exceeded", details: { limit: 10, windowSeconds: 60, retryAfterSeconds: 1 } }; + return new Response(JSON.stringify(err), { status: 429 }); + } + const rows = archive[url.searchParams.get("domain")]; + return rows ? new Response(JSON.stringify(rows), { status: 200 }) : new Response("[]", { status: 200 }); + } + const name = url.searchParams.get("name"); + if (name && name in records) { + return new Response(JSON.stringify({ Status: 0, Answer: [{ name, type: 16, data: records[name] }] }), { status: 200 }); + } + if (name) return new Response(JSON.stringify({ Status: 3, Answer: [] }), { status: 200 }); + return new Response("offline test", { status: 404 }); + }; +} +export const restoreFetch = () => (globalThis.fetch = realFetch); +if (process.env.DOH_STUB_RECORDS || process.env.ARCHIVE_STUB_RECORDS) { + installStub(JSON.parse(process.env.DOH_STUB_RECORDS || "{}"), JSON.parse(process.env.ARCHIVE_STUB_RECORDS || "{}")); +}