jazz-tools 0.9.23 → 0.10.0

package/src/auth/DemoAuth.ts

@@ -0,0 +1,188 @@
+import { AgentSecret } from "cojson";
+import { Account } from "../coValues/account.js";
+import { ID } from "../internal.js";
+import { AuthenticateAccountFunction } from "../types.js";
+import { AuthSecretStorage } from "./AuthSecretStorage.js";
+import { KvStore, KvStoreContext } from "./KvStoreContext.js";
+
+type StorageData = {
+  accountID: ID<Account>;
+  accountSecret: AgentSecret;
+  secretSeed?: number[];
+};
+
+/**
+ * `DemoAuth` provides a `JazzAuth` object for demo authentication.
+ *
+ * Demo authentication is useful for quickly testing your app, as it allows you to create new accounts and log in as existing ones.
+ *
+ * ```
+ * import { DemoAuth } from "jazz-tools";
+ *
+ * const auth = new DemoAuth(jazzContext.authenticate, new AuthSecretStorage());
+ * ```
+ *
+ * @category Auth Providers
+ */
+export class DemoAuth {
+  constructor(
+    private authenticate: AuthenticateAccountFunction,
+    private authSecretStorage: AuthSecretStorage,
+  ) {}
+
+  logIn = async (username: string) => {
+    const existingUsers = await this.getExisitingUsersWithData();
+    const storageData = existingUsers[username];
+
+    if (!storageData?.accountID) {
+      throw new Error("User not found");
+    }
+
+    await this.authenticate({
+      accountID: storageData.accountID,
+      accountSecret: storageData.accountSecret,
+    });
+
+    await this.authSecretStorage.set({
+      accountID: storageData.accountID,
+      accountSecret: storageData.accountSecret,
+      secretSeed: storageData.secretSeed
+        ? new Uint8Array(storageData.secretSeed)
+        : undefined,
+      provider: "demo",
+    });
+  };
+
+  signUp = async (username: string) => {
+    const existingUsers = await this.getExistingUsers();
+    if (existingUsers.includes(username)) {
+      throw new Error("User already registered");
+    }
+
+    const credentials = await this.authSecretStorage.get();
+
+    if (!credentials) {
+      throw new Error("No credentials found");
+    }
+
+    const currentAccount = await Account.getMe().ensureLoaded({
+      profile: {},
+    });
+
+    currentAccount.profile.name = username;
+
+    await this.authSecretStorage.set({
+      accountID: credentials.accountID,
+      accountSecret: credentials.accountSecret,
+      secretSeed: credentials.secretSeed
+        ? new Uint8Array(credentials.secretSeed)
+        : undefined,
+      provider: "demo",
+    });
+
+    await this.addToExistingUsers(username, {
+      accountID: credentials.accountID,
+      accountSecret: credentials.accountSecret,
+      secretSeed: credentials.secretSeed
+        ? Array.from(credentials.secretSeed)
+        : undefined,
+    });
+  };
+
+  private async addToExistingUsers(username: string, data: StorageData) {
+    const existingUsers = await this.getExisitingUsersWithData();
+
+    if (existingUsers[username]) {
+      return;
+    }
+
+    existingUsers[username] = data;
+
+    const kvStore = KvStoreContext.getInstance().getStorage();
+    await kvStore.set("demo-auth-users", JSON.stringify(existingUsers));
+  }
+
+  private async getExisitingUsersWithData() {
+    const kvStore = KvStoreContext.getInstance().getStorage();
+    await migrateExistingUsers(kvStore);
+
+    const existingUsers = await kvStore.get("demo-auth-users");
+    return existingUsers ? JSON.parse(existingUsers) : {};
+  }
+
+  getExistingUsers = async () => {
+    return Object.keys(await this.getExisitingUsersWithData());
+  };
+}
+
+export function encodeUsername(username: string) {
+  return btoa(username)
+    .replace(/=/g, "-")
+    .replace(/\+/g, "_")
+    .replace(/\//g, ".");
+}
+
+async function getStorageVersion(kvStore: KvStore) {
+  try {
+    const version = await kvStore.get("demo-auth-storage-version");
+    return version ? parseInt(version) : 1;
+  } catch (error) {
+    return 1;
+  }
+}
+
+async function setStorageVersion(kvStore: KvStore, version: number) {
+  await kvStore.set("demo-auth-storage-version", version.toString());
+}
+
+async function getExistingUsersList(kvStore: KvStore) {
+  const existingUsers = await kvStore.get("demo-auth-existing-users");
+  return existingUsers ? existingUsers.split(",") : [];
+}
+
+/**
+ * Migrates existing users keys to work with any storage.
+ */
+async function migrateExistingUsers(kvStore: KvStore) {
+  if ((await getStorageVersion(kvStore)) < 2) {
+    const existingUsers = await getExistingUsersList(kvStore);
+
+    for (const username of existingUsers) {
+      const legacyKey = `demo-auth-existing-users-${username}`;
+      const storageData = await kvStore.get(legacyKey);
+      if (storageData) {
+        await kvStore.set(
+          `demo-auth-existing-users-${encodeUsername(username)}`,
+          storageData,
+        );
+        await kvStore.delete(legacyKey);
+      }
+    }
+
+    await setStorageVersion(kvStore, 2);
+  }
+
+  if ((await getStorageVersion(kvStore)) < 3) {
+    const existingUsersList = await getExistingUsersList(kvStore);
+
+    const existingUsers: Record<string, StorageData> = {};
+    const keysToDelete: string[] = ["demo-auth-existing-users"];
+
+    for (const username of existingUsersList) {
+      const key = `demo-auth-existing-users-${encodeUsername(username)}`;
+      const storageData = await kvStore.get(key);
+      if (storageData) {
+        existingUsers[username] = JSON.parse(storageData);
+        keysToDelete.push(key);
+      }
+    }
+
+    await kvStore.set("demo-auth-users", JSON.stringify(existingUsers));
+
+    for (const key of keysToDelete) {
+      await kvStore.delete(key);
+    }
+
+    await setStorageVersion(kvStore, 3);
+  }
+}

package/src/auth/InMemoryKVStore.ts

@@ -0,0 +1,25 @@
+import { KvStore } from "./KvStoreContext.js";
+
+export class InMemoryKVStore implements KvStore {
+  private store: Record<string, string> = {};
+
+  async get(key: string) {
+    const data = this.store[key];
+
+    if (!data) return null;
+
+    return data;
+  }
+
+  async set(key: string, value: string) {
+    this.store[key] = value;
+  }
+
+  async delete(key: string) {
+    delete this.store[key];
+  }
+
+  async clearAll() {
+    this.store = {};
+  }
+}

package/src/auth/KvStoreContext.ts

@@ -0,0 +1,39 @@
+export interface KvStore {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  clearAll(): Promise<void>;
+}
+
+export class KvStoreContext {
+  private static instance: KvStoreContext;
+  private storageInstance: KvStore | null = null;
+
+  private constructor() {}
+
+  public static getInstance(): KvStoreContext {
+    if (!KvStoreContext.instance) {
+      KvStoreContext.instance = new KvStoreContext();
+    }
+    return KvStoreContext.instance;
+  }
+
+  public isInitialized(): boolean {
+    return this.storageInstance !== null;
+  }
+
+  public initialize(store: KvStore): void {
+    if (!this.storageInstance) {
+      this.storageInstance = store;
+    }
+  }
+
+  public getStorage(): KvStore {
+    if (!this.storageInstance) {
+      throw new Error("Storage instance is not initialized.");
+    }
+    return this.storageInstance;
+  }
+}
+
+export default KvStoreContext;

package/src/auth/PassphraseAuth.ts

@@ -0,0 +1,113 @@
+import * as bip39 from "@scure/bip39";
+import { entropyToMnemonic } from "@scure/bip39";
+import { CryptoProvider, cojsonInternals } from "cojson";
+import { Account } from "../coValues/account.js";
+import type { ID } from "../internal.js";
+import type { AuthenticateAccountFunction } from "../types.js";
+import { AuthSecretStorage } from "./AuthSecretStorage.js";
+
+/**
+ * `PassphraseAuth` provides a `JazzAuth` object for passphrase authentication.
+ *
+ * ```ts
+ * import { PassphraseAuth } from "jazz-tools";
+ *
+ * const auth = new PassphraseAuth(crypto, jazzContext.authenticate, new AuthSecretStorage(), wordlist);
+ * ```
+ *
+ * @category Auth Providers
+ */
+export class PassphraseAuth {
+  passphrase: string = "";
+
+  constructor(
+    private crypto: CryptoProvider,
+    private authenticate: AuthenticateAccountFunction,
+    private authSecretStorage: AuthSecretStorage,
+    public wordlist: string[],
+  ) {}
+
+  logIn = async (passphrase: string) => {
+    const { crypto, authenticate } = this;
+
+    let secretSeed;
+
+    try {
+      secretSeed = bip39.mnemonicToEntropy(passphrase, this.wordlist);
+    } catch (e) {
+      throw new Error("Invalid passphrase");
+    }
+
+    const accountSecret = crypto.agentSecretFromSecretSeed(secretSeed);
+
+    const accountID = cojsonInternals.idforHeader(
+      cojsonInternals.accountHeaderForInitialAgentSecret(accountSecret, crypto),
+      crypto,
+    ) as ID<Account>;
+
+    await authenticate({
+      accountID,
+      accountSecret,
+    });
+
+    await this.authSecretStorage.set({
+      accountID,
+      secretSeed,
+      accountSecret,
+      provider: "passphrase",
+    });
+
+    this.passphrase = passphrase;
+    this.notify();
+  };
+
+  signUp = async () => {
+    const credentials = await this.authSecretStorage.get();
+
+    if (!credentials || !credentials.secretSeed) {
+      throw new Error("No credentials found");
+    }
+
+    const passphrase = entropyToMnemonic(credentials.secretSeed, this.wordlist);
+
+    await this.authSecretStorage.set({
+      accountID: credentials.accountID,
+      secretSeed: credentials.secretSeed,
+      accountSecret: credentials.accountSecret,
+      provider: "passphrase",
+    });
+
+    return passphrase;
+  };
+
+  getCurrentAccountPassphrase = async () => {
+    const credentials = await this.authSecretStorage.get();
+
+    if (!credentials || !credentials.secretSeed) {
+      throw new Error("No credentials found");
+    }
+
+    return entropyToMnemonic(credentials.secretSeed, this.wordlist);
+  };
+
+  loadCurrentAccountPassphrase = async () => {
+    const passphrase = await this.getCurrentAccountPassphrase();
+    this.passphrase = passphrase;
+    this.notify();
+  };
+
+  listeners = new Set<() => void>();
+  subscribe = (callback: () => void) => {
+    this.listeners.add(callback);
+
+    return () => {
+      this.listeners.delete(callback);
+    };
+  };
+
+  notify() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}

package/src/coValues/account.ts

@@ -42,6 +42,11 @@ import { createInboxRoot } from "./inbox.js";
 import { Profile } from "./profile.js";
 import { RegisteredSchemas } from "./registeredSchemas.js";
 
+export type AccountCreationProps = {
+  name: string;
+  onboarding?: boolean;
+};
+
 /** @category Identity & Permissions */
 export class Account extends CoValueBase implements CoValue {
   declare id: ID<this>;
@@ -253,7 +258,7 @@ export class Account extends CoValueBase implements CoValue {
     return this.toJSON();
   }
 
-  async applyMigration(creationProps?: { name: string; onboarding?: boolean }) {
+  async applyMigration(creationProps?: AccountCreationProps) {
     if (creationProps) {
       const profileGroup = RegisteredSchemas["Group"].create({ owner: this });
       profileGroup.addMember("everyone", "reader");
@@ -278,7 +283,7 @@ export class Account extends CoValueBase implements CoValue {
   }
 
   // Placeholder method for subclasses to override
-  migrate(creationProps?: { name: string }) {
+  migrate(creationProps?: AccountCreationProps) {
     creationProps; // To avoid unused parameter warning
   }
 
@@ -339,7 +344,7 @@ export class Account extends CoValueBase implements CoValue {
   ensureLoaded<A extends Account, Depth>(
     this: A,
     depth: Depth & DepthsIn<A>,
-  ): Promise<DeeplyLoaded<A, Depth> | undefined> {
+  ): Promise<DeeplyLoaded<A, Depth>> {
     return ensureCoValueLoaded(this, depth);
   }
 

package/src/coValues/coFeed.ts

@@ -391,7 +391,7 @@ export class CoFeed<Item = any> extends CoValueBase implements CoValue {
   ensureLoaded<S extends CoFeed, Depth>(
     this: S,
     depth: Depth & DepthsIn<S>,
-  ): Promise<DeeplyLoaded<S, Depth> | undefined> {
+  ): Promise<DeeplyLoaded<S, Depth>> {
     return ensureCoValueLoaded(this, depth);
   }
 

package/src/coValues/coList.ts

@@ -449,7 +449,7 @@ export class CoList<Item = any> extends Array<Item> implements CoValue {
   ensureLoaded<L extends CoList, Depth>(
     this: L,
     depth: Depth & DepthsIn<L>,
-  ): Promise<DeeplyLoaded<L, Depth> | undefined> {
+  ): Promise<DeeplyLoaded<L, Depth>> {
     return ensureCoValueLoaded(this, depth);
   }
 

package/src/coValues/coMap.ts

@@ -542,7 +542,7 @@ export class CoMap extends CoValueBase implements CoValue {
   ensureLoaded<M extends CoMap, Depth>(
     this: M,
     depth: Depth & DepthsIn<M>,
-  ): Promise<DeeplyLoaded<M, Depth> | undefined> {
+  ): Promise<DeeplyLoaded<M, Depth>> {
     return ensureCoValueLoaded(this, depth);
   }
 

package/src/coValues/group.ts

@@ -139,16 +139,14 @@ export class Group extends CoValueBase implements CoValue {
     return this._raw.myRole();
   }
 
-  addMember(member: Everyone, role: "writer" | "reader"): Group;
-  addMember(member: Account, role: AccountRole): Group;
+  addMember(member: Everyone, role: "writer" | "reader"): void;
+  addMember(member: Account, role: AccountRole): void;
   addMember(member: Everyone | Account, role: AccountRole) {
     this._raw.addMember(member === "everyone" ? member : member._raw, role);
-    return this;
   }
 
   removeMember(member: Everyone | Account) {
-    this._raw.removeMember(member === "everyone" ? member : member._raw);
-    return this;
+    return this._raw.removeMember(member === "everyone" ? member : member._raw);
   }
 
   get members() {
@@ -181,8 +179,11 @@ export class Group extends CoValueBase implements CoValue {
       });
   }
 
-  extend(parent: Group) {
-    this._raw.extend(parent._raw);
+  extend(
+    parent: Group,
+    roleMapping?: "reader" | "writer" | "admin" | "inherit",
+  ) {
+    this._raw.extend(parent._raw, roleMapping);
     return this;
   }
 
@@ -243,7 +244,7 @@ export class Group extends CoValueBase implements CoValue {
   ensureLoaded<G extends Group, Depth>(
     this: G,
     depth: Depth & DepthsIn<G>,
-  ): Promise<DeeplyLoaded<G, Depth> | undefined> {
+  ): Promise<DeeplyLoaded<G, Depth>> {
     return ensureCoValueLoaded(this, depth);
   }
 

package/src/coValues/interfaces.ts

@@ -196,16 +196,22 @@ export function loadCoValue<V extends CoValue, Depth>(
   });
 }
 
-export function ensureCoValueLoaded<V extends CoValue, Depth>(
+export async function ensureCoValueLoaded<V extends CoValue, Depth>(
   existing: V,
   depth: Depth & DepthsIn<V>,
-): Promise<DeeplyLoaded<V, Depth> | undefined> {
-  return loadCoValue(
+): Promise<DeeplyLoaded<V, Depth>> {
+  const response = await loadCoValue(
     existing.constructor as CoValueClass<V>,
     existing.id,
     existing._loadedAs,
     depth,
   );
+
+  if (!response) {
+    throw new Error("Failed to deeply load CoValue " + existing.id);
+  }
+
+  return response;
 }
 
 export function subscribeToCoValueWithoutMe<V extends CoValue, Depth>(
@@ -301,7 +307,7 @@ export function subscribeToCoValue<V extends CoValue, Depth>(
 export function createCoValueObservable<V extends CoValue, Depth>(options?: {
   syncResolution?: boolean;
 }) {
-  let currentValue: DeeplyLoaded<V, Depth> | undefined = undefined;
+  let currentValue: DeeplyLoaded<V, Depth> | undefined | null = undefined;
   let subscriberCount = 0;
 
   function subscribe(
@@ -323,7 +329,10 @@ export function createCoValueObservable<V extends CoValue, Depth>(options?: {
         currentValue = value;
         listener();
       },
-      onUnavailable,
+      () => {
+        currentValue = null;
+        onUnavailable?.();
+      },
       options?.syncResolution,
     );
 

package/src/exports.ts

@@ -18,6 +18,7 @@ export {
   Account,
   isControlledAccount,
   type AccountClass,
+  type AccountCreationProps,
 } from "./coValues/account.js";
 export {
   BinaryCoStream,
@@ -49,6 +50,17 @@ export {
   subscribeToCoValue,
 } from "./internal.js";
 
+export {
+  JazzContextManager,
+  type JazzContextManagerAuthProps,
+} from "./implementation/ContextManager.js";
+
+export { AuthSecretStorage } from "./auth/AuthSecretStorage.js";
+export { KvStoreContext, type KvStore } from "./auth/KvStoreContext.js";
+export { InMemoryKVStore } from "./auth/InMemoryKVStore.js";
+export { DemoAuth } from "./auth/DemoAuth.js";
+export { PassphraseAuth } from "./auth/PassphraseAuth.js";
+
 export {
   createInviteLink,
   parseInviteLink,
@@ -58,11 +70,13 @@ export {
 export {
   AnonymousJazzAgent,
   createAnonymousJazzContext,
+  createJazzContextFromExistingCredentials,
+  createJazzContextForNewAccount,
   createJazzContext,
-  ephemeralCredentialsAuth,
-  fixedCredentialsAuth,
   randomSessionProvider,
-  type AuthMethod,
   type AuthResult,
   type Credentials,
+  type JazzContextWithAccount,
 } from "./internal.js";
+
+export type * from "./types.js";