@drakkar.software/starfish-client 3.0.0-alpha.16 → 3.0.0-alpha.18

package/dist/entitlements.js

@@ -0,0 +1,41 @@
+import { StarfishHttpError } from "./types.js";
+/**
+ * Fetches the list of feature slugs from a user's entitlement document.
+ *
+ * Returns an empty array if the document does not exist yet or the features
+ * field is absent — so callers never need to handle a 404.
+ *
+ * ```ts
+ * import { pullEntitlements } from "@drakkar.software/starfish-client"
+ *
+ * const features = await pullEntitlements(client, userId)
+ * // e.g. ["premium-package-1", "paid-cloud-sync"]
+ *
+ * if (features.includes("paid-cloud-sync")) {
+ *   // unlock cloud sync UI
+ * }
+ * ```
+ *
+ * The path template must match the server-side collection's `storagePath`.
+ * With the recommended default config:
+ * ```ts
+ * { storagePath: "users/{identity}/entitlements" }
+ * // → path: "/pull/users/{userId}/entitlements"  (default)
+ * ```
+ */
+export async function pullEntitlements(client, userId, opts) {
+    const path = (opts?.path ?? "/pull/users/{userId}/entitlements").replace("{userId}", userId);
+    const field = opts?.field ?? "features";
+    try {
+        const result = await client.pull(path);
+        const list = result.data?.[field];
+        if (!Array.isArray(list))
+            return [];
+        return list.filter((s) => typeof s === "string");
+    }
+    catch (err) {
+        if (err instanceof StarfishHttpError && err.status === 404)
+            return [];
+        throw err;
+    }
+}

package/dist/group-crypto.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Group encryption utilities for Starfish.
+ *
+ * Enables multiple users to share a common encrypted collection without sharing
+ * a passphrase. Each member holds their own credentials; a Group Encryption Key
+ * (GEK) is distributed per-member using X25519 ECDH key agreement.
+ *
+ * Typical flow:
+ *   1. Each user calls `deriveCredentials(passphrase)` — now includes groupPublicKey / groupPrivateKey.
+ *   2. Admin calls `createGroupKeyring(...)` to create a keyring document.
+ *   3. Members call `createGroupEncryptor(keyringData, myIdentity, myPrivateKey)` to get an Encryptor.
+ *   4. The Encryptor is passed to SyncManager via the `encryptor` option.
+ */
+import type { Encryptor } from "./crypto.js";
+/** An ECDH key pair used for group encryption. Hex-encoded for easy serialization. */
+export interface GroupKeyPair {
+    /** Hex-encoded X25519 private key (32 bytes). Keep secret — never store on server. */
+    privateKey: string;
+    /** Hex-encoded X25519 public key (32 bytes). Safe to publish. */
+    publicKey: string;
+}
+/** One epoch's wrapped keys: each member's GEK encrypted to their public key. */
+export interface EpochKeyring {
+    /** The admin's hex-encoded X25519 public key (used for ECDH by members). */
+    adminPublicKey: string;
+    /** Map from member identity (userId) → base64(IV || AES-GCM(GEK)) */
+    wrappedKeys: Record<string, string>;
+}
+/** The full keyring document stored in a Starfish collection. Push this with any SyncManager. */
+export interface GroupKeyring {
+    /** The epoch number currently used for new encryptions. */
+    currentEpoch: number;
+    /** All epochs. Members unwrap the GEK for whichever epoch a document was encrypted with. */
+    epochs: Record<string, EpochKeyring>;
+}
+/**
+ * Derives a deterministic X25519 key pair from a passphrase + userId.
+ *
+ * The derivation uses SHA-256 with a fixed domain separator so it is distinct
+ * from the auth token and encryption key derivations. Same passphrase + userId
+ * always produces the same key pair on any device (stateless).
+ */
+export declare function deriveGroupKeyPair(passphrase: string, userId: string): Promise<GroupKeyPair>;
+/** Generates a random 256-bit Group Encryption Key as a hex string. */
+export declare function generateGroupKey(): string;
+/**
+ * Wraps a GEK for a specific member using ECDH key agreement.
+ *
+ * The wrapper (admin) and member each have an X25519 key pair. ECDH between
+ * `wrapperPrivateKey` and `memberPublicKey` produces a shared secret, which is
+ * used to derive an AES-256-GCM key that encrypts the GEK.
+ *
+ * @returns base64(IV || AES-GCM-ciphertext)
+ */
+export declare function wrapGroupKey(gek: string, memberPublicKey: string, wrapperPrivateKey: string): Promise<string>;
+/**
+ * Unwraps a GEK using the member's own private key and the admin's public key.
+ *
+ * ECDH between `memberPrivateKey` and `adminPublicKey` yields the same shared
+ * secret as the wrapping step, so the same AES key is derived and the GEK is
+ * recovered.
+ *
+ * @returns GEK as a hex string
+ */
+export declare function unwrapGroupKey(wrapped: string, memberPrivateKey: string, adminPublicKey: string): Promise<string>;
+/**
+ * Creates a new group keyring document with epoch 1.
+ *
+ * @param adminKeyPair  The admin's key pair (from `deriveGroupKeyPair` or `deriveCredentials`)
+ * @param members       Map from member identity (userId) → hex public key
+ * @param gek           Optional GEK to use; generated randomly if omitted
+ * @returns             The keyring document and the raw GEK (admin keeps the GEK to add future members)
+ */
+export declare function createGroupKeyring(adminKeyPair: GroupKeyPair, members: Record<string, string>, gek?: string): Promise<{
+    keyring: GroupKeyring;
+    gek: string;
+}>;
+/**
+ * Adds a new member to the current epoch of an existing keyring.
+ *
+ * The admin supplies the current GEK (returned by `createGroupKeyring` or
+ * `rotateGroupKey`) and their key pair to wrap it for the new member.
+ * This does NOT rotate the GEK — the new member can read all existing
+ * documents encrypted with the current epoch key.
+ *
+ * Only the admin (whose `publicKey` matches `epochKeyring.adminPublicKey`) can
+ * add members, because all wrapped entries must use the same ECDH key pair.
+ */
+export declare function addGroupMember(keyring: GroupKeyring, adminKeyPair: GroupKeyPair, currentGek: string, newMemberId: string, newMemberPublicKey: string): Promise<GroupKeyring>;
+/**
+ * Rotates the group key, creating a new epoch.
+ *
+ * Used when removing a member. The removed member retains their old epoch key
+ * (and can still read old documents), but cannot read new documents.
+ *
+ * @param remainingMembers  Map from identity → hex public key for members who keep access
+ */
+export declare function rotateGroupKey(keyring: GroupKeyring, adminKeyPair: GroupKeyPair, remainingMembers: Record<string, string>, newGek?: string): Promise<{
+    keyring: GroupKeyring;
+    gek: string;
+}>;
+/**
+ * Creates an Encryptor that can decrypt any epoch and encrypts with the current epoch.
+ *
+ * Wire format: `{ _encrypted: "base64(IV || ciphertext)", _epoch: N }`
+ *
+ * @param keyring         The keyring document fetched from Starfish
+ * @param myIdentity      The caller's userId (to locate their wrapped key in each epoch)
+ * @param myPrivateKey    The caller's hex-encoded X25519 private key
+ */
+export declare function createGroupEncryptor(keyring: GroupKeyring, myIdentity: string, myPrivateKey: string): Promise<Encryptor>;

