@le-space/orbitdb-identity-provider-webauthn-did 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.4.1
+
+### Added
+
+- Derive the OrbitDB signing key from the passkey PRF output instead of letting
+  the keystore generate a random one. `Identities.createIdentity` takes
+  `keystore.getKey(id) || keystore.createKey(id)`, and `createKey` is random, so
+  the same passkey previously produced a different `publicKey` and
+  `signatures.id` — and therefore a different identity document — on every
+  device. Seeding the keystore during `getId()`, the last point before OrbitDB
+  asks for the key, makes the whole document reproducible: one block to keep
+  retrievable for a DID instead of one per device, and a device that loses its
+  keystore while keeping the passkey reconstructs the same identity rather than
+  minting another. Needs no change to `@orbitdb/core`.
+- `createCredential()` now requests the PRF extension even when the keystore is
+  not encrypted, and stores the input. Without a stored input the output would
+  differ per call, so a credential registered without one can never get a
+  reproducible identity. Requesting it is harmless where unsupported.
+
+### Notes
+
+- Falls back cleanly. No PRF support, no stored input, or a refused assertion
+  leaves the keystore to generate its own key — 0.4.0 behaviour, stable per
+  device but not across devices. Opt out with
+  `deriveSigningKeyFromPrf: false`.
+- An existing keystore key is never replaced. Swapping it under a device that
+  already has history would mint a second document for the DID, which is what
+  this avoids. Installs upgrading from 0.4.0 keep their key; fresh installs get
+  a reproducible identity.
+- Costs one extra assertion the first time an identity is created on a device.
+  The key is persisted, so later loads do not repeat it.
+
 ## 0.4.0
 
 ### Breaking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-identity-provider-webauthn-did",
-  "version": "0.4.0",
+  "version": "0.4.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/keystore/derived-signing-key.js

