Skip to content

Add email proof verification to @reclaimprotocol/client - #26

Draft
predatorx7 wants to merge 2 commits into
mainfrom
feat/client-email-verification
Draft

predatorx7 wants to merge 2 commits into
mainfrom
feat/client-email-verification

Conversation

@predatorx7

Copy link
Copy Markdown
Collaborator

Summary

Copies the Reclaim email verification core into @reclaimprotocol/client and adds a consumer verifier for email-v1 proofs. AI-session results from Builder can now carry email proofs, and the client verifies them.

Email entry points

  • @reclaimprotocol/client/email/{core,protocol,contracts,schemas,sender,google,preview,ai} copy the private core's exports one-to-one, under the same names.
  • The copy lives in src/email/core and src/email/lib.
  • The heavy parsing, Google and AI dependencies are optional peers, pinned at the core's exact versions.
  • These entry points are server-only and need Node.js 22.19 or later. Neither the package root nor /api imports them.

Contract changes in the copy

  • EMAIL_PROVIDERS = ['gmail'] and the EmailProvider type.
  • EmailRequest.provider is required, and the request hash covers it.
  • The signed parameters gain emailProvider.
  • authenticatedGmailAddress is renamed authenticatedAddress.

@reclaimprotocol/client/email: verifyEmailProof(proof, { trustedIssuers, mode, request, now, signal })

  • signature mode checks the snapshot and the canonical parameters and context. It checks the keccak identifier and that the EIP-191 signature recovers to a trusted issuer. It also checks the email-proof and raw-email digests, the source kind and the validity window.
  • With request, it also runs every request-binding check that ai-sdk runs, plus a provider check.
  • full mode also re-checks DKIM, re-parses the email and runs the Bubblewrap-sandboxed evidence checks. It needs Linux with bwrap 0.12 or later. Otherwise it throws email-full-verification-unavailable and never falls back to signature.
  • Errors are Boom errors with a reason.
  • A malformed trustedIssuers address throws a 400.

AI-session results (verifyResultFull / results.receive)

An entry with method: 'email' is verified with verifyEmailProof against the entry's email.request.

  • Trust: the issuers trusted are emailIssuers plus the JWKS x-reclaim-email-issuers list.
  • New options: emailVerification ('signature' by default, or 'full') and allowEmailProofs.
  • Fail closed: an entry without email.request fails, as does one whose email.provider, sender or dkimSigner differs from the verified proof.
  • Pins: if the caller pins hashes, proofRecipes or proofValidation.hashes/providerId, email entries fail with email-not-allowed unless allowEmailProofs is set.
  • Expiry: email proof expiry is checked at the result's signed iat, so a redelivered or stored result still verifies.
  • New outcome fields: method, emailProof, emailProvider, sender, dkimSigner, authenticatedAddress, extractedParameters and emailCheck.
  • Reasons: email-issuer-not-trusted, email-proof-invalid, email-not-allowed and email-full-verification-unavailable. Only the last one is retryable.

Sandbox worker fix (differs from the core)

A fresh install resolves strtok3 10.7 or later through file-type. Importing it makes the worker's stdio sockets non-blocking, so large inputs failed with EAGAIN and preview output could be written only in part. The workers now retry on EAGAIN and always write their full output. This bug also exists upstream in the core.

Tests

  • tests/email: tests for verifyEmailProof and verifyResultFull with email entries, using proofs signed in-test with a throwaway key.
  • tests/email/core: 18 of the core's test files (667 tests), ported to node:test through a small compatibility file. Tests that need the document sandbox are skipped on hosts that can't start it.
  • On Linux with bwrap 0.12, all 845 client tests pass, 2 of them macOS-only skips.

Notes

  • Versions are bumped to 0.2.0, because ai-sdk depends on @reclaimprotocol/client@^0.2.0.
  • The optional peers postal-mime 4.0.4 and mailauth 7.1.0 have npm advisories. Upgrading them needs the core's DKIM tests to be re-run.
  • The ./email* exports also have a default condition and typesVersions, so the CommonJS Portal gateway can require() them (Node 22.12+ loads the ESM files).
  • Merge order: this PR, then publish 0.2.0, then ai-sdk 0.3.0, the Portal and Builder.
  • full mode needs user namespaces and /proc mounting in the container.

🤖 Generated with Claude Code

Copy Reclaim's email verification core into @reclaimprotocol/client/email
and verify email proofs from Builder results. Signature checks are the
default; full re-verification of the email runs only on Linux with
Bubblewrap 0.12+ and fails clearly elsewhere.

The copy adds a signed provider field and renames the authenticated
address field. Results trust email issuers from options or Builder's
JWKS (x-reclaim-email-issuers).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
throw new Error('UNKNOWN_SYNTHETIC_CASE')
}

const rsa = generateKeyPairSync('rsa', { modulusLength: 1024 })
CodeQL flagged the start-or-end whitespace regex as polynomial on long
runs of inner whitespace. A plain scan gives the same result.

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

This branch has not been deployed

No deployments
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.

2 participants