package/dist/group-crypto.js

@@ -0,0 +1,205 @@
+// src/group-crypto.ts
+import { x25519 } from "@noble/curves/ed25519.js";
+import { getCrypto as getCrypto2, getBase64 as getBase642, IV_BYTES as IV_BYTES2, deriveKey as deriveKey2 } from "@drakkar.software/starfish-protocol";
+
+// src/crypto.ts
+import { getCrypto, getBase64, IV_BYTES, ENCRYPTED_KEY, deriveKey } from "@drakkar.software/starfish-protocol";
+var ALGO = "AES-GCM";
+function createEncryptor(secret, salt, info = "starfish-e2e") {
+  if (!secret) throw new Error("encryptionSecret must not be empty");
+  if (!salt) throw new Error("encryptionSalt must not be empty");
+  const keyPromise = deriveKey(secret, salt, info);
+  return {
+    async encrypt(data) {
+      const key = await keyPromise;
+      const c = getCrypto();
+      const b64 = getBase64();
+      const plaintext = new TextEncoder().encode(JSON.stringify(data));
+      const iv = c.getRandomValues(new Uint8Array(IV_BYTES));
+      const ciphertext = await c.subtle.encrypt({ name: ALGO, iv }, key, plaintext);
+      const combined = new Uint8Array(iv.length + ciphertext.byteLength);
+      combined.set(iv);
+      combined.set(new Uint8Array(ciphertext), iv.length);
+      return { [ENCRYPTED_KEY]: b64.encode(combined) };
+    },
+    async decrypt(wrapper) {
+      const encoded = wrapper[ENCRYPTED_KEY];
+      if (typeof encoded !== "string") {
+        throw new Error("Expected encrypted data but received unencrypted document");
+      }
+      const key = await keyPromise;
+      const c = getCrypto();
+      const b64 = getBase64();
+      const combined = b64.decode(encoded);
+      if (combined.length < IV_BYTES) {
+        throw new Error("Encrypted data is too short");
+      }
+      const iv = combined.slice(0, IV_BYTES);
+      const ciphertext = combined.slice(IV_BYTES);
+      try {
+        const plaintext = await c.subtle.decrypt({ name: ALGO, iv }, key, ciphertext);
+        return JSON.parse(new TextDecoder().decode(plaintext));
+      } catch (err) {
+        throw new Error("Decryption failed: data may be tampered or key is incorrect", { cause: err });
+      }
+    }
+  };
+}
+
+// src/group-crypto.ts
+function bytesToHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+var ALGO2 = "AES-GCM";
+var GROUP_WRAP_SALT = "starfish-group-wrap";
+var GROUP_WRAP_INFO = "starfish-group-wrap";
+var GROUP_ECDH_DOMAIN = "starfish-group-ecdh";
+var GROUP_DATA_INFO = "starfish-group";
+var GEK_BYTES = 32;
+async function deriveGroupKeyPair(passphrase, userId) {
+  const c = getCrypto2();
+  const enc = new TextEncoder();
+  const input = enc.encode(`${passphrase}:${userId}:${GROUP_ECDH_DOMAIN}`);
+  const hash = await c.subtle.digest("SHA-256", input);
+  const privateKeyBytes = new Uint8Array(hash);
+  const publicKeyBytes = x25519.getPublicKey(privateKeyBytes);
+  return { privateKey: bytesToHex(privateKeyBytes), publicKey: bytesToHex(publicKeyBytes) };
+}
+function generateGroupKey() {
+  const c = getCrypto2();
+  return bytesToHex(c.getRandomValues(new Uint8Array(GEK_BYTES)));
+}
+async function wrapGroupKey(gek, memberPublicKey, wrapperPrivateKey) {
+  const sharedSecret = x25519.getSharedSecret(hexToBytes(wrapperPrivateKey), hexToBytes(memberPublicKey));
+  const wrappingKey = await deriveKey2(bytesToHex(sharedSecret), GROUP_WRAP_SALT, GROUP_WRAP_INFO);
+  const c = getCrypto2();
+  const b64 = getBase642();
+  const iv = c.getRandomValues(new Uint8Array(IV_BYTES2));
+  const encrypted = await c.subtle.encrypt({ name: ALGO2, iv }, wrappingKey, hexToBytes(gek).buffer);
+  const combined = new Uint8Array(IV_BYTES2 + encrypted.byteLength);
+  combined.set(iv);
+  combined.set(new Uint8Array(encrypted), IV_BYTES2);
+  return b64.encode(combined);
+}
+async function unwrapGroupKey(wrapped, memberPrivateKey, adminPublicKey) {
+  const sharedSecret = x25519.getSharedSecret(hexToBytes(memberPrivateKey), hexToBytes(adminPublicKey));
+  const wrappingKey = await deriveKey2(bytesToHex(sharedSecret), GROUP_WRAP_SALT, GROUP_WRAP_INFO);
+  const b64 = getBase642();
+  const c = getCrypto2();
+  const combined = b64.decode(wrapped);
+  const iv = combined.slice(0, IV_BYTES2);
+  const ciphertext = combined.slice(IV_BYTES2);
+  try {
+    const decrypted = await c.subtle.decrypt({ name: ALGO2, iv }, wrappingKey, ciphertext);
+    return bytesToHex(new Uint8Array(decrypted));
+  } catch {
+    throw new Error("Failed to unwrap group key: decryption failed (wrong keys or corrupted data)");
+  }
+}
+async function createGroupKeyring(adminKeyPair, members, gek) {
+  const resolvedGek = gek ?? generateGroupKey();
+  const wrappedKeys = {};
+  for (const [memberId, memberPublicKey] of Object.entries(members)) {
+    wrappedKeys[memberId] = await wrapGroupKey(resolvedGek, memberPublicKey, adminKeyPair.privateKey);
+  }
+  const keyring = {
+    currentEpoch: 1,
+    epochs: {
+      "1": { adminPublicKey: adminKeyPair.publicKey, wrappedKeys }
+    }
+  };
+  return { keyring, gek: resolvedGek };
+}
+async function addGroupMember(keyring, adminKeyPair, currentGek, newMemberId, newMemberPublicKey) {
+  const epochKey = String(keyring.currentEpoch);
+  const epochKeyring = keyring.epochs[epochKey];
+  if (!epochKeyring) throw new Error(`Epoch ${keyring.currentEpoch} not found in keyring`);
+  if (epochKeyring.adminPublicKey !== adminKeyPair.publicKey) {
+    throw new Error(`Provided key pair does not match the admin public key stored in epoch ${keyring.currentEpoch}`);
+  }
+  const wrapped = await wrapGroupKey(currentGek, newMemberPublicKey, adminKeyPair.privateKey);
+  return {
+    ...keyring,
+    epochs: {
+      ...keyring.epochs,
+      [epochKey]: {
+        ...epochKeyring,
+        wrappedKeys: { ...epochKeyring.wrappedKeys, [newMemberId]: wrapped }
+      }
+    }
+  };
+}
+async function rotateGroupKey(keyring, adminKeyPair, remainingMembers, newGek) {
+  const epochKey = String(keyring.currentEpoch);
+  const epochKeyring = keyring.epochs[epochKey];
+  if (epochKeyring && epochKeyring.adminPublicKey !== adminKeyPair.publicKey) {
+    throw new Error(
+      `Provided key pair does not match the admin public key stored in epoch ${keyring.currentEpoch}`
+    );
+  }
+  const resolvedGek = newGek ?? generateGroupKey();
+  const newEpoch = keyring.currentEpoch + 1;
+  const wrappedKeys = {};
+  for (const [memberId, memberPublicKey] of Object.entries(remainingMembers)) {
+    wrappedKeys[memberId] = await wrapGroupKey(resolvedGek, memberPublicKey, adminKeyPair.privateKey);
+  }
+  const newKeyring = {
+    currentEpoch: newEpoch,
+    epochs: {
+      ...keyring.epochs,
+      [String(newEpoch)]: { adminPublicKey: adminKeyPair.publicKey, wrappedKeys }
+    }
+  };
+  return { keyring: newKeyring, gek: resolvedGek };
+}
+async function createGroupEncryptor(keyring, myIdentity, myPrivateKey) {
+  const epochEncryptors = /* @__PURE__ */ new Map();
+  for (const [epochStr, epochKeyring] of Object.entries(keyring.epochs)) {
+    const epoch = parseInt(epochStr, 10);
+    const wrapped = epochKeyring.wrappedKeys[myIdentity];
+    if (!wrapped) continue;
+    const gek = await unwrapGroupKey(wrapped, myPrivateKey, epochKeyring.adminPublicKey);
+    epochEncryptors.set(epoch, createEncryptor(gek, `epoch-${epoch}`, GROUP_DATA_INFO));
+  }
+  const currentEpoch = keyring.currentEpoch;
+  const currentEncryptor = epochEncryptors.get(currentEpoch);
+  if (!currentEncryptor) {
+    throw new Error(
+      `No wrapped key found for identity "${myIdentity}" in epoch ${currentEpoch}. Ensure the admin has added this member to the keyring.`
+    );
+  }
+  return {
+    async encrypt(data) {
+      const encrypted = await currentEncryptor.encrypt(data);
+      return { ...encrypted, _epoch: currentEpoch };
+    },
+    async decrypt(wrapper) {
+      const epoch = typeof wrapper._epoch === "number" ? wrapper._epoch : currentEpoch;
+      const encryptor = epochEncryptors.get(epoch);
+      if (!encryptor) {
+        throw new Error(
+          `No key available for epoch ${epoch}. This document was encrypted in a different epoch. Ensure your keyring is up to date.`
+        );
+      }
+      return encryptor.decrypt(wrapper);
+    }
+  };
+}
+export {
+  addGroupMember,
+  createGroupEncryptor,
+  createGroupKeyring,
+  deriveGroupKeyPair,
+  generateGroupKey,
+  rotateGroupKey,
+  unwrapGroupKey,
+  wrapGroupKey
+};
+//# sourceMappingURL=group-crypto.js.map

