jazz-tools 0.7.35 → 0.8.0

package/src/coValues/interfaces.ts

@@ -8,6 +8,7 @@ import {
     Ref,
     inspect,
     subscriptionsScopes,
+    AnonymousJazzAgent,
 } from "../internal.js";
 import { fulfillsDepth } from "./deepLoading.js";
 
@@ -35,7 +36,7 @@ export interface CoValue {
     /** @category Internals */
     _raw: RawCoValue;
     /** @internal */
-    readonly _loadedAs: Account;
+    readonly _loadedAs: Account | AnonymousJazzAgent;
     /** @category Stringifying & Inspection */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     toJSON(key?: string, seenAbove?: ID<CoValue>[]): any[] | object | string;
@@ -63,11 +64,11 @@ type IDMarker<out T> = { __type(_: never): T };
 
 /** @internal */
 export class CoValueBase implements CoValue {
-    id!: ID<this>;
-    _type!: string;
-    _raw!: RawCoValue;
+    declare id: ID<this>;
+    declare _type: string;
+    declare _raw: RawCoValue;
     /** @category Internals */
-    _instanceID!: string;
+    declare _instanceID: string;
 
     get _owner(): Account | Group {
         const owner =
@@ -86,7 +87,10 @@ export class CoValueBase implements CoValue {
 
     /** @private */
     get _loadedAs() {
-        return Account.fromNode(this._raw.core.node);
+        if (this._raw.core.node.account instanceof RawAccount) {
+            return Account.fromRaw(this._raw.core.node.account);
+        }
+        return new AnonymousJazzAgent(this._raw.core.node);
     }
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -134,7 +138,7 @@ export class CoValueBase implements CoValue {
 export function loadCoValue<V extends CoValue, Depth>(
     cls: CoValueClass<V>,
     id: ID<V>,
-    as: Account,
+    as: Account | AnonymousJazzAgent,
     depth: Depth & DepthsIn<V>,
 ): Promise<DeeplyLoaded<V, Depth> | undefined> {
     return new Promise((resolve) => {
@@ -170,7 +174,7 @@ export function ensureCoValueLoaded<V extends CoValue, Depth>(
 export function subscribeToCoValue<V extends CoValue, Depth>(
     cls: CoValueClass<V>,
     id: ID<V>,
-    as: Account,
+    as: Account | AnonymousJazzAgent,
     depth: Depth & DepthsIn<V>,
     listener: (value: DeeplyLoaded<V, Depth>) => void,
     onUnavailable?: () => void,

package/src/implementation/createContext.ts

@@ -0,0 +1,268 @@
+import {
+    AgentSecret,
+    CoID,
+    ControlledAgent,
+    CryptoProvider,
+    LocalNode,
+    Peer,
+    RawAccount,
+    RawAccountID,
+    SessionID,
+} from "cojson";
+import { Account, AccountClass, ID } from "../internal.js";
+
+export type AuthResult =
+    | {
+          type: "existing";
+          credentials: { accountID: ID<Account>; secret: AgentSecret };
+          onSuccess: () => void;
+          onError: (error: string | Error) => void;
+          logOut: () => void;
+      }
+    | {
+          type: "new";
+          creationProps: { name: string };
+          initialSecret?: AgentSecret;
+          saveCredentials: (credentials: {
+              accountID: ID<Account>;
+              secret: AgentSecret;
+          }) => Promise<void>;
+          onSuccess: () => void;
+          onError: (error: string | Error) => void;
+          logOut: () => void;
+      };
+
+export interface AuthMethod {
+    start(crypto: CryptoProvider): Promise<AuthResult>;
+}
+
+export const fixedCredentialsAuth = (credentials: {
+    accountID: ID<Account>;
+    secret: AgentSecret;
+}): AuthMethod => {
+    return {
+        start: async () => ({
+            type: "existing",
+            credentials,
+            onSuccess: () => {},
+            onError: () => {},
+            logOut: () => {},
+        }),
+    };
+};
+
+export const ephemeralCredentialsAuth = (): AuthMethod => {
+    return {
+        start: async () => ({
+            type: "new",
+            creationProps: { name: "Ephemeral" },
+            saveCredentials: async () => {},
+            onSuccess: () => {},
+            onError: () => {},
+            logOut: () => {},
+        }),
+    };
+};
+
+export async function randomSessionProvider(
+    accountID: ID<Account>,
+    crypto: CryptoProvider,
+) {
+    return {
+        sessionID: crypto.newRandomSessionID(
+            accountID as unknown as RawAccountID,
+        ),
+        sessionDone: () => {},
+    };
+}
+
+type ContextParamsWithAuth<Acc extends Account> = {
+    AccountSchema?: AccountClass<Acc>;
+    auth: AuthMethod;
+    sessionProvider: (
+        accountID: ID<Account>,
+        crypto: CryptoProvider,
+    ) => Promise<{ sessionID: SessionID; sessionDone: () => void }>;
+} & BaseContextParams;
+
+type BaseContextParams = {
+    peersToLoadFrom: Peer[];
+    crypto: CryptoProvider;
+};
+
+export type JazzContextWithAccount<Acc extends Account> = {
+    account: Acc;
+    done: () => void;
+    logOut: () => void;
+};
+
+export type JazzContextWithAgent = {
+    agent: AnonymousJazzAgent;
+    done: () => void;
+    logOut: () => void;
+};
+
+export type JazzContext<Acc extends Account> = JazzContextWithAccount<Acc> | JazzContextWithAgent;
+
+export async function createJazzContext<Acc extends Account>({
+    AccountSchema,
+    auth,
+    sessionProvider,
+    peersToLoadFrom,
+    crypto,
+}: ContextParamsWithAuth<Acc>): Promise<JazzContextWithAccount<Acc>>;
+export async function createJazzContext({
+    peersToLoadFrom,
+    crypto,
+}: BaseContextParams): Promise<JazzContextWithAgent>;
+export async function createJazzContext<Acc extends Account>(
+    options: ContextParamsWithAuth<Acc> | BaseContextParams,
+): Promise<
+JazzContext<Acc>
+>
+export async function createJazzContext<Acc extends Account>(
+    options: ContextParamsWithAuth<Acc> | BaseContextParams,
+): Promise<
+JazzContext<Acc>
+> {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (!("auth" in options)) {
+            return createAnonymousJazzContext({
+                peersToLoadFrom: options.peersToLoadFrom,
+                crypto: options.crypto,
+            });
+        }
+
+        const { auth, sessionProvider, peersToLoadFrom, crypto } = options;
+        const AccountSchema =
+            options.AccountSchema ?? (Account as unknown as AccountClass<Acc>);
+
+        const authResult = await auth.start(crypto);
+
+        if (authResult.type === "existing") {
+            try {
+                const { sessionID, sessionDone } = await sessionProvider(
+                    authResult.credentials.accountID,
+                    crypto,
+                );
+
+                try {
+                    const node = await LocalNode.withLoadedAccount({
+                        accountID: authResult.credentials
+                            .accountID as unknown as CoID<RawAccount>,
+                        accountSecret: authResult.credentials.secret,
+                        sessionID: sessionID,
+                        peersToLoadFrom: peersToLoadFrom,
+                        crypto: crypto,
+                        migration: async (rawAccount, _node, creationProps) => {
+                            const account = new AccountSchema({
+                                fromRaw: rawAccount,
+                            }) as Acc;
+
+                            await account.migrate?.(creationProps);
+                        },
+                    });
+
+                    const account = AccountSchema.fromNode(node);
+                    authResult.onSuccess();
+
+                    return {
+                        account,
+                        done: () => {
+                            node.gracefulShutdown();
+                            sessionDone();
+                        },
+                        logOut: () => {
+                            node.gracefulShutdown();
+                            sessionDone();
+                            authResult.logOut();
+                        },
+                    };
+                } catch (e) {
+                    authResult.onError(
+                        new Error("Error loading account", { cause: e }),
+                    );
+                    sessionDone();
+                }
+            } catch (e) {
+                authResult.onError(
+                    new Error("Error acquiring sessionID", { cause: e }),
+                );
+            }
+        } else if (authResult.type === "new") {
+            try {
+                // TODO: figure out a way to not "waste" the first SessionID
+                const { node } = await LocalNode.withNewlyCreatedAccount({
+                    creationProps: authResult.creationProps,
+                    peersToLoadFrom: peersToLoadFrom,
+                    crypto: crypto,
+                    initialAgentSecret: authResult.initialSecret,
+                    migration: async (rawAccount, _node, creationProps) => {
+                        const account = new AccountSchema({
+                            fromRaw: rawAccount,
+                        }) as Acc;
+
+                        await account.migrate?.(creationProps);
+                    },
+                });
+
+                const account = AccountSchema.fromNode(node);
+
+                await authResult.saveCredentials({
+                    accountID: node.account.id as unknown as ID<Account>,
+                    secret: node.account.agentSecret,
+                });
+
+                authResult.onSuccess();
+
+                return {
+                    account,
+                    done: () => {
+                        node.gracefulShutdown();
+                    },
+                    logOut: () => {
+                        node.gracefulShutdown();
+                        authResult.logOut();
+                    },
+                };
+            } catch (e) {
+                authResult.onError(
+                    new Error("Error creating account", { cause: e }),
+                );
+            }
+        }
+    }
+}
+
+export class AnonymousJazzAgent {
+    _type = "Anonymous" as const;
+    constructor(public node: LocalNode) {}
+}
+
+export async function createAnonymousJazzContext({
+    peersToLoadFrom,
+    crypto,
+}: {
+    peersToLoadFrom: Peer[];
+    crypto: CryptoProvider;
+}): Promise<JazzContextWithAgent> {
+    const agentSecret = crypto.newRandomAgentSecret();
+    const rawAgent = new ControlledAgent(agentSecret, crypto);
+
+    const node = new LocalNode(
+        rawAgent,
+        crypto.newRandomSessionID(rawAgent.id),
+        crypto,
+    );
+
+    for (const peer of peersToLoadFrom) {
+        node.syncManager.addPeer(peer);
+    }
+
+    return {
+        agent: new AnonymousJazzAgent(node),
+        done: () => {},
+        logOut: () => {},
+    };
+}

package/src/implementation/refs.ts

@@ -1,6 +1,7 @@
 import type { CoID, RawCoValue } from "cojson";
 import type {
     Account,
+    AnonymousJazzAgent,
     CoValue,
     ID,
     RefEncoded,
@@ -19,7 +20,7 @@ const TRACE_ACCESSES = false;
 export class Ref<out V extends CoValue> {
     constructor(
         readonly id: ID<V>,
-        readonly controlledAccount: Account,
+        readonly controlledAccount: Account | AnonymousJazzAgent,
         readonly schema: RefEncoded<V>,
     ) {
         if (!isRefEncoded(schema)) {
@@ -28,9 +29,11 @@ export class Ref<out V extends CoValue> {
     }
 
     get value() {
-        const raw = this.controlledAccount._raw.core.node.getLoaded(
-            this.id as unknown as CoID<RawCoValue>,
-        );
+        const node =
+            "node" in this.controlledAccount
+                ? this.controlledAccount.node
+                : this.controlledAccount._raw.core.node;
+        const raw = node.getLoaded(this.id as unknown as CoID<RawCoValue>);
         if (raw) {
             let value = refCache.get(raw);
             if (value) {
@@ -48,7 +51,11 @@ export class Ref<out V extends CoValue> {
     private async loadHelper(options?: {
         onProgress: (p: number) => void;
     }): Promise<V | "unavailable"> {
-        const raw = await this.controlledAccount._raw.core.node.load(
+        const node =
+            "node" in this.controlledAccount
+                ? this.controlledAccount.node
+                : this.controlledAccount._raw.core.node;
+        const raw = await node.load(
             this.id as unknown as CoID<RawCoValue>,
             options?.onProgress,
         );
@@ -117,7 +124,7 @@ export class Ref<out V extends CoValue> {
 export function makeRefs<Keys extends string | number>(
     getIdForKey: (key: Keys) => ID<CoValue> | undefined,
     getKeysWithIds: () => Keys[],
-    controlledAccount: Account,
+    controlledAccount: Account | AnonymousJazzAgent,
     refSchemaForKey: (key: Keys) => RefEncoded<CoValue>,
 ): { [K in Keys]: Ref<CoValue> } & {
     [Symbol.iterator]: () => IterableIterator<Ref<CoValue>>;

package/src/implementation/subscriptionScope.ts

@@ -5,6 +5,7 @@ import type {
     ID,
     CoValueClass,
     CoValueFromRaw,
+    AnonymousJazzAgent,
 } from "../internal.js";
 
 export const subscriptionsScopes = new WeakMap<
@@ -17,7 +18,7 @@ const TRACE_INVALIDATIONS = false;
 
 export class SubscriptionScope<Root extends CoValue> {
     scopeID: string = `scope-${Math.random().toString(36).slice(2)}`;
-    subscriber: Account;
+    subscriber: Account | AnonymousJazzAgent;
     entries = new Map<
         ID<CoValue>,
         | { state: "loading"; immediatelyUnsub?: boolean }
@@ -89,32 +90,34 @@ export class SubscriptionScope<Root extends CoValue> {
                 immediatelyUnsub: false,
             } as const;
             this.entries.set(accessedOrSetId, loadingEntry);
-            void this.subscriber._raw.core.node
-                .loadCoValueCore(accessedOrSetId)
-                .then((core) => {
-                    if (
-                        loadingEntry.state === "loading" &&
-                        loadingEntry.immediatelyUnsub
-                    ) {
-                        return;
-                    }
-                    if (core !== "unavailable") {
-                        const entry = {
-                            state: "loaded" as const,
-                            rawUnsub: () => {}, // placeholder
-                        };
-                        this.entries.set(accessedOrSetId, entry);
+            const node =
+                this.subscriber._type === "Account"
+                    ? this.subscriber._raw.core.node
+                    : this.subscriber.node;
+            void node.loadCoValueCore(accessedOrSetId).then((core) => {
+                if (
+                    loadingEntry.state === "loading" &&
+                    loadingEntry.immediatelyUnsub
+                ) {
+                    return;
+                }
+                if (core !== "unavailable") {
+                    const entry = {
+                        state: "loaded" as const,
+                        rawUnsub: () => {}, // placeholder
+                    };
+                    this.entries.set(accessedOrSetId, entry);
 
-                        const rawUnsub = core.subscribe((rawUpdate) => {
-                            // console.log("ref update", this.scopeID, accessedOrSetId, JSON.stringify(rawUpdate))
-                            if (!rawUpdate) return;
-                            this.invalidate(accessedOrSetId);
-                            this.scheduleUpdate();
-                        });
+                    const rawUnsub = core.subscribe((rawUpdate) => {
+                        // console.log("ref update", this.scopeID, accessedOrSetId, JSON.stringify(rawUpdate))
+                        if (!rawUpdate) return;
+                        this.invalidate(accessedOrSetId);
+                        this.scheduleUpdate();
+                    });
 
-                        entry.rawUnsub = rawUnsub;
-                    }
-                });
+                    entry.rawUnsub = rawUnsub;
+                }
+            });
         }
     }
 

package/src/index.ts

@@ -11,6 +11,7 @@ export type {
     AgentID,
     SyncMessage,
     CryptoProvider,
+    CoValueUniqueness,
 } from "cojson";
 
 export type { ID, CoValue } from "./internal.js";
@@ -21,9 +22,19 @@ export { CoMap, type CoMapInit } from "./internal.js";
 export { CoList } from "./internal.js";
 export { CoStream, BinaryCoStream } from "./internal.js";
 export { Group, Profile } from "./internal.js";
-export { Account, isControlledAccount } from "./internal.js";
+export { Account, isControlledAccount, type AccountClass } from "./internal.js";
 export { ImageDefinition } from "./internal.js";
 export { CoValueBase, type CoValueClass } from "./internal.js";
 export type { DepthsIn, DeeplyLoaded } from "./internal.js";
 
 export { loadCoValue, subscribeToCoValue } from "./internal.js";
+
+export {
+    type AuthMethod,
+    type AuthResult,
+    createJazzContext,
+    fixedCredentialsAuth,
+    ephemeralCredentialsAuth,
+    AnonymousJazzAgent,
+    createAnonymousJazzContext,
+} from "./internal.js";

package/src/internal.ts

@@ -16,4 +16,6 @@ export * from "./coValues/deepLoading.js";
 
 export * from "./coValues/extensions/imageDef.js";
 
+export * from "./implementation/createContext.js";
+
 import "./implementation/devtoolsFormatters.js";

package/src/tests/coList.test.ts

@@ -1,14 +1,16 @@
 import { expect, describe, test } from "vitest";
 import { connectedPeers } from "cojson/src/streamUtils.js";
-import { newRandomSessionID } from "cojson/src/coValueCore.js";
 import {
     Account,
     CoList,
     WasmCrypto,
     co,
     cojsonInternals,
+    createJazzContext,
     isControlledAccount,
+    fixedCredentialsAuth,
 } from "../index.js";
+import { randomSessionProvider } from "../internal.js";
 
 const Crypto = await WasmCrypto.create();
 
@@ -169,12 +171,13 @@ describe("CoList resolution", async () => {
             throw "me is not a controlled account";
         }
         me._raw.core.node.syncManager.addPeer(secondPeer);
-        const meOnSecondPeer = await Account.become({
-            accountID: me.id,
-            accountSecret: me._raw.agentSecret,
+        const { account: meOnSecondPeer } = await createJazzContext({
+            auth: fixedCredentialsAuth({
+                accountID: me.id,
+                secret: me._raw.agentSecret,
+            }),
+            sessionProvider: randomSessionProvider,
             peersToLoadFrom: [initialAsPeer],
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            sessionID: newRandomSessionID(me.id as any),
             crypto: Crypto,
         });
 
@@ -192,7 +195,11 @@ describe("CoList resolution", async () => {
         expect(loadedList?.[0]).toBeDefined();
         expect(loadedList?.[0]?.[0]).toBe(null);
         expect(loadedList?.[0]?._refs[0]?.id).toEqual(list[0]![0]!.id);
-        expect(loadedList?._refs[0]?.value).toEqual(loadedNestedList);
+        // TODO: this should be ref equal
+        // expect(loadedList?._refs[0]?.value).toEqual(loadedNestedList);
+        expect(loadedList?._refs[0]?.value?.toJSON()).toEqual(
+            loadedNestedList?.toJSON(),
+        );
 
         const loadedTwiceNestedList = await TwiceNestedList.load(
             list[0]![0]!.id,
@@ -204,7 +211,11 @@ describe("CoList resolution", async () => {
         expect(loadedList?.[0]?.[0]?.[0]).toBe("a");
         expect(loadedList?.[0]?.[0]?.joined()).toBe("a,b");
         expect(loadedList?.[0]?._refs[0]?.id).toEqual(list[0]?.[0]?.id);
-        expect(loadedList?.[0]?._refs[0]?.value).toEqual(loadedTwiceNestedList);
+        // TODO: this should be ref equal
+        // expect(loadedList?.[0]?._refs[0]?.value).toEqual(loadedTwiceNestedList);
+        expect(loadedList?.[0]?._refs[0]?.value?.toJSON()).toEqual(
+            loadedTwiceNestedList?.toJSON(),
+        );
 
         const otherNestedList = NestedList.create(
             [TwiceNestedList.create(["e", "f"], { owner: meOnSecondPeer })],
@@ -212,7 +223,11 @@ describe("CoList resolution", async () => {
         );
 
         loadedList![0] = otherNestedList;
-        expect(loadedList?.[0]).toEqual(otherNestedList);
+        // TODO: this should be ref equal
+        // expect(loadedList?.[0]).toEqual(otherNestedList);
+        expect(loadedList?._refs[0]?.value?.toJSON()).toEqual(
+            otherNestedList.toJSON(),
+        );
         expect(loadedList?._refs[0]?.id).toEqual(otherNestedList.id);
     });
 
@@ -231,12 +246,13 @@ describe("CoList resolution", async () => {
             throw "me is not a controlled account";
         }
         me._raw.core.node.syncManager.addPeer(secondPeer);
-        const meOnSecondPeer = await Account.become({
-            accountID: me.id,
-            accountSecret: me._raw.agentSecret,
+        const { account: meOnSecondPeer } = await createJazzContext({
+            auth: fixedCredentialsAuth({
+                accountID: me.id,
+                secret: me._raw.agentSecret,
+            }),
+            sessionProvider: randomSessionProvider,
             peersToLoadFrom: [initialAsPeer],
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            sessionID: newRandomSessionID(me.id as any),
             crypto: Crypto,
         });