Skip to content

DKIM: try every known key for the selector (DNS via Google + Cloudflare, all archived keys) - #25

Merged
Divide-By-0 merged 3 commits into
mainfrom
stack/07-dkim-key-candidates
Sep 30, 2026
Merged

Divide-By-0 merged 3 commits into
mainfrom
stack/07-dkim-key-candidates

Conversation

@Divide-By-0

@Divide-By-0 Divide-By-0 commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Stacked on #24. Merge order: #21 → #23 → #24 → this.

Problem

@zk-email/helpers' verifyDKIMSignature looks the key up only once:

  1. It asks Google DNS-over-HTTPS.
  2. Only if that lookup fails does it try archive.prove.email, and then only the archive's first key for the selector.

So an email fails with "bad signature" even though its signing key is known when:

  • the key was rotated under the same selector. DNS returns the new key, so the archive is never asked.
  • the archive holds several keys for the selector. On amazon.com, 8 of 23 selectors have 2–3 keys, and the signing key isn't always the first.

There is also a rate-limit problem. The archive allows 10 requests per minute per IP and answers a 429 with an error object. The helper's own fallback then crashes with data.find is not a function.

Fix

New src/utils/dkimKeys.ts for the site, with a copy in the CLI:

  • Candidate keys: the Google and Cloudflare DoH answers, then every archived key for the selector, most recently seen first. They are deduplicated by p=, and revoked records (empty p=) are dropped.
  • The archive is queried only when needed: only after the DNS keys fail, and never for a body-hash mismatch, since no key can fix that.
  • 429 handling: it retries once after the server's retryAfterSeconds. If that also fails, the error names the rate limit.
  • Key source is reported: the result has a keySource field (dns:google / dns:cloudflare / archive). inspect --json shows it, and prove notes when the key came from the archive.
  • Same interface as before: the result shape and error message match verifyDKIMSignature. The key modulus is read with WebCrypto, so there is no node-forge dependency.

This doesn't accept anything new in kind: the archive was already a fallback, and verify checks the proof's key hash against DNS and the archive on its own.

Tests

  • tests/dkim-keys.test.ts: 6 tests, using a synthetic email, throwaway keys, and stubbed DNS and archive.
    • Both regression tests first assert that the old helper rejects the email, then that the site and CLI both accept it with keySource: archive.
  • Full suite: 25/25. tsc passes, and vite build passes.

Real corpus (DKIM step only, on a separate Linux box)

Only the 73 emails that failed DKIM with the old lookup were re-run. Archive calls were spaced 6.5 s apart.

  • Old lookup: 27 of the 73 pass once paced, so they had only failed because of the rate-limit crash. That leaves 46 real failures:
    • 24 body-hash mismatches;
    • 7 with no signature for the domain;
    • 15 key-related (12 bad signature, 2 DNS failures, 1 no key).
  • New lookup on those 46: 12 now pass, all with archived keys (large senders that rotate keys under reused selectors). Of the 15 key-related failures, only 3 remain.
  • Archive calls: 49 with the new lookup, against 198 with the old one on the 73.
  • Proofs of the 12: all 12 proved and verified locally with this branch's CLI, all using archived keys.
    • 7 large-tier proofs, 35–39 s each; 5 XL-tier proofs, 66–71 s each.
    • Corpus total goes from 76 to 88 of 132 emails proved.

🤖 Generated with Claude Code

Divide-By-0 and others added 2 commits September 29, 2026 16:19
…S, 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 7d618a47-5425-49ae-99af-47ba902c0b5d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

…min limit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Divide-By-0

Copy link
Copy Markdown
Member Author

Web check: I ran the site's own modules in headless Chromium against a local dev server.

  • Rotated-key synthetic email: verifyDkimWithKeyCandidates returns keySource: archive, and the key modulus parsed by WebCrypto matches the signing key.
  • Real key fetches from the browser work (no CORS problems):
    • Google and Cloudflare DoH: Yahoo's s2048 selector returns the DNS key; Cloudflare's identical copy is deduplicated.
    • The archive: an amazon.com selector returns 3 archived keys.
  • The upload parser (parseEmlFile, which reads the file as UTF-8 like UploadModal) verifies 2 of the 12 recovered emails, both with archived keys. The CLI verifies the same files.

🤖 Generated with Claude Code

@Divide-By-0
Divide-By-0 changed the base branch from stack/05-xl-tier-v2 to main September 30, 2026 02:03
@Divide-By-0 Divide-By-0 reopened this Sep 30, 2026
@Divide-By-0
Divide-By-0 merged commit ac35414 into main Sep 30, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant