@ossdeveloper/github-compliance 1.0.0

package/errors.ts

@@ -0,0 +1,149 @@
+/**
+ * Error message builder for compliance violations
+ * 
+ * Generates user-friendly error messages when compliance checks fail.
+ * These messages are shown to the LLM when a write operation is blocked.
+ */
+
+import { ERROR_REASONS } from "./schema";
+
+export interface ValidationResult {
+  valid: boolean;
+  reason: string;
+  message: string;
+}
+
+/**
+ * Build a detailed blocked error message for compliance violations
+ * 
+ * The error message includes:
+ * - The reason for blocking
+ * - Instructions on how to create a valid compliance record
+ * - Reference to the skill documentation
+ * 
+ * @param validation - Validation result with reason and message
+ * @returns Formatted error message string
+ */
+export function buildBlockedError(validation: ValidationResult): string {
+  const skillInstruction = `skill({ name: 'github-compliance' })`;
+
+  const baseError = `
+[GITHUB COMPLIANCE BLOCKED]
+
+Reason: ${validation.message}
+
+To proceed:
+1. Load the github-compliance skill:
+   ${skillInstruction}
+
+2. Follow the workflow to create a valid compliance record:
+   - Read CONTRIBUTING.md for the target repository
+   - Search for existing issues/PRs to avoid duplicates
+   - Draft your issue/PR content
+   - Present draft to user and wait for explicit approval
+   - Call create_compliance_record with approval details
+
+3. After compliance record is created, retry this operation.
+
+Skill location: ~/.config/opencode/skills/github-compliance/SKILL.md
+`;
+
+  if (validation.reason === ERROR_REASONS.NO_RECORD) {
+    return baseError;
+  }
+
+  if (validation.reason === ERROR_REASONS.NOT_APPROVED) {
+    return `
+[GITHUB COMPLIANCE BLOCKED]
+
+Reason: Compliance record exists but has not been approved by user.
+
+Your draft was created but not yet approved. Please:
+1. Present the draft to the user
+2. Wait for explicit approval ("yes", "proceed", etc.)
+3. Call create_compliance_record with approved status
+4. Retry this operation
+
+${baseError}
+`;
+  }
+
+  if (validation.reason === ERROR_REASONS.ALREADY_USED) {
+    return `
+[GITHUB COMPLIANCE BLOCKED]
+
+Reason: This compliance record has already been used.
+
+Each GitHub write operation requires its own compliance record.
+Please create a new compliance record for this operation.
+
+${baseError}
+`;
+  }
+
+  if (validation.reason === ERROR_REASONS.EXPIRED) {
+    return `
+[GITHUB COMPLIANCE BLOCKED]
+
+Reason: Your compliance record has expired (30 minute limit).
+
+Please create a new compliance record by:
+1. Loading the skill: ${skillInstruction}
+2. Presenting draft to user and getting approval again
+3. Creating a new compliance record
+4. Retrying this operation
+
+${baseError}
+`;
+  }
+
+  if (validation.reason === ERROR_REASONS.DATABASE_ERROR) {
+    return `
+[GITHUB COMPLIANCE BLOCKED]
+
+Reason: Compliance database error (${validation.message})
+
+Please try again. If the problem persists, restart your OpenCode session.
+
+${baseError}
+`;
+  }
+
+  return baseError;
+}
+
+/**
+ * Build a compliance JSON snippet for embedding in issue/PR body
+ * 
+ * This JSON is added to the end of issue/PR bodies to provide
+ * transparency about the compliance process that was followed.
+ * 
+ * @param clientIssueId - UUID from the compliance record
+ * @param githubUsername - GitHub username of approver
+ * @param approvedAt - ISO8601 timestamp of approval
+ * @param checksPerformed - List of check types performed
+ * @returns Formatted markdown string with JSON compliance record
+ */
+export function buildComplianceJson(
+  clientIssueId: string,
+  githubUsername: string,
+  approvedAt: string,
+  checksPerformed: string[]
+): string {
+  const compliance = {
+    mcp_compliance: {
+      version: "1.0",
+      client: {
+        name: "opencode",
+        client_issue_id: clientIssueId
+      },
+      human_approval: {
+        github_username: githubUsername,
+        approved_at: approvedAt
+      },
+      checks_performed: checksPerformed
+    }
+  };
+
+  return `\n\n---\n\n## MCP Compliance Record\n\n\`\`\`json\n${JSON.stringify(compliance, null, 2)}\n\`\`\`\n`;
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@ossdeveloper/github-compliance",
+  "version": "1.0.0",
+  "description": "GitHub compliance plugin for OpenCode - enforces human approval for write operations",
+  "main": "dist/plugin.js",
+  "type": "module",
+  "scripts": {
+    "build": "bun build plugin.ts --target=bun --outfile=dist/plugin.js"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.0.0"
+  }
+}

