@zhin.js/a2a 3.0.13 → 3.0.14

package/src/workroom-auth-registry.ts

@@ -0,0 +1,279 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+export type WorkroomA2aCredentialReference =
+  | Readonly<{ source: 'config'; value: string }>
+  | Readonly<{ source: 'secure_provider'; secretRef: string }>;
+
+export interface WorkroomA2aAuthBindingInput {
+  readonly endpointId: string;
+  readonly tenantId: string;
+  readonly cardDigest: string;
+  readonly authBindingId: string;
+  readonly trustDomain: string;
+  readonly extensionDigest: string;
+  readonly credentialId: string;
+  readonly credential: WorkroomA2aCredentialReference;
+  readonly enabled: boolean;
+  readonly expiresAt?: number;
+}
+
+export interface WorkroomA2aSecureCredentialProvider {
+  resolve(secretRef: string): string | undefined;
+}
+
+export interface WorkroomA2aAuthRegistryOptions {
+  readonly generation: number;
+  readonly bindings: readonly WorkroomA2aAuthBindingInput[];
+  readonly secureCredentialProvider?: WorkroomA2aSecureCredentialProvider;
+  readonly now?: () => number;
+}
+
+export interface WorkroomA2aEndpointAuthoritySnapshot {
+  readonly version: 1;
+  readonly endpointId: string;
+  readonly tenantId: string;
+  readonly cardDigest: string;
+  readonly authBindingId: string;
+  readonly trustDomain: string;
+  readonly generation: number;
+  readonly extensionDigest: string;
+  readonly credentialIdDigest: string;
+}
+
+export interface WorkroomA2aRegisteredAuthBindingSnapshot
+extends WorkroomA2aEndpointAuthoritySnapshot {
+  readonly enabled: boolean;
+  readonly expiresAt?: number;
+}
+
+export interface WorkroomA2aAuthRegistrySnapshot {
+  readonly version: 1;
+  readonly generation: number;
+  readonly bindings: readonly WorkroomA2aRegisteredAuthBindingSnapshot[];
+}
+
+interface CompiledBinding {
+  readonly credentialDigest: Buffer;
+  /** Trusted transport-only secret; never exposed through snapshots or serialization. */
+  readonly credential: string;
+  readonly authority: WorkroomA2aEndpointAuthoritySnapshot;
+  readonly enabled: boolean;
+  readonly expiresAt?: number;
+}
+
+export class WorkroomA2aAuthenticationError extends Error {
+  constructor() {
+    super('Workroom A2A credential is unknown or inactive');
+    this.name = 'WorkroomA2aAuthenticationError';
+  }
+}
+
+/** Generation-owned immutable credential-to-endpoint authority registry. */
+export class WorkroomA2aAuthRegistry {
+  readonly #bindings: readonly CompiledBinding[];
+  readonly #now: () => number;
+  readonly snapshot: WorkroomA2aAuthRegistrySnapshot;
+
+  constructor(options: WorkroomA2aAuthRegistryOptions) {
+    validateOptions(options);
+    this.#now = options.now ?? Date.now;
+    const endpointIds = new Set<string>();
+    const authBindingIds = new Set<string>();
+    const credentialIds = new Set<string>();
+    const credentialDigests = new Set<string>();
+    const bindings: CompiledBinding[] = [];
+    for (const input of options.bindings) {
+      validateBinding(input);
+      if (endpointIds.has(input.endpointId)) {
+        throw new Error(`Workroom A2A endpoint binding drift: ${input.endpointId}`);
+      }
+      if (credentialIds.has(input.credentialId)) {
+        throw new Error(`Workroom A2A duplicate credentialId: ${input.credentialId}`);
+      }
+      if (authBindingIds.has(input.authBindingId)) {
+        throw new Error(`Workroom A2A authBindingId drift: ${input.authBindingId}`);
+      }
+      endpointIds.add(input.endpointId);
+      authBindingIds.add(input.authBindingId);
+      credentialIds.add(input.credentialId);
+      const credential = resolveCredential(input.credential, options.secureCredentialProvider);
+      const credentialDigest = hash(credential);
+      const digestKey = credentialDigest.toString('hex');
+      if (credentialDigests.has(digestKey)) {
+        throw new Error('Workroom A2A duplicate credential value');
+      }
+      credentialDigests.add(digestKey);
+      const authority = deepFreeze({
+        version: 1 as const,
+        endpointId: input.endpointId,
+        tenantId: input.tenantId,
+        cardDigest: input.cardDigest,
+        authBindingId: input.authBindingId,
+        trustDomain: input.trustDomain,
+        generation: options.generation,
+        extensionDigest: input.extensionDigest,
+        credentialIdDigest: digestString(input.credentialId),
+      });
+      bindings.push({
+        credentialDigest,
+        credential,
+        authority,
+        enabled: input.enabled,
+        ...(input.expiresAt === undefined ? {} : { expiresAt: input.expiresAt }),
+      });
+    }
+    this.#bindings = Object.freeze(bindings);
+    this.snapshot = deepFreeze({
+      version: 1 as const,
+      generation: options.generation,
+      bindings: bindings.map(binding => ({
+        ...binding.authority,
+        enabled: binding.enabled,
+        ...(binding.expiresAt === undefined ? {} : { expiresAt: binding.expiresAt }),
+      })),
+    });
+  }
+
+  /** Only the transport credential participates; callback claims are not an input. */
+  authenticate(requestCredential: string): WorkroomA2aEndpointAuthoritySnapshot {
+    if (typeof requestCredential !== 'string' || requestCredential.length === 0) {
+      throw new WorkroomA2aAuthenticationError();
+    }
+    const candidate = hash(requestCredential);
+    let matched: CompiledBinding | undefined;
+    for (const binding of this.#bindings) {
+      if (timingSafeEqual(candidate, binding.credentialDigest)) matched = binding;
+    }
+    const now = this.#now();
+    if (!Number.isFinite(now)) throw new Error('Workroom A2A authentication clock must be finite');
+    if (!matched || !matched.enabled
+      || (matched.expiresAt !== undefined && now >= matched.expiresAt)) {
+      throw new WorkroomA2aAuthenticationError();
+    }
+    return matched.authority;
+  }
+
+  /**
+   * Issues the callback credential only to the trusted outbound transport.
+   * The endpoint id is resolved against this exact generation and inactive
+   * credentials fail closed just like inbound authentication.
+   */
+  callbackAuthorization(endpointId: string): string {
+    text(endpointId, 'endpointId');
+    const matched = this.#bindings.find(binding => binding.authority.endpointId === endpointId);
+    const now = this.#now();
+    if (!Number.isFinite(now)) throw new Error('Workroom A2A authentication clock must be finite');
+    if (!matched || !matched.enabled
+      || (matched.expiresAt !== undefined && now >= matched.expiresAt)) {
+      throw new WorkroomA2aAuthenticationError();
+    }
+    return `Bearer ${matched.credential}`;
+  }
+}
+
+function validateOptions(options: WorkroomA2aAuthRegistryOptions): void {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new Error('Workroom A2A auth registry options must be an object');
+  }
+  assertExactKeys(options, ['generation', 'bindings', 'secureCredentialProvider', 'now'], 'options');
+  positiveInteger(options.generation, 'generation');
+  if (!Array.isArray(options.bindings)) throw new Error('Workroom A2A bindings must be an array');
+  if (options.now !== undefined && typeof options.now !== 'function') {
+    throw new Error('Workroom A2A now must be a function');
+  }
+  if (options.secureCredentialProvider !== undefined
+    && (!options.secureCredentialProvider
+      || typeof options.secureCredentialProvider !== 'object'
+      || typeof options.secureCredentialProvider.resolve !== 'function')) {
+    throw new Error('Workroom A2A secure credential provider resolve must be a function');
+  }
+}
+
+function validateBinding(input: WorkroomA2aAuthBindingInput): void {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Workroom A2A auth binding must be an object');
+  }
+  assertExactKeys(input, [
+    'endpointId', 'tenantId', 'cardDigest', 'authBindingId', 'trustDomain',
+    'extensionDigest', 'credentialId', 'credential', 'enabled', 'expiresAt',
+  ], 'binding');
+  for (const [label, value] of Object.entries({
+    endpointId: input.endpointId,
+    tenantId: input.tenantId,
+    authBindingId: input.authBindingId,
+    trustDomain: input.trustDomain,
+    credentialId: input.credentialId,
+  })) text(value, label);
+  canonicalDigest(input.cardDigest, 'cardDigest');
+  canonicalDigest(input.extensionDigest, 'extensionDigest');
+  if (typeof input.enabled !== 'boolean') throw new Error('Workroom A2A enabled must be boolean');
+  if (input.expiresAt !== undefined && !Number.isFinite(input.expiresAt)) {
+    throw new Error('Workroom A2A expiresAt must be finite');
+  }
+}
+
+function resolveCredential(
+  reference: WorkroomA2aCredentialReference,
+  provider: WorkroomA2aSecureCredentialProvider | undefined,
+): string {
+  if (!reference || typeof reference !== 'object' || Array.isArray(reference)) {
+    throw new Error('Workroom A2A credential reference must be an object');
+  }
+  if (reference.source === 'config') {
+    assertExactKeys(reference, ['source', 'value'], 'config credential');
+    return credential(reference.value);
+  }
+  if (reference.source === 'secure_provider') {
+    assertExactKeys(reference, ['source', 'secretRef'], 'secure credential');
+    text(reference.secretRef, 'credential secretRef');
+    if (!provider) throw new Error('Workroom A2A secure credential provider is required');
+    return credential(provider.resolve(reference.secretRef));
+  }
+  throw new Error('Workroom A2A credential source is unsupported');
+}
+
+function credential(value: unknown): string {
+  text(value, 'credential value');
+  const result = value;
+  if (result.length > 8_192 || /\s/u.test(result)) {
+    throw new Error('Workroom A2A credential must be a bounded token without whitespace');
+  }
+  return result;
+}
+
+function hash(value: string): Buffer {
+  return createHash('sha256').update(value).digest();
+}
+
+function digestString(value: string): string {
+  return `sha256:${hash(value).toString('hex')}`;
+}
+
+function assertExactKeys(value: object, allowed: readonly string[], label: string): void {
+  const unexpected = Object.keys(value).find(key => !allowed.includes(key));
+  if (unexpected) throw new Error(`Workroom A2A ${label} contains forbidden field ${unexpected}`);
+}
+
+function text(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`Workroom A2A ${label} must be non-empty text`);
+  }
+}
+
+function positiveInteger(value: unknown, label: string): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) < 1) {
+    throw new Error(`Workroom A2A ${label} must be a positive safe integer`);
+  }
+}
+
+function canonicalDigest(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || !/^sha256:[a-f0-9]{64}$/u.test(value)) {
+    throw new Error(`Workroom A2A ${label} must be a canonical sha256 digest`);
+  }
+}
+
+function deepFreeze<T>(value: T): T {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const item of Object.values(value as Record<string, unknown>)) deepFreeze(item);
+  return Object.freeze(value);
+}

