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

package/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changes
+
+## 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
+
+- WebAuthn credentials now yield the authenticator's actual public key, so the
+  derived `did:key` **changes** for anyone who registered against 0.3.x or
+  earlier. Existing OrbitDB identities keyed on the old DID will not match, and
+  databases gated on it become unwritable under the new DID. `extractPublicKey()`
+  never took its intended path: `cbor-web` returns byte strings as views into
+  the enclosing buffer, so reading `credentialIdLength` through `authData.buffer`
+  without honouring `byteOffset` read bytes from inside `rpIdHash` and yielded
+  43690 for every credential. The COSE slice was then empty, `cbor` threw
+  `Insufficient data`, and the `catch` silently returned a synthetic key derived
+  from `SHA-256(credentialId)`.
+
+### Fixed
+
+- Keep the identity document stable across reloads. `signIdentity()` reuses the
+  proof it already produced instead of running a fresh WebAuthn assertion, which
+  changed `signatures.publicKey` — and therefore the content address of the
+  identity document — on every page load. Peers then dropped entries:
+  `verifiedIdentitiesCache` in `@orbitdb/core` is keyed on the deterministic
+  `signatures.id`, so two documents from one keystore collide on a single cache
+  entry and `isEqual()` rejects whichever was not verified first. The symptom was
+  a database replicating some entries and silently never receiving the rest.
+- Remove the `timestamp` field from the proof envelope and the 24-hour expiry
+  check that read it. Both were wrong for a value embedded in content-addressed,
+  permanent history: the timestamp changed the document hash on every call, and
+  the expiry would have invalidated the identity behind every entry ever signed
+  under it. Compatible in both directions — proofs that still carry a timestamp
+  verify fine, and 0.3.1 verifying a proof without one computes `NaN`, which
+  fails its `> maxAge` test.
+- Prefer `response.getPublicKey()` (WebAuthn L2) over parsing the attestation
+  object, and correct the parser: honour `byteOffset`, validate the AT flag,
+  bounds-check `credentialIdLength`, and decode only the first CBOR item so
+  trailing extension data (the ED flag, set when PRF is requested) no longer
+  throws. The synthetic fallback is now marked `synthetic: true`.
+- Fix an ambiguous locator in `ed25519-keystore-did`: `getByLabel` matches
+  substrings, and the demo's worker toggle is labelled
+  "Use worker-backed Ed25519 keystore".
+
+### Added
+
+- Two-peer OrbitDB replication tests: real libp2p over loopback TCP, Helia with
+  bitswap, gossipsub, two OrbitDB instances, driven by a software WebAuthn
+  authenticator with a real P-256 keypair, an incrementing signature counter and
+  randomised signatures. Covers identity-document stability across reloads,
+  replication of entries written before and after a reload, and that two devices
+  sharing a passkey keep distinct, independently valid identities.
+- Attestation-parsing unit tests: credential ID lengths 16/20/32/64/128,
+  trailing extension data, missing AT flag, non-P-256 COSE keys and truncated
+  coordinates. 13 of the 14 fail against 0.3.1.
+
+### Changed
+
+- CI now runs all eleven test files. Five never ran: `webauthn-unit`,
+  `webauthn-verification`, `standalone-toolkit`, `ed25519-keystore-did` and
+  `simple-encryption-integration`. `webauthn-unit` imports through Vite's `/@fs`
+  endpoint, which only the dev server exposes, so its step runs against `dev`
+  rather than the `preview` build CI otherwise uses.
+- Publishing moves into CI. A `v*` tag runs the full suite and then publishes
+  via npm Trusted Publishing (OIDC), with provenance. A manual run defaults to a
+  check mode that verifies tag/version agreement and packaging without
+  publishing.
+- `test:ci`, which `preversion` and `prepublishOnly` run, now points at the
+  Node-context suites via `playwright.node.config.js` — 32 tests in about ten
+  seconds. It previously ran `webauthn-verification` alone: five tests that check
+  regexes against hardcoded DID literals and one fully mocked database object,
+  none of which creates a credential, touches the keystore or opens an OrbitDB.
+- Restore the `security-audit`, `package-validation` and `notify` jobs. The
+  enforced audit gate is `--prod --audit-level=critical`; auditing the full tree
+  at `moderate` reports 86 advisories from the helia and libp2p dev tree, and
+  even `--prod` reports 5 through `iso-web > iso-kv > conf > ajv`, so both wider
+  audits run informational until that chain is bumped.
+
+### Also shipping in this release
+
+Entries that had accumulated under Unreleased since 0.3.1:
+
+- Add `SECURITY.md` with vulnerability reporting and supported-version policy.
+- Rename `changes.md` to `CHANGELOG.md` and include it in the published package.
+- Add public TypeScript declarations for the root, standalone, verification,
+  and keystore package entrypoints.
+- Add `docs/API.md` and expose `@le-space/orbitdb-identity-provider-webauthn-did/keystore`
+  as a typed package subpath.
+- Remove the Vite node polyfill plugin from production dependencies, update
+  the varsig support stack to `iso-web@^3.1.2`, and verify
+  `npm audit --omit=dev` reports zero production advisories.
+- Re-enable the CI lint step and verify `pnpm run lint` passes.
+- Add shared public constants and catchable error classes for WebAuthn,
+  keystore, and varsig flows.
+- Add root Prettier scripts, ignore rules, and a CI formatting check.
+- Add `CODE_OF_CONDUCT.md` and include it in the published package.
+
+## 0.3.1
+
+- Bump package metadata to `0.3.1` and create the clean release tag after
+  the post-`0.3.0` CI fixes landed.
+- Update example lockfiles so all demos install successfully with
+  `pnpm install --frozen-lockfile`.
+- Fix Playwright web server startup by passing Vite `preview`/`dev` arguments
+  directly, avoiding CI timeouts waiting for the wrong port.
+- Update GitHub Actions to current action majors:
+  `actions/checkout@v7`, `pnpm/action-setup@v6`, `actions/setup-node@v6`,
+  and `actions/upload-artifact@v7`.
+- Verify the release commit with GitHub Actions:
+  root frozen install, all three example frozen installs, all three example
+  builds, WebAuthn focused tests, logging E2E, integration E2E, varsig E2E,
+  encrypted-keystore tests, and Ed25519 encrypted-keystore E2E.
+- Verify the package tarball with `npm pack --dry-run`; the package reports
+  `@le-space/orbitdb-identity-provider-webauthn-did@0.3.1` with 27 published
+  files.
+
+## 0.3.0
+
+- Upgrade the OrbitDB stack to `@orbitdb/core@^4.0.0`.
+- Upgrade Helia to `helia@^7.0.1` and add the current Helia service packages:
+  `@helia/libp2p`, `@helia/http`, and `@helia/bitswap`.
+- Upgrade libp2p to `libp2p@^3.3.4` and the current scoped packages,
+  including `@libp2p/gossipsub@^16.0.3`, `@libp2p/identify@^4.1.8`,
+  `@libp2p/websockets@^10.1.15`, `@chainsafe/libp2p-noise@^17.0.0`,
+  and `@chainsafe/libp2p-yamux@^8.0.1`.
+- Confirm the gossipsub stream-registry fix from
+  `libp2p/js-libp2p#3531` is included via `@libp2p/gossipsub@16.0.3`.
+- Port all Svelte examples to the OrbitDB 4, Helia 7, and libp2p 3 stack:
+  `webauthn-todo-demo`, `ed25519-encrypted-keystore-demo`, and
+  `webauthn-varsig-demo`.
+- Update example libp2p configuration for the v3 `connectionEncrypters`
+  option and current `withLibp2p`, `withHTTP`, and `withBitswap` Helia setup.
+- Update OrbitDB identity and keystore integration for the current OrbitDB 4
+  public APIs, including keystore key generation/storage.
+- Replace older dynamic codec/hash imports with static multiformats imports
+  where needed.
+- Remove obsolete local OrbitDB patches.
+- Clean up known Vite/polyfill build warnings in the examples.
+- Fix varsig verification edge cases for replicated entries, mixed
+  worker/hardware verification, and Node relay default exports.
+
+## 0.2.10
+
+- Release metadata update after varsig verification and worker/hardware
+  compatibility fixes.
+
+## 0.2.9
+
+- Version metadata update after discoverable passkey recovery work.
+
+## 0.2.8
+
+- Add discoverable passkey recovery flows.
+- Add worker-backed keystore demo coverage and fix the worker keystore demo
+  build.
+- Export varsig verification, identity storage, and
+  `wrapWithVarsigVerification`.
+- Stabilize Chromium E2E/unit coverage and align Ed25519 keystore tests.
+- Sync docs, format the codebase, and restrict CI Playwright runs to Chromium.
+
+## 0.2.6
+
+- Release metadata update for the standalone compatibility series.
+
+## 0.2.5
+
+- Add standalone compatibility fallback release.
+
+## 0.2.4
+
+- Re-enable encrypted-keystore CI and stabilize demo checks.
+- Sync pnpm lockfile with package dependencies.
+- Run CI on pushes to all branches.
+- Merge the standalone WebAuthn toolkit feature branch.
+
+## 0.2.3
+
+- Add reusable standalone WebAuthn worker and varsig toolkit exports.
+- Restore ucanto signer metadata and add issuance regression coverage.
+- Stabilize WebAuthn unit harness and mock credentials.
+- Finalize standalone toolkit integration and README updates.
+- Refresh pnpm lockfile.
+
+## 0.2.2
+
+- Ship patch-package in dependencies so postinstall works for consumers.
+
+## 0.2.1
+
+- Add WebAuthn varsig demo E2E coverage and test-mode stubs for CI.
+- Update CI to focus on Chromium-only runs and disable failing encrypted keystore tests.
+- Add @libp2p/crypto dependency and update lockfile.
+- Publish varsig demo build to Storacha and link in README.
+
+## 0.2.0
+
+- Switch iso dependencies to the published `@le-space` fork and pin `@le-space/iso-did@2.1.2`.
+- Restore unscoped `iso-web` from npm to satisfy `iso-did` runtime deps.
+- Document forked iso packages used for WebAuthn varsig support.
+- Clarify Varsig vs keystore-based DID paths and reference the example demos.
+
+## 0.1.0 (preview)
+
+- Initial preview release with WebAuthn DID and varsig provider.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making this project a welcoming, respectful, and
+harassment-free space for everyone who contributes, reports issues, reviews
+code, writes documentation, or participates in project discussions.
+
+## Expected Behavior
+
+- Use welcoming and inclusive language.
+- Be respectful of differing viewpoints and experience levels.
+- Give and receive constructive feedback with care.
+- Focus criticism on ideas, code, and project outcomes, not on people.
+- Respect privacy, security boundaries, and responsible disclosure processes.
+
+## Unacceptable Behavior
+
+Unacceptable behavior includes harassment, discriminatory language, personal
+attacks, intimidation, unwanted attention, publishing private information
+without consent, or any behavior that would reasonably make participation feel
+unsafe or hostile.
+
+Because this project touches identity, cryptography, WebAuthn, and local-first
+security flows, do not pressure others to disclose private credentials, seeds,
+keys, vulnerability details, or personal identity information in public
+channels.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please contact the project
+maintainers through GitHub. For security-sensitive issues, follow the reporting
+process in `SECURITY.md` instead of posting details publicly.
+
+Reports should include enough context for maintainers to understand what
+happened, while avoiding unnecessary disclosure of private information.
+Maintainers will review reports in good faith and handle them as confidentially
+as practical.
+
+## Enforcement
+
+Maintainers may take action they consider appropriate, including clarification,
+moderation, temporary limits on participation, removal from project spaces, or
+permanent bans for repeated or severe violations.
+
+Anyone asked to stop unacceptable behavior is expected to comply immediately.
+
+## Scope
+
+This code of conduct applies in project spaces, including GitHub issues, pull
+requests, discussions, documentation, examples, and any other official project
+collaboration channels.

