@aztec/foundation 0.0.0-test.1 → 0.0.1-commit.017a351

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

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

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

@@ -10,7 +10,13 @@ import { ZodError } from 'zod';
 
 import { type Logger, createLogger } from '../../log/index.js';
 import { promiseWithResolvers } from '../../promise/utils.js';
-import { type ApiSchema, type ApiSchemaFor, parseWithOptionals, schemaHasMethod } from '../../schemas/index.js';
+import {
+  type ApiSchema,
+  type ApiSchemaFor,
+  getSchemaParameters,
+  parseWithOptionals,
+  schemaHasMethod,
+} from '../../schemas/index.js';
 import { jsonStringify } from '../convert.js';
 import { assert } from '../js_utils.js';
 
@@ -23,6 +29,21 @@ export type DiagnosticsData = {
 
 export type DiagnosticsMiddleware = (ctx: DiagnosticsData, next: () => Promise<void>) => Promise<void>;
 
+export type SafeJsonRpcServerConfig = {
+  /** Maximum batch size for batched rpc requests */
+  maxBatchSize: number;
+  /** Return an HTTP 200 status code on errors, but include an error object as per the JSON RPC spec */
+  http200OnError: boolean;
+  /** The maximum body size the server will accept */
+  maxBodySizeBytes: string;
+};
+
+const defaultServerConfig: SafeJsonRpcServerConfig = {
+  http200OnError: false,
+  maxBatchSize: 100,
+  maxBodySizeBytes: '1mb',
+};
+
 export class SafeJsonRpcServer {
   /**
    * The HTTP server accepting remote requests.
@@ -30,21 +51,28 @@ export class SafeJsonRpcServer {
    */
   private httpServer?: http.Server;
 
+  private config: SafeJsonRpcServerConfig;
+
   constructor(
-    /** The proxy object to delegate requests to. */
+    /** The proxy object to delegate requests to */
     private readonly proxy: Proxy,
-    /**
-     *  Return an HTTP 200 status code on errors, but include an error object
-     *  as per the JSON RPC spec
-     */
-    private http200OnError = false,
+    config: Partial<SafeJsonRpcServerConfig> = {},
     /** Health check function */
     private readonly healthCheck: StatusCheckFn = () => true,
-    /** Additional middlewares */
+    /** Additional Koa middlewares */
     private extraMiddlewares: Application.Middleware[] = [],
+    /** Additional per-request diagnostics middlewares */
+    private diagnosticsMiddleware?: DiagnosticsMiddleware,
     /** Logger */
     private log = createLogger('json-rpc:server'),
-  ) {}
+  ) {
+    this.config = { ...defaultServerConfig, ...config };
+
+    // handle empty string
+    if (!this.config.maxBodySizeBytes) {
+      this.config.maxBodySizeBytes = defaultServerConfig.maxBodySizeBytes;
+    }
+  }
 
   public isHealthy(): boolean | Promise<boolean> {
     return this.healthCheck();
@@ -63,20 +91,13 @@ export class SafeJsonRpcServer {
         await next();
       } catch (err: any) {
         const method = (ctx.request.body as any)?.method ?? 'unknown';
-        this.log.warn(`Error in JSON RPC server call ${method}: ${inspect(err)}`);
-        if (err instanceof SyntaxError) {
+        this.log.warn(`Uncaught error in JSON RPC server call ${method}: ${inspect(err)}`);
+        if (err && 'name' in err && err.name === 'BadRequestError') {
           ctx.status = 400;
-          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32700, message: `Parse error: ${err.message}` } };
-        } else if (err instanceof ZodError) {
-          const message = err.issues.map(e => `${e.message} (${e.path.join('.')})`).join('. ') || 'Validation error';
+          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32000, message: `Bad request: ${err.message}` } };
+        } else if (err && err instanceof SyntaxError) {
           ctx.status = 400;
-          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32701, message } };
-        } else if (this.http200OnError) {
-          ctx.body = {
-            jsonrpc: '2.0',
-            id: null,
-            error: { code: err.code || -32600, data: err.data, message: err.message },
-          };
+          ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32700, message: `Parse error: ${err.message}` } };
         } else {
           ctx.status = 500;
           ctx.body = { jsonrpc: '2.0', id: null, error: { code: -32600, message: err.message ?? 'Internal error' } };
@@ -107,7 +128,12 @@ export class SafeJsonRpcServer {
       app.use(middleware);
     }
     app.use(exceptionHandler);
-    app.use(bodyParser({ jsonLimit: '50mb', enableTypes: ['json'], detectJSON: () => true }));
+    app.use(
+      bodyParser({
+        jsonLimit: this.config.maxBodySizeBytes,
+        enableTypes: ['json'],
+      }),
+    );
     app.use(cors());
     app.use(router.routes());
     app.use(router.allowedMethods());
@@ -124,23 +150,102 @@ export class SafeJsonRpcServer {
     const router = new Router({ prefix });
     // "JSON RPC mode" where a single endpoint is used and the method is given in the request body
     router.post('/', async (ctx: Koa.Context) => {
-      const { params = [], jsonrpc, id, method } = ctx.request.body as any;
-      // Fail if not a registered function in the proxy
-      if (typeof method !== 'string' || method === 'constructor' || !this.proxy.hasMethod(method)) {
-        ctx.status = 400;
-        const code = -32601;
-        const message = `Method not found: ${method}`;
-        ctx.body = { jsonrpc, id, error: { code, message } };
+      if (Array.isArray(ctx.request.body)) {
+        if (ctx.request.body.length > this.config.maxBatchSize) {
+          ctx.status = this.config.http200OnError ? 200 : 400;
+          ctx.body = {
+            jsonrpc: '2.0',
+            error: {
+              code: -32600,
+              message: `Batch request exceeds maximum allowed size of ${this.config.maxBatchSize}`,
+            },
+            id: null,
+          };
+          return;
+        }
+        const resp = await this.processBatch(ctx.request.body, ctx.request.headers);
+        if (Array.isArray(resp)) {
+          ctx.status = 200;
+          ctx.body = resp;
+        } else {
+          ctx.status = this.config.http200OnError ? 200 : 400;
+          ctx.body = resp;
+        }
       } else {
-        ctx.status = 200;
-        const result = await this.proxy.call(method, params);
-        ctx.body = { jsonrpc, id, result };
+        const resp = await this.processRequest(ctx.request.body, ctx.request.headers);
+        if ('error' in resp) {
+          ctx.status = this.config.http200OnError ? 200 : 400;
+        }
+
+        ctx.body = resp;
       }
     });
 
     return router;
   }
 
+  private async processBatch(requests: any[], headers: http.IncomingHttpHeaders = {}) {
+    if (requests.length === 0) {
+      return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
+    }
+    const results = await Promise.allSettled(requests.map(req => this.processRequest(req, headers)));
+    return results.map(res => {
+      if (res.status === 'fulfilled') {
+        return res.value;
+      }
+
+      this.log.warn(`Uncaught error executing request in batch: ${res.reason}.`);
+      return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
+    });
+  }
+
+  private async processRequest(request: any, headers: http.IncomingHttpHeaders = {}) {
+    if (!request || typeof request !== 'object') {
+      return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
+    }
+
+    const { params = [], jsonrpc = '2.0', id, method } = request;
+    if (typeof method !== 'string' || !method) {
+      return { jsonrpc: '2.0', id, error: { code: -32600, message: `Invalid request` } };
+    }
+
+    // Fail if not a registered function in the proxy
+    if (typeof method !== 'string' || method === 'constructor' || !this.proxy.hasMethod(method)) {
+      return { jsonrpc, id, error: { code: -32601, message: `Method not found: ${method}` } };
+    } else {
+      try {
+        let result: any;
+
+        if (this.diagnosticsMiddleware) {
+          await this.diagnosticsMiddleware({ id: id ?? null, method, params, headers }, async () => {
+            result = await this.proxy.call(method, params);
+          });
+        } else {
+          result = await this.proxy.call(method, params);
+        }
+
+        return { jsonrpc, id, result };
+      } catch (err: any) {
+        if (err && err instanceof ZodError) {
+          const message = err.issues.map(e => `${e.message} (${e.path.join('.')})`).join('. ') || 'Validation error';
+          return { jsonrpc: '2.0', id, error: { code: -32701, message } };
+        } else if (err) {
+          return {
+            jsonrpc,
+            id,
+            error: { code: -32702, data: err.data, message: err.message },
+          };
+        } else {
+          return {
+            jsonrpc,
+            id,
+            error: { code: -32702, message: 'Error executing request' },
+          };
+        }
+      }
+    }
+  }
+
   /**
    * Start this server with koa.
    * @param port - Port number.
@@ -201,7 +306,10 @@ export class SafeJsonProxy<T extends object = any> implements Proxy {
   private log = createLogger('json-rpc:proxy');
   private schema: ApiSchema;
 
-  constructor(private handler: T, schema: ApiSchemaFor<T>) {
+  constructor(
+    private handler: T,
+    schema: ApiSchemaFor<T>,
+  ) {
     this.schema = schema;
   }
 
@@ -218,7 +326,7 @@ export class SafeJsonProxy<T extends object = any> implements Proxy {
     assert(schemaHasMethod(this.schema, methodName), `Method ${methodName} not found in schema`);
     const method = this.handler[methodName as keyof T];
     assert(typeof method === 'function', `Method ${methodName} is not a function`);
-    const args = await parseWithOptionals(jsonParams, this.schema[methodName].parameters());
+    const args = await parseWithOptionals(jsonParams, getSchemaParameters(this.schema[methodName]));
     const ret = await method.apply(this.handler, args);
     this.log.debug(format('response', methodName, ret));
     return ret;
@@ -265,7 +373,10 @@ function makeAggregateHealthcheck(namedHandlers: NamespacedApiHandlers, log?: Lo
   return async () => {
     try {
       const results = await Promise.all(
-        Object.entries(namedHandlers).map(([name, [, , healthCheck]]) => [name, healthCheck ? healthCheck() : true]),
+        Object.entries(namedHandlers).map(async ([name, [, , healthCheck]]) => [
+          name,
+          healthCheck ? await healthCheck() : true,
+        ]),
       );
       const failed = results.filter(([_, result]) => !result);
       if (failed.length > 0) {
@@ -280,12 +391,14 @@ function makeAggregateHealthcheck(namedHandlers: NamespacedApiHandlers, log?: Lo
   };
 }
 
-export type SafeJsonRpcServerOptions = {
-  http200OnError: boolean;
-  healthCheck?: StatusCheckFn;
-  log?: Logger;
-  middlewares?: Application.Middleware[];
-};
+export type SafeJsonRpcServerOptions = Partial<
+  SafeJsonRpcServerConfig & {
+    healthCheck: StatusCheckFn;
+    diagnostic: DiagnosticsMiddleware;
+    log: Logger;
+    middlewares: Application.Middleware[];
+  }
+>;
 
 /**
  * Creates a single SafeJsonRpcServer from multiple handlers.
@@ -294,24 +407,22 @@ export type SafeJsonRpcServerOptions = {
  */
 export function createNamespacedSafeJsonRpcServer(
   handlers: NamespacedApiHandlers,
-  options: Partial<Omit<SafeJsonRpcServerOptions, 'healthcheck'>> = {
-    log: createLogger('json-rpc:server'),
-  },
+  options: Omit<SafeJsonRpcServerOptions, 'healthcheck'> = {},
 ): SafeJsonRpcServer {
-  const { middlewares, http200OnError, log } = options;
+  const { diagnostic, middlewares, log } = options;
   const proxy = new NamespacedSafeJsonProxy(handlers);
   const healthCheck = makeAggregateHealthcheck(handlers, log);
-  return new SafeJsonRpcServer(proxy, http200OnError, healthCheck, middlewares, log);
+  return new SafeJsonRpcServer(proxy, options, healthCheck, middlewares, diagnostic, log);
 }
 
 export function createSafeJsonRpcServer<T extends object = any>(
   handler: T,
   schema: ApiSchemaFor<T>,
-  options: Partial<SafeJsonRpcServerOptions> = {},
+  options: SafeJsonRpcServerOptions = {},
 ) {
-  const { http200OnError, log, healthCheck, middlewares: extraMiddlewares } = options;
+  const { diagnostic, log, healthCheck, middlewares: extraMiddlewares } = options;
   const proxy = new SafeJsonProxy(handler, schema);
-  return new SafeJsonRpcServer(proxy, http200OnError, healthCheck, extraMiddlewares, log);
+  return new SafeJsonRpcServer(proxy, options, healthCheck, extraMiddlewares, diagnostic, log);
 }
 
 /**
@@ -326,7 +437,7 @@ export function createStatusRouter(getCurrentStatus: StatusCheckFn, apiPrefix =
     let ok: boolean;
     try {
       ok = (await getCurrentStatus()) === true;
-    } catch (err) {
+    } catch {
       ok = false;
     }
 
@@ -364,7 +475,7 @@ export async function startHttpRpcServer(
 
   const { promise, resolve } = promiseWithResolvers<void>();
   const listenPort = options.port ? (typeof options.port === 'string' ? parseInt(options.port) : options.port) : 0;
-  httpServer.listen(listenPort, options.host, () => resolve());
+  httpServer.listen({ host: options.host, port: listenPort, reuseAddress: true }, () => resolve());
 
   // Wait until listen callback is called
   if (!options.noWait) {

package/src/json-rpc/test/integration.ts

@@ -20,7 +20,7 @@ export type JsonRpcTestContext<T extends object> = {
 export async function createJsonRpcTestSetup<T extends object>(
   handler: T,
   schema: ApiSchemaFor<T>,
-  serverOptions: Partial<SafeJsonRpcServerOptions> = {},
+  serverOptions: SafeJsonRpcServerOptions = {},
   clientOptions: SafeJsonRpcClientOptions = {},
 ): Promise<JsonRpcTestContext<T>> {
   const server = createSafeJsonRpcServer<T>(handler, schema, serverOptions);

package/src/log/bigint-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Converts bigint values to strings recursively in a log object to avoid serialization issues.
+ */
+export function convertBigintsToStrings(obj: unknown): unknown {
+  if (typeof obj === 'bigint') {
+    return String(obj);
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => convertBigintsToStrings(item));
+  }
+
+  if (obj !== null && typeof obj === 'object') {
+    if (typeof (obj as any).toJSON === 'function') {
+      return convertBigintsToStrings((obj as any).toJSON());
+    }
+    const result: Record<string, unknown> = {};
+    for (const key in obj) {
+      result[key] = convertBigintsToStrings((obj as Record<string, unknown>)[key]);
+    }
+    return result;
+  }
+
+  return obj;
+}

package/src/log/console.ts

@@ -7,7 +7,10 @@ import type { LogFn } from './log_fn.js';
  * which can be useful for controlling the format of the output or redirecting logs to a different destination.
  */
 class ConsoleLogger {
-  constructor(private prefix: string, private logger: (...args: any[]) => void = console.log) {}
+  constructor(
+    private prefix: string,
+    private logger: (...args: any[]) => void = console.log,
+  ) {}
 
   /**
    * Log messages with the specified prefix using the provided logger.

package/src/log/gcloud-logger-config.ts

@@ -1,5 +1,7 @@
 import type { pino } from 'pino';
 
+import { convertBigintsToStrings } from './bigint-utils.js';
+
 /* eslint-disable camelcase */
 
 const GOOGLE_CLOUD_TRACE_ID = 'logging.googleapis.com/trace';
@@ -13,12 +15,11 @@ const GOOGLE_CLOUD_TRACE_SAMPLED = 'logging.googleapis.com/trace_sampled';
  */
 export const GoogleCloudLoggerConfig = {
   messageKey: 'message',
-  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
-  timestamp(): string {
-    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
-  },
   formatters: {
     log(object: Record<string, unknown>): Record<string, unknown> {
+      // Convert bigints to strings recursively to avoid serialization issues
+      object = convertBigintsToStrings(object) as Record<string, unknown>;
+
       // Add trace context attributes following Cloud Logging structured log format described
       // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
       const { trace_id, span_id, trace_flags, ...rest } = object;
@@ -39,12 +40,12 @@ export const GoogleCloudLoggerConfig = {
       // Severity labels https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity
       let severity: string;
 
-      switch (label as pino.Level | keyof typeof customLevels) {
+      switch (label as pino.Level | keyof CustomLevels) {
         case 'trace':
         case 'debug':
+        case 'verbose':
           severity = 'DEBUG';
           break;
-        case 'verbose':
         case 'info':
           severity = 'INFO';
           break;
@@ -68,4 +69,4 @@ export const GoogleCloudLoggerConfig = {
 } satisfies pino.LoggerOptions;
 
 // Define custom logging levels for pino. Duplicate from pino-logger.ts.
-const customLevels = { verbose: 25 };
+type CustomLevels = { verbose: 25 };

package/src/log/index.ts

@@ -1,6 +1,6 @@
 export * from './console.js';
-export * from './debug.js';
-export * from './pino-logger.js';
-export * from './log_history.js';
-export * from './log_fn.js';
 export * from './libp2p_logger.js';
+export * from './log_fn.js';
+export * from './noir_debug_log_util.js';
+export * from './pino-logger.js';
+export * from './log-levels.js';

package/src/log/libp2p_logger.ts

@@ -2,15 +2,17 @@ import type { ComponentLogger, Logger } from '@libp2p/interface';
 
 import { getLogLevelFromFilters } from './log-filters.js';
 import type { LogLevel } from './log-levels.js';
-import { logFilters, logger } from './pino-logger.js';
+import { type LoggerBindings, logFilters, logger } from './pino-logger.js';
 
 /**
  * Creates a libp2p compatible logger that wraps our pino logger.
  * This adapter implements the ComponentLogger interface required by libp2p.
+ * @param namespace - Base namespace for the logger
+ * @param bindings - Optional bindings to pass to the logger (actor, instanceId)
  */
-export function createLibp2pComponentLogger(namespace: string): ComponentLogger {
+export function createLibp2pComponentLogger(namespace: string, bindings?: LoggerBindings): ComponentLogger {
   return {
-    forComponent: (component: string) => createLibp2pLogger(`${namespace}:${component}`),
+    forComponent: (component: string) => createLibp2pLogger(`${namespace}:${component}`, bindings),
   };
 }
 
@@ -24,16 +26,21 @@ function replaceFormatting(message: string) {
   return message.replace(/(%p|%a)/g, '%s');
 }
 
-function createLibp2pLogger(component: string): Logger {
+function createLibp2pLogger(component: string, bindings?: LoggerBindings): Logger {
   // Create a direct pino logger instance for libp2p that supports string interpolation
-  const log = logger.child({ module: component }, { level: getLogLevelFromFilters(logFilters, component) });
+  const actor = bindings?.actor;
+  const instanceId = bindings?.instanceId;
+  const log = logger.child(
+    { module: component, ...(actor && { actor }), ...(instanceId && { instanceId }) },
+    { level: getLogLevelFromFilters(logFilters, component) },
+  );
 
   const logIfEnabled = (level: LogLevel, message: string, ...args: unknown[]) => {
     if (!log.isLevelEnabled(level)) {
       return;
     }
 
-    log[level](replaceFormatting(message), ...args);
+    log[level](replaceFormatting(message), ...formatArgs(message, args));
   };
 
   // Default log level is trace as this is super super noisy
@@ -45,7 +52,7 @@ function createLibp2pLogger(component: string): Logger {
     enabled: log.isLevelEnabled('debug'),
     error(message: string, ...args: unknown[]) {
       // We write error outputs as debug as they are often expected, e.g. connection errors can happen in happy paths
-      logIfEnabled('debug', message, ...args);
+      logIfEnabled('debug', `error: ${message}`, ...args);
     },
 
     debug(message: string, ...args: unknown[]) {
@@ -65,3 +72,22 @@ function createLibp2pLogger(component: string): Logger {
     },
   });
 }
+
+function formatArgs(message: string, args: unknown[]) {
+  if (!args) {
+    return args;
+  }
+  return args.map(arg => {
+    if (
+      typeof arg === 'object' &&
+      arg &&
+      'err' in arg &&
+      arg.err instanceof Error &&
+      'type' in arg.err &&
+      arg.err.type === 'AbortError'
+    ) {
+      delete arg.err; // Remove the AbortError from the logs
+    }
+    return arg;
+  });
+}

package/src/log/log-filters.ts

@@ -19,22 +19,40 @@ export function getLogLevelFromFilters(filters: LogFilters, module: string): Log
   return undefined;
 }
 
-export function assertLogLevel(level: string): asserts level is LogLevel {
-  if (!LogLevels.includes(level as LogLevel)) {
-    throw new Error(`Invalid log level: ${level}`);
+/**
+ * Parses the LOG_LEVEL env string into a default level and per-module filter overrides.
+ *
+ * Format: `<default_level>;<level>:<module1>,<module2>;<level>:<module3>;...`
+ * - First segment (before the first `;`) is the default log level for all modules.
+ * - Remaining segments are `level:module` pairs: apply the given level to the listed modules (comma-separated).
+ * - Later filters override earlier ones for overlapping module matches.
+ * - The `aztec:` prefix is stripped from module names; spaces are trimmed.
+ *
+ * @example
+ * ```ts
+ * parseLogLevel('debug;warn:module1,module2;error:module3', 'info')
+ * // => ['debug', [['module3', 'error'], ['module2', 'warn'], ['module1', 'warn']]]
+ * ```
+ */
+export function parseLogLevelEnvVar(
+  logLevelEnvVar: string | undefined,
+  defaultLevel: LogLevel,
+): [LogLevel, LogFilters] {
+  if (!logLevelEnvVar) {
+    return [defaultLevel, []];
   }
+  const [level] = logLevelEnvVar.split(';', 1);
+  assertValidLogLevel(level);
+  return [level, parseFilters(logLevelEnvVar.slice(level.length + 1))];
 }
 
-export function parseEnv(env: string | undefined, defaultLevel: LogLevel): [LogLevel, LogFilters] {
-  if (!env) {
-    return [defaultLevel, []];
+function assertValidLogLevel(level: string): asserts level is LogLevel {
+  if (!LogLevels.includes(level as LogLevel)) {
+    throw new Error(`Invalid log level: ${level}`);
   }
-  const [level] = env.split(';', 1);
-  assertLogLevel(level);
-  return [level, parseFilters(env.slice(level.length + 1))];
 }
 
-export function parseFilters(definition: string | undefined): LogFilters {
+function parseFilters(definition: string | undefined): LogFilters {
   if (!definition) {
     return [];
   }
@@ -48,7 +66,7 @@ export function parseFilters(definition: string | undefined): LogFilters {
       throw new Error(`Invalid log filter statement: ${statement}`);
     }
     const sanitizedLevel = level.trim().toLowerCase();
-    assertLogLevel(sanitizedLevel);
+    assertValidLogLevel(sanitizedLevel);
     for (const module of modules.split(',')) {
       filters.push([
         module

package/src/log/log_fn.ts

@@ -1,5 +1,5 @@
 /** Structured log data to include with the message. */
-export type LogData = Record<string, string | number | bigint | boolean | { toString(): string } | undefined>;
+export type LogData = Record<string, string | number | bigint | boolean | { toString(): string } | undefined | null>;
 
 /** A callable logger instance. */
 export type LogFn = (msg: string, data?: unknown) => void;

package/src/log/noir_debug_log_util.ts

@@ -0,0 +1,21 @@
+interface Printable {
+  toString(): string;
+}
+
+/**
+ * Format a debug string filling in `'{0}'` entries with their
+ * corresponding values from the args array, amd `'{}'` with the whole array.
+ *
+ * @param formatStr - str of form `'this is a string with some entries like {0} and {1}'`
+ * @param args - array of fields to fill in the string format entries with
+ * @returns formatted string
+ */
+export function applyStringFormatting(formatStr: string, args: Printable[]): string {
+  return formatStr
+    .replace(/{(\d+)}/g, (match, index) => {
+      return typeof args[index] === 'undefined' ? match : args[index].toString();
+    })
+    .replace(/{}/g, (_match, _index) => {
+      return args.toString();
+    });
+}