package/dist/group-crypto.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/group-crypto.ts", "../src/crypto.ts"],
+  "sourcesContent": ["/**\n * Group encryption utilities for Starfish.\n *\n * Enables multiple users to share a common encrypted collection without sharing\n * a passphrase. Each member holds their own credentials; a Group Encryption Key\n * (GEK) is distributed per-member using X25519 ECDH key agreement.\n *\n * Typical flow:\n *   1. Each user calls `deriveCredentials(passphrase)` \u2014 now includes groupPublicKey / groupPrivateKey.\n *   2. Admin calls `createGroupKeyring(...)` to create a keyring document.\n *   3. Members call `createGroupEncryptor(keyringData, myIdentity, myPrivateKey)` to get an Encryptor.\n *   4. The Encryptor is passed to SyncManager via the `encryptor` option.\n */\n\nimport { x25519 } from \"@noble/curves/ed25519.js\"\nimport { getCrypto, getBase64, IV_BYTES, deriveKey } from \"@drakkar.software/starfish-protocol\"\nimport type { Encryptor } from \"./crypto.js\"\nimport { createEncryptor } from \"./crypto.js\"\n\n// \u2500\u2500 Internal helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nfunction bytesToHex(bytes: Uint8Array): string {\n  return Array.from(bytes, (b) => b.toString(16).padStart(2, \"0\")).join(\"\")\n}\n\nfunction hexToBytes(hex: string): Uint8Array {\n  const bytes = new Uint8Array(hex.length / 2)\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)\n  }\n  return bytes\n}\n\nconst ALGO = \"AES-GCM\"\nconst GROUP_WRAP_SALT = \"starfish-group-wrap\"\nconst GROUP_WRAP_INFO = \"starfish-group-wrap\"\nconst GROUP_ECDH_DOMAIN = \"starfish-group-ecdh\"\nconst GROUP_DATA_INFO = \"starfish-group\"\nconst GEK_BYTES = 32\n\n// \u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/** An ECDH key pair used for group encryption. Hex-encoded for easy serialization. */\nexport interface GroupKeyPair {\n  /** Hex-encoded X25519 private key (32 bytes). Keep secret \u2014 never store on server. */\n  privateKey: string\n  /** Hex-encoded X25519 public key (32 bytes). Safe to publish. */\n  publicKey: string\n}\n\n/** One epoch's wrapped keys: each member's GEK encrypted to their public key. */\nexport interface EpochKeyring {\n  /** The admin's hex-encoded X25519 public key (used for ECDH by members). */\n  adminPublicKey: string\n  /** Map from member identity (userId) \u2192 base64(IV || AES-GCM(GEK)) */\n  wrappedKeys: Record<string, string>\n}\n\n/** The full keyring document stored in a Starfish collection. Push this with any SyncManager. */\nexport interface GroupKeyring {\n  /** The epoch number currently used for new encryptions. */\n  currentEpoch: number\n  /** All epochs. Members unwrap the GEK for whichever epoch a document was encrypted with. */\n  epochs: Record<string, EpochKeyring>\n}\n\n// \u2500\u2500 Key derivation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Derives a deterministic X25519 key pair from a passphrase + userId.\n *\n * The derivation uses SHA-256 with a fixed domain separator so it is distinct\n * from the auth token and encryption key derivations. Same passphrase + userId\n * always produces the same key pair on any device (stateless).\n */\nexport async function deriveGroupKeyPair(passphrase: string, userId: string): Promise<GroupKeyPair> {\n  const c = getCrypto()\n  const enc = new TextEncoder()\n  const input = enc.encode(`${passphrase}:${userId}:${GROUP_ECDH_DOMAIN}`)\n  const hash = await c.subtle.digest(\"SHA-256\", input)\n  const privateKeyBytes = new Uint8Array(hash)\n  const publicKeyBytes = x25519.getPublicKey(privateKeyBytes)\n  return { privateKey: bytesToHex(privateKeyBytes), publicKey: bytesToHex(publicKeyBytes) }\n}\n\n// \u2500\u2500 GEK generation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/** Generates a random 256-bit Group Encryption Key as a hex string. */\nexport function generateGroupKey(): string {\n  const c = getCrypto()\n  return bytesToHex(c.getRandomValues(new Uint8Array(GEK_BYTES)))\n}\n\n// \u2500\u2500 Key wrapping / unwrapping \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Wraps a GEK for a specific member using ECDH key agreement.\n *\n * The wrapper (admin) and member each have an X25519 key pair. ECDH between\n * `wrapperPrivateKey` and `memberPublicKey` produces a shared secret, which is\n * used to derive an AES-256-GCM key that encrypts the GEK.\n *\n * @returns base64(IV || AES-GCM-ciphertext)\n */\nexport async function wrapGroupKey(\n  gek: string,\n  memberPublicKey: string,\n  wrapperPrivateKey: string,\n): Promise<string> {\n  const sharedSecret = x25519.getSharedSecret(hexToBytes(wrapperPrivateKey), hexToBytes(memberPublicKey))\n  const wrappingKey = await deriveKey(bytesToHex(sharedSecret), GROUP_WRAP_SALT, GROUP_WRAP_INFO)\n\n  const c = getCrypto()\n  const b64 = getBase64()\n  const iv = c.getRandomValues(new Uint8Array(IV_BYTES))\n  const encrypted = await c.subtle.encrypt({ name: ALGO, iv }, wrappingKey, hexToBytes(gek).buffer as ArrayBuffer)\n\n  const combined = new Uint8Array(IV_BYTES + encrypted.byteLength)\n  combined.set(iv)\n  combined.set(new Uint8Array(encrypted), IV_BYTES)\n  return b64.encode(combined)\n}\n\n/**\n * Unwraps a GEK using the member's own private key and the admin's public key.\n *\n * ECDH between `memberPrivateKey` and `adminPublicKey` yields the same shared\n * secret as the wrapping step, so the same AES key is derived and the GEK is\n * recovered.\n *\n * @returns GEK as a hex string\n */\nexport async function unwrapGroupKey(\n  wrapped: string,\n  memberPrivateKey: string,\n  adminPublicKey: string,\n): Promise<string> {\n  const sharedSecret = x25519.getSharedSecret(hexToBytes(memberPrivateKey), hexToBytes(adminPublicKey))\n  const wrappingKey = await deriveKey(bytesToHex(sharedSecret), GROUP_WRAP_SALT, GROUP_WRAP_INFO)\n\n  const b64 = getBase64()\n  const c = getCrypto()\n  const combined = b64.decode(wrapped)\n  const iv = combined.slice(0, IV_BYTES)\n  const ciphertext = combined.slice(IV_BYTES)\n  try {\n    const decrypted = await c.subtle.decrypt({ name: ALGO, iv }, wrappingKey, ciphertext)\n    return bytesToHex(new Uint8Array(decrypted))\n  } catch {\n    throw new Error(\"Failed to unwrap group key: decryption failed (wrong keys or corrupted data)\")\n  }\n}\n\n// \u2500\u2500 Keyring management \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Creates a new group keyring document with epoch 1.\n *\n * @param adminKeyPair  The admin's key pair (from `deriveGroupKeyPair` or `deriveCredentials`)\n * @param members       Map from member identity (userId) \u2192 hex public key\n * @param gek           Optional GEK to use; generated randomly if omitted\n * @returns             The keyring document and the raw GEK (admin keeps the GEK to add future members)\n */\nexport async function createGroupKeyring(\n  adminKeyPair: GroupKeyPair,\n  members: Record<string, string>,\n  gek?: string,\n): Promise<{ keyring: GroupKeyring; gek: string }> {\n  const resolvedGek = gek ?? generateGroupKey()\n  const wrappedKeys: Record<string, string> = {}\n  for (const [memberId, memberPublicKey] of Object.entries(members)) {\n    wrappedKeys[memberId] = await wrapGroupKey(resolvedGek, memberPublicKey, adminKeyPair.privateKey)\n  }\n  const keyring: GroupKeyring = {\n    currentEpoch: 1,\n    epochs: {\n      \"1\": { adminPublicKey: adminKeyPair.publicKey, wrappedKeys },\n    },\n  }\n  return { keyring, gek: resolvedGek }\n}\n\n/**\n * Adds a new member to the current epoch of an existing keyring.\n *\n * The admin supplies the current GEK (returned by `createGroupKeyring` or\n * `rotateGroupKey`) and their key pair to wrap it for the new member.\n * This does NOT rotate the GEK \u2014 the new member can read all existing\n * documents encrypted with the current epoch key.\n *\n * Only the admin (whose `publicKey` matches `epochKeyring.adminPublicKey`) can\n * add members, because all wrapped entries must use the same ECDH key pair.\n */\nexport async function addGroupMember(\n  keyring: GroupKeyring,\n  adminKeyPair: GroupKeyPair,\n  currentGek: string,\n  newMemberId: string,\n  newMemberPublicKey: string,\n): Promise<GroupKeyring> {\n  const epochKey = String(keyring.currentEpoch)\n  const epochKeyring = keyring.epochs[epochKey]\n  if (!epochKeyring) throw new Error(`Epoch ${keyring.currentEpoch} not found in keyring`)\n  if (epochKeyring.adminPublicKey !== adminKeyPair.publicKey) {\n    throw new Error(`Provided key pair does not match the admin public key stored in epoch ${keyring.currentEpoch}`)\n  }\n\n  const wrapped = await wrapGroupKey(currentGek, newMemberPublicKey, adminKeyPair.privateKey)\n\n  return {\n    ...keyring,\n    epochs: {\n      ...keyring.epochs,\n      [epochKey]: {\n        ...epochKeyring,\n        wrappedKeys: { ...epochKeyring.wrappedKeys, [newMemberId]: wrapped },\n      },\n    },\n  }\n}\n\n/**\n * Rotates the group key, creating a new epoch.\n *\n * Used when removing a member. The removed member retains their old epoch key\n * (and can still read old documents), but cannot read new documents.\n *\n * @param remainingMembers  Map from identity \u2192 hex public key for members who keep access\n */\nexport async function rotateGroupKey(\n  keyring: GroupKeyring,\n  adminKeyPair: GroupKeyPair,\n  remainingMembers: Record<string, string>,\n  newGek?: string,\n): Promise<{ keyring: GroupKeyring; gek: string }> {\n  const epochKey = String(keyring.currentEpoch)\n  const epochKeyring = keyring.epochs[epochKey]\n  if (epochKeyring && epochKeyring.adminPublicKey !== adminKeyPair.publicKey) {\n    throw new Error(\n      `Provided key pair does not match the admin public key stored in epoch ${keyring.currentEpoch}`,\n    )\n  }\n  const resolvedGek = newGek ?? generateGroupKey()\n  const newEpoch = keyring.currentEpoch + 1\n  const wrappedKeys: Record<string, string> = {}\n  for (const [memberId, memberPublicKey] of Object.entries(remainingMembers)) {\n    wrappedKeys[memberId] = await wrapGroupKey(resolvedGek, memberPublicKey, adminKeyPair.privateKey)\n  }\n  const newKeyring: GroupKeyring = {\n    currentEpoch: newEpoch,\n    epochs: {\n      ...keyring.epochs,\n      [String(newEpoch)]: { adminPublicKey: adminKeyPair.publicKey, wrappedKeys },\n    },\n  }\n  return { keyring: newKeyring, gek: resolvedGek }\n}\n\n// \u2500\u2500 Encryptor factory \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Creates an Encryptor that can decrypt any epoch and encrypts with the current epoch.\n *\n * Wire format: `{ _encrypted: \"base64(IV || ciphertext)\", _epoch: N }`\n *\n * @param keyring         The keyring document fetched from Starfish\n * @param myIdentity      The caller's userId (to locate their wrapped key in each epoch)\n * @param myPrivateKey    The caller's hex-encoded X25519 private key\n */\nexport async function createGroupEncryptor(\n  keyring: GroupKeyring,\n  myIdentity: string,\n  myPrivateKey: string,\n): Promise<Encryptor> {\n  // Unwrap GEK for each epoch we have a key for\n  const epochEncryptors = new Map<number, Encryptor>()\n  for (const [epochStr, epochKeyring] of Object.entries(keyring.epochs)) {\n    const epoch = parseInt(epochStr, 10)\n    const wrapped = epochKeyring.wrappedKeys[myIdentity]\n    if (!wrapped) continue\n    const gek = await unwrapGroupKey(wrapped, myPrivateKey, epochKeyring.adminPublicKey)\n    epochEncryptors.set(epoch, createEncryptor(gek, `epoch-${epoch}`, GROUP_DATA_INFO))\n  }\n\n  const currentEpoch = keyring.currentEpoch\n  const currentEncryptor = epochEncryptors.get(currentEpoch)\n  if (!currentEncryptor) {\n    throw new Error(\n      `No wrapped key found for identity \"${myIdentity}\" in epoch ${currentEpoch}. ` +\n        `Ensure the admin has added this member to the keyring.`,\n    )\n  }\n\n  return {\n    async encrypt(data: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const encrypted = await currentEncryptor.encrypt(data)\n      return { ...encrypted, _epoch: currentEpoch }\n    },\n\n    async decrypt(wrapper: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const epoch = typeof wrapper._epoch === \"number\" ? wrapper._epoch : currentEpoch\n      const encryptor = epochEncryptors.get(epoch)\n      if (!encryptor) {\n        throw new Error(\n          `No key available for epoch ${epoch}. ` +\n            `This document was encrypted in a different epoch. ` +\n            `Ensure your keyring is up to date.`,\n        )\n      }\n      return encryptor.decrypt(wrapper)\n    },\n  }\n}\n", "import { getCrypto, getBase64, IV_BYTES, ENCRYPTED_KEY, deriveKey } from \"@drakkar.software/starfish-protocol\"\n\nconst ALGO = \"AES-GCM\"\n\nexport { ENCRYPTED_KEY }\n\n/** Encrypt/decrypt interface for client-side E2E encryption. */\nexport interface Encryptor {\n  encrypt(data: Record<string, unknown>): Promise<Record<string, unknown>>\n  decrypt(wrapper: Record<string, unknown>): Promise<Record<string, unknown>>\n}\n\n/**\n * Creates an Encryptor that uses AES-256-GCM with HKDF-derived keys.\n */\nexport function createEncryptor(secret: string, salt: string, info: string = \"starfish-e2e\"): Encryptor {\n  if (!secret) throw new Error(\"encryptionSecret must not be empty\")\n  if (!salt) throw new Error(\"encryptionSalt must not be empty\")\n  const keyPromise = deriveKey(secret, salt, info)\n\n  return {\n    async encrypt(data: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const key = await keyPromise\n      const c = getCrypto()\n      const b64 = getBase64()\n      const plaintext = new TextEncoder().encode(JSON.stringify(data))\n      const iv = c.getRandomValues(new Uint8Array(IV_BYTES))\n      const ciphertext = await c.subtle.encrypt({ name: ALGO, iv }, key, plaintext)\n\n      const combined = new Uint8Array(iv.length + ciphertext.byteLength)\n      combined.set(iv)\n      combined.set(new Uint8Array(ciphertext), iv.length)\n\n      return { [ENCRYPTED_KEY]: b64.encode(combined) }\n    },\n\n    async decrypt(wrapper: Record<string, unknown>): Promise<Record<string, unknown>> {\n      const encoded = wrapper[ENCRYPTED_KEY]\n      if (typeof encoded !== \"string\") {\n        throw new Error(\"Expected encrypted data but received unencrypted document\")\n      }\n\n      const key = await keyPromise\n      const c = getCrypto()\n      const b64 = getBase64()\n      const combined = b64.decode(encoded)\n      if (combined.length < IV_BYTES) {\n        throw new Error(\"Encrypted data is too short\")\n      }\n      const iv = combined.slice(0, IV_BYTES)\n      const ciphertext = combined.slice(IV_BYTES)\n      try {\n        const plaintext = await c.subtle.decrypt({ name: ALGO, iv }, key, ciphertext)\n        return JSON.parse(new TextDecoder().decode(plaintext))\n      } catch (err) {\n        throw new Error(\"Decryption failed: data may be tampered or key is incorrect\", { cause: err })\n      }\n    },\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["getCrypto", "getBase64", "IV_BYTES", "deriveKey", "ALGO", "getCrypto", "deriveKey", "getBase64", "IV_BYTES"]
+}

