agentic-orchestrator 0.1.0

package/apps/control-plane/src/mcp/token-claims-validator.ts

@@ -0,0 +1,72 @@
+import { ERROR_CODES } from '../core/error-codes.js';
+import { fail } from '../core/response.js';
+import type { VerifiedActorClaims } from './runtime-types.js';
+
+function isValidIsoDate(value: string): boolean {
+  const parsed = new Date(value);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}
+
+function claimsValidationError(message: string) {
+  return {
+    normalizedResponse: fail(ERROR_CODES.UNAUTHENTICATED, message, {
+      retryable: false,
+      requires_human: true
+    })
+  };
+}
+
+export class TokenClaimsValidator {
+  private readonly now: () => Date;
+
+  constructor(now: () => Date) {
+    this.now = now;
+  }
+
+  validate(claims: VerifiedActorClaims, options: { checkExpiry?: boolean } = {}): void {
+    const checkExpiry = options.checkExpiry ?? true;
+    const requiredStringFields: Array<keyof VerifiedActorClaims> = [
+      'run_id',
+      'session_id',
+      'actor_type',
+      'actor_id',
+      'issued_at',
+      'expires_at'
+    ];
+    for (const field of requiredStringFields) {
+      if (!claims[field] || typeof claims[field] !== 'string') {
+        throw claimsValidationError(`missing_claim_${field}`);
+      }
+    }
+
+    if (!isValidIsoDate(claims.issued_at) || !isValidIsoDate(claims.expires_at)) {
+      throw claimsValidationError('invalid_claim_timestamp');
+    }
+
+    if (claims.actor_type === 'system' && !claims.session_id.startsWith('bootstrap:')) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.FORBIDDEN_TOOL_FOR_ROLE, 'system_role_requires_bootstrap_session', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    if (claims.feature_scope != null && !Array.isArray(claims.feature_scope)) {
+      throw claimsValidationError('invalid_feature_scope_claim');
+    }
+
+    if (checkExpiry) {
+      const nowMs = this.now().getTime();
+      const expiresAtMs = new Date(claims.expires_at).getTime();
+      if (expiresAtMs < nowMs) {
+        throw claimsValidationError('session_token_expired');
+      }
+    }
+  }
+
+  wrapCodecError(error: unknown): never {
+    const message = error instanceof Error ? error.message : String(error);
+    throw claimsValidationError(message);
+  }
+}

package/apps/control-plane/src/mcp/token-codec.ts

@@ -0,0 +1,62 @@
+import crypto from 'node:crypto';
+import type { VerifiedActorClaims } from './runtime-types.js';
+
+export interface TokenHeader {
+  alg: 'HS256';
+  typ: 'JWT';
+}
+
+function base64urlEncode(input: string): string {
+  return Buffer.from(input, 'utf8').toString('base64url');
+}
+
+function base64urlDecode(input: string): string {
+  return Buffer.from(input, 'base64url').toString('utf8');
+}
+
+function sign(secret: string, payload: string): string {
+  return crypto.createHmac('sha256', secret).update(payload).digest('base64url');
+}
+
+export class SessionTokenCodec {
+  private readonly secret: string;
+
+  constructor(secret: string) {
+    this.secret = secret;
+  }
+
+  issue(claims: VerifiedActorClaims): string {
+    const header: TokenHeader = { alg: 'HS256', typ: 'JWT' };
+    const encodedHeader = base64urlEncode(JSON.stringify(header));
+    const encodedClaims = base64urlEncode(JSON.stringify(claims));
+    const signature = sign(this.secret, `${encodedHeader}.${encodedClaims}`);
+    return `${encodedHeader}.${encodedClaims}.${signature}`;
+  }
+
+  decodeAndVerify(token: string): VerifiedActorClaims {
+    if (!token || typeof token !== 'string') {
+      throw new Error('missing_session_token');
+    }
+
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      throw new Error('invalid_session_token_format');
+    }
+
+    const [encodedHeader, encodedPayload, receivedSignature] = parts;
+    const expectedSignature = sign(this.secret, `${encodedHeader}.${encodedPayload}`);
+    if (expectedSignature.length !== receivedSignature.length) {
+      throw new Error('invalid_session_signature');
+    }
+    if (!crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(receivedSignature))) {
+      throw new Error('invalid_session_signature');
+    }
+
+    const header = JSON.parse(base64urlDecode(encodedHeader)) as TokenHeader;
+    if (header.alg !== 'HS256' || header.typ !== 'JWT') {
+      throw new Error('invalid_session_header');
+    }
+
+    return JSON.parse(base64urlDecode(encodedPayload)) as VerifiedActorClaims;
+  }
+}

