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

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 ## Unreleased
 
+## 0.5.0
+
+### Breaking
+
+- The varsig signing context moves into the signed payload, which **changes the
+  bytes a credential signs**. Entries and identities produced by 0.4.x and
+  earlier no longer verify, and peers running different major versions cannot
+  replicate with each other — the whole set has to move together.
+
+  The challenge used to be `SHA-256(label ‖ payload)`. That separated the three
+  signing contexts, but it meant the challenge was no longer the hash of the
+  payload, and the varsig WebAuthn draft has a verifier re-hash the payload and
+  compare it against the challenge (step 5). Nothing outside this package could
+  reproduce that value.
+
+  The label itself is not the problem: one credential signs an identity, a public
+  key and an oplog entry, and a signature over one must not be replayable as a
+  signature over another. That separation cannot live in the varsig header
+  either, because a WebAuthn signature only covers
+  `authenticatorData ‖ SHA-256(clientDataJSON)` — anything carried beside the
+  challenge is unauthenticated. So the context moves into the signed bytes:
+  `bindContext()` frames it length-prefixed ahead of the payload, and the
+  challenge becomes a plain SHA-256 multihash of those bytes. Both properties
+  now hold — the three contexts still yield different challenges, and a spec
+  verifier can reproduce the digest.
+
+  The length prefix is load-bearing. Without it, context `a` with payload `bc`
+  and context `ab` with payload `c` are the same bytes, so a chosen payload
+  could absorb the label and sidestep the separation.
+
+  This is a bet on a draft: ChainAgnostic/varsig#11 is still open with
+  `webauthn-varsig-header = TODO`. If the draft settles differently, the wire
+  format changes again.
+
+- `iso-webauthn-varsig` moves to 0.3.0, which corrects the Ed25519 curve code in
+  the varsig header from `0xed01` to `0xed`. `0xed01` is how the multicodec
+  `ed25519-pub` is written in prose — but that is its _varint encoding_, and
+  using it as the code meant emitting 60673, which no other implementation reads
+  as Ed25519. Ed25519 varsigs written by earlier versions do not decode.
+  **P-256 bytes are unchanged by this second break**, so P-256 deployments are
+  affected only by the challenge change above.
+
+### Migration
+
+Nothing carries over automatically. Re-register credentials and re-create any
+database whose entries were signed under 0.4.x, and upgrade every peer —
+including relays that verify identities — in one step rather than gradually.
+
 ## 0.4.2
 
 ### Fixed

package/README.md

@@ -305,6 +305,63 @@ 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.
 