package/README.md

@@ -8,6 +8,7 @@ This package provides:
 
 - Two WebAuthn-based OrbitDB identity providers.
 - A standalone WebAuthn toolkit export (`@le-space/orbitdb-identity-provider-webauthn-did/standalone`) for reuse outside OrbitDB identity wiring.
+- A keystore helper export (`@le-space/orbitdb-identity-provider-webauthn-did/keystore`) for encrypted keystore utilities and provider wiring.
 - **WebAuthn-Varsig**: No insecure OrbitDB keystore at all. Each entry is signed by WebAuthn (varsig envelope), so keys never leave the authenticator, one Passkey (WebAuthn) prompt per write.
 - **Keystore-based DID**: Generates an Ed25519/secp256k1 keystore keypair for OrbitDB signing in browser memory. When `encryptKeystore` is enabled, the private key is encrypted with AES-GCM and only rehydrated in memory after a WebAuthn unlock (PRF, largeBlob, or hmac-secret).
 
@@ -262,9 +263,10 @@ sequenceDiagram
 
 Svelte demos:
 
-- `examples/webauthn-todo-demo/` - WebAuthn DID (no keystore signing; identity-only). Includes discoverable credential diagnostics, `Use Existing Passkey`, `largeBlob` identity metadata recovery, and local fallback recovery.
-- `examples/ed25519-encrypted-keystore-demo/` - Ed25519 keystore DID; keystore encrypted at rest with WebAuthn (PRF when available, otherwise largeBlob/hmac-secret).
-- `examples/webauthn-varsig-demo/` - Varsig provider with passkey signing for each entry. Includes discoverable credential diagnostics, `Use Existing Passkey`, `largeBlob` varsig metadata recovery, and local fallback recovery. Live demo: https://dweb.link/ipfs/bafybeib6tpwiby7pik67ufb3lxpr3j4by2l7r3ov3zzk6hjbzjzgsvckhy
+- Live demo directory: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/
+- `examples/ed25519-encrypted-keystore-demo/` - Ed25519 keystore DID; keystore encrypted at rest with WebAuthn (PRF when available, otherwise largeBlob/hmac-secret). Live demo: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/ed25519-encrypted-keystore-demo/
+- `examples/webauthn-varsig-demo/` - Varsig provider with passkey signing for each entry. Includes discoverable credential diagnostics, `Use Existing Passkey`, `largeBlob` varsig metadata recovery, and local fallback recovery. Live demo: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/webauthn-varsig-demo/
+- `examples/webauthn-todo-demo/` - WebAuthn DID (no keystore signing; identity-only). Includes discoverable credential diagnostics, `Use Existing Passkey`, `largeBlob` identity metadata recovery, and local fallback recovery. Live demo: https://le-space.github.io/orbitdb-identity-provider-webauthn-did/webauthn-todo-demo/
 
 Scripted examples:
 
