jazz-tools 0.18.26 → 0.18.28

package/src/tools/coValues/coMap.ts

@@ -28,6 +28,8 @@ import {
   SubscribeRestArgs,
   TypeSym,
   BranchDefinition,
+  getIdFromHeader,
+  unstable_loadUnique,
 } from "../internal.js";
 import {
   Account,
@@ -434,19 +436,17 @@ export class CoMap extends CoValueBase implements CoValue {
     ownerID: ID<Account> | ID<Group>,
     as?: Account | Group | AnonymousJazzAgent,
   ) {
-    return CoMap._findUnique(unique, ownerID, as);
+    const header = CoMap._getUniqueHeader(unique, ownerID);
+
+    return getIdFromHeader(header, as);
   }
 
   /** @internal */
-  static _findUnique<M extends CoMap>(
-    this: CoValueClass<M>,
+  static _getUniqueHeader(
     unique: CoValueUniqueness["uniqueness"],
     ownerID: ID<Account> | ID<Group>,
-    as?: Account | Group | AnonymousJazzAgent,
   ) {
-    as ||= activeAccountContext.get();
-
-    const header = {
+    return {
       type: "comap" as const,
       ruleset: {
         type: "ownedByGroup" as const,
@@ -455,9 +455,6 @@ export class CoMap extends CoValueBase implements CoValue {
       meta: null,
       uniqueness: unique,
     };
-    const crypto =
-      as[TypeSym] === "Anonymous" ? as.node.crypto : as.$jazz.localNode.crypto;
-    return cojsonInternals.idforHeader(header, crypto) as ID<M>;
   }
 
   /**
@@ -497,32 +494,24 @@ export class CoMap extends CoValueBase implements CoValue {
       resolve?: RefsToResolveStrict<M, R>;
     },
   ): Promise<Resolved<M, R> | null> {
-    const mapId = CoMap._findUnique(
+    const header = CoMap._getUniqueHeader(
       options.unique,
       options.owner.$jazz.id,
-      options.owner.$jazz.loadedAs,
     );
-    let map: Resolved<M, R> | null = await loadCoValueWithoutMe(this, mapId, {
-      ...options,
-      loadAs: options.owner.$jazz.loadedAs,
-      skipRetry: true,
-    });
-    if (!map) {
-      const instance = new this();
-      map = CoMap._createCoMap(instance, options.value, {
-        owner: options.owner,
-        unique: options.unique,
-      }) as Resolved<M, R>;
-    } else {
-      (map as M).$jazz.applyDiff(
-        options.value as unknown as Partial<CoMapInit<M>>,
-      );
-    }
 
-    return await loadCoValueWithoutMe(this, mapId, {
-      ...options,
-      loadAs: options.owner.$jazz.loadedAs,
-      skipRetry: true,
+    return unstable_loadUnique(this, {
+      header,
+      owner: options.owner,
+      resolve: options.resolve,
+      onCreateWhenMissing: () => {
+        (this as any).create(options.value, {
+          owner: options.owner,
+          unique: options.unique,
+        });
+      },
+      onUpdateWhenFound(value) {
+        value.$jazz.applyDiff(options.value);
+      },
     });
   }
 
@@ -535,7 +524,10 @@ export class CoMap extends CoValueBase implements CoValue {
    *
    * @deprecated Use `co.map(...).loadUnique` instead.
    */
-  static loadUnique<M extends CoMap, const R extends RefsToResolve<M> = true>(
+  static async loadUnique<
+    M extends CoMap,
+    const R extends RefsToResolve<M> = true,
+  >(
     this: CoValueClass<M>,
     unique: CoValueUniqueness["uniqueness"],
     ownerID: ID<Account> | ID<Group>,
@@ -544,11 +536,19 @@ export class CoMap extends CoValueBase implements CoValue {
       loadAs?: Account | AnonymousJazzAgent;
     },
   ): Promise<Resolved<M, R> | null> {
-    return loadCoValueWithoutMe(
-      this,
-      CoMap._findUnique(unique, ownerID, options?.loadAs),
-      { ...options, skipRetry: true },
-    );
+    const header = CoMap._getUniqueHeader(unique, ownerID);
+
+    const owner = await Group.load(ownerID, {
+      loadAs: options?.loadAs,
+    });
+
+    if (!owner) return owner;
+
+    return unstable_loadUnique(this, {
+      header,
+      owner,
+      resolve: options?.resolve,
+    });
   }
 }
 

package/src/tools/coValues/group.ts

@@ -9,6 +9,7 @@ import {
   type Role,
 } from "cojson";
 import {
+  AnonymousJazzAgent,
   BranchDefinition,
   CoValue,
   CoValueClass,
@@ -272,7 +273,10 @@ export class Group extends CoValueBase implements CoValue {
   static load<G extends Group, const R extends RefsToResolve<G>>(
     this: CoValueClass<G>,
     id: ID<G>,
-    options?: { resolve?: RefsToResolveStrict<G, R>; loadAs?: Account },
+    options?: {
+      resolve?: RefsToResolveStrict<G, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
   ): Promise<Resolved<G, R> | null> {
     return loadCoValueWithoutMe(this, id, options);
   }

package/src/tools/coValues/inbox.ts

@@ -293,12 +293,12 @@ export class Inbox {
 
     const handleNewMessages = () => {
       for (const tx of messagesFeed.getNewItems()) {
-        const accountID = getAccountIDfromSessionID(tx.txID.sessionID);
+        const accountID = getAccountIDfromSessionID(tx.currentTxID.sessionID);
 
         if (!accountID) {
           console.warn(
             "Received message from unknown account",
-            tx.txID.sessionID,
+            tx.currentTxID.sessionID,
           );
           continue;
         }
@@ -309,7 +309,8 @@ export class Inbox {
           continue;
         }
 
-        const txKey = `${tx.txID.sessionID}/${tx.txID.txIndex}` as const;
+        const txKey =
+          `${tx.currentTxID.sessionID}/${tx.currentTxID.txIndex}` as const;
 
         if (processed.has(txKey)) {
           continue;

package/src/tools/coValues/interfaces.ts

@@ -1,4 +1,5 @@
 import {
+  cojsonInternals,
   type CoValueUniqueness,
   type CojsonInternalTypes,
   type RawCoValue,
@@ -25,6 +26,7 @@ import {
   inspect,
 } from "../internal.js";
 import type { BranchDefinition } from "../subscribe/types.js";
+import { CoValueHeader } from "cojson/dist/coValueCore/verifiedState.js";
 
 /** @category Abstract interfaces */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -446,6 +448,92 @@ export function parseGroupCreateOptions(
     : { owner: options.owner ?? activeAccountContext.get() };
 }
 
+export function getIdFromHeader(
+  header: CoValueHeader,
+  loadAs?: Account | AnonymousJazzAgent | Group,
+) {
+  loadAs ||= activeAccountContext.get();
+
+  const node =
+    loadAs[TypeSym] === "Anonymous" ? loadAs.node : loadAs.$jazz.localNode;
+
+  return cojsonInternals.idforHeader(header, node.crypto);
+}
+
+export async function unstable_loadUnique<
+  V extends CoValue,
+  R extends RefsToResolve<V>,
+>(
+  cls: CoValueClass<V>,
+  options: {
+    header: CoValueHeader;
+    onCreateWhenMissing?: () => void;
+    onUpdateWhenFound?: (value: Resolved<V, R>) => void;
+    owner: Account | Group;
+    resolve?: RefsToResolveStrict<V, R>;
+  },
+): Promise<Resolved<V, R> | null> {
+  const loadAs = options.owner.$jazz.loadedAs;
+
+  const node =
+    loadAs[TypeSym] === "Anonymous" ? loadAs.node : loadAs.$jazz.localNode;
+
+  const id = cojsonInternals.idforHeader(options.header, node.crypto);
+
+  // We first try to load the unique value without using resolve and without
+  // retrying failures
+  // This way when we want to upsert we are sure that, if the load failed
+  // it failed because the unique value was missing
+  let result = await loadCoValueWithoutMe(cls, id, {
+    skipRetry: true,
+    loadAs,
+  });
+
+  if (options.onCreateWhenMissing) {
+    // if load returns unavailable, we check the state in localNode
+    // to ward against race conditions that would happen when
+    // running the same upsert unique concurrently
+    if (!result && node.getCoValue(id).hasVerifiedContent()) {
+      result = await loadCoValueWithoutMe(cls, id, {
+        loadAs,
+      });
+    }
+
+    if (!result) {
+      options.onCreateWhenMissing();
+
+      return loadCoValueWithoutMe(cls, id, {
+        loadAs,
+        resolve: options.resolve,
+      });
+    }
+  }
+
+  if (!result) return result;
+
+  if (options.onUpdateWhenFound) {
+    // we deeply load the value, retrying any failures
+    const loaded = await loadCoValueWithoutMe(cls, id, {
+      loadAs,
+      resolve: options.resolve,
+    });
+
+    if (loaded) {
+      // we don't return the update result because
+      // we want to run another load to backfill any possible partially loaded
+      // values that have been set in the update
+      options.onUpdateWhenFound(loaded);
+    } else {
+      return loaded;
+    }
+  }
+
+  return loadCoValueWithoutMe(cls, id, {
+    loadAs,
+    resolve: options.resolve,
+  });
+}
+
 /**
  * Deeply export a CoValue to a content piece.
  *

package/src/tools/coValues/request.ts

@@ -172,13 +172,16 @@ async function serializeMessagePayload({
   };
 }
 
+const coIdSchema = z.custom<`co_z${string}`>(isCoValueId);
+const signatureSchema = z.custom<`signature_z${string}`>(
+  (value) => typeof value === "string" && value.startsWith("signature_z"),
+);
+
 const requestSchema = z.object({
   contentPieces: z.array(z.json()),
-  id: z.custom<`co_z${string}`>(isCoValueId),
+  id: coIdSchema,
   createdAt: z.number(),
-  authToken: z.custom<`signature_z${string}`>(
-    (value) => typeof value === "string" && value.startsWith("signature_z"),
-  ),
+  authToken: signatureSchema,
   signerID: z.custom<`signer_z${string}`>(
     (value) => typeof value === "string" && value.startsWith("signer_z"),
   ),
@@ -631,3 +634,184 @@ async function loadWorkerAccountOrGroup(id: string, loadAs: Account) {
     loadAs,
   });
 }
+
+function defaultGetToken(request: Request) {
+  const headerValue = request.headers.get("Authorization");
+  if (headerValue?.startsWith("Jazz ")) {
+    return headerValue.replace("Jazz ", "");
+  }
+
+  if (headerValue) {
+    console.warn(
+      "An Authorization header was found, but it did not start with 'Jazz '. If this is intentional, you can specify the location of the token using the `getToken` option.",
+    );
+  }
+
+  return undefined;
+}
+
+/**
+ * Authenticates a Request by verifying a signed authentication token.
+ *
+ * - If a token is not provided, the returned account is `undefined` and no error is returned.
+ * - If a valid token is provided, the signer account is returned.
+ * - If an invalid token is provided, an error is returned detailing the validation error, and the returned account is `undefined`.
+ *
+ * @see {@link generateAuthToken} for generating a token.
+ *
+ * Note: This function does not perform any authorization checks, it only verifies if - **when provided** - a token is valid. It is up to the caller to perform any additional authorization checks, if needed.
+ *
+ * @param request - The request to authenticate.
+ * @param options - The options for the authentication.
+ * @param options.expiration - The expiration time of the token in milliseconds, defaults to 1 minute.
+ * @param options.loadAs - The account to load the token from, defaults to the current active account.
+ * @param options.getToken - If specified, this function will be used to get the token from the request. By default the token is expected to be in the `Authorization` header in the form of `Jazz <token>`.
+ * @returns The account if it is valid, otherwise an error.
+ *
+ * @example
+ * ```ts
+ * const { account, error } = await authenticateRequest(request);
+ * if (error) {
+ *   return new Response(JSON.stringify(error), { status: 401 });
+ * }
+ * ```
+ */
+export async function authenticateRequest(
+  request: Request,
+  options?: {
+    expiration?: number;
+    loadAs?: Account;
+    getToken?: (request: Request) => string | undefined | null;
+  },
+): Promise<
+  | {
+      account?: Account;
+      error?: never;
+    }
+  | {
+      account?: never;
+      error: { message: string; details?: unknown };
+    }
+> {
+  const token = options?.getToken?.(request) ?? defaultGetToken(request);
+
+  if (!token) {
+    return {};
+  }
+
+  const { account, error } = await parseAuthToken(token, {
+    loadAs: options?.loadAs,
+    expiration: options?.expiration ?? 1000 * 60,
+  });
+
+  if (error) {
+    return { error };
+  }
+
+  return { account, error };
+}
+
+/**
+ * Generates an authentication token for a given account. This token can be used to authenticate a request. See {@link authenticateRequest} for more details.
+ *
+ * @param as - The account to generate the token for, defaults to the current active account.
+ * @returns The authentication token.
+ *
+ * @example Make a fetch request with the token
+ * ```ts
+ * const token = generateAuthToken();
+ * const response = await fetch(url, {
+ *   headers: {
+ *     Authorization: `Jazz ${token}`,
+ *   },
+ * });
+ * ```
+ */
+
+export function generateAuthToken(as?: Account) {
+  const account = as ?? Account.getMe();
+  const node = account.$jazz.localNode;
+  const crypto = node.crypto;
+
+  const agent = node.getCurrentAgent();
+  const signerSecret = agent.currentSignerSecret();
+
+  const createdAt = Date.now();
+
+  const signPayload = crypto.secureHash({
+    id: account.$jazz.id,
+    createdAt,
+  });
+
+  const authToken = crypto.sign(signerSecret, signPayload);
+
+  return `${authToken}~${account.$jazz.id}~${createdAt}`;
+}
+
+export async function parseAuthToken(
+  authToken: string,
+  options?: { loadAs?: Account; expiration?: number },
+): Promise<
+  | { account: Account; error?: never }
+  | { account?: never; error: { message: string; details?: unknown } }
+> {
+  const expiration = options?.expiration ?? 1_000 * 60; // 1 minute
+
+  const parsed = z
+    .tuple([signatureSchema, coIdSchema, z.string().transform(Number)])
+    .safeParse(authToken.split("~"));
+
+  if (!parsed.success) {
+    return {
+      error: {
+        message: "Invalid token",
+        details: parsed.error,
+      },
+    };
+  }
+
+  const [signature, id, createdAt] = parsed.data;
+
+  if (createdAt + expiration < Date.now()) {
+    return {
+      error: {
+        message: "Token expired",
+      },
+    };
+  }
+
+  const account = await Account.load(id, { loadAs: options?.loadAs });
+
+  if (!account) {
+    return {
+      error: {
+        message: "Failed to load account",
+        details: { id },
+      },
+    };
+  }
+
+  const node = account.$jazz.localNode;
+  const crypto = node.crypto;
+
+  // Verify the signature of the message to prevent tampering
+  const signPayload = crypto.secureHash({
+    id: account.$jazz.id,
+    createdAt: Number(createdAt),
+  });
+
+  const agentID = account.$jazz.raw.currentAgentID();
+  const signerID = crypto.getAgentSignerID(agentID);
+
+  if (!crypto.verify(signature, signPayload, signerID)) {
+    return {
+      error: {
+        message: "Invalid signature",
+      },
+    };
+  }
+
+  return {
+    account,
+  };
+}

package/src/tools/exports.ts

@@ -36,6 +36,7 @@ export type {
   AccountClass,
   AccountCreationProps,
   BaseProfileShape,
+  unstable_loadUnique,
 } from "./internal.js";
 
 export {
@@ -116,6 +117,9 @@ export {
   experimental_defineRequest,
   JazzRequestError,
   isJazzRequestError,
+  authenticateRequest,
+  generateAuthToken,
+  parseAuthToken,
   type HttpRoute,
 } from "./coValues/request.js";
 

package/src/tools/tests/authenticate-request.test.ts

@@ -0,0 +1,194 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { authenticateRequest, generateAuthToken } from "../coValues/request.js";
+import { createJazzTestAccount } from "../testing.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("authenticateRequest", () => {
+  it("should correctly authenticate a request", async () => {
+    const me = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${token}`,
+        },
+      }),
+    );
+
+    expect(error).toBeUndefined();
+    expect(account?.$jazz.id).toBe(me.$jazz.id);
+  });
+
+  it("should not return an account if no token is provided", async () => {
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {}),
+    );
+
+    expect(error).toBeUndefined();
+    expect(account).toBeUndefined();
+  });
+
+  it("should return an error if the token is invalid", async () => {
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz invalid~invalid~invalid`,
+        },
+      }),
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Invalid token",
+        details: expect.anything(),
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should return an error if the token is malformed", async () => {
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz malformed`,
+        },
+      }),
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Invalid token",
+        details: expect.anything(),
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should be resilient to tampering", async () => {
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+    const tokenParts = token.split("~");
+    tokenParts[2] = "999999999999999";
+    const tamperedToken = tokenParts.join("~");
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${tamperedToken}`,
+        },
+      }),
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Invalid signature",
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should return an error if the token is expired", async () => {
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${token}`,
+        },
+      }),
+      {
+        expiration: -1000,
+      },
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Token expired",
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should treat the request as unauthenticated if the token is not in the default format, even if present.", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `${token}`,
+        },
+      }),
+    );
+
+    expect(console.warn).toHaveBeenCalled();
+    expect(account).toBeUndefined();
+    expect(error).toBeUndefined();
+  });
+
+  it("should correctly validate a request when the token is in a non standard location", async () => {
+    const me = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          ["x-jazz-auth-token"]: `${token}`,
+        },
+      }),
+      {
+        getToken: (request) => request.headers.get("x-jazz-auth-token"),
+      },
+    );
+
+    expect(error).toBeUndefined();
+    expect(account?.$jazz.id).toBe(me.$jazz.id);
+  });
+
+  it("should correctly validate a request when the token is generated from a non active account", async () => {
+    const notAnActiveAccount = await createJazzTestAccount({
+      isCurrentActiveAccount: false,
+    });
+
+    const token = generateAuthToken(notAnActiveAccount);
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${token}`,
+        },
+      }),
+      {
+        loadAs: notAnActiveAccount,
+      },
+    );
+
+    expect(error).toBeUndefined();
+    expect(account?.$jazz.id).toBe(notAnActiveAccount.$jazz.id);
+  });
+});