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

package/CHANGELOG.md

@@ -2,6 +2,142 @@
 
 ## Unreleased
 
+## 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
 
 ### Security

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.
 
@@ -219,9 +229,38 @@ sequenceDiagram
   DB->>KS: sign entry with keystore key
   KS-->>DB: Entry signature
 
-  Note over App,KS: Keystore private key is encrypted at rest when `encryptKeystore=true`.
+  Note over App,KS: With `encryptKeystore=true` the sealed copy is at rest; the unlocked key lives in the OrbitDB keystore — make that `createSessionKeystore()` so it stays 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
@@ -262,22 +301,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.5.4",
   "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,13 @@ 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';
+
 export default {
   WebAuthnDIDProvider,
   OrbitDBWebAuthnIdentityProvider,

package/src/keystore/encryption.js

@@ -11,7 +11,7 @@ import {
   CRYPTO_ALGORITHMS,
   KEYSTORE_ENCRYPTION_METHODS,
 } from '../constants.js';
-import { KeystoreEncryptionError } from '../errors.js';
+import { KeystoreEncryptionError, PrfUnavailableError } from '../errors.js';
 
 const log = logger(
   'orbitdb-identity-provider-webauthn-did:keystore-encryption'
@@ -44,25 +44,48 @@ async function deriveKeyFromPrfSeed(prfSeed) {
   return new Uint8Array(bits);
 }
 
-function getPrfSeed(credential, rawCredentialId) {
-  if (credential) {
-    try {
-      const extensions = credential.getClientExtensionResults();
-      const prfResults = extensions?.prf;
-      if (prfResults?.results?.first) {
-        log('Using WebAuthn PRF extension for key derivation');
-        return {
-          seed: new Uint8Array(prfResults.results.first),
-          source: KEYSTORE_ENCRYPTION_METHODS.PRF,
-        };
-      }
-    } catch (error) {
-      log('Error reading PRF extension results: %s', error.message);
+/**
+ * The PRF output of an assertion, or null when there is none.
+ *
+ * This used to fall back to the raw credential id, silently, so a key
+ * "wrapped with PRF" could in fact be wrapped with a value that sits in
+ * localStorage in clear. Without PRF there is no secret to derive from.
+ *
+ * @param {PublicKeyCredential} assertion
+ * @returns {{seed: Uint8Array, source: 'prf'}|null}
+ */
+function getPrfSeed(assertion) {
+  if (!assertion) return null;
+  try {
+    const prfResults = assertion.getClientExtensionResults()?.prf;
+    if (prfResults?.results?.first) {
+      log('Using WebAuthn PRF extension for key derivation');
+      return {
+        seed: new Uint8Array(prfResults.results.first),
+        source: KEYSTORE_ENCRYPTION_METHODS.PRF,
+      };
     }
+  } catch (error) {
+    log('Error reading PRF extension results: %s', error.message);
   }
+  log('PRF extension not available');
+  return null;
+}
 
-  log('PRF extension not available, using rawCredentialId for key derivation');
-  return { seed: rawCredentialId, source: 'credentialId' };
+/**
+ * @param {PublicKeyCredential} assertion
+ * @param {string} verb - For the message: what could not be done.
+ * @returns {{seed: Uint8Array, source: 'prf'}}
+ * @throws {PrfUnavailableError}
+ */
+function getPrfSeedOrThrow(assertion, verb) {
+  const prf = getPrfSeed(assertion);
+  if (!prf) {
+    throw new PrfUnavailableError(
+      `the authenticator returned no PRF output, so the key cannot be ${verb}`
+    );
+  }
+  return prf;
 }
 
 /**
@@ -423,7 +446,7 @@ export async function wrapSKWithPRF(credentialId, sk, rpId, prfInput) {
       })
     );
 
-    const { seed, source } = getPrfSeed(assertion, credentialId);
+    const { seed, source } = getPrfSeedOrThrow(assertion, 'wrapped');
     const prfKey = await deriveKeyFromPrfSeed(seed);
     const wrapped = await encryptWithAESGCM(sk, prfKey);
 
@@ -436,6 +459,7 @@ export async function wrapSKWithPRF(credentialId, sk, rpId, prfInput) {
       prfSource: source,
     };
   } catch (error) {
+    if (error instanceof PrfUnavailableError) throw error;
     log.error('Failed to wrap secret key with PRF: %s', error.message);
     throw new KeystoreEncryptionError(
       `Failed to wrap secret key: ${error.message}`,
@@ -544,13 +568,14 @@ export async function unwrapSKWithPRF(
       })
     );
 
-    const { seed, source } = getPrfSeed(assertion, credentialId);
+    const { seed, source } = getPrfSeedOrThrow(assertion, 'unwrapped');
     const prfKey = await deriveKeyFromPrfSeed(seed);
     const sk = await decryptWithAESGCM(wrappedSK, prfKey, wrappingIV);
 
     log('Secret key unwrapped with PRF (%s)', source);
     return sk;
   } catch (error) {
+    if (error instanceof PrfUnavailableError) throw error;
     log.error('Failed to unwrap secret key with PRF: %s', error.message);
     throw new KeystoreEncryptionError(
       `Failed to unwrap secret key: ${error.message}`,

package/src/keystore/index.js

@@ -4,3 +4,5 @@
 export * from './encryption.js';
 export { default } from './encryption.js';
 export * from './provider.js';
+export * from './session-keystore.js';
+export { PrfUnavailableError } from '../errors.js';