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

package/CHANGELOG.md

@@ -1,6 +1,101 @@
 # Changes
 
-## Unreleased
+## 0.7.0
+
+**One breaking change, in the function 0.6.0 added.** `restoreIdentityFromAuthenticator()`
+returned the credential id as bytes, under `credentialId` — the name the rest of this package
+uses for the base64url text. An application that passed the bytes on as `rawCredentialId`, and
+so gave the provider no text, got a third touch of the key and then an exception: `WebAuthn
+signing error: Cannot read properties of undefined (reading 'substring')`. That happened on two
+phones on 21 September, in funkpost's recovery page.
+
+- `credentialId` is now the base64url **text** and `rawCredentialId` the **bytes**, as
+  `WebAuthnCredentialInfo` has always typed them.
+- New: `credential`, the credential the provider takes as it is —
+  `OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential: restored.credential })`.
+- The provider derives either form of the id from the other, so a credential that brings only
+  one of them signs instead of failing after the touch.
+- `sign()` no longer builds a debug line from a field that may be missing.
+
+**Migrating from 0.6.0:** read the bytes from `restored.rawCredentialId` instead of
+`restored.credentialId`, or hand `restored.credential` to the provider.
+
+**Tested now:** the step after the restore — giving the identity to OrbitDB and signing with it
+— which no test reached before. Both new tests fail on 0.6.0, one of them with the exception
+above, word for word.
+
+## 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
 

package/README.md

@@ -188,48 +188,71 @@ 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: 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.
+  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
@@ -274,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
@@ -359,18 +386,22 @@ If you change anything that touches signing, identity documents or verification,
 
 ## Identity Recovery Summary
 
-Current identity recovery behavior in this repo:
+Since **0.6.0** an identity can be restored on a device that has stored nothing:
 
-- Discoverable passkeys are the default.
-- Discoverable authentication can recover the credential ID used for assertion.
-- Discoverable authentication does not reliably re-expose the credential public key.
-- Because of that, OrbitDB identity recovery requires metadata persistence.
-- The demos now try `largeBlob` first for identity metadata recovery.
-- If `largeBlob` is not supported or has no metadata, the demos fall back to local browser storage.
+- Discoverable passkeys are the default, so a device that knows no credential ID can still authenticate.
+- A single assertion does not expose the credential's public key — but **two do**. An ECDSA signature admits exactly two public keys, and only the signer's is in both sets, so `recoverPublicKey()` returns it and the DID follows. Every candidate is checked against the signature it came from, so the recovery cannot invent a key.
+- The PRF input is fixed per relying party, so a second device asks the authenticator the same question and receives the same secret; the signing key is derived from it with the DID mixed in.
+- `restoreIdentityFromAuthenticator()` does both touches and returns the DID, the public key and the signing key — and, since 0.7.0, the credential the provider takes as it is: `OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential: restored.credential })`.
+
+Metadata persistence is therefore a **convenience, not a requirement**. The demos still try `largeBlob` first and fall back to browser storage, which saves a touch of the key; neither is needed to reconstruct the identity.
 
 Practical implication:
 
