[MCP-03] Add explicit, auditable, policy-gated state-changing tools

[jaavid]

Background

CoreLink is one product across multiple implementation repositories. This work is owned by mcp-server under EPIC-02.

Goal

Add explicit, auditable, policy-gated state-changing MCP tools only after the read-only/security boundary is accepted and a named Post-Beta use case justifies the capability.

Parent

• Primary Product Epic: EPIC-02
• Backlog ID: MCP-03

Scope

• Implement explicitly approved state-changing tools inside mcp-server.
• Require least-privilege authorization, explicit consent/confirmation, idempotency where applicable, audit events and safe retry/recovery behavior.
• Map every tool to version-identifiable public API/contracts; do not bypass public authorization/tenancy boundaries through internal runtime access.
• Validate supported behavior against the accepted mock/conformance path and retain Post-Beta evidence.

Out of Scope

• Read-only tooling already covered by MCP-02.
• Making state-changing MCP tools a prerequisite for the read-only MCP-04 RC package unless Product Council explicitly adds them to RC scope.
• Generic state-changing tools without a named customer/pilot use case and accepted security boundary.
• Treating successful implementation or packaging as Product Acceptance.

Acceptance Criteria

• Every state-changing tool has a named customer/pilot use case and explicit product-scope decision.
• MCP-01 security/tenant/consent/audit boundary is accepted for the operation class.
• MCP-02 read-only surface remains non-mutating and regression-safe.
• Authorization and cross-tenant/insufficient-scope paths fail closed.
• Explicit consent/confirmation semantics are demonstrated for sensitive operations.
• Idempotency, duplicate/retry, timeout and recovery behavior are deterministic where relevant.
• Audit evidence identifies actor, tenant, tool/action, target, outcome and correlation data without leaking secrets.
• Supported behavior passes against MOCK-03 or an equivalent accepted conformance environment.
• Documentation and maturity claims identify the exact supported contract/tool revision.

Dependencies and acceptance state

• Security prerequisite: MCP-01 accepted threat/auth/consent/audit boundary.
• Surface prerequisite: MCP-02 accepted read-only tool surface, so mutation semantics remain isolated from read-only guarantees.
• Evidence/product-gate prerequisite: named customer or pilot evidence plus explicit Product Council inclusion for the proposed state-changing operations.
• Conformance input: MOCK-03 or equivalent accepted sandbox before supported claims.
• Blocks: Post-Beta state-changing MCP documentation/acceptance and, only if explicitly included in a future release gate, the corresponding package compatibility evidence.
• Current dependency state: See the CoreLink Product organization Project.

Planning Metadata

• Type: Feature
• Priority snapshot: P2
• Product milestone snapshot: Post-Beta
• Domain snapshots: security, devex
• Area snapshot: backend
• Complexity: L
• Created in status: Triage
• Current status and DRI: See the CoreLink Product organization Project.
• Intended repository labels: type:feature

Definition of Done

• Acceptance criteria demonstrated.
• Named-use-case and scope-decision evidence is retained.
• Security/tenancy/consent/audit review is accepted.
• Required conformance and recovery checks pass.
• Public contract compatibility and provenance are reconciled.
• Documentation and release notes accurately state Post-Beta maturity.
• Pull request(s), exact dependency revisions and retained evidence are linked.

[mahirhir]

Here is a clean, fail-closed architectural pattern for state-changing MCP tools enforcing tenant isolation, idempotency caching, and tamper-evident audit evidence:

1. State-Changing Tool Handler Wrapper (src/mcp/mutations/handler.ts)

import { createHash } from "node:crypto";

export interface MutationContext {
  tenantId: string;
  actorPrincipal: string;
  idempotencyKey?: string;
  confirmationToken?: string;
  toolName: string;
  targetEntityId: string;
  params: Record<string, unknown>;
}

export interface AuditEvidenceRecord {
  eventId: string;
  timestamp: string;
  tenantId: string;
  actor: string;
  tool: string;
  target: string;
  paramsDigestSha256: string;
  outcome: "SUCCESS" | "DENIED" | "FAILED" | "IDEMPOTENT_REPLAY";
  durationMs: number;
}

export class GovernedMutationGate {
  constructor(
    private tenantAuthorizer: (tenantId: string, actor: string, tool: string) => Promise<boolean>,
    private idempotencyStore: {
      get: (key: string) => Promise<any | null>;
      set: (key: string, result: any, ttlSec: number) => Promise<void>;
    },
    private auditEvidenceSink: (evidence: AuditEvidenceRecord) => Promise<void>
  ) {}

  async executeMutation<T>(
    ctx: MutationContext,
    operation: () => Promise<T>
  ): Promise<T> {
    const startTime = Date.now();
    const paramsDigest = createHash("sha256")
      .update(JSON.stringify(ctx.params, Object.keys(ctx.params).sort()))
      .digest("hex");

    // 1. Fail-closed Tenancy & Authorization Verification
    const isAuthorized = await this.tenantAuthorizer(ctx.tenantId, ctx.actorPrincipal, ctx.toolName);
    if (!isAuthorized) {
      await this.auditEvidenceSink({
        eventId: crypto.randomUUID(),
        timestamp: new Date().toISOString(),
        tenantId: ctx.tenantId,
        actor: ctx.actorPrincipal,
        tool: ctx.toolName,
        target: ctx.targetEntityId,
        paramsDigestSha256: paramsDigest,
        outcome: "DENIED",
        durationMs: Date.now() - startTime,
      });
      throw new Error(`Forbidden: Actor '${ctx.actorPrincipal}' not authorized for mutation on tenant '${ctx.tenantId}'`);
    }

    // 2. Deterministic Idempotency Key Handling
    const idempotencyKey = ctx.idempotencyKey 
      ? `idemp:${ctx.tenantId}:${ctx.toolName}:${ctx.idempotencyKey}`
      : null;

    if (idempotencyKey) {
      const cached = await this.idempotencyStore.get(idempotencyKey);
      if (cached !== null) {
        await this.auditEvidenceSink({
          eventId: crypto.randomUUID(),
          timestamp: new Date().toISOString(),
          tenantId: ctx.tenantId,
          actor: ctx.actorPrincipal,
          tool: ctx.toolName,
          target: ctx.targetEntityId,
          paramsDigestSha256: paramsDigest,
          outcome: "IDEMPOTENT_REPLAY",
          durationMs: Date.now() - startTime,
        });
        return cached as T;
      }
    }

    // 3. Execute State-Changing Logic
    try {
      const result = await operation();

      if (idempotencyKey) {
        await this.idempotencyStore.set(idempotencyKey, result, 86400); // 24h TTL
      }

      await this.auditEvidenceSink({
        eventId: crypto.randomUUID(),
        timestamp: new Date().toISOString(),
        tenantId: ctx.tenantId,
        actor: ctx.actorPrincipal,
        tool: ctx.toolName,
        target: ctx.targetEntityId,
        paramsDigestSha256: paramsDigest,
        outcome: "SUCCESS",
        durationMs: Date.now() - startTime,
      });

      return result;
    } catch (err: any) {
      await this.auditEvidenceSink({
        eventId: crypto.randomUUID(),
        timestamp: new Date().toISOString(),
        tenantId: ctx.tenantId,
        actor: ctx.actorPrincipal,
        tool: ctx.toolName,
        target: ctx.targetEntityId,
        paramsDigestSha256: paramsDigest,
        outcome: "FAILED",
        durationMs: Date.now() - startTime,
      });
      throw err;
    }
  }
}

This ensures full tenant isolation, prevents duplicate state mutation via deterministic idempotency keys, and binds all mutations to cryptographic audit evidence.