@le-space/orbitdb-identity-provider-webauthn-did 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,115 @@
 
 ## Unreleased
 
+## 0.5.1
+
+### Fixed
+
+- The WebAuthn user handle is 64 random bytes instead of the UTF-8 of whatever
+  the caller passes as `userId`. An authenticator keeps one discoverable
+  credential per `(rp.id, user.id)` and **replaces** the previous one when both
+  match — silently, with no prompt and nothing to undo. Deriving the handle from
+  a typed name therefore meant two people registering as "anna" on a shared
+  device destroyed each other's passkey, and with it the DID and every entry
+  signed under it. The same happened to one person re-entering their usual name
+  after clearing storage. WebAuthn L2 §5.4.3 also forbids putting personally
+  identifying information in the handle, which a name or e-mail plainly is, and
+  the handle is stored in the authenticator indefinitely.
+
+  `userId` keeps its rightful place as `user.name`, the label the credential
+  picker shows. It is a label only: it identifies nothing, two credentials may
+  carry the same one, and nothing in this package looks a credential up by it.
+  Closes #45.
+
+  Nothing needs migrating. Recovery goes through discoverable credentials
+  (`readLargeBlobMetadata` calls `get()` with no `allowCredentials`), or through
+  an explicit credential ID where those are switched off — no path resolves a
+  credential by handle, so credentials registered under the old scheme keep
+  working untouched. The derived `did:key` comes from the credential's public
+  key and does not change.
+
+  Consumers should expect a behavioural difference: re-registering under a name
+  that was used before now **adds** a passkey instead of replacing one. That is
+  the point — a replaced passkey is data loss, a second entry is a choice — but
+  it means the picker can show several, so `user.name` and `displayName` should
+  be distinguishing enough to pick from. The new random handle is returned as
+  `credential.userHandle` (base64url); the authenticator keeps its own copy, so
+  storing it is optional.
+
+- Actually write the secret key into `largeBlob`. The keystore record carried
+  `secretKey: sk, // Will be moved to largeBlob` — and nothing ever moved it.
+  That was the only occurrence of the field in `src/`, and
+  `storeEncryptedKeystore()` serialises a fixed whitelist that does not include
+  it, so the key was dropped at persist time. Choosing largeBlob therefore
+  produced a keystore that worked for the session that created it and could
+  never be unlocked again: on the next load `retrieveSKFromLargeBlob()` read a
+  blob nobody had written and failed with "No largeBlob data found in
+  credential".
+
+  The key never reached disk in the clear — the whitelist saw to that — but the
+  feature was inert. `writeSKToLargeBlob()` now performs the assertion that
+  stores it (a blob can only be written during an assertion, never at
+  registration, so this costs one extra prompt) and **throws unless the
+  authenticator reports `written: true`**. Failing there beats persisting a
+  record that cannot be opened.
+
+- Carry the authenticator's own answer on the credential. `createCredential()`
+  now records `extensionSupport` — what the authenticator agreed to during the
+  ceremony — because the raw `PublicKeyCredential` does not survive past that
+  function, so the answer is read there or lost. Client support is not
+  authenticator support: measured on a macOS platform authenticator in Brave,
+  the client advertises `hmacCreateSecret` while the authenticator refuses it
+  and PRF works. Reading only the client is what left the demo offering
+  hmac-secret and then failing at the ceremony, which is the failure originally
+  reported in #9.
+
+  The encrypted-keystore demo consumes it: methods the authenticator refused
+  read "Browser yes, this passkey no" rather than "Supported", become
+  unselectable, and a selection it cannot honour falls back automatically. It
+  also no longer logs `encrypted: Yes (largeBlob)` off the back of the
+  _requested_ options — that line reported intent as though it were outcome, so
+  a failed write looked identical to a successful one. It now names the request
+  and the authenticator's capability separately, so a mismatch is visible.
+
+- Detect WebAuthn extensions by asking the browser instead of inspecting a
+  prototype. `checkExtensionSupport()` tested
+  `'largeBlob' in PublicKeyCredential.prototype` — but extensions are never
+  properties of that interface, they arrive through
+  `getClientExtensionResults()`. The test therefore returned `false` in every
+  browser ever shipped, including those with complete support, and `hmacSecret`
+  was hard-coded `false` beside it. Both together meant the encrypted-keystore
+  demo disabled its own headline feature everywhere and could not be switched
+  on at all.
+
+  Measured on Chrome 148: the prototype probe answered `false` for `largeBlob`,
+  `prf` and `hmacCreateSecret` while `getClientCapabilities()` reported all
+  three `true`. Every extension name behaves the same way, so no browser could
+  ever have passed. Closes #9.
+
+  `checkExtensionSupport()` now reads `getClientCapabilities()` and reports
+  `prf` alongside the other two. It also returns `known`, distinguishing "the
+  browser says no" from "the browser cannot say" — callers must not treat the
+  second as a refusal, or they disable a feature that may well work.
+
+### Added
+
+- `extensionSupportFromCredential(credential)` reads what the authenticator
+  actually agreed to, from the registration response. This is the authoritative
+  answer and the one worth persisting: a browser may support `largeBlob` while
+  the security key in front of it does not, and only the ceremony settles that.
+  `addLargeBlobToCredentialOptions()` takes an optional support level for the
+  same reason — it stays `'required'` by default, because under `'preferred'`
+  an unsupported authenticator yields a credential whose secret was silently
+  never written.
+
+### Changed
+
+- The encrypted-keystore demo offers PRF as a keystore encryption method and
+  prefers it, matching the library's own default since 0.4.0. It had hard-coded
+  `largeBlob`, so it overrode that default and never exercised PRF at all.
+  Methods the browser cannot vouch for are now labelled "Unknown" rather than
+  "Not supported", and stay selectable.
+
 ## 0.5.0
 
 ### Breaking