@@ -0,0 +1,198 @@
+/**
+ * @module DerivedSigningKey
+ * @description
+ * Derives the OrbitDB signing key deterministically from the passkey's PRF
+ * output instead of letting the keystore generate a random one.
+ *
+ * `Identities.createIdentity` in `@orbitdb/core` does:
+ *
+ *     const privateKey = await keystore.getKey(id) || await keystore.createKey(id)
+ *     const publicKey  = keystore.getPublic(privateKey)
+ *     const idSignature = await signMessage(privateKey, id)
+ *
+ * `createKey` generates a random secp256k1 key, so `publicKey` and
+ * `signatures.id` differ on every device even for the same passkey — one
+ * identity document per device. Seeding the keystore with a PRF-derived key
+ * before OrbitDB asks for it makes all of that reproducible: the same passkey
+ * yields the same document everywhere, so there is exactly one block to keep
+ * retrievable and a device that loses its keystore reconstructs the identity
+ * rather than minting another one.
+ *
+ * Needs no change to `@orbitdb/core` — it only has to happen before
+ * `getKey(id)` is called, which `getId()` is.
+ *
+ * See issue #18, option 1.
+ */
+import { logger } from '@libp2p/logger';
+import { privateKeyFromRaw } from '@libp2p/crypto/keys';
+
+import { CRYPTO_ALGORITHMS } from '../constants.js';
+import { buildCredentialRequestOptions } from '../webauthn/config.js';
+
+const log = logger('orbitdb-identity-provider-webauthn-did:derived-key');
+
+// Bumping this rotates every derived key, so treat it as a breaking change.
+const DERIVATION_INFO = 'orbitdb-identity-provider-webauthn-did:signing-key:v1';
+
+const SECP256K1_KEY_BYTES = 32;
+
+/**
+ * HKDF-SHA256 a 32-byte candidate from the PRF seed.
+ * @param {Uint8Array} seed - PRF output.
+ * @param {string} info - Domain separation string.
+ * @returns {Promise<Uint8Array>} 32 bytes.
+ */
+async function hkdf(seed, info) {
+  const baseKey = await crypto.subtle.importKey(
+    'raw',
+    seed,
+    CRYPTO_ALGORITHMS.HKDF,
+    false,
+    ['deriveBits']
+  );
+  const bits = await crypto.subtle.deriveBits(
+    {
+      name: CRYPTO_ALGORITHMS.HKDF,
+      hash: CRYPTO_ALGORITHMS.SHA_256,
+      salt: new Uint8Array(0),
+      info: new TextEncoder().encode(info),
+    },
+    baseKey,
+    SECP256K1_KEY_BYTES * 8
+  );
+  return new Uint8Array(bits);
+}
+
+/**
+ * Turn a PRF seed into a valid secp256k1 private key.
+ *
+ * Values outside the curve order are invalid. That is vanishingly unlikely for
+ * a 256-bit hash, but retrying with a counter keeps the derivation total and
+ * deterministic rather than probabilistic.
+ *
+ * @param {Uint8Array} seed - PRF output.
+ * @param {string} did - Identity DID, mixed in for domain separation.
+ * @returns {Promise<Uint8Array>} A valid 32-byte secp256k1 private key.
+ */
+export async function deriveSigningKeyBytes(seed, did) {
+  for (let counter = 0; counter < 256; counter++) {
+    const candidate = await hkdf(seed, `${DERIVATION_INFO}:${did}:${counter}`);
+    try {
+      privateKeyFromRaw(candidate);
+      return candidate;
+    } catch {
+      log('derived scalar %d was not a valid secp256k1 key, retrying', counter);
+    }
+  }
+  // Unreachable short of a broken hash.
+  throw new Error('could not derive a valid secp256k1 key from the PRF seed');
+}
+
+/**
+ * Ask the authenticator for the credential's PRF output.
+ *
+ * Returns null whenever a stable PRF output cannot be obtained — no stored
+ * PRF input, no PRF support, or a refused assertion. Callers must treat null
+ * as "carry on without a derived key" rather than as an error.
+ *
+ * @param {Object} credential - Stored WebAuthn credential info.
+ * @param {Object} [options]
+ * @param {string} [options.rpId] - Relying party id.
+ * @returns {Promise<Uint8Array|null>} PRF output, or null.
+ */
+export async function getPrfOutput(credential, { rpId } = {}) {
+  // Without the original input the output would differ per call, which is
+  // worse than not deriving at all.
+  if (!credential?.prfInput) {
+    log('credential has no stored prfInput; cannot derive a stable key');
+    return null;
+  }
+
+  if (typeof navigator === 'undefined' || !navigator.credentials?.get) {
+    log('no WebAuthn available; cannot derive a key');
+    return null;
+  }
+
+  const rawCredentialId =
+    credential.rawCredentialId instanceof Uint8Array
+      ? credential.rawCredentialId
+      : new Uint8Array(credential.rawCredentialId ?? []);
+
+  try {
+    const assertion = await navigator.credentials.get(
+      buildCredentialRequestOptions({
+        challenge: await crypto.subtle.digest(
+          CRYPTO_ALGORITHMS.SHA_256,
+          new TextEncoder().encode(DERIVATION_INFO)
+        ),
+        credentialId: rawCredentialId,
+        rpId: rpId ?? globalThis.window?.location?.hostname,
+        userVerification: 'required',
+        extensions: { prf: { eval: { first: credential.prfInput } } },
+      })
+    );
+
+    const results = assertion?.getClientExtensionResults?.()?.prf?.results;
+    if (!results?.first) {
+      log('authenticator returned no PRF output');
+      return null;
+    }
+    return new Uint8Array(results.first);
+  } catch (error) {
+    log('PRF assertion failed: %s', error.message);
+    return null;
+  }
+}
+
+/**
+ * Seed the keystore with a PRF-derived signing key for this DID.
+ *
+ * An existing key is never replaced. Overwriting one would change `publicKey`
+ * and `signatures.id`, producing a second identity document for the same DID —
+ * precisely what this is meant to avoid. Installs that already hold a random
+ * key therefore keep it and stay on 0.4.0 behaviour, which is stable per
+ * device; only fresh installs get a reproducible identity.
+ *
+ * @param {Object} params
+ * @param {Object} params.keystore - OrbitDB keystore.
+ * @param {string} params.did - Identity DID.
+ * @param {Object} params.credential - Stored WebAuthn credential info.
+ * @param {string} [params.rpId] - Relying party id.
+ * @returns {Promise<'derived'|'existing'|'unavailable'>} What happened.
+ */
+export async function ensureDerivedSigningKey({
+  keystore,
+  did,
+  credential,
+  rpId,
+}) {
+  if (!keystore || !did || !credential) return 'unavailable';
+
+  try {
+    if (await keystore.getKey(did)) {
+      log('keystore already holds a key for this DID; leaving it alone');
+      return 'existing';
+    }
+  } catch (error) {
+    log('could not read the keystore: %s', error.message);
+    return 'unavailable';
+  }
+
+  const seed = await getPrfOutput(credential, { rpId });
+  if (!seed) {
+    log(
+      'no PRF output; falling back to a keystore-generated key, so this identity is stable per device but not reproducible across devices'
+    );
+    return 'unavailable';
+  }
+
+  try {
+    const privateKey = await deriveSigningKeyBytes(seed, did);
+    await keystore.addKey(did, { privateKey });
+    log('seeded the keystore with a PRF-derived signing key');
+    return 'derived';
+  } catch (error) {
+    log('failed to seed the derived key: %s', error.message);
+    return 'unavailable';
+  }
+}

