cantonjs 0.2.0 → 0.3.0

package/src/testing/setupSandbox.ts

@@ -19,9 +19,10 @@
  * ```
  */
 
+import type { AuthProvider, SessionProvider } from '../auth/types.js'
 import { jsonApi } from '../transport/json-api.js'
 import { createTestClient, type TestClient } from '../clients/createTestClient.js'
-import type { Transport } from '../transport/types.js'
+import type { Transport, TransportConfig } from '../transport/types.js'
 import type { Party } from '../types/party.js'
 
 /** Configuration for sandbox setup. */
@@ -32,7 +33,11 @@ export type SandboxConfig = {
   readonly timeout?: number
   /** JWT token. If not provided, attempts to use cantonctl auth. */
   readonly token?: string
-  /** Party for the TestClient. Default: allocated via sandbox. */
+  /** Per-request bearer token provider for participant calls. */
+  readonly auth?: AuthProvider
+  /** Per-request session provider for participant calls. */
+  readonly session?: SessionProvider
+  /** Party for the TestClient. Default: `test-party`. */
   readonly party?: Party
   /** Custom fetch implementation (for testing the fixture itself). */
   readonly fetchFn?: typeof fetch
@@ -53,12 +58,10 @@ export type SandboxContext = {
 }
 
 /** Default exec using child_process (Node.js only). */
-async function defaultExec(cmd: string): Promise<{ stdout: string; stderr: string }> {
-  // Dynamic import to avoid bundling Node.js modules in browser builds
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const cp = await (Function('return import("node:child_process")')() as Promise<any>)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const util = await (Function('return import("node:util")')() as Promise<any>)
+export async function defaultExec(cmd: string): Promise<{ stdout: string; stderr: string }> {
+  // Dynamic import keeps Node-only modules out of browser-oriented consumers.
+  const cp = await import('node:child_process')
+  const util = await import('node:util')
   const execAsync = util.promisify(cp.exec)
   return execAsync(cmd) as Promise<{ stdout: string; stderr: string }>
 }
@@ -99,6 +102,37 @@ async function waitForHealth(
   )
 }
 
+async function resolveSandboxTransportConfig(
+  url: string,
+  fetchFn: typeof fetch,
+  execFn: (cmd: string) => Promise<{ stdout: string; stderr: string }>,
+  config: SandboxConfig,
+): Promise<TransportConfig> {
+  const token = config.token?.trim() === '' ? undefined : config.token?.trim()
+
+  const transportConfig = {
+    url,
+    fetchFn,
+    token,
+    auth: config.auth,
+    session: config.session,
+  } satisfies TransportConfig
+
+  if (
+    transportConfig.token === undefined &&
+    transportConfig.auth === undefined &&
+    transportConfig.session === undefined
+  ) {
+    const result = await execFn('cantonctl auth token')
+    return {
+      ...transportConfig,
+      token: result.stdout.trim(),
+    }
+  }
+
+  return transportConfig
+}
+
 /**
  * Set up a Canton sandbox for integration testing.
  *
@@ -135,15 +169,9 @@ export async function setupCantonSandbox(
   // Wait for health
   await waitForHealth(url, timeout, fetchFn)
 
-  // Get or generate token
-  let token = config.token
-  if (!token) {
-    const result = await execFn('cantonctl auth token')
-    token = result.stdout.trim()
-  }
-
-  // Create transport and client
-  const transport = jsonApi({ url, token, fetchFn })
+  const transport = jsonApi(
+    await resolveSandboxTransportConfig(url, fetchFn, execFn, config),
+  )
 
   const party = config.party ?? ('test-party' as Party)
   const client = createTestClient({ transport, party })

package/src/transport/grpc.ts

@@ -20,14 +20,17 @@
  *   })
  */
 
-import type { Transport, TransportRequest } from './types.js'
+import {
+  resolveTransportHeaders,
+  type Transport,
+  type TransportAuthConfig,
+  type TransportRequest,
+} from './types.js'
 
 /** Configuration for the gRPC transport. */
-export type GrpcTransportConfig = {
+export type GrpcTransportConfig = TransportAuthConfig & {
   /** Base URL of the Canton node. */
   readonly url: string
-  /** JWT Bearer token for authentication. */
-  readonly token?: string
   /**
    * A ConnectRPC transport instance (from @connectrpc/connect-web or connect-node).
    * Injected to keep cantonjs zero-dependency.
@@ -57,7 +60,7 @@ export type GrpcTransportLike = {
  * Maps Transport requests to gRPC unary calls.
  */
 export function grpc(config: GrpcTransportConfig): Transport {
-  const { url, token, grpcTransport } = config
+  const { url, grpcTransport } = config
   const baseUrl = url.replace(/\/+$/, '')
 
   return {
@@ -65,9 +68,18 @@ export function grpc(config: GrpcTransportConfig): Transport {
     url: baseUrl,
 
     async request<TResponse = unknown>(args: TransportRequest): Promise<TResponse> {
-      const headers: Record<string, string> = {}
-      if (token !== undefined) {
-        headers['Authorization'] = `Bearer ${token}`
+      const headers = {
+        ...args.headers,
+        ...(await resolveTransportHeaders(config, {
+          transport: 'grpc',
+          url: baseUrl,
+          request: {
+            method: args.method,
+            path: args.path,
+            headers: args.headers,
+            signal: args.signal,
+          },
+        })),
       }
 
       const result = await grpcTransport.unary(
@@ -92,18 +104,19 @@ export function grpc(config: GrpcTransportConfig): Transport {
 function pathToService(path: string): { typeName: string } {
   const segments = path.replace(/^\/v2\//, '').split('/')
   const serviceMap: Record<string, string> = {
-    'commands': 'com.daml.ledger.api.v2.CommandService',
+    commands: 'com.daml.ledger.api.v2.CommandService',
     'interactive-submission': 'com.daml.ledger.api.v2.InteractiveSubmissionService',
-    'state': 'com.daml.ledger.api.v2.StateService',
-    'updates': 'com.daml.ledger.api.v2.UpdateService',
-    'events': 'com.daml.ledger.api.v2.EventQueryService',
-    'parties': 'com.daml.ledger.api.v2.PartyManagementService',
-    'users': 'com.daml.ledger.api.v2.UserManagementService',
-    'packages': 'com.daml.ledger.api.v2.PackageService',
-    'dars': 'com.daml.ledger.api.v2.PackageManagementService',
-    'version': 'com.daml.ledger.api.v2.VersionService',
+    state: 'com.daml.ledger.api.v2.StateService',
+    updates: 'com.daml.ledger.api.v2.UpdateService',
+    events: 'com.daml.ledger.api.v2.EventQueryService',
+    parties: 'com.daml.ledger.api.v2.PartyManagementService',
+    users: 'com.daml.ledger.api.v2.UserManagementService',
+    packages: 'com.daml.ledger.api.v2.PackageService',
+    dars: 'com.daml.ledger.api.v2.PackageManagementService',
+    version: 'com.daml.ledger.api.v2.VersionService',
   }
-  const serviceName = serviceMap[segments[0] ?? ''] ?? 'unknown'
+  const serviceKey = segments.find((segment) => segment.length > 0)
+  const serviceName = serviceKey === undefined ? 'unknown' : (serviceMap[serviceKey] ?? 'unknown')
   return { typeName: serviceName }
 }
 
@@ -125,6 +138,7 @@ function pathToMethod(path: string): { name: string } {
     '/v2/events/events-by-contract-id': 'GetEventsByContractId',
     '/v2/version': 'GetLedgerApiVersion',
   }
-  const methodName = methodMap[path] ?? path.split('/').pop() ?? 'unknown'
+  const fallbackMethodName = path.split('/').filter((segment) => segment.length > 0).at(-1)
+  const methodName = methodMap[path] ?? fallbackMethodName ?? 'unknown'
   return { name: methodName }
 }

package/src/transport/index.ts

@@ -1,2 +1,8 @@
 export { jsonApi } from './json-api.js'
-export type { Transport, TransportConfig, TransportRequest, TransportFactory } from './types.js'
+export type {
+  Transport,
+  TransportAuthConfig,
+  TransportConfig,
+  TransportRequest,
+  TransportFactory,
+} from './types.js'

package/src/transport/json-api.ts

@@ -6,12 +6,17 @@
  */
 
 import { ConnectionError, HttpError, TimeoutError } from '../errors/transport.js'
-import type { Transport, TransportConfig, TransportRequest } from './types.js'
+import {
+  resolveTransportHeaders,
+  type Transport,
+  type TransportConfig,
+  type TransportRequest,
+} from './types.js'
 
 const DEFAULT_TIMEOUT = 30_000
 
 export function jsonApi(config: TransportConfig): Transport {
-  const { url, token, timeout = DEFAULT_TIMEOUT, fetchFn = globalThis.fetch } = config
+  const { url, timeout = DEFAULT_TIMEOUT, fetchFn = globalThis.fetch } = config
 
   const baseUrl = url.replace(/\/+$/, '')
 
@@ -21,13 +26,21 @@ export function jsonApi(config: TransportConfig): Transport {
 
     async request<TResponse = unknown>(args: TransportRequest): Promise<TResponse> {
       const requestUrl = `${baseUrl}${args.path}`
+      const authHeaders = await resolveTransportHeaders(config, {
+        transport: 'json-api',
+        url: baseUrl,
+        request: {
+          method: args.method,
+          path: args.path,
+          headers: args.headers,
+          signal: args.signal,
+        },
+      })
+
       const headers: Record<string, string> = {
         'Content-Type': 'application/json',
         ...args.headers,
-      }
-
-      if (token !== undefined) {
-        headers['Authorization'] = `Bearer ${token}`
+        ...authHeaders,
       }
 
       const controller = new AbortController()
@@ -36,7 +49,11 @@ export function jsonApi(config: TransportConfig): Transport {
       const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
 
       if (args.signal !== undefined) {
-        args.signal.addEventListener('abort', () => controller.abort(), { once: true })
+        if (args.signal.aborted) {
+          controller.abort()
+        } else {
+          args.signal.addEventListener('abort', () => controller.abort(), { once: true })
+        }
       }
 
       try {

package/src/transport/types.ts

@@ -6,6 +6,10 @@
  * client logic from communication concerns.
  */
 
+import type { AuthContext, AuthProvider, AuthSession, SessionProvider } from '../auth/types.js'
+import { AuthProviderError } from '../errors/auth.js'
+import { CantonjsError } from '../errors/base.js'
+
 /** A transport handles sending requests to a Canton node. */
 export type Transport = {
   readonly type: string
@@ -23,12 +27,20 @@ export type TransportRequest = {
   timeout?: number
 }
 
+/** Authentication configuration shared by core transports. */
+export type TransportAuthConfig = {
+  /** Static JWT Bearer token for authentication. */
+  readonly token?: string
+  /** Per-request bearer token provider. */
+  readonly auth?: AuthProvider
+  /** Per-request session provider for advanced auth/header injection. */
+  readonly session?: SessionProvider
+}
+
 /** Configuration shared by all transport types. */
-export type TransportConfig = {
+export type TransportConfig = TransportAuthConfig & {
   /** Base URL of the Canton node. */
   readonly url: string
-  /** JWT Bearer token for authentication. */
-  readonly token?: string
   /** Request timeout in milliseconds. Default: 30000. */
   readonly timeout?: number
   /** Custom fetch implementation (for testing or environments without global fetch). */
@@ -37,3 +49,51 @@ export type TransportConfig = {
 
 /** Factory function type for creating transports. */
 export type TransportFactory = (config: TransportConfig) => Transport
+
+export async function resolveTransportSession(
+  config: TransportAuthConfig,
+  context: AuthContext,
+): Promise<AuthSession | undefined> {
+  if (config.session !== undefined) {
+    try {
+      return await config.session(context)
+    } catch (error) {
+      throw toAuthProviderError(context, error)
+    }
+  }
+
+  if (config.auth !== undefined) {
+    try {
+      const token = await config.auth(context)
+      return token === undefined ? undefined : { token }
+    } catch (error) {
+      throw toAuthProviderError(context, error)
+    }
+  }
+
+  return config.token === undefined ? undefined : { token: config.token }
+}
+
+export async function resolveTransportHeaders(
+  config: TransportAuthConfig,
+  context: AuthContext,
+): Promise<Record<string, string>> {
+  const session = await resolveTransportSession(config, context)
+  const headers = session?.headers === undefined ? {} : { ...session.headers }
+
+  if (session?.token !== undefined) {
+    headers['Authorization'] = `Bearer ${session.token}`
+  }
+
+  return headers
+}
+
+function toAuthProviderError(context: AuthContext, error: unknown): CantonjsError {
+  if (error instanceof CantonjsError) {
+    return error
+  }
+
+  return new AuthProviderError(context.transport, context.request.path, {
+    cause: error instanceof Error ? error : new Error(String(error)),
+  })
+}