138 lines
13 KiB
Markdown
138 lines
13 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [detector](./src/core/detector/format-detector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [format-detector](./src/core/detector/format-detector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [validator](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [validate](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [errors](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [password-formats-error](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [csv-export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [format-detector](./src/core/detector/format-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [validator](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [password-formats-error](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_- [csv-export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_- [format-detector](./src/core/detector/format-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [validator](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [password-formats-error](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_- [csv-export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_- [format-detector](./src/core/detector/format-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [validator](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [password-formats-error](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_- [csv-export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_- [format-detector](./src/core/detector/format-detector.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_ - [parse](./src/core/parse/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [validator](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_ - [validate](./src/core/validator/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [password-formats-error](./src/errors/password-formats-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_ - [csv-export](./src/export/csv-export.md) — <!-- begin:auto-docs --> _(no submodules)_- [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_ - [apple-passwords](./src/parsers/apple-passwords/apple-passwords.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_ - [bitwarden](./src/parsers/bitwarden/bitwarden.md) — <!-- begin:auto-docs --> _(no submodules)_- [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_ - [chrome](./src/parsers/chrome/chrome.md) — <!-- begin:auto-docs --> _(no submodules)_- [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(no submodules)_ - [keepass](./src/parsers/keepass/keepass.md) — <!-- begin:auto-docs --> _(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
|
|
|
|
```ts
|
|
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
|
|
|
|
```bash
|
|
bun add @suaveplan/password-formats
|
|
```
|
|
|
|
## Modules
|
|
|
|
- [`src/core/detector/format-detector.md`](src/core/detector/format-detector.md) — Format auto-detection
|
|
- [`src/core/parse/parse.md`](src/core/parse/parse.md) — Main parse entry point with OTel instrumentation
|
|
- [`src/core/validator/validate.md`](src/core/validator/validate.md) — Entry validation
|
|
- [`src/parsers/apple-passwords/apple-passwords.md`](src/parsers/apple-passwords/apple-passwords.md) — Apple Passwords CSV parser
|
|
- [`src/parsers/bitwarden/bitwarden.md`](src/parsers/bitwarden/bitwarden.md) — Bitwarden JSON parser
|
|
- [`src/parsers/chrome/chrome.md`](src/parsers/chrome/chrome.md) — Chrome CSV parser
|
|
- [`src/parsers/keepass/keepass.md`](src/parsers/keepass/keepass.md) — KeePass XML parser
|
|
- [`src/export/csv-export.md`](src/export/csv-export.md) — Universal CSV export
|
|
- [`src/errors/password-formats-error.md`](src/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?)`
|
|
|
|
```ts
|
|
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?)`
|
|
|
|
```ts
|
|
function detect(input: string | Uint8Array, filename?: string): PasswordFormat
|
|
```
|
|
|
|
Returns `"apple" | "bitwarden" | "chrome" | "keepass" | "unknown"`.
|
|
|
|
### `validate(entries)`
|
|
|
|
```ts
|
|
function validate(entries: PasswordEntry[]): ValidationResult
|
|
```
|
|
|
|
Checks that every entry has a non-empty `title` and `password`.
|
|
|
|
### `exportToCsv(entries)`
|
|
|
|
```ts
|
|
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`.
|