Email-native multi-party coordination kernel. Verify a reply, sequence it through a workflow, commit it to a tamper-evident git ledger, trigger the next email.
Status — P1 (lift) + m7c (verification) + m7d (triggers) are COMPLETE. Being extracted from gitdone. A consumer can
create()a bound instance andingest()inbound replies end to end: verify + the inbound decoder (DKIM/DMARC auth + MIME parse), sequence routing, inbound preprocessing, outbound, the full git-ledger storage, both sequencing engines (events workflow + crypto sign-off), the document notary with inbound auto-hash capture, the offlineverify()/reverify()primitives + their public email endpoints, and the trigger pillar (12 neutral-templated occasionkinds). 307node --testtests pass with 2 runtime deps; the public surface ships JSDoc-generated, checkJs-gated TypeScript declarations. Next is P2 — validate by rebuilding gitdone on mailproof. Seedocs/(PRD, DESIGN, SPEC).
A lot of coordination is just: ask some named people to confirm something, in an order, and prove they did. mailproof does that entirely over email — no app, no login for participants. They reply from their normal inbox; that's it.
- Verify — each inbound reply is graded by DKIM/DMARC trust level (via
mailauth); the signer's public key is archived so the reply still verifies after key rotation. - Sequence — replies advance one of two generic modes: an events workflow (ordered / parallel steps among named participants) or a crypto sign-off (verified signers — one, several named, or open via a shared address — counted toward a threshold, optionally bound to a hashed document).
- Git ledger — every reply is committed to a per-event git repo. The commit chain is the tamper-evident, offline-verifiable proof: clone it and check it with stock
git, forever, even if the service disappears. - Email triggers — composes and sends the next notification / reminder through your own MTA (Postfix + opendkim). Self-hosted: more config, full control, no third-party mail dependency.
Every inbound reply is committed — even rejected ones (wrong sender, failed DKIM, out of order). A counted flag records whether it advanced state. The audit trail stays complete; trust gates the transition, never the record.
| Phase | State |
|---|---|
| P0 — composition proof (POC) | ✅ npm run poc |
| P1 — lift real modules + tests | ✅ COMPLETE — verify + inbound decoder (DKIM/DMARC auth + MIME parse), sequence routing, inbound preprocessing, outbound, git-ledger storage, workflow + crypto sign-off engines, document notary (incl. auto-hash capture), and the create()/ingest() assembly |
| m7c — verification surface | ✅ COMPLETE — durable DKIM-key archive, offline verify()/reverify(), OTS-proof anchoring, public verify+/reverify+ email endpoints |
| m7d — trigger pillar | ✅ COMPLETE — every kernel-derivable occasion (state/time/bounce/verify) as one of 12 neutral-templated kinds over one composeNotification hook |
| P2 — gitdone depends on mailproof | ⬜ next — validate by rebuilding gitdone on mailproof (non-merging branch) |
npm i mailproof # 2 runtime deps (mailauth, mailparser); Node ≥ 22.5Pure ESM (import, "type": "module") + JSDoc, no consumer build step. The public surface ships JSDoc-generated, strictNullChecks checkJs-gated TypeScript declarations, so import … from 'mailproof' gives TS consumers a checked surface. The git ledger shells out to the git binary directly (no simple-git), so storage stays dependency-free.
Pre-1.0: the API can still change shape between
0.xminors (SemVer 0.x). P2 (rebuilding gitdone on it) is the surface-validation phase.
npm run poc # stdlib + git only: runs a 2-step workflow, prints the ledger + outbox, self-assertsRequires Node ≥ 22.5. The POC has no dependencies; the lifted library has 2 runtime deps — mailauth (DKIM/DMARC/ARC) and mailparser (MIME), both required because verifying/parsing untrusted mail is security-critical (a vetted library, never hand-rolled). Budget: ≤3.
Start at docs/README.md. The PRD covers what mailproof is, who adopts it, and the NO-GO table; DESIGN covers the extraction boundary (what's in mailproof vs. what stays gitdone policy), the planned public API, and the phasing; the decisions log records the design forks with rationale.
Apache-2.0 © hamr0