-- If you create a passkey on one browser profile and later open the app in a fresh profile, the passkey may still exist in the platform passkey manager, but the app can only reconstruct the OrbitDB identity if it can recover metadata from `largeBlob` or some other persisted mapping.
+- A passkey created in one browser profile reconstructs the same OrbitDB identity in a fresh profile — or on another phone — with nothing carried over. Measured on one YubiKey across a Galaxy Fold 5 and a Galaxy A57 (2026-09-19): same PRF value, same recovered DID, same derived signing key.
+- An authenticator without PRF gets a **refusal**, not a substitute. An identity derived from something else is a different identity that looks like success.
+- Credentials registered before 0.6.0 keep the random PRF input stored with them, so their identities do not move.
+
+Getting the _database_ back is a separate problem, and the two halves together are written up in [Getting a database back on a device that has nothing](https://github.com/NiKrause/orbitdb-storage-bridge/blob/main/docs/RECOVERY-ON-A-SECOND-DEVICE.md).
 
 ## Upstream Packages and Temporary Forks
 

package/package.json

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

@@ -297,6 +297,23 @@ export {
   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,

package/src/keystore/derived-signing-key.js

@@ -35,6 +35,7 @@ import {
 
 import { CRYPTO_ALGORITHMS, KEY_TYPES } from '../constants.js';
 import { buildCredentialRequestOptions } from '../webauthn/config.js';
+import { prfInputForRelyingParty } from '../webauthn/prf-input.js';
 
 const log = logger('orbitdb-identity-provider-webauthn-did:derived-key');
 
@@ -126,12 +127,13 @@ export async function deriveSigningKeyBytes(
  * @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;
-  }
+  // A credential registered before #61 carries the random input it was made
+  // with, and that input is the only one its authenticator answers the same
+  // way twice. Without one, fall back to the input every device can compute
+  // (#61): a credential registered since then was asked exactly that, so a
+  // second device needs nothing from the first.
+  const prfInput =
+    credential?.prfInput ?? (await prfInputForRelyingParty(rpId));
 
   if (typeof navigator === 'undefined' || !navigator.credentials?.get) {
     log('no WebAuthn available; cannot derive a key');
@@ -153,7 +155,7 @@ export async function getPrfOutput(credential, { rpId } = {}) {
         credentialId: rawCredentialId,
         rpId: rpId ?? globalThis.window?.location?.hostname,
         userVerification: 'required',
-        extensions: { prf: { eval: { first: credential.prfInput } } },
+        extensions: { prf: { eval: { first: prfInput } } },
       })
     );
 

package/src/webauthn/prf-input.js

@@ -0,0 +1,46 @@
+/**
+ * @module PrfInput
+ * @description
+ * The PRF input an authenticator is asked to evaluate.
+ *
+ * It was drawn at random per credential and stored with the credential's
+ * metadata, which makes the derived signing key — and with it the identity —
+ * reachable only from the device that kept that metadata. A second device
+ * holding the same passkey asks the same authenticator and gets a different
+ * answer, because it asks a different question.
+ *
+ * Fixing the input per relying party removes the question: both devices ask
+ * the same thing, and the authenticator answers the same thing. The input is
+ * not a secret — the *output* is, and it never leaves the authenticator's
+ * answer — so nothing is lost by making it derivable. See issue #61.
+ */
+import { CRYPTO_ALGORITHMS } from '../constants.js';
+
+/**
+ * Bumping this rotates every PRF output, and with it every derived signing
+ * key, so treat it as a breaking change.
+ */
+export const PRF_INPUT_INFO = 'orbitdb-identity-provider-webauthn-did:prf:v2';
+
+/**
+ * The fixed PRF input for a relying party.
+ *
+ * @param {string} rpId - Relying party id, e.g. `example.org`. The current
+ *   host is used when it is omitted and there is one.
+ * @returns {Promise<Uint8Array>} 32 bytes, the same on every device.
+ */
+export async function prfInputForRelyingParty(rpId) {
+  const party =
+    rpId ??
+    (typeof globalThis.location === 'object'
+      ? globalThis.location.hostname
+      : undefined);
+  if (typeof party !== 'string' || party.length === 0) {
+    throw new TypeError('prfInputForRelyingParty needs a relying party id');
+  }
+  const digest = await crypto.subtle.digest(
+    CRYPTO_ALGORITHMS.SHA_256,
+    new TextEncoder().encode(`${PRF_INPUT_INFO}:${party}`)
+  );
+  return new Uint8Array(digest);
+}

package/src/webauthn/provider.js

@@ -16,6 +16,7 @@ import {
   KEYSTORE_ENCRYPTION_METHODS,
 } from '../constants.js';
 import {
+  ERROR_CODES,
   WebAuthnIdentityError,
   WebAuthnAuthenticationError,
   WebAuthnCredentialError,
@@ -26,6 +27,7 @@ import {
   buildCredentialRequestOptions,
 } from './config.js';
 import { logWebAuthnResponse } from './debug-log.js';
+import { prfInputForRelyingParty } from './prf-input.js';
 import {
   p256PublicKeyBytes,
   verifyWebAuthnProof,
@@ -44,9 +46,28 @@ export class WebAuthnDIDProvider {
    * @param {Uint8Array} credentialInfo.rawCredentialId - Raw credential ID bytes.
    */
   constructor(credentialInfo) {
-    this.credentialId = credentialInfo.credentialId;
+    // The id twice, as WebAuthnCredentialInfo types it: text for the signature
+    // envelope, bytes for the authenticator. Either gives the other, so a
+    // credential that brings only its bytes (as 0.6.0's restore handed them
+    // out, under the text's name) still signs, instead of getting through the
+    // touch and then failing.
+    const { credentialId, rawCredentialId } = credentialInfo;
+    this.rawCredentialId =
+      rawCredentialId ??
+      (typeof credentialId === 'string'
+        ? new Uint8Array(
+            WebAuthnDIDProvider.base64urlToArrayBuffer(credentialId)
+          )
+        : credentialId
+          ? new Uint8Array(credentialId)
+          : undefined);
+    this.credentialId =
+      typeof credentialId === 'string'
+        ? credentialId
+        : this.rawCredentialId
+          ? WebAuthnDIDProvider.arrayBufferToBase64url(this.rawCredentialId)
+          : undefined;
     this.publicKey = credentialInfo.publicKey;
-    this.rawCredentialId = credentialInfo.rawCredentialId;
     this.type = IDENTITY_TYPES.WEBAUTHN;
   }
 
@@ -173,7 +194,8 @@ export class WebAuthnDIDProvider {
 
       if (keystoreEncryptionMethod === KEYSTORE_ENCRYPTION_METHODS.PRF) {
         const prfConfig = KeystoreEncryption.addPRFToCredentialOptions(
-          credentialOptions.publicKey
+          credentialOptions.publicKey,
+          await prfInputForRelyingParty(domain)
         );
         credentialOptions.publicKey = prfConfig.credentialOptions;
         prfInput = prfConfig.prfInput;
@@ -199,14 +221,19 @@ export class WebAuthnDIDProvider {
       };
     }
 
-    // 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.
+    // Request PRF even when the keystore is not encrypted: it is what lets the
+    // OrbitDB signing key be derived reproducibly later, so a credential
+    // registered without it can never get a reproducible identity. The input
+    // is fixed per relying party rather than drawn at random (#61), so a
+    // second device asks the authenticator the same question and gets the same
+    // answer — without that, "the same passkey" still means a different key on
+    // every device.
     // 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,
+        await prfInputForRelyingParty(domain)
       );
       credentialOptions.publicKey = prfConfig.credentialOptions;
       prfInput = prfConfig.prfInput;
@@ -581,38 +608,16 @@ export class WebAuthnDIDProvider {
       const multikeyEncoded = base58btc.encode(multikey);
       return `${DID_KEY_PREFIX}${multikeyEncoded}`;
     } catch (error) {
-      console.warn(
-        'Failed to create DID with multiformats, using fallback:',
-        error
+      // No fallback encoding. What stood here invented a "base58-like"
+      // identifier out of the same coordinates — a string that looks like a
+      // DID, is not `did:key`, and cannot be reproduced by anything else that
+      // reads this key, including this library on another device. An identity
+      // nobody else computes the same way is worse than no identity, and it
+      // fails silently, at registration, where nothing checks it again.
+      throw new WebAuthnIdentityError(
+        `could not encode the public key as a did:key: ${error.message}`,
+        { code: ERROR_CODES.INVALID_INPUT, cause: error }
       );
-
-      // Fallback: Simple DID creation without multiformats dependency
-      const { x, y } = credentialInfo.publicKey;
-
-      // Create a hash-based approach for consistency
-      const combined = new Uint8Array(x.length + y.length);
-      combined.set(x, 0);
-      combined.set(y, x.length);
-
-      // Simple base58-like encoding for fallback
-      const base58Chars =
-        '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
-      let encoded = 'z'; // base58btc prefix
-
-      for (let i = 0; i < Math.min(combined.length, 32); i += 4) {
-        const chunk = combined.slice(i, i + 4);
-        let value = 0;
-        for (let j = 0; j < chunk.length; j++) {
-          value = value * 256 + chunk[j];
-        }
-
-        for (let k = 0; k < 6; k++) {
-          encoded += base58Chars[value % 58];
-          value = Math.floor(value / 58);
-        }
-      }
-
-      return `${DID_KEY_PREFIX}${encoded}`;
     }
   }
 
@@ -726,8 +731,9 @@ export class WebAuthnDIDProvider {
       };
 
       webauthnLog('Proof created successfully: %o', {
-        credentialId: webauthnProof.credentialId.substring(0, 16) + '...',
-        dataHash: webauthnProof.dataHash.substring(0, 16) + '...',
+        // A debug line must not be what fails a signature.
+        credentialId: `${String(webauthnProof.credentialId).slice(0, 16)}...`,
+        dataHash: `${String(webauthnProof.dataHash).slice(0, 16)}...`,
       });
 
       // Return the proof as a base64url encoded string for OrbitDB

package/src/webauthn/recovery.js

@@ -0,0 +1,242 @@
+/**
+ * @module Recovery
+ * @description
+ * Get the credential's public key back from assertions, so a device that has
+ * stored nothing can still know which identity it holds.
+ *
+ * A WebAuthn assertion does not carry the public key; only registration does.
+ * That is why the identity metadata has had to be kept somewhere — largeBlob,
+ * localStorage, a proof store — and why a fresh device with the same
+ * authenticator could not name the identity it was holding.
+ *
+ * It does not have to be kept. An ECDSA signature admits exactly two public
+ * keys, and both are computable from the signature itself; a second signature
+ * over a different challenge admits two more, and only the signer's key is in
+ * both sets. So two touches of the same passkey are enough to recover the key,
+ * and from it the DID. See issue #61.
+ *
+ * Every candidate this module returns has been checked against the signature
+ * it came from with `crypto.subtle.verify`. A mistake in the arithmetic below
+ * can therefore cost a candidate, never invent one: what comes out has
+ * verified, or it does not come out.
+ */
+import { derToRawSignature } from 'iso-webauthn-varsig';
+
+import { ERROR_CODES, WebAuthnIdentityError } from '../errors.js';
+import { CRYPTO_ALGORITHMS } from '../constants.js';
+
+// NIST P-256 (secp256r1). a = p - 3.
+const P = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn;
+const N = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n;
+const B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn;
+const G = {
+  x: 0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296n,
+  y: 0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5n,
+};
+const P1363_SIGNATURE_LENGTH = 64;
+const COORDINATE_BYTES = 32;
+
+const mod = (value, modulus = P) => ((value % modulus) + modulus) % modulus;
+
+/** Extended Euclid; `value` must not be a multiple of `modulus`. */
+function inverse(value, modulus) {
+  let [old, current] = [mod(value, modulus), modulus];
+  let [oldCoefficient, coefficient] = [1n, 0n];
+  while (current !== 0n) {
+    const quotient = old / current;
+    [old, current] = [current, old - quotient * current];
+    [oldCoefficient, coefficient] = [
+      coefficient,
+      oldCoefficient - quotient * coefficient,
+    ];
+  }
+  if (old !== 1n) throw new Error('not invertible');
+  return mod(oldCoefficient, modulus);
+}
+
+function power(base, exponent, modulus) {
+  let result = 1n;
+  let factor = mod(base, modulus);
+  let left = exponent;
+  while (left > 0n) {
+    if (left & 1n) result = mod(result * factor, modulus);
+    factor = mod(factor * factor, modulus);
+    left >>= 1n;
+  }
+  return result;
+}
+
+/** P ≡ 3 (mod 4), so a square root is one exponentiation. Null when there is none. */
+function squareRoot(value) {
+  const root = power(value, (P + 1n) / 4n, P);
+  return mod(root * root, P) === mod(value, P) ? root : null;
+}
+
+// Points are `{ x, y }`, or null for the point at infinity.
+function add(left, right) {
+  if (left === null) return right;
+  if (right === null) return left;
+  if (left.x === right.x && mod(left.y + right.y) === 0n) return null;
+  const slope =
+    left.x === right.x && left.y === right.y
+      ? mod((3n * left.x * left.x - 3n) * inverse(2n * left.y, P))
+      : mod((right.y - left.y) * inverse(right.x - left.x, P));
+  const x = mod(slope * slope - left.x - right.x);
+  return { x, y: mod(slope * (left.x - x) - left.y) };
+}
+
+function multiply(point, scalar) {
+  let result = null;
+  let addend = point;
+  let left = mod(scalar, N);
+  while (left > 0n) {
+    if (left & 1n) result = add(result, addend);
+    addend = add(addend, addend);
+    left >>= 1n;
+  }
+  return result;
+}
+
+const toBigInt = (bytes) =>
+  bytes.reduce((value, byte) => (value << 8n) + BigInt(byte), 0n);
+
+function toBytes(value, length = COORDINATE_BYTES) {
+  const out = new Uint8Array(length);
+  let left = value;
+  for (let index = length - 1; index >= 0; index -= 1) {
+    out[index] = Number(left & 0xffn);
+    left >>= 8n;
+  }
+  return out;
+}
+
+const asBytes = (value) =>
+  value instanceof Uint8Array ? value : new Uint8Array(value);
+
+/** The bytes WebAuthn signs: authenticatorData ‖ SHA-256(clientDataJSON). */
+async function signedBytesOf(authenticatorData, clientDataJSON) {
+  const hash = new Uint8Array(
+    await crypto.subtle.digest(CRYPTO_ALGORITHMS.SHA_256, clientDataJSON)
+  );
+  const out = new Uint8Array(authenticatorData.length + hash.length);
+  out.set(authenticatorData, 0);
+  out.set(hash, authenticatorData.length);
+  return out;
+}
+
+async function verifies(point, signedBytes, rawSignature) {
+  const uncompressed = new Uint8Array(1 + COORDINATE_BYTES * 2);
+  uncompressed[0] = 0x04;
+  uncompressed.set(toBytes(point.x), 1);
+  uncompressed.set(toBytes(point.y), 1 + COORDINATE_BYTES);
+  try {
+    const key = await crypto.subtle.importKey(
+      'raw',
+      uncompressed,
+      { name: 'ECDSA', namedCurve: 'P-256' },
+      false,
+      ['verify']
+    );
+    return await crypto.subtle.verify(
+      { name: 'ECDSA', hash: CRYPTO_ALGORITHMS.SHA_256 },
+      key,
+      rawSignature,
+      signedBytes
+    );
+  } catch {
+    return false; // not a point on the curve, or not a key at all
+  }
+}
+
+/** An assertion, however the caller happens to hold it. */
+function responseOf(assertion) {
+  const response = assertion?.response ?? assertion;
+  const { authenticatorData, clientDataJSON, signature } = response ?? {};
+  if (!authenticatorData || !clientDataJSON || !signature) {
+    throw new WebAuthnIdentityError(
+      'an assertion with authenticatorData, clientDataJSON and signature is required',
+      { code: ERROR_CODES.INVALID_INPUT }
+    );
+  }
+  return {
+    authenticatorData: asBytes(authenticatorData),
+    clientDataJSON: asBytes(clientDataJSON),
+    signature: asBytes(signature),
+  };
+}
+
+/**
+ * The public keys that could have produced this assertion — at most two, each
+ * checked against the signature.
+ *
+ * @param {PublicKeyCredential|{authenticatorData: BufferSource, clientDataJSON: BufferSource, signature: BufferSource}} assertion
+ * @returns {Promise<Array<{x: bigint, y: bigint}>>}
+ */
+export async function recoverPublicKeyCandidates(assertion) {
+  const { authenticatorData, clientDataJSON, signature } =
+    responseOf(assertion);
+  const raw =
+    signature.length === P1363_SIGNATURE_LENGTH
+      ? signature
+      : derToRawSignature(signature);
+  const r = toBigInt(raw.slice(0, COORDINATE_BYTES));
+  const s = toBigInt(raw.slice(COORDINATE_BYTES));
+  if (r <= 0n || r >= N || s <= 0n || s >= N) {
+    throw new WebAuthnIdentityError(
+      'the signature is not an ES256 signature, so no key can be recovered from it',
+      { code: ERROR_CODES.INVALID_INPUT }
+    );
+  }
+
+  const signedBytes = await signedBytesOf(authenticatorData, clientDataJSON);
+  const digest = new Uint8Array(
+    await crypto.subtle.digest(CRYPTO_ALGORITHMS.SHA_256, signedBytes)
+  );
+  const e = toBigInt(digest);
+
+  // R has x = r; both parities of y are candidates. Q = r⁻¹(sR − eG).
+  const y = squareRoot(mod(r * r * r - 3n * r + B));
+  if (y === null) return [];
+  const rInverse = inverse(r, N);
+  const candidates = [];
+  for (const candidateY of [y, mod(P - y)]) {
+    const point = multiply(
+      add(multiply({ x: r, y: candidateY }, s), multiply(G, N - mod(e, N))),
+      rInverse
+    );
+    if (point === null) continue;
+    if (await verifies(point, signedBytes, raw)) candidates.push(point);
+  }
+  return candidates;
+}
+
+/**
+ * The public key behind two assertions of the same credential.
+ *
+ * One assertion leaves two possibilities; a second one, over another
+ * challenge, leaves one. Both must come from the same passkey — pass the
+ * credential id of the first to the second `navigator.credentials.get()`.
+ *
+ * @param {*} first
+ * @param {*} second
+ * @returns {Promise<{x: Uint8Array, y: Uint8Array}>} coordinates, as
+ *   `WebAuthnDIDProvider.createDID` takes them
+ */
+export async function recoverPublicKey(first, second) {
+  const [a, b] = await Promise.all([
+    recoverPublicKeyCandidates(first),
+    recoverPublicKeyCandidates(second),
+  ]);
+  const shared = a.filter((point) =>
+    b.some((other) => other.x === point.x && other.y === point.y)
+  );
+  if (shared.length !== 1) {
+    throw new WebAuthnIdentityError(
+      shared.length === 0
+        ? 'the two assertions do not share a public key — they are not the same credential'
+        : 'the two assertions did not settle on one public key',
+      { code: ERROR_CODES.WEBAUTHN_VERIFICATION_FAILED }
+    );
+  }
+  return { x: toBytes(shared[0].x), y: toBytes(shared[0].y) };
+}

package/src/webauthn/restore.js

@@ -0,0 +1,132 @@
+/**
+ * @module Restore
+ * @description
+ * Restore an identity on a device that has stored nothing (#61).
+ *
+ * Two touches of the same passkey are all it takes. The first is asked with
+ * user verification and with the PRF input every device can compute
+ * (`prf-input.js`), so the authenticator returns the same secret it returns on
+ * the device the identity was made on. The second signs another challenge, and
+ * the two signatures together give back the credential's public key
+ * (`recovery.js`) — which an assertion does not carry, and which nothing here
+ * had a way to learn without largeBlob or a copy in storage.
+ *
+ * From those two: the DID, and the signing key derived from the PRF output
+ * with the DID mixed in — the same pair the original device holds.
+ *
+ * Nothing stands in for a missing PRF. A device whose authenticator cannot
+ * evaluate it gets a refusal, because the alternative is an identity that
+ * silently differs from the one the database knows.
+ */
+import { logger } from '@libp2p/logger';
+
+import {
+  ERROR_CODES,
+  PrfUnavailableError,
+  WebAuthnIdentityError,
+} from '../errors.js';
+import { deriveSigningKeyBytes } from '../keystore/derived-signing-key.js';
+import { KEY_TYPES } from '../constants.js';
+import { buildCredentialRequestOptions } from './config.js';
+import { prfInputForRelyingParty } from './prf-input.js';
+import { WebAuthnDIDProvider } from './provider.js';
+import { recoverPublicKey } from './recovery.js';
+
+const log = logger('orbitdb-identity-provider-webauthn-did:restore');
+
+/**
+ * Ask the authenticator in front of this device who it is.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.rpId] - Relying party id; the current host by default.
+ * @param {number} [options.timeout=120000] - Per touch, in ms. Generous on
+ *   purpose: an NFC key has to be found, held and read.
+ * @param {string} [options.signingKeyType='secp256k1'] - As the keystore wants it.
+ * @param {(step: {touch: number, of: number}) => void} [options.onTouch] -
+ *   Called before each ceremony, so an application can say which touch this is.
+ * @returns {Promise<{did: string, publicKey: {x: Uint8Array, y: Uint8Array},
+ *   credentialId: string, rawCredentialId: Uint8Array, signingKey: Uint8Array,
+ *   prfInput: Uint8Array, credential: Object}>} `credential` is what
+ *   `OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential })` takes.
+ *   `credentialId` is the base64url text, as everywhere else in this package,
+ *   and `rawCredentialId` the bytes (before 0.7.0, `credentialId` was the bytes).
+ */
+export async function restoreIdentityFromAuthenticator({
+  rpId,
+  timeout = 120_000,
+  signingKeyType = KEY_TYPES.SECP256K1,
+  onTouch,
+} = {}) {
+  if (typeof navigator === 'undefined' || !navigator.credentials?.get) {
+    throw new WebAuthnIdentityError('WebAuthn is not available here', {
+      code: ERROR_CODES.WEBAUTHN_NOT_SUPPORTED,
+    });
+  }
+
+  const party = rpId ?? globalThis.location?.hostname;
+  const prfInput = await prfInputForRelyingParty(party);
+
+  // Touch one: discoverable, so the device does not have to know which
+  // credential to ask for — it has nothing stored, that is the premise.
+  onTouch?.({ touch: 1, of: 2 });
+  const first = await navigator.credentials.get(
+    buildCredentialRequestOptions({
+      rpId: party,
+      challenge: crypto.getRandomValues(new Uint8Array(32)),
+      userVerification: 'required',
+      timeout,
+      extensions: { prf: { eval: { first: prfInput } } },
+    })
+  );
+  if (!first) {
+    throw new WebAuthnIdentityError('no credential was offered', {
+      code: ERROR_CODES.WEBAUTHN_AUTHENTICATION_FAILED,
+    });
+  }
+
+  const prfOutput = first.getClientExtensionResults?.()?.prf?.results?.first;
+  if (!prfOutput) {
+    // No fallback: an identity derived from anything else is not this one.
+    throw new PrfUnavailableError(
+      'the authenticator returned no PRF output, so the signing key cannot be derived'
+    );
+  }
+
+  // Touch two: the same credential, another challenge. Only the signature
+  // matters, so this asks for no more verification than the key insists on.
+  onTouch?.({ touch: 2, of: 2 });
+  const second = await navigator.credentials.get(
+    buildCredentialRequestOptions({
+      rpId: party,
+      challenge: crypto.getRandomValues(new Uint8Array(32)),
+      userVerification: 'preferred',
+      timeout,
+      credentialId: first.rawId,
+      discoverableCredentials: false,
+    })
+  );
+
+  const publicKey = await recoverPublicKey(first, second);
+  const did = await WebAuthnDIDProvider.createDID({ publicKey });
+  const signingKey = await deriveSigningKeyBytes(
+    new Uint8Array(prfOutput),
+    did,
+    signingKeyType
+  );
+  log('restored %s from the authenticator alone', did);
+
+  const rawCredentialId = new Uint8Array(first.rawId);
+  const credentialId =
+    WebAuthnDIDProvider.arrayBufferToBase64url(rawCredentialId);
+  return {
+    did,
+    publicKey,
+    credentialId,
+    rawCredentialId,
+    signingKey,
+    prfInput,
+    // Ready for the provider as it is, so nobody has to know which of the two
+    // ids it wants under which name.
+    credential: { credentialId, rawCredentialId, publicKey, prfInput },
+  };
+}

package/types/index.d.ts

@@ -430,6 +430,57 @@ export function createVerificationResult(
 
 export { VerificationUtils };
 
+/**
+ * Restoring on a device that has stored nothing (#61).
+ */
+export interface RestoredIdentity {
+  did: string;
+  publicKey: { x: Uint8Array; y: Uint8Array };
+  /** The credential id as base64url text. Before 0.7.0 this was the bytes. */
+  credentialId: string;
+  /** The credential id as bytes. */
+  rawCredentialId: Uint8Array;
+  signingKey: Uint8Array;
+  prfInput: Uint8Array;
+  /** Ready for `OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential })`. */
+  credential: WebAuthnCredentialInfo;
+}
+
+export interface RestoreIdentityOptions {
+  rpId?: string;
+  timeout?: number;
+  signingKeyType?: string;
+  onTouch?: (step: { touch: number; of: number }) => void;
+}
+
+export const PRF_INPUT_INFO: string;
+
+export function prfInputForRelyingParty(rpId?: string): Promise<Uint8Array>;
+
+export function recoverPublicKeyCandidates(
+  assertion: unknown
+): Promise<Array<{ x: bigint; y: bigint }>>;
+
+export function recoverPublicKey(
+  first: unknown,
+  second: unknown
+): Promise<{ x: Uint8Array; y: Uint8Array }>;
+
+export function restoreIdentityFromAuthenticator(
+  options?: RestoreIdentityOptions
+): Promise<RestoredIdentity>;
+
+export function deriveSigningKeyBytes(
+  seed: Uint8Array,
+  did: string,
+  keyType?: string
+): Promise<Uint8Array>;
+
+export function getPrfOutput(
+  credential: Record<string, unknown>,
+  options?: { rpId?: string }
+): Promise<Uint8Array | null>;
+
 declare const defaultExport: {
   WebAuthnDIDProvider: typeof WebAuthnDIDProvider;
   OrbitDBWebAuthnIdentityProvider: typeof OrbitDBWebAuthnIdentityProvider;