Initial Commit

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

@@ -0,0 +1,27 @@
+# Capability Spec: password-formats
+
+**Package**: `@suaveplan/password-formats`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### PF-01 — Normalised entry shape
+`PasswordEntry` MUST be `{ id, title, username?, password, url?, urls?: string[], notes?, otp?, createdAt?, updatedAt?, folder?, tags?: string[], fields?: Record<string, string>, sourceFormat: PasswordFormat }`. Every parser MUST produce this shape. The schema MUST be enforced via `PasswordEntrySchema.parse`.
+
+### PF-02 — Format detection
+`detect(input)` MUST return one of `'apple-passwords' | 'bitwarden-json' | 'chrome' | 'keepass-xml' | 'lastpass' | '1password-csv' | '1password-1pux' | 'unknown'`. Detection MUST use a combination of filename heuristics (when provided) and content sniffing (first-line CSV header, XML root element, JSON shape, ZIP magic bytes). Unknown inputs MUST return `'unknown'`, not throw.
+
+### PF-03 — Parser dispatch
+`parse(input, format?)` MUST call `detect` when `format` is absent. Unknown formats MUST throw `PASSWORD_FORMATS.UNKNOWN_FORMAT`. Encrypted inputs (Bitwarden `encrypted: true`, encrypted `.1pux`) MUST throw `PASSWORD_FORMATS.ENCRYPTED_INPUT` with actionable context.
+
+### PF-04 — CSV round-trip
+`exportToCsv(parse(x))` MUST be a stable fixed point for CSV-sourced inputs ignoring field ordering and optional fields; round-trip property tests MUST verify this on generated entries.
+
+### PF-05 — Validation
+`validate(entries)` MUST return `{ ok, errors: Array<{ index, field, message }> }`. Validation MUST reject entries missing `password` or `title`.
+
+### PF-06 — Observability
+Parsing MUST record `password_formats.parse.duration_ms` histogram (label `format`) and `password_formats.entries.total` counter (label `format`). No password values MUST appear in OTel attributes.