Initial Commit

openspec/archive/2026-04-19-enterprise-dmarc/proposal.md

@@ -0,0 +1,35 @@
+# OpenSpec Change: enterprise-dmarc
+
+- **Change ID**: enterprise-dmarc
+- **Package**: `@suaveplan/dmarc`
+- **Category**: universal
+- **Target path**: `universal/email/dmarc`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/dmarc.md`
+
+## Summary
+Parses DMARC aggregate (RUA) and forensic (RUF) reports into typed structures. Input: raw XML or `application/gzip`-wrapped XML as produced by Google / Microsoft / Yahoo aggregate reporters. Output: `DmarcAggregateReport` / `DmarcForensicReport`. Leaf package — useful to deliverability analytics.
+
+## Current-state audit (genesis)
+Package does not exist yet — fresh build.
+
+## Dependencies
+- Workspace: none (leaf)
+- External (via catalog): `fast-xml-parser`, `fflate`, `zod`, `tslib`, `@opentelemetry/api`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+- `parseDmarcAggregate(input, options?): DmarcAggregateReport`
+- `parseDmarcForensic(input, options?): DmarcForensicReport`
+- Types: `DmarcAggregateReport`, `DmarcForensicReport`, `DmarcRecord`, `DmarcPolicyPublished`, `DmarcAuthResult`, `DmarcDateRange`, `DmarcIdentifier`, `DmarcReportMetadata`, `AlignmentMode`, `DispositionMode`
+
+## New genesis additions
+- Codes: `DMARC.PARSE_ERROR`, `DMARC.INVALID_REPORT`, `DMARC.UNSUPPORTED_ENCODING`.
+- Zod schemas for each report type.
+- OTel counter `dmarc.parse.total{kind}`, histogram `dmarc.parse.duration_ms{kind}`.
+- Property tests on random but structurally valid XML trees.
+
+## Impact
+- Adds one new package: `universal/email/dmarc`
+- Adds one new spec capability: `dmarc`

openspec/archive/2026-04-19-enterprise-dmarc/specs/dmarc/spec.md

@@ -0,0 +1,24 @@
+# Capability Spec: dmarc
+
+**Package**: `@suaveplan/dmarc`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### DMARC-01 — Aggregate report parsing
+`parseDmarcAggregate(input)` MUST accept raw XML or gzip-wrapped XML (magic `1F 8B`). It MUST return `DmarcAggregateReport { reportMetadata, policyPublished, records: DmarcRecord[] }` matching the schema published at `https://dmarc.org/dmarc-xml/0.1/rua.xsd`.
+
+### DMARC-02 — Forensic report parsing
+`parseDmarcForensic(input)` MUST parse a single RFC 6591 message/feedback-report into `DmarcForensicReport { reportedDomain, sourceIp, identifier, authResults, originalMessage? }`.
+
+### DMARC-03 — Policy / alignment fields
+`AlignmentMode` MUST be `'r' | 's'`. `DispositionMode` MUST be `'none' | 'quarantine' | 'reject'`. `DmarcAuthResult` MUST carry `{ dkim: 'pass' | 'fail', spf: 'pass' | 'fail' }` (minimum).
+
+### DMARC-04 — Validation
+Every report output MUST pass its Zod schema. Invalid input MUST throw `DMARC.INVALID_REPORT` with the failing XPath in context.
+
+### DMARC-05 — Observability
+Parsing MUST record `dmarc.parse.duration_ms{kind}` histogram and `dmarc.parse.total{kind}` counter (`kind` ∈ `aggregate | forensic`).

openspec/archive/2026-04-19-enterprise-dmarc/tasks.md

@@ -0,0 +1,25 @@
+# Tasks: enterprise-dmarc
+
+## 1. Scaffold
+- [x] 1.1 `universal/email/dmarc/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+- [x] 2.1 `src/errors/dmarc-error.ts` — codes.
+- [x] 2.2 Zod schemas for `DmarcAggregateReport`, `DmarcForensicReport`, nested types.
+
+## 3. Decoders
+- [x] 3.1 `src/decoders/gzip.ts` — inflate via `fflate`.
+- [x] 3.2 `src/decoders/xml.ts` — `fast-xml-parser` with strict option set.
+
+## 4. Parsers
+- [x] 4.1 `src/parsers/aggregate.ts` — `parseDmarcAggregate`.
+- [x] 4.2 `src/parsers/forensic.ts` — `parseDmarcForensic`.
+- [x] 4.3 Fixture-based tests (Google/Microsoft/Yahoo samples).
+
+## 5. Docs / barrel / subpath exports / README
+
+## 6. Benchmarks
+- [x] 6.1 Parse a 500 KB aggregate report.
+
+## 7. Ship gate
+- [x] 7.1 Verification sequence; fold + archive.