@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.0

package/TEST_PLAN.md

@@ -0,0 +1,571 @@
+# MCP-I Core Delegation Test Suite Plan
+
+## Overview
+
+Comprehensive test coverage for W3C VC-based delegation system with cascading revocation.
+
+## Test Categories
+
+### 1. Unit Tests (per module)
+
+#### 1.1 Bitstring Manager (`bitstring.test.ts`)
+
+**Critical Tests:**
+```typescript
+describe('BitstringManager', () => {
+  // Basic Operations
+  test('should set and get bits correctly')
+  test('should handle edge cases (index 0, max index)')
+  test('should throw on out-of-range indices')
+  test('should return all set bits')
+
+  // Encoding/Decoding
+  test('should encode to base64url format')
+  test('should decode from base64url format')
+  test('should handle empty bitstring')
+  test('should handle fully set bitstring')
+  test('should round-trip encode/decode without data loss')
+
+  // Compression
+  test('should compress efficiently (large sparse bitstring)')
+  test('should compress efficiently (large dense bitstring)')
+  test('should handle platform-specific compression (mock)')
+
+  // Edge Cases
+  test('should handle bitstring size not multiple of 8')
+  test('should handle maximum bitstring size (1M entries)')
+  test('should handle concurrent bit operations')
+})
+
+describe('isIndexSet', () => {
+  test('should check index without full decode')
+  test('should return false for out-of-range index')
+  test('should work with various compressed formats')
+})
+```
+
+**Estimated: 15 tests**
+
+---
+
+#### 1.2 VC Issuer (`vc-issuer.test.ts`)
+
+**Critical Tests:**
+```typescript
+describe('DelegationCredentialIssuer', () => {
+  // Basic Issuance
+  test('should issue a valid delegation VC')
+  test('should include all required VC fields')
+  test('should sign with Ed25519')
+  test('should use correct verification method')
+
+  // DelegationRecord → VC Conversion
+  test('should wrap delegation record correctly')
+  test('should preserve delegation constraints')
+  test('should handle optional fields')
+  test('should set proper expiration dates')
+
+  // Credential Status
+  test('should include credentialStatus if provided')
+  test('should omit credentialStatus if not provided')
+
+  // Proof Generation
+  test('should generate valid Ed25519Signature2020 proof')
+  test('should canonicalize VC before signing')
+  test('should include verificationMethod in proof')
+
+  // Error Handling
+  test('should throw on missing identity')
+  test('should throw on invalid delegation record')
+  test('should throw on signing failure')
+})
+
+describe('createAndIssueDelegation', () => {
+  test('should create and issue in one step')
+  test('should generate proper vcId')
+  test('should handle parent delegations')
+})
+```
+
+**Estimated: 18 tests**
+
+---
+
+#### 1.3 VC Verifier (`vc-verifier.test.ts`)
+
+**Critical Tests:**
+```typescript
+describe('DelegationCredentialVerifier', () => {
+  // Progressive Enhancement - Stage 1
+  describe('Stage 1: Basic Checks', () => {
+    test('should reject expired credentials')
+    test('should reject not-yet-valid credentials')
+    test('should reject missing proof')
+    test('should reject revoked status')
+    test('should reject invalid schema')
+    test('should accept valid basic properties')
+    test('should complete in <5ms')
+  })
+
+  // Progressive Enhancement - Stage 2
+  describe('Stage 2: Signature Verification', () => {
+    test('should verify valid Ed25519 signature')
+    test('should reject invalid signature')
+    test('should skip if no DID resolver')
+    test('should reject unresolvable DID')
+    test('should reject wrong verification method')
+    test('should complete in <100ms with resolver')
+  })
+
+  describe('Stage 2: Status Checking', () => {
+    test('should check StatusList2021')
+    test('should reject revoked credentials')
+    test('should accept non-revoked credentials')
+    test('should skip if no status list resolver')
+    test('should handle missing status list')
+  })
+
+  // Combined Results
+  describe('Stage 3: Combined Results', () => {
+    test('should run stages in parallel')
+    test('should return combined result')
+    test('should include performance metrics')
+    test('should cache successful verifications')
+  })
+
+  // Caching
+  describe('Caching', () => {
+    test('should cache valid verifications')
+    test('should respect TTL')
+    test('should skip cache when requested')
+    test('should clear cache entries')
+  })
+})
+```
+
+**Estimated: 24 tests**
+
+---
+
+#### 1.4 StatusList2021 Manager (`statuslist-manager.test.ts`)
+
+**Critical Tests:**
+```typescript
+describe('StatusList2021Manager', () => {
+  // Index Allocation
+  describe('allocateStatusEntry', () => {
+    test('should allocate unique indices')
+    test('should create status list on first allocation')
+    test('should handle concurrent allocations')
+    test('should generate proper credentialStatus entry')
+    test('should support revocation purpose')
+    test('should support suspension purpose')
+  })
+
+  // Status Updates
+  describe('updateStatus', () => {
+    test('should revoke a credential')
+    test('should restore a credential')
+    test('should re-sign after update')
+    test('should handle non-existent status list')
+    test('should handle invalid index')
+  })
+
+  // Status Checking
+  describe('checkStatus', () => {
+    test('should return false for non-revoked')
+    test('should return true for revoked')
+    test('should return false for missing status list')
+    test('should handle invalid status entry')
+  })
+
+  // Status List Creation
+  describe('Status List Creation', () => {
+    test('should create proper StatusList2021Credential')
+    test('should include all required fields')
+    test('should sign with issuer key')
+    test('should use correct context URLs')
+  })
+
+  // Storage Integration
+  describe('Storage Integration', () => {
+    test('should store status lists correctly')
+    test('should retrieve status lists correctly')
+    test('should handle storage failures')
+  })
+
+  // Performance
+  describe('Performance', () => {
+    test('should handle 100K+ entries efficiently')
+    test('should compress bitstring properly')
+    test('should update in <50ms')
+  })
+})
+```
+
+**Estimated: 21 tests**
+
+---
+
+#### 1.5 Delegation Graph (`delegation-graph.test.ts`)
+
+**Critical Tests:**
+```typescript
+describe('DelegationGraphManager', () => {
+  // Node Registration
+  describe('registerDelegation', () => {
+    test('should register root delegation')
+    test('should register child delegation')
+    test('should update parent children list')
+    test('should handle duplicate registration')
+    test('should throw on missing parent')
+  })
+
+  // Graph Queries
+  describe('getChildren', () => {
+    test('should return direct children only')
+    test('should return empty array for leaf nodes')
+    test('should handle deleted children')
+  })
+
+  describe('getDescendants', () => {
+    test('should return all descendants')
+    test('should handle multi-level trees')
+    test('should return empty for leaf nodes')
+    test('should handle large trees (1000+ nodes)')
+  })
+
+  describe('getChain', () => {
+    test('should return path from root to node')
+    test('should include the node itself')
+    test('should order correctly (root first)')
+    test('should handle root nodes')
+  })
+
+  // Relationship Queries
+  describe('isAncestor', () => {
+    test('should identify direct parent')
+    test('should identify distant ancestor')
+    test('should return false for siblings')
+    test('should return false for descendants')
+  })
+
+  describe('getDepth', () => {
+    test('should return 0 for root')
+    test('should return correct depth for nested nodes')
+  })
+
+  // Chain Validation
+  describe('validateChain', () => {
+    test('should validate proper chain')
+    test('should reject broken issuer-subject link')
+    test('should reject broken parent pointer')
+    test('should handle missing nodes')
+  })
+
+  // Node Removal
+  describe('removeDelegation', () => {
+    test('should remove node from graph')
+    test('should update parent children list')
+    test('should handle missing node')
+  })
+})
+```
+
+**Estimated: 23 tests**
+
+---
+
+#### 1.6 Cascading Revocation (`cascading-revocation.test.ts`)
+
+**Critical Tests:**
+```typescript
+describe('CascadingRevocationManager', () => {
+  // Basic Revocation
+  describe('revokeDelegation', () => {
+    test('should revoke single delegation')
+    test('should revoke all children')
+    test('should revoke all grandchildren')
+    test('should trigger revocation hooks')
+    test('should return all revocation events')
+    test('should handle root delegation')
+    test('should handle leaf delegation')
+  })
+
+  // Cascade Depth
+  describe('Cascade Depth', () => {
+    test('should cascade to level 10')
+    test('should enforce maxDepth limit')
+    test('should throw on depth exceeded')
+  })
+
+  // Dry Run
+  describe('Dry Run', () => {
+    test('should not actually revoke in dry run')
+    test('should return what would be revoked')
+    test('should include all descendants')
+  })
+
+  // Restoration
+  describe('restoreDelegation', () => {
+    test('should restore single delegation')
+    test('should NOT cascade to children')
+    test('should update status list')
+  })
+
+  // Revocation Checking
+  describe('isRevoked', () => {
+    test('should detect direct revocation')
+    test('should detect ancestor revocation')
+    test('should return false for valid delegation')
+    test('should identify which ancestor is revoked')
+    test('should check entire chain')
+  })
+
+  describe('getRevokedInSubtree', () => {
+    test('should find all revoked in subtree')
+    test('should handle partial revocation')
+    test('should handle fully revoked subtree')
+  })
+
+  // Validation
+  describe('validateDelegation', () => {
+    test('should validate non-revoked delegation')
+    test('should reject revoked delegation')
+    test('should reject if ancestor revoked')
+    test('should validate chain structure')
+    test('should combine all checks')
+  })
+
+  // Hooks & Events
+  describe('Revocation Hooks', () => {
+    test('should call hook for each revocation')
+    test('should pass correct event data')
+    test('should handle async hooks')
+    test('should handle hook errors gracefully')
+  })
+
+  // Performance
+  describe('Performance', () => {
+    test('should cascade 1000 delegations in <1s')
+    test('should handle large trees efficiently')
+  })
+})
+```
+
+**Estimated: 28 tests**
+
+---
+
+### 2. Integration Tests
+
+#### 2.1 Full Lifecycle Test (`delegation-lifecycle.integration.test.ts`)
+
+```typescript
+describe('Complete Delegation Lifecycle', () => {
+  test('Issue → Verify → Use → Revoke → Verify Again', async () => {
+    // 1. Issue delegation VC
+    // 2. Verify signature
+    // 3. Use delegation for action
+    // 4. Revoke delegation
+    // 5. Verify revocation
+    // 6. Attempt use (should fail)
+  })
+
+  test('Multi-level delegation chain', async () => {
+    // Root → Child1 → Child2 → Child3
+    // Verify chain
+    // Revoke Child1
+    // Verify Child2 and Child3 are revoked
+  })
+
+  test('Parallel delegation branches', async () => {
+    // Root → Child1 → Grandchild1
+    //     → Child2 → Grandchild2
+    // Revoke Child1
+    // Verify Child2 still valid
+  })
+})
+```
+
+**Estimated: 10 tests**
+
+---
+
+#### 2.2 Cross-Module Integration (`cross-module.integration.test.ts`)
+
+```typescript
+describe('Cross-Module Integration', () => {
+  test('VC Issuer → StatusList Manager', async () => {
+    // Issue VC with status
+    // Allocate status entry
+    // Verify status entry in VC
+  })
+
+  test('VC Issuer → Graph → Cascading Revocation', async () => {
+    // Issue parent + children VCs
+    // Register in graph
+    // Revoke parent
+    // Verify all revoked
+  })
+
+  test('Verifier → StatusList → Graph', async () => {
+    // Create complex chain
+    // Revoke middle node
+    // Verify with full validation
+  })
+})
+```
+
+**Estimated: 8 tests**
+
+---
+
+### 3. Performance Tests
+
+```typescript
+describe('Performance Benchmarks', () => {
+  test('Issue 1000 VCs in <10s')
+  test('Verify 1000 VCs in <20s')
+  test('Allocate 100K status entries in <30s')
+  test('Cascade revoke 10K delegations in <5s')
+  test('Bitstring compress 1M entries in <100ms')
+  test('Graph query 10K nodes in <50ms')
+})
+```
+
+**Estimated: 6 tests**
+
+---
+
+### 4. Platform Compatibility Tests
+
+```typescript
+describe('Platform Compatibility', () => {
+  // Node.js specific
+  test('Node.js crypto (zlib compression)')
+  test('Node.js jose library')
+
+  // Cloudflare Workers specific
+  test('Cloudflare CompressionStream')
+  test('Cloudflare Web Crypto API')
+
+  // Browser specific
+  test('Browser Web Crypto API')
+  test('Browser CompressionStream')
+})
+```
+
+**Estimated: 6 tests**
+
+---
+
+### 5. Error & Edge Case Tests
+
+```typescript
+describe('Error Handling', () => {
+  test('Handle missing storage')
+  test('Handle corrupted status list')
+  test('Handle invalid bitstring encoding')
+  test('Handle circular delegation references')
+  test('Handle orphaned delegations')
+  test('Handle extremely deep chains (> 100 levels)')
+  test('Handle concurrent revocations')
+  test('Handle network failures')
+  test('Handle malformed VCs')
+  test('Handle expired signing keys')
+})
+```
+
+**Estimated: 10 tests**
+
+---
+
+## Test Summary
+
+| Category | Module | Tests | Priority |
+|----------|--------|-------|----------|
+| Unit | Bitstring | 15 | HIGH |
+| Unit | VC Issuer | 18 | HIGH |
+| Unit | VC Verifier | 24 | HIGH |
+| Unit | StatusList Manager | 21 | HIGH |
+| Unit | Delegation Graph | 23 | HIGH |
+| Unit | Cascading Revocation | 28 | HIGH |
+| Integration | Full Lifecycle | 10 | CRITICAL |
+| Integration | Cross-Module | 8 | HIGH |
+| Performance | Benchmarks | 6 | MEDIUM |
+| Platform | Compatibility | 6 | MEDIUM |
+| Error | Edge Cases | 10 | HIGH |
+| **TOTAL** | | **169** | |
+
+---
+
+## Test Implementation Strategy
+
+### Phase 1: Core Unit Tests (Priority: CRITICAL)
+1. Bitstring Manager (foundation for everything)
+2. VC Issuer (delegation creation)
+3. VC Verifier (delegation validation)
+
+**Target: 57 tests, 2 days**
+
+---
+
+### Phase 2: Advanced Unit Tests (Priority: HIGH)
+1. StatusList Manager (revocation infrastructure)
+2. Delegation Graph (chain tracking)
+3. Cascading Revocation (Python POC parity)
+
+**Target: 72 tests, 3 days**
+
+---
+
+### Phase 3: Integration Tests (Priority: CRITICAL)
+1. Full lifecycle tests
+2. Cross-module integration
+
+**Target: 18 tests, 1 day**
+
+---
+
+### Phase 4: Performance & Platform Tests (Priority: MEDIUM)
+1. Performance benchmarks
+2. Platform compatibility
+3. Error handling
+
+**Target: 22 tests, 1 day**
+
+---
+
+## Testing Tools
+
+- **Framework**: Vitest (already configured)
+- **Mocking**: Vitest mocks for storage providers
+- **Assertions**: Vitest assertions + custom matchers
+- **Coverage Target**: 90%+ for core modules
+
+---
+
+## Success Criteria
+
+✅ All unit tests pass
+✅ All integration tests pass
+✅ Performance benchmarks meet targets
+✅ Platform compatibility verified
+✅ 90%+ code coverage
+✅ No memory leaks in long-running tests
+✅ Thread-safe operations verified
+
+---
+
+## Next Steps
+
+1. Create test utilities (mock storage, identity providers)
+2. Implement Phase 1 tests
+3. Run coverage reports
+4. Iterate on failing tests
+5. Document test patterns
+
+---
+
+**Total Estimated Effort**: 7 days for complete test suite