package/src/keystore/provider.js

@@ -7,6 +7,7 @@ import { generateKeyPair } from '@libp2p/crypto/keys';
 import { varint } from 'multiformats';
 import { base58btc } from 'multiformats/bases/base58';
 import * as KeystoreEncryption from './encryption.js';
+import { ensureDerivedSigningKey } from './derived-signing-key.js';
 import { WebAuthnDIDProvider } from '../webauthn/provider.js';
 import {
   identityProofKey,
@@ -56,8 +57,12 @@ export class OrbitDBWebAuthnIdentityProvider {
     keystoreKeyType = KEY_TYPES.SECP256K1,
     encryptKeystore = false,
     keystoreEncryptionMethod = KEYSTORE_ENCRYPTION_METHODS.PRF,
+    deriveSigningKeyFromPrf = true,
   }) {
     this.credential = webauthnCredential;
+    // Costs one extra assertion the first time an identity is created on a
+    // device. Set false to keep a keystore-generated key instead.
+    this.deriveSigningKeyFromPrf = deriveSigningKeyFromPrf;
     this.webauthnProvider = new WebAuthnDIDProvider(webauthnCredential);
     this.type = IDENTITY_TYPES.WEBAUTHN; // Set instance property
     this.useKeystoreDID = useKeystoreDID; // Flag to use Ed25519 DID from keystore
@@ -76,7 +81,17 @@ export class OrbitDBWebAuthnIdentityProvider {
    * Resolve the identity DID.
    * @returns {Promise<string>} DID string.
    */
-  async getId() {
+  /**
+   * Resolve the identity DID.
+   *
+   * OrbitDB passes its own keystore in `options` and calls this before
+   * `keystore.getKey(id)`, which is the only window in which the signing key
+   * can be seeded deterministically. See derived-signing-key.js.
+   *
+   * @param {Object} [options] - Options supplied by OrbitDB.
+   * @returns {Promise<string>} DID string.
+   */
+  async getId(options = {}) {
     identityLog('getId() called');
 
     // If useKeystoreDID flag is set, create Ed25519 DID from keystore
@@ -95,6 +110,22 @@ export class OrbitDBWebAuthnIdentityProvider {
 
     // Default: Return P-256 DID from WebAuthn credential
     const did = await WebAuthnDIDProvider.createDID(this.credential);
+
+    // Seed the signing key before OrbitDB reaches for it. Never fatal: without
+    // PRF the keystore generates its own key and the identity stays stable per
+    // device, just not reproducible across them.
+    if (this.deriveSigningKeyFromPrf !== false) {
+      const keystore = options.keystore ?? this.keystore;
+      if (keystore) {
+        const outcome = await ensureDerivedSigningKey({
+          keystore,
+          did,
+          credential: this.credential,
+        });
+        identityLog('Derived signing key: %s', outcome);
+      }
+    }
+
     identityLog(
       'getId() returning P-256 DID: %s',
       did.substring(0, 32) + '...'

package/src/webauthn/provider.js

@@ -199,6 +199,19 @@ export class WebAuthnDIDProvider {
       // Note: largeBlob write happens after credential creation
     }
 
+    // Request PRF even when the keystore is not encrypted. The stored input is
+    // what lets the OrbitDB signing key be derived reproducibly later, so a
+    // credential registered without it can never get a reproducible identity.
+    // Requesting the extension is harmless where it is unsupported: the
+    // authenticator simply returns no PRF results.
+    if (!prfInput) {
+      const prfConfig = KeystoreEncryption.addPRFToCredentialOptions(
+        credentialOptions.publicKey
+      );
+      credentialOptions.publicKey = prfConfig.credentialOptions;
+      prfInput = prfConfig.prfInput;
+    }
+
     try {
       const credential = await navigator.credentials.create(credentialOptions);