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

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # 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
+0.5.4 on 16 September and vendored into simple-todo's `escrow01` as `0.5.5-p256.8366ed8`, but
+never pushed or released until now — which is why 0.6.0 and 0.7.0 do not have them, and why #70
+took their absence for a removal.
+
+### Added
+
+- **Passkey primitives for wallets**, in `./standalone` (#60). A smart
+  account that verifies P-256 WebAuthn signatures on-chain — Uniswap's
+  Calibur, through webauthn-sol — can use the identity's passkey, without
+  the wallet duplicating key extraction and DER parsing or creating a
+  second passkey when it cannot recover the key.
+  - `getP256CredentialDescriptor(credential)` returns
+    `{ credentialId, rawCredentialId, x, y, rpId, userVerification }`, with
+    `x` and `y` as 32-byte big-endian `Uint8Array`s, from either credential
+    shape, a stored or JSON copy, or a P-256 `did:key` alone (a varsig DID
+    holds the key compressed). It returns `null` for RS256 and Ed25519 keys,
+    for anything unreadable, and for the placeholder `createCredential`
+    writes when it cannot read the public key — also once that has lost its
+    `synthetic` flag, which largeBlob metadata does not carry: the point has
+    to lie on the curve.
+  - `signP256Challenge(descriptor, challenge)` signs exactly 32 bytes, with
+    `allowCredentials` pinned to the descriptor whatever the discoverable
+    credential policy, and user verification required. It refuses an
+    assertion whose `rawId` differs and returns
+    `{ authenticatorData, clientDataJSON, challengeIndex, typeIndex, r, s }`:
+    `r` and `s` left-padded to 32 bytes, `s` normalised to low-s, and the
+    indices as the byte offsets of `"type":"webauthn.get"` and
+    `"challenge":"…"` that webauthn-sol reads. The signature is verified
+    against `x`/`y` before it is returned.
+
+### Changed
+
+- `createCredential` returns `rpId` on both paths, and a stored varsig
+  (hardware signer) credential keeps it. An assertion has to name the rpId
+  the credential was registered under, which need not be the page's
+  hostname.
+
 ## 0.7.0
 
 **One breaking change, in the function 0.6.0 added.** `restoreIdentityFromAuthenticator()`

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
 
@@ -179,6 +178,55 @@ const ucanUcantoSigner = signer.toUcantoSigner({
 
 The verifier side and app protocol should define which domain label is required. IPFS deployment does not change this requirement.
 
+### Passkeys for smart accounts (P-256)
+
+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 {
+  getP256CredentialDescriptor,
+  signP256Challenge,
+} from '@le-space/orbitdb-identity-provider-webauthn-did/standalone';
+
+// A credential from either createCredential, storage, largeBlob or signer.credential
+const descriptor = getP256CredentialDescriptor(credential);
+if (!descriptor) throw new Error('This passkey has no usable P-256 key');
+// { credentialId, rawCredentialId, x, y, rpId, userVerification: 'required' }
+
+// Exactly 32 bytes, e.g. a user operation hash
+const { authenticatorData, clientDataJSON, challengeIndex, typeIndex, r, s } =
+  await signP256Challenge(descriptor, hash);
+```
+
+- **Key.** `x` and `y` are 32-byte big-endian `Uint8Array`s, like `publicKey.x`/`y` on the default path; Calibur's `abi.encode(uint256 x, uint256 y)` is the two concatenated. They come from `publicKey` (`{ x, y }` or SEC1 bytes) or, failing that, from a P-256 `did:key`; where both are present they must agree. `rpId` is the one `createCredential` returns; a credential stored before it returned one falls back to `window.location.hostname`.
+- **`null`** for RS256 and Ed25519 keys, for the placeholder `createCredential` writes when it cannot read the public key (also once largeBlob metadata has dropped its `synthetic` flag: the point is not on the curve), and for anything unreadable.
+- **Signing.** Unlike other requests, this one pins `allowCredentials` to the descriptor, whatever `configureWebAuthn` says, and requires user verification. An assertion from another credential is refused. The challenge is used as the WebAuthn challenge itself, as Calibur passes its hash.
+- **Result**: the fields of webauthn-sol's `WebAuthnAuth`. `r` and `s` are 32 bytes big-endian, `s` normalised to low-s (webauthn-sol refuses `s > n/2`). `clientDataJSON` is a string; `typeIndex` and `challengeIndex` are the UTF-8 byte offsets of `"type":"webauthn.get"` and `"challenge":"<base64url(challenge), unpadded>"` in it. The signature is verified against `x`/`y` before it is returned; anything a verifier would refuse throws instead.
+
+| Signing mode                                   | Descriptor                                                                                                        |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Default (passkey DID), hardware P-256 (varsig) | yes: the DID encodes the same key                                                                                 |
+| 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
@@ -329,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.
@@ -345,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`
@@ -393,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

@@ -77,6 +77,7 @@ Returns a credential info object containing:
 - `credentialId`
 - `rawCredentialId`
 - `publicKey`
+- `rpId` (the relying party the credential is registered under)
 - `userId`
 - `displayName`
 - `attestationObject`
@@ -105,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
@@ -164,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
 
@@ -186,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
@@ -199,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
 
@@ -215,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
 
@@ -346,7 +545,31 @@ 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
+
+For smart accounts that verify P-256 WebAuthn signatures (for example Calibur
+with webauthn-sol). See the README section "Passkeys for smart accounts".
+
+- `getP256CredentialDescriptor(credential)` →
+  `{ credentialId, rawCredentialId, x, y, rpId, userVerification: 'required' }`
+  or `null` (RS256, Ed25519, placeholder or unreadable key). `x` and `y` are
+  32-byte big-endian `Uint8Array`s.
+- `signP256Challenge(descriptor, challenge)` → `Promise` of
+  `{ authenticatorData, clientDataJSON, challengeIndex, typeIndex, r, s }`.
+  `challenge` must be exactly 32 bytes. `allowCredentials` is pinned to the
+  descriptor, user verification is required, an assertion from another
+  credential is refused. `r` and `s` are 32 bytes with `s` low; the indices
+  are UTF-8 byte offsets in `clientDataJSON`.
 
 ### Worker Keystore Client
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-identity-provider-webauthn-did",
-  "version": "0.7.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,