cap-pro 1.0.0

package/cap/references/security-test-templates.md

@@ -0,0 +1,347 @@
+# Security Test Templates
+
+Reference document for the cap-validator agent (test mode) when generating security-focused tests. Use these templates as starting points, adapting table names, column names, and auth patterns to the target project.
+
+---
+
+## 1. RLS Policy Tests (Supabase)
+
+Row-Level Security tests verify that database policies enforce data isolation between users.
+
+### User isolation -- read
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createClient } from '@supabase/supabase-js';
+
+describe('RLS: TABLE_NAME read isolation', () => {
+  it('user cannot read other user data', async () => {
+    // Arrange: create client authenticated as User A
+    const supabaseA = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+      global: { headers: { Authorization: `Bearer ${userAToken}` } },
+    });
+
+    // Act: query data belonging to User B
+    const { data, error } = await supabaseA
+      .from('TABLE_NAME')
+      .select('*')
+      .eq('user_id', userBId);
+
+    // Assert: no data returned (RLS blocks access)
+    expect(error).toBeNull();
+    expect(data).toHaveLength(0);
+  });
+
+  it('user can read own data', async () => {
+    const supabaseA = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+      global: { headers: { Authorization: `Bearer ${userAToken}` } },
+    });
+
+    const { data, error } = await supabaseA
+      .from('TABLE_NAME')
+      .select('*')
+      .eq('user_id', userAId);
+
+    expect(error).toBeNull();
+    expect(data.length).toBeGreaterThan(0);
+  });
+});
+```
+
+### User isolation -- write
+
+```typescript
+describe('RLS: TABLE_NAME write isolation', () => {
+  it('user cannot update other user data', async () => {
+    const supabaseA = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+      global: { headers: { Authorization: `Bearer ${userAToken}` } },
+    });
+
+    const { error } = await supabaseA
+      .from('TABLE_NAME')
+      .update({ name: 'hacked' })
+      .eq('user_id', userBId);
+
+    // Either error or zero affected rows
+    expect(error || true).toBeTruthy();
+  });
+
+  it('user cannot delete other user data', async () => {
+    const supabaseA = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+      global: { headers: { Authorization: `Bearer ${userAToken}` } },
+    });
+
+    const { error } = await supabaseA
+      .from('TABLE_NAME')
+      .delete()
+      .eq('user_id', userBId);
+
+    expect(error || true).toBeTruthy();
+  });
+});
+```
+
+### Anon access blocked
+
+```typescript
+describe('RLS: TABLE_NAME anon access', () => {
+  it('anonymous user cannot read any data', async () => {
+    const supabaseAnon = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
+
+    const { data, error } = await supabaseAnon
+      .from('TABLE_NAME')
+      .select('*');
+
+    // Either empty result or permission error
+    expect(data?.length ?? 0).toBe(0);
+  });
+});
+```
+
+---
+
+## 2. Auth Bypass Tests
+
+Tests that verify authentication cannot be bypassed through common attack vectors.
+
+### JWT validation
+
+```typescript
+describe('Auth: JWT validation', () => {
+  it('rejects expired JWT token', async () => {
+    const expiredToken = createJWT({ sub: userId, exp: Math.floor(Date.now() / 1000) - 3600 });
+    const response = await fetch(`${API_URL}/protected`, {
+      headers: { Authorization: `Bearer ${expiredToken}` },
+    });
+    expect(response.status).toBe(401);
+  });
+
+  it('rejects modified JWT payload', async () => {
+    const validToken = createJWT({ sub: userId, role: 'user' });
+    // Tamper with payload (change role to admin without re-signing)
+    const parts = validToken.split('.');
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    payload.role = 'admin';
+    parts[1] = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const tamperedToken = parts.join('.');
+
+    const response = await fetch(`${API_URL}/protected`, {
+      headers: { Authorization: `Bearer ${tamperedToken}` },
+    });
+    expect(response.status).toBe(401);
+  });
+
+  it('rejects missing auth header', async () => {
+    const response = await fetch(`${API_URL}/protected`);
+    expect(response.status).toBe(401);
+  });
+
+  it('rejects token from wrong issuer', async () => {
+    const wrongIssuerToken = createJWT({ sub: userId, iss: 'https://evil.example.com' });
+    const response = await fetch(`${API_URL}/protected`, {
+      headers: { Authorization: `Bearer ${wrongIssuerToken}` },
+    });
+    expect(response.status).toBe(401);
+  });
+
+  it('rejects token with invalid signature', async () => {
+    const token = createJWT({ sub: userId });
+    const corruptedToken = token.slice(0, -5) + 'XXXXX';
+    const response = await fetch(`${API_URL}/protected`, {
+      headers: { Authorization: `Bearer ${corruptedToken}` },
+    });
+    expect(response.status).toBe(401);
+  });
+});
+```
+
+### Role escalation
+
+```typescript
+describe('Auth: role escalation prevention', () => {
+  it('regular user cannot access admin endpoint', async () => {
+    const userToken = await loginAs('regular-user');
+    const response = await fetch(`${API_URL}/admin/users`, {
+      headers: { Authorization: `Bearer ${userToken}` },
+    });
+    expect(response.status).toBe(403);
+  });
+
+  it('regular user cannot modify own role', async () => {
+    const userToken = await loginAs('regular-user');
+    const response = await fetch(`${API_URL}/users/me`, {
+      method: 'PATCH',
+      headers: {
+        Authorization: `Bearer ${userToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ role: 'admin' }),
+    });
+    // Should either reject or ignore the role field
+    expect(response.status).not.toBe(200);
+  });
+});
+```
+
+---
+
+## 3. Input Sanitization Tests
+
+Tests that verify user input is properly sanitized against injection attacks.
+
+### XSS prevention
+
+```typescript
+describe('Input: XSS prevention', () => {
+  it('rejects script tags in text fields', async () => {
+    const response = await createResource({
+      name: '<script>alert("xss")</script>',
+    });
+    // Should either reject or escape the input
+    if (response.status === 200) {
+      const data = await response.json();
+      expect(data.name).not.toContain('<script>');
+    } else {
+      expect(response.status).toBe(400);
+    }
+  });
+
+  it('rejects event handler injection', async () => {
+    const response = await createResource({
+      name: '" onmouseover="alert(1)',
+    });
+    if (response.status === 200) {
+      const data = await response.json();
+      expect(data.name).not.toContain('onmouseover');
+    } else {
+      expect(response.status).toBe(400);
+    }
+  });
+});
+```
+
+### SQL injection prevention
+
+```typescript
+describe('Input: SQL injection prevention', () => {
+  it('rejects SQL injection in search parameter', async () => {
+    const response = await fetch(`${API_URL}/search?q=' OR '1'='1`);
+    // Should not return all records
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    expect(data.length).toBeLessThan(100); // Sanity check
+  });
+
+  it('rejects UNION-based injection', async () => {
+    const response = await fetch(`${API_URL}/search?q=' UNION SELECT * FROM users --`);
+    expect(response.status).toBe(200);
+    const data = await response.json();
+    // Should not contain user table data
+    expect(data.some(d => d.password_hash)).toBe(false);
+  });
+});
+```
+
+### Path traversal prevention
+
+```typescript
+describe('Input: path traversal prevention', () => {
+  it('rejects directory traversal in file path', async () => {
+    const response = await fetch(`${API_URL}/files/../../../etc/passwd`);
+    expect(response.status).toBe(400);
+  });
+
+  it('rejects encoded directory traversal', async () => {
+    const response = await fetch(`${API_URL}/files/%2e%2e%2f%2e%2e%2f%2e%2e%2fetc%2fpasswd`);
+    expect([400, 403, 404]).toContain(response.status);
+  });
+});
+```
+
+---
+
+## 4. Data Leakage Tests
+
+Tests that verify sensitive data is never exposed in API responses or error messages.
+
+### Sensitive field filtering
+
+```typescript
+describe('Data leakage: sensitive field filtering', () => {
+  it('API does not return password hash', async () => {
+    const response = await fetch(`${API_URL}/users/me`, {
+      headers: { Authorization: `Bearer ${validToken}` },
+    });
+    const data = await response.json();
+    expect(data).not.toHaveProperty('password_hash');
+    expect(data).not.toHaveProperty('password');
+    expect(data).not.toHaveProperty('hashed_password');
+  });
+
+  it('API does not return internal database IDs in list endpoints', async () => {
+    const response = await fetch(`${API_URL}/resources`, {
+      headers: { Authorization: `Bearer ${validToken}` },
+    });
+    const data = await response.json();
+    for (const item of data) {
+      expect(item).not.toHaveProperty('_id'); // MongoDB internal ID
+      expect(item).not.toHaveProperty('internal_id');
+    }
+  });
+
+  it('API does not expose other users email addresses', async () => {
+    const response = await fetch(`${API_URL}/users`, {
+      headers: { Authorization: `Bearer ${validToken}` },
+    });
+    const data = await response.json();
+    const otherUsers = data.filter(u => u.id !== currentUserId);
+    for (const user of otherUsers) {
+      expect(user).not.toHaveProperty('email');
+    }
+  });
+});
+```
+
+### Error message safety
+
+```typescript
+describe('Data leakage: error messages', () => {
+  it('error responses do not leak stack traces', async () => {
+    const response = await fetch(`${API_URL}/trigger-error`);
+    const body = await response.text();
+    expect(body).not.toMatch(/at\s+\w+\s+\(/); // Stack trace pattern
+    expect(body).not.toContain('node_modules');
+    expect(body).not.toContain('.js:');
+  });
+
+  it('error responses do not leak database details', async () => {
+    const response = await fetch(`${API_URL}/trigger-error`);
+    const body = await response.text();
+    expect(body).not.toMatch(/SELECT|INSERT|UPDATE|DELETE/i);
+    expect(body).not.toContain('postgresql://');
+    expect(body).not.toContain('SQLSTATE');
+  });
+
+  it('404 does not reveal valid resource IDs', async () => {
+    const response = await fetch(`${API_URL}/users/nonexistent-id`);
+    const body = await response.text();
+    expect(body).not.toMatch(/valid IDs include/i);
+    expect(body).not.toMatch(/did you mean/i);
+  });
+});
+```
+
+---
+
+## Usage Notes
+
+When generating security tests:
+
+1. **Adapt table/column names** to the target project's schema
+2. **Use the project's actual auth mechanism** (Supabase, NextAuth, custom JWT, etc.)
+3. **Test both happy and sad paths** -- a secure system rejects bad input AND accepts good input
+4. **Cover the OWASP Top 10** relevant to the application type
+5. **For RLS tests**: create two test users, try cross-user access in both directions
+6. **For auth tests**: test expired, tampered, missing, and wrong-issuer tokens
+7. **For input tests**: use payloads from OWASP cheat sheets
+8. **For leakage tests**: check every API endpoint that returns user data

package/cap/references/session-template.json

@@ -0,0 +1,8 @@
+{
+  "version": "2.0.0",
+  "lastCommand": null,
+  "lastCommandTimestamp": null,
+  "activeFeature": null,
+  "activeDebugSession": null,
+  "metadata": {}
+}

package/cap/references/tdd.md

@@ -0,0 +1,263 @@
+<overview>
+TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
+
+**Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
+
+**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
+</overview>
+
+<when_to_use_tdd>
+## When TDD Improves Quality
+
+**TDD candidates (create a TDD plan):**
+- Business logic with defined inputs/outputs
+- API endpoints with request/response contracts
+- Data transformations, parsing, formatting
+- Validation rules and constraints
+- Algorithms with testable behavior
+- State machines and workflows
+- Utility functions with clear specifications
+
+**Skip TDD (use standard plan with `type="auto"` tasks):**
+- UI layout, styling, visual components
+- Configuration changes
+- Glue code connecting existing components
+- One-off scripts and migrations
+- Simple CRUD with no business logic
+- Exploratory prototyping
+
+**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+→ Yes: Create a TDD plan
+→ No: Use standard plan, add tests after if needed
+</when_to_use_tdd>
+
+<tdd_plan_structure>
+## TDD Plan Structure
+
+Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: tdd
+---
+
+<objective>
+[What feature and why]
+Purpose: [Design benefit of TDD for this feature]
+Output: [Working, tested feature]
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@relevant/source/files.ts
+</context>
+
+<feature>
+  <name>[Feature name]</name>
+  <files>[source file, test file]</files>
+  <behavior>
+    [Expected behavior in testable terms]
+    Cases: input → expected output
+  </behavior>
+  <implementation>[How to implement once tests pass]</implementation>
+</feature>
+
+<verification>
+[Test command that proves feature works]
+</verification>
+
+<success_criteria>
+- Failing test written and committed
+- Implementation passes test
+- Refactor complete (if needed)
+- All 2-3 commits present
+</success_criteria>
+
+<output>
+After completion, create SUMMARY.md with:
+- RED: What test was written, why it failed
+- GREEN: What implementation made it pass
+- REFACTOR: What cleanup was done (if any)
+- Commits: List of commits produced
+</output>
+```
+
+**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after.
+</tdd_plan_structure>
+
+<execution_flow>
+## Red-Green-Refactor Cycle
+
+**RED - Write failing test:**
+1. Create test file following project conventions
+2. Write test describing expected behavior (from `<behavior>` element)
+3. Run test - it MUST fail
+4. If test passes: feature exists or test is wrong. Investigate.
+5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+
+**GREEN - Implement to pass:**
+1. Write minimal code to make test pass
+2. No cleverness, no optimization - just make it work
+3. Run test - it MUST pass
+4. Commit: `feat({phase}-{plan}): implement [feature]`
+
+**REFACTOR (if needed):**
+1. Clean up implementation if obvious improvements exist
+2. Run tests - MUST still pass
+3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
+
+**Result:** Each TDD plan produces 2-3 atomic commits.
+</execution_flow>
+
+<test_quality>
+## Good Tests vs Bad Tests
+
+**Test behavior, not implementation:**
+- Good: "returns formatted date string"
+- Bad: "calls formatDate helper with correct params"
+- Tests should survive refactors
+
+**One concept per test:**
+- Good: Separate tests for valid input, empty input, malformed input
+- Bad: Single test checking all edge cases with multiple assertions
+
+**Descriptive names:**
+- Good: "should reject empty email", "returns null for invalid ID"
+- Bad: "test1", "handles error", "works correctly"
+
+**No implementation details:**
+- Good: Test public API, observable behavior
+- Bad: Mock internals, test private methods, assert on internal state
+</test_quality>
+
+<framework_setup>
+## Test Framework Setup (If None Exists)
+
+When executing a TDD plan but no test framework is configured, set it up as part of the RED phase:
+
+**1. Detect project type:**
+```bash
+# JavaScript/TypeScript
+if [ -f package.json ]; then echo "node"; fi
+
+# Python
+if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
+
+# Go
+if [ -f go.mod ]; then echo "go"; fi
+
+# Rust
+if [ -f Cargo.toml ]; then echo "rust"; fi
+```
+
+**2. Install minimal framework:**
+| Project | Framework | Install |
+|---------|-----------|---------|
+| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
+| Node.js (Vite) | Vitest | `npm install -D vitest` |
+| Python | pytest | `pip install pytest` |
+| Go | testing | Built-in |
+| Rust | cargo test | Built-in |
+
+**3. Create config if needed:**
+- Jest: `jest.config.js` with ts-jest preset
+- Vitest: `vitest.config.ts` with test globals
+- pytest: `pytest.ini` or `pyproject.toml` section
+
+**4. Verify setup:**
+```bash
+# Run empty test suite - should pass with 0 tests
+npm test  # Node
+pytest    # Python
+go test ./...  # Go
+cargo test    # Rust
+```
+
+**5. Create first test file:**
+Follow project conventions for test location:
+- `*.test.ts` / `*.spec.ts` next to source
+- `__tests__/` directory
+- `tests/` directory at root
+
+Framework setup is a one-time cost included in the first TDD plan's RED phase.
+</framework_setup>
+
+<error_handling>
+## Error Handling
+
+**Test doesn't fail in RED phase:**
+- Feature may already exist - investigate
+- Test may be wrong (not testing what you think)
+- Fix before proceeding
+
+**Test doesn't pass in GREEN phase:**
+- Debug implementation
+- Don't skip to refactor
+- Keep iterating until green
+
+**Tests fail in REFACTOR phase:**
+- Undo refactor
+- Commit was premature
+- Refactor in smaller steps
+
+**Unrelated tests break:**
+- Stop and investigate
+- May indicate coupling issue
+- Fix before proceeding
+</error_handling>
+
+<commit_pattern>
+## Commit Pattern for TDD Plans
+
+TDD plans produce 2-3 atomic commits (one per phase):
+
+```
+test(08-02): add failing test for email validation
+
+- Tests valid email formats accepted
+- Tests invalid formats rejected
+- Tests empty input handling
+
+feat(08-02): implement email validation
+
+- Regex pattern matches RFC 5322
+- Returns boolean for validity
+- Handles edge cases (empty, null)
+
+refactor(08-02): extract regex to constant (optional)
+
+- Moved pattern to EMAIL_REGEX constant
+- No behavior changes
+- Tests still pass
+```
+
+**Comparison with standard plans:**
+- Standard plans: 1 commit per task, 2-4 commits per plan
+- TDD plans: 2-3 commits for single feature
+
+Both follow same format: `{type}({phase}-{plan}): {description}`
+
+**Benefits:**
+- Each commit independently revertable
+- Git bisect works at commit level
+- Clear history showing TDD discipline
+- Consistent with overall commit strategy
+</commit_pattern>
+
+<context_budget>
+## Context Budget
+
+TDD plans target **~40% context usage** (lower than standard plans' ~50%).
+
+Why lower:
+- RED phase: write test, run test, potentially debug why it didn't fail
+- GREEN phase: implement, run test, potentially iterate on failures
+- REFACTOR phase: modify code, run tests, verify no regressions
+
+Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
+
+Single feature focus ensures full quality throughout the cycle.
+</context_budget>