@ossdeveloper/github-compliance 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,216 @@
+# Architecture
+
+Deep dive into the GitHub Compliance Plugin design.
+
+## Design Goals
+
+1. **External Enforcement**: Compliance is enforced by external code, not LLM reasoning
+2. **No Server-Side Storage**: All state in local SQLite, no external infrastructure
+3. **Content Integrity**: Hash-based verification prevents content tampering
+4. **Audit Trail**: Complete history of all operations for debugging
+5. **Centralized Schema**: Single source of truth for all database definitions
+
+## Component Flow
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                           tool.execute.before                            │
+│                                                                          │
+│  ┌──────────────┐     ┌──────────────┐     ┌──────────────────────────┐ │
+│  │ isWriteTool? │────▶│ extractInfo  │────▶│ getComplianceRecord     │ │
+│  └──────────────┘     └──────────────┘     └──────────────────────────┘ │
+│                                                        │                 │
+│                                                        ▼                 │
+│                                              ┌──────────────────┐       │
+│                                              │ validateCompliance│       │
+│                                              └──────────────────┘       │
+│                                                        │                 │
+│                              ┌──────────────────────────┼───────────────┐ │
+│                              │                          │               │ │
+│                              ▼                          ▼               │ │
+│                    ┌──────────────────┐    ┌──────────────────────┐    │ │
+│                    │ valid: false     │    │ valid: true          │    │ │
+│                    │ logFailedAttempt │    │ markRecordUsed       │    │ │
+│                    │ throw BlockedErr │    │ attach metadata      │    │ │
+│                    └──────────────────┘    └──────────────────────┘    │ │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## Schema Design (schema.ts)
+
+All database definitions are centralized in `schema.ts`:
+
+```typescript
+export const SCHEMA = {
+  tables: {
+    COMPLIANCE_RECORDS: "compliance_records",
+    COMPLIANCE_CHECKS: "compliance_checks",
+    AUDIT_LOG: "audit_log",
+    FAILED_ATTEMPTS: "failed_attempts"
+  },
+  columns: {
+    ID: "id",
+    TOOL_NAME: "tool_name",
+    // ... all columns
+  },
+  indexes: {
+    COMPLIANCE_LOOKUP: "idx_compliance_lookup",
+    COMPLIANCE_EXPIRES: "idx_compliance_expires"
+  }
+}
+
+export const RECORD_STATUS = {
+  PENDING: "pending",
+  APPROVED: "approved",
+  EXP IRED: "expired",
+  USED: "used"
+}
+```
+
+**Why centralized schema matters:**
+
+1. **Single Source of Truth**: Column names defined once, used everywhere
+2. **No Typos**: `SCHEMA.columns.STATUS` vs manually typing "status"
+3. **Refactoring**: Change a name in schema.ts, all SQL updates automatically
+4. **IDE Support**: Autocomplete works for all table/column names
+
+## Database Design
+
+### Compliance Record Lifecycle
+
+```
+pending ────▶ approved ────▶ used
+                  │
+                  └──▶ expired (automatic after 30 min)
+```
+
+### Content Hash Calculation
+
+```typescript
+// In compliance.ts
+const content = JSON.stringify({
+  title: title || "",
+  body: body || ""
+});
+const hash = "sha256:" + createHash("sha256").update(content).digest("hex");
+```
+
+**Why this matters**: The hash ensures the content the LLM drafted is the same content that gets executed. If the LLM modifies content between approval and execution, the hash won't match and the operation will be rejected.
+
+### Indexes
+
+```sql
+CREATE INDEX idx_compliance_lookup ON compliance_records(tool_name, owner, repo, status);
+CREATE INDEX idx_compliance_expires ON compliance_records(expires_at);
+```
+
+- `idx_compliance_lookup`: Fast lookups for validation
+- `idx_compliance_expires`: Fast cleanup of expired records
+
+## Hook Execution Order
+
+1. **tool.execute.before**
+   - Runs BEFORE tool execution
+   - Can modify output (attach metadata)
+   - Can throw to block execution
+
+2. **Tool executes** (if before hook allowed)
+
+3. **tool.execute.after**
+   - Runs AFTER tool execution
+   - Cannot block, only for logging
+   - Can access output.result
+
+## Custom Tool Execution
+
+Custom tools (from `tools.ts`) do NOT go through the `tool.execute.before` hook. They execute directly. This is intentional - the custom tools are how the LLM creates compliance records, so they must always be allowed.
+
+## Error Handling Strategy
+
+| Error Type | Handling |
+|------------|----------|
+| NO_RECORD | Clear message to load skill and follow workflow |
+| NOT_APPROVED | Tell LLM to present draft and get approval |
+| ALREADY_USED | Each write needs its own record |
+| EXPIRED | Re-approval required |
+| DATABASE_ERROR | Log and suggest retry |
+
+All error reasons are defined in `ERROR_REASONS` enum in `schema.ts`.
+
+## Extensibility Points
+
+### 1. New Check Types
+
+Add to `CHECK_TYPES` in `schema.ts`:
+
+```typescript
+export const CHECK_TYPES = {
+  // ... existing ...
+  VOUCH_VERIFIED: "vouch_verified"
+}
+```
+
+LLM will automatically include them when calling `create_compliance_record`.
+
+### 2. New Validation Rules
+
+Add to `validateCompliance()` in `database.ts`:
+
+```typescript
+if (record.status === RECORD_STATUS.PENDING) {
+  return { valid: false, reason: ERROR_REASONS.NOT_APPROVED, ... };
+}
+// Add new validation here
+```
+
+### 3. New Columns
+
+To add a new column:
+
+1. Add to `SCHEMA.columns` in `schema.ts`
+2. Add to `CREATE TABLE` in `initDatabase()` in `database.ts`
+3. Add to `ComplianceRecord` interface in `database.ts`
+
+### 4. New Table
+
+To add a new table:
+
+1. Add table name to `SCHEMA.tables` in `schema.ts`
+2. Add column constants to `SCHEMA.columns` in `schema.ts`
+3. Add `CREATE TABLE` in `initDatabase()` in `database.ts`
+4. Create CRUD functions in `database.ts`
+
+## Security Considerations
+
+1. **No Fabrication**: LLM cannot fake compliance records - they must actually call `create_compliance_record`
+2. **No Bypass**: Plugin hook cannot be circumvented by LLM
+3. **Content Integrity**: Hash prevents silent content changes
+4. **Expiration**: 30-minute window limits abuse window
+
+## Testing Considerations
+
+### Happy Path
+1. Load skill
+2. Read CONTRIBUTING.md
+3. Search duplicates
+4. Draft content
+5. Present to user
+6. Get approval
+7. Call create_compliance_record
+8. Call issue_write
+9. Success logged
+
+### Rejection Paths
+- No record → Blocked with NO_RECORD
+- Expired record → Blocked with EXPIRED
+- Content changed → Blocked (hash mismatch)
+- Record already used → Blocked with ALREADY_USED
+
+## Future Improvements
+
+1. **Cleanup Job**: Cron-like cleanup of old records
+2. **Metrics**: Track compliance pass/fail rates
+3. **Policy Fetching**: Pull compliance policy from repo
+4. **Multi-Client Support**: Share compliance records across clients
+5. **Signature Verification**: Cryptographic signing of records

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to the GitHub Compliance Plugin.
+
+## [1.2.0] - 2026-03-21
+
+### Added
+
+- Prefix/suffix variation support - all GitHub write tools now have both `tool_name` and `github_tool_name` variants (e.g., `issue_write` and `github_issue_write`)
+- Additional GitHub write tools intercepted:
+  - `push_files` / `github_push_files`
+  - `create_branch` / `github_create_branch`
+  - `create_or_update_file` / `github_create_or_update_file`
+  - `delete_file` / `github_delete_file`
+  - `create_repository` / `github_create_repository`
+  - `create_pull_request_with_copilot` / `github_create_pull_request_with_copilot`
+  - `update_pull_request_branch` / `github_update_pull_request_branch`
+  - `reply_to_pull_request_comment` / `github_reply_to_pull_request_comment`
+  - `add_reply_to_pull_request_comment` / `github_add_reply_to_pull_request_comment`
+
+### Benefits
+
+- Ensures no GitHub write operation can escape interception regardless of MCP tool naming convention
+- Comprehensive coverage of all GitHub MCP write tools
+
+## [1.1.0] - 2026-03-21
+
+### Added
+
+- `schema.ts` - Centralized constants for all table names, column names, enums
+- `SCHEMA.tables` - Table name constants
+- `SCHEMA.columns` - All column name constants
+- `SCHEMA.indexes` - Index name constants
+- `RECORD_STATUS` enum - Record status values
+- `CHECK_TYPES` enum - Check type constants
+- `ERROR_REASONS` enum - Error reason constants
+- `RECORD_TTL_MS` - Record expiration time constant
+- `RECORD_CLEANUP_AGE_MS` - Cleanup age constant
+- `CONTENT_PREVIEW_MAX_LENGTH` - Content preview truncation limit
+
+### Changed
+
+- Refactored all SQL queries to use centralized schema constants
+- All `CREATE TABLE` statements now use `SCHEMA.tables.*` and `SCHEMA.columns.*`
+- All `INSERT` statements now use centralized constants
+- All `SELECT`, `UPDATE`, `DELETE` statements now use centralized constants
+- `validateCompliance()` now uses `RECORD_STATUS` enum
+- Error handling now uses `ERROR_REASONS` enum
+- Plugin hook now uses `ERROR_REASONS` enum
+
+### Benefits
+
+- Single source of truth for all schema definitions
+- Change a column name in one place, propagates everywhere
+- Eliminates typos between schema definition and queries
+- IDE autocomplete works for table/column names
+- Self-documenting SQL
+
+## [1.0.0] - 2026-03-20
+
+### Added
+
+- Initial implementation
+- SQLite database with 4 tables:
+  - `compliance_records` - Main compliance records
+  - `compliance_checks` - Individual checks per record
+  - `audit_log` - Successful operation log
+  - `failed_attempts` - Rejected operation log
+- Plugin hooks:
+  - `tool.execute.before` - Intercepts and validates GitHub write tools
+  - `tool.execute.after` - Logs successful executions
+- Custom tools for LLM:
+  - `create_compliance_record` - Create record after user approval
+  - `get_compliance_status` - Check existing record status
+- GitHub write tool interception (11 tools):
+  - issue_write, issue_update
+  - pull_request_write, pull_request_update
+  - add_issue_comment, add_pull_request_comment
+  - pull_request_review, pull_request_review_comment
+  - create_pull_request, update_issue, update_pull_request
+- Content hash integrity verification
+- 30-minute expiration on compliance records
+- Comprehensive error messages with workflow instructions
+- JSDoc documentation throughout
+
+### Configuration
+
+- Plugin configured in `opencode.json`:
+  ```json
+  {
+    "plugin": ["github-compliance"],
+    "permission": {
+      "github_*": "ask"
+    }
+  }
+  ```
+
+### Database Location
+
+`~/.opencode/github-compliance.db`

