13 KiB
13 KiB
@suaveplan/password-formats - Universal import/export layer for common password-manager export formats — Apple Passwords CSV, Bitwarden JSON, Chrome CSV, KeePass XML
Summary
Universal import/export layer for common password-manager export formats. Parses Apple Passwords CSV, Bitwarden JSON, Chrome CSV, and KeePass XML into a normalized PasswordEntry[] array, and exports back to a universal CSV format.
Documentation tree
- detector — (no submodules)
- format-detector — (no submodules)
- parse — (no submodules)
- parse — (no submodules)
- validator — (no submodules)
- validate — (no submodules)
- errors — (no submodules)
- password-formats-error — (no submodules)
- export — (no submodules)
- csv-export — (no submodules)
- apple-passwords — (no submodules)
- apple-passwords — (no submodules)
- bitwarden — (no submodules)
- bitwarden — (no submodules)
- chrome — (no submodules)
- chrome — (no submodules)
- keepass — (no submodules)
- keepass — (no submodules)
Supported Formats
| Format | Type | Detection |
|---|---|---|
| Apple Passwords | CSV | OTPAuth + Title header columns |
| Bitwarden | JSON | items / encrypted keys |
| Chrome | CSV | name,url,username,password header |
| KeePass | XML | <KeePassFile tag |
Quick Start
import { parse, validate, exportToCsv } from "@suaveplan/password-formats";
// Auto-detect format and parse
const entries = await parse(fileContent);
// Validate entries
const result = validate(entries);
if (!result.valid) {
console.error(`${result.invalidCount} invalid entries`);
}
// Export to universal CSV
const csv = exportToCsv(entries);
Installation
bun add @suaveplan/password-formats
Modules
src/core/detector/format-detector.md— Format auto-detectionsrc/core/parse/parse.md— Main parse entry point with OTel instrumentationsrc/core/validator/validate.md— Entry validationsrc/parsers/apple-passwords/apple-passwords.md— Apple Passwords CSV parsersrc/parsers/bitwarden/bitwarden.md— Bitwarden JSON parsersrc/parsers/chrome/chrome.md— Chrome CSV parsersrc/parsers/keepass/keepass.md— KeePass XML parsersrc/export/csv-export.md— Universal CSV exportsrc/errors/password-formats-error.md— Error codes and class
Package Exports
| Export path | Description |
|---|---|
@suaveplan/password-formats |
Full re-export of all public APIs |
@suaveplan/password-formats/detect |
detect() function |
@suaveplan/password-formats/parse |
parse() + validate() functions |
@suaveplan/password-formats/parsers/apple |
parseApplePasswordsCsv() |
@suaveplan/password-formats/parsers/bitwarden |
parseBitwardenJson() |
@suaveplan/password-formats/parsers/chrome |
parseChromeCsv() |
@suaveplan/password-formats/parsers/keepass |
parseKeePassXml() |
@suaveplan/password-formats/export |
exportToCsv() |
@suaveplan/password-formats/errors |
PasswordFormatsError, PASSWORD_FORMATS_CODES |
API
parse(input, format?, options?)
async function parse(
input: string | Uint8Array,
format?: PasswordFormat,
options?: ParseOptions,
): Promise<PasswordEntry[]>
Auto-detects the format if not specified. Emits OTel metrics.
detect(input, filename?)
function detect(input: string | Uint8Array, filename?: string): PasswordFormat
Returns "apple" | "bitwarden" | "chrome" | "keepass" | "unknown".
validate(entries)
function validate(entries: PasswordEntry[]): ValidationResult
Checks that every entry has a non-empty title and password.
exportToCsv(entries)
function exportToCsv(entries: PasswordEntry[]): string
Exports to a 7-column CSV: title, url, username, password, notes, folder, tags.
Error Codes
| Code | Meaning |
|---|---|
PASSWORD_FORMATS.UNSUPPORTED_FORMAT |
Format could not be detected or is unsupported |
PASSWORD_FORMATS.PARSE_ERROR |
Malformed content |
PASSWORD_FORMATS.INVALID_INPUT |
Empty input |
PASSWORD_FORMATS.ENCRYPTED_NOT_SUPPORTED |
Bitwarden encrypted vault |
Dependencies
No @suaveplan/* runtime dependencies. External deps: papaparse, fast-xml-parser, fflate, zod, @opentelemetry/api, tslib.