@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/mcp/broker.mjs

@@ -8,27 +8,139 @@
  * `Broker.invoke({...})`, every denial emits a typed error rather than
  * a silent fallthrough, and every brokered call appends a `tool.called`
  * trace event tagged with the policy decision.
+ *
+ * LMCP-I3: every decision (allow/deny/approval_required) is also recorded
+ * as durable evidence under one schema — {decisionId, actor, tenant,
+ * project, tool, target, risk, outcome, correlationId, ts} — via
+ * `_recordDecision`. Denied decisions additionally persist to
+ * lib/mcp/denied-store.mjs so a PolicyDenied throw is never the only trace
+ * of the denial. `correlationId` reuses an inbound `traceId` when the
+ * caller has one, or mints a fresh trace-shaped id, so the same value ties
+ * the broker call to its `tool.called` trace event and to any run/task/
+ * external write layered on top by the caller.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
 import { policyDecision } from '../policy/engine.mjs';
-import { emitTraceEvent } from '../worker/trace.mjs';
+import { emitTraceEvent, newTraceId } from '../worker/trace.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { ApprovalQueue } from '../embed/approval-queue.mjs';
+import { resolveTenantContext } from '../tenant/context.mjs';
+import { appendAuditRecord } from '../audit-trail.mjs';
+import { DeniedStore } from './denied-store.mjs';
+import { ConsumptionBudgetStore, BudgetExceeded } from '../policy/consumption-budget.mjs';
 
 const DEFAULT_RATE_WINDOW_MS = 60_000;
 const DEFAULT_RATE_BUDGET = 30;
 
