# @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`.