@ossdeveloper/github-compliance 1.0.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossdeveloper/github-compliance",
-  "version": "1.0.1",
+  "version": "1.3.0",
   "description": "GitHub compliance plugin for OpenCode - enforces human approval for write operations",
   "main": "dist/plugin.js",
   "type": "module",

package/plugin.ts

@@ -8,23 +8,158 @@
 import type { Plugin } from "@opencode-ai/plugin";
 import { 
   initDatabase, 
-  getComplianceRecord, 
+  getComplianceRecord,
   validateCompliance,
   markRecordUsed,
   logAudit,
   logFailedAttempt,
-  type ComplianceRecord
+  type ComplianceRecord,
+  type ValidationResult
 } from "./database";
 import { 
-  isGitHubWriteTool, 
-  extractToolInfo,
+  isGitHubWriteTool,
   extractGitHubUrl,
   extractGitHubId,
-  type ToolInfo
+  normalizeToolName,
+  type ToolInfo 
 } from "./compliance";
-import { buildBlockedError } from "./errors";
+import { extractRecordFields, computeContentHash, type ComplianceRecordFields } from "./contracts";
+import { buildBlockedError, type BlockedError } from "./errors";
 import { tools } from "./tools";
-import { ERROR_REASONS } from "./schema";
+import { ERROR_REASONS, SCHEMA } from "./schema";
+
+/**
+ * Check if this is an MCP tool (has github_ prefix)
+ * MCP tools don't have args populated in tool.execute.before
+ */
+function isMcpTool(toolName: string): boolean {
+  return toolName.startsWith("github_");
+}
+
+/**
+ * Extract tool info from args, handling the case where args might be missing
+ * 
+ * For MCP tools in tool.execute.before, args are not available.
+ * For other tools, args should be in output.args.
+ */
+function extractToolInfoFromArgs(
+  toolName: string, 
+  args: Record<string, unknown> | null | undefined
+): ToolInfo {
+  const fields = extractRecordFields(toolName, args);
+  return {
+    toolName: fields.toolName,
+    owner: fields.owner,
+    repo: fields.repo,
+    title: fields.title,
+    body: fields.body,
+    contentHash: fields.contentHash
+  };
+}
+
+/**
+ * Attempt to extract args from various sources in the input/output
+ */
+function extractArgs(input: Record<string, unknown>, output: Record<string, unknown>): Record<string, unknown> | null {
+  // Try output.args first (works for non-MCP tools)
+  if (output.args && typeof output.args === 'object') {
+    return output.args as Record<string, unknown>;
+  }
+  
+  // Try input.arguments (sometimes populated)
+  if (input.arguments && typeof input.arguments === 'object') {
+    return input.arguments as Record<string, unknown>;
+  }
+  
+  // Try input.args
+  if (input.args && typeof input.args === 'object') {
+    return input.args as Record<string, unknown>;
+  }
+  
+  // For MCP tools, args might be stringified in a different field
+  if (typeof input.arguments === 'string') {
+    try {
+      return JSON.parse(input.arguments);
+    } catch {
+      // Not JSON
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Validate compliance for a GitHub write operation
+ */
+async function validateAndProcess(
+  toolName: string,
+  owner: string,
+  repo: string,
+  contentHash: string,
+  toolInfo: ToolInfo
+): Promise<{ allowed: boolean; record: ComplianceRecord | null; validation: ValidationResult }> {
+  // Look up compliance record by tool, repo, and content hash
+  const record = await getComplianceRecord(
+    toolName,
+    owner,
+    repo,
+    contentHash
+  );
+
+  // Validate the record (status, expiration, etc.)
+  const validation = await validateCompliance(record, {
+    toolName,
+    owner,
+    repo,
+    contentHash
+  });
+
+  if (!validation.valid) {
+    // Log rejected attempt for audit
+    await logFailedAttempt({
+      tool_name: toolName,
+      owner,
+      repo,
+      reason: validation.reason,
+      content_hash: contentHash,
+      provided_record_id: record?.id || null,
+      error_details: validation.message
+    });
+
+    return { allowed: false, record, validation };
+  }
+
+  // Record is valid - mark as used to prevent replay
+  await markRecordUsed(record.id);
+
+  return { allowed: true, record, validation };
+}
+
+/**
+ * Log successful execution
+ */
+async function logSuccess(
+  toolInfo: ToolInfo,
+  record: ComplianceRecord,
+  result: unknown
+): Promise<void> {
+  const githubUrl = extractGitHubUrl(result);
+  const githubId = extractGitHubId(result);
+
+  await logAudit({
+    compliance_record_id: record.id,
+    tool_name: toolInfo.toolName,
+    owner: toolInfo.owner,
+    repo: toolInfo.repo,
+    github_username: record.github_username,
+    status: "success",
+    error_message: null,
+    github_url: githubUrl,
+    github_id: githubId,
+    executed_at: new Date().toISOString(),
+    content_preview: toolInfo.body ? toolInfo.body.substring(0, 500) : null
+  });
+}
 
 export const GitHubCompliancePlugin: Plugin = async (_ctx) => {
   await initDatabase();
@@ -36,26 +171,33 @@ export const GitHubCompliancePlugin: Plugin = async (_ctx) => {
     /**
      * Pre-execution hook for tool calls
      * 
-     * Intercepts GitHub write tools and validates compliance:
-     * - Checks for existing compliance record in SQLite
-     * - Validates record status (approved, not expired, not used)
-     * - Blocks tool execution if validation fails
-     * - Marks record as 'used' if validation succeeds
+     * For non-MCP tools: Validates compliance and blocks if invalid
+     * For MCP tools: Cannot validate (args not available), lets call proceed
      */
     "tool.execute.before": async (input, output) => {
-      // Only intercept GitHub write tools - let everything else pass through
+      // Only intercept GitHub write tools
       if (!isGitHubWriteTool(input.tool)) {
         return;
       }
 
-      let toolInfo: ToolInfo;
-      let record: ComplianceRecord | null = null;
+      const isMcp = isMcpTool(input.tool);
 
-      // Extract tool-specific information for compliance lookup
+      // For MCP tools, we cannot get args in before hook - skip validation
+      // The after hook will handle validation for MCP tools
+      if (isMcp) {
+        // Store a marker that this MCP tool needs post-execution validation
+        (output as Record<string, unknown>).__needsMcpValidation = true;
+        (output as Record<string, unknown>).__mcpToolName = input.tool;
+        return;
+      }
+
+      // For non-MCP tools, validate as before
+      let toolInfo: ToolInfo;
+      
       try {
-        toolInfo = extractToolInfo(input.tool, input.args as Record<string, unknown>);
+        const args = extractArgs(input as Record<string, unknown>, output as Record<string, unknown>);
+        toolInfo = extractToolInfoFromArgs(input.tool, args);
       } catch (error) {
-        // Log extraction failures for debugging
         await logFailedAttempt({
           tool_name: input.tool,
           owner: "unknown",
@@ -73,54 +215,34 @@ export const GitHubCompliancePlugin: Plugin = async (_ctx) => {
       }
 
       try {
-        // Look up compliance record by tool, repo, and content hash
-        record = await getComplianceRecord(
+        const { allowed, record, validation } = await validateAndProcess(
           toolInfo.toolName,
           toolInfo.owner,
           toolInfo.repo,
-          toolInfo.contentHash
+          toolInfo.contentHash,
+          toolInfo
         );
 
-        // Validate the record (status, expiration, etc.)
-        const validation = await validateCompliance(record, toolInfo);
-
-        if (!validation.valid) {
-          // Log rejected attempt for audit
-          await logFailedAttempt({
-            tool_name: toolInfo.toolName,
-            owner: toolInfo.owner,
-            repo: toolInfo.repo,
-            reason: validation.reason,
-            content_hash: toolInfo.contentHash,
-            provided_record_id: record?.id || null,
-            error_details: validation.message
-          });
-
-          // Block the tool execution with detailed error message
+        if (!allowed) {
           throw new Error(buildBlockedError(validation));
         }
 
-        // Record is valid - mark as used to prevent replay
-        await markRecordUsed(record.id);
-
         // Attach metadata for after hook
-        (output as Record<string, unknown>).__complianceRecordId = record.id;
+        (output as Record<string, unknown>).__complianceRecordId = record!.id;
         (output as Record<string, unknown>).__toolInfo = toolInfo;
 
       } catch (error) {
-        // Re-throw blocked errors as-is
         if (error instanceof Error && error.message.includes("[GITHUB COMPLIANCE BLOCKED]")) {
           throw error;
         }
 
-        // Unexpected errors - log and block
         await logFailedAttempt({
           tool_name: toolInfo.toolName,
           owner: toolInfo.owner,
-          repo: toolInfo.repo,
+          toolInfo: toolInfo.repo,
           reason: ERROR_REASONS.UNEXPECTED_ERROR,
           content_hash: toolInfo.contentHash,
-          provided_record_id: record?.id || null,
+          provided_record_id: null,
           error_details: error instanceof Error ? error.message : String(error)
         });
 
@@ -135,16 +257,82 @@ export const GitHubCompliancePlugin: Plugin = async (_ctx) => {
     /**
      * Post-execution hook for successful tool calls
      * 
-     * Logs successful GitHub write operations to audit trail.
-     * Only logs for GitHub write tools that were validated.
+     * For MCP tools: Performs compliance validation here (args available in input)
+     * For non-MCP tools: Logs successful execution
      */
     "tool.execute.after": async (input, output) => {
-      // Only process GitHub write tools we intercepted
+      // Only process GitHub write tools we might have skipped in before
       if (!isGitHubWriteTool(input.tool)) {
         return;
       }
 
-      // Skip if no compliance record was attached (shouldn't happen)
+      const isMcp = isMcpTool(input.tool);
+      const needsMcpValidation = (output as Record<string, unknown>).__needsMcpValidation === true;
+
+      // For MCP tools that weren't validated in before hook
+      if (isMcp && needsMcpValidation) {
+        let toolInfo: ToolInfo;
+        
+        try {
+          // Args ARE available in input for after hook
+          const args = input.args as Record<string, unknown> | null;
+          toolInfo = extractToolInfoFromArgs(input.tool, args || null);
+        } catch (error) {
+          // Log extraction failure but don't block - tool already executed
+          await logFailedAttempt({
+            tool_name: input.tool,
+            owner: "unknown",
+            repo: "unknown",
+            reason: ERROR_REASONS.EXTRACTION_ERROR,
+            content_hash: null,
+            error_details: `Failed to extract MCP tool info in after hook: ${error instanceof Error ? error.message : String(error)}`
+          });
+          return;
+        }
+
+        try {
+          const { allowed, record, validation } = await validateAndProcess(
+            toolInfo.toolName,
+            toolInfo.owner,
+            toolInfo.repo,
+            toolInfo.contentHash,
+            toolInfo
+          );
+
+          if (!allowed) {
+            // Tool already executed, log the violation
+            await logFailedAttempt({
+              tool_name: toolInfo.toolName,
+              owner: toolInfo.owner,
+              repo: toolInfo.repo,
+              reason: validation.reason,
+              content_hash: toolInfo.contentHash,
+              provided_record_id: record?.id || null,
+              error_details: "MCP tool executed without valid compliance record"
+            });
+            return;
+          }
+
+          // Valid - log success
+          if (record) {
+            await logSuccess(toolInfo, record, output.result);
+          }
+
+        } catch (error) {
+          await logFailedAttempt({
+            tool_name: toolInfo.toolName,
+            owner: toolInfo.owner,
+            repo: toolInfo.repo,
+            reason: ERROR_REASONS.UNEXPECTED_ERROR,
+            content_hash: toolInfo.contentHash,
+            provided_record_id: null,
+            error_details: error instanceof Error ? error.message : String(error)
+          });
+        }
+        return;
+      }
+
+      // For non-MCP tools - log successful execution
       const complianceRecordId = (output as Record<string, unknown>).__complianceRecordId as string | undefined;
       const toolInfo = (output as Record<string, unknown>).__toolInfo as ToolInfo | undefined;
 
@@ -152,26 +340,19 @@ export const GitHubCompliancePlugin: Plugin = async (_ctx) => {
         return;
       }
 
-      // Extract GitHub response data for audit
-      const githubUrl = extractGitHubUrl(output.result);
-      const githubId = extractGitHubId(output.result);
-
-      // Log successful execution
-      await logAudit({
-        compliance_record_id: complianceRecordId,
-        tool_name: toolInfo.toolName,
-        owner: toolInfo.owner,
-        repo: toolInfo.repo,
-        github_username: "unknown",
-        status: "success",
-        error_message: null,
-        github_url: githubUrl,
-        github_id: githubId,
-        executed_at: new Date().toISOString(),
-        content_preview: toolInfo.body ? toolInfo.body.substring(0, 500) : null
-      });
+      // Get the record from DB to log with proper username
+      const record = await getComplianceRecord(
+        toolInfo.toolName,
+        toolInfo.owner,
+        toolInfo.repo,
+        toolInfo.contentHash
+      );
+
+      if (record) {
+        await logSuccess(toolInfo, record, output.result);
+      }
     }
   };
 };
 
-export default GitHubCompliancePlugin;
+export default GitHubCompliancePlugin;

package/tools.ts

@@ -7,6 +7,7 @@
  */
 
 import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
 import type { Plugin } from "@opencode-ai/plugin";
 import { 
   createComplianceRecord, 
@@ -26,43 +27,54 @@ import {
  * 
  * The tool records that human approval was obtained and creates
  * a valid compliance record that will allow the GitHub write operation.
+ * 
+ * Note: body and title are base64 encoded to work around BunShell serialization
+ * issues with multiline strings. Caller should encode these values.
  */
 export const createComplianceRecordTool = tool({
-  description: "Create a compliance record AFTER user approves the draft. MUST be called after explicit user approval. This records that human approval was obtained and allows the GitHub write operation to proceed.",
+  description: "Create compliance record",
   args: {
-    tool_name: tool.schema.string({ description: "GitHub tool name (e.g., issue_write, pull_request_write)" }),
-    owner: tool.schema.string({ description: "Repository owner (user or org)" }),
-    repo: tool.schema.string({ description: "Repository name" }),
-    title: tool.schema.string().optional({ description: "Issue/PR title" }),
-    body: tool.schema.string({ description: "Issue/PR body content" }),
-    github_username: tool.schema.string({ description: "GitHub username of human approver" }),
-    approved_at: tool.schema.string({ description: "ISO8601 timestamp when user approved" }),
-    checks: tool.schema.array(tool.schema.object({
-      check_type: tool.schema.string({ description: "Type of check performed" }),
-      passed: tool.schema.boolean({ description: "Whether check passed" }),
-      details: tool.schema.record(tool.schema.string(), tool.schema.any()).optional({ description: "Additional details" })
-    })).optional({ description: "List of compliance checks performed" })
+    tool_name: z.string(),
+    owner: z.string(),
+    repo: z.string(),
+    title: z.string().optional(),
+    body: z.string(),
+    github_username: z.string(),
+    approved_at: z.string(),
+    checks: z.string().optional()
   },
   async execute(args, _context) {
+    let checks: CreateRecordInput['checks'] = [];
+    if (args.checks) {
+      try {
+        checks = JSON.parse(args.checks);
+      } catch {
+        checks = [];
+      }
+    }
+
+    const body = Buffer.from(args.body, 'base64').toString('utf-8');
+    const title = args.title ? Buffer.from(args.title, 'base64').toString('utf-8') : null;
+
     const input: CreateRecordInput = {
       tool_name: args.tool_name,
       owner: args.owner,
       repo: args.repo,
-      title: args.title || null,
-      body: args.body,
+      title,
+      body,
       github_username: args.github_username,
       approved_at: args.approved_at,
-      checks: args.checks || []
+      checks
     };
 
     const recordId = await createComplianceRecord(input);
 
-    return {
+    return JSON.stringify({
       success: true,
       record_id: recordId,
-      message: "Compliance record created. You may now execute the GitHub write operation.",
+      message: "Compliance record created",
       expires_at: new Date(Date.now() + 30 * 60 * 1000).toISOString()
-    };
+    });
   }
 });
 
@@ -73,16 +85,16 @@ export const createComplianceRecordTool = tool({
  * before attempting a GitHub write operation.
  */
 export const getComplianceStatusTool = tool({
-  description: "Check if a valid compliance record exists for a planned GitHub write operation.",
+  description: "Check compliance status",
   args: {
-    tool_name: tool.schema.string({ description: "GitHub tool name" }),
-    owner: tool.schema.string({ description: "Repository owner" }),
-    repo: tool.schema.string({ description: "Repository name" }),
-    content_hash: tool.schema.string({ description: "SHA256 hash of the content (format: sha256:...)" })
+    tool_name: z.string(),
+    owner: z.string(),
+    repo: z.string(),
+    content_hash: z.string()
   },
   async execute(args, _context) {
     const status = await getComplianceStatus(args.tool_name, args.owner, args.repo, args.content_hash);
-    return status;
+    return JSON.stringify(status);
   }
 });