@broberg/mail-identity 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,232 @@
-# Temporary Holding Version
+# @broberg/mail-identity
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Is this inbound mail **provably** from who the `From:` field claims?
+
+Four pure functions, zero dependencies, no I/O. They read addresses and
+`Authentication-Results` **the way the grammar does, not the way a regex does**.
+
+```bash
+npm i @broberg/mail-identity
+```
+
+```ts
+import { extractAddresses, addressesMatch, splitPlusTag, readAuthResults } from "@broberg/mail-identity";
+
+extractAddresses('"cb@webhouse.dk" <attacker@evil.dk>');  // ['attacker@evil.dk']
+addressesMatch(mail.from, ["cb@webhouse.dk"]);            // false
+splitPlusTag("buddy+whop@broberg.ai");                    // { address: 'buddy@broberg.ai', tag: 'whop' }
+readAuthResults(mail.headers["authentication-results"]);  // { verdict: 'pass' | 'fail' | 'conflicted' | 'no-verdict', … }
+```
+
+## What it owns, and what it refuses to own
+
+| | |
+| --- | --- |
+| **What an address is** | `extractAddresses` · `splitPlusTag` · `addressesMatch` |
+| **What the auth header says** | `readAuthResults` |
+| **What a match MEANS** | **not ours** |
+
+The third row is the design. "May this mail wake an agent" is authorisation, and
+it stays at your call-site where you can read it. Move it in here and every
+consumer inherits a policy it cannot see, and a change to that policy ships
+silently as a patch release.
+
+## Why this package exists
+
+Two codebases independently wrote this same rule, and **both had holes in it,
+found the same day, in each codebase separately.** The value here is not the
+code — it is the cases in `test/`, every one of them an attack that **worked**
+against a live implementation. Each looks correct until someone builds the
+counter-example.
+
+## API
+
+### `extractAddresses(field): string[]`
+
+Every address in a `From`/`To`/`Cc` field, lowercased. **A display name never
+contributes one.**
+
+```ts
+extractAddresses('Christian <cb@webhouse.dk>');            // ['cb@webhouse.dk']
+extractAddresses('cb@webhouse.dk <attacker@evil.dk>');     // ['attacker@evil.dk']
+extractAddresses('"x <buddy@broberg.ai>, y" <a@evil.dk>'); // ['a@evil.dk']
+extractAddresses('"Broberg, Christian" <cb@webhouse.dk>'); // ['cb@webhouse.dk']
+```
+
+The second line killed `from.includes(owner)`, which accepted the owner's
+address written as display **text** — four call-paths reproduced it. The third
+killed `field.split(',')`, which cuts a quoted display name in half *before*
+quoting is understood; end-to-end it produced `isOwnerInstruction: true` for a
+mail from `attacker@evil.dk` addressed to `victim@evil.dk`. The fourth is the
+same bug's benign half — `Broberg, Christian` is just how a directory writes a
+name, and a too-eager split turns it into a junk address.
+
+### `addressesMatch(field, known): boolean`
+
+Equality on extracted addresses. **Never a substring, prefix or suffix.** Both
+sides go through the same extraction and the same plus-tag normalisation, so
+`known` may be bare addresses or full fields. An empty or unparseable field
+matches nothing.
+
+### `splitPlusTag(address): { address, tag }`
+
+```ts
+splitPlusTag("buddy+whop@broberg.ai"); // { address: 'buddy@broberg.ai', tag: 'whop' }
+splitPlusTag("buddy@broberg.ai");      // { address: 'buddy@broberg.ai', tag: null }
+```
+
+**The tag informs; the address proves.** An unknown tag must still match. A tag
+able to *refuse* a match would be authorisation disguised as routing, and a typo
+(`buddy+whopp@`) would make mail vanish silently. `+admin`, `+deploy`, `+urgent`
+must never mean anything privileged — anyone can type them.
+
+**Split after `extractAddresses`, never on a raw field.** The other way round
+puts you back in the impersonation hole wearing a new hat.
+
+### `readAuthResults(header): AuthResults`
+
+```ts
+type AuthVerdict = "pass" | "fail" | "conflicted" | "no-verdict";
+```
+
+**Four outcomes, not three, and never two.**
+
+| outcome | meaning |
+| --- | --- |
+| `pass` | a dmarc verdict exists and everything present passed |
+| `fail` | at least one method's verdicts unambiguously did not pass |
+| `conflicted` | one method carries **both** a passing and a failing verdict |
+| `no-verdict` | nothing readable to judge by |
+
+Also returned: `spf` / `dkim` / `dmarc` as read, `conflicted` (which methods
+disagreed), and `reason` — always set, including on `pass`, because a caller
+logging a decision needs the why.
+
+## Three things that will bite you
+
+### 1. A missing verdict is not a failure — and the inversion is the whole point
+
+A genuine **self-sent** mail carries **no verdict at all**: the header is written
+by the *receiving* server, and a mail from your own authenticated session never
+crosses that boundary. An external **forgery** of the same `From:` **does** cross
+it, gets a verdict, and that verdict **fails**.
+
+So a gate demanding `'pass'` rejects precisely the mail the feature exists for,
+while letting nothing extra in. Never collapse `no-verdict` into either
+neighbour.
+
+### 2. The permissive outcome must never be your `default` branch
+
+A new outcome silently lands in `default`. If `default` is the accepting one,
+**adding an outcome widens your gate.**
+
+This is not hypothetical. The first consumer hit it while adding the fourth
+outcome *they had argued for*: `conflicted` fell into the `no-verdict` branch,
+because that branch was the default — and the `no-verdict` branch accepts the
+owner's own address (see #1). An injected verdict would have become the owner's
+instruction. Yesterday's hole, reopened by their own cleanup, and **invisible to
+every test of the reader.**
+
+```ts
+import { readAuthResults, addressesMatch, type AuthVerdict } from "@broberg/mail-identity";
+
+type Decision = "accept-owner" | "accept-external" | "reject";
+
+function decide(verdict: AuthVerdict, fromOwner: boolean): Decision {
+  switch (verdict) {
+    case "pass":
+      return fromOwner ? "accept-owner" : "accept-external";
+    case "no-verdict":
+      return fromOwner ? "accept-owner" : "reject";   // permissive — never the default
+    case "fail":
+      return "reject";
+    case "conflicted":
+      return "reject";                                // YOUR policy, on one findable line
+    default: {
+      const unhandled: never = verdict;               // compile-time: a fifth outcome breaks the build
+      void unhandled;
+      return "reject";                                // runtime: the REJECTING answer
+    }
+  }
+}
+```
+
+**Both layers, and neither is redundant.** `never` protects only the consumers
+that compile — the input is an untrusted header, and a JavaScript consumer has
+no type at all. A package that defends itself with `never` alone defends half its
+consumers.
+
+**And put the guard on the DECISION, not on the reader.** Asserting that
+`readAuthResults` returns `'conflicted'` proves nothing about what you do with
+it. The test that matters asserts the resulting *authorisation*. Ours is in
+`test/consumer-trap.test.ts` — the snippet above, executable.
+
+### 3. `conflicted` is not "probably an attack"
+
+RFC 8601 **Appendix B.6**, *"Service Provided, Multi-tiered Authentication
+Done"* — the standard's own example of **normal operation**:
+
+```
+dkim=pass reason="good signature" header.i=@mail-router.example.net;
+dkim=fail reason="bad signature" header.i=@newyork.example.com
+```
+
+Two signatures, one good, one bad, in one header. **Syntactically identical to a
+duplicate-injection attack**, and not distinguishable from one by reading the
+header. So this package does not try: it reports the disagreement and you decide.
+
+Fail-closed is a perfectly good policy. It is just not ours to choose for
+everyone — and if you pick it, know that you are condemning an RFC-documented
+legal case, which is a trade, not a free win.
+
+## Notes from the corpus
+
+- **The anchor is an allowlist.** A verdict must stand at the start of the header
+  or after a real separator (whitespace, `;`, `,` — RFC 8601's own). `\b` was the
+  original and a dot is a word boundary, so `\bdmarc=` matched inside
+  `header.dmarc=pass`. The denylist that replaced it left 27 printable characters
+  open, including a colon. The test sweeps the **entire** printable character set,
+  because a hand-written list of 9 found 3 of the 27.
+- **Quoted strings and comments are blanked before matching.** They are two more
+  places a verdict cannot stand, and both manufactured verdicts in the prior
+  implementation: `dkim=pass reason="relayed dmarc=pass ok"` turned `no-verdict`
+  into `pass`. A space inside a quoted string is a legal separator to a regex and
+  no separator at all to the grammar. **That one sentence explains every parsing
+  bug this package was built to end**, and it is why the answer is a tokeniser
+  rather than another regex patch.
+- **All verdicts are read, never the first.** "First wins" lets an injected
+  `dmarc=pass` drown out the real `dmarc=fail`.
+- **An unambiguous fail beats a conflict.** A method where *no* verdict passed is
+  stronger evidence than a disagreement elsewhere. Backwards, and a genuine
+  rejection is downgraded to "cannot determine" — which a lenient consumer lets
+  through.
+- **A header that does not parse to the end yields nothing.** An unterminated
+  quote or comment blanks every verdict after it while leaving earlier ones
+  standing; erasing a trailing `dmarc=fail` and keeping a leading `spf=pass` is
+  strictly useful to an attacker.
+- **Read the topmost `Authentication-Results` only.** RFC 8601 B.5 shows two,
+  written by two MTAs, disagreeing. Concatenate every instance and you are asking
+  two machines one question and getting the disagreement you asked for.
+- **The RFC cannot prove the accept path.** `dmarc=` appears **zero** times in RFC
+  8601 — the three "DMARC" hits are all bibliography. Since `pass` requires a
+  dmarc verdict (it is the only method that binds `From:` to what passed), every
+  RFC example yields `no-verdict`, `fail` or `conflicted`. The RFC is the best
+  corpus in existence for the *parser* and contributes **no positive controls**.
+  That is pinned as a number in `test/rfc-8601-examples.test.ts`, so it breaks if
+  anyone adds a fixture believing otherwise.
+
+## Testing
+
+```bash
+pnpm test          # the suite
+node test/mutations.mjs   # revert each security decision, one at a time
+```
+
+The mutation harness is the part worth copying. A green suite proves nothing on
+its own; it checks that every reverted decision reddens a **different,
+non-overlapping** set of tests. A mutation that reddens everything only proves
+the suite runs, and one that reddens nothing means the decision is untested. It
+found a real gap in this suite: two different defects reddened identical sets, so
+a reader would have been sent to the wrong line.
+
+MIT · part of the [broberg.ai](https://discovery.broberg.ai) shared inventory.

package/dist/index.cjs

@@ -0,0 +1,170 @@
+'use strict';
+
+// src/index.ts
+var METHODS = ["spf", "dkim", "dmarc"];
+function maskQuotedAndComments(s) {
+  const out = s.split("");
+  let quoted = false;
+  let comment = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if ((quoted || comment > 0) && c === "\\" && i + 1 < s.length) {
+      out[i] = " ";
+      out[i + 1] = " ";
+      i++;
+      continue;
+    }
+    if (quoted) {
+      out[i] = " ";
+      if (c === '"') quoted = false;
+      continue;
+    }
+    if (comment > 0) {
+      if (c === "(") comment++;
+      else if (c === ")") comment--;
+      out[i] = " ";
+      continue;
+    }
+    if (c === '"') {
+      quoted = true;
+      out[i] = " ";
+      continue;
+    }
+    if (c === "(") {
+      comment++;
+      out[i] = " ";
+      continue;
+    }
+  }
+  return { masked: out.join(""), malformed: quoted || comment > 0 };
+}
+function normalise(s) {
+  const t = s.trim().toLowerCase();
+  return t.length > 0 ? t : null;
+}
+function addressOfPart(raw, masked, from, to) {
+  let open = -1;
+  let close = -1;
+  let depth = 0;
+  for (let i = from; i < to; i++) {
+    const c = masked[i];
+    if (c === "<") {
+      if (depth === 0) open = i;
+      depth++;
+    } else if (c === ">" && depth > 0) {
+      depth--;
+      if (depth === 0) {
+        close = i;
+        break;
+      }
+    }
+  }
+  if (open >= 0 && close > open) return normalise(raw.slice(open + 1, close));
+  if (open >= 0) return normalise(raw.slice(from, to));
+  return normalise(masked.slice(from, to));
+}
+function extractAddresses(field) {
+  if (!field) return [];
+  const { masked } = maskQuotedAndComments(field);
+  const out = [];
+  let start = 0;
+  let angle = 0;
+  const flush = (end) => {
+    const a = addressOfPart(field, masked, start, end);
+    if (a) out.push(a);
+    start = end + 1;
+  };
+  for (let i = 0; i < masked.length; i++) {
+    const c = masked[i];
+    if (c === "<") angle++;
+    else if (c === ">" && angle > 0) angle--;
+    else if (c === "," && angle === 0) flush(i);
+  }
+  flush(masked.length);
+  return out;
+}
+function splitPlusTag(address) {
+  const at = address.indexOf("@");
+  if (at < 0 || address.indexOf("@", at + 1) !== -1) return { address, tag: null };
+  const plus = address.indexOf("+");
+  if (plus < 0 || plus > at) return { address, tag: null };
+  const tag = address.slice(plus + 1, at);
+  return { address: address.slice(0, plus) + address.slice(at), tag: tag || null };
+}
+function addressesMatch(field, known) {
+  const present = new Set(extractAddresses(field).map((a) => splitPlusTag(a).address));
+  if (present.size === 0) return false;
+  const list = typeof known === "string" ? [known] : known;
+  return list.some(
+    (k) => extractAddresses(k).some((a) => present.has(splitPlusTag(a).address))
+  );
+}
+function readAuthResults(header) {
+  if (!header || !header.trim()) {
+    return {
+      verdict: "no-verdict",
+      conflicted: [],
+      reason: "no Authentication-Results header \u2014 the sender is unproven, which is not the same as disproven"
+    };
+  }
+  const { masked, malformed } = maskQuotedAndComments(header);
+  if (malformed) {
+    return {
+      verdict: "no-verdict",
+      conflicted: [],
+      reason: "unterminated quoted string or comment \u2014 the header could not be parsed to the end, and a verdict read out of the readable half would be a verdict an attacker chose the boundary of"
+    };
+  }
+  const found = {};
+  const conflicted = [];
+  for (const method of METHODS) {
+    const re = new RegExp(`(?<=^|[\\s;,])${method}\\s*(?:/\\s*\\d+\\s*)?=\\s*([a-z]+)`, "gi");
+    const verdicts = [...masked.matchAll(re)].map((m) => m[1].toLowerCase());
+    if (verdicts.length === 0) continue;
+    const passed = verdicts.filter((v) => v === "pass").length;
+    if (passed > 0 && passed < verdicts.length) conflicted.push(method);
+    found[method] = passed === verdicts.length ? "pass" : verdicts.find((v) => v !== "pass");
+  }
+  if (Object.keys(found).length === 0) {
+    return {
+      verdict: "no-verdict",
+      conflicted: [],
+      reason: "Authentication-Results was present but carried no readable spf/dkim/dmarc verdict"
+    };
+  }
+  const failed = METHODS.filter(
+    (m) => found[m] !== void 0 && found[m] !== "pass" && !conflicted.includes(m)
+  );
+  if (failed.length > 0) {
+    return {
+      verdict: "fail",
+      ...found,
+      conflicted,
+      reason: `rejected: ${failed.map((m) => `${m}=${found[m]}`).join(", ")}`
+    };
+  }
+  if (conflicted.length > 0) {
+    return {
+      verdict: "conflicted",
+      ...found,
+      conflicted,
+      reason: `contradictory verdicts for ${conflicted.join(", ")} \u2014 the header carries both a pass and a non-pass. This is legal multi-tiered authentication (RFC 8601 B.6) OR an injected verdict, and the header cannot tell you which. Your call.`
+    };
+  }
+  if (found.dmarc === void 0) {
+    return {
+      verdict: "no-verdict",
+      ...found,
+      conflicted,
+      reason: "no dmarc verdict \u2014 the From: field is not bound to whatever did pass"
+    };
+  }
+  return { verdict: "pass", ...found, conflicted, reason: "spf/dkim/dmarc pass" };
+}
+
+exports.addressesMatch = addressesMatch;
+exports.extractAddresses = extractAddresses;
+exports.readAuthResults = readAuthResults;
+exports.splitPlusTag = splitPlusTag;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @broberg/mail-identity — is this inbound mail provably from who the From:\n * field claims?\n *\n * Four pure functions, no I/O, no dependencies. They answer two questions and\n * refuse a third:\n *\n *   WHAT IS AN ADDRESS?          extractAddresses · splitPlusTag · addressesMatch\n *   WHAT DOES THE HEADER SAY?    readAuthResults\n *   WHAT DOES A MATCH MEAN?      NOT OURS. That is authorisation, and it stays\n *                                at the call-site where it can be read.\n *\n * The third line is the design. Moving an authorisation decision into a shared\n * dependency would build something worse than the drift it replaces: every\n * consumer inherits a policy it cannot see, and a change to that policy ships\n * silently as a patch release.\n *\n * ORIGIN: buddy and cardmem independently wrote this same rule, and BOTH had\n * holes in it, found the same day in each codebase separately. The value here is\n * not the code — it is the cases in test/, every one of them an attack that\n * WORKED against a live implementation. Each looks correct until someone builds\n * the counter-example.\n */\n\n/**\n * What the Authentication-Results header says. FOUR outcomes, not three, and\n * not two.\n *\n *   pass         a dmarc verdict exists and everything present passed\n *   fail         at least one method's verdicts unambiguously did not pass\n *   conflicted   one method carries BOTH a passing and a failing verdict\n *   no-verdict   nothing readable to judge by\n *\n * `conflicted` exists because RFC 8601 Appendix B.6 — \"Service Provided,\n * Multi-tiered Authentication Done\", the standard's own example of NORMAL\n * OPERATION — is SYNTACTICALLY IDENTICAL to a duplicate-injection attack:\n *\n *     dkim=pass reason=\"good signature\" header.i=@mail-router.example.net;\n *     dkim=fail reason=\"bad signature\" header.i=@newyork.example.com\n *\n * Two signatures, one good, one bad, in one header. Nothing in the header\n * distinguishes that from an attacker appending `dkim=pass`. So this package\n * does not try: it REPORTS the disagreement and the caller decides. Fail-closed\n * is a perfectly good policy — it is just not ours to choose for everyone.\n *\n * `no-verdict` must NEVER collapse into `pass`, and the inversion is why it\n * matters more than it looks: a genuine SELF-SENT mail has no verdict at all\n * (the header is written by the RECEIVING server, and a mail from your own\n * authenticated session never crosses that boundary), while an external forgery\n * HAS one and it FAILS. A gate demanding `pass` rejects precisely the mail the\n * feature exists for.\n */\nexport type AuthVerdict = \"pass\" | \"fail\" | \"conflicted\" | \"no-verdict\";\n\n/** The three methods that say something about the sending domain. */\nexport type AuthMethod = \"spf\" | \"dkim\" | \"dmarc\";\n\nconst METHODS: readonly AuthMethod[] = [\"spf\", \"dkim\", \"dmarc\"];\n\nexport interface AuthResults {\n  verdict: AuthVerdict;\n  /** Per-method result as read. `pass` only when every verdict for it passed. */\n  spf?: string;\n  dkim?: string;\n  dmarc?: string;\n  /** Methods carrying BOTH a passing and a failing verdict. Empty unless `conflicted`. */\n  conflicted: readonly AuthMethod[];\n  /** Always set, including on `pass` — a caller logging a decision needs the why. */\n  reason: string;\n}\n\n/**\n * A view of `s` in which every quoted-string and every (nested) comment — and\n * their delimiters — is replaced by a SPACE, position for position.\n *\n * THIS IS THE WHOLE TRICK, and it is what a regex over the raw string cannot do.\n * Both grammars we parse (RFC 5322 address lists, RFC 8601 auth results) have\n * quoting, and in both a comment is defined to be whitespace. A regex has\n * neither notion, so it sees a legal separator wherever there is a space —\n * INCLUDING the spaces inside a quoted string. Measured against the prior\n * implementation, all three of these came from exactly that:\n *\n *   'Authentication-Results: …; dkim=pass reason=\"relayed dmarc=pass ok\"'\n *      → no-verdict became PASS. Text inside a reason string became a verdict.\n *\n *   'Authentication-Results: …; dkim=pass (relayed dmarc=pass ok)'\n *      → same, via a comment.\n *\n *   'To: \"x <buddy@broberg.ai>, y\" <attacker@evil.dk>'\n *      → split-on-comma cut the quoted display name in half, and the half\n *        carried an <addr> that was only ever decoration. A display name\n *        contributed an address, which is the single property this package\n *        exists to guarantee it cannot.\n *\n * Replacing with a space rather than DELETING is deliberate: deletion joins the\n * neighbours, so `dmar(x)c=pass` would become the verdict `dmarc=pass` out of\n * text that is not one. A comment is whitespace; blanking says exactly that.\n *\n * Unterminated quotes and comments blank the remainder of the string, and are\n * reported as `malformed` so a caller of this helper can refuse to read a\n * PARTIAL result out of a header it could not finish parsing. That distinction\n * is not pedantry — the qualifier values in an auth header (`smtp.mailfrom=`,\n * `header.i=`) come from the message, so an unterminated delimiter there would\n * blank every verdict AFTER it while leaving the earlier ones standing. Erasing\n * a trailing `dmarc=fail` and keeping a leading `spf=pass` is a strictly useful\n * outcome for an attacker, so a header that does not parse yields nothing.\n */\nfunction maskQuotedAndComments(s: string): { masked: string; malformed: boolean } {\n  const out = s.split(\"\");\n  let quoted = false;\n  let comment = 0;\n\n  for (let i = 0; i < s.length; i++) {\n    const c = s[i]!;\n\n    if ((quoted || comment > 0) && c === \"\\\\\" && i + 1 < s.length) {\n      out[i] = \" \";\n      out[i + 1] = \" \";\n      i++;\n      continue;\n    }\n    if (quoted) {\n      out[i] = \" \";\n      if (c === '\"') quoted = false;\n      continue;\n    }\n    if (comment > 0) {\n      if (c === \"(\") comment++;\n      else if (c === \")\") comment--;\n      out[i] = \" \";\n      continue;\n    }\n    if (c === '\"') {\n      quoted = true;\n      out[i] = \" \";\n      continue;\n    }\n    if (c === \"(\") {\n      comment++;\n      out[i] = \" \";\n      continue;\n    }\n  }\n\n  return { masked: out.join(\"\"), malformed: quoted || comment > 0 };\n}\n\n/** Lowercase + trim, or null when nothing is left. */\nfunction normalise(s: string): string | null {\n  const t = s.trim().toLowerCase();\n  return t.length > 0 ? t : null;\n}\n\n/**\n * The address of ONE address-list entry, given the raw field and its mask.\n *\n * Angle brackets are located in the MASKED view, so a `<` inside a quoted\n * display name is simply not there to be found — but the address itself is\n * sliced from the RAW string, so a quoted local part (`<\"odd name\"@example.com>`)\n * survives intact.\n */\nfunction addressOfPart(raw: string, masked: string, from: number, to: number): string | null {\n  let open = -1;\n  let close = -1;\n  let depth = 0;\n\n  for (let i = from; i < to; i++) {\n    const c = masked[i]!;\n    if (c === \"<\") {\n      if (depth === 0) open = i;\n      depth++;\n    } else if (c === \">\" && depth > 0) {\n      depth--;\n      if (depth === 0) {\n        close = i;\n        break;\n      }\n    }\n  }\n\n  if (open >= 0 && close > open) return normalise(raw.slice(open + 1, close));\n\n  // An UNTERMINATED '<' is malformed. Hand back the part as it stands rather\n  // than guessing which half was meant to be the address — something that\n  // matches nothing beats something that might match the owner.\n  if (open >= 0) return normalise(raw.slice(from, to));\n\n  // No angle brackets: the address is the bare text, which is the MASKED text —\n  // so a comment such as `cb@webhouse.dk (Christian)` contributes nothing.\n  return normalise(masked.slice(from, to));\n}\n\n/**\n * Every address in a From/To/Cc field. A DISPLAY NAME NEVER CONTRIBUTES ONE.\n *\n *   'Christian Broberg <cb@webhouse.dk>'          → ['cb@webhouse.dk']\n *   'A <a@x.dk>, b@y.dk'                          → ['a@x.dk', 'b@y.dk']\n *   '\"cb@webhouse.dk\" <attacker@evil.dk>'         → ['attacker@evil.dk']\n *   '\"x <buddy@broberg.ai>, y\" <a@evil.dk>'       → ['a@evil.dk']\n *   '\"Broberg, Christian\" <cb@webhouse.dk>'       → ['cb@webhouse.dk']\n *\n * The first counter-example killed `from.includes(owner)`, which accepted the\n * owner's address written as DISPLAY TEXT — four call-paths reproduced it. The\n * second and third killed `field.split(',')`, which cuts a quoted display name\n * in half before quoting is understood. Both were live; neither was theoretical.\n *\n * Addresses are lowercased. Local parts are formally case-sensitive (RFC 5321),\n * but no provider we send through treats them that way, and NOT normalising\n * would mean `CB@webhouse.dk` fails an owner check that `cb@webhouse.dk` passes\n * — a comparison anyone can sidestep with the shift key.\n */\nexport function extractAddresses(field: string | null | undefined): string[] {\n  if (!field) return [];\n  // A malformed field is not rejected outright here: blanking already makes the\n  // unparseable remainder match nothing, and an address list has no equivalent\n  // of the partial-verdict problem — an address either equals a known one or it\n  // does not.\n  const { masked } = maskQuotedAndComments(field);\n\n  const out: string[] = [];\n  let start = 0;\n  let angle = 0;\n\n  const flush = (end: number): void => {\n    const a = addressOfPart(field, masked, start, end);\n    if (a) out.push(a);\n    start = end + 1;\n  };\n\n  for (let i = 0; i < masked.length; i++) {\n    const c = masked[i]!;\n    if (c === \"<\") angle++;\n    else if (c === \">\" && angle > 0) angle--;\n    else if (c === \",\" && angle === 0) flush(i);\n  }\n  flush(masked.length);\n\n  return out;\n}\n\n/**\n * Split a plus-tag off an address.\n *\n *   'buddy+whop@broberg.ai'  →  { address: 'buddy@broberg.ai', tag: 'whop' }\n *   'buddy@broberg.ai'       →  { address: 'buddy@broberg.ai', tag: null }\n *\n * TWO RULES CARRY THE SECURITY, and they are the reason this is separate from\n * matching rather than folded into it:\n *\n * 1. THE TAG INFORMS, THE ADDRESS PROVES. An unknown tag must still match. A tag\n *    able to REFUSE a match would be authorisation disguised as routing, and a\n *    typo (`buddy+whopp@`) would make mail vanish silently. `+admin`, `+deploy`\n *    and `+urgent` must never mean anything privileged — anyone can type them.\n *\n * 2. SPLIT AFTER extractAddresses(), NEVER on a raw field. Do it the other way\n *    round and you are back in the impersonation hole wearing a new hat: a\n *    display name must not contribute an address, and that property lives in the\n *    extraction.\n *\n * An address with more than one '@' is malformed and is returned UNTOUCHED:\n * `buddy+x@evil.com@broberg.ai` must never be reshaped into something valid.\n *\n * `tag` is `null`, not `undefined`, so that a fixture written as\n * `{ address: 'x', tag: undefined }` cannot pass a deep-equality check against\n * `{ address: 'x' }`. Two different facts, two distinguishable values.\n */\nexport function splitPlusTag(address: string): { address: string; tag: string | null } {\n  const at = address.indexOf(\"@\");\n  if (at < 0 || address.indexOf(\"@\", at + 1) !== -1) return { address, tag: null };\n\n  const plus = address.indexOf(\"+\");\n  if (plus < 0 || plus > at) return { address, tag: null };\n\n  // From the FIRST '+': 'buddy+a+b@' has the tag 'a+b', not 'b'.\n  const tag = address.slice(plus + 1, at);\n  return { address: address.slice(0, plus) + address.slice(at), tag: tag || null };\n}\n\n/**\n * Does any address in `field` EQUAL any address in `known`?\n *\n * Equality on extracted addresses. Never a substring, never a prefix, never a\n * suffix — `cb@webhouse.dk.evil.com` and `\"cb@webhouse.dk\" <x@evil.dk>` and\n * `buddy@broberg.ai.evil.com` are all rejected, and each of the three was\n * accepted by a live implementation this week.\n *\n * Both sides go through the SAME extraction and the SAME plus-tag\n * normalisation, so `known` may be given as bare addresses or as full fields.\n * An empty or unparseable `field` matches nothing.\n */\nexport function addressesMatch(\n  field: string | null | undefined,\n  known: string | readonly string[],\n): boolean {\n  const present = new Set(extractAddresses(field).map((a) => splitPlusTag(a).address));\n  if (present.size === 0) return false;\n\n  const list = typeof known === \"string\" ? [known] : known;\n  return list.some((k) =>\n    extractAddresses(k).some((a) => present.has(splitPlusTag(a).address)),\n  );\n}\n\n/**\n * Read an Authentication-Results header (RFC 8601). Reports; does not judge.\n *\n * ANCHORING IS AN ALLOWLIST, NOT A DENYLIST. `\\b` was the original, and a dot is\n * a word boundary, so `\\bdmarc=` matched INSIDE `header.dmarc=pass` — a\n * qualified key read as a verdict:\n *\n *   'header.dmarc=pass header.dkim=pass header.spf=pass; dmarc=fail; dkim=fail; spf=fail'\n *     → PASS, while every real verdict in it is `fail`.\n *\n * The first fix was a denylist, `(?<![\\w.-])`. Swept over the whole printable\n * character set it left 27 characters open, including a colon — `arc:dmarc=pass`\n * read as a pass. A denylist has to predict every character a future vendor\n * invents. So: a verdict must stand at the start of the header or after a REAL\n * separator (whitespace, `;` or `,` — RFC 8601's own), and anything else in\n * front of it makes it a qualified key rather than a verdict.\n *\n * Quoted strings and comments are blanked before matching (see\n * maskQuotedAndComments) — they are two more places a verdict cannot stand, and\n * both manufactured verdicts in the prior implementation.\n *\n * ALL occurrences are collected, not the first: a header can carry more than one\n * verdict per method, and \"first wins\" lets an injected `dmarc=pass` drown out\n * the real `dmarc=fail`.\n *\n * PRECEDENCE IS SECURITY-BEARING. An unambiguous fail beats a conflict:\n *\n *   'dkim=pass; dkim=fail; dmarc=fail'  →  fail, NOT conflicted\n *\n * A method where NO verdict passed is stronger evidence than a disagreement\n * somewhere else. Get the order wrong and a genuine, unambiguous rejection is\n * downgraded to \"cannot determine\" — which a lenient caller then lets through.\n */\nexport function readAuthResults(header: string | null | undefined): AuthResults {\n  if (!header || !header.trim()) {\n    return {\n      verdict: \"no-verdict\",\n      conflicted: [],\n      reason: \"no Authentication-Results header — the sender is unproven, which is not the same as disproven\",\n    };\n  }\n\n  const { masked, malformed } = maskQuotedAndComments(header);\n  if (malformed) {\n    return {\n      verdict: \"no-verdict\",\n      conflicted: [],\n      reason:\n        \"unterminated quoted string or comment — the header could not be parsed to the end, \" +\n        \"and a verdict read out of the readable half would be a verdict an attacker chose the boundary of\",\n    };\n  }\n\n  const found: Partial<Record<AuthMethod, string>> = {};\n  const conflicted: AuthMethod[] = [];\n\n  for (const method of METHODS) {\n    // The optional `/1` is RFC 8601's method-version, and the `\\s*` around it\n    // and around `=` is CFWS — comments are already spaces by now. Appendix B.7,\n    // the RFC's own \"perfectly legal\" example, is written\n    // `dkim (Because I like it) / 1 (One yay) = (wait for it) fail`, and a\n    // parser too narrow to read it would report no-verdict on a header that\n    // plainly says fail. Rejecting genuine mail is the equally expensive\n    // opposite error.\n    const re = new RegExp(`(?<=^|[\\\\s;,])${method}\\\\s*(?:/\\\\s*\\\\d+\\\\s*)?=\\\\s*([a-z]+)`, \"gi\");\n    const verdicts = [...masked.matchAll(re)].map((m) => m[1]!.toLowerCase());\n    if (verdicts.length === 0) continue;\n\n    const passed = verdicts.filter((v) => v === \"pass\").length;\n    // DISAGREEMENT and UNIFORMLY-NOT-PASSED are two different facts:\n    //   dmarc=fail              a real, unambiguous rejection\n    //   dkim=pass … dkim=fail   a disagreement (RFC B.6 legal, OR injected)\n    // Collapsing both into `fail` hides the difference from the caller and puts\n    // the policy here, where no consumer can change it. A REPEATED AGREEING\n    // verdict is not a conflict — a relay may legitimately repeat itself, and\n    // reading that as tampering blocks real mail.\n    if (passed > 0 && passed < verdicts.length) conflicted.push(method);\n    found[method] = passed === verdicts.length ? \"pass\" : verdicts.find((v) => v !== \"pass\")!;\n  }\n\n  if (Object.keys(found).length === 0) {\n    return {\n      verdict: \"no-verdict\",\n      conflicted: [],\n      reason: \"Authentication-Results was present but carried no readable spf/dkim/dmarc verdict\",\n    };\n  }\n\n  const failed = METHODS.filter(\n    (m) => found[m] !== undefined && found[m] !== \"pass\" && !conflicted.includes(m),\n  );\n  if (failed.length > 0) {\n    return {\n      verdict: \"fail\",\n      ...found,\n      conflicted,\n      reason: `rejected: ${failed.map((m) => `${m}=${found[m]}`).join(\", \")}`,\n    };\n  }\n\n  if (conflicted.length > 0) {\n    return {\n      verdict: \"conflicted\",\n      ...found,\n      conflicted,\n      reason:\n        `contradictory verdicts for ${conflicted.join(\", \")} — the header carries both a pass and a non-pass. ` +\n        \"This is legal multi-tiered authentication (RFC 8601 B.6) OR an injected verdict, and the header cannot tell you which. Your call.\",\n    };\n  }\n\n  // DMARC is the one that binds the From: field to what passed. Without it we\n  // know SOMETHING authenticated, but not that the claimed sender is who did.\n  if (found.dmarc === undefined) {\n    return {\n      verdict: \"no-verdict\",\n      ...found,\n      conflicted,\n      reason: \"no dmarc verdict — the From: field is not bound to whatever did pass\",\n    };\n  }\n\n  return { verdict: \"pass\", ...found, conflicted, reason: \"spf/dkim/dmarc pass\" };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+/**
+ * @broberg/mail-identity — is this inbound mail provably from who the From:
+ * field claims?
+ *
+ * Four pure functions, no I/O, no dependencies. They answer two questions and
+ * refuse a third:
+ *
+ *   WHAT IS AN ADDRESS?          extractAddresses · splitPlusTag · addressesMatch
+ *   WHAT DOES THE HEADER SAY?    readAuthResults
+ *   WHAT DOES A MATCH MEAN?      NOT OURS. That is authorisation, and it stays
+ *                                at the call-site where it can be read.
+ *
+ * The third line is the design. Moving an authorisation decision into a shared
+ * dependency would build something worse than the drift it replaces: every
+ * consumer inherits a policy it cannot see, and a change to that policy ships
+ * silently as a patch release.
+ *
+ * ORIGIN: buddy and cardmem independently wrote this same rule, and BOTH had
+ * holes in it, found the same day in each codebase separately. The value here is
+ * not the code — it is the cases in test/, every one of them an attack that
+ * WORKED against a live implementation. Each looks correct until someone builds
+ * the counter-example.
+ */
+/**
+ * What the Authentication-Results header says. FOUR outcomes, not three, and
+ * not two.
+ *
+ *   pass         a dmarc verdict exists and everything present passed
+ *   fail         at least one method's verdicts unambiguously did not pass
+ *   conflicted   one method carries BOTH a passing and a failing verdict
+ *   no-verdict   nothing readable to judge by
+ *
+ * `conflicted` exists because RFC 8601 Appendix B.6 — "Service Provided,
+ * Multi-tiered Authentication Done", the standard's own example of NORMAL
+ * OPERATION — is SYNTACTICALLY IDENTICAL to a duplicate-injection attack:
+ *
+ *     dkim=pass reason="good signature" header.i=@mail-router.example.net;
+ *     dkim=fail reason="bad signature" header.i=@newyork.example.com
+ *
+ * Two signatures, one good, one bad, in one header. Nothing in the header
+ * distinguishes that from an attacker appending `dkim=pass`. So this package
+ * does not try: it REPORTS the disagreement and the caller decides. Fail-closed
+ * is a perfectly good policy — it is just not ours to choose for everyone.
+ *
+ * `no-verdict` must NEVER collapse into `pass`, and the inversion is why it
+ * matters more than it looks: a genuine SELF-SENT mail has no verdict at all
+ * (the header is written by the RECEIVING server, and a mail from your own
+ * authenticated session never crosses that boundary), while an external forgery
+ * HAS one and it FAILS. A gate demanding `pass` rejects precisely the mail the
+ * feature exists for.
+ */
+type AuthVerdict = "pass" | "fail" | "conflicted" | "no-verdict";
+/** The three methods that say something about the sending domain. */
+type AuthMethod = "spf" | "dkim" | "dmarc";
+interface AuthResults {
+    verdict: AuthVerdict;
+    /** Per-method result as read. `pass` only when every verdict for it passed. */
+    spf?: string;
+    dkim?: string;
+    dmarc?: string;
+    /** Methods carrying BOTH a passing and a failing verdict. Empty unless `conflicted`. */
+    conflicted: readonly AuthMethod[];
+    /** Always set, including on `pass` — a caller logging a decision needs the why. */
+    reason: string;
+}
+/**
+ * Every address in a From/To/Cc field. A DISPLAY NAME NEVER CONTRIBUTES ONE.
+ *
+ *   'Christian Broberg <cb@webhouse.dk>'          → ['cb@webhouse.dk']
+ *   'A <a@x.dk>, b@y.dk'                          → ['a@x.dk', 'b@y.dk']
+ *   '"cb@webhouse.dk" <attacker@evil.dk>'         → ['attacker@evil.dk']
+ *   '"x <buddy@broberg.ai>, y" <a@evil.dk>'       → ['a@evil.dk']
+ *   '"Broberg, Christian" <cb@webhouse.dk>'       → ['cb@webhouse.dk']
+ *
+ * The first counter-example killed `from.includes(owner)`, which accepted the
+ * owner's address written as DISPLAY TEXT — four call-paths reproduced it. The
+ * second and third killed `field.split(',')`, which cuts a quoted display name
+ * in half before quoting is understood. Both were live; neither was theoretical.
+ *
+ * Addresses are lowercased. Local parts are formally case-sensitive (RFC 5321),
+ * but no provider we send through treats them that way, and NOT normalising
+ * would mean `CB@webhouse.dk` fails an owner check that `cb@webhouse.dk` passes
+ * — a comparison anyone can sidestep with the shift key.
+ */
+declare function extractAddresses(field: string | null | undefined): string[];
+/**
+ * Split a plus-tag off an address.
+ *
+ *   'buddy+whop@broberg.ai'  →  { address: 'buddy@broberg.ai', tag: 'whop' }
+ *   'buddy@broberg.ai'       →  { address: 'buddy@broberg.ai', tag: null }
+ *
+ * TWO RULES CARRY THE SECURITY, and they are the reason this is separate from
+ * matching rather than folded into it:
+ *
+ * 1. THE TAG INFORMS, THE ADDRESS PROVES. An unknown tag must still match. A tag
+ *    able to REFUSE a match would be authorisation disguised as routing, and a
+ *    typo (`buddy+whopp@`) would make mail vanish silently. `+admin`, `+deploy`
+ *    and `+urgent` must never mean anything privileged — anyone can type them.
+ *
+ * 2. SPLIT AFTER extractAddresses(), NEVER on a raw field. Do it the other way
+ *    round and you are back in the impersonation hole wearing a new hat: a
+ *    display name must not contribute an address, and that property lives in the
+ *    extraction.
+ *
+ * An address with more than one '@' is malformed and is returned UNTOUCHED:
+ * `buddy+x@evil.com@broberg.ai` must never be reshaped into something valid.
+ *
+ * `tag` is `null`, not `undefined`, so that a fixture written as
+ * `{ address: 'x', tag: undefined }` cannot pass a deep-equality check against
+ * `{ address: 'x' }`. Two different facts, two distinguishable values.
+ */
+declare function splitPlusTag(address: string): {
+    address: string;
+    tag: string | null;
+};
+/**
+ * Does any address in `field` EQUAL any address in `known`?
+ *
+ * Equality on extracted addresses. Never a substring, never a prefix, never a
+ * suffix — `cb@webhouse.dk.evil.com` and `"cb@webhouse.dk" <x@evil.dk>` and
+ * `buddy@broberg.ai.evil.com` are all rejected, and each of the three was
+ * accepted by a live implementation this week.
+ *
+ * Both sides go through the SAME extraction and the SAME plus-tag
+ * normalisation, so `known` may be given as bare addresses or as full fields.
+ * An empty or unparseable `field` matches nothing.
+ */
+declare function addressesMatch(field: string | null | undefined, known: string | readonly string[]): boolean;
+/**
+ * Read an Authentication-Results header (RFC 8601). Reports; does not judge.
+ *
+ * ANCHORING IS AN ALLOWLIST, NOT A DENYLIST. `\b` was the original, and a dot is
+ * a word boundary, so `\bdmarc=` matched INSIDE `header.dmarc=pass` — a
+ * qualified key read as a verdict:
+ *
+ *   'header.dmarc=pass header.dkim=pass header.spf=pass; dmarc=fail; dkim=fail; spf=fail'
+ *     → PASS, while every real verdict in it is `fail`.
+ *
+ * The first fix was a denylist, `(?<![\w.-])`. Swept over the whole printable
+ * character set it left 27 characters open, including a colon — `arc:dmarc=pass`
+ * read as a pass. A denylist has to predict every character a future vendor
+ * invents. So: a verdict must stand at the start of the header or after a REAL
+ * separator (whitespace, `;` or `,` — RFC 8601's own), and anything else in
+ * front of it makes it a qualified key rather than a verdict.
+ *
+ * Quoted strings and comments are blanked before matching (see
+ * maskQuotedAndComments) — they are two more places a verdict cannot stand, and
+ * both manufactured verdicts in the prior implementation.
+ *
+ * ALL occurrences are collected, not the first: a header can carry more than one
+ * verdict per method, and "first wins" lets an injected `dmarc=pass` drown out
+ * the real `dmarc=fail`.
+ *
+ * PRECEDENCE IS SECURITY-BEARING. An unambiguous fail beats a conflict:
+ *
+ *   'dkim=pass; dkim=fail; dmarc=fail'  →  fail, NOT conflicted
+ *
+ * A method where NO verdict passed is stronger evidence than a disagreement
+ * somewhere else. Get the order wrong and a genuine, unambiguous rejection is
+ * downgraded to "cannot determine" — which a lenient caller then lets through.
+ */
+declare function readAuthResults(header: string | null | undefined): AuthResults;
+
+export { type AuthMethod, type AuthResults, type AuthVerdict, addressesMatch, extractAddresses, readAuthResults, splitPlusTag };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @broberg/mail-identity — is this inbound mail provably from who the From:
+ * field claims?
+ *
+ * Four pure functions, no I/O, no dependencies. They answer two questions and
+ * refuse a third:
+ *
+ *   WHAT IS AN ADDRESS?          extractAddresses · splitPlusTag · addressesMatch
+ *   WHAT DOES THE HEADER SAY?    readAuthResults
+ *   WHAT DOES A MATCH MEAN?      NOT OURS. That is authorisation, and it stays
+ *                                at the call-site where it can be read.
+ *
+ * The third line is the design. Moving an authorisation decision into a shared
+ * dependency would build something worse than the drift it replaces: every
+ * consumer inherits a policy it cannot see, and a change to that policy ships
+ * silently as a patch release.
+ *
+ * ORIGIN: buddy and cardmem independently wrote this same rule, and BOTH had
+ * holes in it, found the same day in each codebase separately. The value here is
+ * not the code — it is the cases in test/, every one of them an attack that
+ * WORKED against a live implementation. Each looks correct until someone builds
+ * the counter-example.
+ */
+/**
+ * What the Authentication-Results header says. FOUR outcomes, not three, and
+ * not two.
+ *
+ *   pass         a dmarc verdict exists and everything present passed
+ *   fail         at least one method's verdicts unambiguously did not pass
+ *   conflicted   one method carries BOTH a passing and a failing verdict
+ *   no-verdict   nothing readable to judge by
+ *
+ * `conflicted` exists because RFC 8601 Appendix B.6 — "Service Provided,
+ * Multi-tiered Authentication Done", the standard's own example of NORMAL
+ * OPERATION — is SYNTACTICALLY IDENTICAL to a duplicate-injection attack:
+ *
+ *     dkim=pass reason="good signature" header.i=@mail-router.example.net;
+ *     dkim=fail reason="bad signature" header.i=@newyork.example.com
+ *
+ * Two signatures, one good, one bad, in one header. Nothing in the header
+ * distinguishes that from an attacker appending `dkim=pass`. So this package
+ * does not try: it REPORTS the disagreement and the caller decides. Fail-closed
+ * is a perfectly good policy — it is just not ours to choose for everyone.
+ *
+ * `no-verdict` must NEVER collapse into `pass`, and the inversion is why it
+ * matters more than it looks: a genuine SELF-SENT mail has no verdict at all
+ * (the header is written by the RECEIVING server, and a mail from your own
+ * authenticated session never crosses that boundary), while an external forgery
+ * HAS one and it FAILS. A gate demanding `pass` rejects precisely the mail the
+ * feature exists for.
+ */
+type AuthVerdict = "pass" | "fail" | "conflicted" | "no-verdict";
+/** The three methods that say something about the sending domain. */
+type AuthMethod = "spf" | "dkim" | "dmarc";
+interface AuthResults {
+    verdict: AuthVerdict;
+    /** Per-method result as read. `pass` only when every verdict for it passed. */
+    spf?: string;
+    dkim?: string;
+    dmarc?: string;
+    /** Methods carrying BOTH a passing and a failing verdict. Empty unless `conflicted`. */
+    conflicted: readonly AuthMethod[];
+    /** Always set, including on `pass` — a caller logging a decision needs the why. */
+    reason: string;
+}
+/**
+ * Every address in a From/To/Cc field. A DISPLAY NAME NEVER CONTRIBUTES ONE.
+ *
+ *   'Christian Broberg <cb@webhouse.dk>'          → ['cb@webhouse.dk']
+ *   'A <a@x.dk>, b@y.dk'                          → ['a@x.dk', 'b@y.dk']
+ *   '"cb@webhouse.dk" <attacker@evil.dk>'         → ['attacker@evil.dk']
+ *   '"x <buddy@broberg.ai>, y" <a@evil.dk>'       → ['a@evil.dk']
+ *   '"Broberg, Christian" <cb@webhouse.dk>'       → ['cb@webhouse.dk']
+ *
+ * The first counter-example killed `from.includes(owner)`, which accepted the
+ * owner's address written as DISPLAY TEXT — four call-paths reproduced it. The
+ * second and third killed `field.split(',')`, which cuts a quoted display name
+ * in half before quoting is understood. Both were live; neither was theoretical.
+ *
+ * Addresses are lowercased. Local parts are formally case-sensitive (RFC 5321),
+ * but no provider we send through treats them that way, and NOT normalising
+ * would mean `CB@webhouse.dk` fails an owner check that `cb@webhouse.dk` passes
+ * — a comparison anyone can sidestep with the shift key.
+ */
+declare function extractAddresses(field: string | null | undefined): string[];
+/**
+ * Split a plus-tag off an address.
+ *
+ *   'buddy+whop@broberg.ai'  →  { address: 'buddy@broberg.ai', tag: 'whop' }
+ *   'buddy@broberg.ai'       →  { address: 'buddy@broberg.ai', tag: null }
+ *
+ * TWO RULES CARRY THE SECURITY, and they are the reason this is separate from
+ * matching rather than folded into it:
+ *
+ * 1. THE TAG INFORMS, THE ADDRESS PROVES. An unknown tag must still match. A tag
+ *    able to REFUSE a match would be authorisation disguised as routing, and a
+ *    typo (`buddy+whopp@`) would make mail vanish silently. `+admin`, `+deploy`
+ *    and `+urgent` must never mean anything privileged — anyone can type them.
+ *
+ * 2. SPLIT AFTER extractAddresses(), NEVER on a raw field. Do it the other way
+ *    round and you are back in the impersonation hole wearing a new hat: a
+ *    display name must not contribute an address, and that property lives in the
+ *    extraction.
+ *
+ * An address with more than one '@' is malformed and is returned UNTOUCHED:
+ * `buddy+x@evil.com@broberg.ai` must never be reshaped into something valid.
+ *
+ * `tag` is `null`, not `undefined`, so that a fixture written as
+ * `{ address: 'x', tag: undefined }` cannot pass a deep-equality check against
+ * `{ address: 'x' }`. Two different facts, two distinguishable values.
+ */
+declare function splitPlusTag(address: string): {
+    address: string;
+    tag: string | null;
+};
+/**
+ * Does any address in `field` EQUAL any address in `known`?
+ *
+ * Equality on extracted addresses. Never a substring, never a prefix, never a
+ * suffix — `cb@webhouse.dk.evil.com` and `"cb@webhouse.dk" <x@evil.dk>` and
+ * `buddy@broberg.ai.evil.com` are all rejected, and each of the three was
+ * accepted by a live implementation this week.
+ *
+ * Both sides go through the SAME extraction and the SAME plus-tag
+ * normalisation, so `known` may be given as bare addresses or as full fields.
+ * An empty or unparseable `field` matches nothing.
+ */
+declare function addressesMatch(field: string | null | undefined, known: string | readonly string[]): boolean;
+/**
+ * Read an Authentication-Results header (RFC 8601). Reports; does not judge.
+ *
+ * ANCHORING IS AN ALLOWLIST, NOT A DENYLIST. `\b` was the original, and a dot is
+ * a word boundary, so `\bdmarc=` matched INSIDE `header.dmarc=pass` — a
+ * qualified key read as a verdict:
+ *
+ *   'header.dmarc=pass header.dkim=pass header.spf=pass; dmarc=fail; dkim=fail; spf=fail'
+ *     → PASS, while every real verdict in it is `fail`.
+ *
+ * The first fix was a denylist, `(?<![\w.-])`. Swept over the whole printable
+ * character set it left 27 characters open, including a colon — `arc:dmarc=pass`
+ * read as a pass. A denylist has to predict every character a future vendor
+ * invents. So: a verdict must stand at the start of the header or after a REAL
+ * separator (whitespace, `;` or `,` — RFC 8601's own), and anything else in
+ * front of it makes it a qualified key rather than a verdict.
+ *
+ * Quoted strings and comments are blanked before matching (see
+ * maskQuotedAndComments) — they are two more places a verdict cannot stand, and
+ * both manufactured verdicts in the prior implementation.
+ *
+ * ALL occurrences are collected, not the first: a header can carry more than one
+ * verdict per method, and "first wins" lets an injected `dmarc=pass` drown out
+ * the real `dmarc=fail`.
+ *
+ * PRECEDENCE IS SECURITY-BEARING. An unambiguous fail beats a conflict:
+ *
+ *   'dkim=pass; dkim=fail; dmarc=fail'  →  fail, NOT conflicted
+ *
+ * A method where NO verdict passed is stronger evidence than a disagreement
+ * somewhere else. Get the order wrong and a genuine, unambiguous rejection is
+ * downgraded to "cannot determine" — which a lenient caller then lets through.
+ */
+declare function readAuthResults(header: string | null | undefined): AuthResults;
+
+export { type AuthMethod, type AuthResults, type AuthVerdict, addressesMatch, extractAddresses, readAuthResults, splitPlusTag };

package/dist/index.js

@@ -0,0 +1,165 @@
+// src/index.ts
+var METHODS = ["spf", "dkim", "dmarc"];
+function maskQuotedAndComments(s) {
+  const out = s.split("");
+  let quoted = false;
+  let comment = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if ((quoted || comment > 0) && c === "\\" && i + 1 < s.length) {
+      out[i] = " ";
+      out[i + 1] = " ";
+      i++;
+      continue;
+    }
+    if (quoted) {
+      out[i] = " ";
+      if (c === '"') quoted = false;
+      continue;
+    }
+    if (comment > 0) {
+      if (c === "(") comment++;
+      else if (c === ")") comment--;
+      out[i] = " ";
+      continue;
+    }
+    if (c === '"') {
+      quoted = true;
+      out[i] = " ";
+      continue;
+    }
+    if (c === "(") {
+      comment++;
+      out[i] = " ";
+      continue;
+    }
+  }
+  return { masked: out.join(""), malformed: quoted || comment > 0 };
+}
+function normalise(s) {
+  const t = s.trim().toLowerCase();
+  return t.length > 0 ? t : null;
+}
+function addressOfPart(raw, masked, from, to) {
+  let open = -1;
+  let close = -1;
+  let depth = 0;
+  for (let i = from; i < to; i++) {
+    const c = masked[i];
+    if (c === "<") {
+      if (depth === 0) open = i;
+      depth++;
+    } else if (c === ">" && depth > 0) {
+      depth--;
+      if (depth === 0) {
+        close = i;
+        break;
+      }
+    }
+  }
+  if (open >= 0 && close > open) return normalise(raw.slice(open + 1, close));
+  if (open >= 0) return normalise(raw.slice(from, to));
+  return normalise(masked.slice(from, to));
+}
+function extractAddresses(field) {
+  if (!field) return [];
+  const { masked } = maskQuotedAndComments(field);
+  const out = [];
+  let start = 0;
+  let angle = 0;
+  const flush = (end) => {
+    const a = addressOfPart(field, masked, start, end);
+    if (a) out.push(a);
+    start = end + 1;
+  };
+  for (let i = 0; i < masked.length; i++) {
+    const c = masked[i];
+    if (c === "<") angle++;
+    else if (c === ">" && angle > 0) angle--;
+    else if (c === "," && angle === 0) flush(i);
+  }
+  flush(masked.length);
+  return out;
+}
+function splitPlusTag(address) {
+  const at = address.indexOf("@");
+  if (at < 0 || address.indexOf("@", at + 1) !== -1) return { address, tag: null };
+  const plus = address.indexOf("+");
+  if (plus < 0 || plus > at) return { address, tag: null };
+  const tag = address.slice(plus + 1, at);
+  return { address: address.slice(0, plus) + address.slice(at), tag: tag || null };
+}
+function addressesMatch(field, known) {
+  const present = new Set(extractAddresses(field).map((a) => splitPlusTag(a).address));
+  if (present.size === 0) return false;
+  const list = typeof known === "string" ? [known] : known;
+  return list.some(
+    (k) => extractAddresses(k).some((a) => present.has(splitPlusTag(a).address))
+  );
+}
+function readAuthResults(header) {
+  if (!header || !header.trim()) {
+    return {
+      verdict: "no-verdict",
+      conflicted: [],
+      reason: "no Authentication-Results header \u2014 the sender is unproven, which is not the same as disproven"
+    };
+  }
+  const { masked, malformed } = maskQuotedAndComments(header);
+  if (malformed) {
+    return {
+      verdict: "no-verdict",
+      conflicted: [],
+      reason: "unterminated quoted string or comment \u2014 the header could not be parsed to the end, and a verdict read out of the readable half would be a verdict an attacker chose the boundary of"
+    };
+  }
+  const found = {};
+  const conflicted = [];
+  for (const method of METHODS) {
+    const re = new RegExp(`(?<=^|[\\s;,])${method}\\s*(?:/\\s*\\d+\\s*)?=\\s*([a-z]+)`, "gi");
+    const verdicts = [...masked.matchAll(re)].map((m) => m[1].toLowerCase());
+    if (verdicts.length === 0) continue;
+    const passed = verdicts.filter((v) => v === "pass").length;
+    if (passed > 0 && passed < verdicts.length) conflicted.push(method);
+    found[method] = passed === verdicts.length ? "pass" : verdicts.find((v) => v !== "pass");
+  }
+  if (Object.keys(found).length === 0) {
+    return {
+      verdict: "no-verdict",
+      conflicted: [],
+      reason: "Authentication-Results was present but carried no readable spf/dkim/dmarc verdict"
+    };
+  }
+  const failed = METHODS.filter(
+    (m) => found[m] !== void 0 && found[m] !== "pass" && !conflicted.includes(m)
+  );
+  if (failed.length > 0) {
+    return {
+      verdict: "fail",
+      ...found,
+      conflicted,
+      reason: `rejected: ${failed.map((m) => `${m}=${found[m]}`).join(", ")}`
+    };
+  }
+  if (conflicted.length > 0) {
+    return {
+      verdict: "conflicted",
+      ...found,
+      conflicted,
+      reason: `contradictory verdicts for ${conflicted.join(", ")} \u2014 the header carries both a pass and a non-pass. This is legal multi-tiered authentication (RFC 8601 B.6) OR an injected verdict, and the header cannot tell you which. Your call.`
+    };
+  }
+  if (found.dmarc === void 0) {
+    return {
+      verdict: "no-verdict",
+      ...found,
+      conflicted,
+      reason: "no dmarc verdict \u2014 the From: field is not bound to whatever did pass"
+    };
+  }
+  return { verdict: "pass", ...found, conflicted, reason: "spf/dkim/dmarc pass" };
+}
+
+export { addressesMatch, extractAddresses, readAuthResults, splitPlusTag };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @broberg/mail-identity — is this inbound mail provably from who the From:\n * field claims?\n *\n * Four pure functions, no I/O, no dependencies. They answer two questions and\n * refuse a third:\n *\n *   WHAT IS AN ADDRESS?          extractAddresses · splitPlusTag · addressesMatch\n *   WHAT DOES THE HEADER SAY?    readAuthResults\n *   WHAT DOES A MATCH MEAN?      NOT OURS. That is authorisation, and it stays\n *                                at the call-site where it can be read.\n *\n * The third line is the design. Moving an authorisation decision into a shared\n * dependency would build something worse than the drift it replaces: every\n * consumer inherits a policy it cannot see, and a change to that policy ships\n * silently as a patch release.\n *\n * ORIGIN: buddy and cardmem independently wrote this same rule, and BOTH had\n * holes in it, found the same day in each codebase separately. The value here is\n * not the code — it is the cases in test/, every one of them an attack that\n * WORKED against a live implementation. Each looks correct until someone builds\n * the counter-example.\n */\n\n/**\n * What the Authentication-Results header says. FOUR outcomes, not three, and\n * not two.\n *\n *   pass         a dmarc verdict exists and everything present passed\n *   fail         at least one method's verdicts unambiguously did not pass\n *   conflicted   one method carries BOTH a passing and a failing verdict\n *   no-verdict   nothing readable to judge by\n *\n * `conflicted` exists because RFC 8601 Appendix B.6 — \"Service Provided,\n * Multi-tiered Authentication Done\", the standard's own example of NORMAL\n * OPERATION — is SYNTACTICALLY IDENTICAL to a duplicate-injection attack:\n *\n *     dkim=pass reason=\"good signature\" header.i=@mail-router.example.net;\n *     dkim=fail reason=\"bad signature\" header.i=@newyork.example.com\n *\n * Two signatures, one good, one bad, in one header. Nothing in the header\n * distinguishes that from an attacker appending `dkim=pass`. So this package\n * does not try: it REPORTS the disagreement and the caller decides. Fail-closed\n * is a perfectly good policy — it is just not ours to choose for everyone.\n *\n * `no-verdict` must NEVER collapse into `pass`, and the inversion is why it\n * matters more than it looks: a genuine SELF-SENT mail has no verdict at all\n * (the header is written by the RECEIVING server, and a mail from your own\n * authenticated session never crosses that boundary), while an external forgery\n * HAS one and it FAILS. A gate demanding `pass` rejects precisely the mail the\n * feature exists for.\n */\nexport type AuthVerdict = \"pass\" | \"fail\" | \"conflicted\" | \"no-verdict\";\n\n/** The three methods that say something about the sending domain. */\nexport type AuthMethod = \"spf\" | \"dkim\" | \"dmarc\";\n\nconst METHODS: readonly AuthMethod[] = [\"spf\", \"dkim\", \"dmarc\"];\n\nexport interface AuthResults {\n  verdict: AuthVerdict;\n  /** Per-method result as read. `pass` only when every verdict for it passed. */\n  spf?: string;\n  dkim?: string;\n  dmarc?: string;\n  /** Methods carrying BOTH a passing and a failing verdict. Empty unless `conflicted`. */\n  conflicted: readonly AuthMethod[];\n  /** Always set, including on `pass` — a caller logging a decision needs the why. */\n  reason: string;\n}\n\n/**\n * A view of `s` in which every quoted-string and every (nested) comment — and\n * their delimiters — is replaced by a SPACE, position for position.\n *\n * THIS IS THE WHOLE TRICK, and it is what a regex over the raw string cannot do.\n * Both grammars we parse (RFC 5322 address lists, RFC 8601 auth results) have\n * quoting, and in both a comment is defined to be whitespace. A regex has\n * neither notion, so it sees a legal separator wherever there is a space —\n * INCLUDING the spaces inside a quoted string. Measured against the prior\n * implementation, all three of these came from exactly that:\n *\n *   'Authentication-Results: …; dkim=pass reason=\"relayed dmarc=pass ok\"'\n *      → no-verdict became PASS. Text inside a reason string became a verdict.\n *\n *   'Authentication-Results: …; dkim=pass (relayed dmarc=pass ok)'\n *      → same, via a comment.\n *\n *   'To: \"x <buddy@broberg.ai>, y\" <attacker@evil.dk>'\n *      → split-on-comma cut the quoted display name in half, and the half\n *        carried an <addr> that was only ever decoration. A display name\n *        contributed an address, which is the single property this package\n *        exists to guarantee it cannot.\n *\n * Replacing with a space rather than DELETING is deliberate: deletion joins the\n * neighbours, so `dmar(x)c=pass` would become the verdict `dmarc=pass` out of\n * text that is not one. A comment is whitespace; blanking says exactly that.\n *\n * Unterminated quotes and comments blank the remainder of the string, and are\n * reported as `malformed` so a caller of this helper can refuse to read a\n * PARTIAL result out of a header it could not finish parsing. That distinction\n * is not pedantry — the qualifier values in an auth header (`smtp.mailfrom=`,\n * `header.i=`) come from the message, so an unterminated delimiter there would\n * blank every verdict AFTER it while leaving the earlier ones standing. Erasing\n * a trailing `dmarc=fail` and keeping a leading `spf=pass` is a strictly useful\n * outcome for an attacker, so a header that does not parse yields nothing.\n */\nfunction maskQuotedAndComments(s: string): { masked: string; malformed: boolean } {\n  const out = s.split(\"\");\n  let quoted = false;\n  let comment = 0;\n\n  for (let i = 0; i < s.length; i++) {\n    const c = s[i]!;\n\n    if ((quoted || comment > 0) && c === \"\\\\\" && i + 1 < s.length) {\n      out[i] = \" \";\n      out[i + 1] = \" \";\n      i++;\n      continue;\n    }\n    if (quoted) {\n      out[i] = \" \";\n      if (c === '\"') quoted = false;\n      continue;\n    }\n    if (comment > 0) {\n      if (c === \"(\") comment++;\n      else if (c === \")\") comment--;\n      out[i] = \" \";\n      continue;\n    }\n    if (c === '\"') {\n      quoted = true;\n      out[i] = \" \";\n      continue;\n    }\n    if (c === \"(\") {\n      comment++;\n      out[i] = \" \";\n      continue;\n    }\n  }\n\n  return { masked: out.join(\"\"), malformed: quoted || comment > 0 };\n}\n\n/** Lowercase + trim, or null when nothing is left. */\nfunction normalise(s: string): string | null {\n  const t = s.trim().toLowerCase();\n  return t.length > 0 ? t : null;\n}\n\n/**\n * The address of ONE address-list entry, given the raw field and its mask.\n *\n * Angle brackets are located in the MASKED view, so a `<` inside a quoted\n * display name is simply not there to be found — but the address itself is\n * sliced from the RAW string, so a quoted local part (`<\"odd name\"@example.com>`)\n * survives intact.\n */\nfunction addressOfPart(raw: string, masked: string, from: number, to: number): string | null {\n  let open = -1;\n  let close = -1;\n  let depth = 0;\n\n  for (let i = from; i < to; i++) {\n    const c = masked[i]!;\n    if (c === \"<\") {\n      if (depth === 0) open = i;\n      depth++;\n    } else if (c === \">\" && depth > 0) {\n      depth--;\n      if (depth === 0) {\n        close = i;\n        break;\n      }\n    }\n  }\n\n  if (open >= 0 && close > open) return normalise(raw.slice(open + 1, close));\n\n  // An UNTERMINATED '<' is malformed. Hand back the part as it stands rather\n  // than guessing which half was meant to be the address — something that\n  // matches nothing beats something that might match the owner.\n  if (open >= 0) return normalise(raw.slice(from, to));\n\n  // No angle brackets: the address is the bare text, which is the MASKED text —\n  // so a comment such as `cb@webhouse.dk (Christian)` contributes nothing.\n  return normalise(masked.slice(from, to));\n}\n\n/**\n * Every address in a From/To/Cc field. A DISPLAY NAME NEVER CONTRIBUTES ONE.\n *\n *   'Christian Broberg <cb@webhouse.dk>'          → ['cb@webhouse.dk']\n *   'A <a@x.dk>, b@y.dk'                          → ['a@x.dk', 'b@y.dk']\n *   '\"cb@webhouse.dk\" <attacker@evil.dk>'         → ['attacker@evil.dk']\n *   '\"x <buddy@broberg.ai>, y\" <a@evil.dk>'       → ['a@evil.dk']\n *   '\"Broberg, Christian\" <cb@webhouse.dk>'       → ['cb@webhouse.dk']\n *\n * The first counter-example killed `from.includes(owner)`, which accepted the\n * owner's address written as DISPLAY TEXT — four call-paths reproduced it. The\n * second and third killed `field.split(',')`, which cuts a quoted display name\n * in half before quoting is understood. Both were live; neither was theoretical.\n *\n * Addresses are lowercased. Local parts are formally case-sensitive (RFC 5321),\n * but no provider we send through treats them that way, and NOT normalising\n * would mean `CB@webhouse.dk` fails an owner check that `cb@webhouse.dk` passes\n * — a comparison anyone can sidestep with the shift key.\n */\nexport function extractAddresses(field: string | null | undefined): string[] {\n  if (!field) return [];\n  // A malformed field is not rejected outright here: blanking already makes the\n  // unparseable remainder match nothing, and an address list has no equivalent\n  // of the partial-verdict problem — an address either equals a known one or it\n  // does not.\n  const { masked } = maskQuotedAndComments(field);\n\n  const out: string[] = [];\n  let start = 0;\n  let angle = 0;\n\n  const flush = (end: number): void => {\n    const a = addressOfPart(field, masked, start, end);\n    if (a) out.push(a);\n    start = end + 1;\n  };\n\n  for (let i = 0; i < masked.length; i++) {\n    const c = masked[i]!;\n    if (c === \"<\") angle++;\n    else if (c === \">\" && angle > 0) angle--;\n    else if (c === \",\" && angle === 0) flush(i);\n  }\n  flush(masked.length);\n\n  return out;\n}\n\n/**\n * Split a plus-tag off an address.\n *\n *   'buddy+whop@broberg.ai'  →  { address: 'buddy@broberg.ai', tag: 'whop' }\n *   'buddy@broberg.ai'       →  { address: 'buddy@broberg.ai', tag: null }\n *\n * TWO RULES CARRY THE SECURITY, and they are the reason this is separate from\n * matching rather than folded into it:\n *\n * 1. THE TAG INFORMS, THE ADDRESS PROVES. An unknown tag must still match. A tag\n *    able to REFUSE a match would be authorisation disguised as routing, and a\n *    typo (`buddy+whopp@`) would make mail vanish silently. `+admin`, `+deploy`\n *    and `+urgent` must never mean anything privileged — anyone can type them.\n *\n * 2. SPLIT AFTER extractAddresses(), NEVER on a raw field. Do it the other way\n *    round and you are back in the impersonation hole wearing a new hat: a\n *    display name must not contribute an address, and that property lives in the\n *    extraction.\n *\n * An address with more than one '@' is malformed and is returned UNTOUCHED:\n * `buddy+x@evil.com@broberg.ai` must never be reshaped into something valid.\n *\n * `tag` is `null`, not `undefined`, so that a fixture written as\n * `{ address: 'x', tag: undefined }` cannot pass a deep-equality check against\n * `{ address: 'x' }`. Two different facts, two distinguishable values.\n */\nexport function splitPlusTag(address: string): { address: string; tag: string | null } {\n  const at = address.indexOf(\"@\");\n  if (at < 0 || address.indexOf(\"@\", at + 1) !== -1) return { address, tag: null };\n\n  const plus = address.indexOf(\"+\");\n  if (plus < 0 || plus > at) return { address, tag: null };\n\n  // From the FIRST '+': 'buddy+a+b@' has the tag 'a+b', not 'b'.\n  const tag = address.slice(plus + 1, at);\n  return { address: address.slice(0, plus) + address.slice(at), tag: tag || null };\n}\n\n/**\n * Does any address in `field` EQUAL any address in `known`?\n *\n * Equality on extracted addresses. Never a substring, never a prefix, never a\n * suffix — `cb@webhouse.dk.evil.com` and `\"cb@webhouse.dk\" <x@evil.dk>` and\n * `buddy@broberg.ai.evil.com` are all rejected, and each of the three was\n * accepted by a live implementation this week.\n *\n * Both sides go through the SAME extraction and the SAME plus-tag\n * normalisation, so `known` may be given as bare addresses or as full fields.\n * An empty or unparseable `field` matches nothing.\n */\nexport function addressesMatch(\n  field: string | null | undefined,\n  known: string | readonly string[],\n): boolean {\n  const present = new Set(extractAddresses(field).map((a) => splitPlusTag(a).address));\n  if (present.size === 0) return false;\n\n  const list = typeof known === \"string\" ? [known] : known;\n  return list.some((k) =>\n    extractAddresses(k).some((a) => present.has(splitPlusTag(a).address)),\n  );\n}\n\n/**\n * Read an Authentication-Results header (RFC 8601). Reports; does not judge.\n *\n * ANCHORING IS AN ALLOWLIST, NOT A DENYLIST. `\\b` was the original, and a dot is\n * a word boundary, so `\\bdmarc=` matched INSIDE `header.dmarc=pass` — a\n * qualified key read as a verdict:\n *\n *   'header.dmarc=pass header.dkim=pass header.spf=pass; dmarc=fail; dkim=fail; spf=fail'\n *     → PASS, while every real verdict in it is `fail`.\n *\n * The first fix was a denylist, `(?<![\\w.-])`. Swept over the whole printable\n * character set it left 27 characters open, including a colon — `arc:dmarc=pass`\n * read as a pass. A denylist has to predict every character a future vendor\n * invents. So: a verdict must stand at the start of the header or after a REAL\n * separator (whitespace, `;` or `,` — RFC 8601's own), and anything else in\n * front of it makes it a qualified key rather than a verdict.\n *\n * Quoted strings and comments are blanked before matching (see\n * maskQuotedAndComments) — they are two more places a verdict cannot stand, and\n * both manufactured verdicts in the prior implementation.\n *\n * ALL occurrences are collected, not the first: a header can carry more than one\n * verdict per method, and \"first wins\" lets an injected `dmarc=pass` drown out\n * the real `dmarc=fail`.\n *\n * PRECEDENCE IS SECURITY-BEARING. An unambiguous fail beats a conflict:\n *\n *   'dkim=pass; dkim=fail; dmarc=fail'  →  fail, NOT conflicted\n *\n * A method where NO verdict passed is stronger evidence than a disagreement\n * somewhere else. Get the order wrong and a genuine, unambiguous rejection is\n * downgraded to \"cannot determine\" — which a lenient caller then lets through.\n */\nexport function readAuthResults(header: string | null | undefined): AuthResults {\n  if (!header || !header.trim()) {\n    return {\n      verdict: \"no-verdict\",\n      conflicted: [],\n      reason: \"no Authentication-Results header — the sender is unproven, which is not the same as disproven\",\n    };\n  }\n\n  const { masked, malformed } = maskQuotedAndComments(header);\n  if (malformed) {\n    return {\n      verdict: \"no-verdict\",\n      conflicted: [],\n      reason:\n        \"unterminated quoted string or comment — the header could not be parsed to the end, \" +\n        \"and a verdict read out of the readable half would be a verdict an attacker chose the boundary of\",\n    };\n  }\n\n  const found: Partial<Record<AuthMethod, string>> = {};\n  const conflicted: AuthMethod[] = [];\n\n  for (const method of METHODS) {\n    // The optional `/1` is RFC 8601's method-version, and the `\\s*` around it\n    // and around `=` is CFWS — comments are already spaces by now. Appendix B.7,\n    // the RFC's own \"perfectly legal\" example, is written\n    // `dkim (Because I like it) / 1 (One yay) = (wait for it) fail`, and a\n    // parser too narrow to read it would report no-verdict on a header that\n    // plainly says fail. Rejecting genuine mail is the equally expensive\n    // opposite error.\n    const re = new RegExp(`(?<=^|[\\\\s;,])${method}\\\\s*(?:/\\\\s*\\\\d+\\\\s*)?=\\\\s*([a-z]+)`, \"gi\");\n    const verdicts = [...masked.matchAll(re)].map((m) => m[1]!.toLowerCase());\n    if (verdicts.length === 0) continue;\n\n    const passed = verdicts.filter((v) => v === \"pass\").length;\n    // DISAGREEMENT and UNIFORMLY-NOT-PASSED are two different facts:\n    //   dmarc=fail              a real, unambiguous rejection\n    //   dkim=pass … dkim=fail   a disagreement (RFC B.6 legal, OR injected)\n    // Collapsing both into `fail` hides the difference from the caller and puts\n    // the policy here, where no consumer can change it. A REPEATED AGREEING\n    // verdict is not a conflict — a relay may legitimately repeat itself, and\n    // reading that as tampering blocks real mail.\n    if (passed > 0 && passed < verdicts.length) conflicted.push(method);\n    found[method] = passed === verdicts.length ? \"pass\" : verdicts.find((v) => v !== \"pass\")!;\n  }\n\n  if (Object.keys(found).length === 0) {\n    return {\n      verdict: \"no-verdict\",\n      conflicted: [],\n      reason: \"Authentication-Results was present but carried no readable spf/dkim/dmarc verdict\",\n    };\n  }\n\n  const failed = METHODS.filter(\n    (m) => found[m] !== undefined && found[m] !== \"pass\" && !conflicted.includes(m),\n  );\n  if (failed.length > 0) {\n    return {\n      verdict: \"fail\",\n      ...found,\n      conflicted,\n      reason: `rejected: ${failed.map((m) => `${m}=${found[m]}`).join(\", \")}`,\n    };\n  }\n\n  if (conflicted.length > 0) {\n    return {\n      verdict: \"conflicted\",\n      ...found,\n      conflicted,\n      reason:\n        `contradictory verdicts for ${conflicted.join(\", \")} — the header carries both a pass and a non-pass. ` +\n        \"This is legal multi-tiered authentication (RFC 8601 B.6) OR an injected verdict, and the header cannot tell you which. Your call.\",\n    };\n  }\n\n  // DMARC is the one that binds the From: field to what passed. Without it we\n  // know SOMETHING authenticated, but not that the claimed sender is who did.\n  if (found.dmarc === undefined) {\n    return {\n      verdict: \"no-verdict\",\n      ...found,\n      conflicted,\n      reason: \"no dmarc verdict — the From: field is not bound to whatever did pass\",\n    };\n  }\n\n  return { verdict: \"pass\", ...found, conflicted, reason: \"spf/dkim/dmarc pass\" };\n}\n"]}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@broberg/mail-identity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Is this inbound mail provably from who the From: field claims? Reads addresses and Authentication-Results the way the grammar does, not the way a regex does. Four pure functions, zero dependencies, no I/O. It owns WHAT AN ADDRESS IS and WHAT THE AUTH HEADER SAYS — never what a match MEANS.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --reporter=default --reporter=json --outputFile.json=.vitest-report/results.json && node ../../scripts/mutations-if-changed.mjs test/mutations.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "email",
+    "mail",
+    "inbound",
+    "sender",
+    "identity",
+    "spoofing",
+    "impersonation",
+    "authentication-results",
+    "dmarc",
+    "dkim",
+    "spf",
+    "rfc8601",
+    "rfc5322",
+    "plus-addressing",
+    "broberg"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/broberg-ai/components",
+    "directory": "packages/mail-identity"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}