jazz-tools 0.18.25 → 0.18.27

package/src/media/index.ts

@@ -1,5 +1,8 @@
-import type { ImageDefinition } from "jazz-tools";
-import { CreateImageOptions } from "./create-image-factory";
+import type { ImageDefinition, Loaded } from "jazz-tools";
+import type {
+  CreateImageOptions,
+  CreateImageReturnType,
+} from "./create-image-factory";
 
 export * from "./exports";
 
@@ -38,7 +41,7 @@ export * from "./exports";
 export declare function createImage(
   imageBlobOrFile: Blob | File,
   options?: CreateImageOptions,
-): Promise<ImageDefinition>;
+): Promise<CreateImageReturnType>;
 
 /**
  * Creates an ImageDefinition from an image file path with built-in UX features.
@@ -66,4 +69,4 @@ export declare function createImage(
 export declare function createImage(
   filePath: string,
   options?: CreateImageOptions,
-): Promise<ImageDefinition>;
+): Promise<CreateImageReturnType>;

package/src/tools/coValues/coVector.ts

@@ -0,0 +1,432 @@
+import type { RawBinaryCoStream } from "cojson";
+import { cojsonInternals } from "cojson";
+import {
+  AnonymousJazzAgent,
+  CoValue,
+  CoValueClass,
+  getCoValueOwner,
+  Group,
+  ID,
+  Resolved,
+  SubscribeListenerOptions,
+  SubscribeRestArgs,
+  TypeSym,
+} from "../internal.js";
+import {
+  Account,
+  CoValueJazzApi,
+  inspect,
+  loadCoValueWithoutMe,
+  parseCoValueCreateOptions,
+  parseSubscribeRestArgs,
+  subscribeToCoValueWithoutMe,
+  subscribeToExistingCoValue,
+} from "../internal.js";
+
+/**
+ * CoVectors are collaborative storages of vectors (floating point arrays).
+ *
+ * @category CoValues
+ */
+export class CoVector
+  extends Float32Array
+  implements Readonly<Float32Array>, CoValue
+{
+  declare $jazz: CoVectorJazzApi<this>;
+
+  /** @category Type Helpers */
+  declare [TypeSym]: "BinaryCoStream";
+
+  static get [Symbol.species]() {
+    return Float32Array;
+  }
+
+  protected static requiredDimensionsCount: number | undefined = undefined;
+  private declare _isVectorLoaded: boolean;
+  private declare _requiredDimensionsCount: number;
+
+  constructor(
+    options:
+      | {
+          owner: Account | Group;
+        }
+      | {
+          fromRaw: RawBinaryCoStream;
+        },
+  ) {
+    const dimensionsCount = (new.target as typeof CoVector)
+      .requiredDimensionsCount;
+
+    if (dimensionsCount === undefined) {
+      throw new Error(
+        "Instantiating CoVector without a dimensions count is not allowed. Use co.vector(...).create() instead.",
+      );
+    }
+
+    // Initialize empty Float32Array buffer with the expected vector length
+    // to be filled with the vector data later
+    super(dimensionsCount);
+
+    const isFromRaw = "fromRaw" in options;
+
+    const raw: RawBinaryCoStream = isFromRaw
+      ? options.fromRaw
+      : options.owner.$jazz.raw.createBinaryStream();
+
+    Object.defineProperties(this, {
+      [TypeSym]: { value: "BinaryCoStream", enumerable: false },
+      $jazz: {
+        value: new CoVectorJazzApi(this, raw),
+        enumerable: false,
+      },
+      _isVectorLoaded: { value: false, enumerable: false, writable: true },
+      _requiredDimensionsCount: {
+        value: dimensionsCount,
+        enumerable: false,
+        writable: false,
+      },
+    });
+
+    if (isFromRaw) {
+      this.loadVectorData();
+    }
+  }
+
+  /** @category Internals */
+  static fromRaw<V extends CoVector>(
+    this: CoValueClass<V> & typeof CoVector,
+    raw: RawBinaryCoStream,
+  ) {
+    return new this({ fromRaw: raw });
+  }
+
+  /**
+   * Create a new `CoVector` instance with the given vector.
+   *
+   * @category Creation
+   * @deprecated Use `co.vector(...).create` instead.
+   */
+  static create<S extends CoVector>(
+    this: CoValueClass<S> & typeof CoVector,
+    vector: number[] | Float32Array,
+    options?: { owner?: Account | Group } | Account | Group,
+  ) {
+    const vectorAsFloat32Array =
+      vector instanceof Float32Array ? vector : new Float32Array(vector);
+
+    const givenVectorDimensions =
+      vectorAsFloat32Array.byteLength / vectorAsFloat32Array.BYTES_PER_ELEMENT;
+
+    if (
+      this.requiredDimensionsCount !== undefined &&
+      givenVectorDimensions !== this.requiredDimensionsCount
+    ) {
+      throw new Error(
+        `Vector dimension mismatch! Expected ${this.requiredDimensionsCount} dimensions, got ${
+          givenVectorDimensions
+        }`,
+      );
+    }
+
+    const coVector = new this(parseCoValueCreateOptions(options));
+    coVector.setVectorData(vectorAsFloat32Array);
+
+    const byteArray = CoVector.toByteArray(vectorAsFloat32Array);
+
+    coVector.$jazz.raw.startBinaryStream({
+      mimeType: "application/vector+octet-stream",
+      totalSizeBytes: byteArray.byteLength,
+    });
+
+    const chunkSize =
+      cojsonInternals.TRANSACTION_CONFIG.MAX_RECOMMENDED_TX_SIZE;
+
+    // Although most embedding vectors are small
+    // (3072-dimensional vector is only 12,288 bytes),
+    // we should still chunk the data to avoid transaction size limits
+    for (let idx = 0; idx < byteArray.length; idx += chunkSize) {
+      coVector.$jazz.raw.pushBinaryStreamChunk(
+        byteArray.slice(idx, idx + chunkSize),
+      );
+    }
+    coVector.$jazz.raw.endBinaryStream();
+
+    return coVector;
+  }
+
+  private static toByteArray(vector: Float32Array): Uint8Array {
+    // zero copy view of the vector bytes
+    return new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength);
+  }
+
+  private static fromByteArray(bytesChunks: Uint8Array[]): Float32Array {
+    const total = bytesChunks.reduce((acc, c) => acc + c.byteLength, 0);
+
+    if (total % 4 !== 0)
+      throw new Error("[INTERNAL] Total byte length must be multiple of 4");
+
+    const u8 = new Uint8Array(total);
+    let off = 0;
+
+    for (const c of bytesChunks) {
+      u8.set(c, off);
+      off += c.byteLength;
+    }
+
+    return new Float32Array(u8.buffer, u8.byteOffset, total / 4);
+  }
+
+  private loadVectorData(): void {
+    if (this._isVectorLoaded === true) {
+      return;
+    }
+
+    const chunks = this.$jazz.raw.getBinaryChunks();
+
+    if (!chunks) {
+      // This should never happen
+      throw new Error(`CoVector '${this.$jazz.raw.id}' is not loaded`);
+    }
+
+    const vector = CoVector.fromByteArray(chunks.chunks);
+
+    if (vector.length !== this._requiredDimensionsCount) {
+      throw new Error(
+        `Vector dimension mismatch! CoVector '${this.$jazz.raw.id}' loaded with ${vector.length} dimensions, but the schema requires ${this._requiredDimensionsCount} dimensions`,
+      );
+    }
+
+    this.setVectorData(vector);
+
+    return;
+  }
+
+  private setVectorData(vector: Float32Array): void {
+    super.set(vector, 0);
+    this._isVectorLoaded = true;
+  }
+
+  /**
+   * Get a JSON representation of the `CoVector`
+   * @category Content
+   */
+  toJSON(): Array<number> {
+    return Array.from(this);
+  }
+
+  /** @internal */
+  [inspect]() {
+    return this.toJSON();
+  }
+
+  /**
+   * Load a `CoVector`
+   *
+   * @category Subscription & Loading
+   * @deprecated Use `co.vector(...).load` instead.
+   */
+  static async load<C extends CoVector>(
+    this: CoValueClass<C>,
+    id: ID<C>,
+    options?: {
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<C | null> {
+    const coVector = await loadCoValueWithoutMe(this, id, options);
+
+    /**
+     * We are only interested in the entire vector. Since most vectors are small (<15kB),
+     * we can wait for the stream to be complete before returning the vector
+     */
+    if (!coVector?.$jazz.raw.isBinaryStreamEnded()) {
+      return new Promise<C | null>((resolve) => {
+        subscribeToCoValueWithoutMe(
+          this,
+          id,
+          options || {},
+          (value, unsubscribe) => {
+            if (value.$jazz.raw.isBinaryStreamEnded()) {
+              unsubscribe();
+              resolve(value);
+            }
+          },
+        );
+      });
+    }
+
+    coVector.loadVectorData();
+    return coVector;
+  }
+
+  /**
+   * Subscribe to a `CoVector`, when you have an ID but don't have a `CoVector` instance yet
+   * @category Subscription & Loading
+   * @deprecated Use `co.vector(...).subscribe` instead.
+   */
+  static subscribe<V extends CoVector>(
+    this: CoValueClass<V>,
+    id: ID<V>,
+    listener: (value: Resolved<V, true>, unsubscribe: () => void) => void,
+  ): () => void;
+  static subscribe<V extends CoVector>(
+    this: CoValueClass<V>,
+    id: ID<V>,
+    options: SubscribeListenerOptions<V, true>,
+    listener: (value: Resolved<V, true>, unsubscribe: () => void) => void,
+  ): () => void;
+  static subscribe<V extends CoVector>(
+    this: CoValueClass<V>,
+    id: ID<V>,
+    ...args: SubscribeRestArgs<V, true>
+  ): () => void {
+    const { options, listener } = parseSubscribeRestArgs(args);
+    return subscribeToCoValueWithoutMe<V, true>(this, id, options, listener);
+  }
+
+  // CoVector mutation method overrides, as CoVectors aren't meant to be mutated
+  /**
+   * Calling `copyWithin` on a CoVector is forbidden. CoVectors are immutable.
+   * @deprecated If you want to change the vector, replace the former instance of CoVector with a new one.
+   */
+  override copyWithin(target: number, start: number, end?: number): never {
+    throw new Error("Cannot mutate a CoVector using `copyWithin`");
+  }
+  /**
+   * Calling `fill` on a CoVector is forbidden. CoVectors are immutable.
+   * @deprecated If you want to change the vector, replace the former instance of CoVector with a new one.
+   */
+  override fill(value: number, start?: number, end?: number): never {
+    throw new Error("Cannot mutate a CoVector using `fill`");
+  }
+  /**
+   * Calling `reverse` on a CoVector is forbidden. CoVectors are immutable.
+   * @deprecated If you want to change the vector, replace the former instance of CoVector with a new one.
+   */
+  override reverse(): never {
+    throw new Error("Cannot mutate a CoVector using `reverse`");
+  }
+  /**
+   * Calling `set` on a CoVector is forbidden. CoVectors are immutable.
+   * @deprecated If you want to change the vector, replace the former instance of CoVector with a new one.
+  //  */
+  override set(array: ArrayLike<number>, offset?: number): never {
+    throw new Error("Cannot mutate a CoVector using `set`");
+  }
+  /**
+   * Calling `sort` on a CoVector is forbidden. CoVectors are immutable.
+   * @deprecated If you want to change the vector, replace the former instance of CoVector with a new one.
+   */
+  override sort(compareFn?: (a: number, b: number) => number): never {
+    throw new Error("Cannot mutate a CoVector using `sort`");
+  }
+}
+
+export class CoVectorJazzApi<V extends CoVector> extends CoValueJazzApi<V> {
+  constructor(
+    private coVector: V,
+    public raw: RawBinaryCoStream,
+  ) {
+    super(coVector);
+  }
+
+  get owner(): Group {
+    return getCoValueOwner(this.coVector);
+  }
+
+  /**
+   * An instance method to subscribe to an existing `CoVector`
+   * @category Subscription & Loading
+   */
+  subscribe<B extends CoVector>(
+    this: CoVectorJazzApi<B>,
+    listener: (value: Resolved<B, true>) => void,
+  ): () => void {
+    return subscribeToExistingCoValue(this.coVector, {}, listener);
+  }
+
+  /**
+   * Wait for the `CoVector` to be uploaded to the other peers.
+   *
+   * @category Subscription & Loading
+   */
+  waitForSync(options?: { timeout?: number }) {
+    return this.raw.core.waitForSync(options);
+  }
+
+  // Vector operations
+  /**
+   * Calculate the magnitude of this vector.
+   */
+  magnitude(): number {
+    return VectorCalculation.magnitude(this.coVector);
+  }
+
+  /**
+   * Normalize this vector.
+   * @returns A new instance of a normalized vector.
+   */
+  normalize(): Float32Array {
+    return VectorCalculation.normalize(this.coVector);
+  }
+
+  /**
+   * Calculate the dot product of this vector and another vector.
+   */
+  dotProduct(otherVector: CoVector | Float32Array | number[]): number {
+    return VectorCalculation.dotProduct(this.coVector, otherVector);
+  }
+
+  /**
+   * Calculate the cosine similarity between this vector and another vector.
+   *
+   * @returns A value between `-1` and `1`:
+   * - `1` means the vectors are identical
+   * - `0` means the vectors are orthogonal (i.e. no similarity)
+   * - `-1` means the vectors are opposite direction (perfectly dissimilar)
+   */
+  cosineSimilarity(otherVector: CoVector | Float32Array | number[]): number {
+    return VectorCalculation.cosineSimilarity(this.coVector, otherVector);
+  }
+}
+
+const VectorCalculation = {
+  magnitude: (vector: Float32Array | number[]) => {
+    let sum = 0;
+    for (const v of vector) {
+      sum += v * v;
+    }
+    return Math.sqrt(sum);
+  },
+  normalize: (vector: Float32Array) => {
+    const mag = VectorCalculation.magnitude(vector);
+
+    if (mag === 0) {
+      return new Float32Array(vector.length).fill(0);
+    }
+
+    return vector.map((v) => v / mag);
+  },
+  dotProduct: (vectorA: Float32Array, vectorB: Float32Array | number[]) => {
+    if (vectorA.length !== vectorB.length) {
+      throw new Error(
+        `Vector dimensions don't match: ${vectorA.length} vs ${vectorB.length}`,
+      );
+    }
+
+    return vectorA.reduce((sum, a, i) => sum + a * vectorB[i]!, 0);
+  },
+  cosineSimilarity: (
+    vectorA: Float32Array,
+    vectorB: Float32Array | number[],
+  ) => {
+    const magnitudeA = VectorCalculation.magnitude(vectorA);
+    const magnitudeB = VectorCalculation.magnitude(vectorB);
+
+    if (magnitudeA === 0 || magnitudeB === 0) {
+      return 0;
+    }
+
+    const dotProductAB = VectorCalculation.dotProduct(vectorA, vectorB);
+    return dotProductAB / (magnitudeA * magnitudeB);
+  },
+};

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

@@ -116,6 +116,9 @@ export {
   experimental_defineRequest,
   JazzRequestError,
   isJazzRequestError,
+  authenticateRequest,
+  generateAuthToken,
+  parseAuthToken,
   type HttpRoute,
 } from "./coValues/request.js";
 

package/src/tools/implementation/zodSchema/coExport.ts

@@ -7,6 +7,7 @@ export { CoFeedSchema as Feed } from "./schemaTypes/CoFeedSchema.js";
 export { PlainTextSchema as PlainText } from "./schemaTypes/PlainTextSchema.js";
 export { RichTextSchema as RichText } from "./schemaTypes/RichTextSchema.js";
 export { FileStreamSchema as FileStream } from "./schemaTypes/FileStreamSchema.js";
+export { CoVectorSchema as Vector } from "./schemaTypes/CoVectorSchema.js";
 export { CoInput as input } from "./typeConverters/CoFieldSchemaInit.js";
 export {
   AccountSchema as Account,
@@ -23,6 +24,7 @@ export {
   coPlainTextDefiner as plainText,
   coRichTextDefiner as richText,
   coFileStreamDefiner as fileStream,
+  coVectorDefiner as vector,
   coImageDefiner as image,
   coAccountDefiner as account,
   coGroupDefiner as group,