package/README.md

@@ -290,6 +290,27 @@ Mermaid sequences for scripts:
 - `SECURITY.md`
 - `CODE_OF_CONDUCT.md`
 
+## Cross-Project Verification
+
+This repo's own suite covers the units and runs two OrbitDB peers in-process. The strongest evidence that a release actually works, though, comes from outside it: the replication mode matrix in [`orbitdb-relay`](https://github.com/NiKrause/orbitdb-relay), at `mocha/relay-replication-mode-matrix.mjs`.
+
+It drives six alice/bob pairings through a real relay:
+
+| Mode                                          | Pairing                                    |
+| --------------------------------------------- | ------------------------------------------ |
+| `alice-worker-bob-hardware-ed25519`           | worker keystore ↔ hardware Ed25519         |
+| `alice-worker-bob-hardware-p256`              | worker keystore ↔ hardware P-256           |
+| `alice-hardware-ed25519-bob-hardware-p256`    | the two hardware curves against each other |
+| `alice-worker-ed25519-bob-worker-ed25519`     | worker keystore, both sides                |
+| `alice-hardware-ed25519-bob-hardware-ed25519` | hardware Ed25519, both sides               |
+| `alice-hardware-p256-bob-hardware-p256`       | hardware P-256, both sides                 |
+
+Three things make it worth more than an in-repo test. It runs **out of process and across repos**, against the published package rather than the working tree. It exercises **identity verification between two distinct peers** — different keystores, different identity documents — instead of one instance talking to itself. And the relay **verifies identities itself**, so a third independent verifier sits in the path.
+
+That is exactly the surface a change to the signing format breaks. The 0.5.0 signing-context change was validated here before the consumers moved: all six pairings replicate under the new format.
+
+If you change anything that touches signing, identity documents or verification, run that matrix — not just this repo's tests.
+
 ## Identity Recovery Summary
 
 Current identity recovery behavior in this repo:

package/package.json

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

