@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/embed/approval-queue.mjs

@@ -1,36 +1,35 @@
 /**
- * lib/embed/approval-queue.mjs — high-risk action approval queue.
+ * lib/embed/approval-queue.mjs — durable approval queue for MCP tool calls.
  *
- * Actions that match the approval.require list in embed config are held
- * here until approved, rejected, or timed out.
+ * Per ADR-0056 (LMCP-A6), every approval-required tool call creates a durable
+ * record with full identity, state machine, and file-backed persistence.
+ * Records survive process restart and can be resolved by any authorized actor
+ * with queue access.
  *
- * Persistence: in-memory by default; optionally writes to a JSONL file
- * at ~/.cx/approval-queue.jsonl for cross-session visibility.
+ * Persistence: JSONL file at `.cx/approvals/queue.jsonl` (team mode) or
+ * `~/.cx/approvals/queue.jsonl` (solo mode). Written on every state transition.
  */
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
 import { doctorRoot } from '../config/xdg.mjs';
 
+const APPROVAL_TTL_MS = 3_600_000; // 1 hour default
+
 export class ApprovalQueue {
-  #items = new Map();   // id → ApprovalItem
+  #items = new Map();
   #persistPath = null;
-  #requirePatterns = [];
-  #timeoutMs = 3_600_000;
-  #fallback = 'reject';
+  #timeoutMs = APPROVAL_TTL_MS;
 
   /**
    * @param {object} opts
-   * @param {string[]} opts.require        - Action type patterns that need approval
-   * @param {number}  [opts.timeoutMs]     - Auto-expiry after this many ms (default: 1h)
-   * @param {string}  [opts.fallback]      - 'reject' | 'proceed' on timeout
-   * @param {string}  [opts.persistPath]   - Path to JSONL persistence file
+   * @param {string}  [opts.persistPath]  - Path to JSONL persistence file
+   * @param {number}  [opts.timeoutMs]    - Auto-expiry after this many ms (default: 1h)
    */
-  constructor({ require: requirePatterns = [], timeoutMs, fallback, persistPath } = {}) {
-    this.#requirePatterns = requirePatterns;
+  constructor({ persistPath, timeoutMs } = {}) {
     if (timeoutMs != null) this.#timeoutMs = timeoutMs;
-    if (fallback) this.#fallback = fallback;
     if (persistPath) {
       this.#persistPath = persistPath;
       this.#loadFromDisk();
@@ -38,113 +37,186 @@ export class ApprovalQueue {
   }
 
   /**
-   * Check if an action type requires approval.
+   * Compute a deterministic hash from tool name and args.
    */
-  requiresApproval(actionType) {
-    return this.#requirePatterns.some((p) => {
-      if (p.endsWith('*')) return actionType.startsWith(p.slice(0, -1));
-      return p === actionType;
-    });
+  static hashToolCall(tool, args) {
+    const stable = JSON.stringify(sortKeys({ tool, args: args ?? {} }));
+    return crypto.createHash('sha256').update(stable).digest('hex');
   }
 
   /**
-   * Determine approval mode for an action type.
-   * Returns 'auto' if autonomous execution is safe, 'human' if gating required.
+   * Enqueue a tool call for approval. Returns the full approval record.
    *
-   * Hybrid model rules (in priority order):
-   *   1. If requiresApproval() → 'human'
-   *   2. If action.autoApprove === true → 'auto'
-   *   3. If action type matches low-risk patterns → 'auto'
-   *   4. Default → 'human' (fail-safe)
-   */
-  approvalMode(actionType, { autoApprove = false } = {}) {
-    if (this.requiresApproval(actionType)) return 'human';
-    if (autoApprove) return 'auto';
-    const LOW_RISK = ['webhook.', 'snapshot.', 'observation.', 'search.', 'read.'];
-    if (LOW_RISK.some(prefix => actionType.startsWith(prefix))) return 'auto';
-    return 'human';
-  }
-
-  /**
-   * Enqueue an action for approval. Returns the item id.
-   * @param {object} action - { type, provider, payload, requestedBy?, autoApprove? }
+   * If an identical tool call (same tool + argsHash) already exists with
+   * status `awaiting_approval`, returns the existing record instead of
+   * creating a duplicate.
    *
-   * If approvalMode resolves to 'auto' the item is immediately auto-approved
-   * and persisted with status 'auto-approved'. Callers can check the returned
-   * item's status to decide whether to proceed immediately.
+   * @param {object} spec
+   * @param {string} spec.tool       - Tool name
+   * @param {object} spec.args       - Tool arguments
+   * @param {string} spec.surface    - Interaction surface (e.g. 'mcp', 'cli')
+   * @param {string} spec.argsHash   - Pre-computed hash (optional, computed if absent)
+   * @param {object} spec.requestedBy - Actor identity { userId, serviceId, tenantId, sessionId, role }
+   * @returns {object} Full approval record
    */
-  enqueue(action) {
-    const id = `appr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    const mode = this.approvalMode(action.type ?? action.action ?? 'unknown', {
-      autoApprove: action.autoApprove === true,
-    });
-    const item = {
-      id,
-      type: action.type ?? action.action ?? 'unknown',
-      provider: action.provider ?? null,
-      payload: action.payload ?? {},
-      requestedBy: action.requestedBy ?? 'construct',
-      approvalMode: mode,
-      status: mode === 'auto' ? 'auto-approved' : 'pending',
-      enqueuedAt: new Date().toISOString(),
-      resolvedAt: mode === 'auto' ? new Date().toISOString() : null,
-      expiresAt: new Date(Date.now() + this.#timeoutMs).toISOString(),
+  enqueue(spec) {
+    const { tool, args = {}, surface = 'mcp', requestedBy = {} } = spec;
+    const argsHash = spec.argsHash || ApprovalQueue.hashToolCall(tool, args);
+
+    const existing = this.#findByToolArgs(tool, argsHash);
+    if (existing && existing.state === 'awaiting_approval') {
+      return existing;
+    }
+
+    const approvalId = `appr-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    const resumeToken = crypto.randomBytes(32).toString('hex');
+    const now = new Date();
+
+    const record = {
+      approvalId,
+      toolCall: { tool, args, surface, argsHash },
+      requestedAt: now.toISOString(),
+      requestedBy: {
+        userId: requestedBy.userId ?? null,
+        serviceId: requestedBy.serviceId ?? null,
+        tenantId: requestedBy.tenantId ?? null,
+        sessionId: requestedBy.sessionId ?? null,
+        role: requestedBy.role ?? null,
+      },
+      state: 'awaiting_approval',
+      decidedAt: null,
+      decidedBy: null,
+      reason: null,
+      resumeToken,
+      expiresAt: new Date(now.getTime() + this.#timeoutMs).toISOString(),
     };
-    this.#items.set(id, item);
+
+    this.#items.set(approvalId, record);
     this.#persist();
-    return id;
+    return record;
   }
 
   /**
-   * Approve a pending item. Returns the resolved item.
+   * Approve a pending approval. Returns the resolved record.
+   * @param {string} approvalId
+   * @param {object} [opts]
+   * @param {object} [opts.decidedBy] - Actor identity of the decider
+   * @param {string} [opts.reason]
    */
-  approve(id, { approvedBy = 'human' } = {}) {
-    return this.#resolve(id, 'approved', { approvedBy });
+  approve(approvalId, { decidedBy = {}, reason = null } = {}) {
+    return this.#resolve(approvalId, 'approved', { decidedBy, reason });
   }
 
   /**
-   * Reject a pending item.
+   * Deny a pending approval. Returns the resolved record.
+   * @param {string} approvalId
+   * @param {object} [opts]
+   * @param {object} [opts.decidedBy] - Actor identity of the decider
+   * @param {string} [opts.reason]
    */
-  reject(id, { reason = '' } = {}) {
-    return this.#resolve(id, 'rejected', { reason });
+  deny(approvalId, { decidedBy = {}, reason = null } = {}) {
+    return this.#resolve(approvalId, 'denied', { decidedBy, reason });
   }
 
   /**
-   * Get an item by id.
+   * Get a record by approvalId.
    */
+  getById(approvalId) {
+    return this.#items.get(approvalId) ?? null;
+  }
+
+  /** @deprecated Use getById() — kept for backward compat with old tests. */
   get(id) {
-    return this.#items.get(id) ?? null;
+    if (typeof id === 'object' || id === null || id === undefined) return null;
+    return this.getById(id);
+  }
+
+  /** @deprecated Kept for backward compat; always returns false (policy decides). */
+  requiresApproval() {
+    return false;
+  }
+
+  /** @deprecated Use deny() — kept for backward compat with old tests. */
+  reject(id, opts = {}) {
+    const reason = opts?.reason ?? null;
+    return this.deny(id, { decidedBy: opts?.decidedBy ?? {}, reason });
   }
 
   /**
-   * List all items, optionally filtered by status.
+   * Get all records with state `awaiting_approval`.
    */
-  list(status = null) {
-    const items = [...this.#items.values()];
-    return status ? items.filter((i) => i.status === status) : items;
+  getPending() {
+    const results = [];
+    for (const item of this.#items.values()) {
+      if (item.state === 'awaiting_approval') results.push(item);
+    }
+    return results;
   }
 
   /**
-   * Expire any pending items past their expiry time.
-   * Returns the list of expired items.
+   * Look up a record by resumeToken.
+   */
+  getByResumeToken(resumeToken) {
+    for (const item of this.#items.values()) {
+      if (item.resumeToken === resumeToken) return item;
+    }
+    return null;
+  }
+
+  /**
+   * Find a record by tool + argsHash (for dedup).
+   */
+  #findByToolArgs(tool, argsHash) {
+    for (const item of this.#items.values()) {
+      if (item.toolCall?.tool === tool && item.toolCall?.argsHash === argsHash) {
+        return item;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Find a record by tool + argsHash (public, for broker lookup).
+   */
+  findByToolArgs(tool, argsHash) {
+    return this.#findByToolArgs(tool, argsHash);
+  }
+
+  /**
+   * Expire any awaiting_approval records past their expiry time.
+   * Returns the list of expired records.
    */
   expireStale() {
     const now = Date.now();
     const expired = [];
     for (const item of this.#items.values()) {
-      if (item.status === 'pending' && new Date(item.expiresAt).getTime() < now) {
-        this.#resolve(item.id, this.#fallback === 'proceed' ? 'approved' : 'expired');
+      if (item.state === 'awaiting_approval' && new Date(item.expiresAt).getTime() < now) {
+        this.#resolve(item.approvalId, 'expired', { reason: 'auto-expired' });
         expired.push(item);
       }
     }
     return expired;
   }
 
-  #resolve(id, status, extra = {}) {
-    const item = this.#items.get(id);
-    if (!item) throw new Error(`Approval item not found: ${id}`);
-    if (item.status !== 'pending') throw new Error(`Item ${id} is already ${item.status}`);
-    Object.assign(item, { status, resolvedAt: new Date().toISOString(), ...extra });
+  /**
+   * List all records, optionally filtered by state.
+   */
+  list(state = null) {
+    const items = [...this.#items.values()];
+    return state ? items.filter((i) => i.state === state) : items;
+  }
+
+  #resolve(approvalId, newState, extra = {}) {
+    const item = this.#items.get(approvalId);
+    if (!item) throw new Error(`Approval record not found: ${approvalId}`);
+    if (item.state !== 'awaiting_approval') {
+      throw new Error(`Approval ${approvalId} is already ${item.state}`);
+    }
+    const now = new Date();
+    item.state = newState;
+    item.decidedAt = now.toISOString();
+    if (extra.decidedBy) item.decidedBy = extra.decidedBy;
+    if (extra.reason) item.reason = extra.reason;
     this.#persist();
     return item;
   }
@@ -155,7 +227,9 @@ export class ApprovalQueue {
       fs.mkdirSync(path.dirname(this.#persistPath), { recursive: true });
       const lines = [...this.#items.values()].map((i) => JSON.stringify(i)).join('\n');
       fs.writeFileSync(this.#persistPath, lines + '\n', 'utf8');
-    } catch (err) { process.stderr.write('[approval-queue.mjs] persist: ' + (err?.message ?? String(err)) + '\n'); }
+    } catch (err) {
+      process.stderr.write('[approval-queue.mjs] persist: ' + (err?.message ?? String(err)) + '\n');
+    }
   }
 
   #loadFromDisk() {
@@ -165,13 +239,35 @@ export class ApprovalQueue {
       for (const line of lines) {
         try {
           const item = JSON.parse(line);
-          this.#items.set(item.id, item);
+          this.#items.set(item.approvalId || item.id, item);
         } catch { /* skip malformed */ }
       }
-    } catch (err) { process.stderr.write('[approval-queue.mjs] load-from-disk: ' + (err?.message ?? String(err)) + '\n'); }
+    } catch (err) {
+      process.stderr.write('[approval-queue.mjs] load-from-disk: ' + (err?.message ?? String(err)) + '\n');
+    }
   }
 
-  static defaultPersistPath() {
-    return path.join(doctorRoot(), 'approval-queue.jsonl');
+  /**
+   * Compute the default persistence path.
+   * In team mode: `.cx/approvals/queue.jsonl` under the project root.
+   * In solo mode: `~/.cx/approvals/queue.jsonl` (via doctorRoot).
+   */
+  static resolvePersistPath(rootDir, deploymentMode) {
+    if (deploymentMode === 'team' || deploymentMode === 'enterprise') {
+      return path.join(rootDir, '.cx', 'approvals', 'queue.jsonl');
+    }
+    return path.join(doctorRoot(), 'approvals', 'queue.jsonl');
   }
 }
+
+/**
+ * Recursively sort the keys of an object for deterministic JSON serialization.
+ */
+function sortKeys(obj) {
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return obj;
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = sortKeys(obj[key]);
+  }
+  return sorted;
+}

package/lib/embed/authority-guard.mjs

@@ -20,6 +20,18 @@
  *   const result = await guard.check('externalPost', { description: 'Post roadmap to Slack' });
  *   if (result.allowed) { ... execute ... }
  *   else { ... it's been queued or denied ... }
+ *
+ * Per-specialist binding enforcement (LMCP-E4): the operating-profile
+ * authority level answers "is this action *class* ever permitted" but has no
+ * per-specialist dimension — nothing stopped an embedded specialist from
+ * reading any provider or proposing any external write. When the caller
+ * passes `meta.proposal = { specialistId, providerId, writeKind }`, `check()`
+ * consults the specialist's `embedBindings` grant (lib/packs/manifest-schema.mjs)
+ * *before* the authority-level/queue logic runs: a `<providerId>.<writeKind>`
+ * token not present in that specialist's `proposals[]` is denied outright,
+ * never queued. Callers that omit `meta.proposal` are unaffected — this is
+ * additive, backward-compatible enforcement layered in front of the existing
+ * authority-level check.
  */
 
 // ─── Action-type → authority-key mapping ────────────────────────────────────
@@ -67,24 +79,75 @@ function resolveAuthorityKey(actionType) {
 export class AuthorityGuard {
   #authority;
   #approvalQueue;
+  #embedBindings;
 
   /**
    * @param {object} operatingProfile  - The embed config's operatingProfile object
    * @param {ApprovalQueue} approvalQueue
+   * @param {object} [embedBindings]   - Map of specialistId → { providers[], proposals[] }
+   *                                     (lib/packs/manifest-schema.mjs embedBindings shape).
+   *                                     Consulted only when a check's meta.proposal names
+   *                                     a specialistId; omit for non-embed callers.
    */
-  constructor(operatingProfile, approvalQueue) {
+  constructor(operatingProfile, approvalQueue, embedBindings = {}) {
     this.#authority = operatingProfile?.authority ?? {};
     this.#approvalQueue = approvalQueue;
+    this.#embedBindings = embedBindings ?? {};
+  }
+
+  /**
+   * Check a proposed embed action against the specialist's binding grant.
+   * Returns `null` when no binding-scoped check applies (no proposal meta,
+   * or no bindings configured) so the caller falls through to the ordinary
+   * authority-level check unaffected.
+   *
+   * @param {{specialistId: string, providerId: string, writeKind: string}} proposal
+   * @returns {{ allowed: boolean, mode: string, reason: string }|null}
+   */
+  #checkProposalBinding(proposal) {
+    if (!proposal || !proposal.specialistId) return null;
+
+    const { specialistId, providerId, writeKind } = proposal;
+    const binding = this.#embedBindings[specialistId];
+
+    if (!binding) {
+      return {
+        allowed: false,
+        mode: 'denied',
+        reason: `specialist "${specialistId}" has no embedBindings grant — no providers or proposals are authorized`,
+      };
+    }
+
+    const token = writeKind ? `${providerId}.${writeKind}` : providerId;
+    const grantedProposals = new Set(binding.proposals || []);
+
+    if (!grantedProposals.has(token)) {
+      return {
+        allowed: false,
+        mode: 'denied',
+        reason: `specialist "${specialistId}" is not granted to propose "${token}" (embedBindings.proposals: ${[...grantedProposals].join(', ') || '(none)'})`,
+      };
+    }
+
+    return null;
   }
 
   /**
    * Check whether an action is allowed under the current authority profile.
    *
    * @param {string} actionType   - e.g. 'externalPost', 'artifact:prd', 'issue:create'
-   * @param {object} [meta]       - Optional metadata: { description, payload }
+   * @param {object} [meta]       - Optional metadata: { description, payload, proposal }
+   * @param {{specialistId: string, providerId: string, writeKind: string}} [meta.proposal]
+   *        Embed-originated proposal descriptor (LMCP-E4). When present, the
+   *        proposal is checked against the specialist's embedBindings grant
+   *        before any authority-level/queue logic runs; a proposal outside
+   *        the grant is denied and never queued.
    * @returns {{ allowed: boolean, mode: string, queueId?: string, reason?: string }}
    */
   async check(actionType, meta = {}) {
+    const bindingDenial = this.#checkProposalBinding(meta.proposal);
+    if (bindingDenial) return bindingDenial;
+
     const key = resolveAuthorityKey(actionType);
     const level = this.#authority[key] ?? 'approval-queued'; // fail-safe default