package/apps/control-plane/src/mcp/tool-authorizer.ts

@@ -0,0 +1,43 @@
+import type { LoadedToolRegistry } from './runtime-types.js';
+
+export class ToolAuthorizer {
+  readonly policyRbac: Record<string, string[]>;
+  readonly registry: LoadedToolRegistry;
+
+  constructor(policyRbac: Record<string, string[]> = {}, registry: LoadedToolRegistry) {
+    this.policyRbac = policyRbac;
+    this.registry = registry;
+    this.assertPolicyIntersectionIsValid();
+  }
+
+  isAuthorized(actorType: string, toolName: string): boolean {
+    const tool = this.registry.toolsByName.get(toolName);
+    if (!tool) {
+      return false;
+    }
+
+    const policyAllowlist = this.policyRbac[actorType] ?? [];
+    const policyAllows = policyAllowlist.includes('*') || policyAllowlist.includes(toolName);
+    const registryAllows = tool.supported_roles.includes(actorType);
+    return policyAllows && registryAllows;
+  }
+
+  private assertPolicyIntersectionIsValid(): void {
+    for (const [role, allowlist] of Object.entries(this.policyRbac)) {
+      const effective = allowlist.includes('*')
+        ? [...this.registry.toolsByName.keys()]
+        : allowlist;
+
+      for (const toolName of effective) {
+        const tool = this.registry.toolsByName.get(toolName);
+        if (!tool) {
+          throw new Error(`policy_references_unknown_tool:${role}:${toolName}`);
+        }
+
+        if (!tool.supported_roles.includes(role)) {
+          throw new Error(`policy_role_outside_supported_roles:${role}:${toolName}`);
+        }
+      }
+    }
+  }
+}

package/apps/control-plane/src/mcp/tool-client.ts

@@ -0,0 +1,78 @@
+import crypto from 'node:crypto';
+import type { ToolResponse } from '../core/response.js';
+import type { VerifiedActorClaims } from './runtime-types.js';
+import type { ToolDescriptor } from './transport-types.js';
+import { type McpServerAdapter } from './mcp-server-adapter.js';
+import { type TokenAuthVerifier } from './token-auth-verifier.js';
+import { type ToolRuntime } from './tool-runtime.js';
+
+export interface ToolClientIdentity {
+  run_id: string;
+  session_id: string;
+  actor_type: string;
+  actor_id: string;
+  feature_scope?: string[];
+}
+
+export interface ToolClient {
+  listTools(): Promise<ToolDescriptor[]>;
+  call(toolName: string, args: Record<string, unknown>, identity: ToolClientIdentity): Promise<ToolResponse>;
+}
+
+function toVerifiedClaims(identity: ToolClientIdentity): VerifiedActorClaims {
+  const now = new Date();
+  return {
+    ...identity,
+    issued_at: now.toISOString(),
+    expires_at: new Date(now.getTime() + 15 * 60 * 1000).toISOString()
+  };
+}
+
+export class InProcessToolClient implements ToolClient {
+  readonly runtime: ToolRuntime;
+
+  constructor(runtime: ToolRuntime) {
+    this.runtime = runtime;
+  }
+
+  async listTools(): Promise<ToolDescriptor[]> {
+    return await this.runtime.listTools();
+  }
+
+  async call(toolName: string, args: Record<string, unknown>, identity: ToolClientIdentity): Promise<ToolResponse> {
+    return await this.runtime.callTool(toolName, args, toVerifiedClaims(identity));
+  }
+}
+
+export class McpToolClient implements ToolClient {
+  readonly adapter: McpServerAdapter;
+  readonly authVerifier: TokenAuthVerifier;
+
+  constructor(adapter: McpServerAdapter, authVerifier: TokenAuthVerifier) {
+    this.adapter = adapter;
+    this.authVerifier = authVerifier;
+  }
+
+  async listTools(): Promise<ToolDescriptor[]> {
+    const response = await this.adapter.toolsList();
+    return response.tools;
+  }
+
+  async call(toolName: string, args: Record<string, unknown>, identity: ToolClientIdentity): Promise<ToolResponse> {
+    const token = this.authVerifier.issueToken(identity);
+    return await this.adapter.toolsCall({
+      name: toolName,
+      arguments: args,
+      session_token: token
+    });
+  }
+}
+
+export function createOperationId(toolName: string, featureId?: string): string {
+  const parts = [toolName.replace(/[^a-zA-Z0-9]/g, '_')];
+  if (featureId) {
+    parts.push(featureId.replace(/[^a-zA-Z0-9_-]/g, '_'));
+  }
+  parts.push(crypto.randomUUID());
+  return parts.join('__');
+}

