Secure Change Governance

import { TealEngine } from 'tealtiger';

const engine = new TealEngine({
  policy: {
    codeChange: {
      enabled: true,

      // Path allowlists — which files the agent can modify
      pathAllowlist: [
        'src/features/**',
        'src/components/**',
        'tests/**',
        '!src/core/**',          // Deny core modifications
        '!*.config.*',           // Deny config file changes
        '!infrastructure/**'     // Deny IaC changes
      ],

      // Branch allowlists — which branches the agent can target
      branchAllowlist: [
        'feature/*',
        'fix/*',
        'agent/*',
        '!main',                 // Never push to main
        '!release/*',            // Never push to release branches
        '!production'            // Never push to production
      ],

      // Diff hash requirement
      diffHash: {
        required: true,
        algorithm: 'sha256'
      },

      // Two-person rule
      twoPersonRule: {
        enabled: true,
        approvers: ['[email protected]', '[email protected]'],
        timeout: '30m',
        requireDiffReview: true
      }
    }
  }
});

const decision = await engine.evaluate(
  {
    action: 'CODE_CHANGE',
    tool: 'file_write',
    toolParams: {
      path: 'src/core/engine.ts',  // Matches deny pattern '!src/core/**'
      content: '...',
      diff: '...'
    }
  },
  { correlation_id: 'req-001', agentId: 'coding-agent-001' }
);

// decision.action === 'DENY'
// decision.reason_codes === ['CODE_CHANGE_PATH_DENIED']
// decision.metadata.deniedPath === 'src/core/engine.ts'
// decision.metadata.matchedPattern === '!src/core/**'

const decision = await engine.evaluate(
  {
    action: 'CODE_CHANGE',
    tool: 'git_push',
    toolParams: {
      branch: 'main',  // Matches deny pattern '!main'
      commit: 'abc123'
    }
  },
  { correlation_id: 'req-001', agentId: 'coding-agent-001' }
);

// decision.action === 'DENY'
// decision.reason_codes === ['CODE_CHANGE_BRANCH_DENIED']
// decision.metadata.deniedBranch === 'main'

branchAllowlist:
  # Agent creates feature branches
  - "agent/{agent_id}/*"     # e.g., agent/coding-agent-001/fix-login
  - "feature/*"
  - "fix/*"

  # Agent cannot push to protected branches
  - "!main"
  - "!master"
  - "!release/*"
  - "!production"
  - "!staging"

const decision = await engine.evaluate(
  {
    action: 'CODE_CHANGE',
    tool: 'file_write',
    toolParams: {
      path: 'src/features/login.ts',
      content: newContent,
      // Required: SHA-256 hash of the diff
      diffHash: 'sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
      diff: unifiedDiff
    }
  },
  { correlation_id: 'req-001', agentId: 'coding-agent-001' }
);

// If diffHash is missing:
// decision.action === 'DENY'
// decision.reason_codes === ['CODE_CHANGE_DIFF_HASH_MISSING']

// If diffHash doesn't match actual diff:
// decision.action === 'DENY'
// decision.reason_codes === ['CODE_CHANGE_DIFF_HASH_MISMATCH']

// Agent submits code change
const decision = await engine.evaluate(
  {
    action: 'CODE_CHANGE',
    tool: 'git_commit',
    toolParams: {
      files: ['src/features/payment.ts'],
      message: 'Fix payment validation edge case',
      diffHash: 'sha256:abc...',
      diff: unifiedDiff
    }
  },
  { correlation_id: 'req-001', agentId: 'coding-agent-001' }
);

// decision.action === 'PENDING'
// decision.automation_level === 'approval_required'
// decision.approval.token === 'approval-xyz'
// decision.approval.approvers === ['[email protected]']
// decision.approval.requireDiffReview === true

// Human reviews the diff and approves
const approved = await engine.approveDecision('approval-xyz', {
  approvedBy: '[email protected]',
  justification: 'Reviewed diff — fix is correct and scoped appropriately',
  diffReviewed: true
});

// approved.action === 'ALLOW'
// Now the agent can proceed with the commit

interface TwoPersonRule {
  /** Enable two-person rule */
  enabled: boolean;

  /** Who can approve code changes */
  approvers: string[];

  /** Approval timeout */
  timeout: string;

  /** Require the approver to confirm they reviewed the diff */
  requireDiffReview: boolean;

  /** Minimum approvals required (default: 1) */
  minApprovals?: number;

  /** The agent itself cannot be an approver */
  excludeAgent: boolean;

  /** Conditions that trigger two-person rule */
  conditions?: {
    /** Always require for these paths */
    paths?: string[];
    /** Always require for changes > N lines */
    minLines?: number;
    /** Always require for these file types */
    fileTypes?: string[];
  };
}

// In your CI/CD pipeline (GitHub Actions, GitLab CI, etc.)
import { CodeChangeValidator } from 'tealtiger/code-change';

const validator = new CodeChangeValidator({
  engine,
  // Validate that all changes in a PR were governed
  requireGovernanceEvidence: true,
  // Check that diff hashes match actual changes
  validateDiffHashes: true,
  // Verify two-person rule was satisfied
  verifyApprovals: true
});

// Run as a CI check
const result = await validator.validatePR({
  prNumber: 42,
  baseBranch: 'main',
  headBranch: 'agent/coding-agent-001/fix-login',
  commits: prCommits
});

if (!result.valid) {
  console.error('Governance validation failed:', result.violations);
  process.exit(1);  // Fail the CI check
}

# tealtiger.config.yaml
codeChange:
  enabled: true

  pathAllowlist:
    - "src/features/**"
    - "src/components/**"
    - "tests/**"
    - "!src/core/**"
    - "!infrastructure/**"
    - "!*.config.*"
    - "!.env*"

  branchAllowlist:
    - "agent/*"
    - "feature/*"
    - "fix/*"
    - "!main"
    - "!release/*"

  diffHash:
    required: true
    algorithm: sha256

  twoPersonRule:
    enabled: true
    approvers:
      - [email protected]
      - [email protected]
    timeout: 30m
    requireDiffReview: true
    excludeAgent: true
    conditions:
      paths: ["src/core/**", "infrastructure/**"]
      minLines: 50
      fileTypes: [".ts", ".py", ".yaml", ".tf"]