package/plugin.ts

@@ -0,0 +1,177 @@
+/**
+ * GitHub Compliance Plugin for OpenCode
+ * 
+ * Enforces mandatory human approval for GitHub write operations.
+ * Blocks write operations without valid compliance records in SQLite.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import { 
+  initDatabase, 
+  getComplianceRecord, 
+  validateCompliance,
+  markRecordUsed,
+  logAudit,
+  logFailedAttempt,
+  type ComplianceRecord
+} from "./database";
+import { 
+  isGitHubWriteTool, 
+  extractToolInfo,
+  extractGitHubUrl,
+  extractGitHubId,
+  type ToolInfo
+} from "./compliance";
+import { buildBlockedError } from "./errors";
+import { tools } from "./tools";
+import { ERROR_REASONS } from "./schema";
+
+export const GitHubCompliancePlugin: Plugin = async (_ctx) => {
+  await initDatabase();
+
+  return {
+    /** Custom tools exposed to the LLM */
+    tool: tools,
+
+    /**
+     * 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
+     */
+    "tool.execute.before": async (input, output) => {
+      // Only intercept GitHub write tools - let everything else pass through
+      if (!isGitHubWriteTool(input.tool)) {
+        return;
+      }
+
+      let toolInfo: ToolInfo;
+      let record: ComplianceRecord | null = null;
+
+      // Extract tool-specific information for compliance lookup
+      try {
+        toolInfo = extractToolInfo(input.tool, input.args as Record<string, unknown>);
+      } catch (error) {
+        // Log extraction failures for debugging
+        await logFailedAttempt({
+          tool_name: input.tool,
+          owner: "unknown",
+          repo: "unknown",
+          reason: ERROR_REASONS.EXTRACTION_ERROR,
+          content_hash: null,
+          error_details: `Failed to extract tool info: ${error instanceof Error ? error.message : String(error)}`
+        });
+
+        throw new Error(buildBlockedError({
+          valid: false,
+          reason: ERROR_REASONS.DATABASE_ERROR,
+          message: `Failed to parse tool arguments: ${error instanceof Error ? error.message : String(error)}`
+        }));
+      }
+
+      try {
+        // Look up compliance record by tool, repo, and content hash
+        record = await getComplianceRecord(
+          toolInfo.toolName,
+          toolInfo.owner,
+          toolInfo.repo,
+          toolInfo.contentHash
+        );
+
+        // 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
+          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>).__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,
+          reason: ERROR_REASONS.UNEXPECTED_ERROR,
+          content_hash: toolInfo.contentHash,
+          provided_record_id: record?.id || null,
+          error_details: error instanceof Error ? error.message : String(error)
+        });
+
+        throw new Error(buildBlockedError({
+          valid: false,
+          reason: ERROR_REASONS.DATABASE_ERROR,
+          message: error instanceof Error ? error.message : String(error)
+        }));
+      }
+    },
+
+    /**
+     * Post-execution hook for successful tool calls
+     * 
+     * Logs successful GitHub write operations to audit trail.
+     * Only logs for GitHub write tools that were validated.
+     */
+    "tool.execute.after": async (input, output) => {
+      // Only process GitHub write tools we intercepted
+      if (!isGitHubWriteTool(input.tool)) {
+        return;
+      }
+
+      // Skip if no compliance record was attached (shouldn't happen)
+      const complianceRecordId = (output as Record<string, unknown>).__complianceRecordId as string | undefined;
+      const toolInfo = (output as Record<string, unknown>).__toolInfo as ToolInfo | undefined;
+
+      if (!complianceRecordId || !toolInfo) {
+        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
+      });
+    }
+  };
+};
+
+export default GitHubCompliancePlugin;

package/schema.ts

