From ebd817e3d03cce88a53dff394881bc51a1827c10 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 29 Aug 2026 10:11:38 +0000
Subject: [PATCH] Implement OpenCreds: two more item types, and a portable
 vault

The vault could hold logins, cards, identities and notes, and could only
leave through a CSV. A CSV is plaintext by construction, drops whatever
it has no column for -- password history, TOTP seeds, folders, custom
fields, URI match rules -- and carries no integrity: one truncated at
3,000 rows imports 3,000 rows and reports success.

This implements OpenCreds 0.1 (https://logicsrc.com/opencreds), which
specifies the record, the envelope and a portable file.

Two more item types, both things people already keep in a vault and
neither expressible as a login:

- key (5): SSH and PGP keys, API tokens, certificates, .env secrets.
  Carries path and mode, so a restore is total -- a private key written
  back 0644 is a key ssh refuses to use, and one at the wrong path is a
  key nothing finds.
- account (6): a provider account and the OAuth tokens that act as it.
  Deliberately not a login: a login is what a person types at a sign-in
  form, an account is what a machine presents to an API. Conflating them
  is how a rotated refresh token ends up in a password history array.

Codes 1-4 are untouched. This vault's deployed codes are what fixed them
in the specification; renumbering would break every ciphertext already
written. For the same reason the vault declares the namespace
`marksyncr` rather than adopting `opencreds` -- its labels are compiled
into the AAD of every ciphertext it has written, so editing one would
not migrate a vault, it would make it undecryptable. `marksyncr` is a
registered namespace, and not one existing vault needed re-encrypting.

The portable database, both directions. Encrypted by default under a key
derived from an export passphrase, not the vault's user key -- a file
encrypted under the user key only opens inside the vault it came from.
The header is bound as AAD over the payload, so the manifest is
authenticated by the same tag as the data: the item count is previewable
before anyone types a passphrase, and cannot be a lie. Import writes
nothing when the passphrase is wrong, the file was altered, or the
manifest disagrees with the payload.

Import accepts an .opencreds file alongside the CSVs, prompting for the
passphrase with the real item count in the prompt. The editor gains
fields for both new types, and vault_items accepts type 5 and 6 in the
database and in the API validator.

packages/vault/__tests__/opencreds-interop.test.js drives this vault
against the reference implementation in both directions and asserts the
item records come back byte-identical -- a round trip inside one
implementation only proves the code agrees with itself. It skips when
the reference is not installed rather than reddening CI; point
OPENCREDS_REF at a built checkout to run it. Verified passing against
@logicsrc/opencreds: six types out and back, history, key modes and
account scopes intact, wrong passphrases and restated manifests refused.

149 vault tests, 786 extension tests, lint clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QRQrfuwuYKKV5UB9kLHuX5
---
 .../src/popup/components/VaultPanel.jsx       |  87 +++-
 .../components/vault/VaultItemEditor.jsx      | 183 ++++++++-
 apps/web/__tests__/vault-validation.test.js   |   7 +-
 apps/web/lib/vault-validation.js              |   5 +-
 docs/opencreds.md                             | 122 ++++++
 .../vault/__tests__/opencreds-interop.test.js | 167 ++++++++
 packages/vault/__tests__/opencreds.test.js    | 333 +++++++++++++++
 packages/vault/package.json                   |   3 +-
 packages/vault/src/import.js                  | 104 ++++-
 packages/vault/src/index.js                   |  20 +
 packages/vault/src/items.js                   |  75 ++++
 packages/vault/src/opencreds.js               | 378 ++++++++++++++++++
 .../20260829180000_vault_opencreds_types.sql  |  28 ++
 13 files changed, 1490 insertions(+), 22 deletions(-)
 create mode 100644 docs/opencreds.md
 create mode 100644 packages/vault/__tests__/opencreds-interop.test.js
 create mode 100644 packages/vault/__tests__/opencreds.test.js
 create mode 100644 packages/vault/src/opencreds.js
 create mode 100644 supabase/migrations/20260829180000_vault_opencreds_types.sql

diff --git a/apps/extension/src/popup/components/VaultPanel.jsx b/apps/extension/src/popup/components/VaultPanel.jsx
index f9794d5..db46d77 100644
--- a/apps/extension/src/popup/components/VaultPanel.jsx
+++ b/apps/extension/src/popup/components/VaultPanel.jsx
@@ -1,5 +1,5 @@
 import React, { useCallback, useEffect, useMemo, useState } from 'react';
-import { parseImport } from '@marksyncr/vault';
+import { detectImportKind, inspectOpenCredsFile, parseImport, parseOpenCredsImport } from '@marksyncr/vault';
 import { VaultUnlock } from './vault/VaultUnlock.jsx';
 import { VaultItemEditor } from './vault/VaultItemEditor.jsx';
 
@@ -31,8 +31,13 @@ const TYPE_META = {
   card: { label: 'Card', badge: 'bg-violet-50 text-violet-700' },
   identity: { label: 'Identity', badge: 'bg-amber-50 text-amber-700' },
   note: { label: 'Note', badge: 'bg-slate-100 text-slate-600' },
+  key: { label: 'Key', badge: 'bg-emerald-50 text-emerald-700' },
+  account: { label: 'Account', badge: 'bg-rose-50 text-rose-700' },
 };
 
+/** The types offered as new-item buttons. Notes are reachable from import. */
+const NEW_ITEM_TYPES = ['login', 'card', 'identity', 'key', 'account'];
+
 /** Search across the fields a person would actually search by. */
 export function filterItems(items, query) {
   const q = String(query || '').trim().toLowerCase();
@@ -251,23 +256,82 @@ export function VaultPanel() {
     await refreshStatus();
   };
 
+  /**
+   * Import a CSV export from another manager, or an OpenCreds database.
+   *
+   * An OpenCreds file is a whole vault rather than a table of logins: it
+   * carries folders, password history, TOTP seeds, and `key` and `account`
+   * items that no CSV has a column for. When it is encrypted — the default —
+   * the header still says what it holds, and that claim is authenticated, so
+   * the passphrase prompt can name a real number before anyone types anything.
+   */
   const onImport = async (event) => {
     const file = event.target.files?.[0];
     if (!file) return;
     event.target.value = '';
 
     const text = await file.text();
-    const { source, items: parsed, skipped } = parseImport(text);
 
-    if (!parsed.length) {
-      notify(skipped[0]?.reason || 'Nothing to import');
+    if (detectImportKind(text) !== 'opencreds') {
+      const { source, items: parsed, skipped } = parseImport(text);
+      if (!parsed.length) {
+        notify(skipped[0]?.reason || 'Nothing to import');
+        return;
+      }
+      const res = await sendMessage({ type: 'VAULT_IMPORT', payload: { items: parsed } });
+      if (res?.success) {
+        await loadItems(showTrash);
+        notify(
+          skipped.length
+            ? `Imported ${res.imported} from ${source}; skipped ${skipped.length}`
+            : `Imported ${res.imported} from ${source}`
+        );
+      } else {
+        notify(res?.error || 'Import failed');
+      }
+      return;
+    }
+
+    let header;
+    try {
+      header = inspectOpenCredsFile(text);
+    } catch (err) {
+      notify(err.message);
       return;
     }
 
-    const res = await sendMessage({ type: 'VAULT_IMPORT', payload: { items: parsed } });
+    let passphrase;
+    if (header.protected) {
+      // The popup has no modal layer, and asking here is better than importing
+      // nothing and explaining why afterwards.
+      passphrase = window.prompt(
+        `This OpenCreds file holds ${header.itemCount} ${
+          header.itemCount === 1 ? 'item' : 'items'
+        }. Enter its export passphrase to import.`
+      );
+      if (passphrase === null) return;
+    } else if (
+      !window.confirm(
+        `This OpenCreds file is unprotected — every secret in it is in the clear. Import ${header.itemCount} items anyway?`
+      )
+    ) {
+      return;
+    }
+
+    let parsed;
+    try {
+      parsed = await parseOpenCredsImport(text, { passphrase });
+    } catch (err) {
+      // A manifest mismatch, a wrong passphrase and an altered file all land
+      // here, and in every one of them nothing has been written.
+      notify(err.message);
+      return;
+    }
+
+    const res = await sendMessage({ type: 'VAULT_IMPORT', payload: { items: parsed.items } });
     if (res?.success) {
       await loadItems(showTrash);
-      notify(`Imported ${res.imported} from ${source}`);
+      notify(`Imported ${res.imported} of ${parsed.items.length} from OpenCreds`);
     } else {
       notify(res?.error || 'Import failed');
     }
@@ -338,8 +402,8 @@ export function VaultPanel() {
       </div>
 
       {!showTrash && (
-        <div className="flex gap-1.5">
-          {['login', 'card', 'identity'].map((type) => (
+        <div className="flex flex-wrap gap-1.5">
+          {NEW_ITEM_TYPES.map((type) => (
             <button
               key={type}
               type="button"
@@ -401,7 +465,12 @@ export function VaultPanel() {
         {!showTrash && (
           <label className="cursor-pointer text-xs font-medium text-primary-600 hover:underline">
             Import
-            <input type="file" accept=".csv,text/csv" onChange={onImport} className="hidden" />
+            <input
+              type="file"
+              accept=".csv,text/csv,.opencreds,.json,application/json,application/vnd.logicsrc.opencreds+json"
+              onChange={onImport}
+              className="hidden"
+            />
           </label>
         )}
       </div>
diff --git a/apps/extension/src/popup/components/vault/VaultItemEditor.jsx b/apps/extension/src/popup/components/vault/VaultItemEditor.jsx
index fe2991e..8efcf25 100644
--- a/apps/extension/src/popup/components/vault/VaultItemEditor.jsx
+++ b/apps/extension/src/popup/components/vault/VaultItemEditor.jsx
@@ -4,11 +4,23 @@ import { generatePassword, generatePassphrase, passwordEntropyBits } from '@mark
 /**
  * Create and edit vault items.
  *
- * One editor for all three types — logins, cards and identities differ only in
- * which field group they render, because they are one record shape underneath.
+ * One editor for every type — logins, cards, identities, notes, keys and
+ * accounts differ only in which field group they render, because they are one
+ * record shape underneath. The types are the OpenCreds six; see
+ * https://logicsrc.com/opencreds.
  */
 
-const TYPE_LABELS = { login: 'Login', card: 'Card', identity: 'Identity', note: 'Note' };
+const TYPE_LABELS = {
+  login: 'Login',
+  card: 'Card',
+  identity: 'Identity',
+  note: 'Note',
+  key: 'Key',
+  account: 'Account',
+};
+
+/** Key kinds, in the order people reach for them. */
+const KEY_TYPES = ['ssh', 'api', 'pgp', 'certificate', 'symmetric', 'env'];
 
 /**
  * Placeholder shown in place of a hidden password. Built rather than written as
@@ -36,6 +48,66 @@ function Field({ label, value, onChange, type = 'text', mono = false, autoFocus
   );
 }
 
+/** A multi-line field, for key bodies and anything else that wraps. */
+function TextArea({ label, value, onChange, rows = 3 }) {
+  return (
+    <label className="block">
+      <span className="text-[11px] font-medium text-slate-600">{label}</span>
+      <textarea
+        value={value || ''}
+        onChange={(e) => onChange(e.target.value)}
+        rows={rows}
+        spellCheck={false}
+        className="mt-0.5 w-full rounded-lg border border-slate-300 px-2.5 py-1.5 font-mono text-xs focus:border-primary-500 focus:outline-none focus:ring-1 focus:ring-primary-500"
+      />
+    </label>
+  );
+}
+
+/**
+ * A secret that is masked until asked for.
+ *
+ * Distinct from PasswordField because these have no generator: nobody generates
+ * an access token here, they paste the one the provider issued.
+ */
+function SecretField({ label, value, onChange, multiline = false }) {
+  const [revealed, setRevealed] = useState(false);
+
+  return (
+    <div>
+      <div className="flex items-center justify-between">
+        <span className="text-[11px] font-medium text-slate-600">{label}</span>
+        <button
+          type="button"
+          onClick={() => setRevealed((v) => !v)}
+          className="text-[10px] text-primary-600 hover:underline"
+        >
+          {revealed ? 'Hide' : 'Show'}
+        </button>
+      </div>
+      {multiline ? (
+        <textarea
+          value={revealed ? value || '' : value ? MASK : ''}
+          onChange={(e) => onChange(e.target.value)}
+          readOnly={!revealed && Boolean(value)}
+          rows={3}
+          spellCheck={false}
+          className="mt-0.5 w-full rounded-lg border border-slate-300 px-2.5 py-1.5 font-mono text-xs focus:border-primary-500 focus:outline-none focus:ring-1 focus:ring-primary-500"
+        />
+      ) : (
+        <input
+          type={revealed ? 'text' : 'password'}
+          value={value || ''}
+          onChange={(e) => onChange(e.target.value)}
+          autoComplete="off"
+          spellCheck={false}
+          className="mt-0.5 w-full rounded-lg border border-slate-300 px-2.5 py-1.5 font-mono text-xs focus:border-primary-500 focus:outline-none focus:ring-1 focus:ring-primary-500"
+        />
+      )}
+    </div>
+  );
+}
+
 /** The password field, with reveal and a generator. */
 function PasswordField({ value, onChange }) {
   const [revealed, setRevealed] = useState(false);
@@ -318,6 +390,111 @@ export function VaultItemEditor({ item, type: initialType, onSave, onCancel }) {
         </>
       )}
 
+      {type === 'key' && (
+        <>
+          <label className="block">
+            <span className="text-[11px] font-medium text-slate-600">Kind</span>
+            <select
+              value={group.keyType || ''}
+              onChange={(e) => setField('keyType')(e.target.value)}
+              className="mt-0.5 w-full rounded-lg border border-slate-300 px-2.5 py-1.5 text-sm focus:border-primary-500 focus:outline-none focus:ring-1 focus:ring-primary-500"
+            >
+              <option value="">Choose…</option>
+              {KEY_TYPES.map((kind) => (
+                <option key={kind} value={kind}>
+                  {kind}
+                </option>
+              ))}
+            </select>
+          </label>
+
+          {/* An api, env or symmetric key is one opaque string; the rest are a
+              keypair. Rendering both would ask for a public key for an API
+              token, which is a question with no answer. */}
+          {['api', 'env', 'symmetric'].includes(group.keyType) ? (
+            <SecretField label="Secret" value={group.value} onChange={setField('value')} />
+          ) : (
+            <>
+              <TextArea
+                label="Public key"
+                value={group.publicKey}
+                onChange={setField('publicKey')}
+              />
+              <SecretField
+                label="Private key"
+                value={group.privateKey}
+                onChange={setField('privateKey')}
+                multiline
+              />
+              <SecretField
+                label="Key passphrase"
+                value={group.passphrase}
+                onChange={setField('passphrase')}
+              />
+            </>
+          )}
+
+          <Field label="Algorithm" value={group.algorithm} onChange={setField('algorithm')} />
+          {/* Path and mode make a restore total: a private key written back
+              with the wrong mode is a key ssh refuses to use, and one at the
+              wrong path is a key nothing finds. */}
+          <div className="grid grid-cols-3 gap-2">
+            <div className="col-span-2">
+              <Field label="Path" value={group.path} onChange={setField('path')} mono />
+            </div>
+            <Field label="Mode" value={group.mode} onChange={setField('mode')} mono />
+          </div>
+          <Field
+            label="Fingerprint"
+            value={group.fingerprint}
+            onChange={setField('fingerprint')}
+            mono
+          />
+        </>
+      )}
+
+      {type === 'account' && (
+        <>
+          <div className="grid grid-cols-2 gap-2">
+            <Field label="Provider" value={group.provider} onChange={setField('provider')} />
+            <Field label="Handle" value={group.handle} onChange={setField('handle')} />
+          </div>
+          <Field label="Account id" value={group.accountId} onChange={setField('accountId')} mono />
+          <Field label="Email" value={group.email} onChange={setField('email')} type="email" />
+          <SecretField
+            label="Access token"
+            value={group.accessToken}
+            onChange={setField('accessToken')}
+          />
+          <SecretField
+            label="Refresh token"
+            value={group.refreshToken}
+            onChange={setField('refreshToken')}
+          />
+          <div className="grid grid-cols-2 gap-2">
+            {/* A test key and a live key look identical and are not. */}
+            <Field
+              label="Environment"
+              value={group.environment}
+              onChange={setField('environment')}
+            />
+            <Field label="Expires" value={group.expiresAt} onChange={setField('expiresAt')} />
+          </div>
+          <Field
+            label="Scopes (comma separated)"
+            value={Array.isArray(group.scopes) ? group.scopes.join(', ') : group.scopes}
+            onChange={(value) =>
+              setField('scopes')(
+                String(value)
+                  .split(',')
+                  .map((s) => s.trim())
+                  .filter(Boolean)
+              )
+            }
+          />
+        </>
+      )}
+
       <label className="block">
         <span className="text-[11px] font-medium text-slate-600">Notes</span>
         <textarea
diff --git a/apps/web/__tests__/vault-validation.test.js b/apps/web/__tests__/vault-validation.test.js
index 983d1d5..2c4e3f1 100644
--- a/apps/web/__tests__/vault-validation.test.js
+++ b/apps/web/__tests__/vault-validation.test.js
@@ -82,12 +82,15 @@ describe('validateItemPayload', () => {
     expect(validateItemPayload(withoutId, { requireId: false })).toBeNull();
   });
 
-  it.each([[0], [5], [null], ['login'], [1.5]])('rejects type %s', (type) => {
+  it.each([[0], [7], [null], ['login'], [1.5]])('rejects type %s', (type) => {
     expect(validateItemPayload({ ...validItem(), type })).toMatch(/Unknown item type/);
   });
 
   it('accepts every defined type', () => {
-    for (const type of [1, 2, 3, 4]) {
+    // The OpenCreds six: 1 login, 2 card, 3 identity, 4 note, 5 key, 6 account.
+    // Mirrors the vault_items_type_known constraint, so a rejection here and a
+    // rejection in the database mean the same thing.
+    for (const type of [1, 2, 3, 4, 5, 6]) {
       expect(validateItemPayload({ ...validItem(), type })).toBeNull();
     }
   });
diff --git a/apps/web/lib/vault-validation.js b/apps/web/lib/vault-validation.js
index 9a1bb88..41c590b 100644
--- a/apps/web/lib/vault-validation.js
+++ b/apps/web/lib/vault-validation.js
@@ -52,7 +52,10 @@ export function isSaneBlob(value, { required = true, maxLength = MAX_KEY_FIELD_L
 export function validateItemPayload(body, { requireId = true } = {}) {
   if (!body || typeof body !== 'object') return 'Invalid JSON body';
   if (requireId && !isUuid(body.id)) return 'A valid item id is required';
-  if (!Number.isInteger(body.type) || body.type < 1 || body.type > 4) return 'Unknown item type';
+  // OpenCreds type codes: 1 login, 2 card, 3 identity, 4 note, 5 key, 6 account.
+  // Mirrors the vault_items_type_known constraint, so a rejection here and a
+  // rejection in the database mean the same thing.
+  if (!Number.isInteger(body.type) || body.type < 1 || body.type > 6) return 'Unknown item type';
   if (!isSaneBlob(body.ciphertext, { maxLength: MAX_CIPHERTEXT_LENGTH })) {
     return 'Malformed ciphertext';
   }
diff --git a/docs/opencreds.md b/docs/opencreds.md
new file mode 100644
index 0000000..6c44bd4
--- /dev/null
+++ b/docs/opencreds.md
@@ -0,0 +1,122 @@
+# OpenCreds in the MarkSyncr vault
+
+The MarkSyncr vault implements **OpenCreds 0.1** — the open standard for
+credential records and portable vaults. Specification:
+<https://logicsrc.com/opencreds>.
+
+What that buys a person: they can leave. A vault exports as one encrypted file
+that another conforming implementation reads, with password history, TOTP seeds,
+folders, custom fields, URI match rules and every item type intact — rather than
+a CSV that writes every secret to disk in the clear and drops whatever it has no
+column for.
+
+## What this vault implements
+
+| Part of the spec | Status |
+| --- | --- |
+| Six item types (`login`, `card`, `identity`, `note`, `key`, `account`) | Yes |
+| Item envelope, AES-256-GCM with the id bound as AAD | Yes |
+| Key hierarchy: PBKDF2 → HKDF → wrapped random user key | Yes |
+| Recovery key | Yes |
+| Portable database, encrypted form — read and write | Yes |
+| Portable database, plaintext form — read and write | Yes, opt-in |
+| Manifest verification on import | Yes |
+| CSV importers (Bitwarden, 1Password, Chrome) | Yes |
+| `user` profile | Yes |
+| `team` profile | No — this is a personal vault |
+
+## Namespace
+
+This vault declares the namespace **`marksyncr`**.
+
+Every domain-separation label in OpenCreds is prefixed by the vault's namespace,
+and a label is compiled into the additional authenticated data of every
+ciphertext a vault has ever written. Editing one does not migrate a vault; it
+makes it undecryptable.
+
+MarkSyncr's vault shipped before OpenCreds existed, with `marksyncr:vault:*`
+labels already in every ciphertext. So the specification carries the prefix as a
+declared per-vault property rather than mandating one string, `marksyncr` is a
+registered namespace, and not one existing vault had to be re-encrypted to
+become conformant.
+
+Item type codes 1–4 are likewise the ones this vault already used. OpenCreds
+fixed them there and added 5 (`key`) and 6 (`account`).
+
+## Importing
+
+The Import control accepts a CSV export from another manager, or an OpenCreds
+database.
+
+```
+vault.opencreds   an OpenCreds database (encrypted by default)
+export.csv        Bitwarden, 1Password or Chrome
+```
+
+An OpenCreds file is a whole vault rather than a table of logins. When it is
+encrypted — the default — its header is still readable, and authenticated, so
+the passphrase prompt names the real item count before anyone types anything.
+
+Import fails, and writes nothing, when:
+
+- the passphrase is wrong;
+- the file was altered after export — the header is bound as additional
+  authenticated data over the payload, so a restated item count fails the tag;
+- the manifest disagrees with the payload — a dropped item, a truncated file, or
+  a re-ordered payload.
+
+That last one is the difference from a CSV. A CSV truncated at 3,000 rows
+imports 3,000 rows and reports success. There is no state in which this
+implementation reports a complete import of an incomplete file.
+
+## Exporting
+
+```js
+import { exportOpenCredsDatabase } from '@marksyncr/vault';
+
+const db = await exportOpenCredsDatabase({ folders, items }, { passphrase });
+```
+
+The export is encrypted under a key derived from the **export passphrase**, not
+the vault's own user key — a file encrypted under the user key would only open
+inside the vault it came from, which is the opposite of portable.
+
+The plaintext form exists because the products people move *to* frequently read
+nothing else. It requires `acknowledged: true` in code, writes
+`"protected": false` into its own header, and is never a default.
+
+## API
+
+```js
+import {
+  // reading
+  detectImportKind,        // 'opencreds' | 'csv' | 'unknown'
+  inspectOpenCredsFile,    // the header, without the passphrase
+  parseOpenCredsImport,    // decrypt + verify + return items and folders
+  importFile,              // one entry point for either kind
+
+  // writing
+  exportOpenCredsDatabase,
+  exportPlaintextOpenCredsDatabase,
+
+  // pieces
+  buildManifest,
+  verifyManifest,
+  openOpenCredsDatabase,
+  readOpenCredsHeader,
+  OPENCREDS_VERSION,
+  OPENCREDS_NAMESPACE,
+} from '@marksyncr/vault';
+```
+
+Nothing in this module touches the network. The CSV path touches no crypto at
+all; the OpenCreds path decrypts the file it was handed and nothing else. Both
+produce plain item objects, and the caller encrypts them into the vault.
+
+## Verifying interoperability
+
+`packages/vault/__tests__/opencreds-interop.test.js` drives this implementation
+against the OpenCreds reference implementation (`@logicsrc/opencreds`) when that
+package is present, in both directions, and asserts the item records come back
+byte-identical. It skips itself when the reference implementation is not
+installed, so it never turns CI red on a machine that simply does not have it.
diff --git a/packages/vault/__tests__/opencreds-interop.test.js b/packages/vault/__tests__/opencreds-interop.test.js
new file mode 100644
index 0000000..036676e
--- /dev/null
+++ b/packages/vault/__tests__/opencreds-interop.test.js
@@ -0,0 +1,167 @@
+/**
+ * Cross-implementation interoperability, against the OpenCreds reference
+ * implementation.
+ *
+ * The whole claim of the specification is that a vault exported from one
+ * conforming implementation imports into another with the item records
+ * unchanged. A round trip within one implementation proves nothing about that —
+ * it only proves this code agrees with itself — so these tests drive
+ * `@marksyncr/vault` against `@logicsrc/opencreds` in both directions.
+ *
+ * The reference implementation is not a dependency of this repo, and should not
+ * become one: MarkSyncr ships a vault, not a standards toolkit. So the suite
+ * resolves it at runtime and skips itself when it is absent, rather than turning
+ * CI red on a machine that simply does not have it. Point OPENCREDS_REF at a
+ * built checkout to run it.
+ */
+
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { createItem } from '../src/items.js';
+import { decryptItems, encryptItem } from '../src/items.js';
+import { randomBytes } from '../src/primitives.js';
+import {
+  exportOpenCredsDatabase,
+  exportPlaintextOpenCredsDatabase,
+} from '../src/opencreds.js';
+import { detectImportKind, inspectOpenCredsFile, parseOpenCredsImport } from '../src/import.js';
+
+const PASSPHRASE = 'opencreds-fixture';
+// The construction is under test, not the work factor.
+const FAST = { kdf: 'pbkdf2-sha256', iterations: 100_000 };
+
+/** The reference implementation, or null when it is not installed. */
+let ref = null;
+
+beforeAll(async () => {
+  const candidates = [
+    process.env.OPENCREDS_REF,
+    '@logicsrc/opencreds',
+  ].filter(Boolean);
+
+  for (const specifier of candidates) {
+    try {
+      ref = await import(specifier);
+      return;
+    } catch {
+      /* try the next one */
+    }
+  }
+});
+
+/** One item of every type, so no field group goes unexercised. */
+function payloadFrom(impl) {
+  const folder = { id: '11111111-1111-4111-8111-111111111111', name: 'Work' };
+  return {
+    folders: [folder],
+    items: [
+      impl.createItem('login', {
+        name: 'GitHub',
+        folderId: folder.id,
+        login: {
+          username: 'anthony',
+          password: 'hunter2',
+          totp: 'otpauth://totp/GitHub:anthony?secret=JBSWY3DPEHPK3PXP',
+          uris: [{ uri: 'https://github.com', match: 'domain' }],
+        },
+        history: [{ password: 'hunter1', changedAt: '2026-01-04T09:12:00.000Z' }],
+      }),
+      impl.createItem('card', {
+        name: 'Visa',
+        card: { number: '4242424242424242', code: '123', expMonth: '4', expYear: '2029' },
+      }),
+      impl.createItem('identity', { name: 'Me', identity: { firstName: 'Anthony', ssn: '000-00-0000' } }),
+      impl.createItem('note', { name: 'WiFi', notes: 'the password is on the router' }),
+      impl.createItem('key', {
+        name: 'deploy@railway',
+        key: { keyType: 'ssh', algorithm: 'ed25519', privateKey: '-----BEGIN-----', path: '~/.ssh/id_ed25519', mode: '0600' },
+      }),
+      impl.createItem('account', {
+        name: 'Stripe',
+        account: { provider: 'stripe', accessToken: 'sk_live_x', scopes: ['charges:write', 'customers:read'] },
+      }),
+    ],
+  };
+}
+
+describe('OpenCreds interoperability', () => {
+  it('has a reference implementation, or is skipped', (ctx) => {
+    if (!ref) ctx.skip();
+    expect(ref.OPENCREDS_VERSION).toBe('0.1');
+  });
+
+  it('reads a database the reference implementation wrote', async (ctx) => {
+    if (!ref) ctx.skip();
+    const payload = payloadFrom(ref);
+    const wire = JSON.stringify(await ref.exportDatabase(payload, { passphrase: PASSPHRASE, params: FAST }));
+
+    expect(detectImportKind(wire)).toBe('opencreds');
+
+    // The header is readable without the passphrase, and authenticated.
+    const header = inspectOpenCredsFile(wire);
+    expect(header.itemCount).toBe(6);
+    expect(header.namespace).toBe('opencreds');
+
+    const opened = await parseOpenCredsImport(wire, { passphrase: PASSPHRASE });
+    expect(opened.items).toEqual(payload.items);
+    expect(opened.folders).toEqual(payload.folders);
+
+    // The fields no CSV has a column for.
+    expect(opened.items[0].history[0].password).toBe('hunter1');
+    expect(opened.items.find((i) => i.type === 'key').key.mode).toBe('0600');
+    expect(opened.items.find((i) => i.type === 'account').account.scopes).toHaveLength(2);
+  }, 30_000);
+
+  it('stores every imported item in this vault, under this vault’s own labels', async (ctx) => {
+    if (!ref) ctx.skip();
+    const payload = payloadFrom(ref);
+    const wire = JSON.stringify(await ref.exportDatabase(payload, { passphrase: PASSPHRASE, params: FAST }));
+    const opened = await parseOpenCredsImport(wire, { passphrase: PASSPHRASE });
+
+    const userKey = randomBytes(32);
+    const rows = [];
+    for (const item of opened.items) rows.push(await encryptItem(userKey, item));
+
+    expect(rows.map((r) => r.type).sort()).toEqual([1, 2, 3, 4, 5, 6]);
+    const back = await decryptItems(userKey, rows);
+    expect(back.failed).toHaveLength(0);
+    expect(back.items).toHaveLength(6);
+  }, 30_000);
+
+  it('writes a database the reference implementation reads', async (ctx) => {
+    if (!ref) ctx.skip();
+    const payload = payloadFrom({ createItem });
+    const db = await exportOpenCredsDatabase(payload, { passphrase: PASSPHRASE, iterations: 100_000 });
+
+    const parsed = ref.parseDatabase(JSON.stringify(db));
+    expect(ref.readHeader(parsed).namespace).toBe('marksyncr');
+
+    const opened = await ref.openDatabase(parsed, { passphrase: PASSPHRASE });
+    expect(opened.items).toEqual(payload.items);
+  }, 30_000);
+
+  it('writes a plaintext database that passes the reference validator', async (ctx) => {
+    if (!ref) ctx.skip();
+    const db = await exportPlaintextOpenCredsDatabase(payloadFrom({ createItem }), { acknowledged: true });
+    const { diagnostics } = ref.validateDocument(JSON.parse(JSON.stringify(db)));
+    const errors = diagnostics.filter((d) => d.severity === 'error');
+    expect(ref.formatDiagnostics(errors)).toBe('');
+  });
+
+  it('survives a round trip out through the reference implementation and back', async (ctx) => {
+    if (!ref) ctx.skip();
+    const original = payloadFrom(ref);
+
+    const first = JSON.stringify(await ref.exportDatabase(original, { passphrase: PASSPHRASE, params: FAST }));
+    const here = await parseOpenCredsImport(first, { passphrase: PASSPHRASE });
+    const second = JSON.stringify(
+      await exportOpenCredsDatabase({ folders: here.folders, items: here.items }, { passphrase: PASSPHRASE, iterations: 100_000 })
+    );
+    const there = await ref.openDatabase(ref.parseDatabase(second), { passphrase: PASSPHRASE });
+
+    expect(there.items).toEqual(original.items);
+    // createdAt is the only evidence of when a password was last rotated.
+    expect(there.items[0].createdAt).toBe(original.items[0].createdAt);
+    expect(there.folders).toEqual(original.folders);
+  }, 60_000);
+});
diff --git a/packages/vault/__tests__/opencreds.test.js b/packages/vault/__tests__/opencreds.test.js
new file mode 100644
index 0000000..bd26514
--- /dev/null
+++ b/packages/vault/__tests__/opencreds.test.js
@@ -0,0 +1,333 @@
+/**
+ * OpenCreds — the portable vault database.
+ *
+ * These tests are the interoperability contract. A file this vault writes must
+ * open in any conforming implementation, and a file any conforming
+ * implementation writes must open here, with the item records byte-identical
+ * both ways.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { createItem, encryptItem, decryptItem, ITEM_TYPE } from '../src/items.js';
+import {
+  buildManifest,
+  exportOpenCredsDatabase,
+  exportPlaintextOpenCredsDatabase,
+  isOpenCredsDatabase,
+  NAMESPACE,
+  openOpenCredsDatabase,
+  OPENCREDS_VERSION,
+  parseOpenCredsDatabase,
+  readOpenCredsHeader,
+  verifyManifest,
+} from '../src/opencreds.js';
+import {
+  detectImportKind,
+  importFile,
+  inspectOpenCredsFile,
+  parseOpenCredsImport,
+} from '../src/import.js';
+import { randomBytes } from '../src/primitives.js';
+
+const PASSPHRASE = 'opencreds-fixture';
+// The construction is under test, not the work factor.
+const FAST = 100_000;
+
+function samplePayload() {
+  const work = { id: '11111111-1111-4111-8111-111111111111', name: 'Work' };
+  return {
+    folders: [work],
+    items: [
+      createItem('login', {
+        name: 'GitHub',
+        folderId: work.id,
+        login: {
+          username: 'anthony',
+          password: 'hunter2',
+          totp: 'otpauth://totp/GitHub',
+          uris: [{ uri: 'https://github.com', match: 'domain' }],
+        },
+      }),
+      createItem('card', { name: 'Visa', card: { number: '4242424242424242', code: '123' } }),
+      createItem('identity', { name: 'Me', identity: { firstName: 'Anthony' } }),
+      createItem('note', { name: 'WiFi', notes: 'on the router' }),
+      createItem('key', {
+        name: 'deploy',
+        key: { keyType: 'ssh', privateKey: '-----BEGIN-----', path: '~/.ssh/id_ed25519', mode: '0600' },
+      }),
+      createItem('account', {
+        name: 'Stripe',
+        account: { provider: 'stripe', accessToken: 'sk_live_x', scopes: ['charges:write'] },
+      }),
+    ],
+  };
+}
+
+describe('the six item types', () => {
+  it('carries the OpenCreds codes, with 1-4 unchanged', () => {
+    // Renumbering these would break every ciphertext already written.
+    expect(ITEM_TYPE).toEqual({ login: 1, card: 2, identity: 3, note: 4, key: 5, account: 6 });
+  });
+
+  it('creates a key and an account with their full field groups', () => {
+    const key = createItem('key', { name: 'deploy' });
+    expect(key.key).toMatchObject({ keyType: '', privateKey: '', path: '', mode: '' });
+
+    const account = createItem('account', { name: 'Stripe' });
+    expect(account.account).toMatchObject({ provider: '', accessToken: '', scopes: [] });
+  });
+
+  it('round-trips a key and an account through the vault envelope', async () => {
+    const userKey = randomBytes(32);
+    for (const item of [
+      createItem('key', { name: 'deploy', key: { keyType: 'ssh', privateKey: 'SECRET' } }),
+      createItem('account', { name: 'Stripe', account: { accessToken: 'sk_live_x' } }),
+    ]) {
+      const row = await encryptItem(userKey, item);
+      expect(row.type).toBe(ITEM_TYPE[item.type]);
+      expect(row.ciphertext).not.toContain('SECRET');
+      expect(await decryptItem(userKey, row)).toEqual(item);
+    }
+  });
+
+  it('refuses to encrypt an item carrying another type’s group', async () => {
+    const userKey = randomBytes(32);
+    const item = { ...createItem('login', { name: 'x' }), account: { provider: 'stripe' } };
+    await expect(encryptItem(userKey, item)).rejects.toThrow(/must not carry an account field group/);
+  });
+});
+
+describe('the manifest', () => {
+  it('counts by type and digests the sorted ids', async () => {
+    const manifest = await buildManifest(samplePayload());
+    expect(manifest.itemCount).toBe(6);
+    expect(manifest.folderCount).toBe(1);
+    expect(manifest.types).toEqual({ login: 1, card: 1, identity: 1, note: 1, key: 1, account: 1 });
+  });
+
+  it('digests identically whatever order the items arrive in', async () => {
+    const payload = samplePayload();
+    const reversed = { ...payload, items: [...payload.items].reverse() };
+    expect((await buildManifest(reversed)).digest).toBe((await buildManifest(payload)).digest);
+  });
+
+  it('reports every disagreement rather than the first', async () => {
+    const payload = samplePayload();
+    const manifest = await buildManifest(payload);
+    const problems = await verifyManifest(manifest, { ...payload, items: payload.items.slice(0, 4) });
+    expect(problems.length).toBeGreaterThan(1);
+    expect(problems.join(' ')).toMatch(/says 6 items, payload has 4/);
+  });
+});
+
+describe('exporting', () => {
+  it('writes an encrypted database with no plaintext secret in it', async () => {
+    const db = await exportOpenCredsDatabase(samplePayload(), {
+      passphrase: PASSPHRASE,
+      iterations: FAST,
+    });
+
+    expect(db.opencreds).toBe(OPENCREDS_VERSION);
+    expect(db.protected).toBe(true);
+    expect(db.namespace).toBe(NAMESPACE);
+    const raw = JSON.stringify(db);
+    expect(raw).not.toContain('hunter2');
+    expect(raw).not.toContain('4242424242424242');
+    expect(raw).not.toContain('sk_live_x');
+    // The counts are readable without the passphrase, for a preview.
+    expect(db.manifest.itemCount).toBe(6);
+  });
+
+  it('round-trips a whole vault', async () => {
+    const payload = samplePayload();
+    const db = await exportOpenCredsDatabase(payload, { passphrase: PASSPHRASE, iterations: FAST });
+    const back = await openOpenCredsDatabase(db, { passphrase: PASSPHRASE });
+    expect(back.items).toEqual(payload.items);
+    expect(back.folders).toEqual(payload.folders);
+  });
+
+  it('refuses a plaintext export that was not asked for in so many words', async () => {
+    await expect(exportPlaintextOpenCredsDatabase(samplePayload(), {})).rejects.toThrow(
+      /every secret in the vault out unencrypted/
+    );
+  });
+
+  it('labels a plaintext export unprotected in its own header', async () => {
+    const db = await exportPlaintextOpenCredsDatabase(samplePayload(), { acknowledged: true });
+    expect(db.protected).toBe(false);
+    expect(JSON.stringify(db)).toContain('hunter2');
+  });
+
+  it('uses a fresh salt and IV each time', async () => {
+    const payload = samplePayload();
+    const a = await exportOpenCredsDatabase(payload, { passphrase: PASSPHRASE, iterations: FAST });
+    const b = await exportOpenCredsDatabase(payload, { passphrase: PASSPHRASE, iterations: FAST });
+    expect(a.ciphertext).not.toBe(b.ciphertext);
+    expect(a.kdf.salt).not.toBe(b.kdf.salt);
+  });
+});
+
+describe('importing', () => {
+  it('rejects the wrong passphrase', async () => {
+    const db = await exportOpenCredsDatabase(samplePayload(), {
+      passphrase: PASSPHRASE,
+      iterations: FAST,
+    });
+    await expect(openOpenCredsDatabase(db, { passphrase: 'nope' })).rejects.toThrow(
+      /Could not decrypt/
+    );
+  });
+
+  it('fails when the manifest is restated, because the header is the AAD', async () => {
+    const db = await exportOpenCredsDatabase(samplePayload(), {
+      passphrase: PASSPHRASE,
+      iterations: FAST,
+    });
+    const lying = { ...db, manifest: { ...db.manifest, itemCount: 5 } };
+    await expect(openOpenCredsDatabase(lying, { passphrase: PASSPHRASE })).rejects.toThrow(
+      /wrong passphrase, or the file was altered/
+    );
+  });
+
+  it('fails when a plaintext database loses an item', async () => {
+    const db = await exportPlaintextOpenCredsDatabase(samplePayload(), { acknowledged: true });
+    const truncated = { ...db, items: db.items.slice(0, 3) };
+    await expect(openOpenCredsDatabase(truncated)).rejects.toThrow(/Manifest does not match/);
+  });
+
+  it('refuses an unregistered namespace unless told otherwise', async () => {
+    const db = await exportPlaintextOpenCredsDatabase(samplePayload(), { acknowledged: true });
+    const foreign = { ...db, namespace: 'someone-else' };
+    await expect(openOpenCredsDatabase(foreign)).rejects.toThrow(/Unregistered namespace/);
+    await expect(
+      openOpenCredsDatabase(foreign, { allowUnregisteredNamespace: true })
+    ).resolves.toBeTruthy();
+  });
+
+  it('accepts a database written under the opencreds namespace', async () => {
+    // The interoperability case: a file from @logicsrc/opencreds.
+    const db = await exportPlaintextOpenCredsDatabase(samplePayload(), { acknowledged: true });
+    const fromLogicSrc = { ...db, namespace: 'opencreds' };
+    expect((await openOpenCredsDatabase(fromLogicSrc)).items).toHaveLength(6);
+  });
+
+  it('refuses a version it does not read', async () => {
+    const db = await exportPlaintextOpenCredsDatabase(samplePayload(), { acknowledged: true });
+    await expect(openOpenCredsDatabase({ ...db, opencreds: '9.9' })).rejects.toThrow(
+      /Unsupported OpenCreds version/
+    );
+  });
+
+  it('rejects an item whose group does not match its type', async () => {
+    const payload = samplePayload();
+    payload.items.push({ ...createItem('login', { name: 'bad' }), card: { number: '1' } });
+    const db = await exportPlaintextOpenCredsDatabase(payload, { acknowledged: true });
+    await expect(openOpenCredsDatabase(db)).rejects.toThrow(/must not carry a card field group/);
+  });
+});
+
+describe('file detection', () => {
+  it('tells an OpenCreds database from a CSV', async () => {
+    const db = await exportOpenCredsDatabase(samplePayload(), {
+      passphrase: PASSPHRASE,
+      iterations: FAST,
+    });
+    expect(detectImportKind(JSON.stringify(db))).toBe('opencreds');
+    expect(detectImportKind('name,url,username,password\nGitHub,x,y,z\n')).toBe('csv');
+    expect(detectImportKind('{"hello":"world"}')).toBe('unknown');
+    expect(detectImportKind('')).toBe('unknown');
+  });
+
+  it('survives a BOM in front of the JSON', async () => {
+    const db = await exportPlaintextOpenCredsDatabase(samplePayload(), { acknowledged: true });
+    expect(detectImportKind(`${JSON.stringify(db)}`)).toBe('opencreds');
+  });
+
+  it('previews the header without the passphrase', async () => {
+    const db = await exportOpenCredsDatabase(samplePayload(), {
+      passphrase: PASSPHRASE,
+      iterations: FAST,
+    });
+    const header = inspectOpenCredsFile(JSON.stringify(db));
+    expect(header.protected).toBe(true);
+    expect(header.itemCount).toBe(6);
+    expect(header.types.key).toBe(1);
+    expect(header.generator.name).toBe('@marksyncr/vault');
+  });
+
+  it('says what a CSV is when one reaches the database reader', () => {
+    expect(() => parseOpenCredsDatabase('name,url\nx,y')).toThrow(/not a CSV/);
+    expect(() => parseOpenCredsDatabase('{"hello":"world"}')).toThrow(/Not an OpenCreds database/);
+    expect(isOpenCredsDatabase({ type: 'opencreds.database' })).toBe(true);
+    expect(isOpenCredsDatabase(null)).toBe(false);
+  });
+});
+
+describe('importFile', () => {
+  it('imports an OpenCreds database, folders and all', async () => {
+    const payload = samplePayload();
+    const db = await exportOpenCredsDatabase(payload, { passphrase: PASSPHRASE, iterations: FAST });
+
+    const result = await importFile(JSON.stringify(db), { passphrase: PASSPHRASE });
+    expect(result.source).toBe('opencreds');
+    expect(result.items).toEqual(payload.items);
+    expect(result.folders).toEqual(payload.folders);
+    expect(result.skipped).toEqual([]);
+  });
+
+  it('still imports a CSV, and reports what it skipped', async () => {
+    const csv = 'name,url,username,password,note\nGitHub,https://github.com,a,b,\n,,,,\n';
+    const result = await importFile(csv);
+    expect(result.source).toBe('chrome');
+    expect(result.items).toHaveLength(1);
+    expect(result.folders).toEqual([]);
+    expect(result.skipped).toEqual([{ row: 3, reason: 'Empty row' }]);
+  });
+
+  it('carries password history, which no CSV has a column for', async () => {
+    const payload = samplePayload();
+    payload.items[0].history = [{ password: 'old', changedAt: '2026-01-01T00:00:00.000Z' }];
+    const db = await exportOpenCredsDatabase(payload, { passphrase: PASSPHRASE, iterations: FAST });
+
+    const result = await parseOpenCredsImport(JSON.stringify(db), { passphrase: PASSPHRASE });
+    expect(result.items[0].history).toEqual([
+      { password: 'old', changedAt: '2026-01-01T00:00:00.000Z' },
+    ]);
+  });
+
+  it('does not restamp timestamps or drop fields it does not know', async () => {
+    const payload = samplePayload();
+    payload.items[0] = {
+      ...payload.items[0],
+      createdAt: '2019-04-01T00:00:00.000Z',
+      updatedAt: '2020-07-09T00:00:00.000Z',
+      fromTheFuture: { keep: 'me' },
+    };
+
+    const db = await exportOpenCredsDatabase(payload, { passphrase: PASSPHRASE, iterations: FAST });
+    const back = await openOpenCredsDatabase(db, { passphrase: PASSPHRASE });
+
+    expect(back.items[0].createdAt).toBe('2019-04-01T00:00:00.000Z');
+    expect(back.items[0].updatedAt).toBe('2020-07-09T00:00:00.000Z');
+    expect(back.items[0].fromTheFuture).toEqual({ keep: 'me' });
+  });
+});
+
+describe('the header a reader sees', () => {
+  it('exposes only what a preview needs', async () => {
+    const db = await exportOpenCredsDatabase(samplePayload(), {
+      passphrase: PASSPHRASE,
+      iterations: FAST,
+    });
+    const header = readOpenCredsHeader(db);
+    expect(header).toMatchObject({
+      opencreds: '0.1',
+      protected: true,
+      namespace: 'marksyncr',
+      itemCount: 6,
+      folderCount: 1,
+    });
+    expect(JSON.stringify(header)).not.toContain('hunter2');
+  });
+});
diff --git a/packages/vault/package.json b/packages/vault/package.json
index bb35b6a..9366f0f 100644
--- a/packages/vault/package.json
+++ b/packages/vault/package.json
@@ -11,7 +11,8 @@
     "./keys": "./src/vault-key.js",
     "./items": "./src/items.js",
     "./generator": "./src/generator.js",
-    "./import": "./src/import.js"
+    "./import": "./src/import.js",
+    "./opencreds": "./src/opencreds.js"
   },
   "scripts": {
     "test": "vitest run",
diff --git a/packages/vault/src/import.js b/packages/vault/src/import.js
index 40ee856..2b0371e 100644
--- a/packages/vault/src/import.js
+++ b/packages/vault/src/import.js
@@ -1,17 +1,34 @@
 /**
  * Importing from other password managers.
  *
- * Every supported source exports CSV, so the work is one correct CSV reader
- * plus a column mapping per product. The reader is hand-written rather than
- * pulled from a dependency because this runs inside an extension service worker
- * and inside Next — and because the failure mode of a sloppy parser here is
+ * Two shapes arrive here, and they are not equally good.
+ *
+ * Most products export CSV, so most of the work is one correct CSV reader plus
+ * a column mapping per product. The reader is hand-written rather than pulled
+ * from a dependency because this runs inside an extension service worker and
+ * inside Next — and because the failure mode of a sloppy parser here is
  * silently importing half of somebody's passwords.
  *
- * Nothing in this file touches the network or the crypto. It turns text into
- * plain item objects; the caller encrypts them.
+ * The other shape is an OpenCreds database (https://logicsrc.com/opencreds): a
+ * whole vault as one encrypted file, with a manifest authenticated by the same
+ * tag as the data. Where a CSV truncated at 3,000 rows imports 3,000 rows and
+ * reports success, an OpenCreds file that lost an item fails its manifest and
+ * imports nothing. It also carries what no CSV has a column for — password
+ * history, TOTP seeds, folders, custom fields, URI match rules, and `key` and
+ * `account` items.
+ *
+ * Nothing in this file touches the network. The CSV path touches no crypto at
+ * all; the OpenCreds path decrypts the file it was handed and nothing else.
+ * Both produce plain item objects, and the caller encrypts them into the vault.
  */
 
 import { createItem } from './items.js';
+import {
+  isOpenCredsDatabase,
+  openOpenCredsDatabase,
+  parseOpenCredsDatabase,
+  readOpenCredsHeader,
+} from './opencreds.js';
 
 /**
  * Parse CSV into rows of cells.
@@ -307,3 +324,78 @@ export function parseImport(text, { source } = {}) {
 
   return { source: detected, items, skipped };
 }
+
+/**
+ * Which kind of file this is, without parsing it properly.
+ *
+ * Cheap enough to run on a dropped file before deciding whether to ask for a
+ * passphrase.
+ * @param {string} text
+ * @returns {'opencreds'|'csv'|'unknown'}
+ */
+export function detectImportKind(text) {
+  // A BOM written as an escape, not as the character: a literal BOM in source
+  // is invisible in every editor and reads as a corrupted file to the next
+  // person who opens it.
+  const trimmed = String(text || '')
+    .replace(/^\uFEFF/, '')
+    .trimStart();
+  if (trimmed.startsWith('{')) {
+    try {
+      return isOpenCredsDatabase(JSON.parse(trimmed)) ? 'opencreds' : 'unknown';
+    } catch {
+      return 'unknown';
+    }
+  }
+  return trimmed.length > 0 ? 'csv' : 'unknown';
+}
+
+/**
+ * Inspect an OpenCreds file before importing it.
+ *
+ * The header is readable without the passphrase, and in the encrypted form it
+ * is authenticated — so a preview can show what the file claims to hold and the
+ * claim cannot be a lie. Use this to decide whether to prompt.
+ * @param {string} text
+ */
+export function inspectOpenCredsFile(text) {
+  return readOpenCredsHeader(parseOpenCredsDatabase(text));
+}
+
+/**
+ * Import an OpenCreds database.
+ *
+ * Returns the same shape as {@link parseImport}, plus the folders the file
+ * carried and its header. Throws when the passphrase is wrong, the file was
+ * altered, or the manifest disagrees with the payload — and in every one of
+ * those cases the caller writes nothing.
+ *
+ * @param {string} text
+ * @param {{ passphrase?: string, key?: Uint8Array, allowUnregisteredNamespace?: boolean }} [options]
+ * @returns {Promise<{source: 'opencreds', items: Array, folders: Array, skipped: Array, header: Object}>}
+ */
+export async function parseOpenCredsImport(text, options = {}) {
+  const db = parseOpenCredsDatabase(text);
+  const header = readOpenCredsHeader(db);
+  const payload = await openOpenCredsDatabase(db, options);
+  return { source: 'opencreds', items: payload.items, folders: payload.folders, skipped: [], header };
+}
+
+/**
+ * Import a file of either kind.
+ *
+ * One entry point, so a caller does not have to know what it was handed. CSV
+ * imports carry no folders; OpenCreds imports report no skipped rows, because a
+ * file that would have had any fails its manifest instead.
+ *
+ * @param {string} text
+ * @param {{ passphrase?: string, source?: string, key?: Uint8Array }} [options]
+ * @returns {Promise<{source: string|null, items: Array, folders: Array, skipped: Array, header?: Object}>}
+ */
+export async function importFile(text, options = {}) {
+  if (detectImportKind(text) === 'opencreds') {
+    return parseOpenCredsImport(text, options);
+  }
+  const parsed = parseImport(text, options.source ? { source: options.source } : {});
+  return { ...parsed, folders: [] };
+}
diff --git a/packages/vault/src/index.js b/packages/vault/src/index.js
index bc8c103..80f129a 100644
--- a/packages/vault/src/index.js
+++ b/packages/vault/src/index.js
@@ -66,12 +66,28 @@ export {
   ITEM_SCHEMA_VERSION,
   MAX_HISTORY_ENTRIES,
   createItem,
+  assertGroupsMatchType,
   recordPasswordChange,
   encryptItem,
   decryptItem,
   decryptItems,
 } from './items.js';
 
+export {
+  OPENCREDS_VERSION,
+  OPENCREDS_EXTENSION,
+  OPENCREDS_MEDIA_TYPE,
+  NAMESPACE as OPENCREDS_NAMESPACE,
+  buildManifest,
+  verifyManifest,
+  isOpenCredsDatabase,
+  readOpenCredsHeader,
+  parseOpenCredsDatabase,
+  openOpenCredsDatabase,
+  exportOpenCredsDatabase,
+  exportPlaintextOpenCredsDatabase,
+} from './opencreds.js';
+
 export {
   LOWERCASE,
   UPPERCASE,
@@ -91,4 +107,8 @@ export {
   rowsToObjects,
   detectSource,
   parseImport,
+  detectImportKind,
+  inspectOpenCredsFile,
+  parseOpenCredsImport,
+  importFile,
 } from './import.js';
diff --git a/packages/vault/src/items.js b/packages/vault/src/items.js
index 500f7cd..23b8004 100644
--- a/packages/vault/src/items.js
+++ b/packages/vault/src/items.js
@@ -22,12 +22,18 @@ import {
  * paginate without decrypting. This is deliberate, and it is the metadata the
  * design accepts leaking: the server learns you hold 40 logins and 2 cards,
  * never which sites or what values.
+ *
+ * These are the OpenCreds type codes (https://logicsrc.com/opencreds). Codes
+ * 1-4 predate that specification and are what fixed them there — renumbering
+ * would break every vault already written. Codes 5 and 6 come from it.
  */
 export const ITEM_TYPE = Object.freeze({
   login: 1,
   card: 2,
   identity: 3,
   note: 4,
+  key: 5,
+  account: 6,
 });
 
 /** Reverse lookup, for turning a stored row back into a name. */
@@ -57,19 +63,87 @@ const EMPTY_FIELDS = Object.freeze({
     firstName: '',
     middleName: '',
     lastName: '',
+    username: '',
     company: '',
     email: '',
     phone: '',
     address1: '',
     address2: '',
+    address3: '',
     city: '',
     state: '',
     postalCode: '',
     country: '',
+    ssn: '',
+    passportNumber: '',
+    licenseNumber: '',
   }),
   note: () => ({}),
+  /**
+   * SSH and PGP keys, API tokens, certificates, and .env secrets.
+   *
+   * `path` and `mode` are carried so a restore is total: a private key written
+   * back with the wrong mode is a key ssh refuses to use, and one written to
+   * the wrong path is a key nothing finds.
+   */
+  key: () => ({
+    keyType: '',
+    algorithm: '',
+    publicKey: '',
+    privateKey: '',
+    passphrase: '',
+    fingerprint: '',
+    value: '',
+    path: '',
+    mode: '',
+    expiresAt: '',
+  }),
+  /**
+   * A provider account and the tokens that authorize acting as it.
+   *
+   * Deliberately not a login: a login is what a person types at a sign-in form,
+   * an account is what a machine presents to an API. They expire differently
+   * and are revoked differently, and conflating them is how a rotated refresh
+   * token ends up in a password history array.
+   */
+  account: () => ({
+    provider: '',
+    accountId: '',
+    handle: '',
+    email: '',
+    accessToken: '',
+    refreshToken: '',
+    tokenType: '',
+    scopes: [],
+    expiresAt: '',
+    environment: '',
+  }),
 });
 
+/** The per-type group names, so the wrong-group check cannot fall out of step. */
+const GROUP_NAMES = Object.freeze(Object.keys(EMPTY_FIELDS));
+
+/** "an account", "a login" — these strings are read by people. */
+function article(word) {
+  return /^[aeiou]/i.test(word) ? 'an' : 'a';
+}
+
+/**
+ * Reject an item carrying a field group that is not its own type's.
+ *
+ * A card group on a login is either a broken importer or an attempt to smuggle
+ * a field past a type-based check; neither should reach the ciphertext.
+ * @param {Object} item
+ */
+export function assertGroupsMatchType(item) {
+  for (const name of GROUP_NAMES) {
+    if (name === 'note') continue;
+    if (name !== item.type && item[name] !== undefined) {
+      throw new Error(`A ${item.type} item must not carry ${article(name)} ${name} field group`);
+    }
+  }
+}
+
 /**
  * Create a new item.
  *
@@ -163,6 +237,7 @@ function itemAad(id, version) {
 export async function encryptItem(userKey, item) {
   if (!item?.id) throw new Error('An item must have an id before it can be encrypted');
   if (!(item.type in ITEM_TYPE)) throw new Error(`Unknown item type: ${item.type}`);
+  assertGroupsMatchType(item);
 
   const version = item.v ?? ITEM_SCHEMA_VERSION;
   const plaintext = utf8Encode(JSON.stringify({ ...item, v: version }));
diff --git a/packages/vault/src/opencreds.js b/packages/vault/src/opencreds.js
new file mode 100644
index 0000000..2fa6eeb
--- /dev/null
+++ b/packages/vault/src/opencreds.js
@@ -0,0 +1,378 @@
+/**
+ * OpenCreds — the portable vault database.
+ *
+ * https://logicsrc.com/opencreds
+ *
+ * A whole vault as one file, so moving between products is a supported
+ * operation rather than a plaintext CSV export. Encrypted by default, under a
+ * key derived from an *export passphrase* rather than the vault's own user key
+ * — a file encrypted under the user key would only open inside the vault it
+ * came from, which is the opposite of portable.
+ *
+ * The header is bound as additional authenticated data over the payload, so the
+ * manifest is authenticated by the same tag as the data. That is the difference
+ * between an import you can trust and a CSV: a CSV truncated at 3,000 rows
+ * imports 3,000 rows and reports success.
+ *
+ * Nothing here touches the network, and nothing here touches a vault's own key
+ * material. It turns a file into plain item objects and back; the caller
+ * encrypts them under the vault they belong to.
+ */
+
+import {
+  aesGcmDecrypt,
+  aesGcmEncrypt,
+  fromBase64,
+  KEY_BYTES,
+  randomBytes,
+  toBase64,
+  utf8Decode,
+  utf8Encode,
+} from './primitives.js';
+import { hkdf, pbkdf2 } from './primitives.js';
+import { assertGroupsMatchType, ITEM_TYPE } from './items.js';
+
+/** The specification version this module reads and writes. */
+export const OPENCREDS_VERSION = '0.1';
+
+/** Conventional extension and media type. */
+export const OPENCREDS_EXTENSION = '.opencreds';
+export const OPENCREDS_MEDIA_TYPE = 'application/vnd.logicsrc.opencreds+json';
+
+/**
+ * This vault's declared namespace.
+ *
+ * MarkSyncr's vault shipped before OpenCreds, with `marksyncr:vault:*` labels
+ * already compiled into the additional authenticated data of every ciphertext
+ * it has written. A label cannot be edited — changing one does not migrate a
+ * vault, it makes it undecryptable — so the specification carries the prefix as
+ * a declared per-vault property, and `marksyncr` is registered.
+ */
+export const NAMESPACE = 'marksyncr';
+
+/** Namespaces registered by the specification. */
+const REGISTERED_NAMESPACES = Object.freeze(['opencreds', 'marksyncr']);
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
+
+/** OWASP's current floor for PBKDF2-HMAC-SHA256, and the lowest we will accept. */
+const DEFAULT_ITERATIONS = 600_000;
+const MIN_ITERATIONS = 100_000;
+const SALT_BYTES = 16;
+
+const GENERATOR = Object.freeze({ name: '@marksyncr/vault', version: '0.1.0' });
+
+const TYPE_NAMES = Object.freeze(Object.keys(ITEM_TYPE));
+
+/**
+ * Derive the key a database is encrypted under.
+ *
+ * PBKDF2 to stretch the passphrase, then HKDF under the database label, so an
+ * export key and a vault's wrapping key are computationally independent even
+ * when a person reuses the passphrase.
+ * @param {string} passphrase
+ * @param {Uint8Array} salt
+ * @param {number} iterations
+ * @param {string} namespace
+ * @returns {Promise<Uint8Array>}
+ */
+async function deriveExportKey(passphrase, salt, iterations, namespace) {
+  if (typeof passphrase !== 'string' || passphrase.length === 0) {
+    throw new Error('An export passphrase is required');
+  }
+  if (!Number.isInteger(iterations) || iterations < MIN_ITERATIONS) {
+    throw new Error(
+      `Refusing to derive a key with ${iterations} iterations — the minimum is ${MIN_ITERATIONS}`
+    );
+  }
+  const master = await pbkdf2(passphrase, salt, iterations, KEY_BYTES);
+  return hkdf(master, `${namespace}:database:v1`, KEY_BYTES);
+}
+
+/**
+ * The bytes bound as additional authenticated data.
+ *
+ * The key order is fixed by the specification: JSON.stringify preserves
+ * insertion order, so a header rebuilt in another order produces different AAD
+ * and fails to decrypt on a conforming reader.
+ * @param {Object} header
+ * @returns {Uint8Array}
+ */
+function headerAad(header) {
+  const ordered = {
+    opencreds: header.opencreds,
+    type: header.type,
+    protected: header.protected,
+    namespace: header.namespace,
+    exportedAt: header.exportedAt,
+    generator: header.generator,
+    kdf: header.kdf,
+    manifest: header.manifest,
+  };
+  for (const key of Object.keys(ordered)) {
+    if (ordered[key] === undefined) delete ordered[key];
+  }
+  return utf8Encode(JSON.stringify(ordered));
+}
+
+async function sha256(bytes) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return new Uint8Array(digest);
+}
+
+/**
+ * Build the manifest for a payload.
+ *
+ * The digest is over sorted item ids, so a re-ordered payload is detectable —
+ * an importer that silently accepted a reordering would also silently accept a
+ * substitution.
+ * @param {{ folders: Array, items: Array }} payload
+ * @returns {Promise<{itemCount: number, types: Object, folderCount: number, digest: string}>}
+ */
+export async function buildManifest(payload) {
+  const types = {};
+  for (const item of payload.items) {
+    if (!(item.type in ITEM_TYPE)) continue;
+    types[item.type] = (types[item.type] ?? 0) + 1;
+  }
+  const ids = payload.items.map((item) => item.id).sort();
+  return {
+    itemCount: payload.items.length,
+    types,
+    folderCount: payload.folders.length,
+    digest: toBase64(await sha256(utf8Encode(ids.join('\n')))),
+  };
+}
+
+/**
+ * Compare a claimed manifest against what a payload actually holds.
+ *
+ * Returns every disagreement rather than the first, because a person looking at
+ * a failed import wants to know whether one item went missing or the file is
+ * from a different vault entirely.
+ * @returns {Promise<string[]>}
+ */
+export async function verifyManifest(claimed, payload) {
+  const actual = await buildManifest(payload);
+  const problems = [];
+  if (claimed?.itemCount !== actual.itemCount) {
+    problems.push(`manifest says ${claimed?.itemCount} items, payload has ${actual.itemCount}`);
+  }
+  if (claimed?.folderCount !== actual.folderCount) {
+    problems.push(`manifest says ${claimed?.folderCount} folders, payload has ${actual.folderCount}`);
+  }
+  if (claimed?.digest !== actual.digest) {
+    problems.push('manifest digest does not match the payload’s item ids');
+  }
+  for (const type of TYPE_NAMES) {
+    const want = claimed?.types?.[type] ?? 0;
+    const have = actual.types[type] ?? 0;
+    if (want !== have) problems.push(`manifest says ${want} ${type} items, payload has ${have}`);
+  }
+  return problems;
+}
+
+/** True when a parsed document is an OpenCreds database. */
+export function isOpenCredsDatabase(value) {
+  return Boolean(value) && typeof value === 'object' && value.type === 'opencreds.database';
+}
+
+/**
+ * Read a database's header without opening it.
+ *
+ * Enough for a preview — version, namespace, export time, generator and the
+ * counts — and, in the encrypted form, authenticated, so none of it can be lied
+ * about. Everything else needs the passphrase, which is the point.
+ * @param {Object} db
+ */
+export function readOpenCredsHeader(db) {
+  if (!isOpenCredsDatabase(db)) throw new Error('Not an OpenCreds database');
+  return {
+    opencreds: db.opencreds,
+    protected: db.protected !== false,
+    namespace: db.namespace,
+    exportedAt: db.exportedAt,
+    generator: db.generator,
+    manifest: db.manifest,
+    itemCount: db.manifest?.itemCount ?? 0,
+    types: db.manifest?.types ?? {},
+    folderCount: db.manifest?.folderCount ?? 0,
+  };
+}
+
+/**
+ * Parse a file's text as an OpenCreds database.
+ * @param {string} text
+ */
+export function parseOpenCredsDatabase(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error('Not valid JSON — an OpenCreds database is a JSON document, not a CSV');
+  }
+  if (!isOpenCredsDatabase(parsed)) throw new Error('Not an OpenCreds database');
+  return parsed;
+}
+
+function assertReadable(db, allowUnregisteredNamespace) {
+  if (db.opencreds !== OPENCREDS_VERSION) {
+    throw new Error(
+      `Unsupported OpenCreds version ${JSON.stringify(db.opencreds)} — this build reads ${OPENCREDS_VERSION}`
+    );
+  }
+  if (typeof db.namespace !== 'string' || !NAMESPACE_PATTERN.test(db.namespace)) {
+    throw new Error(`Invalid namespace: ${JSON.stringify(db.namespace)}`);
+  }
+  // Accepting an arbitrary prefix is accepting an arbitrary derivation.
+  if (!allowUnregisteredNamespace && !REGISTERED_NAMESPACES.includes(db.namespace)) {
+    throw new Error(
+      `Unregistered namespace "${db.namespace}" — registered namespaces are ${REGISTERED_NAMESPACES.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Open an OpenCreds database and verify its manifest.
+ *
+ * Throws on a mismatch, and the caller writes nothing — there is no state in
+ * which a conforming implementation reports a complete import of an incomplete
+ * file.
+ *
+ * @param {Object} db a parsed database
+ * @param {{ passphrase?: string, key?: Uint8Array, allowUnregisteredNamespace?: boolean }} [options]
+ * @returns {Promise<{ folders: Array, items: Array }>}
+ */
+export async function openOpenCredsDatabase(db, options = {}) {
+  if (!isOpenCredsDatabase(db)) throw new Error('Not an OpenCreds database');
+  assertReadable(db, options.allowUnregisteredNamespace);
+
+  let payload;
+
+  if (db.protected === false) {
+    payload = { folders: db.folders ?? [], items: db.items ?? [] };
+  } else {
+    let exportKey;
+    if (options.key) {
+      exportKey = options.key;
+    } else if (typeof options.passphrase === 'string') {
+      if (!db.kdf) throw new Error('This database was encrypted with a raw key, not a passphrase');
+      exportKey = await deriveExportKey(
+        options.passphrase,
+        fromBase64(db.kdf.salt),
+        db.kdf.iterations,
+        db.namespace
+      );
+    } else {
+      throw new Error('This database is encrypted; a passphrase is required');
+    }
+
+    let plaintext;
+    try {
+      plaintext = await aesGcmDecrypt(
+        exportKey,
+        fromBase64(db.iv),
+        fromBase64(db.ciphertext),
+        headerAad(db)
+      );
+    } catch {
+      // One message for a wrong passphrase and for a tampered header, because
+      // the reader cannot tell them apart and guessing would be worse.
+      throw new Error('Could not decrypt the database — wrong passphrase, or the file was altered');
+    }
+    payload = JSON.parse(utf8Decode(plaintext));
+  }
+
+  payload.folders ??= [];
+  payload.items ??= [];
+
+  const problems = await verifyManifest(db.manifest, payload);
+  if (problems.length > 0) {
+    throw new Error(`Manifest does not match the payload: ${problems.join('; ')}`);
+  }
+
+  for (const item of payload.items) {
+    if (!(item.type in ITEM_TYPE)) {
+      throw new Error(`Unknown item type in database: ${String(item.type)}`);
+    }
+    assertGroupsMatchType(item);
+  }
+
+  return payload;
+}
+
+/**
+ * Export a payload as an encrypted OpenCreds database.
+ *
+ * @param {{ folders: Array, items: Array }} payload
+ * @param {{ passphrase?: string, key?: Uint8Array, iterations?: number, exportedAt?: string }} options
+ */
+export async function exportOpenCredsDatabase(payload, options = {}) {
+  if (!options.passphrase && !options.key) {
+    throw new Error('An export needs a passphrase or a raw key');
+  }
+  if (options.passphrase && options.key) {
+    throw new Error('Pass a passphrase or a raw key, not both');
+  }
+
+  const iterations = options.iterations ?? DEFAULT_ITERATIONS;
+  let exportKey;
+  let kdf;
+
+  if (options.passphrase) {
+    const salt = randomBytes(SALT_BYTES);
+    exportKey = await deriveExportKey(options.passphrase, salt, iterations, NAMESPACE);
+    kdf = { kdf: 'pbkdf2-sha256', iterations, salt: toBase64(salt) };
+  } else {
+    exportKey = options.key;
+    if (exportKey.length !== KEY_BYTES) throw new Error('A raw export key must be 32 bytes');
+  }
+
+  const header = {
+    opencreds: OPENCREDS_VERSION,
+    type: 'opencreds.database',
+    protected: true,
+    namespace: NAMESPACE,
+    exportedAt: options.exportedAt ?? new Date().toISOString(),
+    generator: { ...GENERATOR },
+    ...(kdf ? { kdf } : {}),
+    manifest: await buildManifest(payload),
+  };
+
+  const { iv, ciphertext } = await aesGcmEncrypt(
+    exportKey,
+    utf8Encode(JSON.stringify({ folders: payload.folders, items: payload.items })),
+    headerAad(header)
+  );
+
+  return { ...header, iv: toBase64(iv), ciphertext: toBase64(ciphertext) };
+}
+
+/**
+ * Export a payload in the plaintext form.
+ *
+ * Every secret in the vault, in a file, in the clear. It exists because the
+ * products people move *to* frequently read nothing else, and an export format
+ * that cannot express that gets worked around with a script that is worse — no
+ * warning, no file mode, no label.
+ *
+ * `acknowledged` is not decoration: a caller must state, in code, that it meant
+ * this. The UI turns that into a confirmation.
+ */
+export async function exportPlaintextOpenCredsDatabase(payload, options = {}) {
+  if (!options.acknowledged) {
+    throw new Error(
+      'A plaintext export writes every secret in the vault out unencrypted; pass acknowledged: true to proceed'
+    );
+  }
+  return {
+    opencreds: OPENCREDS_VERSION,
+    type: 'opencreds.database',
+    protected: false,
+    namespace: NAMESPACE,
+    exportedAt: options.exportedAt ?? new Date().toISOString(),
+    generator: { ...GENERATOR },
+    manifest: await buildManifest(payload),
+    folders: payload.folders,
+    items: payload.items,
+  };
+}
diff --git a/supabase/migrations/20260829180000_vault_opencreds_types.sql b/supabase/migrations/20260829180000_vault_opencreds_types.sql
new file mode 100644
index 0000000..c56e68d
--- /dev/null
+++ b/supabase/migrations/20260829180000_vault_opencreds_types.sql
@@ -0,0 +1,28 @@
+-- OpenCreds item types — widen vault_items to the full six
+--
+-- The vault shipped with four types: 1 login, 2 card, 3 identity, 4 note. The
+-- OpenCreds specification (https://logicsrc.com/opencreds) adds two more, and
+-- fixes 1-4 at the values already deployed here, because renumbering them would
+-- break every ciphertext already written:
+--
+--   5 key      SSH and PGP keys, API tokens, certificates, .env secrets
+--   6 account  a provider account and the OAuth tokens that act as it
+--
+-- A key is not a note with a long body, and an account is not a login. A login
+-- is what a person types at a sign-in form; an account is what a machine
+-- presents to an API. They expire differently and are revoked differently, and
+-- conflating them is how a rotated refresh token ends up in a password history
+-- array.
+--
+-- Nothing about the row shape changes: type stays plaintext so the server can
+-- filter and paginate without decrypting, and everything else stays inside the
+-- one ciphertext.
+
+ALTER TABLE public.vault_items
+    DROP CONSTRAINT IF EXISTS vault_items_type_known;
+
+ALTER TABLE public.vault_items
+    ADD CONSTRAINT vault_items_type_known CHECK (type BETWEEN 1 AND 6);
+
+COMMENT ON COLUMN public.vault_items.type IS
+    'OpenCreds item type code: 1 login, 2 card, 3 identity, 4 note, 5 key, 6 account. Plaintext on purpose — see the migration header for the metadata this deliberately leaks.';