@@ -277,6 +277,7 @@ export {
   decryptWithAESGCM,
   addLargeBlobToCredentialOptions,
   addPRFToCredentialOptions,
+  writeSKToLargeBlob,
   retrieveSKFromLargeBlob,
   addHmacSecretToCredentialOptions,
   wrapSKWithPRF,
@@ -287,6 +288,7 @@ export {
   loadEncryptedKeystore,
   clearEncryptedKeystore,
   checkExtensionSupport,
+  extensionSupportFromCredential,
 } from './keystore/encryption.js';
 
 export default {

package/src/keystore/encryption.js

@@ -150,19 +150,37 @@ export async function decryptWithAESGCM(ciphertext, sk, iv) {
 
 /**
  * Store secret key in WebAuthn credential using largeBlob extension
+ *
+ * Defaults to `support: 'required'` so an authenticator that cannot hold a
+ * blob fails the ceremony outright. That is the safe default here: under
+ * `'preferred'` the credential is created successfully and the secret is
+ * simply never written, which loses the keystore silently.
+ *
+ * Pass `'preferred'` only when the caller reads the outcome back with
+ * {@link extensionSupportFromCredential} and handles an unsupported
+ * authenticator itself — probing for capability, for instance.
+ *
  * @param {Object} credentialOptions - WebAuthn credential creation options
  * @param {Uint8Array} sk - Secret key to store
- * @returns {Promise<Object>} Enhanced credential options with largeBlob
+ * @param {'required'|'preferred'} [support] - largeBlob support level
+ * @returns {Object} Enhanced credential options with largeBlob
  */
-export function addLargeBlobToCredentialOptions(credentialOptions, sk) {
-  log('Adding largeBlob extension to credential options');
+export function addLargeBlobToCredentialOptions(
+  credentialOptions,
+  sk,
+  support = 'required'
+) {
+  log(
+    'Adding largeBlob extension to credential options (support: %s)',
+    support
+  );
 
   return {
     ...credentialOptions,
     extensions: {
       ...credentialOptions.extensions,
       largeBlob: {
-        support: 'required',
+        support,
         write: sk,
       },
     },
@@ -195,6 +213,67 @@ export function addPRFToCredentialOptions(
   };
 }
 
+/**
+ * Write the secret key into the credential's largeBlob.
+ *
+ * A blob can only be written during an assertion, never at registration — so
+ * this costs one extra WebAuthn prompt after the credential exists. That is
+ * why `addLargeBlobToCredentialOptions()` alone does not persist anything.
+ *
+ * Throws unless the authenticator reports `written: true`. Silence here would
+ * leave a keystore whose key exists only in memory: it works for the current
+ * session and can never be unlocked again, because
+ * {@link retrieveSKFromLargeBlob} would read a blob nobody wrote.
+ *
+ * @param {Uint8Array} credentialId - WebAuthn credential ID (raw bytes).
+ * @param {Uint8Array} sk - Secret key to store.
+ * @param {string} rpId - Relying party ID (domain).
+ * @returns {Promise<void>}
+ */
+export async function writeSKToLargeBlob(credentialId, sk, rpId) {
+  log('Writing secret key to largeBlob');
+
+  let assertion;
+  try {
+    assertion = await navigator.credentials.get(
+      buildCredentialRequestOptions({
+        challenge: crypto.getRandomValues(new Uint8Array(32)),
+        credentialId,
+        rpId,
+        userVerification: 'required',
+        extensions: {
+          largeBlob: {
+            write: sk,
+          },
+        },
+      })
+    );
+  } catch (error) {
+    log.error('largeBlob write assertion failed: %s', error.message);
+    throw new KeystoreEncryptionError(
+      `Failed to write secret key to largeBlob: ${error.message}`,
+      { cause: error }
+    );
+  }
+
+  // The authenticator answers whether it took the blob. Accepting the
+  // assertion without reading this is how a write that never happened passes
+  // for a success.
+  const written = assertion?.getClientExtensionResults?.()?.largeBlob?.written;
+
+  if (written !== true) {
+    log.error(
+      'Authenticator did not write the largeBlob (written: %o)',
+      written
+    );
+    throw new KeystoreEncryptionError(
+      'Authenticator did not store the secret key in largeBlob'
+    );
+  }
+
+  log('Secret key written to largeBlob');
+}
+
 /**
  * Retrieve secret key from WebAuthn credential using largeBlob extension
  * @param {Uint8Array} credentialId - WebAuthn credential ID
@@ -620,39 +699,95 @@ export async function clearEncryptedKeystore(credentialId) {
 }
 
 /**
- * Check if browser supports WebAuthn extensions
- * @returns {Promise<Object>} Support status for largeBlob and hmac-secret
+ * Which WebAuthn extensions is this *client* willing to negotiate?
+ *
+ * Answers one question only: would the browser pass the extension through. It
+ * cannot tell you whether the authenticator behind it will honour the request —
+ * that is settled during a ceremony, by
+ * {@link extensionSupportFromCredential}, and belongs to the credential rather
+ * than to the browser.
+ *
+ * `known: false` means the browser is too old to say. That is **not** the same
+ * as unsupported: callers should attempt the ceremony and let its result
+ * decide, rather than disabling the feature outright.
+ *
+ * @returns {Promise<{largeBlob: boolean, prf: boolean, hmacSecret: boolean, known: boolean}>}
  */
 export async function checkExtensionSupport() {
   const support = {
     largeBlob: false,
+    prf: false,
     hmacSecret: false,
+    known: false,
   };
 
-  if (!window.PublicKeyCredential) {
+  if (typeof globalThis.PublicKeyCredential !== 'function') {
     return support;
   }
 
-  try {
-    // Check largeBlob support
-    if (
-      window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable
-    ) {
-      const available =
-        await window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
-      // largeBlob is available in Chrome 106+, Edge 106+
-      support.largeBlob =
-        available && 'largeBlob' in PublicKeyCredential.prototype;
-    }
+  // getClientCapabilities is the only pre-flight answer that means anything.
+  // The previous check asked `'largeBlob' in PublicKeyCredential.prototype`,
+  // which tests whether the extension is a property of the credential
+  // interface. Extensions never are — they arrive through
+  // getClientExtensionResults() — so it returned false in every browser ever
+  // shipped, including those with complete support, and silently disabled
+  // keystore encryption everywhere.
+  if (typeof PublicKeyCredential.getClientCapabilities !== 'function') {
+    log('getClientCapabilities unavailable; extension support is unknown');
+    return support;
+  }
 
-    // hmac-secret support cannot be reliably detected without a real credential.
-    // Keep it false by default and let users opt-in explicitly.
-    support.hmacSecret = false;
+  try {
+    const capabilities = await PublicKeyCredential.getClientCapabilities();
+    return {
+      largeBlob: capabilities['extension:largeBlob'] === true,
+      prf: capabilities['extension:prf'] === true,
+      hmacSecret: capabilities['extension:hmacCreateSecret'] === true,
+      known: true,
+    };
   } catch (error) {
     log.error('Failed to check extension support: %s', error.message);
+    return support;
+  }
+}
+
+/**
+ * What did the authenticator actually agree to, for this credential?
+ *
+ * The authoritative answer, and the only one worth persisting: a browser may
+ * support largeBlob while the security key in front of it does not. Read this
+ * from the registration response and store it next to the credential.
+ *
+ * Requires the ceremony to have asked with `support: 'preferred'` — see
+ * {@link addLargeBlobToCredentialOptions}. Asking with `'required'` makes
+ * creation fail outright instead of reporting back.
+ *
+ * @param {PublicKeyCredential} credential - The result of navigator.credentials.create().
+ * @returns {{largeBlob: boolean, prf: boolean, hmacSecret: boolean}}
+ */
+export function extensionSupportFromCredential(credential) {
+  const support = { largeBlob: false, prf: false, hmacSecret: false };
+
+  if (typeof credential?.getClientExtensionResults !== 'function') {
+    return support;
   }
 
-  return support;
+  try {
+    const results = credential.getClientExtensionResults() ?? {};
+    return {
+      largeBlob: results.largeBlob?.supported === true,
+      // PRF reports either an explicit `enabled` flag or, when the ceremony
+      // evaluated a salt straight away, the results themselves.
+      prf: results.prf?.enabled === true || results.prf?.results != null,
+      hmacSecret: results.hmacCreateSecret === true,
+    };
+  } catch (error) {
+    log.error(
+      'Failed to read extension results from credential: %s',
+      error.message
+    );
+    return support;
+  }
 }
 
 export default {
@@ -660,6 +795,7 @@ export default {
   encryptWithAESGCM,
   decryptWithAESGCM,
   addLargeBlobToCredentialOptions,
+  writeSKToLargeBlob,
   retrieveSKFromLargeBlob,
   addHmacSecretToCredentialOptions,
   wrapSKWithHmacSecret,
@@ -668,4 +804,5 @@ export default {
   loadEncryptedKeystore,
   clearEncryptedKeystore,
   checkExtensionSupport,
+  extensionSupportFromCredential,
 };

package/src/keystore/provider.js

@@ -408,15 +408,24 @@ export class OrbitDBWebAuthnIdentityProvider {
       } else if (
         this.keystoreEncryptionMethod === KEYSTORE_ENCRYPTION_METHODS.LARGE_BLOB
       ) {
-        // For largeBlob, we need to store SK during next authentication
-        // Store it temporarily for wrapping
+        // Write the key into the authenticator before recording anything.
+        // This used to be `secretKey: sk, // Will be moved to largeBlob` — and
+        // nothing ever moved it: the field was dropped at serialization, so
+        // the key survived only in memory and the keystore could never be
+        // unlocked again. Throws if the authenticator refuses, which is better
+        // than persisting a record that cannot be opened.
+        await KeystoreEncryption.writeSKToLargeBlob(
+          this.credential.rawCredentialId,
+          sk,
+          window.location.hostname
+        );
+
         encryptedData = {
           ciphertext,
           iv,
           credentialId: this.credential.credentialId,
           publicKey: publicKeyBytes,
           keyType,
-          secretKey: sk, // Will be moved to largeBlob
           encryptionMethod: KEYSTORE_ENCRYPTION_METHODS.LARGE_BLOB,
         };
       } else if (

package/src/webauthn/provider.js

@@ -82,7 +82,11 @@ export class WebAuthnDIDProvider {
    * Create a WebAuthn credential for OrbitDB identity
    * This triggers biometric authentication (Face ID, Touch ID, Windows Hello, etc.)
    * @param {Object} options - Credential options
-   * @param {string} options.userId - User ID
+   * @param {string} options.userId - Account label shown in the credential
+   *   picker (`user.name`). A label only: it does not identify the credential,
+   *   two credentials may carry the same one, and it is never used to look one
+   *   up. The handle the authenticator files the credential under is generated
+   *   here and returned as `userHandle`.
    * @param {string} options.displayName - Display name
    * @param {string} options.domain - Domain/RP ID
    * @param {boolean} options.encryptKeystore - Enable keystore encryption
@@ -117,7 +121,19 @@ export class WebAuthnDIDProvider {
 
     // Generate challenge for credential creation
     const challenge = crypto.getRandomValues(new Uint8Array(32));
-    const userIdBytes = new TextEncoder().encode(userId);
+
+    // The user handle is an opaque key, not a label. An authenticator stores
+    // one discoverable credential per (rp.id, user.id) pair and *replaces* the
+    // previous one when both match — silently, with no prompt and nothing to
+    // undo. Deriving the handle from a typed name therefore meant two people
+    // registering as "anna" on a shared device destroyed each other's passkey,
+    // and with it the DID and everything written under it (#45).
+    //
+    // 64 random bytes, as WebAuthn L2 §5.4.3 recommends. The same section
+    // forbids putting personally identifying information here, which a typed
+    // name or e-mail address plainly is. The name keeps its rightful place in
+    // `user.name` below, where the credential picker shows it.
+    const userHandle = crypto.getRandomValues(new Uint8Array(64));
 
     webauthnLog('Calling navigator.credentials.create() for user: %s', userId);
 
@@ -130,7 +146,7 @@ export class WebAuthnDIDProvider {
           id: domain,
         },
         user: {
-          id: userIdBytes,
+          id: userHandle,
           name: userId,
           displayName,
         },
@@ -228,6 +244,17 @@ export class WebAuthnDIDProvider {
         hasY: !!publicKey.y,
       });
 
+      // What the authenticator actually agreed to, as opposed to what the
+      // browser said it could negotiate. Only the ceremony settles this, and
+      // the raw PublicKeyCredential does not survive past this function — so
+      // read it here or lose the answer. Callers that offer a choice of
+      // keystore encryption method need it: a client can support largeBlob
+      // while the key in front of it does not.
+      const extensionSupport =
+        KeystoreEncryption.extensionSupportFromCredential(credential);
+
+      webauthnLog('Authenticator extension support: %o', extensionSupport);
+
       const result = {
         credentialId: WebAuthnDIDProvider.arrayBufferToBase64url(
           credential.rawId
@@ -236,10 +263,18 @@ export class WebAuthnDIDProvider {
         publicKey,
         userId,
         displayName,
+        // Nothing in this package looks a credential up by handle — recovery
+        // goes through discoverable credentials, or through an explicit
+        // credential ID when those are switched off. It is surfaced anyway
+        // because it is the only copy the caller will ever see, and a flow
+        // that one day passes `allowCredentials` needs it. Decode with
+        // `WebAuthnDIDProvider.base64urlToArrayBuffer()`.
+        userHandle: WebAuthnDIDProvider.arrayBufferToBase64url(userHandle),
         attestationObject: new Uint8Array(
           credential.response.attestationObject
         ),
         prfInput: prfInput || undefined,
+        extensionSupport,
       };
 
       webauthnLog('Credential creation completed successfully');

package/types/index.d.ts

@@ -91,6 +91,8 @@ export interface WebAuthnCredentialInfo {
   publicKey: WebAuthnPublicKey | Uint8Array;
   userId?: string;
   displayName?: string;
+  /** Random 64-byte WebAuthn user handle, base64url. Not derived from userId. */
+  userHandle?: string;
   attestationObject?: Uint8Array;
   prfInput?: Uint8Array;
   did?: string;
@@ -99,6 +101,7 @@ export interface WebAuthnCredentialInfo {
 }
 
 export interface CreateCredentialOptions {
+  /** Account label for the credential picker. Not an identifier. */
   userId?: string;
   displayName?: string;
   domain?: string;