package/README.md

@@ -0,0 +1,273 @@
+# GitHub Compliance Plugin
+
+Enforces mandatory human approval for GitHub write operations in OpenCode.
+
+## Overview
+
+This plugin intercepts GitHub write operations and blocks them unless a valid compliance record exists in SQLite. The LLM must follow the compliance workflow to create a record before any write operation is allowed.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         OpenCode                                 │
+│  ┌───────────┐    ┌──────────────────────────────────────────┐ │
+│  │   LLM    │───▶│ Plugin (tool.execute.before)              │ │
+│  └───────────┘    │ - Checks SQLite for compliance record      │ │
+│                   │ - Validates status, expiration           │ │
+│                   │ - Blocks if invalid, allows if valid     │ │
+│                   └──────────────────────────────────────────┘ │
+│                                    │                            │
+│                                    ▼                            │
+│                   ┌──────────────────────────────────────────┐ │
+│                   │ Custom Tools (LLM calls these)             │ │
+│                   │ - create_compliance_record                 │ │
+│                   │ - get_compliance_status                    │ │
+│                   └──────────────────────────────────────────┘ │
+│                                    │                            │
+└────────────────────────────────────┼────────────────────────────┘
+                                     │
+                                     ▼
+                         ┌─────────────────────┐
+                         │  SQLite Database     │
+                         │  ~/.opencode/       │
+                         │  github-compliance.db│
+                         └─────────────────────┘
+```
+
+## Components
+
+| File | Purpose |
+|------|---------|
+| `schema.ts` | Centralized constants for table/column names, enums |
+| `database.ts` | SQLite operations, schema, CRUD |
+| `compliance.ts` | Tool identification, content hashing, validation logic |
+| `errors.ts` | Error message generation |
+| `tools.ts` | Custom tools exposed to LLM |
+| `plugin.ts` | Main entry, hooks into tool.execute.before/after |
+
+## Schema (schema.ts)
+
+All table and column names are centralized in `schema.ts`:
+
+```typescript
+export const SCHEMA = {
+  tables: {
+    COMPLIANCE_RECORDS: "compliance_records",
+    COMPLIANCE_CHECKS: "compliance_checks",
+    AUDIT_LOG: "audit_log",
+    FAILED_ATTEMPTS: "failed_attempts"
+  },
+  columns: { ID, TOOL_NAME, OWNER, REPO, ... },
+  indexes: { COMPLIANCE_LOOKUP, COMPLIANCE_EXPIRES }
+}
+
+export const RECORD_STATUS = { PENDING, APPROVED, EXPIRED, USED }
+export const CHECK_TYPES = { CONTRIBUTING_MD_READ, DUPLICATE_SEARCHED, ... }
+export const ERROR_REASONS = { NO_RECORD, NOT_APPROVED, ALREADY_USED, ... }
+export const RECORD_TTL_MS = 30 * 60 * 1000
+```
+
+## Installation
+
+1. Copy plugin to `~/.config/opencode/plugins/github-compliance/`
+2. Add to `opencode.json`:
+
+```json
+{
+  "plugin": ["github-compliance"],
+  "permission": {
+    "github_*": "ask"
+  }
+}
+```
+
+## Database Schema
+
+### compliance_records
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | TEXT | UUID primary key |
+| tool_name | TEXT | GitHub tool name |
+| owner | TEXT | Repository owner |
+| repo | TEXT | Repository name |
+| content_hash | TEXT | SHA256 of content |
+| github_username | TEXT | Approver's GitHub username |
+| approved_at | TEXT | ISO8601 timestamp |
+| expires_at | TEXT | ISO8601 expiration |
+| status | TEXT | pending/approved/expired/used |
+
+### compliance_checks
+
+Stores individual checks performed for each record.
+
+### audit_log
+
+Immutable log of successful operations.
+
+### failed_attempts
+
+Log of rejected operations with reasons.
+
+## Workflow
+
+```
+1. LLM attempts github_issue_write
+         ↓
+2. plugin.tool.execute.before intercepts
+         ↓
+3. Checks SQLite for compliance record
+         ↓
+4. No record → BLOCK with error message
+   Record valid → Mark as used, allow execution
+         ↓
+5. If allowed, plugin.tool.execute.after logs success
+```
+
+## Custom Tools
+
+### create_compliance_record
+
+Called by LLM after user approval.
+
+```typescript
+create_compliance_record({
+  tool_name: "issue_write",
+  owner: "owner",
+  repo: "repo",
+  title: "Issue title",
+  body: "Issue body",
+  github_username: "user",
+  approved_at: "2026-03-20T15:30:00Z",
+  checks: [
+    { check_type: "contributing_md_read", passed: true },
+    { check_type: "duplicate_searched", passed: true },
+    { check_type: "human_approval_obtained", passed: true }
+  ]
+})
+```
+
+### get_compliance_status
+
+Check if valid record exists.
+
+```typescript
+get_compliance_status({
+  tool_name: "issue_write",
+  owner: "owner",
+  repo: "repo",
+  content_hash: "sha256:abc123..."
+})
+```
+
+## Extending
+
+### Adding New Write Tools
+
+Edit `GITHUB_WRITE_TOOLS_UNPREFIXED` in `compliance.ts`. The prefixed variants (`github_` prefix) are automatically generated:
+
+```typescript
+const GITHUB_WRITE_TOOLS_UNPREFIXED = [
+  // ... existing tools ...
+  "new_write_tool"
+] as const;
+
+const GITHUB_WRITE_TOOLS_PREFIXED = GITHUB_WRITE_TOOLS_UNPREFIXED.map(t => `github_${t}`);
+
+export const GITHUB_WRITE_TOOLS = [...GITHUB_WRITE_TOOLS_UNPREFIXED, ...GITHUB_WRITE_TOOLS_PREFIXED] as const;
+```
+
+Note: Both `tool_name` and `github_tool_name` variants will be intercepted.
+
+### Currently Intercepted Tools
+
+The plugin intercepts all GitHub write tools in both prefixed and unprefixed forms:
+
+- Issue operations: `issue_write`, `issue_update`, `update_issue`
+- Pull request operations: `pull_request_write`, `pull_request_update`, `create_pull_request`, `update_pull_request`, `pull_request_review`, `update_pull_request_branch`
+- Comments: `add_issue_comment`, `add_pull_request_comment`, `pull_request_review_comment`, `reply_to_pull_request_comment`, `add_reply_to_pull_request_comment`
+- Repository operations: `push_files`, `create_branch`, `create_or_update_file`, `delete_file`, `create_repository`
+- Advanced: `create_pull_request_with_copilot`
+
+### Adding New Check Types
+
+1. Add to `CHECK_TYPES` in `schema.ts`
+2. LLM includes in `checks` array when calling `create_compliance_record`
+3. Check is stored in `compliance_checks` table
+
+### Adding New Validation Rules
+
+Edit `validateCompliance()` in `database.ts`:
+
+```typescript
+if (record.status === RECORD_STATUS.PENDING) {
+  return { valid: false, reason: ERROR_REASONS.NOT_APPROVED, ... };
+}
+// Add new validation here
+```
+
+### Adding New Columns
+
+1. Add column constant to `SCHEMA.columns` in `schema.ts`
+2. Update `CREATE TABLE` statements in `initDatabase()` in `database.ts`
+3. Update type interfaces in `database.ts`
+
+## Compliance JSON Format
+
+Issues/PRs should include this JSON in the body:
+
+```json
+{
+  "mcp_compliance": {
+    "version": "1.0",
+    "client": {
+      "name": "opencode",
+      "client_issue_id": "<record_uuid>"
+    },
+    "human_approval": {
+      "github_username": "<user>",
+      "approved_at": "<timestamp>"
+    },
+    "checks_performed": [
+      "contributing_md_read",
+      "duplicate_searched",
+      "human_approval_obtained"
+    ]
+  }
+}
+```
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| NO_RECORD | No compliance record found |
+| NOT_APPROVED | Record exists but not approved |
+| ALREADY_USED | Record already consumed |
+| EXPIRED | Record older than 30 minutes |
+| DATABASE_ERROR | SQLite error |
+
+## Maintenance
+
+### Cleanup Expired Records
+
+Called automatically on plugin init:
+
+```typescript
+await cleanupExpiredRecords();  // Marks expired as 'expired'
+await cleanupOldRecords();      // Deletes records > 7 days old
+```
+
+### Content Hash Stability
+
+Hash is computed from `title` and `body` only. Do not include:
+- Timestamps
+- Dynamic content
+- Template auto-fill that changes
+
+## Version
+
+Current: 1.2.0
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.