package/apps/control-plane/src/mcp/tool-contract-validator.ts

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import Ajv2020Import from 'ajv/dist/2020.js';
+import type { ErrorObject, ValidateFunction } from 'ajv';
+import type { LoadedToolRegistry, ToolCatalogEntry } from './runtime-types.js';
+import { type ToolRegistryLoader } from './tool-registry-loader.js';
+
+interface AjvInstance {
+  compile(schema: Record<string, unknown>): ValidateFunction;
+}
+
+function createAjvInstance(): AjvInstance {
+  const Ajv2020Ctor = Ajv2020Import as unknown as new (
+    options?: Record<string, unknown>
+  ) => AjvInstance;
+  return new Ajv2020Ctor({ allErrors: true, strict: false });
+}
+
+export class ToolContractValidator {
+  readonly loader: ToolRegistryLoader;
+  readonly registry: LoadedToolRegistry;
+  readonly ajv: AjvInstance;
+  readonly validators: Map<string, ValidateFunction>;
+  readonly errorsValidator: ValidateFunction;
+
+  private constructor(
+    loader: ToolRegistryLoader,
+    registry: LoadedToolRegistry,
+    ajv: AjvInstance,
+    errorsValidator: ValidateFunction
+  ) {
+    this.loader = loader;
+    this.registry = registry;
+    this.ajv = ajv;
+    this.validators = new Map();
+    this.errorsValidator = errorsValidator;
+  }
+
+  static async create(loader: ToolRegistryLoader, registry: LoadedToolRegistry): Promise<ToolContractValidator> {
+    const ajv = createAjvInstance();
+    const errorsSchema = await loader.readErrorsSchema();
+    const errorsValidator = ajv.compile(errorsSchema);
+    return new ToolContractValidator(loader, registry, ajv, errorsValidator);
+  }
+
+  async validateInput(tool: ToolCatalogEntry, payload: unknown): Promise<{ valid: boolean; errors: ErrorObject[] }> {
+    const validator = await this.getOrCompile(tool.input_schema_ref);
+    const valid = validator(payload);
+    return {
+      valid: Boolean(valid),
+      errors: valid ? [] : ((validator.errors ?? []))
+    };
+  }
+
+  async validateOutput(tool: ToolCatalogEntry, payload: unknown): Promise<{ valid: boolean; errors: ErrorObject[] }> {
+    const validator = await this.getOrCompile(tool.output_schema_ref);
+    const valid = validator(payload);
+    return {
+      valid: Boolean(valid),
+      errors: valid ? [] : ((validator.errors ?? []))
+    };
+  }
+
+  validateErrorEnvelope(response: unknown): { valid: boolean; errors: ErrorObject[] } {
+    const valid = this.errorsValidator(response);
+    return {
+      valid: Boolean(valid),
+      errors: valid ? [] : ((this.errorsValidator.errors ?? []))
+    };
+  }
+
+  private async getOrCompile(schemaRef: string): Promise<ValidateFunction> {
+    const absolute = path.resolve(this.registry.toolsRoot, schemaRef);
+    const existing = this.validators.get(absolute);
+    if (existing) {
+      return existing;
+    }
+
+    const schema = await this.loader.readSchemaByRef(schemaRef);
+    const validator = this.ajv.compile(schema);
+    this.validators.set(absolute, validator);
+    return validator;
+  }
+}

package/apps/control-plane/src/mcp/tool-registry-loader.ts

