@le-space/orbitdb-identity-provider-webauthn-did 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,213 @@
 # Changes
 
-## Unreleased
+## 0.6.0
+
+An identity can be restored on a second device with **nothing stored**: two
+touches of the same passkey give back the DID and the signing key, so
+largeBlob and `localStorage` become a convenience rather than the only road.
+Measured on two phones with one YubiKey before it was written (#61).
+
+Nothing existing moves: a credential registered before this keeps the PRF
+input it was made with, and the identity it derives is unchanged. Credentials
+registered from here on are asked the input every device can compute, which is
+what makes the restore work. Two behaviours do change — `getPrfOutput()` now
+falls back to that derivable input instead of returning `null` when a
+credential has none stored, and `createDID()` throws instead of inventing a
+"base58-like" identifier when it cannot encode a key.
+
+### Added
+
+- **An identity can be restored on a device that has stored nothing** (#61).
+  `restoreIdentityFromAuthenticator()` touches the same passkey twice: once
+  with user verification and the PRF input every device can compute, once for a
+  second signature. Two ECDSA signatures admit exactly one common public key —
+  which an assertion does not carry, and which is why the identity metadata has
+  had to live in largeBlob or `localStorage` until now. From it: the DID, and
+  the signing key derived from the PRF output with the DID mixed in. The pieces
+  are exported on their own as well: `prfInputForRelyingParty()`,
+  `recoverPublicKey()` and `recoverPublicKeyCandidates()`.
+
+  Measured on hardware before it was written — one YubiKey, a Galaxy Fold 5 and
+  a Galaxy A57, 2026-09-19: the same PRF value on both phones, the same DID
+  recovered from two signatures, the same derived signing key. What of that is
+  machine-checkable runs in `tests/webauthn-recovery.test.js`, against a
+  software authenticator with a real P-256 key.
+
+  Nothing stands in for a missing PRF: an authenticator without it gets a
+  refusal, because an identity derived from something else is a different
+  identity that looks like success.
+
+### Changed
+
+- **The PRF input is now fixed per relying party** instead of drawn at random
+  per credential (#61). It was stored with the credential metadata, so the
+  derived signing key — and with it the identity — was reachable only from the
+  device that kept that metadata; a second device asking the same authenticator
+  a different question got a different answer. The input is not a secret, the
+  output is. Credentials registered earlier keep working: their stored input is
+  still used when there is one, and `getPrfOutput()` now falls back to the
+  derivable input instead of giving up when there is none.
+- **`createDID` refuses a key it cannot encode.** Its `catch` built a
+  "base58-like" identifier out of the same coordinates: a string that looked
+  like a DID, was not `did:key`, and could not be reproduced by anything else
+  reading that key — including this library on another device. It throws now.
+
+### Changed
+
+- CI now runs all 22 test files. Eight never ran there: `identity-forgery`,
+  `p256-signature-shapes`, `session-keystore`, `webauthn-debug-log`,
+  `webauthn-extension-support`, `webauthn-user-handle`,
+  `webauthn-varsig-challenge` and `worker-signer`. They were listed in
+  `playwright.node.config.js`, which only the local `preversion` and
+  `prepublishOnly` hooks ran, while `release.yml` publishes with
+  `--ignore-scripts` because CI is its gate — so no automated gate ran them
+  before a release. CI now runs that config in one step, before installing
+  browsers; `standalone-toolkit`, `webauthn-attestation-parsing` and
+  `webauthn-two-peer-replication` lose their separate steps, which booted a
+  demo server they do not use.
+- `identity-forgery` did not load in a clean install. It imported `concat`
+  from `uint8arrays`, which this package does not declare; only a hoisted
+  `node_modules` (`node-linker=hoisted`) made it resolvable. It now takes
+  `concat` from `iso-base/utils`, a declared dependency.
+- `scripts/check-ci-runs-every-test.mjs` fails CI when a file in `tests/` is
+  selected by no step. This is the second time suites went unrun: 0.4.0 found
+  five.
+
+## 0.5.4
+
+Fixes a verification bug that refused about one P-256 passkey identity in
+128 at every peer, since 0.5.2 (see _Fixed_). Upgrade if you use P-256
+passkeys, which is most platform authenticators.
+
+**Upgrade note.** `encryptKeystore` no longer falls back to the credential
+id when the authenticator has no PRF: `wrapSKWithPRF`/`unwrapSKWithPRF`
+throw `PrfUnavailableError`, and `extractPrfSeedFromCredential` returns
+`{ seed: null, source: 'none' }`. The credential id sits in localStorage in
+clear, so a key sealed that way was never sealed. An app that used
+`encryptKeystore` with users whose authenticator has no PRF cannot unseal
+their old key; those users get a fresh keystore DID. The default path and
+varsig are unaffected.
+
+### Added
+
+- `signer` option and `createSessionKeystore({ signer })`: a key that signs
+  elsewhere — typically a Web Worker — becomes the identity. The keystore
+  answers for the signer's DID with a key object whose `sign()` calls the
+  signer, OrbitDB signs through it, and no private key exists in the page.
+  From the standalone toolkit, `client.deriveSigner(prfSeed)` derives an
+  Ed25519 key from the passkey's PRF output inside the worker and returns
+  only its DID and public key; `createWorkerSigner(client, { did, publicKey })`
+  turns that into the signer.
+- `createSessionKeystore()`: an OrbitDB keystore on memory storage. OrbitDB
+  signs with whatever its keystore returns, and the default keystore writes
+  every key to disk — so with `encryptKeystore` the unlocked key was sitting
+  in IndexedDB unencrypted, and the sealed copy protected nothing after the
+  first session. Hand this keystore to `Identities()` and the unlocked key
+  lives in memory only; the provider warns when it is given any other.
+- `provider.encryptionState`: `{ enabled, method | reason }`, so an app can
+  show whether the key is actually sealed.
+
+### Changed
+
+- **No PRF, no seal.** When the authenticator returns no PRF output,
+  `wrapSKWithPRF`/`unwrapSKWithPRF` throw `PrfUnavailableError` and
+  `extractPrfSeedFromCredential` returns `{ seed: null, source: 'none' }`.
+  They used to fall back to the raw credential id, which sits in
+  localStorage in clear, so a key "wrapped with PRF" could be wrapped with
+  nothing secret. The provider carries on without encryption in that case
+  (`encryptionState.reason === 'prf-unavailable'`) and warns. Anything that
+  relied on the `'credentialId'` source has to decide for itself now.
+- A varsig identity's id is always derived from its public key.
+  `createWebAuthnVarsigIdentity` used to let a stored `credential.did` win,
+  so metadata recovered from largeBlob or localStorage — data anyone with
+  access to either can edit — decided which DID an identity claimed.
+  Verification would then refuse it (0.5.2+), but an app showed the wrong
+  DID first.
+- Both `createCredential` paths register with
+  `largeBlob: { support: 'preferred' }`. Identity metadata is written to
+  largeBlob after registration, and an authenticator only allows that for a
+  credential created asking for it; without this the write was refused and
+  recovery through "Use Existing Passkey" found nothing once localStorage
+  was gone. A `required` set by the largeBlob encryption method stays.
+- The largeBlob identity payload (`createDidLargeBlobPayload`, version 2)
+  carries the credential's `prfInput`. Without it a recovered credential
+  could name its DID but not re-derive its signing key, so a second device
+  got a key of its own — the one thing the derived key exists to prevent.
+  Version 1 payloads still parse.
+- `clearIdentityProofs` is exported from the package root, so an app can
+  forget an identity completely: credential metadata, stored identity
+  assertion, keystore.
+
+### Fixed
+
+- **Genuine P-256 signatures were refused about once in 90.** An
+  authenticator returns an ES256 signature as DER with minimal integers, so r
+  or s can be 31 bytes long. The default path's identity binding unwrapped
+  it with a helper that did not pad them back to 32, so about one passkey
+  identity in 128 failed verification — at every peer, and permanently,
+  because the proof is stored and reused (since 0.5.2). The varsig path had
+  the same unwrap plus a second fault: the raw r‖s went to a verifier that
+  takes DER, and one that started with 0x30 was parsed as DER and refused.
+  Both now leave the conversion to `derToRawSignature`/`verifyP256Signature`
+  from `iso-webauthn-varsig`. Found as a 2% flake in the forgery suite;
+  `tests/p256-signature-shapes.test.js` forces each shape through the mock
+  authenticator's new `signatureShape` option.
+- The `/keystore` subpath exports `PrfUnavailableError`, which its type
+  declarations already promised.
+- Creating an encrypted keystore no longer unlocks it straight afterwards:
+  the pair is already in memory, and the second prompt bought nothing.
+- The static `OrbitDBWebAuthnIdentityProvider.createIdentity` created a new
+  encrypted keystore on every call, replacing the sealed key; it now loads
+  the existing one and creates only when there is none.
+
+### Examples
+
+- One module per option under `examples/shared/lib/options/`
+  (`default-path.js`, `encrypted-keystore.js`, `varsig.js`) builds the
+  identity for that option; the demos import them, and each is covered by
+  the suite that drives its demo. The four scripted examples in
+  `examples/*.js` are gone — none of them ran (Node globals in the browser,
+  browser globals in Node, an import that did not exist), and no test ever
+  executed them.
+- The three demos share one stack (`examples/shared/lib/stack.js`) and one
+  todo store. Each demo prefixes its IndexedDB stores with its own name, so
+  "Reset DB" in one demo no longer wipes the other two on the shared
+  GitHub Pages origin; the varsig demo's reset now waits for the deletes and
+  closes the Level stores first, like the others already did. No more HTTP
+  gateway fallback in the demos.
+- `docs/EXAMPLE-SEQUENCES.md` rewritten around the three options, with the
+  prompt counts the suites assert; `docs/WEBAUTHN-ENCRYPTED-KEYSTORE-INTEGRATION.md`
+  no longer promises what `encryptKeystore` cannot do on the default keystore,
+  and no longer names a `secretKey` option that does not exist.
+- The encrypted-keystore demo gives OrbitDB a session keystore in both of its
+  modes, so its "encrypted at rest" is true, and its worker mode is now the
+  real signer: the key is derived from the passkey inside the worker and
+  OrbitDB signs through it (`createWorkerSigner`, `signer` option). The
+  archive the worker used to hand to the page, the probe panel beside the
+  real signing, and the credential-id fallback are gone; the panel shows the
+  signing backend, what is at rest and the prompt count.
+- The default demo lets you pick the derived key's type (`signingKeyType`),
+  shows the identity document's hash, the key in use and the number of
+  WebAuthn prompts, and splits "Logout" (keeps the passkey metadata) from
+  "Forget identity" (removes everything this device holds). Its own
+  credential store dropped `prfInput`; it uses the library's now.
+- One pnpm workspace for the three demos: one lockfile, one set of
+  dependencies, `examples/shared` for what they share.
+- The "Verified" badge is now the verdict of a real check — entry signature,
+  identity block, DID binding, write list — and each demo carries a panel
+  that runs the same verifier on two forgeries. The old badge compared the
+  database's identity with itself.
+- The varsig demo no longer honours `window.__PLAYWRIGHT__`; its browser
+  test drives the real flow with a virtual authenticator, including
+  recovery from largeBlob.
+- Demo READMEs, the README's option table and SECURITY.md describe what the
+  code does: which key signs, what sits at rest, how many prompts.
+
+### Tests
+
+- The mock authenticator returns DER-encoded P-256 signatures, as
+  authenticators do. Raw r‖s starting with 0x30 (one in 256) was read as
+  DER by the varsig decoder and refused.
 
 ## 0.5.3
 

package/README.md

@@ -11,7 +11,7 @@ This package provides:
 - A keystore helper export (`@le-space/orbitdb-identity-provider-webauthn-did/keystore`) for encrypted keystore utilities and provider wiring.
 - **WebAuthn-Varsig**: No insecure OrbitDB keystore at all. Each entry is signed by WebAuthn (varsig envelope), so keys never leave the authenticator, one Passkey (WebAuthn) prompt per write.
 - **Passkey DID with a derived signing key** (the default): the DID is the credential's own P-256 key, and OrbitDB signs entries with a key derived from the passkey's PRF output (HKDF-SHA256, domain-separated by the DID) — secp256k1 by default, Ed25519 with `signingKeyType: 'Ed25519'`. The same passkey yields the same identity document on every device. That key lives in OrbitDB's keystore and is **not** covered by `encryptKeystore`; without PRF the keystore generates one, which then stays on that device.
-- **Keystore-based DID**: Generates an Ed25519/secp256k1 keystore keypair for OrbitDB signing in browser memory. When `encryptKeystore` is enabled, the private key is encrypted with AES-GCM and only rehydrated in memory after a WebAuthn unlock (PRF, largeBlob, or hmac-secret).
+- **Keystore-based DID**: an Ed25519/secp256k1 key pair in the OrbitDB keystore is the identity and signs entries. With `encryptKeystore` a sealed copy of that key sits in localStorage and the passkey unlocks it once per session (PRF; largeBlob or hmac-secret where supported). The unlocked key then lives in OrbitDB's own keystore — give OrbitDB `createSessionKeystore()` so that copy stays in memory; with the default keystore it is written to IndexedDB unencrypted, and the provider warns. Without PRF nothing is sealed: the key goes in unencrypted and `provider.encryptionState` says so.
 
 ## Current WebAuthn Model
 
@@ -28,10 +28,20 @@ In this repo today, metadata recovery works in two layers:
 
 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.
 
-**Recommendation (security-first):**
+**Which option, and what each one actually gives you:**
 
-- **Best security:** Varsig provider (hardware-backed key for every write).
-- **Best balance:** Keystore provider with WebAuthn-encrypted keystore (fewer prompts, faster writes, key material in memory during session).
+|                                  | Default (passkey DID + derived key)                                                          | Keystore DID + `encryptKeystore`                                                                    | Varsig                                    |
+| -------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| DID                              | the passkey's P-256 key                                                                      | the keystore key (Ed25519/secp256k1)                                                                | the passkey's key                         |
+| Signs an entry                   | a key derived from the passkey's PRF output (secp256k1, or Ed25519 with `signingKeyType`)    | the keystore key, sealed by the passkey and unlocked once per session                               | the passkey, every write                  |
+| Prompts per write                | 0                                                                                            | 0                                                                                                   | 1                                         |
+| Prompts per session              | 0 after the first (the identity assertion is stored)                                         | 1 (unlock)                                                                                          | 2 (identity assertions)                   |
+| Same identity on a second device | yes, given PRF                                                                               | no — a new keystore key, unless the sealed copy travels                                             | yes                                       |
+| At rest in the browser           | the derived key, **unencrypted**, in OrbitDB's keystore                                      | the sealed copy only, **if** OrbitDB gets `createSessionKeystore()`; otherwise the unlocked key too | nothing                                   |
+| Without PRF                      | a generated key, one device only                                                             | not sealed at all (`encryptionState.reason === 'prf-unavailable'`)                                  | unaffected                                |
+| What a peer verifies             | the WebAuthn assertion binding the DID's key to the derived key, then each entry's signature | the DID is the signing key, then each entry's signature                                             | each entry's varsig against the DID's key |
+
+Varsig is the only option with no signing key in JavaScript at all; it costs a prompt per write and binds entries to the origin. The default is the cheapest and moves with the passkey, but leaves a software key on disk. The sealed keystore sits between, and only means something at rest with a session keystore.
 
 Note: WebAuthn varsig support in this repo relies on our forked `@le-space/iso-*` packages of [Hugo Dias iso-repo](https://github.com/hugomrdias/iso-repo/) (notably `@le-space/iso-did` and `@le-space/iso-webauthn-varsig`) to align with the updated varsig flow.
 
@@ -178,50 +188,102 @@ sequenceDiagram
   participant App
   participant WebAuthn
   participant Auth as Authenticator
-  participant KS as OrbitDB Keystore
-  participant Enc as KeystoreEncryption
+  participant Prov as Keystore-DID provider
+  participant LS as localStorage
+  participant KS as OrbitDB keystore
   participant DB as OrbitDB
 
   User->>App: Create credential
-  App->>WebAuthn: create()
+  App->>WebAuthn: create() with PRF and largeBlob requested
   WebAuthn->>Auth: Create passkey
   Auth-->>WebAuthn: Attestation
   WebAuthn-->>App: Credential
 
-  App->>KS: getKey() or add generated Ed25519 key
-  KS-->>App: Keystore keypair
-
-  opt encryptKeystore=true
-    App->>Enc: generateSecretKey()
-    Enc-->>App: sk
-    App->>Enc: encrypt keystore private key (AES-GCM)
-    alt prf
-      App->>WebAuthn: get() with PRF
+  App->>Prov: createIdentity({ useKeystoreDID, encryptKeystore })
+  alt encryptKeystore, first session
+    Prov->>Prov: generateSecretKey() gives sk
+    Prov->>Prov: generateKeyPair() gives a random Ed25519 key
+    Prov->>Prov: AES-GCM encrypt the private key with sk
+    alt prf (the default)
+      Prov->>WebAuthn: get() with PRF
       WebAuthn->>Auth: User verification
-      Auth-->>WebAuthn: PRF output
-      WebAuthn-->>App: PRF bytes
-      App->>Enc: wrap sk with PRF
+      alt PRF output
+        Auth-->>Prov: PRF output
+        Prov->>Prov: wrap sk with a key derived from it
+        Prov->>LS: sealed key, wrapped sk, PRF input
+        Prov->>KS: addKey(did, the unlocked key)
+      else no PRF
+        Auth-->>Prov: no PRF result
+        Note right of Prov: Nothing is sealed. encryptionState is { enabled false, reason prf-unavailable }
+        Prov->>KS: getKey(), or add a generated key
+      end
     else largeBlob
-      App->>WebAuthn: get() with largeBlob write
+      Prov->>WebAuthn: get() with largeBlob write
       WebAuthn->>Auth: User verification
-      Auth-->>WebAuthn: Store sk in largeBlob
-      WebAuthn-->>App: largeBlob stored
+      alt written
+        Auth-->>Prov: written is true
+        Prov->>LS: sealed key, sk kept on the authenticator
+        Prov->>KS: addKey(did, the unlocked key)
+      else not written
+        Auth-->>Prov: written is false
+        Note right of Prov: Throws. Nothing is stored.
+      end
     else hmac-secret
-      App->>WebAuthn: get() with hmac-secret
+      Prov->>WebAuthn: get() with hmac-secret
       WebAuthn->>Auth: User verification
-      Auth-->>WebAuthn: HMAC output
-      WebAuthn-->>App: HMAC bytes
-      App->>Enc: wrap sk with HMAC
+      Auth-->>Prov: HMAC output
+      Prov->>Prov: wrap sk with it
+      Prov->>LS: sealed key, wrapped sk
+      Prov->>KS: addKey(did, the unlocked key)
     end
+  else encryptKeystore with prf, later session
+    Prov->>LS: load the sealed key
+    Prov->>WebAuthn: get() with PRF, the stored input
+    Auth-->>Prov: PRF output
+    Prov->>Prov: unwrap sk, then decrypt the key
+    Prov->>KS: addKey(did, the unlocked key)
+  else not encrypted
+    Prov->>KS: getKey(), or add a generated key
   end
+  Prov-->>App: Identity, DID = did:key of the keystore key
 
+  User->>App: Add entry
   App->>DB: db.put()
-  DB->>KS: sign entry with keystore key
+  DB->>KS: sign entry with the keystore key
   KS-->>DB: Entry signature
 
-  Note over App,KS: Keystore private key is encrypted at rest when `encryptKeystore=true`.
+  Note over App,KS: The sealed copy stays at rest. The unlocked key lives in the OrbitDB keystore, so create it with createSessionKeystore() to keep it in memory.
 ```
 
+OrbitDB signs with whatever its keystore returns, and the default keystore
+persists every key it holds. So `encryptKeystore` needs a keystore that
+forgets:
+
+```js
+import { Identities } from '@orbitdb/core';
+import {
+  OrbitDBWebAuthnIdentityProviderFunction,
+  createSessionKeystore,
+} from '@le-space/orbitdb-identity-provider-webauthn-did';
+
+const keystore = await createSessionKeystore(); // memory only
+const identities = await Identities({ ipfs, keystore });
+const identity = await identities.createIdentity({
+  provider: OrbitDBWebAuthnIdentityProviderFunction({
+    webauthnCredential,
+    useKeystoreDID: true,
+    keystoreKeyType: 'Ed25519',
+    encryptKeystore: true,
+    keystore,
+  }),
+});
+```
+
+Every session unlocks the sealed copy again (one passkey prompt). Without
+PRF the provider does not seal anything — it used to fall back to the
+credential id, which is not a secret — and reports
+`encryptionState: { enabled: false, reason: 'prf-unavailable' }`.
+
 ### Varsig (no keystore)
 
 ```mermaid
@@ -235,24 +297,28 @@ sequenceDiagram
   participant DB as OrbitDB
 
   User->>App: Create credential
-  App->>WebAuthn: create()
+  App->>WebAuthn: create() with largeBlob requested
   WebAuthn->>Auth: Create passkey
   Auth-->>WebAuthn: Attestation
   WebAuthn-->>App: Credential
 
   User->>App: Create varsig identity
-  App->>Var: createIdentity()
-  Var->>WebAuthn: get()
+  App->>Var: createWebAuthnVarsigIdentity({ credential })
+  Var->>Var: id = did:key of the passkey's public key
+  Var->>WebAuthn: get() over the id
   WebAuthn->>Auth: User verification
   Auth-->>WebAuthn: Assertion
-  WebAuthn-->>Var: Assertion
-  Var->>Var: encode varsig envelope
+  WebAuthn-->>Var: Assertion, becomes signatures.id
+  Var->>WebAuthn: get() over publicKey + idSignature
+  WebAuthn->>Auth: User verification
+  Auth-->>WebAuthn: Assertion
+  WebAuthn-->>Var: Assertion, becomes signatures.publicKey
   Var-->>App: Identity
 
   User->>App: Add entry
   App->>DB: db.put()
-  DB->>Var: signIdentity(payload)
-  Var->>WebAuthn: get()
+  DB->>Var: sign(entry)
+  Var->>WebAuthn: get() over the entry
   WebAuthn->>Auth: User verification
   Auth-->>WebAuthn: Assertion
   WebAuthn-->>Var: Assertion
@@ -262,22 +328,28 @@ sequenceDiagram
 
 ## Examples
 
-Svelte demos:
-
-- Live demo directory: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/
-- `examples/ed25519-encrypted-keystore-demo/` - Ed25519 keystore DID; keystore encrypted at rest with WebAuthn (PRF when available, otherwise largeBlob/hmac-secret). Live demo: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/ed25519-encrypted-keystore-demo/
-- `examples/webauthn-varsig-demo/` - Varsig provider with passkey signing for each entry. Includes discoverable credential diagnostics, `Use Existing Passkey`, `largeBlob` varsig metadata recovery, and local fallback recovery. Live demo: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/webauthn-varsig-demo/
-- `examples/webauthn-todo-demo/` - WebAuthn DID (no keystore signing; identity-only). Includes discoverable credential diagnostics, `Use Existing Passkey`, `largeBlob` identity metadata recovery, and local fallback recovery. Live demo: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/webauthn-todo-demo/
-
-Scripted examples:
-
-- `examples/ed25519-keystore-did-example.js` - Keystore DID flow.
-- `examples/encrypted-keystore-example.js` - Keystore encryption flow.
-- `examples/simple-encryption-integration.js` - Keystore + database content encryption.
-
-Mermaid sequences for scripts:
-
-- `docs/EXAMPLE-SEQUENCES.md`
+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
+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.
+
+- `examples/webauthn-todo-demo/` — the default: passkey DID, entries signed by
+  a key derived from the passkey (secp256k1 or Ed25519), no prompt per write.
+  Live: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/webauthn-todo-demo/
+- `examples/ed25519-encrypted-keystore-demo/` — an Ed25519 keystore DID,
+  either sealed by the passkey and unlocked into a session keystore, or
+  signed in a Web Worker that derives the key from the passkey and never
+  hands it to the page. Live:
+  https://le-space.github.io/orbitdb-identity-provider-webauthn-did/ed25519-encrypted-keystore-demo/
+- `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/
+
+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.
 
 ## Documentation
 

package/SECURITY.md

@@ -2,12 +2,16 @@
 
 ## Supported Versions
 
-Security fixes are provided for the current `0.3.x` release line.
+Security fixes are provided for the current `0.5.x` release line.
 
 | Version | Supported |
 | ------- | --------- |
-| 0.3.x   | Yes       |
-| < 0.3   | No        |
+| 0.5.x   | Yes       |
+| < 0.5   | No        |
+
+Every release up to and including 0.5.2 is affected by
+[GHSA-326j-4cc3-4rrg](https://github.com/Le-Space/orbitdb-identity-provider-webauthn-did/security/advisories/GHSA-326j-4cc3-4rrg)
+(identity verification checked shapes, not signatures). Use 0.5.3 or later.
 
 ## Reporting a Vulnerability
 
@@ -35,22 +39,49 @@ This package provides WebAuthn-based identity providers and helper APIs for
 OrbitDB. It handles sensitive identity material and should be reviewed in the
 context of the application that embeds it.
 
+There are three ways to use it, and they protect different things. The
+README carries a table; the short version:
+
 ### Varsig Provider
 
-The varsig provider is the preferred security model when available. Entry
-signing is performed through WebAuthn assertions, so the private key remains
-inside the authenticator and is not exported to application memory.
+The only option with no signing key in JavaScript: every entry is a WebAuthn
+assertion in a varsig envelope, so the private key never leaves the
+authenticator (or the passkey provider — synced passkeys are not
+device-bound). It costs one prompt per write, and entries are bound to the
+origin they were signed on.
+
+### Default: passkey DID with a derived signing key
+
+The DID is the passkey's own P-256 key. OrbitDB entries are signed by a
+software key **derived** from the passkey's PRF output (HKDF-SHA256,
+domain-separated by the DID; secp256k1, or Ed25519 with `signingKeyType`).
+The passkey signs the identity document once, binding its key to the derived
+key; that assertion is stored and reused.
+
+The derived key sits in OrbitDB's keystore, **unencrypted**, in the
+browser's IndexedDB. `encryptKeystore` does not apply to this path. Anyone who
+can read that storage can sign as the DID until the identity is rotated.
+Without PRF the keystore generates a key instead, which stays on one device.
+
+### Keystore Provider (`useKeystoreDID` + `encryptKeystore`)
+
+The DID is a keystore key (Ed25519 or secp256k1). With `encryptKeystore` a
+sealed copy of that key is kept in localStorage, unlocked once per session by
+the passkey (PRF; largeBlob or hmac-secret where supported).
 
-### Keystore Provider
+Two things decide whether that means anything at rest:
 
-The keystore provider can generate browser-side Ed25519 or secp256k1 keys for
-OrbitDB signing. When encrypted keystore mode is enabled, key material is
-encrypted at rest with AES-GCM and unlocked through WebAuthn-supported secret
-recovery mechanisms such as PRF, largeBlob, or hmac-secret.
+- OrbitDB signs with whatever its keystore returns, and its default keystore
+  writes every key to disk. Give `Identities()` the keystore from
+  `createSessionKeystore()` (memory only). With any other keystore the
+  unlocked key lands in IndexedDB unencrypted, and the provider warns.
+- Without PRF output nothing is sealed. The provider used to fall back to
+  the credential id — a value that sits in localStorage in clear — as the
+  wrapping seed; since 0.5.4 it does not, and reports
+  `encryptionState: { enabled: false, reason: 'prf-unavailable' }`.
 
-During an unlocked session, private key material may exist in browser memory.
-Applications with stricter requirements should prefer the varsig provider or
-keep keystore sessions short.
+During an unlocked session the private key is in page memory in every
+option but varsig.
 
 ### Identity Metadata Recovery
 
@@ -70,8 +101,14 @@ as a replacement for authenticator-backed key protection.
 
 - Serve production applications over HTTPS.
 - Configure WebAuthn relying party IDs and origins deliberately.
-- Prefer the varsig provider for hardware-backed signing on every write.
-- Enable encrypted keystore mode if using the keystore provider in production.
+- Prefer the varsig provider where a prompt per write is acceptable; nothing
+  else keeps the signing key out of JavaScript.
+- With the keystore provider, use `encryptKeystore` together with
+  `createSessionKeystore()`, and check `provider.encryptionState` before
+  telling users their key is encrypted.
+- Verify identities and entries the way a peer would (see
+  `examples/shared/lib/verification.js`); a badge that checks nothing is
+  worse than none.
 - Keep dependencies updated and review `npm audit --omit=dev` output before
   production deployments.
 - Do not log private keys, PRF seeds, decrypted keystore archives, or raw secret

package/docs/API.md

@@ -132,7 +132,7 @@ Creates a signer instance from credential metadata.
 ```js
 const provider = new WebAuthnDIDProvider(credential);
 const signature = await provider.sign(new TextEncoder().encode('hello'));
-const valid = await provider.verify(signature);
+const valid = await provider.verify(signature, data, credential.publicKey);
 ```
 
 ### OrbitDB Identity Provider

package/package.json

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

package/src/errors.js

@@ -72,6 +72,20 @@ export class KeystoreEncryptionError extends WebAuthnIdentityError {
   }
 }
 
+/**
+ * The authenticator produced no PRF output. Nothing else can stand in for
+ * it: a key derived from a value anyone can read (the credential id used to
+ * be that stand-in) is not a secret, so callers decide what to do without
+ * PRF instead of getting a "wrapped" key that is not.
+ */
+export class PrfUnavailableError extends KeystoreEncryptionError {
+  constructor(message = 'PRF output unavailable', options) {
+    super(message, options);
+    this.name = 'PrfUnavailableError';
+    this.code = 'PRF_UNAVAILABLE';
+  }
+}
+
 export class VarsigVerificationError extends WebAuthnIdentityError {
   constructor(message, options = {}) {
     super(message, {

package/src/index.js

@@ -291,6 +291,30 @@ export {
   extensionSupportFromCredential,
 } from './keystore/encryption.js';
 
+export { clearIdentityProofs } from './webauthn/identity-proof-store.js';
+export {
+  createSessionKeystore,
+  isSessionKeystore,
+} from './keystore/session-keystore.js';
+export { PrfUnavailableError } 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 {
+  PRF_INPUT_INFO,
+  prfInputForRelyingParty,
+} from './webauthn/prf-input.js';
+export {
+  recoverPublicKey,
+  recoverPublicKeyCandidates,
+} from './webauthn/recovery.js';
+export { restoreIdentityFromAuthenticator } from './webauthn/restore.js';
+// The two halves of it, for a caller that already holds one: a PRF output, or
+// a credential it wants the output for.
+export {
+  deriveSigningKeyBytes,
+  getPrfOutput,
+} from './keystore/derived-signing-key.js';
+
 export default {
   WebAuthnDIDProvider,
   OrbitDBWebAuthnIdentityProvider,