@@ -0,0 +1,88 @@
+/**
+ * GitHub Compliance Plugin for OpenCode
+ * 
+ * Enforces mandatory human approval for GitHub write operations.
+ */
+
+// Centralized schema - single source of truth for all column/table names
+export const SCHEMA = {
+  tables: {
+    COMPLIANCE_RECORDS: "compliance_records",
+    COMPLIANCE_CHECKS: "compliance_checks",
+    AUDIT_LOG: "audit_log",
+    FAILED_ATTEMPTS: "failed_attempts"
+  },
+  columns: {
+    // compliance_records
+    ID: "id",
+    TOOL_NAME: "tool_name",
+    OWNER: "owner",
+    REPO: "repo",
+    TITLE: "title",
+    CONTENT_HASH: "content_hash",
+    GITHUB_USERNAME: "github_username",
+    APPROVED_AT: "approved_at",
+    EXPIRES_AT: "expires_at",
+    STATUS: "status",
+    CREATED_AT: "created_at",
+    CLIENT_NAME: "client_name",
+    POLICY_VERSION: "policy_version",
+    // compliance_checks
+    COMPLIANCE_RECORD_ID: "compliance_record_id",
+    CHECK_TYPE: "check_type",
+    CHECK_PASSED: "check_passed",
+    DETAILS: "details",
+    // audit_log & failed_attempts
+    ERROR_MESSAGE: "error_message",
+    GITHUB_URL: "github_url",
+    GITHUB_ID: "github_id",
+    EXECUTED_AT: "executed_at",
+    CONTENT_PREVIEW: "content_preview",
+    // failed_attempts
+    PROVIDED_RECORD_ID: "provided_record_id",
+    ATTEMPTED_AT: "attempted_at",
+    ERROR_DETAILS: "error_details"
+  },
+  indexes: {
+    COMPLIANCE_LOOKUP: "idx_compliance_lookup",
+    COMPLIANCE_EXPIRES: "idx_compliance_expires"
+  }
+} as const;
+
+// Record status enum
+export const RECORD_STATUS = {
+  PENDING: "pending",
+  APPROVED: "approved",
+  EXPIRED: "expired",
+  USED: "used"
+} as const;
+
+// Check types
+export const CHECK_TYPES = {
+  CONTRIBUTING_MD_READ: "contributing_md_read",
+  DUPLICATE_SEARCHED: "duplicate_searched",
+  TEMPLATE_FOLLOWED: "template_followed",
+  HUMAN_APPROVAL_OBTAINED: "human_approval_obtained",
+  POLICY_ACKNOWLEDGED: "policy_acknowledged",
+  VOUCH_VERIFIED: "vouch_verified"
+} as const;
+
+// Error reasons
+export const ERROR_REASONS = {
+  NO_RECORD: "NO_RECORD",
+  NOT_APPROVED: "NOT_APPROVED",
+  ALREADY_USED: "ALREADY_USED",
+  EXPIRED: "EXPIRED",
+  DATABASE_ERROR: "DATABASE_ERROR",
+  EXTRACTION_ERROR: "EXTRACTION_ERROR",
+  UNEXPECTED_ERROR: "UNEXPECTED_ERROR"
+} as const;
+
+// Record expiration time in milliseconds (30 minutes)
+export const RECORD_TTL_MS = 30 * 60 * 1000;
+
+// Record cleanup age in milliseconds (7 days)
+export const RECORD_CLEANUP_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Content preview max length
+export const CONTENT_PREVIEW_MAX_LENGTH = 500;

package/tools.ts

@@ -0,0 +1,95 @@
+/**
+ * Custom tools exposed to the LLM by the GitHub Compliance Plugin
+ * 
+ * These tools allow the LLM to interact with the compliance system:
+ * - create_compliance_record: Create a record after user approval
+ * - get_compliance_status: Check if a valid record exists
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import type { Plugin } from "@opencode-ai/plugin";
+import { 
+  createComplianceRecord, 
+  getComplianceStatus,
+  type CreateRecordInput 
+} from "./database";
+
+/**
+ * Create a compliance record after user approval
+ * 
+ * This tool MUST be called AFTER:
+ * 1. Reading CONTRIBUTING.md and other community files
+ * 2. Searching for duplicates
+ * 3. Drafting the issue/PR content
+ * 4. Presenting draft to user
+ * 5. Getting explicit user approval ("yes", "proceed", etc.)
+ * 
+ * The tool records that human approval was obtained and creates
+ * a valid compliance record that will allow the GitHub write operation.
+ */
+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.",
+  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" })
+  },
+  async execute(args, _context) {
+    const input: CreateRecordInput = {
+      tool_name: args.tool_name,
+      owner: args.owner,
+      repo: args.repo,
+      title: args.title || null,
+      body: args.body,
+      github_username: args.github_username,
+      approved_at: args.approved_at,
+      checks: args.checks || []
+    };
+
+    const recordId = await createComplianceRecord(input);
+
+    return {
+      success: true,
+      record_id: recordId,
+      message: "Compliance record created. You may now execute the GitHub write operation.",
+      expires_at: new Date(Date.now() + 30 * 60 * 1000).toISOString()
+    };
+  }
+});
+
+/**
+ * Check compliance status for a planned operation
+ * 
+ * Use this to verify if a valid compliance record already exists
+ * before attempting a GitHub write operation.
+ */
+export const getComplianceStatusTool = tool({
+  description: "Check if a valid compliance record exists for a planned GitHub write operation.",
+  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:...)" })
+  },
+  async execute(args, _context) {
+    const status = await getComplianceStatus(args.tool_name, args.owner, args.repo, args.content_hash);
+    return status;
+  }
+});
+
+/**
+ * All custom tools exported by this plugin
+ */
+export const tools = {
+  create_compliance_record: createComplianceRecordTool,
+  get_compliance_status: getComplianceStatusTool
+};