@@ -278,12 +280,15 @@ Mermaid sequences for scripts:
 
 ## Documentation
 
+- `docs/API.md`
 - `docs/ED25519-KEYSTORE-DID.md`
 - `docs/WEBAUTHN-ENCRYPTED-KEYSTORE-INTEGRATION.md`
 - `docs/WEBAUTHN-DID-AND-ORBITDB-IDENTITY.md`
 - `docs/STANDALONE-API-PLAN.md`
 - `docs/EXAMPLE-SEQUENCES.md`
 - `docs/E2E-TEST-SUMMARY.md`
+- `SECURITY.md`
+- `CODE_OF_CONDUCT.md`
 
 ## Identity Recovery Summary
 

package/SECURITY.md

@@ -0,0 +1,88 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the current `0.3.x` release line.
+
+| Version | Supported |
+| ------- | --------- |
+| 0.3.x   | Yes       |
+| < 0.3   | No        |
+
+## Reporting a Vulnerability
+
+Please do not report security vulnerabilities through public GitHub issues.
+
+Report suspected vulnerabilities by email:
+
+security@le-space.de
+
+Please include as much detail as you can:
+
+- affected package version, commit, or tag
+- affected browser, runtime, or operating system
+- steps to reproduce
+- expected and actual behavior
+- proof of concept, logs, screenshots, or traces if available
+- your assessment of impact
+
+We aim to acknowledge reports within 48 hours and coordinate fixes before
+public disclosure.
+
+## Security Model
+
+This package provides WebAuthn-based identity providers and helper APIs for
+OrbitDB. It handles sensitive identity material and should be reviewed in the
+context of the application that embeds it.
+
+### Varsig Provider
+
+The varsig provider is the preferred security model when available. Entry
+signing is performed through WebAuthn assertions, so the private key remains
+inside the authenticator and is not exported to application memory.
+
+### Keystore Provider
+
+The keystore provider can generate browser-side Ed25519 or secp256k1 keys for
+OrbitDB signing. When encrypted keystore mode is enabled, key material is
+encrypted at rest with AES-GCM and unlocked through WebAuthn-supported secret
+recovery mechanisms such as PRF, largeBlob, or hmac-secret.
+
+During an unlocked session, private key material may exist in browser memory.
+Applications with stricter requirements should prefer the varsig provider or
+keep keystore sessions short.
+
+### Identity Metadata Recovery
+
+Discoverable passkeys can identify a credential during authentication, but
+WebAuthn assertions do not reliably return the public key after registration.
+This package therefore needs identity metadata persistence for recovery.
+
+The example applications use:
+
+- WebAuthn largeBlob metadata as the preferred recovery path
+- browser localStorage as a fallback when largeBlob is unavailable or empty
+
+Applications should treat localStorage metadata as recoverability metadata, not
+as a replacement for authenticator-backed key protection.
+
+## Operational Guidance
+
+- Serve production applications over HTTPS.
+- Configure WebAuthn relying party IDs and origins deliberately.
+- Prefer the varsig provider for hardware-backed signing on every write.
+- Enable encrypted keystore mode if using the keystore provider in production.
+- Keep dependencies updated and review `npm audit --omit=dev` output before
+  production deployments.
+- Do not log private keys, PRF seeds, decrypted keystore archives, or raw secret
+  key material.
+- Review browser storage behavior for your deployment, especially if using
+  localStorage fallback recovery.
+
+## Disclosure Process
+
+1. A vulnerability report is received privately.
+2. We acknowledge the report and investigate impact.
+3. We prepare and test a fix.
+4. We publish a patched release.
+5. We coordinate public disclosure with the reporter where appropriate.