@postalsys/otp-detect 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postal Systems OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# otp-detect
 
-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.
+Finds the one-time code (login, verification, two-factor and similar codes) in an email message.
+
+Senders can put the code in an `OTP-Token` header as described in
+[draft-goto-otp-token](https://datatracker.ietf.org/doc/draft-goto-otp-token/), and
+[postal-mime](https://github.com/postalsys/postal-mime) already exposes that header as `message.otp`.
+Most senders do not set it yet, so this package looks for the code in the message body instead, using
+a small trained model.
+
+**Status:** early development, not published yet.
+
+## Usage
+
+```js
+import { detectOtp } from '@postalsys/otp-detect';
+
+const result = detectOtp({ subject, text, html });
+// { code: '739104', raw: '739 104', score: 0.98, source: 'html' } or null
+```
+
+The input is an already parsed message: `subject`, the `text/plain` body and the `text/html` body,
+any of them optional. With [postal-mime](https://github.com/postalsys/postal-mime):
+
+```js
+const email = await PostalMime.parse(raw);
+const code = email.otp?.code ?? detectOtp(email)?.code;
+```
+
+Prefer the `OTP-Token` header when there is one. Neither the header nor the body is authenticated:
+check that the message passes DKIM for the sender's domain before offering a code to a user.
+
+`scoreCandidates(input)` returns every code-like token with its score, best first, for debugging or
+custom rules. Both functions take `{ threshold }` to override the default threshold (0.97).
+
+## How it works
+
+1. **Rendering.** The HTML body is rendered to text while remembering how each piece of text looks:
+   font size, bold, letter spacing, links, hidden preheaders, quoted reply history.
+2. **Candidates.** Code-like tokens are extracted from the rendered HTML and the plain text: digit
+   runs, grouped digits (`123 456`), capital letter codes (`QWKZT`), mixed alphanumeric codes.
+3. **Scoring.** Gradient boosted trees score each candidate from its context: the distance to words
+   that name a code in many languages, to words that name order numbers, prices and promo codes,
+   its styling and position, and message-level signals such as the subject. The best candidate above
+   the threshold is returned, or nothing.
+
+The model is a few dozen kilobytes of trees embedded in the package, and runs in plain JavaScript with
+no runtime dependencies. Work is linear in the size of the message, which is cut at 512 KB per body.
+
+## Accuracy
+
+Measured on real mail with cross-validation grouped by sender domain, so every score is for senders
+the model never saw in training, averaged over three shuffles, at the default threshold:
+
+| emails                                                         | result                         |
+| -------------------------------------------------------------- | ------------------------------ |
+| 324 emails with a one-time code                                | 67.3% correct, no wrong codes  |
+| 2,045 random emails                                            | none answered                  |
+| 8,862 hard negatives (order numbers, promo codes, magic links) | 0.9% answered (false positive) |
+
+The real training mail is mostly English and Estonian. Synthetic emails from fictional services in
+17 languages fill the gap: on 300 held-out synthetic emails the detector finds 97.5% of the codes
+with no wrong codes. Synthetic emails come from the same generator as the training ones, so treat that
+figure as an upper bound for real mail in those languages.
+
+## Repository layout
+
+| path        | contents                                                                        |
+| ----------- | ------------------------------------------------------------------------------- |
+| `src/`      | The library: HTML rendering, candidates, keywords, features, tree evaluation    |
+| `scripts/`  | Feature dump for training and a corpus scanner (`dump-features`, `scan-corpus`) |
+| `training/` | Python pipeline: corpus prefilter, LLM labeling, synthetic emails, training     |
+
+Training data is derived from private mail and lives in a separate private repository. Nothing in
+this repository contains message content; test fixtures are written by hand.
+
+## License
+
+MIT

package/dist/cjs/analyze.d.ts

@@ -0,0 +1,18 @@
+import type { Candidate } from './candidates.js';
+import type { Doc } from './doc.js';
+export type MessageInput = {
+    subject?: string | undefined;
+    /** The text/plain body */
+    text?: string | undefined;
+    /** The text/html body */
+    html?: string | undefined;
+};
+export type Occurrence = {
+    candidate: Candidate;
+    source: Doc['source'];
+    features: number[];
+};
+/** Bodies larger than this are cut; code notifications are a few kilobytes */
+export declare const MAX_BODY_CHARS: number;
+export declare function renderDocs(input: MessageInput): Doc[];
+export declare function analyze(input: MessageInput): Occurrence[];

package/dist/cjs/analyze.js

@@ -0,0 +1,41 @@
+"use strict";
+// Shared by the library and the training data dump, so that both compute features the same way.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BODY_CHARS = void 0;
+exports.renderDocs = renderDocs;
+exports.analyze = analyze;
+const candidates_js_1 = require("./candidates.js");
+const doc_js_1 = require("./doc.js");
+const features_js_1 = require("./features.js");
+const html_js_1 = require("./html.js");
+/** Bodies larger than this are cut; code notifications are a few kilobytes */
+exports.MAX_BODY_CHARS = 512 * 1024;
+function renderDocs(input) {
+    const docs = [];
+    if (input.html) {
+        docs.push((0, html_js_1.renderHtml)(input.html.slice(0, exports.MAX_BODY_CHARS)));
+    }
+    if (input.text) {
+        docs.push((0, doc_js_1.renderText)(input.text.slice(0, exports.MAX_BODY_CHARS)));
+    }
+    return docs.filter(d => d.text.length > 0);
+}
+function analyze(input) {
+    const docs = renderDocs(input);
+    const perDoc = docs.map(doc => ({ doc, candidates: (0, candidates_js_1.extractCandidates)(doc) }));
+    const distinctCodes = new Set(perDoc.flatMap(d => d.candidates.map(c => c.code))).size;
+    const subject = (input.subject ?? '').slice(0, 1000);
+    const out = [];
+    for (const { doc, candidates } of perDoc) {
+        const ctx = (0, features_js_1.docContext)(doc, candidates);
+        const otherText = docs
+            .filter(d => d !== doc)
+            .map(d => d.text)
+            .join('\n');
+        const msg = (0, features_js_1.messageContext)(subject, otherText, distinctCodes);
+        candidates.forEach((candidate, i) => {
+            out.push({ candidate, source: doc.source, features: (0, features_js_1.candidateFeatures)(ctx, msg, i) });
+        });
+    }
+    return out;
+}

package/dist/cjs/candidates.d.ts

@@ -0,0 +1,14 @@
+import type { Doc } from './doc.js';
+export type CandidateKind = 'token' | 'dashed-part' | 'grouped' | 'spaced';
+export type Candidate = {
+    /** The code as it would be typed: separators inside digit groups and spaced letters removed */
+    code: string;
+    /** The text as it appears in the document */
+    raw: string;
+    start: number;
+    end: number;
+    kind: CandidateKind;
+};
+/** Whether a token without separators looks like a code */
+export declare function codeLike(core: string): boolean;
+export declare function extractCandidates(doc: Doc): Candidate[];

package/dist/cjs/candidates.js

@@ -0,0 +1,138 @@
+"use strict";
+// Finds every token in a document that could be a one-time code. This step is deliberately
+// generous: a code it misses can never be found, while a wrong candidate only costs the scorer
+// one more row to reject.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codeLike = codeLike;
+exports.extractCandidates = extractCandidates;
+const TOKEN_RE = /[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*/g;
+// Single characters separated by single spaces or line breaks: "4 8 2 9 1 7", or one digit per table cell
+const SPACED_RE = /(?<![A-Za-z0-9])[A-Z0-9](?:[ \n][A-Z0-9]){3,9}(?![A-Za-z0-9])/g;
+// Characters that glue a token to its neighbour into something that is not a code: 12.50, 10:30,
+// 1,000, a/b, user@host, snake_case
+const JOINERS = new Set(['.', ',', ':', '/', '@', '_', '\\', '=', '&', '?', '%', '+']);
+const ALNUM_RE = /[A-Za-z0-9]/;
+const MAX_CANDIDATES = 400;
+function isAlnum(ch) {
+    return ch !== undefined && ALNUM_RE.test(ch);
+}
+/** Whether a token without separators looks like a code */
+function codeLike(core) {
+    const len = core.length;
+    if (len > 12 && len <= 40) {
+        // Long random validation codes mix upper case, lower case and digits (domain validation)
+        return /[A-Z]/.test(core) && /[a-z]/.test(core) && /\d/.test(core) && /^[A-Za-z0-9]+$/.test(core);
+    }
+    if (len < 4 || len > 12) {
+        return false;
+    }
+    if (/^\d+$/.test(core)) {
+        return len <= 10;
+    }
+    const hasDigit = /\d/.test(core);
+    if (!hasDigit) {
+        // Letter-only codes are printed in capitals (Steam Guard style: QWKZT)
+        return /^[A-Z]+$/.test(core) && len <= 10;
+    }
+    if (!/[A-Za-z]/.test(core)) {
+        return false;
+    }
+    // 21st, 100mg, 1080p, 12px, 5000mAh
+    return !/^\d+(?:[a-z]{1,3}|mAh|MB|GB|KB|kB|Hz)$/.test(core);
+}
+// Checked once per whitespace separated chunk, never per token, so a long blob stays linear
+const URL_OR_ADDRESS_RE = /:\/\/|^www\.|@[A-Za-z0-9-]+\.|\.[a-z]{2,6}\//i;
+const CHUNK_RE = /\S+/g;
+function gluedToNeighbour(text, start, end) {
+    const before = text[start - 1];
+    const after = text[end];
+    if (before !== undefined && JOINERS.has(before) && isAlnum(text[start - 2])) {
+        return true;
+    }
+    return after !== undefined && JOINERS.has(after) && isAlnum(text[end + 1]);
+}
+function make(text, start, end, kind, code) {
+    return { code, raw: text.slice(start, end), start, end, kind };
+}
+function tokenCandidates(text, out) {
+    const tokens = [];
+    CHUNK_RE.lastIndex = 0;
+    for (let chunk = CHUNK_RE.exec(text); chunk; chunk = CHUNK_RE.exec(text)) {
+        if (URL_OR_ADDRESS_RE.test(chunk[0])) {
+            continue;
+        }
+        TOKEN_RE.lastIndex = 0;
+        for (let m = TOKEN_RE.exec(chunk[0]); m; m = TOKEN_RE.exec(chunk[0])) {
+            const start = chunk.index + m.index;
+            const end = start + m[0].length;
+            if (!gluedToNeighbour(text, start, end)) {
+                tokens.push({ start, end, value: m[0] });
+                addToken(text, start, m[0], out);
+            }
+        }
+    }
+    addDigitGroups(text, tokens, out);
+}
+function addToken(text, start, value, out) {
+    const end = start + value.length;
+    if (!value.includes('-')) {
+        if (codeLike(value)) {
+            out.push(make(text, start, end, 'token', value));
+        }
+        return;
+    }
+    const parts = value.split('-');
+    const joined = parts.join('');
+    if (/^\d+$/.test(joined)) {
+        // 123-456, 12-34-56: typed without the dashes. Other digit runs are phone numbers and dates
+        if (parts.every(p => p.length >= 2 && p.length <= 4) && codeLike(joined)) {
+            out.push(make(text, start, end, 'grouped', joined));
+        }
+        return;
+    }
+    if (joined.length >= 4 && value.length <= 40 && /\d/.test(joined) && /[A-Za-z]/.test(joined)) {
+        // ABCD-1234, G-123456, 4a7c01e9-82f3b6d0: keys printed with their dashes. Digit-only runs
+        // that are not two to four even groups are phone numbers and dates (372-5-555-0100)
+        out.push(make(text, start, end, 'token', value));
+    }
+    let offset = start;
+    for (const part of parts) {
+        if (codeLike(part)) {
+            out.push(make(text, offset, offset + part.length, 'dashed-part', part));
+        }
+        offset += part.length + 1;
+    }
+}
+// "123 456" and "1234 5678": two or three digit groups separated by a single space
+function addDigitGroups(text, tokens, out) {
+    for (let i = 0; i < tokens.length; i++) {
+        let digits = '';
+        for (let j = i; j < tokens.length && j < i + 3; j++) {
+            const token = tokens[j];
+            const separatedBySpace = j === i || (token.start === tokens[j - 1].end + 1 && text[token.start - 1] === ' ');
+            if (!/^\d{2,4}$/.test(token.value) || !separatedBySpace) {
+                break;
+            }
+            digits += token.value;
+            if (j > i && digits.length >= 6 && digits.length <= 9) {
+                out.push(make(text, tokens[i].start, token.end, 'grouped', digits));
+            }
+        }
+    }
+}
+function spacedCandidates(text, out) {
+    SPACED_RE.lastIndex = 0;
+    for (let m = SPACED_RE.exec(text); m; m = SPACED_RE.exec(text)) {
+        const code = m[0].replace(/[ \n]/g, '');
+        if (/\d/.test(code)) {
+            out.push(make(text, m.index, m.index + m[0].length, 'spaced', code));
+        }
+    }
+}
+function extractCandidates(doc) {
+    const out = [];
+    tokenCandidates(doc.text, out);
+    spacedCandidates(doc.text, out);
+    out.sort((a, b) => a.start - b.start || b.end - a.end);
+    return out.slice(0, MAX_CANDIDATES);
+}

package/dist/cjs/doc.d.ts

@@ -0,0 +1,52 @@
+export declare const DEFAULT_FONT_SIZE = 16;
+export type Style = {
+    fontSize: number;
+    bold: boolean;
+    letterSpacing: boolean;
+    link: boolean;
+    heading: boolean;
+    mono: boolean;
+    hidden: boolean;
+    /** Inside quoted reply history or a forwarded message */
+    quote: boolean;
+};
+export declare const DEFAULT_STYLE: Readonly<Style>;
+export type Span = {
+    start: number;
+    end: number;
+};
+export type StyledSpan = Span & {
+    style: Readonly<Style>;
+};
+export type Doc = {
+    source: 'html' | 'text';
+    text: string;
+    /** Consecutive, non-overlapping, sorted by start; text between spans is whitespace */
+    spans: StyledSpan[];
+    /** Every block, innermost ones included, sorted by start */
+    blocks: Span[];
+    /** Offset where reply history or a forwarded message starts, text.length if none */
+    quoteStart: number;
+};
+export declare class DocBuilder {
+    private parts;
+    private length;
+    private last;
+    private spans;
+    private blocks;
+    private openBlocks;
+    private readonly source;
+    constructor(source: 'html' | 'text');
+    private append;
+    text(raw: string, style: Readonly<Style>): void;
+    private dropTrailingSpace;
+    newline(): void;
+    openBlock(): void;
+    closeBlock(): void;
+    finish(): Doc;
+}
+export declare function renderText(input: string): Doc;
+/** The style at a text offset; whitespace between spans takes the style of the span before it */
+export declare function styleAt(doc: Doc, offset: number): Readonly<Style>;
+/** The smallest block that contains the whole range */
+export declare function blockAround(doc: Doc, start: number, end: number): Span;

package/dist/cjs/doc.js

@@ -0,0 +1,151 @@
+"use strict";
+// The common representation both the HTML and the plain text body are turned into: visible text,
+// the style of every stretch of it, and the blocks (paragraphs, table cells, lines) it is split in.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocBuilder = exports.DEFAULT_STYLE = exports.DEFAULT_FONT_SIZE = void 0;
+exports.renderText = renderText;
+exports.styleAt = styleAt;
+exports.blockAround = blockAround;
+exports.DEFAULT_FONT_SIZE = 16;
+exports.DEFAULT_STYLE = Object.freeze({
+    fontSize: exports.DEFAULT_FONT_SIZE,
+    bold: false,
+    letterSpacing: false,
+    link: false,
+    heading: false,
+    mono: false,
+    hidden: false,
+    quote: false
+});
+const SPACE_RE = /[\s\u00a0\u200b\u200c\u200d\u2028\u2029\ufeff]+/g;
+// "On Tue, 1 Jan 2025 John wrote:", Outlook and forward separators, and the same in Estonian
+const ATTRIBUTION_RE = /^(?:-{2,}\s*(?:original message|forwarded message|edastatud kiri|algne kiri)\s*-{2,}|-{5,}|on .{3,200}(?:wrote|kirjutas):|.{3,120}kirjutas(?: .{0,80})?:|from: .{3,200}\n(?:sent|date): )/im;
+class DocBuilder {
+    constructor(source) {
+        // The output is kept as parts plus its length and last character: reading back a string that
+        // is being appended to makes V8 flatten it on every call, which is quadratic on large bodies
+        this.parts = [];
+        this.length = 0;
+        this.last = '';
+        this.spans = [];
+        this.blocks = [];
+        this.openBlocks = [];
+        this.source = source;
+    }
+    append(chunk) {
+        this.parts.push(chunk);
+        this.length += chunk.length;
+        this.last = chunk[chunk.length - 1];
+    }
+    text(raw, style) {
+        const collapsed = raw.replace(SPACE_RE, ' ');
+        const atLineStart = this.length === 0 || this.last === '\n' || this.last === ' ';
+        const chunk = atLineStart && collapsed.startsWith(' ') ? collapsed.slice(1) : collapsed;
+        if (!chunk) {
+            return;
+        }
+        const start = this.length;
+        this.append(chunk);
+        const span = this.spans[this.spans.length - 1];
+        if (span && span.style === style && span.end === start) {
+            span.end = this.length;
+        }
+        else {
+            this.spans.push({ start, end: this.length, style });
+        }
+    }
+    dropTrailingSpace() {
+        if (this.last !== ' ') {
+            return;
+        }
+        const part = this.parts.pop();
+        const rest = part.slice(0, -1);
+        this.length--;
+        if (rest) {
+            this.parts.push(rest);
+        }
+        const prev = this.parts[this.parts.length - 1];
+        this.last = prev ? prev[prev.length - 1] : '';
+        const span = this.spans[this.spans.length - 1];
+        if (span && span.end > this.length) {
+            span.end = this.length;
+        }
+    }
+    newline() {
+        this.dropTrailingSpace();
+        if (this.length && this.last !== '\n') {
+            this.append('\n');
+        }
+    }
+    openBlock() {
+        this.newline();
+        this.openBlocks.push(this.length);
+    }
+    closeBlock() {
+        const start = this.openBlocks.pop();
+        if (start === undefined) {
+            return;
+        }
+        // Text is collapsed as it is added, so at most one whitespace character trails it
+        const end = this.length - (this.last === '\n' || this.last === ' ' ? 1 : 0);
+        if (end > start) {
+            this.blocks.push({ start, end });
+        }
+        this.newline();
+    }
+    finish() {
+        while (this.openBlocks.length) {
+            this.closeBlock();
+        }
+        const text = this.parts.join('').replace(/\s+$/, '');
+        const spans = this.spans.filter(s => s.start < text.length).map(s => ({ ...s, end: Math.min(s.end, text.length) }));
+        // Every line is a block too, which covers plain text and HTML without block elements
+        for (const line of text.matchAll(/[^\n]+/g)) {
+            this.blocks.push({ start: line.index, end: line.index + line[0].length });
+        }
+        this.blocks.sort((a, b) => a.start - b.start || b.end - a.end);
+        const attribution = ATTRIBUTION_RE.exec(text);
+        return { source: this.source, text, spans, blocks: this.blocks, quoteStart: attribution ? attribution.index : text.length };
+    }
+}
+exports.DocBuilder = DocBuilder;
+const QUOTED_STYLE = Object.freeze({ ...exports.DEFAULT_STYLE, quote: true });
+function renderText(input) {
+    const doc = new DocBuilder('text');
+    for (const line of input.replace(/\r\n?/g, '\n').split('\n')) {
+        doc.text(line, /^\s*>/.test(line) ? QUOTED_STYLE : exports.DEFAULT_STYLE);
+        doc.newline();
+    }
+    return doc.finish();
+}
+/** The style at a text offset; whitespace between spans takes the style of the span before it */
+function styleAt(doc, offset) {
+    let lo = 0;
+    let hi = doc.spans.length - 1;
+    let found;
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const span = doc.spans[mid];
+        if (span.start <= offset) {
+            found = span;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return found?.style ?? exports.DEFAULT_STYLE;
+}
+/** The smallest block that contains the whole range */
+function blockAround(doc, start, end) {
+    let best = { start: 0, end: doc.text.length };
+    for (const block of doc.blocks) {
+        if (block.start > start) {
+            break;
+        }
+        if (block.end >= end && block.end - block.start < best.end - best.start) {
+            best = block;
+        }
+    }
+    return best;
+}

package/dist/cjs/features.d.ts

@@ -0,0 +1,37 @@
+import type { Candidate } from './candidates.js';
+import type { Doc } from './doc.js';
+export declare const FEATURE_NAMES: readonly ["len", "digits", "upper", "lower", "isDigits", "isUpperAlpha", "isMixedCase", "kindGrouped", "kindSpaced", "kindDashedPart", "hasDash", "leadingZero", "distinctRatio", "trivialSequence", "looksYear", "colonBefore", "hashBefore", "currencyNear", "plusOrParenBefore", "digitNearby", "percentAfter", "strongBefore", "strongAfter", "weakBefore", "weakAfter", "cueBefore", "cueAfter", "negBefore", "negAfter", "strongInLine", "weakInLine", "negInLine", "strongRank", "lineLen", "aloneOnLine", "blockLen", "aloneInBlock", "fontSize", "fontRatio", "isLargestFont", "bold", "letterSpacing", "link", "heading", "mono", "hidden", "quoted", "relPosition", "fromHtml", "occurrences", "inOtherDoc", "inSubject", "subjectStrong", "subjectWeak", "subjectNeg", "docStrong", "docCue", "docLen", "candidates", "distinctCodes", "candidateIndex", "promoBefore", "promoAfter", "promoInLine", "docPromo", "subjectPromo", "vowelRatio", "longestLetterRun", "caseChanges"];
+type Hits = {
+    start: number;
+    end: number;
+}[];
+/** Per-document data shared by all candidates of the document */
+export type DocContext = {
+    doc: Doc;
+    strong: Hits;
+    weak: Hits;
+    cue: Hits;
+    neg: Hits;
+    promo: Hits;
+    dominantFont: number;
+    maxCandidateFont: number;
+    candidates: Candidate[];
+    strongRanks: Map<Candidate, number>;
+    /** How many candidates of the document share each code */
+    codeCounts: Map<string, number>;
+};
+/** Message data shared by the documents of one email */
+export type MessageContext = {
+    subject: string;
+    otherText: string;
+    distinctCodes: number;
+    subjectStrong: boolean;
+    subjectWeak: boolean;
+    subjectNeg: boolean;
+    subjectPromo: boolean;
+};
+export declare function messageContext(subject: string, otherText: string, distinctCodes: number): MessageContext;
+export declare function docContext(doc: Doc, candidates: Candidate[]): DocContext;
+/** The feature vector of the candidate at `index` in ctx.candidates */
+export declare function candidateFeatures(ctx: DocContext, msg: MessageContext, index: number): number[];
+export {};