@le-space/orbitdb-identity-provider-webauthn-did 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changes
 
+## 0.9.0
+
+What applications kept writing for themselves, once and here: one read of the PRF output for every
+key an application derives from it, and a vault, so that a second security key can open what the
+first one sealed. Nothing changes for code that does not call it, and every derivation that exists
+today gives the same bytes.
+
+### Added
+
+- **`readPrfOutput(credential, options?)`**: one assertion, the PRF output. It always asks with a
+  fixed input — the credential's own, else the relying party's from `prfInputForRelyingParty` —
+  and never with a random one, whose answer would never come back. `PrfUnavailableError` when the
+  authenticator has no PRF; a refused prompt stays the browser's `NotAllowedError`.
+- **`deriveSubkey(prfOutput, info, { length })` and `deriveAesKey(prfOutput, info)`**: HKDF-SHA-256
+  with an empty salt, as bytes or as a non-extractable AES-GCM key. They give the same bytes as the
+  HKDF that Le-Space/belege, Le-Space/invoice and simple-todo's escrow01 each wrote themselves, and
+  as this package's signing-key derivation, which now runs on them. Vectors from all four are
+  tests.
+- **Vaults**: `createVault`, `openVault`, `addSlot`, `removeSlot`, `replacePayload`, `slotIdFor`
+  and `VaultError`. A random vault key seals the payload, and each registered authenticator gets a
+  slot holding that key, sealed under a key from its own PRF output, so any of them opens the
+  vault. The record is plain JSON with nothing secret in the clear; every ciphertext is bound to
+  the vault id and every slot to its authenticator. Removing a slot revokes nothing already
+  opened. Tested in Chromium with two virtual authenticators, each with its own PRF secret, as two
+  YubiKeys have.
+- **`prfOutput`**, an identity-provider option: the OrbitDB signing key is derived from a PRF
+  output the application already read, so unlocking its data and creating the identity cost one
+  touch instead of two. It is the same key the provider derives when it asks itself.
+- All of it in `./standalone` as well, and declared in `types/`.
+
+### Changed
+
+- `extractPrfSeedFromCredential` says on the console when it has no `prfInput`: it then asks a
+  random question, and the seed it returns never comes back. What it returns is unchanged.
+- `types/index.d.ts` declared `extractPrfSeedFromCredential` as synchronous and returning bytes. It
+  is async and returns `{ seed, source }`, as `types/standalone.d.ts` already said.
+  `PrfUnavailableError` is now declared in the root types as well.
+
 ## 0.8.0
 
 Two functions for wallets, and nothing that changes for anyone else. They were written against

package/README.md

@@ -21,12 +21,12 @@ This package provides:
 - Registration is still the point where this package extracts the credential public key from attestation.
 - Later `navigator.credentials.get()` assertions do not reliably return the public key again, so identity reconstruction still needs metadata from somewhere else.
 
-In this repo today, metadata recovery works in two layers:
+Since **0.6.0** the passkey alone is enough, and stored metadata is a convenience rather than a requirement:
 