@@ -0,0 +1,135 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists } from '../core/fs.js';
+import { MCP_PROTOCOL_PIN, REQUIRED_MCP_TRANSPORTS } from './protocol-contract.js';
+import type { LoadedToolRegistry, ProtocolContract, ToolCatalog, ToolCatalogEntry } from './runtime-types.js';
+
+export class ToolRegistryLoader {
+  readonly repoRoot: string;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+  }
+
+  get toolsRoot(): string {
+    return path.join(this.repoRoot, 'agentic', 'orchestrator', 'tools');
+  }
+
+  get catalogPath(): string {
+    return path.join(this.toolsRoot, 'catalog.json');
+  }
+
+  get protocolPath(): string {
+    return path.join(this.toolsRoot, 'protocol.json');
+  }
+
+  get errorsSchemaPath(): string {
+    return path.join(this.toolsRoot, 'errors.schema.json');
+  }
+
+  resolveSchemaPath(schemaRef: string): string {
+    return path.resolve(this.toolsRoot, schemaRef);
+  }
+
+  async load(): Promise<LoadedToolRegistry> {
+    const catalog = await this.readCatalog();
+    const protocol = await this.readProtocol();
+
+    const toolsByName = new Map<string, ToolCatalogEntry>();
+    const toolsByHandlerId = new Map<string, ToolCatalogEntry>();
+
+    for (const tool of catalog.tools) {
+      if (toolsByName.has(tool.name)) {
+        throw new Error(`registry_duplicate_tool_name:${tool.name}`);
+      }
+      if (toolsByHandlerId.has(tool.handler_id)) {
+        throw new Error(`registry_duplicate_handler_id:${tool.handler_id}`);
+      }
+
+      if (!Array.isArray(tool.supported_roles) || tool.supported_roles.length === 0) {
+        throw new Error(`registry_supported_roles_missing:${tool.name}`);
+      }
+      if (tool.mutating && tool.requires_operation_id !== true) {
+        throw new Error(`registry_mutating_requires_operation_id:${tool.name}`);
+      }
+
+      const inputSchemaPath = this.resolveSchemaPath(tool.input_schema_ref);
+      const outputSchemaPath = this.resolveSchemaPath(tool.output_schema_ref);
+      if (!(await pathExists(inputSchemaPath))) {
+        throw new Error(`registry_missing_input_schema:${tool.name}:${tool.input_schema_ref}`);
+      }
+      if (!(await pathExists(outputSchemaPath))) {
+        throw new Error(`registry_missing_output_schema:${tool.name}:${tool.output_schema_ref}`);
+      }
+
+      toolsByName.set(tool.name, tool);
+      toolsByHandlerId.set(tool.handler_id, tool);
+    }
+
+    if (!(await pathExists(this.errorsSchemaPath))) {
+      throw new Error('registry_missing_errors_schema');
+    }
+
+    return {
+      toolsRoot: this.toolsRoot,
+      catalogPath: this.catalogPath,
+      protocolPath: this.protocolPath,
+      catalog,
+      protocol,
+      toolsByName,
+      toolsByHandlerId
+    };
+  }
+
+  async readSchemaByRef(schemaRef: string): Promise<Record<string, unknown>> {
+    const absolute = this.resolveSchemaPath(schemaRef);
+    const text = await fs.readFile(absolute, 'utf8');
+    return JSON.parse(text) as Record<string, unknown>;
+  }
+
+  async readErrorsSchema(): Promise<Record<string, unknown>> {
+    const text = await fs.readFile(this.errorsSchemaPath, 'utf8');
+    return JSON.parse(text) as Record<string, unknown>;
+  }
+
+  private async readCatalog(): Promise<ToolCatalog> {
+    const text = await fs.readFile(this.catalogPath, 'utf8');
+    const parsed = JSON.parse(text) as ToolCatalog;
+
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.tools)) {
+      throw new Error('registry_invalid_catalog_shape');
+    }
+
+    return parsed;
+  }
+
+  private async readProtocol(): Promise<ProtocolContract> {
+    const text = await fs.readFile(this.protocolPath, 'utf8');
+    const parsed = JSON.parse(text) as ProtocolContract;
+
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error('registry_invalid_protocol_shape');
+    }
+    if (!parsed.mcp_protocol_version || !parsed.sdk?.package || !parsed.sdk?.version) {
+      throw new Error('registry_invalid_protocol_fields');
+    }
+    if (!Array.isArray(parsed.enabled_transports) || parsed.enabled_transports.length === 0) {
+      throw new Error('registry_invalid_protocol_transports');
+    }
+    if (
+      parsed.mcp_protocol_version !== MCP_PROTOCOL_PIN.mcp_protocol_version ||
+      parsed.sdk.package !== MCP_PROTOCOL_PIN.sdk.package ||
+      parsed.sdk.version !== MCP_PROTOCOL_PIN.sdk.version
+    ) {
+      throw new Error('registry_protocol_pin_mismatch');
+    }
+    for (const requiredTransport of REQUIRED_MCP_TRANSPORTS) {
+      if (!parsed.enabled_transports.includes(requiredTransport)) {
+        throw new Error(`registry_missing_required_transport:${requiredTransport}`);
+      }
+    }
+
+    return parsed;
+  }
+
+}