@johnhenry/keyvault 0.0.0-stage → 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `@johnhenry/keyvault`. Format follows [Keep a Changelog](https://keepachangelog.com/); versions follow semver (0.x: minor bumps may break).
+
+## [0.1.0] - Unreleased
+
+First release. Consolidates the password-based crypto that p2pws (`backup.mjs`, `login.mjs`) and
+`@johnhenry/browsermesh-core` (`VaultIdentityStorage`) each carried a copy of.
+
+### Added
+- `seal()` / `open()` / `openText()` / `openJson()`: PBKDF2-SHA256 (600,000 by default) to AES-256-GCM. The whole header, including the KDF parameters, is AES-GCM additional data. Byte-compatible with p2pws's `v: 1` backup files in both directions.
+- `open()` also reads browsermesh `VaultIdentityStorage` envelopes (and whole stored records), exactly as that class reads them (no Unicode normalisation, no header binding).
+- `needsUpgrade()`: true when a record's KDF is weaker than `defaultKdf()` (or a target you pass), or it is a header-less browsermesh vault envelope.
+- `deriveKey()` with an explicit domain-separation `purpose`; `deriveLoginKeys()` / `deriveVaultKey()` reproduce p2pws's `salt || "\np2pws-login/" + purpose` derivation exactly (`P2PWS_LOGIN_KDF` = its 310,000 iterations).
+- `VaultError` with stable codes `bad_passphrase`, `corrupt`, `unsupported`, `wrong_type`, `weak_secret`.
+- Caps on hostile input: PBKDF2 iterations 1,000 to 10,000,000, Argon2id memory/passes/lanes, unknown KDF names, oversized records and payloads, empty / undefined / non-string secrets.
+- `prfFromPasskey()`: a secret from a passkey via the WebAuthn PRF extension.
+- Optional `@johnhenry/keyvault/argon2`: Argon2id through `hash-wasm` (optional peer dependency) or your own implementation.
+- Zero runtime dependencies; ESM; browsers, Node >= 20, Deno. TypeScript declarations.
+- Tests in Node, Deno and headless Chromium (Playwright), with fixtures written by the current p2pws and browsermesh-core code.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 John Henry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @johnhenry/keyvault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turn a human secret (a password, a passphrase, a passkey) into keys, and seal small secrets such as private keys with them.
+
+- **Zero runtime dependencies.** WebCrypto only. ESM. Browsers, Node >= 20 and Deno.
+- **Self-describing.** The KDF name and parameters are written into every record and authenticated, so you can raise them later without orphaning old records (`needsUpgrade()`).
+- **Safe on hostile input.** Iteration, memory and size caps, unknown KDFs rejected, empty / `undefined` / non-string secrets refused.
+- **Compatible.** Reads (and writes) the sealed files p2pws's `backup.mjs` produces, and reads the records browsermesh's `VaultIdentityStorage` stores.
+
+```sh
+npm install @johnhenry/keyvault
+```
+
+## Quick start
+
+```js
+import { seal, open, needsUpgrade, VaultError } from '@johnhenry/keyvault';
+
+// Seal a private key (bytes or a string). The header is readable, and tamper-proof.
+const text = await seal(pkcs8Bytes, 'correct horse battery staple', {
+  type: 'my-key-backup',
+  header: { kid: 'abc', label: 'laptop', createdAt: Date.now() },
+});
+// `text` is JSON: store it anywhere.
+
+try {
+  const { header, payload } = await open(text, passphrase, { type: 'my-key-backup' });
+  // payload is a Uint8Array; header.kid etc. are authenticated.
+  if (needsUpgrade(text)) await save(await seal(payload, passphrase, { type: 'my-key-backup', header }));
+} catch (e) {
+  if (e instanceof VaultError && e.code === 'bad_passphrase') { /* ask again */ }
+  else throw e;
+}
+```
+
+## API
+
+### Sealing
+
+| Function | |
+|---|---|
+| `seal(payload, secret, { type, header?, kdf?, minLength? })` | `payload`: `Uint8Array` or string (at most 1 MiB). `type` is required. `header`: extra readable fields (strings, safe integers, booleans, `null`, arrays, plain objects; not `v`, `t`, `kdf`, `iv`, `ct`). `kdf` defaults to `defaultKdf()`. `minLength` is your password policy (default 1). Returns JSON text. |
+| `open(text, secret, { type?, limits? })` | Resolves `{ header, type, kdf, payload: Uint8Array, legacy }`. Pass `type`: a record of another type is refused with `wrong_type` before any key derivation. `text` may also be an already-parsed object. |
+| `openText(...)` / `openJson(...)` | The same, decoding `payload` as UTF-8 / JSON (`corrupt` if it is not). |
+| `needsUpgrade(text, target = defaultKdf())` | `true` when the record's KDF is weaker than `target` (fewer PBKDF2 iterations; PBKDF2 vs Argon2id; less Argon2 memory or fewer passes), or it is a header-less browsermesh vault envelope. Does not decrypt. Throws `VaultError` for something that is not a valid record. |
+| `defaultKdf()` | `{ name: 'PBKDF2-SHA256', iterations: 600000 }` today (OWASP's figure). A fresh object each call. |
+
+`open()` returns `header` only after authenticating it, so its fields can be trusted, but it is still *your* data: check it the way you would any input (for example that a key id matches the key you decrypted).
+
+### Deriving keys
+
+```js
+import { deriveKey, deriveLoginKeys, p2pwsLoginPurpose, P2PWS_LOGIN_KDF, defaultKdf } from '@johnhenry/keyvault';
+
+// One password, two unrelated keys: authKey goes to a server (which should store only a verifier of it),
+// vaultKey never leaves the device and is the `secret` for seal()/open().
+const { authKey, vaultKey } = await deriveLoginKeys(password, salt, defaultKdf());
+
+// The general primitive. `purpose` is required; keys for different purposes are unrelated.
+const bytes = await deriveKey(secret, salt, defaultKdf(), 'my-app/session-key'); // Uint8Array(32)
+```
+
+`deriveKey(secret, salt, params, purpose, { bits = 256, normalize = false, limits })` runs the KDF over the salt bytes followed by the UTF-8 of `purpose`: `salt || purpose`. `salt` is bytes or a base64url string.
+
+**p2pws compatibility.** p2pws derives its sign-in keys with salt `salt || "\np2pws-login/" + purpose`, PBKDF2-SHA256 at 310,000 iterations, no Unicode normalisation, and base64url output. `deriveLoginKeys(password, salt, P2PWS_LOGIN_KDF)` and `deriveVaultKey(...)` reproduce those keys exactly (checked against fixtures written by p2pws's own `login.mjs`), so existing logins keep working; `deriveKey(..., p2pwsLoginPurpose('auth'))` is the same thing spelled out. Move to `defaultKdf()` on the next successful sign-in.
+
+### Normalisation
+
+`seal`/`open` NFKC-normalise the secret, as p2pws's backups do (so a fullwidth `ｐａｓｓ` and `pass` are the same passphrase). `deriveKey` does **not** unless you pass `normalize: 'NFKC'`, because p2pws's login derivation does not. browsermesh vault records are read without normalisation, exactly as `VaultIdentityStorage` wrote them.
+
+### Errors
+
+Every expected failure is a `VaultError` with a stable `code`:
+
+| code | meaning |
+|---|---|
+| `bad_passphrase` | Wrong secret, **or the record was modified**. AES-GCM cannot tell the two apart. |
+| `corrupt` | Not JSON, truncated, wrong shape, bad base64url, ciphertext shorter than its tag, a KDF parameter of the wrong type. |
+| `unsupported` | A valid shape that is refused: unknown record version, unknown KDF name, parameters outside the caps (iterations 1,000 to 10,000,000 for PBKDF2), Argon2id not enabled, payload over 1 MiB. |
+| `wrong_type` | The record's `type` is not the `type` you asked for. |
+| `weak_secret` | The secret is empty, `undefined`, `null`, not a string, or shorter than `minLength`. |
+
+Mistakes in your own call (a missing `type`, a reserved or non-integer header field, an empty `purpose`) throw `TypeError` instead.
+
+Caps can be tightened per call with `limits: { minIterations, maxIterations, maxArgon2Passes, maxMemoryKiB, maxParallelism }`.
+
+### Argon2id (optional)
+
+WebCrypto has no Argon2, so it lives behind a separate entry point and the core never loads it.
+
+```js
+import { enableArgon2id, argon2idKdf } from '@johnhenry/keyvault/argon2';
+await enableArgon2id();                       // uses the optional peer dependency `hash-wasm`
+const text = await seal(bytes, secret, { type: 'my-key-backup', kdf: argon2idKdf() }); // 19 MiB, 2 passes, 1 lane
+```
+
+`npm install hash-wasm` (a bare `import('hash-wasm')` needs a bundler or an import map in browsers), or pass your own implementation: `enableArgon2id({ hash: ({ password, salt, iterations, memoryKiB, parallelism, hashLength }) => Uint8Array })`. Until it is enabled, Argon2id records are refused with `unsupported` and a message naming this entry point. Whether Argon2id becomes `defaultKdf()` is a decision for the consuming apps; today it is opt-in.
+
+### Passkeys
+
+```js
+import { prfFromPasskey, seal, open } from '@johnhenry/keyvault';
+const secret = await prfFromPasskey({ credentialId, salt: appSalt, rpId: 'example.com' }); // base64url, 32 bytes
+const text = await seal(bytes, secret, { type: 'my-key-backup' });
+```
+
+Uses the WebAuthn `prf` extension: the secret exists only when the authenticator is used, so nothing a server stores can be guessed offline. Needs a secure context and an authenticator that supports PRF (otherwise `unsupported`). Create the credential yourself with `extensions: { prf: {} }`. Because the secret is high entropy, you may pass `kdf: { name: 'PBKDF2-SHA256', iterations: 1000 }` to skip the stretching.
+
+## File format
+
+Plain JSON, version 1:
+
+```json
+{ "v": 1, "t": "my-key-backup",
+  "kdf": { "name": "PBKDF2-SHA256", "iterations": 600000, "salt": "<base64url, 16 bytes>" },
+  "kid": "...", "label": "laptop", "createdAt": 1760000000000,
+  "iv": "<base64url, 12 bytes>", "ct": "<base64url AES-256-GCM ciphertext + tag>" }
+```
+
+The key is PBKDF2-HMAC-SHA256 of the NFKC-normalised secret, 256 bits. The AES-GCM additional data is the UTF-8 of the **canonical JSON** (keys sorted, safe integers only) of every field except `ct`. That is the construction p2pws's `backup.mjs` uses, so its files are valid records, and records written here with the same header fields (`kid`, `account`, `label`, `createdAt`) open with p2pws's `openBackup` / `openIdentityBundle`.
+
+p2pws-specific rules (key ids, `acct_` ids, the 1 MiB bundle limit) are not enforced here; validate them in the application after `open()`.
+
+Accepted from browsermesh: the `{ kdf?, iterations?, salt, iv, ciphertext }` envelope of `VaultIdentityStorage` (type `'browsermesh-vault'`, `legacy: true`), or the stored record that contains it as `encryptedPrivateKey`. `kdf` and `iterations` may be missing in old records (PBKDF2, 310,000). Those envelopes bind no header, so `needsUpgrade()` is always `true` for them.
+
+## Security notes
+
+- A sealed record is only as strong as its secret. The KDF slows guessing down; it does not stop it. Prefer passkeys or long passphrases, and Argon2id where WASM is acceptable.
+- `bad_passphrase` also means "tampered". Do not tell users which.
+- Nothing is zeroed in JavaScript memory beyond the raw derived key bytes; do not treat this as a hardware boundary.
+- Payloads are capped at 1 MiB: this is for keys, not files.
+
+## Tests
+
+```sh
+npm test                 # Node: unit cases, node:crypto cross-checks, Argon2id
+npm run test:deno        # the same cases under Deno
+npx playwright install chromium && npm run test:browser   # the same cases in headless Chromium, plus Argon2id and a real WebAuthn PRF round trip via a virtual authenticator
+npm run typecheck
+```
+
+The cases include the RFC 6070 (PBKDF2-HMAC-SHA1, as a WebCrypto platform check) and RFC 7914 section 11 (PBKDF2-HMAC-SHA-256) vectors, round trips, tampering with every authenticated field, truncation, and hostile iteration counts, KDF names and secrets.
+
+`test/fixtures/` holds files written by the *current* p2pws (`createBackup`, `sealIdentityBundle` for `p2pws-account-recovery` and `p2pws-identity-bundle`, `deriveLoginKeys`) and browsermesh-core `VaultIdentityStorage` code, at 1,000 and the real default 600,000 / 310,000 iterations. `test/fixtures/manifest.json` records which commit/version wrote them. To regenerate: `P2PWS_DIR=/path/to/p2pws npm run fixtures`.
+
+## Releasing
+
+Main is the release branch: a push to `main` whose `package.json` version is not on npm publishes it (trusted publishing, with provenance) and tags `v<version>`. Do not rename `.github/workflows/publish.yml`; the npm trusted-publisher entry is bound to that filename.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@johnhenry/keyvault",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Zero-dependency WebCrypto key vault: turn a human secret into keys and seal small secrets with them (browser, Node, Deno)",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./argon2": {
+      "types": "./types/argon2.d.ts",
+      "default": "./src/argon2.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "types/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test test/node/*.test.mjs",
+    "test:browser": "node test/browser/run.mjs",
+    "test:deno": "deno test --no-check --allow-read test/node/core.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "fixtures": "node scripts/gen-fixtures.mjs",
+    "prepublishOnly": "npm test && npm run typecheck"
+  },
+  "keywords": [
+    "webcrypto",
+    "pbkdf2",
+    "argon2id",
+    "aes-gcm",
+    "passphrase",
+    "key-derivation",
+    "vault",
+    "passkey",
+    "webauthn-prf"
+  ],
+  "author": "John Henry <john@iamjohnhenry.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/keyvault.git"
+  },
+  "homepage": "https://github.com/johnhenry/keyvault#readme",
+  "bugs": "https://github.com/johnhenry/keyvault/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "hash-wasm": "^4.11.0"
+  },
+  "peerDependenciesMeta": {
+    "hash-wasm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "hash-wasm": "^4.11.0",
+    "playwright": "^1.50.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/argon2.mjs

@@ -0,0 +1,50 @@
+// Optional Argon2id. WebCrypto has no Argon2, so this entry point drives a WASM implementation. The core never imports it.
+//
+//   import { enableArgon2id, argon2idKdf } from '@johnhenry/keyvault/argon2';
+//   await enableArgon2id();                       // loads the optional peer dependency `hash-wasm`
+//   const text = await seal(bytes, secret, { type, kdf: argon2idKdf() });
+//
+// Once enabled, open() reads Argon2id files and needsUpgrade() ranks Argon2id above PBKDF2.
+import { fail } from './errors.mjs';
+import { ARGON2ID, registerKdf, DEFAULT_LIMITS } from './kdf.mjs';
+
+const int = (v) => typeof v === 'number' && Number.isSafeInteger(v);
+
+/** OWASP's minimum Argon2id profile (19 MiB, 2 passes, 1 lane). A fresh object each call. */
+export function argon2idKdf(overrides = {}) {
+  return { name: ARGON2ID, iterations: 2, memoryKiB: 19_456, parallelism: 1, ...overrides };
+}
+
+/**
+ * Register Argon2id.
+ * @param {object} [options]
+ * @param {(a: {password: Uint8Array, salt: Uint8Array, iterations: number, memoryKiB: number, parallelism: number, hashLength: number}) => Promise<Uint8Array>|Uint8Array} [options.hash]
+ *   your own implementation (e.g. one backed by a bundled WASM build). Default: `hash-wasm`'s argon2id, imported on demand.
+ */
+export async function enableArgon2id({ hash } = {}) {
+  let impl = hash;
+  if (!impl) {
+    let mod;
+    try { mod = await import('hash-wasm'); } catch { fail('unsupported', "Argon2id needs the optional dependency 'hash-wasm' (npm install hash-wasm), or pass enableArgon2id({ hash })"); }
+    impl = ({ password, salt, iterations, memoryKiB, parallelism, hashLength }) =>
+      mod.argon2id({ password, salt, iterations, memorySize: memoryKiB, parallelism, hashLength, outputType: 'binary' });
+  }
+  registerKdf({
+    name: ARGON2ID,
+    rank: 2,
+    validate(p, lim) {
+      for (const k of ['iterations', 'memoryKiB', 'parallelism']) if (!int(p[k])) fail('corrupt', `kdf.${k} must be an integer`);
+      const L = { ...DEFAULT_LIMITS, ...lim };
+      if (p.iterations < 1 || p.iterations > L.maxArgon2Passes) fail('unsupported', `kdf.iterations ${p.iterations} is outside 1..${L.maxArgon2Passes}`);
+      if (p.parallelism < 1 || p.parallelism > L.maxParallelism) fail('unsupported', `kdf.parallelism ${p.parallelism} is outside 1..${L.maxParallelism}`);
+      if (p.memoryKiB < 8 * p.parallelism || p.memoryKiB > L.maxMemoryKiB) fail('unsupported', `kdf.memoryKiB ${p.memoryKiB} is outside ${8 * p.parallelism}..${L.maxMemoryKiB}`);
+      return { name: ARGON2ID, iterations: p.iterations, memoryKiB: p.memoryKiB, parallelism: p.parallelism };
+    },
+    async derive(secret, salt, p, bits) {
+      const out = await impl({ password: secret, salt, iterations: p.iterations, memoryKiB: p.memoryKiB, parallelism: p.parallelism, hashLength: bits / 8 });
+      if (!(out instanceof Uint8Array) || out.length !== bits / 8) fail('corrupt', 'Argon2id implementation returned the wrong output');
+      return out;
+    },
+    weaker: (p, t) => p.memoryKiB < t.memoryKiB || p.iterations < t.iterations,
+  });
+}

package/src/bytes.mjs

@@ -0,0 +1,56 @@
+import { fail } from './errors.mjs';
+
+export const te = new TextEncoder();
+
+export function b64uEncode(bytes) {
+  let s = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+  return btoa(s).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+
+/** Strict base64url (no padding, no other alphabets). Throws VaultError('corrupt'). */
+export function b64uDecode(str, what = 'value') {
+  if (typeof str !== 'string' || !/^[A-Za-z0-9_-]*$/.test(str) || str.length % 4 === 1) fail('corrupt', `${what} is not base64url`);
+  const s = atob(str.replaceAll('-', '+').replaceAll('_', '/'));
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+
+/** Uint8Array | ArrayBuffer | base64url string -> Uint8Array copy-free where possible. */
+export function toBytes(v, what = 'value') {
+  if (v instanceof Uint8Array) return v;
+  if (v instanceof ArrayBuffer) return new Uint8Array(v);
+  if (ArrayBuffer.isView(v)) return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+  if (typeof v === 'string') return b64uDecode(v, what);
+  throw new TypeError(`${what} must be a Uint8Array, ArrayBuffer or base64url string`);
+}
+
+export const concat = (...parts) => {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+};
+
+/**
+ * Sorted-key JSON (JCS-like subset: objects, arrays, strings, booleans, null, safe integers). Identical to the
+ * canonicalisation p2pws uses for its header, so p2pws files authenticate the same bytes. Throws TypeError on anything else.
+ */
+export function canonicalize(v) {
+  if (v === null) return 'null';
+  switch (typeof v) {
+    case 'string': return JSON.stringify(v);
+    case 'boolean': return v ? 'true' : 'false';
+    case 'number':
+      if (!Number.isSafeInteger(v)) throw new TypeError('only safe integers are allowed in a header');
+      return String(v);
+    case 'object': {
+      if (Array.isArray(v)) return '[' + v.map(canonicalize).join(',') + ']';
+      const proto = Object.getPrototypeOf(v);
+      if (proto !== Object.prototype && proto !== null) throw new TypeError('plain objects only');
+      return '{' + Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canonicalize(v[k])).join(',') + '}';
+    }
+    default: throw new TypeError(`unsupported header value of type ${typeof v}`);
+  }
+}

package/src/derive.mjs

@@ -0,0 +1,67 @@
+import { fail, requireSecret } from './errors.mjs';
+import { te, toBytes, concat, b64uEncode } from './bytes.mjs';
+import { defaultKdf, validateKdf, kdfOf } from './kdf.mjs';
+
+/** The domain-separation prefix p2pws uses for its sign-in keys: salt || "\np2pws-login/" + purpose. */
+export const P2PWS_LOGIN_PREFIX = '\np2pws-login/';
+/** The `purpose` string that reproduces p2pws's login derivation for `name` ('auth' or 'vault'). */
+export const p2pwsLoginPurpose = (name) => P2PWS_LOGIN_PREFIX + name;
+/** The PBKDF2 parameters p2pws's login.mjs used before keyvault. Pass these to derive the same keys as existing logins. */
+export const P2PWS_LOGIN_KDF = Object.freeze({ name: 'PBKDF2-SHA256', iterations: 310_000 });
+
+const NORMALIZE = new Set([false, 'NFKC']);
+
+/** @returns {Promise<Uint8Array>} the raw derived bytes. Callers own (and should wipe) them. */
+export async function deriveBytes(secret, saltBytes, params, bits, normalize = false) {
+  if (!NORMALIZE.has(normalize)) throw new TypeError("normalize must be false or 'NFKC'");
+  const kdf = kdfOf(params);
+  return kdf.derive(te.encode(normalize ? secret.normalize(normalize) : secret), saltBytes, params, bits);
+}
+
+/**
+ * Stretch a human secret into a 32-byte key, domain-separated by `purpose`.
+ *
+ * The bytes actually fed to the KDF as salt are `salt || utf8(purpose)`. Two different purposes therefore give unrelated keys
+ * from the same secret and salt. `purpose` is required and is used verbatim, so p2pws's exact construction is
+ * `deriveKey(pw, salt, params, p2pwsLoginPurpose('auth'))`.
+ *
+ * The secret is used exactly as given (no Unicode normalisation) unless `options.normalize` is `'NFKC'`; this matches
+ * p2pws's login derivation, which does not normalise. Sealing (`seal`/`open`) always applies NFKC, as p2pws backups do.
+ *
+ * @param {string} secret
+ * @param {Uint8Array|ArrayBuffer|string} salt bytes, or a base64url string
+ * @param {{name: string, iterations: number}} [params] defaults to defaultKdf()
+ * @param {string} purpose non-empty domain-separation string
+ * @param {{bits?: number, normalize?: false|'NFKC', limits?: object}} [options]
+ * @returns {Promise<Uint8Array>}
+ */
+export async function deriveKey(secret, salt, params, purpose, options = {}) {
+  requireSecret(secret);
+  if (typeof purpose !== 'string' || purpose.length === 0) throw new TypeError('purpose must be a non-empty string');
+  const p = validateKdf(params ?? defaultKdf(), options.limits);
+  const bits = options.bits ?? 256;
+  if (!Number.isInteger(bits) || bits < 128 || bits > 512 || bits % 8) throw new TypeError('bits must be a multiple of 8 between 128 and 512');
+  const saltBytes = concat(toBytes(salt, 'salt'), te.encode(purpose));
+  return deriveBytes(secret, saltBytes, p, bits, options.normalize ?? false);
+}
+
+/**
+ * From one password derive an `authKey` (send it to a server, which should keep only a verifier of it) and a `vaultKey`
+ * (never sent; use it as the secret for `seal`). The two are unrelated. Both are base64url strings of 32 bytes.
+ *
+ * Existing p2pws logins were derived with 310,000 iterations: pass `P2PWS_LOGIN_KDF` to reproduce them, and re-seal with
+ * `defaultKdf()` on the next successful sign-in.
+ *
+ * @example const { authKey, vaultKey } = await deriveLoginKeys('correct horse battery', salt, P2PWS_LOGIN_KDF);
+ */
+export async function deriveLoginKeys(password, salt, params = defaultKdf(), options = {}) {
+  requireSecret(password, 1, 'password');
+  const [authKey, vaultKey] = await Promise.all(['auth', 'vault'].map(async (n) => b64uEncode(await deriveKey(password, salt, params, p2pwsLoginPurpose(n), options))));
+  return { authKey, vaultKey };
+}
+
+/** Only the vault half of `deriveLoginKeys` (p2pws's `deriveVaultKey`, for external logins). */
+export async function deriveVaultKey(passphrase, salt, params = defaultKdf(), options = {}) {
+  requireSecret(passphrase, 1, 'passphrase');
+  return b64uEncode(await deriveKey(passphrase, salt, params, p2pwsLoginPurpose('vault'), options));
+}

package/src/errors.mjs

@@ -0,0 +1,39 @@
+/**
+ * Every failure a caller is expected to handle is a VaultError with one of these stable codes.
+ * Programmer mistakes (wrong argument types for options, for example) throw TypeError instead.
+ */
+export const CODES = Object.freeze({
+  /** Wrong secret, or the file was modified (AES-GCM cannot tell the two apart). */
+  bad_passphrase: 'bad_passphrase',
+  /** Not a keyvault/p2pws/browsermesh record, truncated, or structurally invalid. */
+  corrupt: 'corrupt',
+  /** Valid shape but something we refuse: unknown version or KDF, parameters outside the accepted limits, KDF not enabled. */
+  unsupported: 'unsupported',
+  /** The record's `t` is not the type the caller asked for. */
+  wrong_type: 'wrong_type',
+  /** The secret is empty, undefined, not a string, or shorter than the caller's minimum. */
+  weak_secret: 'weak_secret',
+});
+
+export class VaultError extends Error {
+  /** @param {keyof typeof CODES} code @param {string} [message] */
+  constructor(code, message) {
+    super(message ?? code);
+    this.name = 'VaultError';
+    this.code = code;
+  }
+}
+
+export const fail = (code, message) => { throw new VaultError(code, message); };
+
+/**
+ * Refuse a secret that would not protect anything. PBKDF2 accepts an empty key and TextEncoder renders `undefined` as the
+ * bytes "undefined", so either would produce a well-formed ciphertext that anyone can open.
+ * @returns {string}
+ */
+export function requireSecret(secret, minLength = 1, what = 'secret') {
+  if (typeof secret !== 'string') fail('weak_secret', `${what} must be a string, got ${secret === null ? 'null' : typeof secret}`);
+  if (secret.length === 0) fail('weak_secret', `${what} must not be empty`);
+  if (secret.length < minLength) fail('weak_secret', `${what} must be at least ${minLength} characters`);
+  return secret;
+}

package/src/index.mjs

@@ -0,0 +1,5 @@
+export { VaultError, CODES } from './errors.mjs';
+export { defaultKdf, DEFAULT_LIMITS } from './kdf.mjs';
+export { deriveKey, deriveLoginKeys, deriveVaultKey, p2pwsLoginPurpose, P2PWS_LOGIN_PREFIX, P2PWS_LOGIN_KDF } from './derive.mjs';
+export { seal, open, openText, openJson, needsUpgrade, FORMAT_VERSION, BROWSERMESH_VAULT } from './seal.mjs';
+export { prfFromPasskey } from './passkey.mjs';

package/src/kdf.mjs

@@ -0,0 +1,71 @@
+// KDF registry. PBKDF2-SHA256 is built in (WebCrypto). Argon2id is registered by '@johnhenry/keyvault/argon2'.
+// Every KDF parameter set that is read from untrusted input passes through `validateKdf`, which enforces the caps.
+import { fail } from './errors.mjs';
+
+export const PBKDF2 = 'PBKDF2-SHA256';
+export const ARGON2ID = 'Argon2id';
+
+/** Hard defaults for what a file may ask of this machine. Callers can pass tighter (or looser) `limits`. */
+export const DEFAULT_LIMITS = Object.freeze({
+  minIterations: 1000,        // floor when reading; below this a "KDF" is no protection at all
+  maxIterations: 10_000_000,  // PBKDF2 cap: a hostile file cannot hang the tab (p2pws's cap)
+  maxArgon2Passes: 20,
+  maxMemoryKiB: 262_144,      // 256 MiB: Argon2 cap, so a hostile file cannot exhaust memory
+  maxParallelism: 16,
+});
+
+const int = (v) => typeof v === 'number' && Number.isSafeInteger(v);
+
+/** Raw PBKDF2 over WebCrypto. `hash` is only ever 'SHA-256' in the public API; SHA-1 exists so RFC 6070 can be checked. */
+export async function pbkdf2Bits(secret, salt, iterations, bits, hash = 'SHA-256') {
+  const base = await crypto.subtle.importKey('raw', secret, 'PBKDF2', false, ['deriveBits']);
+  return new Uint8Array(await crypto.subtle.deriveBits({ name: 'PBKDF2', hash, salt, iterations }, base, bits));
+}
+
+const registry = new Map();
+
+registry.set(PBKDF2, {
+  name: PBKDF2,
+  rank: 1,
+  validate(p, lim) {
+    if (!int(p.iterations)) fail('corrupt', 'kdf.iterations must be an integer');
+    if (p.iterations < lim.minIterations || p.iterations > lim.maxIterations) {
+      fail('unsupported', `kdf.iterations ${p.iterations} is outside the accepted range ${lim.minIterations}..${lim.maxIterations}`);
+    }
+    return { name: PBKDF2, iterations: p.iterations };
+  },
+  derive: (secret, salt, p, bits) => pbkdf2Bits(secret, salt, p.iterations, bits),
+  weaker: (p, target) => p.iterations < target.iterations,
+});
+
+/** Used by '@johnhenry/keyvault/argon2'. `impl(secret, salt, params, bits) -> Promise<Uint8Array>`. */
+export function registerKdf(def) { registry.set(def.name, def); }
+export const hasKdf = (name) => registry.has(name);
+
+/** The parameters new files are written with today. A fresh object each call. */
+export function defaultKdf() { return { name: PBKDF2, iterations: 600_000 }; }
+
+/**
+ * Validate KDF parameters from anywhere (a file, a caller). Returns a clean copy without `salt`.
+ * @throws {VaultError} corrupt (wrong shape), unsupported (unknown name / outside limits / not enabled)
+ */
+export function validateKdf(params, limits) {
+  if (!params || typeof params !== 'object' || Array.isArray(params)) fail('corrupt', 'kdf must be an object');
+  if (typeof params.name !== 'string') fail('corrupt', 'kdf.name must be a string');
+  const def = registry.get(params.name);
+  if (!def) {
+    fail('unsupported', params.name === ARGON2ID
+      ? "Argon2id is not enabled: import '@johnhenry/keyvault/argon2' and call enableArgon2id() first"
+      : `unknown key derivation function ${JSON.stringify(String(params.name).slice(0, 40))}`);
+  }
+  return def.validate(params, { ...DEFAULT_LIMITS, ...limits });
+}
+
+export const kdfOf = (params) => registry.get(params.name);
+
+/** Is `params` (validated) weaker than `target` (validated)? Different KDFs are ranked: Argon2id beats PBKDF2. */
+export function isWeaker(params, target) {
+  const a = kdfOf(params), b = kdfOf(target);
+  if (a.rank !== b.rank) return a.rank < b.rank;
+  return a.weaker(params, target);
+}

package/src/passkey.mjs

@@ -0,0 +1,40 @@
+import { fail } from './errors.mjs';
+import { toBytes, b64uEncode } from './bytes.mjs';
+
+/**
+ * Get a stable per-credential secret from a passkey via the WebAuthn `prf` extension. The secret exists only when the
+ * authenticator is used, so nothing a server stores can be guessed offline. Use the result as the `secret` for `seal`/`open`.
+ *
+ * Needs a secure context and a browser/authenticator with PRF support (otherwise VaultError 'unsupported'). The user-presence
+ * prompt and its cancellation surface as the browser's own DOMException (NotAllowedError); they are not wrapped.
+ *
+ * @param {object} options
+ * @param {Uint8Array|ArrayBuffer|string} options.credentialId  the credential to use (bytes, or base64url)
+ * @param {Uint8Array|ArrayBuffer|string} options.salt  application salt, 1..64 bytes; a different salt gives an unrelated secret
+ * @param {string} [options.rpId]
+ * @param {'required'|'preferred'|'discouraged'} [options.userVerification='preferred']
+ * @param {number} [options.timeout]
+ * @param {{get: Function}} [options.credentials=navigator.credentials]  injectable for tests
+ * @returns {Promise<string>} the 32-byte PRF output as base64url (a string, so it satisfies the "secret is a string" rule)
+ */
+export async function prfFromPasskey({ credentialId, salt, rpId, userVerification = 'preferred', timeout, credentials = globalThis.navigator?.credentials } = {}) {
+  if (!credentials || typeof credentials.get !== 'function') fail('unsupported', 'WebAuthn is not available in this environment');
+  const id = toBytes(credentialId, 'credentialId');
+  const saltBytes = toBytes(salt, 'salt');
+  if (id.length === 0) throw new TypeError('credentialId must not be empty');
+  if (saltBytes.length === 0 || saltBytes.length > 64) throw new TypeError('salt must be 1..64 bytes');
+  const publicKey = {
+    challenge: crypto.getRandomValues(new Uint8Array(32)), // the assertion is never verified server-side; PRF is the point
+    allowCredentials: [{ type: 'public-key', id }],
+    userVerification,
+    extensions: { prf: { eval: { first: saltBytes } } },
+  };
+  if (rpId) publicKey.rpId = rpId;
+  if (timeout) publicKey.timeout = timeout;
+  const cred = await credentials.get({ publicKey });
+  const first = cred?.getClientExtensionResults?.()?.prf?.results?.first;
+  if (!first) fail('unsupported', 'this passkey or browser does not support the WebAuthn PRF extension');
+  const out = ArrayBuffer.isView(first) ? new Uint8Array(first.buffer, first.byteOffset, first.byteLength) : new Uint8Array(first);
+  if (out.length !== 32) fail('corrupt', 'unexpected PRF output length');
+  return b64uEncode(out);
+}

package/src/seal.mjs

@@ -0,0 +1,162 @@
+import { fail, requireSecret, VaultError } from './errors.mjs';
+import { te, b64uEncode, b64uDecode, canonicalize } from './bytes.mjs';
+import { defaultKdf, validateKdf, isWeaker, PBKDF2 } from './kdf.mjs';
+import { deriveBytes } from './derive.mjs';
+
+export const FORMAT_VERSION = 1;
+/** `type` reported by open() for records written by browsermesh's VaultIdentityStorage. */
+export const BROWSERMESH_VAULT = 'browsermesh-vault';
+const RESERVED = new Set(['v', 't', 'kdf', 'iv', 'ct']);
+const SALT_BYTES = 16, IV_BYTES = 12, TAG_BYTES = 16;
+const MAX_FILE_CHARS = 2 * 1024 * 1024;     // reading: a hostile blob cannot be parsed forever
+const MAX_PAYLOAD_BYTES = 1024 * 1024;      // sealing: this is for keys, not files
+const MAX_HEADER_CHARS = 64 * 1024;
+const VAULT_DEFAULT_ITERATIONS = 310_000;   // VaultIdentityStorage's constant, used when its envelope has no `iterations`
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+async function aesKey(secret, salt, params, usage, normalize) {
+  const raw = await deriveBytes(secret, salt, params, 256, normalize);
+  try { return await crypto.subtle.importKey('raw', raw, 'AES-GCM', false, [usage]); } finally { raw.fill(0); }
+}
+
+function kdfToFile(params, salt) {
+  const { name, ...rest } = params;
+  return { name, ...rest, salt: b64uEncode(salt) };
+}
+
+/**
+ * Seal a small secret under a human secret.
+ *
+ * The file is plain JSON: `{ v: 1, t: type, kdf: {name, ...params, salt}, ...header, iv, ct }`. Everything except `ct` is bound
+ * as AES-GCM additional data, so editing the type, the KDF parameters or any header field makes `open` fail. This is
+ * byte-compatible with the files p2pws's backup.mjs writes (the secret is NFKC-normalised, as there).
+ *
+ * @param {Uint8Array|string} payload  bytes, or a string (UTF-8). At most 1 MiB.
+ * @param {string} secret  non-empty string (see `minLength`)
+ * @param {object} options
+ * @param {string} options.type  what this record is, e.g. 'p2pws-key-backup'. Checked by open().
+ * @param {object} [options.header]  extra authenticated, readable fields (strings, safe integers, booleans, null, arrays, plain objects). Not v/t/kdf/iv/ct.
+ * @param {{name: string, iterations: number}} [options.kdf]  defaults to defaultKdf()
+ * @param {number} [options.minLength=1]  minimum secret length, your password policy
+ * @param {object} [options.limits]  see DEFAULT_LIMITS
+ * @returns {Promise<string>} JSON text
+ */
+export async function seal(payload, secret, options = {}) {
+  const { type, header = {}, kdf, minLength = 1, limits } = options;
+  requireSecret(secret, minLength);
+  if (typeof type !== 'string' || type.length === 0) throw new TypeError('options.type must be a non-empty string');
+  if (!isObject(header)) throw new TypeError('options.header must be an object');
+  for (const k of Object.keys(header)) if (RESERVED.has(k)) throw new TypeError(`header field "${k}" is reserved`);
+  const bytes = typeof payload === 'string' ? te.encode(payload) : payload;
+  if (!(bytes instanceof Uint8Array)) throw new TypeError('payload must be a string or Uint8Array');
+  if (bytes.length > MAX_PAYLOAD_BYTES) fail('unsupported', 'payload is larger than 1 MiB; keyvault seals keys, not files');
+
+  const params = validateKdf(kdf ?? defaultKdf(), limits);
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const file = { v: FORMAT_VERSION, t: type, kdf: kdfToFile(params, salt), ...header, iv: b64uEncode(iv) };
+  let aad;
+  try { aad = te.encode(canonicalize(file)); } catch (e) { throw new TypeError(`header is not canonicalisable: ${e.message}`); }
+  if (aad.length > MAX_HEADER_CHARS) throw new TypeError('header is too large');
+  const key = await aesKey(secret, salt, params, 'encrypt', 'NFKC');
+  const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad }, key, bytes));
+  return JSON.stringify({ ...file, ct: b64uEncode(ct) }, null, 2);
+}
+
+/**
+ * Parse and structurally validate a record without decrypting it. Throws VaultError. Used by open() and needsUpgrade().
+ * @returns {{legacy: boolean, type: string, kdf: object, salt: Uint8Array, iv: Uint8Array, ct: Uint8Array, header: object, file: object}}
+ */
+export function parse(input, { limits, maxChars = MAX_FILE_CHARS } = {}) {
+  let f = input;
+  if (typeof input === 'string') {
+    if (input.length > maxChars) fail('corrupt', 'record is too large');
+    try { f = JSON.parse(input); } catch { fail('corrupt', 'not JSON (truncated or not a keyvault record)'); }
+  }
+  if (!isObject(f)) fail('corrupt', 'record must be a JSON object');
+  // A whole VaultIdentityStorage record: the envelope is its encryptedPrivateKey.
+  if (isObject(f.encryptedPrivateKey) && f.v === undefined && f.ct === undefined) f = f.encryptedPrivateKey;
+  if (f.v === undefined && f.t === undefined && typeof f.ciphertext === 'string') return parseVaultEnvelope(f, limits);
+
+  if (f.v !== FORMAT_VERSION) fail(typeof f.v === 'number' ? 'unsupported' : 'corrupt', typeof f.v === 'number' ? `unsupported record version ${f.v}` : 'not a keyvault record (no version)');
+  if (typeof f.t !== 'string' || f.t.length === 0) fail('corrupt', 'record has no type');
+  const kdf = validateKdf(f.kdf, limits);
+  const salt = b64uDecode(f.kdf.salt, 'kdf.salt');
+  if (salt.length < 8 || salt.length > 64) fail('corrupt', 'kdf.salt has a bad length');
+  const iv = b64uDecode(f.iv, 'iv');
+  if (iv.length !== IV_BYTES) fail('corrupt', 'iv has a bad length');
+  const ct = b64uDecode(f.ct, 'ct');
+  if (ct.length < TAG_BYTES) fail('corrupt', 'ciphertext is truncated');
+  const { kdf: _k, iv: _i, ct: _c, ...header } = f;
+  return { legacy: false, type: f.t, kdf, salt, iv, ct, header, file: f };
+}
+
+function parseVaultEnvelope(e, limits) {
+  if (e.kdf !== undefined && e.kdf !== PBKDF2) fail('unsupported', 'unsupported key derivation function in vault record');
+  const kdf = validateKdf({ name: PBKDF2, iterations: e.iterations ?? VAULT_DEFAULT_ITERATIONS }, limits);
+  const salt = b64uDecode(e.salt, 'salt');
+  if (salt.length < 8 || salt.length > 64) fail('corrupt', 'salt has a bad length');
+  const iv = b64uDecode(e.iv, 'iv');
+  if (iv.length !== IV_BYTES) fail('corrupt', 'iv has a bad length');
+  const ct = b64uDecode(e.ciphertext, 'ciphertext');
+  if (ct.length < TAG_BYTES) fail('corrupt', 'ciphertext is truncated');
+  return { legacy: true, type: BROWSERMESH_VAULT, kdf, salt, iv, ct, header: { t: BROWSERMESH_VAULT }, file: e };
+}
+
+/**
+ * Open a record written by `seal`, by p2pws's backup.mjs (types p2pws-key-backup, p2pws-identity-bundle,
+ * p2pws-account-recovery), or by browsermesh's VaultIdentityStorage (type 'browsermesh-vault'; the envelope or the whole record).
+ *
+ * Header fields come back only after authentication, so they can be trusted (browsermesh vault envelopes have no header).
+ * Apply your own checks to them (e.g. that a key id matches the decrypted key).
+ *
+ * @param {string|object} input  the JSON text (or parsed object)
+ * @param {string} secret
+ * @param {{type?: string, limits?: object}} [options]  `type`: refuse (wrong_type) anything else. Pass it.
+ * @returns {Promise<{header: object, type: string, kdf: object, payload: Uint8Array, legacy: boolean}>}
+ * @throws {VaultError} weak_secret | corrupt | unsupported | wrong_type | bad_passphrase
+ */
+export async function open(input, secret, options = {}) {
+  requireSecret(secret);
+  const { type, limits } = options;
+  if (type !== undefined && typeof type !== 'string') throw new TypeError('options.type must be a string');
+  const r = parse(input, { limits });
+  if (type !== undefined && r.type !== type) fail('wrong_type', `this is a ${JSON.stringify(r.type.slice(0, 60))} record, not ${JSON.stringify(type)}`);
+  const params = { name: 'AES-GCM', iv: r.iv };
+  if (!r.legacy) {
+    const { ct, ...rest } = r.file;
+    try { params.additionalData = te.encode(canonicalize(rest)); } catch { fail('corrupt', 'record header is not canonical'); }
+  }
+  // Vault envelopes were written without header binding and without NFKC; keep reading them exactly as written.
+  const key = await aesKey(secret, r.salt, r.kdf, 'decrypt', r.legacy ? false : 'NFKC');
+  let payload;
+  try { payload = new Uint8Array(await crypto.subtle.decrypt(params, key, r.ct)); } catch { fail('bad_passphrase', 'wrong secret, or the record was modified'); }
+  return { header: r.header, type: r.type, kdf: { ...r.kdf }, payload, legacy: r.legacy };
+}
+
+/** `open`, decoding the payload as UTF-8 text. */
+export async function openText(input, secret, options) {
+  const r = await open(input, secret, options);
+  try { return { ...r, payload: new TextDecoder('utf-8', { fatal: true }).decode(r.payload) }; } catch { fail('corrupt', 'payload is not UTF-8 text'); }
+}
+
+/** `open`, decoding the payload as JSON. */
+export async function openJson(input, secret, options) {
+  const r = await openText(input, secret, options);
+  try { return { ...r, payload: JSON.parse(r.payload) }; } catch { fail('corrupt', 'payload is not JSON'); }
+}
+
+/**
+ * True when the record should be re-sealed: its KDF is weaker than `target` (default `defaultKdf()`), or it is a
+ * browsermesh vault envelope (no header binding). Does not decrypt, so call it before or after a successful open().
+ * @param {string|object} input
+ * @param {{name: string, iterations: number}} [target]
+ */
+export function needsUpgrade(input, target = defaultKdf(), options = {}) {
+  const r = parse(input, options);
+  if (r.legacy) return true;
+  return isWeaker(r.kdf, validateKdf(target, options.limits));
+}
+
+export { VaultError };

package/types/argon2.d.ts

@@ -0,0 +1,10 @@
+import type { Argon2idParams } from './index.js';
+
+/** OWASP's minimum Argon2id profile (19 MiB, 2 passes, 1 lane), with optional overrides. */
+export function argon2idKdf(overrides?: Partial<Omit<Argon2idParams, 'name'>>): Argon2idParams;
+
+export interface Argon2idImplementation {
+  (args: { password: Uint8Array; salt: Uint8Array; iterations: number; memoryKiB: number; parallelism: number; hashLength: number }): Promise<Uint8Array> | Uint8Array;
+}
+/** Register Argon2id so `seal`, `open`, `deriveKey` and `needsUpgrade` understand it. Loads the optional `hash-wasm` unless `hash` is given. */
+export function enableArgon2id(options?: { hash?: Argon2idImplementation }): Promise<void>;

package/types/index.d.ts

@@ -0,0 +1,85 @@
+export type VaultErrorCode = 'bad_passphrase' | 'corrupt' | 'unsupported' | 'wrong_type' | 'weak_secret';
+
+export class VaultError extends Error {
+  constructor(code: VaultErrorCode, message?: string);
+  readonly name: 'VaultError';
+  readonly code: VaultErrorCode;
+}
+export const CODES: Readonly<Record<VaultErrorCode, VaultErrorCode>>;
+
+/** PBKDF2 parameters. */
+export interface Pbkdf2Params { name: 'PBKDF2-SHA256'; iterations: number }
+/** Argon2id parameters (needs `@johnhenry/keyvault/argon2`). `iterations` is the number of passes. */
+export interface Argon2idParams { name: 'Argon2id'; iterations: number; memoryKiB: number; parallelism: number }
+export type KdfParams = Pbkdf2Params | Argon2idParams;
+
+export interface Limits {
+  minIterations?: number;
+  maxIterations?: number;
+  maxArgon2Passes?: number;
+  maxMemoryKiB?: number;
+  maxParallelism?: number;
+}
+export const DEFAULT_LIMITS: Readonly<Required<Limits>>;
+
+/** `{ name: 'PBKDF2-SHA256', iterations: 600000 }` today. A fresh object each call. */
+export function defaultKdf(): Pbkdf2Params;
+
+export type Bytes = Uint8Array | ArrayBuffer;
+
+export interface DeriveOptions {
+  /** Output size in bits, a multiple of 8 from 128 to 512. Default 256. */
+  bits?: number;
+  /** Unicode-normalise the secret first. Default `false`, which is what p2pws's login derivation does. */
+  normalize?: false | 'NFKC';
+  limits?: Limits;
+}
+export function deriveKey(secret: string, salt: Bytes | string, params: KdfParams | undefined, purpose: string, options?: DeriveOptions): Promise<Uint8Array>;
+export function deriveLoginKeys(password: string, salt: Bytes | string, params?: KdfParams, options?: DeriveOptions): Promise<{ authKey: string; vaultKey: string }>;
+export function deriveVaultKey(passphrase: string, salt: Bytes | string, params?: KdfParams, options?: DeriveOptions): Promise<string>;
+export function p2pwsLoginPurpose(name: 'auth' | 'vault' | (string & {})): string;
+export const P2PWS_LOGIN_PREFIX: '\np2pws-login/';
+/** `{ name: 'PBKDF2-SHA256', iterations: 310000 }`: what existing p2pws logins were derived with. */
+export const P2PWS_LOGIN_KDF: Readonly<Pbkdf2Params>;
+
+export type HeaderValue = string | number | boolean | null | HeaderValue[] | { [key: string]: HeaderValue };
+export interface SealOptions {
+  /** What this record is, e.g. `'p2pws-key-backup'`. Checked by `open`. */
+  type: string;
+  /** Extra readable, authenticated fields. Not `v`, `t`, `kdf`, `iv` or `ct`. Numbers must be safe integers. */
+  header?: { [key: string]: HeaderValue };
+  kdf?: KdfParams;
+  /** Your password policy: refuse secrets shorter than this. Default 1. */
+  minLength?: number;
+  limits?: Limits;
+}
+export function seal(payload: Uint8Array | string, secret: string, options: SealOptions): Promise<string>;
+
+export interface OpenOptions { type?: string; limits?: Limits }
+export interface Opened<P = Uint8Array> {
+  /** Authenticated fields (`v`, `t` and everything given as `header`). For browsermesh vault records: `{ t: 'browsermesh-vault' }`. */
+  header: { v?: number; t: string; [key: string]: HeaderValue | undefined };
+  type: string;
+  kdf: KdfParams;
+  payload: P;
+  /** True for browsermesh VaultIdentityStorage envelopes (no header binding): re-seal them. */
+  legacy: boolean;
+}
+export function open(input: string | object, secret: string, options?: OpenOptions): Promise<Opened>;
+export function openText(input: string | object, secret: string, options?: OpenOptions): Promise<Opened<string>>;
+export function openJson<T = unknown>(input: string | object, secret: string, options?: OpenOptions): Promise<Opened<T>>;
+export function needsUpgrade(input: string | object, target?: KdfParams, options?: { limits?: Limits }): boolean;
+
+export const FORMAT_VERSION: 1;
+export const BROWSERMESH_VAULT: 'browsermesh-vault';
+
+export interface PrfOptions {
+  credentialId: Bytes | string;
+  salt: Bytes | string;
+  rpId?: string;
+  userVerification?: 'required' | 'preferred' | 'discouraged';
+  timeout?: number;
+  credentials?: { get(options: any): Promise<any> };
+}
+/** The 32-byte PRF output as base64url; use it as the `secret` for `seal`/`open`. */
+export function prfFromPasskey(options: PrfOptions): Promise<string>;