Kaiza MCP Server

--- title: "ADR-002: Plan-Based Authorization System" description: "Decision to implement a plan-based authorization system using hash-addressed contracts" version: "2.0.0" last_updated: "2026-01-31" review_date: "2026-04-30" owners: ["architecture-team"] tags: ["adr", "authorization", "security", "governance"] audience: ["technical", "executive"] --- # ADR-002: Plan-Based Authorization System ## Status Accepted ## Context Traditional authorization systems for AI development face several challenges: - Difficulty in defining granular permissions for complex development tasks - Limited ability to enforce specific implementation requirements - Challenges in maintaining audit trails for authorization decisions - Insufficient control over scope and boundaries of AI agent activities Existing approaches typically rely on: - Role-based permissions that are too coarse-grained - Time-based access controls that don't consider context - Manual approval processes that are difficult to automate - Static rule sets that can't adapt to changing requirements The need exists for a system that can: - Define specific, bounded tasks for AI agents - Ensure all changes are pre-approved and documented - Provide cryptographic verification of authorization - Support complex, multi-step development workflows ## Decision Implement a plan-based authorization system using hash-addressed contracts: ### Plan Structure Each plan is a markdown document containing: - **SHA256 Content Hash**: Cryptographic identifier for the plan - **Role Specification**: Which role can execute this plan - **Status Indicator**: APPROVED/PROPOSED/DEPRECATED - **Scope Definition**: Explicit boundaries of authorized changes - **Implementation Requirements**: Specific technical requirements - **Metadata**: Purpose, context, and execution constraints ### Authorization Process 1. **Plan Creation**: ANTIGRAVITY role creates detailed implementation plans 2. **Plan Review**: Plans undergo technical and security review 3. **Plan Approval**: Approved plans receive APPROVED status 4. **Plan Execution**: WINDSURF role executes only approved plans 5. **Audit Logging**: All plan activities are cryptographically logged ### Hash-Based Identification - Plans are identified by their SHA256 content hash - Hash addressing prevents tampering and ensures integrity - Plans stored as hash-addressed files (e.g., `docs/plans/<HASH>.md`) - Cryptographic verification ensures plan authenticity ## Rationale ### Security Benefits - **Immutable Authorization**: Plans cannot be modified after approval - **Cryptographic Verification**: Hash-based identification prevents tampering - **Bounded Execution**: Plans explicitly define scope and boundaries - **Pre-Approval**: All changes must be approved before execution ### Governance Benefits - **Clear Intent**: Plans document specific implementation requirements - **Audit Trail**: Complete history of plan creation and execution - **Review Process**: Formal review process for all changes - **Accountability**: Clear responsibility assignment for plan creation ### Operational Benefits - **Predictable Execution**: Plans define expected outcomes and constraints - **Reproducibility**: Hash-based identification ensures reproducible results - **Scalability**: System scales with complex development workflows - **Integration**: Compatible with existing development processes ## Alternatives Considered ### Database-Driven Authorization **Pros**: Dynamic updates, complex queries, transaction support **Cons**: Single point of failure, complex infrastructure, potential for data corruption ### Token-Based Authorization **Pros**: Standard approach, widely supported, easy to implement **Cons**: Limited expressiveness, difficult to encode complex requirements, potential for token theft ### Rule-Based Authorization **Pros**: Flexible, can encode complex logic, dynamic evaluation **Cons**: Difficult to audit, complex rule management, potential for rule conflicts ### Manual Approval Workflows **Pros**: Human oversight, flexible, easy to understand **Cons**: Slow, error-prone, difficult to scale, inconsistent enforcement ## Consequences ### Positive Consequences - **Enhanced Security**: Cryptographic verification prevents unauthorized changes - **Clear Governance**: Formal process for all development activities - **Audit Compliance**: Comprehensive audit trail for regulatory compliance - **Quality Assurance**: Pre-approval process ensures quality standards ### Negative Consequences - **Process Overhead**: Additional steps in development workflow - **Complexity**: More complex than simple permission systems - **Learning Curve**: Requires training for plan creation and management - **Tooling Requirements**: Requires specialized tooling for plan management ### Neutral Consequences - **Storage Requirements**: Additional storage for plan documents - **Network Overhead**: Minimal impact on network performance - **Integration Effort**: Requires integration with development workflows ## Implementation Notes ### Technical Implementation - Plan storage in `docs/plans/` directory with hash-based naming - Plan validation through content hash verification - Role-based access control for plan creation and execution - Integration with existing MCP protocol extensions ### Security Considerations - Cryptographic hash verification for plan integrity - Access controls for plan creation and modification - Audit logging for all plan-related activities - Protection against plan collision attacks ### Performance Considerations - Efficient hash calculation and verification - Caching of frequently accessed plans - Optimized plan lookup and validation - Minimal impact on execution performance ### Integration Points - Integration with version control systems - Compatibility with existing CI/CD pipelines - Support for enterprise approval workflows - Integration with project management tools ## Related Decisions - [ADR-001: Dual-Role Governance Model](./001-dual-role-governance.md) - [ADR-003: Cryptographic Audit Logging](./003-cryptographic-audit-logging.md) - [ADR-006: Content Integrity Verification](./006-content-integrity-verification.md) --- **Decision Date**: 2026-01-19 **Decision Maker**: KAIZA MCP Architecture Team **Review Date**: 2026-04-19 **Status**: Accepted and Implemented