Import and export

The format is detected from the file content (ZIP entries, JSON keys, XML root element or CSV header row), so the source the user picks in the wizard only selects the instructions. Two sources force a format: Excel/CSV always shows the column mapping, Passbolt also accepts Passbolt's copies of other layouts.

Mapping rules

• Logins use the well-known fields username, password, url and totp. Further URLs become extra "Website" fields; the title falls back to the host name, then the username.
• One-time passwords are kept when they are an otpauth://totp/ URI or a Base32 setup key (spaces and dashes are removed; key=… from older KeePass plugins is understood). Anything else (a six-digit code, HOTP) is kept as a hidden field and reported.
• Cards use cardholder, card_number, card_expiry (MM/YYYY) and card_code; brand and PIN become extra fields.
• Identities use stable field IDs (first_name, last_name, email, phone, address, postal_code, city, country, company, job_title, ssn, passport_number, …); see IDENTITY_FIELDS in build.ts.
• Folders and groups become one tag with the full path (Work/Servers). KeePass root groups ("Root", the database name) are dropped. Tags of the source are kept as tags.
• Unknown data is kept: columns or fields Passbox has no slot for become extra text fields (hidden when the source marks them as secret), and item types Passbox does not have yet are imported as "Other" with all their fields. Nothing is silently dropped except sync bookkeeping (Firefox guid and timestamps, KeePass icons and modification dates).
• Not imported, and reported in the wizard: items in the source's trash, attachments, passkeys that the source does not export, empty rows.
• URLs without a scheme get https://.

Passkeys

Only Bitwarden JSON and KeePassXC XML export passkeys with their private key. Passbox imports them when they are ES256 (P-256) keys: Bitwarden's GUID credential IDs are converted to their 16 raw bytes, PEM keys from KeePassXC to PKCS#8 DER. 1Password, Apple and Proton Pass do not export usable passkeys; the wizard lists the affected items so users can keep them in the old app or register a new passkey.

Generic CSV and column detection

detectColumns(headers) suggests a target for each column from English and German header names (for example Bezeichnung, Benutzername, Kennwort, Webseite, Bemerkung, Ordner). Exact names win over partial matches, each target is used once, a lone email column becomes the username, and columns that look secret (PIN, Code, Geheim) become hidden fields. Everything else becomes a visible extra field. The user can change every column in the mapping step; mappingProblem blocks mappings without any useful column or with a target used twice.

Columns the header rules do not recognize can get a suggestion in the mapping step: Suggest fields uses value patterns on the device (URLs → website, email addresses → username, otpauth:///Base32 → one-time password, random strings → hidden field); with the AI feature switched on, Suggest with AI asks the configured model and sends only the headers and a pattern profile per column, never cell values. Suggestions are marked and can be undone. See architecture/ai-gateway.md.

Duplicates

An imported login is a duplicate of an existing one when the normalized host (lower case, without www., ignoring path and scheme) and the username (case-insensitive) match. Other items match on category and title. Items in the trash are ignored. For each duplicate the user chooses Skip (default), Update existing (imported values replace existing ones, new fields are added, tags and passkeys are merged, a different note is appended, and the old password goes into the password history) or Keep both.

Large imports

PassboxClient.importItems uploads items with up to six requests in flight, refreshes the item list every 200 items, yields to the event loop between batches and syncs once at the end. Server errors and dropped connections are retried with backoff, and the number of parallel requests halves while the server reports errors, then grows again. The wizard shows a progress bar and can stop the import.

Measured with a synthetic Chrome CSV against a local debug build of the server (packages/client/src/import/import.integration.test.ts, PASSBOX_IMPORT_BENCH=10000). These numbers are from the SQLite server before ADR 0007 and have not been repeated on PostgreSQL yet:

The longest pause between two progress callbacks stayed below 30 ms (no frozen UI); 40,000 items take a few minutes. When the server reports errors, the client's retries absorb them.

Exports exclude items in the trash unless the user asks for them, and can be limited to some vaults. The dialog requires the master password again (checked locally: the derived key must decrypt the account key; no new sign-in).

Encrypted export (.pbx-export, recommended)

A JSON envelope whose payload is encrypted with a password chosen for this file (independent of the account, so it can be imported into any Passbox account):

{
  "format": "passbox-export",
  "version": 1,
  "kdf": { "algorithm": "argon2id", "salt": "<16 bytes, Base64url>", "memoryKib": 131072, "iterations": 3, "parallelism": 4 },
  "cipher": "xchacha20poly1305",
  "ciphertext": "<Base64url>"
}

• key = HKDF-SHA256(Argon2id(password, salt, params), info = "passbox/v1/export").
• The ciphertext is the standard Passbox AEAD envelope (version, algorithm, 24-byte nonce, XChaCha20-Poly1305) with the header as associated data: "passbox-export" 0 "1" 0 "argon2id" 0 m 0 t 0 p 0 salt 0 "xchacha20poly1305". Changing any header field, for example lowering the KDF cost, makes decryption fail.
• Decryption enforces KdfParams::MINIMUM (64 MiB, 3 passes) and a maximum (1 GiB, 64 passes, 16 lanes), so a crafted file can neither downgrade the derivation nor exhaust memory.
• The UI requires an export password with a strength score of at least 3.
• The decrypted payload is {"format":"passbox-export-payload","version":1,"exportedAt":<ms>,"vaults":[{"name":…,"items":[<item data v1>…]}]} with the complete item data, including passkeys and password history.

Code: crates/core/src/export.rs (WebAssembly: encryptExport, decryptExport, isExport).

CSV export (not encrypted)

Bitwarden's CSV layout (folder,favorite,type,name,notes,fields,reprompt,login_uri,login_username,login_password,login_totp), which Bitwarden, Proton Pass, 1Password, Passbolt and Passbox import. Logins keep all their website fields (comma-separated) and extra fields (label: value lines); cards, identities and other items become notes with their fields. The folder is the first tag (prefixed with the vault name when several vaults are exported). Passkeys, password history and further tags are not included. Values are written unchanged, so a spreadsheet program may interpret cells that start with =, +, - or @ as formulas: do not open the file in Excel.

The dialog shows a strong warning and requires an explicit confirmation before it writes the file.

• pnpm --filter @passbox/client test: parsers against the fixtures in packages/client/src/import/fixtures (synthetic data only), format detection, duplicate detection, the encrypted export round trip through the WebAssembly core and the importer, and CSV export round trips.
• cargo test -p passbox-core export: the export envelope (round trip, wrong password, header authentication, KDF bounds, versions).
• PASSBOX_TEST_SERVER_URL=… pnpm --filter @passbox/client test: bulk import, duplicate update and master password check against a server; add PASSBOX_IMPORT_BENCH=10000 for the benchmark.
• pnpm e2e in passboxnet/web (e2e/tests/import.spec.ts): imports the Chrome fixture in the web app, finds the items, re-imports to see the duplicates, and exports encrypted and CSV files from Settings.