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

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changes
 
+## 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

package/README.md

@@ -386,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.6.0",
+  "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/webauthn/provider.js

@@ -46,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;
   }
 
@@ -712,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/restore.js

@@ -45,7 +45,11 @@ const log = logger('orbitdb-identity-provider-webauthn-did:restore');
  * @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: Uint8Array, signingKey: Uint8Array, prfInput: 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,
@@ -111,11 +115,18 @@ export async function restoreIdentityFromAuthenticator({
   );
   log('restored %s from the authenticator alone', did);
 
+  const rawCredentialId = new Uint8Array(first.rawId);
+  const credentialId =
+    WebAuthnDIDProvider.arrayBufferToBase64url(rawCredentialId);
   return {
     did,
     publicKey,
-    credentialId: new Uint8Array(first.rawId),
+    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

@@ -436,9 +436,14 @@ export { VerificationUtils };
 export interface RestoredIdentity {
   did: string;
   publicKey: { x: Uint8Array; y: Uint8Array };
-  credentialId: 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 {