-- **Preferred recovery path**: store identity metadata in WebAuthn `largeBlob` and recover it later through discoverable authentication.
-- **Fallback recovery path**: store the same metadata in browser `localStorage`.
+- **From the authenticator**: `restoreIdentityFromAuthenticator()` asks the same passkey twice and reconstructs the DID from the two signatures and the signing key from the PRF output, with nothing kept anywhere — see [Identity Recovery Summary](#identity-recovery-summary).
+- **From a stored copy**, when an application keeps one: WebAuthn `largeBlob`, or browser `localStorage`. It costs no touch at all, which is the only reason to keep one.
 
-This means discoverable credentials remove the need to pre-select the credential for authentication, but they do not by themselves eliminate the need for identity metadata persistence.
+`largeBlob` is requested at registration since 0.5.4 ([#55](https://github.com/Le-Space/orbitdb-identity-provider-webauthn-did/pull/55)), but it is not a path to rely on. Measured on hardware: Android Chrome writes the blob and does not return it on read, while desktop Chrome reads it ([#48](https://github.com/Le-Space/orbitdb-identity-provider-webauthn-did/issues/48)).
 
 **Which option, and what each one actually gives you:**
 
@@ -105,11 +105,10 @@ For the DID-based flow:
 - later discoverable `navigator.credentials.get()` proves possession of the credential, but usually returns only `rawId`, `authenticatorData`, `clientDataJSON`, `signature`, and maybe `userHandle`
 - that assertion is not enough on its own to reconstruct the DID
 
-To address this, the demos now attempt to:
+Two ways past that, and the first keeps nothing:
 
-1. write identity metadata to `largeBlob` after passkey creation
-2. recover that metadata later through discoverable authentication
-3. fall back to local browser storage if `largeBlob` is unavailable or empty
+1. `restoreIdentityFromAuthenticator()` — two discoverable assertions, from which `recoverPublicKey()` returns the credential's public key and with it the DID (0.6.0)
+2. metadata written at registration — `largeBlob` where it comes back, otherwise browser storage — which the demos still do, because a stored copy spares both touches
 
 ### Hardware-Secured Varsig Quick Start
 
@@ -181,7 +180,7 @@ The verifier side and app protocol should define which domain label is required.
 
 ### Passkeys for smart accounts (P-256)
 
-One passkey can be both the OrbitDB identity and the key of a smart account that verifies P-256 WebAuthn signatures on-chain, such as Uniswap's [Calibur](https://github.com/Uniswap/calibur) with Base's [webauthn-sol](https://github.com/base/webauthn-sol). The standalone export hands wallet code the key and the signature parts; turning them into a transaction (key hashes, ABI encoding, the account client) stays in the wallet.
+Since **0.8.0**, one passkey can be both the OrbitDB identity and the key of a smart account that verifies P-256 WebAuthn signatures on-chain, such as Uniswap's [Calibur](https://github.com/Uniswap/calibur) with Base's [webauthn-sol](https://github.com/base/webauthn-sol). The standalone export hands wallet code the key and the signature parts; turning them into a transaction (key hashes, ABI encoding, the account client) stays in the wallet.
 
 ```javascript
 import {
@@ -210,6 +209,24 @@ const { authenticatorData, clientDataJSON, challengeIndex, typeIndex, r, s } =
 | Keystore or worker Ed25519 DID                 | yes, from the credential's `x`/`y`; the DID does not commit to the passkey, so link the wallet key to it yourself |
 | Hardware Ed25519 (varsig)                      | `null`: there is no P-256 key                                                                                     |
 
+### One touch, and a second security key
+
+Since **0.9.0**, an application that keeps data under keys from the passkey reads the PRF output once with `readPrfOutput()`, derives each key from it with `deriveSubkey()` or `deriveAesKey()`, and hands the same output to the identity provider as `prfOutput`: unlocking and signing cost one touch. What has to outlive one security key goes into a vault, with a slot for every registered authenticator, so a second YubiKey opens what the first one sealed.
+
+```javascript
+const prfOutput = await readPrfOutput(credential);
+const slot = {
+  slotKey: await deriveAesKey(prfOutput, 'myapp/vault-slot/v1'),
+  rawCredentialId: credential.rawCredentialId,
+};
+const { vault, vaultKey } = await createVault(payload, slot); // later: openVault(vault, slot)
+
+// With the vault open, touch the second key and give it a slot of its own.
+const withSecondKey = await addSlot(vault, vaultKey, secondKeysSlot);
+```
+
+How it works, and what a vault does not do: [docs/API.md](docs/API.md#prf-keys-and-vaults).
+
 ### Keystore-based DID (WebAuthn + OrbitDB keystore)
 
 ```mermaid
@@ -360,7 +377,8 @@ sequenceDiagram
 ## Examples
 
 Three demo apps, one per option, in one pnpm workspace (`examples/README.md`
-has the install). Each proves its option in the browser: a real
+has the install), and a probe that measures the authenticator itself. Each
+demo proves its option in the browser: a real
 authenticator (Chromium's virtual one in CI), a badge that is the verdict of
 the same checks a peer makes, and a panel that runs those checks on two
 forgeries.
@@ -376,12 +394,36 @@ forgeries.
 - `examples/webauthn-varsig-demo/` — varsig: the passkey signs every write,
   no keystore. Live:
   https://le-space.github.io/orbitdb-identity-provider-webauthn-did/webauthn-varsig-demo/
+- `examples/passkey-probe/` — not an option but an instrument, for the
+  authenticator in front of you: create a passkey, ask for PRF, derive a key
+  from it, write an encrypted record, read it back, recover it on what stands
+  in for a second device. One static file in two languages, no build step, so
+  what is served is what a reader gets by opening it. Live:
+  https://le-space.github.io/orbitdb-identity-provider-webauthn-did/passkey-probe/
 
 The identity for each option is built by one module under
 `examples/shared/lib/options/`, which is also the shortest way to read the
 API; `docs/EXAMPLE-SEQUENCES.md` walks through the three sequences and their
 prompt counts.
 
+### In other repositories
+
+Three consumers that show the package doing a whole job rather than one call:
+
+- [orbitdb-storage-bridge `examples/svelte/recovery`](https://github.com/NiKrause/orbitdb-storage-bridge/tree/main/examples/svelte/recovery)
+  — a page that takes a security key and nothing else, and ends up with an
+  identity OrbitDB accepts and a list it can write to. Its browser test stands
+  a virtual authenticator in for the YubiKey the two phones used. It ran in
+  funkpost until 2026-09-23, and moved to the packages it demonstrates. Live:
+  https://nikrause.github.io/orbitdb-storage-bridge/recovery/
+- [orbitdb-storage-bridge, _Getting a database back on a device that has
+  nothing_](https://github.com/NiKrause/orbitdb-storage-bridge/blob/main/docs/RECOVERY-ON-A-SECOND-DEVICE.md)
+  — the other half of a recovery: this package returns the identity, that one
+  returns the database, and the PRF output is what both are derived from.
+- [simple-todo `escrow01`](https://github.com/Le-Space/simple-todo/tree/main/apps/escrow01)
+  — one passkey as the OrbitDB identity _and_ the admin key of a Calibur smart
+  account, using the P-256 primitives of the standalone export.
+
 ## Documentation
 
 - `docs/API.md`
@@ -424,11 +466,14 @@ Since **0.6.0** an identity can be restored on a device that has stored nothing:
 - The PRF input is fixed per relying party, so a second device asks the authenticator the same question and receives the same secret; the signing key is derived from it with the DID mixed in.
 - `restoreIdentityFromAuthenticator()` does both touches and returns the DID, the public key and the signing key — and, since 0.7.0, the credential the provider takes as it is: `OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential: restored.credential })`.
 
-Metadata persistence is therefore a **convenience, not a requirement**. The demos still try `largeBlob` first and fall back to browser storage, which saves a touch of the key; neither is needed to reconstruct the identity.
+**What that costs the person holding the key.** Two presentations of it: with a security key, two taps; with a platform passkey, two fingerprints. A third follows when OrbitDB builds the identity and asks for its signature — unless the application puts the returned `signingKey` into its keystore first, in which case the restore's own PRF read is not repeated. Applications can name each step through the `onTouch` callback rather than leaving a person wondering why they are being asked again.
+
+Metadata persistence is therefore a **convenience, not a requirement**. A stored copy spares those touches, which is why the demos still write one; `largeBlob` is the less dependable half of that, since Android Chrome writes it but does not return it ([#48](https://github.com/Le-Space/orbitdb-identity-provider-webauthn-did/issues/48)).
 
 Practical implication:
 
 - A passkey created in one browser profile reconstructs the same OrbitDB identity in a fresh profile — or on another phone — with nothing carried over. Measured on one YubiKey across a Galaxy Fold 5 and a Galaxy A57 (2026-09-19): same PRF value, same recovered DID, same derived signing key.
+- The same thing, as an application rather than a measurement: on 2026-09-21 a Fold 5 made a list and was reset, and an A57 holding the same YubiKey had the same identity, brought the list back with the key alone and wrote to it ([funkpost#93](https://github.com/NiKrause/funkpost/issues/93)). The page it ran is [`examples/svelte/recovery`](https://github.com/NiKrause/orbitdb-storage-bridge/tree/main/examples/svelte/recovery), which has since moved to orbitdb-storage-bridge, with a browser test that stands a virtual authenticator in for the key.
 - An authenticator without PRF gets a **refusal**, not a substitute. An identity derived from something else is a different identity that looks like success.
 - Credentials registered before 0.6.0 keep the random PRF input stored with them, so their identities do not move.
 

package/docs/API.md

@@ -106,6 +106,9 @@ property:
 - `WebAuthnAuthenticationError`
 - `WebAuthnVerificationError`
 - `KeystoreEncryptionError`
+  - `PrfUnavailableError` (`PRF_UNAVAILABLE`) — the authenticator answered
+    without a PRF output
+  - `VaultError` — a vault refused; see [Vaults](#vaults)
 - `VarsigVerificationError`
 
 ```js
@@ -165,6 +168,9 @@ Common options:
 - `keystoreEncryptionMethod`
 - `keyType`
 - `usePersistentKey`
+- `prfOutput` — a PRF output already read with `readPrfOutput`, so the signing
+  key costs no second touch; see
+  [One touch for the data and the identity](#one-touch-for-the-data-and-the-identity)
 
 ### WebAuthn Configuration
 
@@ -187,6 +193,189 @@ Returns the current WebAuthn config.
 
 Restores default WebAuthn config.
 
+### Identity Restore
+
+#### `restoreIdentityFromAuthenticator(options?)`
+
+Reconstructs an identity on a device that has stored nothing — a second device,
+or the same one after its profile was cleared. Two touches of the same passkey:
+the first is asked with the relying party's fixed PRF input, the second signs
+another challenge, and the two signatures together give back the credential's
+public key, which a single assertion does not carry. The DID follows from that
+key, and the signing key from the PRF output with the DID mixed in.
+
+```js
+import { restoreIdentityFromAuthenticator } from '@le-space/orbitdb-identity-provider-webauthn-did';
+
+const restored = await restoreIdentityFromAuthenticator({
+  onTouch: ({ touch, of }) => setStatus(`Touch ${touch} of ${of}`),
+});
+
+const identity = await identities.createIdentity({
+  provider: OrbitDBWebAuthnIdentityProviderFunction({
+    webauthnCredential: restored.credential,
+  }),
+});
+```
+
+Options, all optional:
+
+- `rpId` — relying party id; the current host by default.
+- `timeout` — per touch, in ms; `120000`. Generous on purpose: an NFC key has to
+  be found, held and read.
+- `signingKeyType` — `'secp256k1'` by default, as the keystore wants it. Pass
+  the same type the identity was created with.
+- `onTouch({ touch, of })` — called before each ceremony, so an application can
+  say which touch this is rather than leaving a person wondering why they are
+  asked twice.
+
+Returns `{ did, publicKey: { x, y }, credentialId, rawCredentialId, signingKey,
+prfInput, credential }`. `credential` is what
+`OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential })` takes;
+`credentialId` is base64url text and `rawCredentialId` the bytes (before 0.7.0,
+`credentialId` was the bytes).
+
+Putting `signingKey` into the keystore under the DID before OrbitDB builds the
+identity spares one further touch: the provider would otherwise read the PRF
+output a second time to derive the very same key.
+
+Throws rather than substituting anything:
+
+- `WebAuthnIdentityError` (`WEBAUTHN_NOT_SUPPORTED`) where WebAuthn is absent,
+  and when no credential is offered for this relying party.
+- `PrfUnavailableError` when the authenticator cannot evaluate PRF. Nothing
+  stands in for it: an identity derived from something else is a different
+  identity that looks like success.
+
+Since 0.6.0. Measured on hardware across two phones sharing one YubiKey, and
+used in [the recovery example](https://github.com/NiKrause/orbitdb-storage-bridge/tree/main/examples/svelte/recovery);
+the database half of the same problem is in
+[orbitdb-storage-bridge](https://github.com/NiKrause/orbitdb-storage-bridge/blob/main/docs/RECOVERY-ON-A-SECOND-DEVICE.md).
+
+### PRF Keys and Vaults
+
+Since 0.9.0. Applications that keep data under keys from the passkey used to
+write their own HKDF over the PRF output, read it once per key, and had no way
+for a second security key to open what the first one sealed. These functions
+replace that: one read, any number of keys derived from it, and a vault any
+registered authenticator opens.
+
+#### `readPrfOutput(credential, options?)`
+
+One assertion — one touch — returning the credential's PRF output, 32 bytes.
+It always asks the same question: `options.prfInput`, else the input the
+credential was registered with, else `prfInputForRelyingParty(rpId)`, which
+every device computes alike. It never draws a random input, which would give
+bytes that never come back.
+
+- `rpId` — the current host by default.
+- `prfInput` — overrides the credential's. Leave it out when the output also
+  goes to the identity provider, which asks with the credential's.
+
+Throws `PrfUnavailableError` when the authenticator answers without a PRF
+output. A refused prompt stays the browser's `NotAllowedError`, so "the user
+said no" and "this authenticator has no PRF" can be told apart.
+
+#### `deriveSubkey(prfOutput, info, { length = 32 })`
+
+HKDF-SHA-256 with an empty salt, 1 to 8160 bytes. `info` is part of the data
+format: the same output and `info` always give the same bytes, and a different
+`info` gives unrelated ones. Name it after the application and the purpose, and
+version it — `invoice/db-key/v1`; bumping the version rotates the key and makes
+everything sealed under the old one unreadable.
+
+The derivations Le-Space/belege, Le-Space/invoice and simple-todo's escrow01
+wrote for themselves give the same bytes through it, and so does this
+package's own signing key; `tests/prf-keys.test.js` holds vectors from each.
+
+#### `deriveAesKey(prfOutput, info)`
+
+The same derivation as a non-extractable AES-GCM-256 `CryptoKey`: it encrypts
+and decrypts, and no script can read its bytes.
+
+#### One touch for the data and the identity
+
+Hand the output to the identity provider as `prfOutput`, and it derives the
+OrbitDB signing key from it instead of asking the passkey again:
+
+```js
+const prfOutput = await readPrfOutput(credential);
+
+const { payload } = await openVault(vault, {
+  slotKey: await deriveAesKey(prfOutput, 'invoice/vault-slot/v1'),
+  rawCredentialId: credential.rawCredentialId,
+});
+
+const identity = await identities.createIdentity({
+  provider: OrbitDBWebAuthnIdentityProviderFunction({
+    webauthnCredential: credential,
+    prfOutput,
+  }),
+});
+```
+
+It is the same key the provider would have derived by asking itself, so a
+device where nobody hands it over arrives at the same identity document. The
+provider instance drops its reference once the key is in the keystore and
+never alters the bytes; the options object passed to
+`OrbitDBWebAuthnIdentityProviderFunction` still holds them for as long as the
+application keeps it. `encryptKeystore` still asks on its own.
+
+#### Vaults
+
+A key derived from a passkey exists only where that passkey is. A second
+security key has its own PRF secret, so it derives different keys and cannot
+open what the first one sealed. A vault holds what must be the same for every
+key — a database key, database names, a peer seed — sealed under a random
+vault key, and gives each registered authenticator a slot: the vault key,
+sealed under that authenticator's
+`deriveAesKey(prfOutput, '<app>/vault-slot/v1')`. Any slot opens the vault.
+
+- `createVault(payload, { slotKey, rawCredentialId })` → `{ vault, vaultKey }`.
+  The creating authenticator's slot comes with it: a vault without one could
+  never be opened.
+- `openVault(vault, { slotKey, rawCredentialId })` → `{ payload, vaultKey }`.
+- `addSlot(vault, vaultKey, { slotKey, rawCredentialId })` → a new record with
+  the new authenticator's slot. It needs the vault open and the new key
+  touched, so in practice both keys are at one computer.
+- `removeSlot(vault, rawCredentialId)` → a new record without that slot. It
+  needs no key: whoever may write the record may shorten it, so guard the
+  record where it is stored.
+- `replacePayload(vault, vaultKey, payload)` → a new record with a new
+  payload, the same vault key and the same slots.
+- `slotIdFor(rawCredentialId)` → the id a slot is filed under, the SHA-256 of
+  the raw credential id; the id itself is never written into the record.
+
+Each function returns a new record and leaves the one passed in unchanged. The
+record is plain JSON with nothing secret in the clear (format version 1, in
+`src/keystore/vault.js`), so it can be stored anywhere, replicated, and backed
+up in public. Every ciphertext in it is bound to the vault's id, and every slot
+also to its authenticator, so neither can be moved to another vault or
+relabelled to another authenticator.
+
+Refusals are `VaultError`, with `code`:
+
+- `VAULT_MALFORMED` — not a version-1 vault
+- `VAULT_NO_SLOT` — this authenticator has no slot
+- `VAULT_LOCKED` — the key does not open it, or the record was altered
+- `VAULT_SLOT_EXISTS` — the authenticator already has a slot
+- `VAULT_LAST_SLOT` — the last slot cannot go
+
+What a vault does not do:
+
+- **Removing a slot revokes nothing already opened.** An authenticator that
+  opened the vault has seen the vault key, and older copies of the record still
+  carry its slot. Against a stolen key, make a new vault with a new key and move
+  what the old one protected.
+- **It cannot tell the current record from an earlier copy of itself.** Where a
+  rollback matters, the place the record is stored has to say which is current.
+- **It does not make two keys one person.** Each authenticator keeps its own DID
+  and signing key; who may write to a database is its access controller's
+  decision.
+
+`tests/vault-two-authenticators.test.js` runs this in Chromium with two virtual
+authenticators, each with its own PRF secret as two YubiKeys have.
+
 ### largeBlob Metadata Helpers
 
 These helpers encode and recover identity metadata used by the demo recovery
@@ -200,8 +389,13 @@ flows.
 - `writeLargeBlobMetadata(credentialId, payload, options)`
 
 Discoverable passkeys can identify a credential later, but WebAuthn assertions
-do not reliably return the public key after registration. Persisted metadata is
-therefore still required to reconstruct an OrbitDB identity.
+do not reliably return the public key after registration. Persisted metadata was
+therefore the only way to reconstruct an identity until 0.6.0; since then
+`restoreIdentityFromAuthenticator()` does it from two signatures instead, and a
+stored copy only spares the touches. `largeBlob` is the less dependable place to
+keep one: Android Chrome writes the blob and does not return it on read, while
+desktop Chrome reads it
+([#48](https://github.com/Le-Space/orbitdb-identity-provider-webauthn-did/issues/48)).
 
 ### Credential Storage Helpers
 
@@ -216,7 +410,11 @@ Safer storage helpers:
 - `storeWebAuthnCredentialSafe(credential, key?)`
 - `loadWebAuthnCredentialSafe(key?)`
 - `clearWebAuthnCredentialSafe(key?)`
-- `extractPrfSeedFromCredential(credential)`
+- `extractPrfSeedFromCredential(credential, options?)` →
+  `{ seed, source: 'prf' }`, or `{ seed: null, source: 'none' }` without PRF.
+  Without a `prfInput` — in `options` or on the credential — it asks a random
+  question, so the seed never comes back and nothing derived from it survives
+  the page; it says so on the console. Prefer `readPrfOutput`.
 
 ### Keystore Encryption Helpers
 
@@ -347,7 +545,15 @@ const ucanSigner = signer.toUcantoSigner({
 - `storeWebAuthnCredentialSafe(credential, key?)`
 - `loadWebAuthnCredentialSafe(key?)`
 - `clearWebAuthnCredentialSafe(key?)`
-- `extractPrfSeedFromCredential(credential)`
+- `extractPrfSeedFromCredential(credential, options?)` — see
+  [Credential Storage Helpers](#credential-storage-helpers)
+
+### PRF Keys and Vaults (standalone)
+
+The same functions as the root export, without OrbitDB: `readPrfOutput`,
+`deriveSubkey`, `deriveAesKey`, `createVault`, `openVault`, `addSlot`,
+`removeSlot`, `replacePayload`, `slotIdFor`, `PrfUnavailableError` and
+`VaultError`. See [PRF Keys and Vaults](#prf-keys-and-vaults).
 
 ### P-256 Wallet Primitives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-identity-provider-webauthn-did",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "WebAuthn-based DID identity provider for OrbitDB for hardware-secured wallets and biometric Passkey authentication",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -118,6 +118,7 @@
     "libp2p": "^3.3.4",
     "mocha": "^10.0.0",
     "prettier": "^3.6.2",
+    "viem": "^2.56.5",
     "vite-plugin-node-polyfills": "^0.24.0"
   },
   "engines": {
@@ -145,7 +146,7 @@
       "iso-web": "^3.1.2",
       "iso-webauthn-varsig": "npm:@le-space/iso-webauthn-varsig@^0.3.0",
       "conf>ajv": "^8.18.0",
-      "ajv>fast-uri": "^3.1.6"
+      "ajv>fast-uri": "^3.1.8"
     },
     "onlyBuiltDependencies": [
       "@ipshipyard/node-datachannel",

package/src/errors.js

@@ -6,6 +6,11 @@ export const ERROR_CODES = Object.freeze({
   KEYSTORE_ENCRYPTION_FAILED: 'KEYSTORE_ENCRYPTION_FAILED',
   VARSIG_VERIFICATION_FAILED: 'VARSIG_VERIFICATION_FAILED',
   INVALID_INPUT: 'INVALID_INPUT',
+  VAULT_MALFORMED: 'VAULT_MALFORMED',
+  VAULT_NO_SLOT: 'VAULT_NO_SLOT',
+  VAULT_LOCKED: 'VAULT_LOCKED',
+  VAULT_SLOT_EXISTS: 'VAULT_SLOT_EXISTS',
+  VAULT_LAST_SLOT: 'VAULT_LAST_SLOT',
 });
 
 export class WebAuthnIdentityError extends Error {
@@ -86,6 +91,22 @@ export class PrfUnavailableError extends KeystoreEncryptionError {
   }
 }
 
+/**
+ * A vault refused: it is not a vault (`VAULT_MALFORMED`), this authenticator
+ * has no slot in it (`VAULT_NO_SLOT`), the key does not open it or it was
+ * altered (`VAULT_LOCKED`), the authenticator already has a slot
+ * (`VAULT_SLOT_EXISTS`), or the slot is the last one (`VAULT_LAST_SLOT`).
+ */
+export class VaultError extends KeystoreEncryptionError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || ERROR_CODES.VAULT_MALFORMED,
+    });
+    this.name = 'VaultError';
+  }
+}
+
 export class VarsigVerificationError extends WebAuthnIdentityError {
   constructor(message, options = {}) {
     super(message, {

package/src/index.js

@@ -296,7 +296,7 @@ export {
   createSessionKeystore,
   isSessionKeystore,
 } from './keystore/session-keystore.js';
-export { PrfUnavailableError } from './errors.js';
+export { PrfUnavailableError, VaultError } from './errors.js';
 // Restoring on a device that has stored nothing (#61): the fixed PRF input,
 // the public key recovered from two assertions, and the two together.
 export {
@@ -314,6 +314,21 @@ export {
   deriveSigningKeyBytes,
   getPrfOutput,
 } from './keystore/derived-signing-key.js';
+// Read the PRF output once and derive everything from that one answer, and keep
+// what must outlive one security key in a vault any registered one can open.
+export {
+  readPrfOutput,
+  deriveSubkey,
+  deriveAesKey,
+} from './keystore/prf-keys.js';
+export {
+  createVault,
+  openVault,
+  addSlot,
+  removeSlot,
+  replacePayload,
+  slotIdFor,
+} from './keystore/vault.js';
 
 export default {
   WebAuthnDIDProvider,

package/src/keystore/derived-signing-key.js

@@ -36,6 +36,7 @@ import {
 import { CRYPTO_ALGORITHMS, KEY_TYPES } from '../constants.js';
 import { buildCredentialRequestOptions } from '../webauthn/config.js';
 import { prfInputForRelyingParty } from '../webauthn/prf-input.js';
+import { hkdfSha256 } from './prf-keys.js';
 
 const log = logger('orbitdb-identity-provider-webauthn-did:derived-key');
 
@@ -45,30 +46,15 @@ const DERIVATION_INFO = 'orbitdb-identity-provider-webauthn-did:signing-key:v1';
 const SECP256K1_KEY_BYTES = 32;
 
 /**
- * HKDF-SHA256 a 32-byte candidate from the PRF seed.
+ * HKDF-SHA256 a 32-byte candidate from the PRF seed — the same HKDF that
+ * `deriveSubkey` exposes, without its input checks, so this derivation accepts
+ * exactly what it accepted before.
  * @param {Uint8Array} seed - PRF output.
  * @param {string} info - Domain separation string.
  * @returns {Promise<Uint8Array>} 32 bytes.
  */
-async function hkdf(seed, info) {
-  const baseKey = await crypto.subtle.importKey(
-    'raw',
-    seed,
-    CRYPTO_ALGORITHMS.HKDF,
-    false,
-    ['deriveBits']
-  );
-  const bits = await crypto.subtle.deriveBits(
-    {
-      name: CRYPTO_ALGORITHMS.HKDF,
-      hash: CRYPTO_ALGORITHMS.SHA_256,
-      salt: new Uint8Array(0),
-      info: new TextEncoder().encode(info),
-    },
-    baseKey,
-    SECP256K1_KEY_BYTES * 8
-  );
-  return new Uint8Array(bits);
+function hkdf(seed, info) {
+  return hkdfSha256(seed, info, SECP256K1_KEY_BYTES);
 }
 
 /**
@@ -186,6 +172,10 @@ export async function getPrfOutput(credential, { rpId } = {}) {
  * @param {Object} params.credential - Stored WebAuthn credential info.
  * @param {string} [params.rpId] - Relying party id.
  * @param {string} [params.keyType='secp256k1'] - Type of key to derive.
+ * @param {Uint8Array} [params.seed] - A PRF output already read, e.g. by
+ *   `readPrfOutput` while unlocking something else. When given, the passkey is
+ *   not asked again: one touch serves the signing key and whatever else the
+ *   application derives from the same answer.
  * @returns {Promise<'derived'|'existing'|'unavailable'>} What happened.
  */
 export async function ensureDerivedSigningKey({
@@ -194,6 +184,7 @@ export async function ensureDerivedSigningKey({
   credential,
   rpId,
   keyType = KEY_TYPES.SECP256K1,
+  seed: prfSeed,
 }) {
   if (!keystore || !did || !credential) return 'unavailable';
 
@@ -218,7 +209,10 @@ export async function ensureDerivedSigningKey({
     return 'unavailable';
   }
 
-  const seed = await getPrfOutput(credential, { rpId });
+  const seed =
+    prfSeed instanceof Uint8Array
+      ? prfSeed
+      : await getPrfOutput(credential, { rpId });
   if (!seed) {
     log(
       'no PRF output; falling back to a keystore-generated key, so this identity is stable per device but not reproducible across devices'