+// Every broker decision — allow, deny, or approval-required — is recorded
+// under this one schema so the durable denied-store and the audit-trail
+// entry for the same decision can be cross-referenced by decisionId, and a
+// correlationId ties the decision back to the trace event and, downstream,
+// to whatever run/task/external write the tool call was part of.
+
+function newDecisionId() {
+  return `decision-${crypto.randomBytes(8).toString('hex')}`;
+}
+
+function buildDecisionRecord({ decision, outcome, actor, tenant, project, tool, target, risk, correlationId, ts }) {
+  return {
+    decisionId: newDecisionId(),
+    actor: actor ?? 'unknown',
+    tenant: tenant ?? 'unknown',
+    project: project ?? null,
+    tool: tool ?? 'unknown',
+    target: target ?? null,
+    risk: risk || 'low',
+    outcome,
+    correlationId,
+    reason: decision?.reason ?? null,
+    source: decision?.source ?? null,
+    ts,
+  };
+}
+
+/**
+ * BrokerStore — file-backed durable storage for broker rate-limit state.
+ *
+ * Persists call timestamps to `<rootDir>/.cx/broker-state.json` so that
+ * rate-limit windows survive broker instance recreation and server restarts.
+ * In-memory `_data` is the authoritative write buffer; `load`/`save` sync
+ * against disk. All disk I/O is best-effort: a disk failure leaves in-memory
+ * state intact without crashing the broker.
+ * Rate-limit windows are keyed by actor+tool+windowStart (epoch ms).
+ */
+export class BrokerStore {
+  constructor() {
+    // key → timestamp[] (ms since epoch), trimmed to current window on read
+    this._data = {};
+  }
+
+  /** Load persisted state from `storePath`. No-op if the file is absent or unreadable. */
+  load(storePath) {
+    try {
+      const raw = fs.readFileSync(storePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        this._data = parsed;
+      }
+    } catch { /* absent or corrupt file — start fresh */ }
+  }
+
+  /** Persist current state to `storePath`. Best-effort. */
+  save(storePath) {
+    try {
+      fs.mkdirSync(path.dirname(storePath), { recursive: true });
+      fs.writeFileSync(storePath, JSON.stringify(this._data), 'utf8');
+    } catch { /* best-effort */ }
+  }
+
+  /**
+   * getRateLimitState(actor, tool, windowMs) → timestamps[] within the window.
+   * Trims stale entries before returning.
+   */
+  getRateLimitState(actor, tool, windowMs) {
+    const key = `${actor}::${tool}`;
+    const now = Date.now();
+    const all = this._data[key] || [];
+    const fresh = all.filter((ts) => now - ts < windowMs);
+    this._data[key] = fresh;
+    return fresh;
+  }
+
+  /**
+   * incrementRateLimitState(actor, tool, windowMs) → updated timestamps[].
+   * Appends `Date.now()` and trims stale entries.
+   */
+  incrementRateLimitState(actor, tool, windowMs) {
+    const key = `${actor}::${tool}`;
+    const now = Date.now();
+    const all = this._data[key] || [];
+    const fresh = all.filter((ts) => now - ts < windowMs);
+    fresh.push(now);
+    this._data[key] = fresh;
+    return fresh;
+  }
+}
+
 export class PolicyDenied extends Error {
-  constructor(decision) {
+  constructor(decision, correlationId = null) {
     super(`policy denied: ${decision.reason}`);
     this.name = 'PolicyDenied';
     this.decision = decision;
+    this.correlationId = correlationId;
   }
 }
 
 export class ApprovalRequired extends Error {
-  constructor(decision) {
+  constructor(decision, correlationId = null) {
     super(`approval required: ${decision.reason}`);
     this.name = 'ApprovalRequired';
     this.decision = decision;
+    this.correlationId = correlationId;
   }
 }
 
@@ -49,6 +161,13 @@ export class Broker {
     rateBudget = DEFAULT_RATE_BUDGET,
     rateWindowMs = DEFAULT_RATE_WINDOW_MS,
     now = () => Date.now(),
+    store,
+    approvalQueue,
+    deniedStore,
+    consumptionBudgets,
+    tenantContext,
+    auditRecorder = appendAuditRecord,
+    env = process.env,
   } = {}) {
     if (!rootDir) throw new Error('Broker: rootDir is required');
     this.rootDir = rootDir;
@@ -57,42 +176,170 @@ export class Broker {
     this.rateBudget = rateBudget;
     this.rateWindowMs = rateWindowMs;
     this.now = now;
+    // Durable store for rate-limit state.
+    this._storePath = path.join(rootDir, '.cx', 'broker-state.json');
+    this._store = store instanceof BrokerStore ? store : new BrokerStore();
+    if (!(store instanceof BrokerStore)) {
+      this._store.load(this._storePath);
+    }
+    // Approval queue for durable awaiting_approval state (per ADR-0056).
+    this.approvalQueue = approvalQueue || null;
+    // Durable store for denied decisions (LMCP-I3) — every PolicyDenied
+    // throw also lands a row here, keyed by decisionId, before the error
+    // leaves invoke().
+    this._deniedStore = deniedStore instanceof DeniedStore ? deniedStore : new DeniedStore({ rootDir });
+    // Durable per-actor/run consumption budgets (LMCP-N5) — checked pre-
+    // execution when a caller passes `runId`; a caller that never passes
+    // one sees no budget behavior at all (backward compatible).
+    this._consumptionBudgets = consumptionBudgets instanceof ConsumptionBudgetStore
+      ? consumptionBudgets
+      : new ConsumptionBudgetStore({ rootDir, env });
+    // Audit recorder is injectable so tests can capture records without
+    // touching the real ~/.cx/audit-trail.jsonl file.
+    this._auditRecorder = auditRecorder;
+    // Tenant resolved once per broker instance (env/config are stable for
+    // the process lifetime); reused for every decision record.
+    this._tenant = tenantContext || resolveTenantContext({ env, mode: getDeploymentMode(env, { cwd: rootDir }) }).tenantId;
+    // Keep this.calls as an in-memory Map for callers that read it directly
     this.calls = new Map();
   }
 
+  /**
+   * Attach an ApprovalQueue instance to this broker after construction.
+   */
+  setApprovalQueue(queue) {
+    this.approvalQueue = queue;
+  }
+
   _checkRate(role, tool) {
-    const key = `${role}::${tool}`;
-    const ts = this.now();
-    const window = this.calls.get(key) || [];
-    const fresh = window.filter((t) => ts - t < this.rateWindowMs);
+    const fresh = this._store.getRateLimitState(role, tool, this.rateWindowMs);
     if (fresh.length >= this.rateBudget) throw new RateLimited(role, tool, this.rateBudget);
-    fresh.push(ts);
-    this.calls.set(key, fresh);
+    this._store.incrementRateLimitState(role, tool, this.rateWindowMs);
+    // Persist after every update so the state is durable across restarts.
+    this._store.save(this._storePath);
+    // Keep the legacy Map in sync for any callers inspecting it directly.
+    this.calls.set(`${role}::${tool}`, this._store.getRateLimitState(role, tool, this.rateWindowMs));
+  }
+
+  // requestedBy already carries the H2 identity record (identityToRecord()
+  // shape: userId/serviceId/role/...) at every call site observed in
+  // lib/mcp/server.mjs and lib/writes/envelope.mjs. Fall back to role, then
+  // to 'unknown' rather than fabricating an identity that was never resolved.
+
+  _resolveActor(role, requestedBy) {
+    if (requestedBy && typeof requestedBy === 'object') {
+      const id = requestedBy.userId || requestedBy.serviceId;
+      if (id) return id;
+    }
+    return role || 'unknown';
+  }
+
+  /**
+   * Record a broker decision as durable evidence: a denied-store row when
+   * the outcome is 'denied' or 'budget_denied' (LMCP-N5 — a budget refusal
+   * is a denial under the same schema, just from a different gate than the
+   * policy engine), and an audit-trail entry for every outcome (allow/deny/
+   * approval/budget_denied) under the same schema. Both writes are
+   * best-effort — a disk failure here must never break tool dispatch, the
+   * same guarantee lib/mcp/server.mjs already gives its own audit call.
+   */
+  _recordDecision({ decision, outcome, role, tool, action, risk, project, requestedBy, correlationId }) {
+    const record = buildDecisionRecord({
+      decision,
+      outcome,
+      actor: this._resolveActor(role, requestedBy),
+      tenant: this._tenant,
+      project,
+      tool,
+      target: action ?? null,
+      risk,
+      correlationId,
+      ts: new Date(this.now()).toISOString(),
+    });
+
+    if (outcome === 'denied' || outcome === 'budget_denied') {
+      try { this._deniedStore.append(record); } catch { /* best-effort, mirrors BrokerStore.save */ }
+    }
+
+    try { this._auditRecorder({ agent: 'mcp-broker', ...record }); } catch { /* audit trail unavailable must not fail the call */ }
+
+    return record;
   }
 
   /**
    * Invoke a tool through the broker. The `execute` function does the
    * actual work; the broker decides whether to call it.
    *
+   * When approval is required, returns a structured `{ status, approvalId,
+   * resumeToken, expiresAt }` instead of throwing. Callers that retry with
+   * the same tool+args will match the existing approval record. After the
+   * record is approved (via CLI or API), a call with the same args executes
+   * the tool. Pass `resumeToken` explicitly to bypass argsHash dedup.
+   *
    * @param {object} args
    * @param {string} args.role
    * @param {string} args.tool
    * @param {string} args.action
+   * @param {object} [args.toolArgs]  - Raw tool arguments for argsHash dedup
    * @param {string} [args.risk]
    * @param {string} [args.project]
    * @param {string} [args.traceId]
+   * @param {string} [args.resumeToken] - Explicit resume token (bypasses dedup)
+   * @param {object} [args.requestedBy] - Actor identity (identityToRecord() shape)
+   * @param {string} [args.runId] - LMCP-N5: attributes consumption to a run; omitted means no budget check at all
+   * @param {number} [args.tokenEstimate] - LMCP-N5: tokens this call is expected to consume, counted toward the run's token budget
+   * @param {object} [args.budget] - LMCP-N5: explicit budget override (defaults to the deployment-mode default)
    * @param {Function} args.execute
-   * @returns {Promise<{result, decision}>}
+   * @returns {Promise<{result, decision, correlationId}|{status, approvalId, resumeToken, expiresAt, correlationId}>}
    */
-  async invoke({ role, tool, action, risk, project, traceId, execute }) {
+  async invoke({ role, tool, action, toolArgs, risk, project, traceId, resumeToken, requestedBy, runId, tokenEstimate = 0, budget, execute }) {
     if (typeof execute !== 'function') throw new Error('Broker.invoke: execute function is required');
 
+    // If a resumeToken is provided, look up the approval record directly.
+    if (resumeToken && this.approvalQueue) {
+      const record = this.approvalQueue.getByResumeToken(resumeToken);
+      if (!record) return { status: 'not_found', resumeToken };
+      if (record.state === 'approved') {
+        const result = await execute();
+        return { result, decision: { allowed: true, reason: 'resumed after approval', approvalRequired: false, source: 'approval-queue' } };
+      }
+      if (record.state === 'denied') return { status: 'denied', approvalId: record.approvalId, reason: record.reason };
+      if (record.state === 'expired') return { status: 'expired', approvalId: record.approvalId };
+      return { status: 'awaiting_approval', approvalId: record.approvalId, resumeToken: record.resumeToken, expiresAt: record.expiresAt };
+    }
+
+    // Compute argsHash for dedup with the approval queue.
+    const argsHash = this.approvalQueue ? ApprovalQueue.hashToolCall(tool, toolArgs ?? {}) : null;
+
+    // Check if there is already an approval record for this exact tool call.
+    if (this.approvalQueue && argsHash) {
+      this.approvalQueue.expireStale();
+      const existing = this.approvalQueue.findByToolArgs(tool, argsHash);
+      if (existing) {
+        if (existing.state === 'approved') {
+          const result = await execute();
+          return { result, decision: { allowed: true, reason: 'approved via queue', approvalRequired: false, source: 'approval-queue' } };
+        }
+        if (existing.state === 'denied') return { status: 'denied', approvalId: existing.approvalId, reason: existing.reason };
+        if (existing.state === 'expired') return { status: 'expired', approvalId: existing.approvalId };
+        return { status: 'awaiting_approval', approvalId: existing.approvalId, resumeToken: existing.resumeToken, expiresAt: existing.expiresAt };
+      }
+    }
+
     const decision = this.policy({ role, project, tool, action, risk });
 
+    // correlationId ties this broker decision to the tool.called trace event
+    // (same value as traceId), and downstream to whatever run/task/external
+    // write the caller layers on top — reuse an inbound traceId so a caller
+    // that already has one keeps a single id across the whole chain, and
+    // mint a trace-shaped id only when the caller supplied none.
+
+    const correlationId = traceId || newTraceId();
+
     this.emit({
       rootDir: this.rootDir,
       eventType: 'tool.called',
-      traceId,
+      traceId: correlationId,
       project,
       role,
       metadata: {
@@ -106,19 +353,87 @@ export class Broker {
       },
     });
 
-    if (!decision.allowed) throw new PolicyDenied(decision);
-    if (decision.approvalRequired) throw new ApprovalRequired(decision);
+    if (!decision.allowed) {
+      this._recordDecision({ decision, outcome: 'denied', role, tool, action, risk, project, requestedBy, correlationId });
+      throw new PolicyDenied(decision, correlationId);
+    }
+
+    if (decision.approvalRequired) {
+      this._recordDecision({ decision, outcome: 'approval_required', role, tool, action, risk, project, requestedBy, correlationId });
+      if (this.approvalQueue) {
+        const record = this.approvalQueue.enqueue({
+          tool,
+          args: toolArgs ?? {},
+          surface: 'mcp',
+          argsHash,
+          requestedBy: requestedBy ?? { role },
+        });
+        return {
+          status: 'awaiting_approval',
+          approvalId: record.approvalId,
+          resumeToken: record.resumeToken,
+          expiresAt: record.expiresAt,
+          correlationId,
+        };
+      }
+      // No queue configured — fall back to throwing for backward compat.
+      throw new ApprovalRequired(decision, correlationId);
+    }
+
+    this._recordDecision({ decision, outcome: 'allowed', role, tool, action, risk, project, requestedBy, correlationId });
+
+    // LMCP-N5: a caller with no runId gets no budget behavior at all — only
+    // an attributed run accrues durable consumption, so this is additive to
+    // every call site that predates runId.
+    if (runId) {
+      const actor = this._resolveActor(role, requestedBy);
+      const toolCallCheck = this._consumptionBudgets.check(actor, runId, 'toolCalls', 1, { budget });
+      const tokenCheck = tokenEstimate > 0
+        ? this._consumptionBudgets.check(actor, runId, 'tokens', tokenEstimate, { budget })
+        : { allowed: true };
+      const failed = !toolCallCheck.allowed ? { kind: 'toolCalls', check: toolCallCheck } : (!tokenCheck.allowed ? { kind: 'tokens', check: tokenCheck } : null);
+      if (failed) {
+        const budgetDecision = {
+          allowed: false,
+          approvalRequired: false,
+          reason: `consumption budget exceeded: ${failed.kind} would reach ${failed.check.projected} against a budget of ${failed.check.cap}`,
+          source: 'consumption-budget',
+        };
+        this._recordDecision({ decision: budgetDecision, outcome: 'budget_denied', role, tool, action, risk, project, requestedBy, correlationId });
+        throw new BudgetExceeded({ actor, runId, kind: failed.kind, cap: failed.check.cap, projected: failed.check.projected });
+      }
+    }
 
     this._checkRate(role, tool);
     const result = await execute();
-    return { result, decision };
+
+    if (runId) {
+      const actor = this._resolveActor(role, requestedBy);
+      this._consumptionBudgets.record(actor, runId, 'toolCalls', 1);
+      if (tokenEstimate > 0) this._consumptionBudgets.record(actor, runId, 'tokens', tokenEstimate);
+    }
+
+    return { result, decision, correlationId };
   }
 }
 
-export function isBrokered(env = process.env) {
+export { BudgetExceeded };
+
+export function isBrokered(env = process.env, { cwd } = {}) {
   const override = env?.CONSTRUCT_MCP_BROKER;
   if (override === 'on') return true;
   if (override === 'off') return false;
-  const mode = env?.CONSTRUCT_DEPLOYMENT_MODE || 'solo';
+
+  // Same env > config > default precedence as getDeploymentMode: 'auto' (or an
+  // absent key) falls through to the deployment-mode default below.
+
+  try {
+    const { config } = loadProjectConfig(cwd, env);
+    const fromConfig = config?.deployment?.mcpBroker;
+    if (fromConfig === 'on') return true;
+    if (fromConfig === 'off') return false;
+  } catch { /* loader is best-effort — fall through to deployment-mode default */ }
+
+  const mode = getDeploymentMode(env, { cwd });
   return mode === 'team' || mode === 'enterprise';
 }

package/lib/mcp/denied-store.mjs

@@ -0,0 +1,95 @@
+/**
+ * lib/mcp/denied-store.mjs — durable store for denied policy decisions.
+ *
+ * LMCP-I3: a PolicyDenied throw is a transient exception unless the decision
+ * that produced it is also written somewhere a reviewer can re-open later.
+ * DeniedStore appends one JSONL line per denied decision to
+ * `<rootDir>/.cx/denied-decisions.jsonl` — append-only, never rewritten, so a
+ * repeated-denial pattern for one actor+tool is visible as a policy-tuning
+ * signal without replaying the audit-trail chain. Every record uses the same
+ * schema as the audit-trail entry for the same decision — {decisionId, actor,
+ * tenant, project, tool, target, risk, outcome, correlationId, ts} — so the
+ * two stores can be cross-referenced by decisionId. Disk I/O is best-effort:
+ * a write failure never breaks the broker call it originated from.
+ *
+ * readAllForTenant (LMCP-H5) composes readAll with
+ * lib/tenant/isolation.mjs#readTenantScoped so any caller reading denied
+ * decisions for a specific tenant gets a fail-closed, tenant-scoped view —
+ * a record from another tenant is excluded, and an unresolved tenantId
+ * throws rather than silently returning the unfiltered store.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readTenantScoped } from '../tenant/isolation.mjs';
+
+const DENIED_STORE_SUBPATH = path.join('.cx', 'denied-decisions.jsonl');
+
+export function deniedStorePath(rootDir) {
+  return path.join(rootDir, DENIED_STORE_SUBPATH);
+}
+
+export class DeniedStore {
+  constructor({ rootDir, file } = {}) {
+    if (!rootDir && !file) throw new Error('DeniedStore: rootDir or file is required');
+    this.file = file || deniedStorePath(rootDir);
+  }
+
+  /**
+   * Append a denied-decision record. Returns the record on success, or null
+   * if the write failed (disk full, permissions) — best-effort, never throws.
+   *
+   * @param {object} record - {decisionId, actor, tenant, project, tool, target, risk, outcome, correlationId, ts}
+   */
+  append(record) {
+    try {
+      fs.mkdirSync(path.dirname(this.file), { recursive: true });
+      fs.appendFileSync(this.file, `${JSON.stringify(record)}\n`, 'utf8');
+      return record;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Read all durable denied records. Returns [] if the store is absent or
+   * unreadable rather than throwing — a missing store means zero denials so
+   * far, not a hard error.
+   */
+  readAll() {
+    try {
+      const raw = fs.readFileSync(this.file, 'utf8');
+      return raw
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => {
+          try { return JSON.parse(line); } catch { return null; }
+        })
+        .filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  /** Find denied records matching decisionId. Linear scan — store is low-volume by design. */
+  findByDecisionId(decisionId) {
+    return this.readAll().filter((r) => r.decisionId === decisionId);
+  }
+
+  /** Find denied records matching correlationId, tying a denial back to its originating call. */
+  findByCorrelationId(correlationId) {
+    return this.readAll().filter((r) => r.correlationId === correlationId);
+  }
+
+  /**
+   * Tenant-scoped read: same records as readAll(), filtered to exactly the
+   * given tenantId. Fail-closed — throws TenantIsolationViolation rather
+   * than returning the unfiltered store when tenantId is missing/blank.
+   *
+   * @param {string} tenantId
+   */
+  readAllForTenant(tenantId) {
+    return readTenantScoped(() => this.readAll(), tenantId);
+  }
+}

package/lib/mcp/destructive-gate.mjs

@@ -0,0 +1,30 @@
+/**
+ * lib/mcp/destructive-gate.mjs — unified gate for destructive-class MCP tools.
+ *
+ * Replaces per-tool confirm:true booleans: a tool classified destructive in
+ * TOOL_SAFETY requires a valid out-of-band approval token (consumeApprovalToken)
+ * before the broker will dispatch it. Single choke point for all destructive tools.
+ */
+
+import { TOOL_SAFETY } from './tool-safety.mjs';
+import { consumeApprovalToken } from './destructive-approval.mjs';
+
+const DESTRUCTIVE_CLASS = 'destructive';
+
+export function checkDestructiveGate(toolName, toolArgs, opts = {}) {
+  const safety = TOOL_SAFETY[toolName];
+  if (!safety || safety.class !== DESTRUCTIVE_CLASS) {
+    return { gated: false, allowed: true };
+  }
+
+  const token = toolArgs?.approval_token;
+  if (!consumeApprovalToken(toolName, token)) {
+    return {
+      gated: true,
+      allowed: false,
+      reason: `${toolName} requires a valid out-of-band approval token (destructive tool; confirm=true alone is not authorization). Use 'construct tokens issue ${toolName}' or set approval_token.`,
+    };
+  }
+
+  return { gated: true, allowed: true };
+}