package/src/workroom-callback-runtime.ts

@@ -0,0 +1,294 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpRouteHost } from '@zhin.js/host-http-contract';
+import type {
+  RemoteCallbackApplicationOutcome,
+  RemoteExecutionLinkRecord,
+  WorkroomCallbackAuthRegistry,
+  WorkroomRemoteCallbackGatewayResult,
+  WorkroomRemoteCallbackRequest,
+} from '@zhin.js/agent';
+import { WorkroomA2aAuthenticationError } from './workroom-auth-registry.js';
+
+export interface RuntimeWorkroomCallbackDependencies {
+  readonly authRegistry: Pick<WorkroomCallbackAuthRegistry, 'authenticate'>;
+  readonly gateway: Readonly<{
+    handle(
+      request: WorkroomRemoteCallbackRequest,
+      signal: AbortSignal,
+    ): Promise<WorkroomRemoteCallbackGatewayResult>;
+  }>;
+  readonly linkRegistry: Readonly<{
+    listRegistered(): Promise<readonly Pick<RemoteExecutionLinkRecord, 'id'>[]>;
+  }>;
+  readonly application: Readonly<{
+    runOnce(linkId: string, signal: AbortSignal): Promise<RemoteCallbackApplicationOutcome>;
+  }>;
+}
+
+export interface InstallRuntimeWorkroomCallbacksOptions {
+  readonly http: HttpRouteHost;
+  /** Exact route, intentionally separate from `/a2a/{agent}/*`. */
+  readonly path?: string;
+  readonly ordinaryA2aBasePath?: string;
+  readonly dependencies: RuntimeWorkroomCallbackDependencies;
+  readonly maxBodyBytes: number;
+  readonly signal?: AbortSignal;
+  /** Root handoff uses this so database-backed Workroom state activates first. */
+  readonly deferRecovery?: boolean;
+  readonly onRecoveryError?: (linkId: string, error: unknown) => void;
+}
+
+export interface RuntimeWorkroomCallbackRecoverySummary {
+  readonly registered: number;
+  readonly recovered: number;
+  readonly failed: number;
+}
+
+export interface RuntimeWorkroomCallbackInstallation {
+  readonly recovery: RuntimeWorkroomCallbackRecoverySummary | undefined;
+  recover(signal?: AbortSignal): Promise<RuntimeWorkroomCallbackRecoverySummary>;
+  dispose(): void;
+}
+
+/**
+ * Installs the authority-isolated Workroom callback ingress. This route never
+ * invokes the ordinary A2A Agent executor; accepted observations can reach
+ * Workroom state only through the injected Callback Application.
+ */
+export async function installRuntimeWorkroomCallbacks(
+  options: InstallRuntimeWorkroomCallbacksOptions,
+): Promise<RuntimeWorkroomCallbackInstallation> {
+  const path = normalizeExactPath(options.path ?? '/workroom-a2a/callback');
+  const ordinaryA2aBasePath = normalizeBasePath(options.ordinaryA2aBasePath ?? '/a2a');
+  if (ordinaryA2aBasePath === '/'
+    || path === ordinaryA2aBasePath
+    || path.startsWith(`${ordinaryA2aBasePath}/`)) {
+    throw new Error('Workroom callback path must be outside ordinary A2A inbound');
+  }
+  const maxBodyBytes = positiveInteger(options.maxBodyBytes, 'maxBodyBytes');
+  const controller = new AbortController();
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, controller.signal])
+    : controller.signal;
+  let recovery = options.deferRecovery === true
+    ? undefined
+    : await recoverRegisteredLinks(options.dependencies, signal, options.onRecoveryError);
+  signal.throwIfAborted();
+
+  const unregister = options.http.route('POST', path, async (request, response) => {
+    const credential = bearerCredential(request);
+    if (!credential) {
+      writeJson(response, 401, { error: 'Unauthorized' });
+      return;
+    }
+    // Authenticate before consuming attacker-controlled request bytes. The
+    // Gateway authenticates again while deriving the immutable authority.
+    try {
+      options.dependencies.authRegistry.authenticate(credential);
+    } catch {
+      writeJson(response, 401, { error: 'Unauthorized' });
+      return;
+    }
+
+    const requestController = new AbortController();
+    const abortRequest = () => requestController.abort(new Error('Callback request aborted'));
+    request.once('aborted', abortRequest);
+    const requestSignal = AbortSignal.any([signal, requestController.signal]);
+    try {
+      const body = await readRawBody(request, maxBodyBytes);
+      const result = await options.dependencies.gateway.handle({ credential, body }, requestSignal);
+      writeJson(response, 202, {
+        accepted: true,
+        duplicate: result.duplicate,
+        applicationStatus: result.application.status,
+      });
+    } catch (error) {
+      if (error instanceof WorkroomA2aAuthenticationError) {
+        writeJson(response, 401, { error: 'Unauthorized' });
+      } else if (error instanceof RuntimeWorkroomCallbackBodyError) {
+        writeJson(
+          response,
+          error.statusCode,
+          { error: error.message },
+          error.closeConnection ? () => request.destroy() : undefined,
+        );
+      } else if (!response.headersSent && signal.aborted && !requestController.signal.aborted) {
+        writeJson(response, 503, { error: 'Callback Host unavailable' });
+      } else if (!response.headersSent && !requestSignal.aborted) {
+        writeJson(response, 400, { error: 'Callback rejected' });
+      }
+    } finally {
+      request.off('aborted', abortRequest);
+    }
+  }, {
+    summary: 'Authenticated Workroom remote execution callback',
+    tags: ['workroom', 'a2a-callback'],
+  });
+
+  let disposed = false;
+  return Object.freeze({
+    get recovery() { return recovery; },
+    async recover(recoverySignal?: AbortSignal) {
+      const activeSignal = recoverySignal
+        ? AbortSignal.any([signal, recoverySignal])
+        : signal;
+      recovery = await recoverRegisteredLinks(
+        options.dependencies,
+        activeSignal,
+        options.onRecoveryError,
+      );
+      return recovery;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      controller.abort(new Error('Workroom callback Host retired'));
+      unregister();
+    },
+  });
+}
+
+async function recoverRegisteredLinks(
+  dependencies: RuntimeWorkroomCallbackDependencies,
+  signal: AbortSignal,
+  onRecoveryError: ((linkId: string, error: unknown) => void) | undefined,
+): Promise<RuntimeWorkroomCallbackRecoverySummary> {
+  signal.throwIfAborted();
+  const records = [...await dependencies.linkRegistry.listRegistered()]
+    .sort((left, right) => left.id.localeCompare(right.id));
+  let recovered = 0;
+  let failed = 0;
+  for (const record of records) {
+    signal.throwIfAborted();
+    try {
+      await dependencies.application.runOnce(record.id, signal);
+      recovered += 1;
+    } catch (error) {
+      failed += 1;
+      onRecoveryError?.(record.id, error);
+    }
+    signal.throwIfAborted();
+  }
+  signal.throwIfAborted();
+  return Object.freeze({ registered: records.length, recovered, failed });
+}
+
+class RuntimeWorkroomCallbackBodyError extends Error {
+  constructor(
+    message: string,
+    readonly statusCode: 400 | 413,
+    readonly closeConnection = false,
+  ) {
+    super(message);
+    this.name = 'RuntimeWorkroomCallbackBodyError';
+  }
+}
+
+async function readRawBody(request: IncomingMessage, limit: number): Promise<Uint8Array> {
+  const declaredLength = declaredContentLength(request);
+  if (declaredLength !== undefined && declaredLength > limit) {
+    request.pause();
+    throw new RuntimeWorkroomCallbackBodyError(
+      `Callback body exceeds ${limit} bytes`,
+      413,
+      true,
+    );
+  }
+  const chunks = await new Promise<Buffer[]>((resolve, reject) => {
+    const buffered: Buffer[] = [];
+    let size = 0;
+    const cleanup = () => {
+      request.off('data', onData);
+      request.off('end', onEnd);
+      request.off('error', onError);
+      request.off('aborted', onAborted);
+    };
+    const onData = (chunk: Buffer | string) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      size += buffer.length;
+      if (size > limit) {
+        request.pause();
+        cleanup();
+        reject(new RuntimeWorkroomCallbackBodyError(
+          `Callback body exceeds ${limit} bytes`,
+          413,
+          true,
+        ));
+        return;
+      }
+      buffered.push(buffer);
+    };
+    const onEnd = () => {
+      cleanup();
+      resolve(buffered);
+    };
+    const onError = (error: Error) => {
+      cleanup();
+      reject(error);
+    };
+    const onAborted = () => {
+      cleanup();
+      reject(new Error('Callback request aborted'));
+    };
+    request.on('data', onData);
+    request.once('end', onEnd);
+    request.once('error', onError);
+    request.once('aborted', onAborted);
+  });
+  if (chunks.length === 0) {
+    throw new RuntimeWorkroomCallbackBodyError('Callback body is required', 400);
+  }
+  return Buffer.concat(chunks);
+}
+
+function declaredContentLength(request: IncomingMessage): number | undefined {
+  const value = request.headers['content-length'];
+  if (typeof value !== 'string' || !/^\d+$/u.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : Number.POSITIVE_INFINITY;
+}
+
+function bearerCredential(request: IncomingMessage): string | undefined {
+  const value = request.headers.authorization;
+  if (typeof value !== 'string') return undefined;
+  const match = /^Bearer ([^\s]+)$/u.exec(value);
+  return match?.[1];
+}
+
+function normalizeExactPath(value: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error('Workroom callback path is required');
+  }
+  const leading = value.startsWith('/') ? value : `/${value}`;
+  let end = leading.length;
+  while (end > 1 && leading.charCodeAt(end - 1) === 47) end -= 1;
+  const normalized = leading.slice(0, end);
+  if (normalized.includes('*')) throw new Error('Workroom callback path must be exact');
+  return normalized;
+}
+
+function normalizeBasePath(value: string): string {
+  return normalizeExactPath(value);
+}
+
+function positiveInteger(value: unknown, field: string): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 1) {
+    throw new Error(`Workroom callback ${field} must be a positive safe integer`);
+  }
+  return Number(value);
+}
+
+function writeJson(
+  response: ServerResponse,
+  status: number,
+  value: unknown,
+  afterSend?: () => void,
+): void {
+  const body = JSON.stringify(value);
+  response.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': String(Buffer.byteLength(body)),
+    ...(afterSend ? { connection: 'close' } : {}),
+  });
+  response.end(body, afterSend);
+}