+## Upstream Packages and Temporary Forks
+
+This package builds on the [`iso-repo`](https://github.com/hugomrdias/iso-repo)
+toolkit by **[Hugo Dias](https://github.com/hugomrdias)** — `iso-base`,
+`iso-did` and `iso-passkeys` do the WebAuthn parsing, DID encoding and base
+conversion that this provider is built on top of. It is excellent work and this
+package would be considerably larger without it. Thank you.
+
+Four of the dependencies resolve to `@le-space` builds rather than the
+published originals. Two different reasons, and they should not be confused:
+
+### Temporary forks
+
+Published only to unblock this package, and meant to disappear. Each carries a
+small delta that belongs upstream.
+
+| Dependency     | Upstream                                                                               | Why it is forked                                                                                                              |
+| -------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `iso-passkeys` | [iso-passkeys](https://github.com/hugomrdias/iso-repo/tree/main/packages/iso-passkeys) | Re-exports `parseAttestationObject` and `unwrapEC2Signature`, which already exist upstream but are not part of the public API |
+| `iso-base`     | [iso-base](https://github.com/hugomrdias/iso-repo/tree/main/packages/iso-base)         | Kept in step with the forks above                                                                                             |
+| `iso-did`      | [iso-did](https://github.com/hugomrdias/iso-repo/tree/main/packages/iso-did)           | Kept in step with the forks above                                                                                             |
+
+The `iso-passkeys` delta is two lines and purely additive — nothing is changed
+or removed, two existing internal functions are simply exported. It is proposed
+upstream as
+[hugomrdias/iso-repo#543](https://github.com/hugomrdias/iso-repo/pull/543); once
+that lands, these three forks and their entries in `pnpm.overrides` can go. The
+remaining entries in that block — `iso-web`, `conf>ajv`, `ajv>fast-uri` — are
+unrelated and stay.
+
+### Not a fork
+
+`iso-webauthn-varsig` is a **new** package rather than a modified copy of an
+existing one. It implements WebAuthn varsig signing for OrbitDB oplog entries
+and has no upstream equivalent. It follows `iso-repo` conventions and lives in
+the same lineage, which is why it is named the way it is.
+
+It follows the non-recursive varsig layout, which shipped in 0.2.0.
+
+One thing is still open, and it is on the spec side rather than here: the
+WebAuthn varsig header. `webauthn-varsig-header` is `TODO` in
+[ChainAgnostic/varsig#11](https://github.com/ChainAgnostic/varsig/pull/11), so
+the `0x300001` marker this package writes is a private-use codepoint chosen
+here rather than an allocated one. Expect the wire format to change once that
+is settled.
+
+### Not forked at all
+
+`iso-web` appears in `pnpm.overrides` but resolves to the genuine upstream
+package. The entry only pins a version.
+
+### Licensing
+
+All `iso-repo` packages are MIT, © Hugo Dias. The forks keep the original
+`license` and `author` fields, so authorship travels with them; only the
+package name changes.
+
 ## License
 
 MIT. See `LICENSE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/orbitdb-identity-provider-webauthn-did",
-  "version": "0.4.2",
+  "version": "0.5.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",
@@ -90,7 +90,7 @@
     "iso-did": "npm:@le-space/iso-did@2.1.2",
     "iso-passkeys": "npm:@le-space/iso-passkeys",
     "iso-web": "^3.1.2",
-    "iso-webauthn-varsig": "npm:@le-space/iso-webauthn-varsig@^0.2.0",
+    "iso-webauthn-varsig": "npm:@le-space/iso-webauthn-varsig@^0.3.0",
     "multiformats": "^14.0.0"
   },
   "devDependencies": {
@@ -143,7 +143,7 @@
       "iso-base": "npm:@le-space/iso-base",
       "iso-did": "npm:@le-space/iso-did@2.1.2",
       "iso-web": "^3.1.2",
-      "iso-webauthn-varsig": "npm:@le-space/iso-webauthn-varsig@^0.2.0",
+      "iso-webauthn-varsig": "npm:@le-space/iso-webauthn-varsig@^0.3.0",
       "conf>ajv": "^8.18.0",
       "ajv>fast-uri": "^3.1.4"
     },

package/src/varsig/assertion.js

@@ -12,7 +12,12 @@ import {
   verifyP256Signature,
   verifyWebAuthnAssertion,
 } from 'iso-webauthn-varsig';
-import { buildChallengeBytes, toArrayBuffer, toBytes } from './utils.js';
+import {
+  bindContext,
+  buildChallengeBytes,
+  toArrayBuffer,
+  toBytes,
+} from './utils.js';
 import { buildCredentialRequestOptions } from '../webauthn/config.js';
 import { KEY_TYPES, WEBAUTHN_CLIENT_DATA_TYPES } from '../constants.js';
 import {
@@ -44,7 +49,10 @@ async function runWebAuthnAssertionForPayload(
 ) {
   const rpId = window.location.hostname;
   const origin = window.location.origin;
-  const challengeBytes = await buildChallengeBytes(domainLabel, payloadBytes);
+  // The context is framed into the signed bytes, not into the challenge
+  // preimage, so the challenge stays a plain hash of what was signed.
+  const signedBytes = bindContext(domainLabel, payloadBytes);
+  const challengeBytes = await buildChallengeBytes(signedBytes);
 
   if (isTestMode()) {
     return {
@@ -208,8 +216,7 @@ async function verifyVarsigForPayload(
   }
   const clientData = parseClientDataJSON(decoded.clientDataJSON);
   const expectedChallenge = await buildChallengeBytes(
-    domainLabel,
-    payloadBytes
+    bindContext(domainLabel, payloadBytes)
   );
   const expectedChallengeEncoded = bytesToBase64url(expectedChallenge);
 

package/src/varsig/utils.js

@@ -1,7 +1,7 @@
 /**
  * Byte and challenge helpers for varsig signing.
  */
-import { concat } from 'iso-webauthn-varsig';
+import { concat, varintEncode } from 'iso-webauthn-varsig';
 
 const encoder = new TextEncoder();
 
@@ -27,18 +27,51 @@ function toBytes(data) {
 }
 
 /**
- * Build a WebAuthn challenge from a domain label and payload.
- * @param {string} domainLabel - Domain label prefix.
+ * Frame a payload with the context it is signed for.
+ *
+ * The same credential signs three different things — an identity, a public key
+ * and an oplog entry — and a signature over one must not be reusable as a
+ * signature over another. The separation has to live inside the bytes that get
+ * hashed: the WebAuthn signature covers `authenticatorData ‖ SHA-256(clientDataJSON)`
+ * and nothing else, so a context field carried alongside the varsig would not
+ * be bound to the signature at all.
+ *
+ * It used to be mixed into the challenge preimage instead
+ * (`SHA-256(label ‖ payload)`), which separated the domains but meant the
+ * challenge was no longer the hash of the payload — so verifiers following the
+ * varsig spec could never reproduce it.
+ *
+ * @param {string} context - Domain label, e.g. 'orbitdb-entry:'.
  * @param {Uint8Array} payloadBytes - Payload bytes.
- * @returns {Promise<Uint8Array>} SHA-256 digest.
+ * @returns {Uint8Array} The bytes that are signed over.
  */
-async function buildChallengeBytes(domainLabel, payloadBytes) {
-  const domain = encoder.encode(domainLabel);
-  const hash = await crypto.subtle.digest(
-    'SHA-256',
-    concat([domain, payloadBytes])
+function bindContext(context, payloadBytes) {
+  const contextBytes = encoder.encode(context);
+  // Length-prefixed so the frame is unambiguous: without it, a context of
+  // 'a' with payload 'bc' and a context of 'ab' with payload 'c' would
+  // produce identical bytes.
+  return concat([
+    varintEncode(contextBytes.length),
+    contextBytes,
+    payloadBytes,
+  ]);
+}
+
+/**
+ * Build a WebAuthn challenge as a multihash of the payload.
+ *
+ * Per the varsig WebAuthn draft the challenge carries the payload hash as a
+ * multihash, so a verifier can re-hash the payload and compare. `0x12 0x20` is
+ * the SHA-256 prefix and its 32-byte length.
+ *
+ * @param {Uint8Array} payloadBytes - The bytes being signed, context included.
+ * @returns {Promise<Uint8Array>} Multihash of the payload.
+ */
+async function buildChallengeBytes(payloadBytes) {
+  const hash = new Uint8Array(
+    await crypto.subtle.digest('SHA-256', payloadBytes)
   );
-  return new Uint8Array(hash);
+  return concat([new Uint8Array([0x12, 0x20]), hash]);
 }
 
-export { encoder, toArrayBuffer, toBytes, buildChallengeBytes };
+export { encoder, toArrayBuffer, toBytes, bindContext, buildChallengeBytes };