@le-space/p2pass 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sabysachi Patra & Nico Krause
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# P2Pass (`@le-space/p2pass`)
+
+[![Tests](https://github.com/asabya/p2p-passkeys/actions/workflows/tests.yml/badge.svg)](https://github.com/asabya/p2p-passkeys/actions/workflows/tests.yml)
+
+Standalone Svelte component for passkey-based DID identities replicating p2p between devices and [Storacha](https://storacha.network) decentralized backup. Published on npm as **`@le-space/p2pass`** (Le Space).
+
+Drop in `<StorachaFab />` and get:
+
+- WebAuthn passkey authentication (hardware Ed25519, P-256, or worker Ed25519 fallback)
+- UCAN delegation-based Storacha access
+- OrbitDB backup/restore with progress tracking
+- P2P device linking via libp2p with copy/paste peer info
+- Multi-device registry with automatic device detection
+- Floating action button with Storacha branding
+
+## Install
+
+```bash
+npm install @le-space/p2pass
+```
+
+## Usage
+
+```svelte
+<script>
+  import { StorachaFab } from '@le-space/p2pass';
+</script>
+
+<StorachaFab {orbitdb} {libp2p} onAuthenticate={handleAuthenticate} />
+```
+
+The component handles everything internally:
+
+1. Click the floating Storacha button (bottom-right)
+2. Choose a **signing mode** (hardware Ed25519 with P-256 fallback, hardware P-256 only, or worker Ed25519), then **Authenticate with Passkey** → biometric prompt → DID created
+3. Two tabs appear: **P2P Passkeys** (device linking) and **Storacha** (backup/restore); P2P Passkeys is the default
+4. Paste a UCAN delegation → connected to Storacha → backup/restore enabled
+5. P2P Passkeys tab shows connection status, peer info, and linked devices
+
+## Worker Ed25519 Passkey Flow
+
+Worker mode (`preferWorkerMode={true}`) uses WebAuthn purely for user verification and PRF seed extraction — the actual signing key is an Ed25519 keypair generated in a web worker, encrypted with the PRF-derived key.
+
+### First Visit (Registration)
+
+```
+User clicks "Authenticate with Passkey"
+  │
+  ├─ navigator.credentials.create()
+  │    ├─ Biometric prompt (Face ID / Touch ID / PIN)
+  │    ├─ Creates discoverable credential (resident key)
+  │    └─ PRF extension: eval({ first: deterministicSalt })
+  │
+  ├─ Extract PRF seed from credential response
+  │    └─ Deterministic 32-byte seed derived from biometric + salt
+  │
+  ├─ Initialize Ed25519 keystore with PRF seed
+  │    └─ PRF seed used as AES-GCM encryption key for the keystore
+  │
+  ├─ Generate Ed25519 keypair in web worker
+  │    ├─ Random Ed25519 keypair created
+  │    ├─ DID derived: did:key:z6Mk...
+  │    └─ Archive exported (private key material)
+  │
+  ├─ Encrypt archive with PRF-derived AES key
+  │    └─ { ciphertext, iv } stored as hex strings
+  │
+  ├─ Derive IPNS keypair from PRF seed (for recovery)
+  │    └─ Deterministic Ed25519 key for IPNS manifest publishing
+  │
+  └─ Store credentials
+       ├─ Encrypted archive → localStorage (bootstrap cache)
+       ├─ Keypair + archive → OrbitDB registry (when available)
+       └─ WebAuthn credential metadata → localStorage (for re-auth)
+```
+
+### Return Visit (Restoration)
+
+```
+User clicks "Authenticate with Passkey"
+  │
+  ├─ Find cached archive in localStorage
+  │    └─ { did, ciphertext, iv, publicKeyHex }
+  │
+  ├─ Load stored WebAuthn credential metadata
+  │
+  ├─ navigator.credentials.get()
+  │    ├─ Biometric prompt (same passkey as registration)
+  │    └─ PRF extension: eval({ first: sameSalt })
+  │
+  ├─ Extract PRF seed → same seed as registration
+  │
+  ├─ Decrypt archive with PRF seed → same Ed25519 keypair
+  │
+  └─ Same DID restored: did:key:z6Mk...
+```
+
+### Recovery (New Device / Cleared Storage)
+
+```
+User clicks "Recover Identity"
+  │
+  ├─ navigator.credentials.get() (discoverable credential)
+  │    ├─ Biometric prompt — passkey synced via iCloud/Google/etc.
+  │    └─ PRF extension → same PRF seed
+  │
+  ├─ Derive IPNS keypair from PRF seed
+  │
+  ├─ Resolve IPNS manifest via w3name
+  │    └─ Manifest contains: { ownerDid, archiveCID, delegation, registryAddress }
+  │
+  ├─ Fetch encrypted archive from IPFS gateway (no auth needed)
+  │    └─ GET https://{archiveCID}.ipfs.w3s.link/ → { ciphertext, iv }
+  │
+  ├─ Decrypt archive with PRF seed → Ed25519 keypair restored
+  │
+  ├─ Connect to Storacha using delegation from manifest
+  │
+  └─ Same DID restored on new device
+```
+
+### Key Insight
+
+The WebAuthn credential never signs anything — it's only used for:
+
+1. **User verification** (biometric gate)
+2. **PRF seed extraction** (deterministic secret derived from biometric + salt)
+
+The PRF seed is the root of all derived keys:
+
+- **Ed25519 DID keypair** — encrypted with PRF-derived AES key
+- **IPNS recovery key** — deterministically derived from PRF seed
+- **Keystore encryption** — PRF seed used as AES-GCM key
+
+This means the same passkey on any device (via passkey sync) produces the same PRF seed, which unlocks the same DID identity.
+
+### Signing Modes
+
+| Mode             | Security | Key Storage                         | Biometric     |
+| ---------------- | -------- | ----------------------------------- | ------------- |
+| Hardware Ed25519 | Highest  | TPM/Secure Enclave                  | Per signature |
+| Hardware P-256   | High     | TPM/Secure Enclave                  | Per signature |
+| Worker Ed25519   | Medium   | Web worker + encrypted localStorage | On init only  |
+
+**Worker Ed25519** matches typical OrbitDB multi-device flows (signing key in a worker). **Hardware** modes keep private keys in the authenticator; hardware Ed25519 lists Ed25519 first and may obtain **P-256** if the device does not support hardware Ed25519. Pick the mode in the panel before authenticating, or set `signingPreference="worker"` / `preferWorkerMode` on the component.
+
+## Props
+
+When using `StorachaFab` or `StorachaIntegration` directly:
+
+| Prop                | Type     | Default         | Description                                                                              |
+| ------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------- |
+| `orbitdb`           | object   | `null`          | OrbitDB instance (for backup/restore)                                                    |
+| `database`          | object   | `null`          | Database instance to backup                                                              |
+| `isInitialized`     | boolean  | `false`         | Whether OrbitDB is ready                                                                 |
+| `entryCount`        | number   | `0`             | Database entry count                                                                     |
+| `databaseName`      | string   | `'restored-db'` | Name for restored database                                                               |
+| `onRestore`         | function | `() => {}`      | Called when restore completes                                                            |
+| `onBackup`          | function | `() => {}`      | Called when backup completes                                                             |
+| `onAuthenticate`    | function | `() => {}`      | Called after passkey auth (receives signingMode)                                         |
+| `libp2p`            | object   | `null`          | libp2p instance for P2P connectivity                                                     |
+| `signingPreference` | `string` | `null`          | `'hardware-ed25519'`, `'hardware-p256'`, or `'worker'` — overrides the in-panel selector |
+| `preferWorkerMode`  | boolean  | `false`         | Deprecated; same as `signingPreference="worker"`                                         |
+
+## Components
+
+### `StorachaFab`
+
+Floating action button (bottom-right) with the Storacha rooster logo. Opens the integration panel as an overlay. Self-contained — no Tailwind or external CSS required.
+
+### `StorachaIntegration`
+
+The panel component itself. Can be embedded inline instead of as a floating panel.
+
+## Programmatic API
+
+```js
+import {
+  IdentityService,
+  createStorachaClient,
+  parseDelegation,
+  setupP2PStack,
+  createLibp2pInstance,
+  cleanupP2PStack,
+} from '@le-space/p2pass';
+
+// Create identity (worker mode for P2P)
+const identity = new IdentityService();
+const { mode, did, algorithm } = await identity.initialize(undefined, { preferWorkerMode: true });
+
+// Get UCAN principal
+const principal = await identity.getPrincipal();
+
+// Connect to Storacha
+const delegation = await parseDelegation(delegationBase64);
+const client = await createStorachaClient(principal, delegation);
+
+// Start P2P stack
+const libp2p = await createLibp2pInstance();
+// After auth, upgrade to full stack with OrbitDB:
+const stack = await setupP2PStack(credential);
+```
+
+## Development
+
+```bash
+npm run dev:example    # Run example app
+npm test               # Run unit tests
+npm run package        # Build library
+```
+
+### End-to-end tests
+
+Playwright drives the **example app** in Chromium with virtual WebAuthn. Tests live in `e2e/` (for example `link-devices.spec.js` for multi-device pairing).
+
+**Run:**
+
+```bash
+npm run test:e2e       # headless; starts relay + Vite automatically
+npm run test:e2e:ui    # Playwright UI mode (debugging)
+```
+
+`playwright.config.js` starts **`scripts/e2e-with-relay.mjs`**, which:
+
+1. Launches **orbitdb-relay-pinner** (local libp2p relay).
+2. Fetches WebSocket bootstrap multiaddrs from the relay’s HTTP API and passes them to Vite as **`VITE_BOOTSTRAP_PEERS`** so browsers can connect.
+3. Runs **`svelte-package`** and the **example Vite dev server** on port **5173**.
+
+First-time setup may require browser binaries:
+
+```bash
+npx playwright install chromium
+```
+
+**Reuse a running dev server** (you must still provide a relay and matching `VITE_BOOTSTRAP_PEERS` yourself if you skip the script):
+
+```bash
+PW_REUSE_SERVER=1 npm run test:e2e
+```
+
+Failed runs write HTML reports, screenshots, traces, and video under `test-results/` (see Playwright output for paths).
+
+**Signing mode in e2e:** set `E2E_SIGNING_MODE` to `worker`, `hardware-ed25519`, or `hardware-p256` (default in helpers is `worker`). CI runs the link-devices spec **three times** (matrix), one per mode.
+
+```bash
+E2E_SIGNING_MODE=hardware-ed25519 npm run test:e2e
+```
+
+## Dependencies
+
+- [`@le-space/orbitdb-identity-provider-webauthn-did`](https://github.com/Le-Space/orbitdb-identity-provider-webauthn-did) — WebAuthn crypto primitives
+- [`@storacha/client`](https://github.com/storacha/w3up) — Storacha storage client
+- [`orbitdb-storacha-bridge`](https://github.com/nicobao/orbitdb-storacha-bridge) — OrbitDB backup/restore
+- Forked `@le-space/ucanto-*` packages for WebAuthn Ed25519/P-256 UCAN support
+
+## License
+
+MIT

package/dist/backup/registry-backup.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Backup registry DB to Storacha via bridge.
+ * @param {Object} bridge - Initialized OrbitDBStorachaBridge instance
+ * @param {Object} orbitdb - OrbitDB instance
+ * @param {Object} registryDb - Registry database to backup
+ * @returns {Promise<{success: boolean, blocksUploaded?: number, blocksTotal?: number, error?: string}>}
+ */
+export function backupRegistryDb(bridge: Object, orbitdb: Object, registryDb: Object): Promise<{
+    success: boolean;
+    blocksUploaded?: number;
+    blocksTotal?: number;
+    error?: string;
+}>;
+/**
+ * Restore registry from Storacha backup.
+ * @param {Object} bridge - Initialized OrbitDBStorachaBridge instance
+ * @param {Object} orbitdb - OrbitDB instance
+ * @param {Object} [options]
+ * @returns {Promise<{success: boolean, database?: Object, entriesRecovered?: number, error?: string}>}
+ */
+export function restoreRegistryDb(bridge: Object, orbitdb: Object, options?: Object): Promise<{
+    success: boolean;
+    database?: Object;
+    entriesRecovered?: number;
+    error?: string;
+}>;

package/dist/backup/registry-backup.js

@@ -0,0 +1,51 @@
+/**
+ * Backup registry DB to Storacha via bridge.
+ * @param {Object} bridge - Initialized OrbitDBStorachaBridge instance
+ * @param {Object} orbitdb - OrbitDB instance
+ * @param {Object} registryDb - Registry database to backup
+ * @returns {Promise<{success: boolean, blocksUploaded?: number, blocksTotal?: number, error?: string}>}
+ */
+export async function backupRegistryDb(bridge, orbitdb, registryDb) {
+  try {
+    const result = await bridge.backup(orbitdb, registryDb.address);
+    return {
+      success: true,
+      blocksUploaded: result.blocksUploaded,
+      blocksTotal: result.blocksTotal,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+    };
+  }
+}
+
+/**
+ * Restore registry from Storacha backup.
+ * @param {Object} bridge - Initialized OrbitDBStorachaBridge instance
+ * @param {Object} orbitdb - OrbitDB instance
+ * @param {Object} [options]
+ * @returns {Promise<{success: boolean, database?: Object, entriesRecovered?: number, error?: string}>}
+ */
+export async function restoreRegistryDb(bridge, orbitdb, options = {}) {
+  try {
+    const result = await bridge.restoreFromSpace(orbitdb, {
+      timeout: 120000,
+      preferredDatabaseName: 'multi-device-registry',
+      restartAfterRestore: true,
+      verifyIntegrity: true,
+      ...options,
+    });
+    return {
+      success: true,
+      database: result.database,
+      entriesRecovered: result.entriesRecovered,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+    };
+  }
+}

package/dist/identity/identity-service.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Best-effort: this origin likely already has passkey / identity material (no WebAuthn prompt).
+ * Uses the same signals as restore paths — false negatives are OK (same handlers still apply).
+ *
+ * @returns {boolean}
+ */
+export function hasLocalPasskeyHint(): boolean;
+export class IdentityService {
+    /**
+     * Bind an OrbitDB registry database for credential storage.
+     * If pending credentials exist from a prior initialize() call, flushes them.
+     *
+     * @param {Object} db - OrbitDB KeyValue database (from openDeviceRegistry)
+     */
+    setRegistry(db: Object): Promise<void>;
+    /**
+     * Get the bound registry DB (or null).
+     * @returns {Object|null}
+     */
+    getRegistry(): Object | null;
+    /**
+     * Initialize identity — auto-detect hardware vs worker mode.
+     * If existing credentials found, restores them (may prompt biometric for worker PRF).
+     * If no credentials, creates new passkey.
+     *
+     * @param {'platform'|'cross-platform'} [authenticatorType]
+     * @param {{ preferWorkerMode?: boolean, signingPreference?: import('./signing-preference.js').SigningPreference }} [options]
+     * @returns {Promise<{ mode: string, did: string, algorithm: string }>}
+     */
+    initialize(authenticatorType?: "platform" | "cross-platform", options?: {
+        preferWorkerMode?: boolean;
+        signingPreference?: import("./signing-preference.js").SigningPreference;
+    }): Promise<{
+        mode: string;
+        did: string;
+        algorithm: string;
+    }>;
+    /**
+     * Force create a new identity (discards existing).
+     * @param {'platform'|'cross-platform'} [authenticatorType]
+     * @param {{ preferWorkerMode?: boolean, signingPreference?: import('./signing-preference.js').SigningPreference }} [options]
+     * @returns {Promise<{ mode: string, did: string, algorithm: string }>}
+     */
+    createNewIdentity(authenticatorType?: "platform" | "cross-platform", options?: {
+        preferWorkerMode?: boolean;
+        signingPreference?: import("./signing-preference.js").SigningPreference;
+    }): Promise<{
+        mode: string;
+        did: string;
+        algorithm: string;
+    }>;
+    /**
+     * Recovery entry point — uses discoverable credentials to derive IPNS key.
+     * Does NOT restore the DID — caller must resolve manifest and restore registry first.
+     * @returns {Promise<{ prfSeed: Uint8Array, ipnsKeyPair: Object, rawCredentialId: Uint8Array }>}
+     */
+    initializeFromRecovery(): Promise<{
+        prfSeed: Uint8Array;
+        ipnsKeyPair: Object;
+        rawCredentialId: Uint8Array;
+    }>;
+    /**
+     * Restore DID from an encrypted archive entry (from registry DB after recovery).
+     * Uses the PRF seed stored during initializeFromRecovery().
+     * @param {Object} archiveEntry - { ciphertext: string (hex), iv: string (hex) }
+     * @param {string} did - The owner DID from the manifest
+     * @returns {Promise<void>}
+     */
+    restoreFromManifest(archiveEntry: Object, did: string): Promise<void>;
+    /**
+     * Get current signing mode info.
+     * @returns {{ mode: string|null, did: string|null, algorithm: string|null, secure: boolean }}
+     */
+    getSigningMode(): {
+        mode: string | null;
+        did: string | null;
+        algorithm: string | null;
+        secure: boolean;
+    };
+    /**
+     * Get a UCAN-compatible principal/signer.
+     * For hardware mode: returns varsig signer via toUcantoSigner()
+     * For worker mode: returns Ed25519 principal from archive
+     *
+     * @returns {Promise<any>} UCAN signer
+     */
+    getPrincipal(): Promise<any>;
+    /**
+     * @returns {boolean}
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the derived IPNS keypair (available after initialize or recovery).
+     * @returns {{ privateKey: Object, publicKey: Object }|null}
+     */
+    getIPNSKeyPair(): {
+        privateKey: Object;
+        publicKey: Object;
+    } | null;
+    /**
+     * Get the stored PRF seed (available after initialize or recovery).
+     * @returns {Uint8Array|null}
+     */
+    getPrfSeed(): Uint8Array | null;
+    /**
+     * Get the encrypted archive data (ciphertext + iv as hex strings) for the current identity.
+     * Used by manifest publishing to upload the archive to IPFS for auth-free recovery.
+     *
+     * @returns {Promise<{ ciphertext: string, iv: string }|null>}
+     */
+    getEncryptedArchiveData(): Promise<{
+        ciphertext: string;
+        iv: string;
+    } | null>;
+    #private;
+}