@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/json-rpc/client/undici.ts

@@ -0,0 +1,128 @@
+import { promisify } from 'node:util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'node:zlib';
+import { Agent, type Dispatcher } from 'undici';
+
+import { createLogger } from '../../log/pino-logger.js';
+import { NoRetryError } from '../../retry/index.js';
+import { jsonStringify } from '../convert.js';
+import type { JsonRpcFetch } from './fetch.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
+const log = createLogger('json-rpc:json_rpc_client:undici');
+
+/** Minimum request size in bytes to trigger compression. */
+const COMPRESSION_THRESHOLD = 1024;
+
+export { Agent };
+
+/** Asynchronous cookie storage. */
+export interface CookieJar {
+  getCookieString(url: string): Promise<string>;
+  setCookie(cookie: string, url: string): Promise<unknown>;
+}
+
+/**
+ * Creates an Undici JSON-RPC transport.
+ * @param client - Dispatcher used to make requests.
+ * @param cookieJar - Optional application-owned cookie storage. Cookies are ignored when omitted.
+ * @returns A JSON-RPC fetch implementation.
+ */
+export function makeUndiciFetch(client: Dispatcher = new Agent(), cookieJar?: CookieJar): JsonRpcFetch {
+  return async (host: string, body: unknown, extraHeaders: Record<string, string> = {}, noRetry = false) => {
+    log.trace(`JsonRpcClient.fetch: ${host}`, { host, body });
+    const requestUrl = new URL(host);
+    requestUrl.hash = '';
+    let resp: Dispatcher.ResponseData;
+    try {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(extraHeaders)) {
+        headers.append(name, value);
+      }
+      const cookie = await cookieJar?.getCookieString(requestUrl.href);
+      if (cookie) {
+        headers.append('cookie', cookie);
+      }
+      const jsonBody = Buffer.from(jsonStringify(body));
+      const shouldCompress = jsonBody.length >= COMPRESSION_THRESHOLD;
+      headers.set('content-type', 'application/json');
+      if (shouldCompress) {
+        headers.set('content-encoding', 'gzip');
+      }
+      headers.set('accept-encoding', 'gzip');
+      const requestHeaders: string[] = [];
+      headers.forEach((value, name) => requestHeaders.push(name, value));
+      resp = await client.request({
+        method: 'POST',
+        origin: requestUrl.origin,
+        path: `${requestUrl.pathname}${requestUrl.search}`,
+        body: shouldCompress ? await gzip(jsonBody) : jsonBody,
+        headers: requestHeaders,
+      });
+    } catch (err) {
+      const errorMessage = `Error fetching from host ${host}: ${String(err)}`;
+      throw new Error(errorMessage);
+    }
+
+    let responseJson: any;
+    const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
+    const contentEncoding = resp.headers['content-encoding'];
+    let responseText: string;
+    try {
+      if (contentEncoding === 'gzip') {
+        const jsonBuffer = await gunzip(await resp.body.arrayBuffer());
+        responseText = jsonBuffer.toString('utf-8');
+      } else {
+        responseText = await resp.body.text();
+      }
+    } catch (err) {
+      if (!responseOk) {
+        throw new Error('HTTP ' + resp.statusCode);
+      }
+      throw new Error(`Failed to read response body. encoding: ${contentEncoding}, error: ${String(err)}`);
+    }
+
+    if (cookieJar) {
+      const setCookieHeaders = resp.headers['set-cookie'];
+      const cookies = typeof setCookieHeaders === 'string' ? [setCookieHeaders] : (setCookieHeaders ?? []);
+      for (const cookie of cookies) {
+        await cookieJar.setCookie(cookie, requestUrl.href);
+      }
+    }
+
+    try {
+      responseJson = JSON.parse(responseText);
+    } catch {
+      if (!responseOk) {
+        throw new Error('HTTP ' + resp.statusCode);
+      }
+      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${responseText}`);
+    }
+
+    if (!responseOk) {
+      const errorMessage = `Error ${resp.statusCode} response from server ${host}: ${responseJson}`;
+      if (noRetry || (resp.statusCode >= 400 && resp.statusCode < 500)) {
+        throw new NoRetryError(errorMessage);
+      } else {
+        throw new Error(errorMessage);
+      }
+    }
+
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(resp.headers)) {
+      if (typeof value === 'string') {
+        headers.append(key, value);
+      } else if (Array.isArray(value)) {
+        for (const v of value) {
+          headers.append(key, v);
+        }
+      }
+    }
+
+    return {
+      response: responseJson,
+      headers,
+    };
+  };
+}

package/src/json-rpc/convert.ts

@@ -0,0 +1,52 @@
+import { Buffer } from 'buffer';
+
+import type { ZodFor } from '../schemas/types.js';
+
+/**
+ * Parses a json string and then feeds it to a zod schema.
+ * @param json - JSON string.
+ * @param schema - Zod schema.
+ * @returns Result of parsing json with schema.
+ */
+export function jsonParseWithSchema<T>(json: string, schema: ZodFor<T>): T {
+  return schema.parse(JSON.parse(json));
+}
+
+/**
+ * JSON.stringify helper that stringifies bigints, buffers, maps, and sets.
+ * @param obj - The object to be stringified.
+ * @returns The resulting string.
+ */
+export function jsonStringify(obj: unknown, prettify?: boolean): string {
+  return JSON.stringify(
+    obj,
+    (_key, value) => {
+      if (typeof value === 'bigint') {
+        return value.toString();
+      } else if (typeof value === 'object' && value && value.type === 'Buffer' && Array.isArray(value.data)) {
+        return Buffer.from(value.data).toString('base64');
+      } else if (typeof value === 'object' && value && Buffer.isBuffer(value)) {
+        return value.toString('base64');
+      } else if (typeof value === 'object' && value instanceof Map) {
+        return Array.from(value.entries());
+      } else if (typeof value === 'object' && value instanceof Set) {
+        return Array.from(value.values());
+      } else {
+        return value;
+      }
+    },
+    prettify ? 2 : 0,
+  );
+}
+
+/**
+ * Calls jsonStringify but swallows errors.
+ * Use for logging, when you don't want to potentially introduce another thing that throws.
+ */
+export function tryJsonStringify(obj: any, prettify?: boolean): string | undefined {
+  try {
+    return jsonStringify(obj, prettify);
+  } catch {
+    return undefined;
+  }
+}

package/src/json-rpc/errors.ts

@@ -0,0 +1,6 @@
+export class BadRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BadRequestError';
+  }
+}

package/src/json-rpc/fixtures/class_a.ts

@@ -0,0 +1,18 @@
+/**
+ * Test class for testing string converter.
+ */
+export class ToStringClass {
+  constructor(
+    /** A value */ public readonly x: string,
+    /** Another value */ public readonly y: string,
+  ) {}
+
+  toString(): string {
+    return [this.x, this.y].join('-');
+  }
+
+  static fromString(value: string) {
+    const [x, y] = value.split('-');
+    return new ToStringClass(x, y);
+  }
+}

package/src/json-rpc/fixtures/class_b.ts

@@ -0,0 +1,18 @@
+/**
+ * Test class for testing string converter.
+ */
+export class ToStringClass {
+  constructor(
+    /** A value */ public readonly x: string,
+    /** Another value */ public readonly y: string,
+  ) {}
+
+  toString(): string {
+    return [this.x, this.y].join('-');
+  }
+
+  static fromString(value: string) {
+    const [x, y] = value.split('-');
+    return new ToStringClass(x, y);
+  }
+}

package/src/json-rpc/fixtures/test_state.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+
+import { type ApiSchemaFor, optional, schemas } from '../../schemas/index.js';
+import { sleep } from '../../sleep/index.js';
+
+/**
+ * Contrived example for JSON RPC tests.
+ */
+export class TestNote {
+  constructor(private data: string) {}
+
+  static get schema() {
+    return z.object({ data: z.string() }).transform(({ data }) => new TestNote(data));
+  }
+
+  toJSON() {
+    return { data: this.data };
+  }
+
+  /**
+   * Create a string representation of this class.
+   * @returns The string representation.
+   */
+  toString(): string {
+    return this.data;
+  }
+  /**
+   * Creates a string representation of this class.
+   * @param data - The data.
+   * @returns The string representation.
+   */
+  static fromString(data: string): TestNote {
+    return new TestNote(data);
+  }
+}
+
+export interface TestStateApi {
+  getNote: (index: number) => Promise<TestNote | undefined>;
+  getNotes: (limit?: number) => Promise<TestNote[]>;
+  getNotes2: (limit: bigint | undefined) => Promise<TestNote[]>;
+  getNotes3: (limit?: number) => Promise<TestNote[]>;
+  clear: () => Promise<void>;
+  addNotes: (notes: TestNote[]) => Promise<TestNote[]>;
+  fail: () => Promise<void>;
+  count: () => Promise<number>;
+  getStatus: () => Promise<{ status: string; count: bigint }>;
+  getTuple(): Promise<[string, string | undefined, number]>;
+}
+
+/**
+ * Represents a simple state management for TestNote instances.
+ * Provides functionality to get a note by index and add notes asynchronously.
+ * Primarily used for testing JSON RPC-related functionalities.
+ */
+export class TestState implements TestStateApi {
+  constructor(public notes: TestNote[]) {}
+  /**
+   * Retrieve the TestNote instance at the specified index from the notes array.
+   * This method allows getting a desired TestNote from the collection of notes
+   * maintained by the TestState instance using the provided index value.
+   *
+   * @param index - The index of the TestNote to be retrieved from the notes array.
+   * @returns The TestNote instance corresponding to the given index.
+   */
+  async getNote(index: number): Promise<TestNote> {
+    await sleep(0.1);
+    return this.notes[index];
+  }
+
+  fail(): Promise<void> {
+    throw new Error('Test state failed');
+  }
+
+  async count(): Promise<number> {
+    await sleep(0.1);
+    return this.notes.length;
+  }
+
+  async getNotes(limit?: number): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, limit) : this.notes;
+  }
+
+  async getNotes2(limit: bigint | undefined): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, Number(limit)) : this.notes;
+  }
+
+  async getNotes3(limit = 1): Promise<TestNote[]> {
+    await sleep(0.1);
+    return limit ? this.notes.slice(0, Number(limit)) : this.notes;
+  }
+
+  async clear(): Promise<void> {
+    await sleep(0.1);
+    this.notes = [];
+  }
+
+  /**
+   * Add an array of TestNote instances to the current TestState's notes.
+   * This function simulates asynchronous behavior by waiting for a duration
+   * equal to the number of notes being added. It then returns the updated
+   * list of TestNote instances in the TestState.
+   *
+   * @param notes - An array of TestNote instances to be added.
+   * @returns A Promise that resolves to an array of TestNote instances, including the newly added notes.
+   */
+  async addNotes(notes: TestNote[]): Promise<TestNote[]> {
+    for (const note of notes) {
+      this.notes.push(note);
+    }
+    await sleep(notes.length);
+    return this.notes;
+  }
+
+  async forceClear() {
+    await sleep(0.1);
+    this.notes = [];
+  }
+
+  async getStatus(): Promise<{ status: string; count: bigint }> {
+    await sleep(0.1);
+    return { status: 'ok', count: BigInt(this.notes.length) };
+  }
+
+  async getTuple(): Promise<[string, string | undefined, number]> {
+    await sleep(0.1);
+    return ['a', undefined, 1];
+  }
+}
+
+export const TestStateSchema: ApiSchemaFor<TestStateApi> = {
+  getNote: z.function({ input: z.tuple([z.number()]), output: TestNote.schema.optional() }),
+  getNotes: z.function({ input: z.tuple([optional(schemas.Integer)]), output: z.array(TestNote.schema) }),
+  getNotes2: z.function({ input: z.tuple([optional(schemas.BigInt)]), output: z.array(TestNote.schema) }),
+  getNotes3: z.function({ input: z.tuple([optional(schemas.Integer)]), output: z.array(TestNote.schema) }),
+  clear: z.function({ input: z.tuple([]), output: z.void() }),
+  addNotes: z.function({ input: z.tuple([z.array(TestNote.schema)]), output: z.array(TestNote.schema) }),
+  fail: z.function({ input: z.tuple([]), output: z.void() }),
+  count: z.function({ input: z.tuple([]), output: z.number() }),
+  getStatus: z.function({ input: z.tuple([]), output: z.object({ status: z.string(), count: schemas.BigInt }) }),
+  getTuple: z.function({ input: z.tuple([]), output: z.tuple([z.string(), optional(z.string()), z.number()]) }),
+};

package/src/json-rpc/index.ts

@@ -0,0 +1,2 @@
+export { jsonStringify, jsonParseWithSchema, tryJsonStringify } from './convert.js';
+export { BadRequestError } from './errors.js';

package/src/json-rpc/js_utils.ts

@@ -0,0 +1,21 @@
+// Make sure this property was not inherited
+// TODO(palla): Delete this file
+
+/**
+ * Does this own the property?
+ * @param obj - An object.
+ * @param method - A property name.
+ */
+export const hasOwnProperty = (obj: any, propertyName: string) =>
+  Object.prototype.hasOwnProperty.call(obj, propertyName);
+
+/**
+ * Helper function to assert a condition is truthy
+ * @param x - A boolean condition to assert.
+ * @param err - Error message to throw if x isn't met.
+ */
+export function assert(x: any, err: string): asserts x {
+  if (!x) {
+    throw new Error(err);
+  }
+}

package/src/json-rpc/server/api_key_auth.ts

@@ -0,0 +1,63 @@
+import { timingSafeEqual } from 'crypto';
+import type Koa from 'koa';
+
+import { sha256 } from '../../crypto/sha256/index.js';
+import { createLogger } from '../../log/index.js';
+
+const log = createLogger('json-rpc:api-key-auth');
+
+/**
+ * Computes the SHA-256 hash of a string and returns it as a Buffer.
+ * @param input - The input string to hash.
+ * @returns The SHA-256 hash as a Buffer.
+ */
+export function sha256Hash(input: string): Buffer {
+  return sha256(Buffer.from(input));
+}
+
+/**
+ * Creates a Koa middleware that enforces API key authentication on all requests
+ * except the health check endpoint (GET /status).
+ *
+ * The API key can be provided via the `x-api-key` header or the `Authorization: Bearer <key>` header.
+ * Comparison is done by hashing the provided key with SHA-256 and comparing against the stored hash.
+ *
+ * @param apiKeyHash - The SHA-256 hash of the expected API key as a Buffer.
+ * @returns A Koa middleware that rejects requests without a valid API key.
+ */
+export function getApiKeyAuthMiddleware(
+  apiKeyHash: Buffer,
+): (ctx: Koa.Context, next: () => Promise<void>) => Promise<void> {
+  return async (ctx: Koa.Context, next: () => Promise<void>) => {
+    // Allow health check through without auth
+    if (ctx.path === '/status' && ctx.method === 'GET') {
+      return next();
+    }
+
+    const providedKey = ctx.get('x-api-key') || ctx.get('authorization')?.replace(/^Bearer\s+/i, '');
+    if (!providedKey) {
+      log.warn(`Rejected admin RPC request from ${ctx.ip}: missing API key`);
+      ctx.status = 401;
+      ctx.body = {
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32000, message: 'Unauthorized: invalid or missing API key' },
+      };
+      return;
+    }
+
+    const providedHashBuf = sha256Hash(providedKey);
+    if (!timingSafeEqual(apiKeyHash, providedHashBuf)) {
+      log.warn(`Rejected admin RPC request from ${ctx.ip}: invalid API key`);
+      ctx.status = 401;
+      ctx.body = {
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32000, message: 'Unauthorized: invalid or missing API key' },
+      };
+      return;
+    }
+
+    await next();
+  };
+}

package/src/json-rpc/server/index.ts

@@ -0,0 +1,2 @@
+export * from './api_key_auth.js';
+export * from './safe_json_rpc_server.js';