@auctra/mcp-gateway 0.1.3 → 0.1.5

package/README.md

@@ -1,10 +1,15 @@
 # @auctra/mcp-gateway
 
-Stage 0 MCP gateway adapter. Wrap MCP tool calls with Auctra **Authority Gate** (`action.execute`) before execution.
+Stage 0 MCP gateway adapter. Wrap MCP tool calls **and installs** with Auctra **Authority Gate** (`action.execute`) before execution.
 
 ```ts
 import { Auctra } from "@auctra/sdk";
-import { gateMcpToolCall, withAuctraGate } from "@auctra/mcp-gateway";
+import {
+  gateMcpToolCall,
+  gateMcpInstall,
+  withAuctraGate,
+  declareMcpInstallMetadata,
+} from "@auctra/mcp-gateway";
 
 const client = new Auctra({ apiKey: process.env.AUCTRA_API_KEY! });
 
@@ -25,6 +30,56 @@ const sendEmail = withAuctraGate({
 
 Blocked or approval-required tool calls throw `McpToolBlockedError` with the decision evidence hash when present.
 
+## NL→SQL data scope (`gateMcpSqlQuery`)
+
+Declare requested vs authorized query scope so the production gate can emit `SQL_SCOPE_EXCEEDED`:
+
+```ts
+import { gateMcpSqlQuery } from "@auctra/mcp-gateway";
+
+await gateMcpSqlQuery({
+  client,
+  agentId: "agent-uuid",
+  toolName: "customer_query",
+  requestedScope: "customers.*",
+  authorizedScope: "customers.aggregate_metrics",
+  claimedIntentId: intent.id,
+  intentAnchorToken: intent.anchor_token,
+});
+```
+
+## Engine 15 — MCP / skill install attestation
+
+High-impact installs require `mcp_install` + HMAC `supply_chain_attestation` on the gate.
+Use the **same secret** as Auctra `SUPPLY_CHAIN_ATTESTATION_SECRET` (falls back to `TOOL_ATTESTATION_SECRET`).
+
+```ts
+await gateMcpInstall({
+  client,
+  agentId: "agent-uuid",
+  organizationId: "org-uuid",
+  secret: process.env.SUPPLY_CHAIN_ATTESTATION_SECRET!,
+  install: { name: "trusted-mcp", version: "1.2.0", kind: "mcp" },
+  manifestBody: { tools: ["send_email"] }, // hashed when contentHash omitted
+  claimedIntentId: intent.id,
+  intentAnchorToken: intent.anchor_token,
+});
+
+// Or attach metadata yourself on any action.execute:
+const metadata = declareMcpInstallMetadata({
+  organizationId: "org-uuid",
+  secret: process.env.SUPPLY_CHAIN_ATTESTATION_SECRET!,
+  install: { name: "trusted-mcp", kind: "mcp" },
+  manifestBody: packageJson,
+});
+```
+
+Also exported: `hashMcpPackageManifest`, `signSupplyChainAttestation`.
+
+## Engine 03 — tool response attestation
+
+`withAuctraGate({ attestation: { organizationId, secret } })` HMAC-signs the tool body as `tool_attestation` for the next consequential `action.execute`.
+
 ## Stdio MCP server
 
 Run the package as a real MCP stdio server:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@auctra/mcp-gateway",
-  "version": "0.1.3",
-  "description": "Stage 0 MCP gateway adapter — gate MCP tool calls through Auctra action.execute",
+  "version": "0.1.5",
+  "description": "MCP gateway — gate tool calls and MCP/skill installs through Auctra action.execute",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.ts",

package/src/index.js

@@ -45,6 +45,97 @@ export function signToolResponseAttestation(input) {
   };
 }
 
+/** Stable sha256 of an MCP/skill package manifest (Engine 15). */
+export function hashMcpPackageManifest(manifest) {
+  const payload = typeof manifest === "string" ? manifest : JSON.stringify(manifest ?? null);
+  return `sha256:${createHash("sha256").update(payload).digest("hex")}`;
+}
+
+function installAttestationKey(organizationId, secret) {
+  return `${secret}:install:${organizationId}`;
+}
+
+/**
+ * HMAC-sign an MCP/skill install (Engine 15).
+ * Must match Auctra gate signSupplyChainAttestation / evaluateAgentSupplyChain.
+ */
+export function signSupplyChainAttestation(input) {
+  const issuedAt = input.issuedAt ?? new Date().toISOString();
+  const contentHash = input.contentHash.trim();
+  const packageName = input.packageName.trim();
+  const signature = createHmac("sha256", installAttestationKey(input.organizationId, input.secret))
+    .update(`${packageName}\n${contentHash}\n${issuedAt}`)
+    .digest("hex");
+  return {
+    content_hash: contentHash,
+    package_name: packageName,
+    issued_at: issuedAt,
+    signature,
+    alg: "hmac-sha256",
+    key_id: input.keyId ?? "org-default",
+  };
+}
+
+/** Metadata bag for action.execute — Engine 15 mcp_install + supply_chain_attestation. */
+export function declareMcpInstallMetadata(input) {
+  const name = input.install.name.trim();
+  const contentHash =
+    input.install.contentHash?.trim() ||
+    hashMcpPackageManifest(input.manifestBody ?? { name, version: input.install.version ?? null });
+  const kind = input.install.kind ?? "mcp";
+  return {
+    mcp_install: {
+      name,
+      ...(input.install.version ? { version: input.install.version } : {}),
+      content_hash: contentHash,
+      kind,
+    },
+    supply_chain_attestation: signSupplyChainAttestation({
+      organizationId: input.organizationId,
+      packageName: name,
+      contentHash,
+      secret: input.secret,
+      issuedAt: input.issuedAt,
+      keyId: input.keyId,
+    }),
+  };
+}
+
+/** Gate an MCP/skill install through action.execute with Engine 15 attestation. */
+export async function gateMcpInstall(input) {
+  const metadata = declareMcpInstallMetadata({
+    organizationId: input.organizationId,
+    secret: input.secret,
+    install: input.install,
+    manifestBody: input.manifestBody,
+  });
+  const result = await input.client.action.execute({
+    agentId: input.agentId,
+    actionType: input.actionType ?? "execute_tool",
+    claimedIntentId: input.claimedIntentId,
+    intentAnchorToken: input.intentAnchorToken,
+    payload: {
+      tool: "mcp_install",
+      package: input.install.name,
+      version: input.install.version ?? null,
+    },
+    action: {
+      target: `mcp-install:${input.install.name}`,
+      description: `Install MCP/skill package ${input.install.name}`,
+      riskLevel: input.riskLevel ?? "high",
+      metadata,
+    },
+  });
+
+  if (result.decision !== "allowed") {
+    const evidenceId = evidenceIdFromResult(result);
+    const message = evidenceId ? `${result.reason} (evidence: ${evidenceId})` : result.reason;
+    throw new McpToolBlockedError(message, result.decision, result.evidence);
+  }
+
+  return { ...result, metadata };
+}
+
 /** Provenance for a tool/MCP result — attach on the next consequential action.execute. */
 export function declareToolResponseInput(input) {
   return {

package/src/index.ts

@@ -53,6 +53,22 @@ export type ToolAttestation = {
   key_id?: string;
 };
 
+export type SupplyChainAttestation = {
+  content_hash: string;
+  package_name: string;
+  issued_at: string;
+  signature: string;
+  alg: "hmac-sha256";
+  key_id?: string;
+};
+
+export type McpInstallManifest = {
+  name: string;
+  version?: string;
+  contentHash?: string;
+  kind?: "mcp" | "skill" | "tool_schema" | "model";
+};
+
 export class McpToolBlockedError extends Error {
   readonly decision: "blocked" | "require_approval";
   readonly evidence?: Awaited<ReturnType<ExecuteActionClient["action"]["execute"]>>["evidence"];
@@ -115,6 +131,136 @@ export function signToolResponseAttestation(input: {
   };
 }
 
+/** Stable sha256 of an MCP/skill package manifest (Engine 15). */
+export function hashMcpPackageManifest(manifest: unknown): string {
+  const payload = typeof manifest === "string" ? manifest : JSON.stringify(manifest ?? null);
+  return `sha256:${createHash("sha256").update(payload).digest("hex")}`;
+}
+
+function installAttestationKey(organizationId: string, secret: string) {
+  // Must match Auctra `installSecret` in supply-chain.server.ts
+  return `${secret}:install:${organizationId}`;
+}
+
+/**
+ * HMAC-sign an MCP/skill install (Engine 15).
+ * Must match Auctra gate `signSupplyChainAttestation` / `evaluateAgentSupplyChain`.
+ * Use the same secret as `SUPPLY_CHAIN_ATTESTATION_SECRET` (or `TOOL_ATTESTATION_SECRET`) on the gate.
+ */
+export function signSupplyChainAttestation(input: {
+  organizationId: string;
+  packageName: string;
+  contentHash: string;
+  secret: string;
+  issuedAt?: string;
+  keyId?: string;
+}): SupplyChainAttestation {
+  const issuedAt = input.issuedAt ?? new Date().toISOString();
+  const contentHash = input.contentHash.trim();
+  const packageName = input.packageName.trim();
+  const signature = createHmac("sha256", installAttestationKey(input.organizationId, input.secret))
+    .update(`${packageName}\n${contentHash}\n${issuedAt}`)
+    .digest("hex");
+  return {
+    content_hash: contentHash,
+    package_name: packageName,
+    issued_at: issuedAt,
+    signature,
+    alg: "hmac-sha256",
+    key_id: input.keyId ?? "org-default",
+  };
+}
+
+/** Metadata bag for action.execute — Engine 15 mcp_install + supply_chain_attestation. */
+export function declareMcpInstallMetadata(input: {
+  organizationId: string;
+  secret: string;
+  install: McpInstallManifest;
+  /** Raw manifest/schema used to derive content_hash when install.contentHash omitted. */
+  manifestBody?: unknown;
+  issuedAt?: string;
+  keyId?: string;
+}): {
+  mcp_install: {
+    name: string;
+    version?: string;
+    content_hash: string;
+    kind: "mcp" | "skill" | "tool_schema" | "model";
+  };
+  supply_chain_attestation: SupplyChainAttestation;
+} {
+  const name = input.install.name.trim();
+  const contentHash =
+    input.install.contentHash?.trim() ||
+    hashMcpPackageManifest(input.manifestBody ?? { name, version: input.install.version ?? null });
+  const kind = input.install.kind ?? "mcp";
+  return {
+    mcp_install: {
+      name,
+      ...(input.install.version ? { version: input.install.version } : {}),
+      content_hash: contentHash,
+      kind,
+    },
+    supply_chain_attestation: signSupplyChainAttestation({
+      organizationId: input.organizationId,
+      packageName: name,
+      contentHash,
+      secret: input.secret,
+      issuedAt: input.issuedAt,
+      keyId: input.keyId,
+    }),
+  };
+}
+
+/**
+ * Gate an MCP/skill install through action.execute with Engine 15 attestation attached.
+ * Prefer action types matching install/register (high+ requires attestation on the gate).
+ */
+export async function gateMcpInstall(input: {
+  client: ExecuteActionClient;
+  agentId: string;
+  organizationId: string;
+  secret: string;
+  install: McpInstallManifest;
+  manifestBody?: unknown;
+  actionType?: string;
+  claimedIntentId?: string;
+  intentAnchorToken?: string;
+  riskLevel?: string;
+}) {
+  const metadata = declareMcpInstallMetadata({
+    organizationId: input.organizationId,
+    secret: input.secret,
+    install: input.install,
+    manifestBody: input.manifestBody,
+  });
+  const result = await input.client.action.execute({
+    agentId: input.agentId,
+    actionType: input.actionType ?? "execute_tool",
+    claimedIntentId: input.claimedIntentId,
+    intentAnchorToken: input.intentAnchorToken,
+    payload: {
+      tool: "mcp_install",
+      package: input.install.name,
+      version: input.install.version ?? null,
+    },
+    action: {
+      target: `mcp-install:${input.install.name}`,
+      description: `Install MCP/skill package ${input.install.name}`,
+      riskLevel: input.riskLevel ?? "high",
+      metadata,
+    },
+  });
+
+  if (result.decision !== "allowed") {
+    const evidenceId = evidenceIdFromResult(result);
+    const message = evidenceId ? `${result.reason} (evidence: ${evidenceId})` : result.reason;
+    throw new McpToolBlockedError(message, result.decision, result.evidence);
+  }
+
+  return { ...result, metadata };
+}
+
 /**
  * Provenance for a tool/MCP result — attach on the *next* consequential
  * action.execute so Engine 03 treats the output as untrusted evidence.
@@ -203,3 +349,62 @@ export function withAuctraGate<TArgs extends Record<string, unknown>, TResult>(
     };
   };
 }
+
+/**
+ * Gate an NL→SQL / database tool call with declared data scope metadata.
+ * Production path: same action.execute gate companies use — requested ⊆ authorized.
+ */
+export async function gateMcpSqlQuery(input: {
+  client: ExecuteActionClient;
+  agentId: string;
+  toolName: string;
+  requestedScope: string | string[];
+  authorizedScope?: string | string[];
+  args?: Record<string, unknown>;
+  actionType?: string;
+  claimedIntentId?: string;
+  intentAnchorToken?: string;
+}) {
+  const result = await input.client.action.execute({
+    agentId: input.agentId,
+    actionType: input.actionType ?? "execute_sql",
+    claimedIntentId: input.claimedIntentId,
+    intentAnchorToken: input.intentAnchorToken,
+    payload: {
+      tool: input.toolName,
+      arguments: input.args ?? {},
+      resource: Array.isArray(input.requestedScope)
+        ? input.requestedScope[0]
+        : input.requestedScope,
+    },
+    action: {
+      target: `mcp-sql:${input.toolName}`,
+      description: `SQL/query tool ${input.toolName}`,
+      metadata: {
+        sql: {
+          requested_scope: input.requestedScope,
+          ...(input.authorizedScope != null
+            ? { authorized_scope: input.authorizedScope }
+            : {}),
+        },
+        inputs: [
+          {
+            source: `mcp:${input.toolName}:sql`,
+            source_type: "mcp_tool_response",
+            trust_level: "untrusted",
+            authority: "none",
+            claimed_influence: "privilege_escalation",
+          },
+        ],
+      },
+    },
+  });
+
+  if (result.decision !== "allowed") {
+    const evidenceId = evidenceIdFromResult(result);
+    const message = evidenceId ? `${result.reason} (evidence: ${evidenceId})` : result.reason;
+    throw new McpToolBlockedError(message, result.decision, result.evidence);
+  }
+
+  return result;
+}