@abraca/dabra 1.1.2 → 1.3.0

package/dist/index.d.ts

@@ -531,72 +531,105 @@ declare class AbracadabraClient {
 /**
  * CryptoIdentityKeystore
  *
- * Per-device Ed25519 keypair, private key protected by WebAuthn PRF + AES-256-GCM.
- * Stored in IndexedDB under "abracadabra:identity" / "identity" / key "current".
+ * Per-user Ed25519 keypair derived deterministically from a synced WebAuthn
+ * passkey's PRF extension output. The same passkey on any device produces the
+ * same identity — no private key storage needed.
  *
- * No private key is ever shared between devices. Each device generates its own
- * keypair, encrypts the private key with the PRF output from its own WebAuthn
- * credential, and stores the ciphertext in IndexedDB.
+ * Derivation chain:
+ *   Synced Passkey → PRF(constant salt) → HKDF-SHA256 → Ed25519 seed → keypair
  *
- * Dependencies: @noble/ed25519, @noble/hashes (for HKDF)
+ * IndexedDB is used only as a lightweight cache for the public key and
+ * credential ID. Loss of IndexedDB is non-catastrophic — a passkey assertion
+ * re-derives everything.
+ *
+ * Dependencies: @noble/ed25519, @noble/hashes (for HKDF), @noble/curves (for X25519)
  */
 declare class CryptoIdentityKeystore {
   /**
-   * One-time setup for a device: generates an Ed25519 keypair, creates a
-   * WebAuthn credential with PRF extension, encrypts the private key, and
-   * stores everything in IndexedDB.
-   *
-   * Returns the base64url-encoded public key. The caller must register this
-   * key with the server via POST /auth/register (first device) or
-   * POST /auth/keys (additional device).
+   * Check whether the platform supports WebAuthn with PRF extension.
+   * Call this before offering the "Secure with Passkey" option.
+   */
+  static isPrfAvailable(): Promise<boolean>;
+  /**
+   * Create a synced discoverable passkey and derive the Ed25519 identity from
+   * its PRF output. The passkey is stored in the platform credential manager
+   * (e.g. iCloud Keychain) and syncs across devices automatically.
    *
-   * @param username  - The user's account name.
-   * @param rpId      - WebAuthn relying party ID (e.g. "example.com").
-   * @param rpName    - Human-readable relying party name.
+   * Returns the base64url-encoded public key, X25519 public key, and credential ID.
+   * The caller must register the public key with the server.
    */
   register(username: string, rpId: string, rpName: string): Promise<{
     publicKey: string;
     x25519PublicKey: string;
+    credentialId: string;
   }>;
   /**
-   * Sign a base64url-encoded challenge using the stored Ed25519 private key.
-   *
-   * This triggers a WebAuthn assertion (biometric / PIN prompt) to unlock the
-   * private key via PRF → HKDF → AES-GCM decryption. The private key is
-   * wiped from memory after signing.
+   * Sign a base64url-encoded challenge using the Ed25519 key derived from
+   * a passkey assertion. Triggers a WebAuthn prompt (biometric / PIN).
    *
    * @param challengeB64 - base64url-encoded challenge bytes from the server.
+   * @param credentialIdHint - optional credential ID to select a specific passkey.
    * @returns base64url-encoded Ed25519 signature (64 bytes).
    */
-  sign(challengeB64: string): Promise<string>;
-  /** Returns the stored base64url public key, or null if no identity exists. */
-  getPublicKey(): Promise<string | null>;
+  sign(challengeB64: string, credentialIdHint?: string): Promise<string>;
   /**
-   * Returns the locally-stored internal username label, or null if no identity exists.
+   * Returns the cached base64url public key, or null if no identity is cached.
    *
-   * This is NOT the auth identifier (the public key is). It can be used as a
-   * hint when calling POST /auth/register, or displayed before the user sets
-   * a real display name via PATCH /users/me.
+   * Does NOT trigger a WebAuthn prompt. If the cache is empty (e.g. IndexedDB
+   * cleared), returns null — the identity can be recovered via sign() or
+   * a fresh register() with the same synced passkey.
    */
-  getUsername(): Promise<string | null>;
-  /** Returns true if an identity is stored in IndexedDB. */
+  getPublicKey(credentialIdHint?: string): Promise<string | null>;
+  /**
+   * Returns the locally-cached username label, or null if no identity is cached.
+   */
+  getUsername(credentialIdHint?: string): Promise<string | null>;
+  /**
+   * Updates the cached username for a given credential (or the first cached identity).
+   * Call this after the user sets/changes their display name so it persists across devices.
+   */
+  setUsername(username: string, credentialIdHint?: string): Promise<void>;
+  /** Returns true if an identity is cached in IndexedDB. */
   hasIdentity(): Promise<boolean>;
-  /** Remove the stored identity from IndexedDB. */
+  /** Remove cached identity record(s) from IndexedDB. The passkey itself
+   *  remains in the platform credential store. */
   clear(): Promise<void>;
   /**
-   * Returns the X25519 public key derived from the stored Ed25519 private key.
-   * Does NOT require WebAuthn — computed from the stored encrypted key... actually
-   * we derive from the Ed25519 public key directly (Montgomery form), no decryption needed
-   * since nobleEd25519Curves.utils.toMontgomery only needs the public key.
-   * Returns null if no identity is stored.
+   * Returns the X25519 public key derived from the cached Ed25519 public key.
+   * Does NOT require WebAuthn — computed from the cached public key only.
+   * Returns null if no identity is cached.
    */
   getX25519PublicKey(): Promise<Uint8Array | null>;
   /**
-   * Returns the X25519 private key derived from the stored Ed25519 private key.
-   * Requires WebAuthn assertion to decrypt the private key.
+   * Returns the X25519 private key derived from the Ed25519 seed.
+   * Requires a WebAuthn assertion to get the PRF output.
    * The caller MUST wipe the returned Uint8Array after use.
    */
-  getX25519PrivateKey(): Promise<Uint8Array>;
+  getX25519PrivateKey(credentialIdHint?: string): Promise<Uint8Array>;
+  /**
+   * Trigger a WebAuthn assertion to derive (or re-derive) the identity and
+   * update the IndexedDB cache. Returns the public key and credential ID.
+   *
+   * Use this when the cache is empty but you need the public key before
+   * signing (e.g. to send it to the server for the challenge request).
+   */
+  deriveIdentity(credentialIdHint?: string): Promise<{
+    publicKey: string;
+    credentialId: string;
+  }>;
+  /**
+   * List all cached credential IDs. Useful for account switching UI.
+   */
+  listCachedIdentities(): Promise<{
+    credentialId: string;
+    publicKey: string;
+    username: string;
+  }[]>;
+  /**
+   * Perform a WebAuthn assertion with PRF, derive the Ed25519 seed, and
+   * update the IndexedDB cache. Returns the seed (caller MUST wipe it).
+   */
+  private _assertAndDerive;
 }
 //#endregion
 //#region packages/provider/src/DocKeyManager.d.ts
@@ -1725,7 +1758,7 @@ interface BackgroundSyncManagerOptions {
   syncTimeout?: number;
   /** Pre-cache file blobs after syncing a doc. Default: true. */
   prefetchFiles?: boolean;
-  /** Delay (ms) between starting each doc sync to avoid server pressure. Default: 50. */
+  /** Delay (ms) between starting each doc sync to avoid server pressure. Default: 200. */
   throttleMs?: number;
   /** Max retries for failed docs within a single syncAll() run. Default: 2. */
   maxRetries?: number;
@@ -2032,7 +2065,7 @@ interface AbracadabraWebRTCConfiguration {
    * When provided, all data channel messages (except key-exchange) are
    * encrypted with AES-256-GCM using X25519 ECDH-derived session keys.
    */
-  e2ee?: E2EEIdentity;
+  e2ee?: E2EEIdentity | (() => Promise<E2EEIdentity>);
   /** WebSocket polyfill for signaling (e.g. for Node.js). */
   WebSocketPolyfill?: any;
 }
@@ -2093,6 +2126,9 @@ declare class AbracadabraWebRTC extends EventEmitter {
   private fileChannels;
   private e2eeChannels;
   private readonly config;
+  /** Cached resolved E2EE identity (lazily resolved from factory on first peer connect). */
+  private _resolvedE2ee;
+  private _resolveE2eePromise;
   readonly peers: Map<string, PeerState>;
   localPeerId: string | null;
   isConnected: boolean;
@@ -2129,6 +2165,8 @@ declare class AbracadabraWebRTC extends EventEmitter {
   private removePeer;
   private removeAllPeers;
   private createPeerConnection;
+  /** Resolve the E2EE identity, supporting both pre-resolved objects and lazy factories. */
+  private resolveE2ee;
   private attachDataHandlers;
   private startDataSync;
   private initiateConnection;
@@ -2502,8 +2540,8 @@ interface IdentityDocConfiguration {
    */
   webrtc?: {
     /** Server URL to use for signaling (any connected server works). */signalingServerUrl: string; /** Token for the signaling server. */
-    token: string | (() => string) | (() => Promise<string>); /** E2EE identity for the data channel. */
-    e2ee?: E2EEIdentity; /** ICE servers. */
+    token: string | (() => string) | (() => Promise<string>); /** E2EE identity for the data channel. Accepts a factory for lazy derivation. */
+    e2ee?: E2EEIdentity | (() => Promise<E2EEIdentity>); /** ICE servers. */
     iceServers?: RTCIceServer[];
   };
   /** Disable IndexedDB offline store. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/BackgroundSyncManager.ts

@@ -38,7 +38,7 @@ export interface BackgroundSyncManagerOptions {
 	syncTimeout?: number;
 	/** Pre-cache file blobs after syncing a doc. Default: true. */
 	prefetchFiles?: boolean;
-	/** Delay (ms) between starting each doc sync to avoid server pressure. Default: 50. */
+	/** Delay (ms) between starting each doc sync to avoid server pressure. Default: 200. */
 	throttleMs?: number;
 	/** Max retries for failed docs within a single syncAll() run. Default: 2. */
 	maxRetries?: number;
@@ -100,7 +100,7 @@ export class BackgroundSyncManager extends EventEmitter {
 			concurrency: opts?.concurrency ?? 2,
 			syncTimeout: opts?.syncTimeout ?? 15_000,
 			prefetchFiles: opts?.prefetchFiles ?? true,
-			throttleMs: opts?.throttleMs ?? 50,
+			throttleMs: opts?.throttleMs ?? 200,
 			maxRetries: opts?.maxRetries ?? 2,
 		};