package/dist/identity.d.ts

@@ -1,6 +1,84 @@
+declare const WORDLIST: string[];
+/** Credentials derived from a passphrase. Pass directly to SyncManager / StarfishClient. */
+export interface DerivedCredentials {
+    /** Hex-encoded auth token. Use as `Bearer ${authToken}` in request headers. */
+    authToken: string;
+    /**
+     * Short identifier derived from the auth token (first 16 hex chars = 8 bytes).
+     * Used as the user/namespace segment in collection paths.
+     */
+    userId: string;
+    /**
+     * Hex-encoded key suitable as `encryptionSecret` for SyncManager.
+     * Combined with `encryptionSalt` to derive the AES-256-GCM key via HKDF.
+     */
+    encryptionSecret: string;
+    /**
+     * Value suitable as `encryptionSalt` for SyncManager. Equals `userId`.
+     * Using a per-identity salt ensures that even if two users share a passphrase,
+     * their encryption keys are different.
+     */
+    encryptionSalt: string;
+    /**
+     * Hex-encoded X25519 public key for group encryption.
+     * Publish this so group admins can wrap the Group Encryption Key (GEK) for you.
+     * Safe to store in a public Starfish document.
+     */
+    groupPublicKey: string;
+    /**
+     * Hex-encoded X25519 private key for group encryption.
+     * Used to unwrap the GEK from a keyring document.
+     * Never transmit this — keep it in memory or derive it from the passphrase.
+     */
+    groupPrivateKey: string;
+}
 /**
- * Phase-2 transitional shim. The implementation lives in
- * `@drakkar.software/starfish-identities`. Removed in Phase 3.
+ * Generates a cryptographically random passphrase from the built-in 256-word list.
+ *
+ * Each word represents one byte of entropy (256 words = one byte per word, zero modulo bias).
+ * A 12-word passphrase gives 96 bits of entropy — stronger than a random UUID.
+ *
+ * @param wordCount Number of words (default: 12).
+ * @param wordlist Custom word list (must have exactly 256 entries).
  */
