Initial Commit

openspec/archive/2026-05-24-email-processing/specs/email-processing/spec.md

@@ -0,0 +1,99 @@
+# Spec delta — email-processing
+
+## ADDED Requirements
+
+### Requirement: Parse RFC 822 messages with hook pipeline
+
+The package SHALL expose `parseEmail(raw, options?)` that:
+
+- accepts `string | ArrayBuffer | Uint8Array`,
+- validates `options` via a strict Zod schema,
+- raises `EmailProcessingError(INVALID_INPUT)` for null / undefined /
+    wrong-type `raw`,
+- raises `EmailProcessingError(INVALID_OPTIONS)` for any Zod failure,
+- wraps `postal-mime` parse failures in
+    `EmailProcessingError(PARSE_FAILURE)` and increments the OTel
+    counter `email_processing.parse.failure_total`,
+- on success, increments `email_processing.parse.total` (attributed
+    by attachment count) and pipes the result through the
+    `email:processing` hook pipeline.
+
+#### Scenario: Successful parse threads through the hook pipeline
+
+- **WHEN** `parseEmail` is called with a valid multipart MIME string
+    and an `onEmailProcessing` handler is registered that mutates
+    `parsed.subject`
+- **THEN** the returned `ParsedEmail.subject` reflects the handler's
+    transformation.
+
+### Requirement: Attachment processing with size + MIME allowlist
+
+`processAttachment` SHALL hash content with SHA-256, validate against
+`maxSize` (default 25 MiB) and `allowedMimeTypes` (wildcard `image/*`
+supported), increment `email_processing.attachment.processed_total` or
+`...rejected_total` (attributed by reason), and record an
+`...extraction_duration_ms` histogram entry per call.
+
+#### Scenario: Attachment over maxSize is rejected with reason=size
+
+- **WHEN** `processAttachment` is called with content larger than the
+    configured `maxSize`
+- **THEN** the result has `valid: false`, the `error` mentions the
+    size limit, and the rejected counter is incremented with
+    `reason=size`.
+
+### Requirement: Hook pipeline with public registry
+
+The package SHALL expose `Hooks<TMap>`, `emailHooks`, and
+`onEmailProcessing`. Handler errors SHALL short-circuit the pipeline
+and surface as `EmailProcessingError(HOOK_FAILURE)`. The
+`email_processing.hook.invocation_total` counter SHALL be incremented
+once per successful pipeline invocation, attributed by event name and
+handler count.
+
+### Requirement: DKIM / SPF / DMARC verification
+
+- `verifyDkim` SHALL parse the `DKIM-Signature` header, look up the
+    public key through an injectable DNS resolver, recompute the body
+    hash, rebuild the canonicalised signed-header block, call
+    `crypto.subtle.verify`, and emit
+    `email_processing.dkim.result_total` attributed by outcome.
+- `checkSpf` SHALL enforce `MAX_INCLUDE_DEPTH = 10` and
+    `MAX_DNS_LOOKUPS = 10`, emit
+    `email_processing.spf.result_total` attributed by outcome.
+- `checkDmarc` SHALL combine SPF + DKIM into a relaxed / strict
+    alignment evaluation, emit
+    `email_processing.dmarc.result_total` attributed by outcome.
+
+### Requirement: Heuristic spam scoring
+
+`scoreSpam` SHALL apply the twelve default rules, accept
+`customRules` (which replace defaults with the same `id`), clamp the
+score at `[0, 10]`, classify against `suspiciousThreshold` (default
+3) and `spamThreshold` (default 6), and emit
+`email_processing.spam.scored_total` attributed by classification.
+
+### Requirement: Threading
+
+`groupThreads` SHALL produce one `EmailThread` per conversation,
+using `In-Reply-To`, `References`, and a subject-change heuristic,
+sorted chronologically by first-message date. The
+`email_processing.thread.grouped_total` counter SHALL be incremented
+with the produced thread count per call.
+
+### Requirement: Stable error registry
+
+The package SHALL expose `EMAIL_PROCESSING_CODES` containing exactly
+eight codes — `INVALID_INPUT`, `PARSE_FAILURE`, `INVALID_OPTIONS`,
+`ATTACHMENT_TOO_LARGE`, `ATTACHMENT_TYPE_REJECTED`, `HASH_FAILURE`,
+`DKIM_VERIFY_FAILURE`, `HOOK_FAILURE`. Every code SHALL be thrown by
+at least one production path. `EmailProcessingError`'s constructor
+SHALL be `public`.
+
+#### Scenario: Public constructor allows direct construction
+
+- **WHEN** a downstream package imports `EmailProcessingError` and
+    `EMAIL_PROCESSING_CODES.INVALID_INPUT` and calls `new
+    EmailProcessingError(code, key)`
+- **THEN** TypeScript accepts the call and the resulting instance
+    has `code === "EMAIL_PROCESSING.INVALID_INPUT"`.