From 4116d7cfcacffbbb2b878be11583fdb01cdbd79e Mon Sep 17 00:00:00 2001 From: Divide-By-0 Date: Tue, 29 Sep 2026 16:19:27 -0700 Subject: [PATCH 1/3] fix(dkim): try every known key for the selector (Google+Cloudflare DNS, all archived keys) @zk-email/helpers resolves the key once: Google DoH, and only if that lookup fails, the first archive record. A key rotated under a reused selector, or an archive with several keys per selector, gave 'bad signature' although the signing key is known. Site and CLI now try all candidates and report the key source. Co-Authored-By: Claude Opus 5.5 --- .../redacted-email-proof/scripts/package.json | 1 + .../redacted-email-proof/scripts/redacted.mjs | 139 +++++++++++++- src/lib.ts | 6 +- src/utils/dkimKeys.ts | 178 ++++++++++++++++++ src/utils/emlParser.ts | 7 +- tests/dkim-keys.test.ts | 120 ++++++++++++ tests/fixtures/doh-stub.mjs | 37 ++-- 7 files changed, 463 insertions(+), 25 deletions(-) create mode 100644 src/utils/dkimKeys.ts create mode 100644 tests/dkim-keys.test.ts 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..d59d853 100755 --- a/skills/redacted-email-proof/scripts/redacted.mjs +++ b/skills/redacted-email-proof/scripts/redacted.mjs @@ -216,12 +216,139 @@ 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, "") ?? ""; + +/** All candidate keys for ._domainkey., deduplicated by p=, revoked (empty p=) dropped. */ +export async function dkimKeyCandidates(name) { + 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 + } + }; + const archive = async () => { + try { + const url = new URL(DKIM_ARCHIVE_API); + url.searchParams.set("domain", domain); + const rows = await (await fetch(url)).json(); + return rows + .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 })); + } catch { + return []; // archive is best-effort + } + }; + const all = (await Promise.all([dns(DoHServer.Google, "dns:google"), dns(DoHServer.Cloudflare, "dns:cloudflare"), archive()])).flat(); + const seen = new Set(); + return all.filter((c) => { + const p = pOf(c.record); + if (!p || seen.has(p)) return false; + seen.add(p); + return true; + }); +} + +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 cache = new Map(); + const keys = (name) => { + if (!cache.has(name)) cache.set(name, resolveKeys(name)); + return cache.get(name); + }; + const emailStr = Buffer.isBuffer(email) || email instanceof Uint8Array ? Buffer.from(email).toString("latin1") : String(email); + let firstFailure; + // Round i serves candidate i for every selector in the message; stop past the longest list. + let rounds = 1; + 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); + 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", + }; + } + firstFailure ??= r; + } + throw new Error(`DKIM signature verification failed for domain ${firstFailure.signingDomain}. Reason: ${firstFailure.status.comment}`); +} + 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 +845,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 +872,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..39e0bcd --- /dev/null +++ b/src/utils/dkimKeys.ts @@ -0,0 +1,178 @@ +/** + * 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, "") ?? ""; + +/** All candidate keys for `._domainkey.`, deduplicated by p=, revoked (empty p=) dropped. */ +export async function dkimKeyCandidates(name: string): 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 + } + }; + const archive = async (): Promise => { + try { + const url = new URL(DKIM_ARCHIVE_API); + url.searchParams.set("domain", domain); + const rows = (await (await fetch(url)).json()) as { selector: string; value: string; lastSeenAt?: string }[]; + return rows + .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 })); + } catch { + return []; // archive is best-effort + } + }; + const all = (await Promise.all([dns(DoHServer.Google, "dns:google"), dns(DoHServer.Cloudflare, "dns:cloudflare"), archive()])).flat(); + const seen = new Set(); + return all.filter((c) => { + const p = pOf(c.record); + if (!p || seen.has(p)) return false; + seen.add(p); + return true; + }); +} + +type ResolveKeys = (name: string) => 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 cache = new Map>(); + const keys = (name: string) => { + if (!cache.has(name)) cache.set(name, resolveKeys(name)); + return cache.get(name)!; + }; + const emailStr = typeof email === "string" ? email : new TextDecoder("latin1").decode(email); + let firstFailure: RawResult | undefined; + // 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; + 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); + 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", + }; + } + firstFailure ??= r; + } + throw new Error(`DKIM signature verification failed for domain ${firstFailure!.signingDomain}. Reason: ${firstFailure!.status.comment}`); +} 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..6a8258c --- /dev/null +++ b/tests/dkim-keys.test.ts @@ -0,0 +1,120 @@ +/** + * 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 } 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 still verifies first (dns:google)", 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"); +}); + +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..5b8dcd4 100644 --- a/tests/fixtures/doh-stub.mjs +++ b/tests/fixtures/doh-stub.mjs @@ -1,13 +1,24 @@ -// 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; +export function installStub(records = {}, archive = {}) { + globalThis.fetch = async (input) => { + const url = new URL(String(input)); + if (url.pathname === "/api/key") { + 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 || "{}")); +} From 16a0ab97ec055896d26f2cb3dc757cad275231fc Mon Sep 17 00:00:00 2001 From: Divide-By-0 Date: Tue, 29 Sep 2026 16:25:37 -0700 Subject: [PATCH 2/3] fix(dkim): query the archive only after DNS keys fail; retry once on its 429 archive.prove.email allows 10 requests/min per IP and answers 429 with an error object (the helper's own fallback crashes on it). Fetch archived keys only for key-related failures (not body-hash mismatches), retry once after retryAfterSeconds, and name the rate limit in the error. Co-Authored-By: Claude Opus 5.5 --- .../redacted-email-proof/scripts/redacted.mjs | 161 ++++++++++------ src/utils/dkimKeys.ts | 177 ++++++++++++------ tests/dkim-keys.test.ts | 27 ++- tests/fixtures/doh-stub.mjs | 11 +- 4 files changed, 250 insertions(+), 126 deletions(-) diff --git a/skills/redacted-email-proof/scripts/redacted.mjs b/skills/redacted-email-proof/scripts/redacted.mjs index d59d853..01e77c7 100755 --- a/skills/redacted-email-proof/scripts/redacted.mjs +++ b/skills/redacted-email-proof/scripts/redacted.mjs @@ -241,8 +241,32 @@ async function helpers() { const pOf = (record) => /(?:^|;)\s*p\s*=\s*([^;]*)/i.exec(record)?.[1]?.replace(/\s+/g, "") ?? ""; -/** All candidate keys for ._domainkey., deduplicated by p=, revoked (empty p=) dropped. */ -export async function dkimKeyCandidates(name) { +// 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("."); @@ -254,27 +278,24 @@ export async function dkimKeyCandidates(name) { return []; // one resolver being down must not hide keys the other sources have } }; - const archive = async () => { - try { - const url = new URL(DKIM_ARCHIVE_API); - url.searchParams.set("domain", domain); - const rows = await (await fetch(url)).json(); - return rows - .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 })); - } catch { - return []; // archive is best-effort - } - }; + 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(); - return all.filter((c) => { + 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) { @@ -293,57 +314,75 @@ async function runVerifier(h, email, domain, skipBodyHash, resolver) { /** 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 cache = new Map(); - const keys = (name) => { - if (!cache.has(name)) cache.set(name, resolveKeys(name)); - return cache.get(name); - }; const emailStr = Buffer.isBuffer(email) || email instanceof Uint8Array ? Buffer.from(email).toString("latin1") : String(email); - let firstFailure; - // Round i serves candidate i for every selector in the message; stop past the longest list. - let rounds = 1; - 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); - return [pick.record]; + 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); }; - 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; + // 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; } - 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", - }; - } - firstFailure ??= r; } - throw new Error(`DKIM signature verification failed for domain ${firstFailure.signingDomain}. Reason: ${firstFailure.status.comment}`); + 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) { diff --git a/src/utils/dkimKeys.ts b/src/utils/dkimKeys.ts index 39e0bcd..3ee3b61 100644 --- a/src/utils/dkimKeys.ts +++ b/src/utils/dkimKeys.ts @@ -46,8 +46,44 @@ export type DkimKeyResult = DKIMVerificationResult & { keySource: string }; const pOf = (record: string) => /(?:^|;)\s*p\s*=\s*([^;]*)/i.exec(record)?.[1]?.replace(/\s+/g, "") ?? ""; -/** All candidate keys for `._domainkey.`, deduplicated by p=, revoked (empty p=) dropped. */ -export async function dkimKeyCandidates(name: string): Promise { +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 => { @@ -58,30 +94,27 @@ export async function dkimKeyCandidates(name: string): Promise { return []; // REASON: one resolver being down must not hide keys the other sources have } }; - const archive = async (): Promise => { - try { - const url = new URL(DKIM_ARCHIVE_API); - url.searchParams.set("domain", domain); - const rows = (await (await fetch(url)).json()) as { selector: string; value: string; lastSeenAt?: string }[]; - return rows - .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 })); - } catch { - return []; // archive is best-effort - } - }; + 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(); - return all.filter((c) => { + 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) => Promise; +type ResolveKeys = (name: string, withArchive: boolean) => Promise; // eslint-disable-next-line @typescript-eslint/no-explicit-any type RawResult = { [key: string]: any }; @@ -124,55 +157,75 @@ export async function verifyDkimWithKeyCandidates( skipBodyHash = false, resolveKeys: ResolveKeys = dkimKeyCandidates ): Promise { - const cache = new Map>(); - const keys = (name: string) => { - if (!cache.has(name)) cache.set(name, resolveKeys(name)); - return cache.get(name)!; - }; const emailStr = typeof email === "string" ? email : new TextDecoder("latin1").decode(email); - let firstFailure: RawResult | undefined; - // 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; - 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); - return [pick.record]; + 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)!; }; - 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; + // 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; } - 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", - }; - } - firstFailure ??= r; } - throw new Error(`DKIM signature verification failed for domain ${firstFailure!.signingDomain}. Reason: ${firstFailure!.status.comment}`); + const note = archiveError ? ` (${archiveError})` : ""; + throw new Error(`DKIM signature verification failed for domain ${failure!.signingDomain}. Reason: ${failure!.status.comment}${note}`); } diff --git a/tests/dkim-keys.test.ts b/tests/dkim-keys.test.ts index 6a8258c..494eb71 100644 --- a/tests/dkim-keys.test.ts +++ b/tests/dkim-keys.test.ts @@ -16,7 +16,7 @@ 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 } from "./fixtures/doh-stub.mjs"; +import { installStub, restoreFetch, archiveCalls } from "./fixtures/doh-stub.mjs"; const ROOT = join(import.meta.dirname, ".."); const NAME = "sel._domainkey.example.test"; @@ -102,7 +102,7 @@ test("REGRESSION: selector gone from DNS and the signing key is not the archive' assert.equal(site.keySource, "archive"); }); -test("current DNS key still verifies first (dns:google)", async () => { +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) }); @@ -110,6 +110,29 @@ test("current DNS key still verifies first (dns:google)", async () => { 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 () => { diff --git a/tests/fixtures/doh-stub.mjs b/tests/fixtures/doh-stub.mjs index 5b8dcd4..200e3ee 100644 --- a/tests/fixtures/doh-stub.mjs +++ b/tests/fixtures/doh-stub.mjs @@ -3,10 +3,19 @@ // 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; -export function installStub(records = {}, archive = {}) { +/** 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 }); } From bb597030ae0016a76713ab11f2f09be4e992543c Mon Sep 17 00:00:00 2001 From: Divide-By-0 Date: Tue, 29 Sep 2026 16:56:09 -0700 Subject: [PATCH 3/3] docs(maintainer skill): DKIM key candidates and the archive's 10 req/min limit Co-Authored-By: Claude Opus 5.5 --- .agents/skills/redacted-circuit-maintenance/SKILL.md | 11 +++++++++++ 1 file changed, 11 insertions(+) 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.