-export { deriveRootIdentity } from "@drakkar.software/starfish-identities";
-export type { RootIdentity, RootKeyPair } from "@drakkar.software/starfish-identities";
+export declare function generatePassphrase(wordCount?: number, wordlist?: string[]): string;
+/**
+ * Derives auth credentials from a passphrase.
+ *
+ * All derivations are deterministic — the same passphrase always produces the same credentials.
+ * Sharing the passphrase grants access on any device.
+ *
+ * The returned values map directly to Starfish options:
+ * ```ts
+ * const creds = await deriveCredentials(passphrase)
+ *
+ * const client = new StarfishClient({
+ *   baseUrl: serverUrl,
+ *   auth: () => ({ Authorization: `Bearer ${creds.authToken}` }),
+ * })
+ * const syncManager = new SyncManager({
+ *   client,
+ *   pullPath: `/pull/${creds.userId}/wedding`,
+ *   pushPath: `/push/${creds.userId}/wedding`,
+ *   encryptionSecret: creds.encryptionSecret,
+ *   encryptionSalt: creds.encryptionSalt,
+ * })
+ * ```
+ */
+export declare function deriveCredentials(passphrase: string): Promise<DerivedCredentials>;
+/**
+ * Encodes an invite payload as a URL-safe token and appends it as `?t=<token>`.
+ *
+ * ```ts
+ * const url = buildInviteUrl("myapp://join", { name: "Alice & Bob", p: passphrase })
+ * // → "myapp://join?t=eyJuYW1lIjoiQWxpY2UgJiBCb2IifQ"
+ * ```
+ */
+export declare function buildInviteUrl(baseUrl: string, payload: Record<string, unknown>): string;
+/**
+ * Decodes an invite URL produced by `buildInviteUrl`.
+ *
+ * Returns the decoded payload, or `null` if the URL is missing or malformed.
+ */
+export declare function parseInviteUrl(url: string): Record<string, unknown> | null;
+export { WORDLIST as DEFAULT_WORDLIST };