mcp-quickbase 2.0.5 → 2.2.0

package/.sdd/tickets/RELS_relationship-management/planning/quality-strategy.md

@@ -0,0 +1,335 @@
+# Quality Strategy: Relationship Management
+
+## Testing Philosophy
+
+This feature follows enterprise-grade testing principles with comprehensive coverage of both happy paths and error scenarios. Given the destructive nature of the delete operation, testing must verify that tool descriptions accurately communicate risks and that error handling prevents unintended data loss.
+
+Testing priorities:
+1. **Critical paths** - All CRUD operations must work correctly
+2. **Error handling** - API errors, validation errors, and edge cases
+3. **Safety verification** - Delete tool description contains required warnings
+4. **Integration** - Tools register correctly and are callable through MCP
+
+## Coverage Requirements
+
+**Minimum Thresholds (from jest.config.js):**
+- Line coverage: 40%
+- Function coverage: 40%
+- Statement coverage: 40%
+- Branch coverage: 20%
+
+**Target Thresholds:**
+- Line coverage: 80% for new relationship tools
+- Branch coverage: 70% for new relationship tools
+
+**Note:** The minimum thresholds are enforced by jest.config.js and represent hard requirements. The target thresholds are aspirational goals for new relationship tool code quality.
+
+**Coverage Focus Areas:**
+- All tool `run()` methods
+- Parameter validation paths
+- Error handling branches
+- Response transformation logic
+
+## Test Types
+
+### Unit Tests
+
+**Scope:** Individual tool classes with mocked QuickbaseClient
+
+**Tools:** Jest with ts-jest
+
+**Coverage Target:** >= 80% for new code
+
+**What to Test:**
+
+1. **Tool Properties**
+   - Correct `name` value
+   - Description is non-empty string
+   - `paramSchema` is valid JSON Schema object
+
+2. **Happy Path Execution**
+   - Successful API responses transformed correctly
+   - All response fields mapped properly
+   - Metadata included in results
+
+3. **Parameter Validation**
+   - Required parameters validated
+   - Invalid parameter types rejected
+   - Optional parameters handled correctly
+
+4. **Error Handling**
+   - API errors (4xx, 5xx) handled gracefully
+   - Network errors caught and reported
+   - Validation errors include helpful messages
+
+5. **Edge Cases**
+   - Empty relationship lists
+   - Relationships with no lookup/summary fields
+   - Large relationship counts (pagination)
+
+### Integration Tests
+
+**Scope:** Tool registration and end-to-end execution flow
+
+**Approach:** Test that tools are registered and callable through the registry
+
+**What to Test:**
+- All four tools appear in `toolRegistry.getAllTools()`
+- Tools can be retrieved by name via `toolRegistry.getTool()`
+- Execute returns proper `ApiResponse` structure
+
+### End-to-End Tests
+
+**Scope:** Not required for initial release
+
+**Note:** E2E tests against real Quickbase API would require test credentials and are deferred to future work.
+
+## Critical Paths
+
+The following paths MUST have comprehensive test coverage:
+
+### 1. Get Relationships
+
+**Happy Path:**
+- Returns array of relationships with complete structure
+- Pagination works (skip parameter honored)
+- Empty array returned for tables with no relationships
+
+**Error Cases:**
+- Table not found (404)
+- Unauthorized (401)
+- Forbidden (403)
+- Network error
+
+**Edge Cases:**
+- Table with many relationships (pagination needed)
+- Cross-app relationships have limited details
+
+### 2. Create Relationship
+
+**Happy Path:**
+- Basic relationship creation (parent + child only)
+- With lookup field IDs
+- With summary field (all accumulation types)
+- With both lookup and summary fields
+
+**Error Cases:**
+- Parent table not found
+- Invalid field IDs for lookups
+- Missing accumulation type when summary_field_id provided (must be validated via JSON Schema)
+- Tables in different apps
+
+**Edge Cases:**
+- Creating relationship that already exists
+- Summary field with WHERE filter
+
+### 3. Update Relationship
+
+**Happy Path:**
+- Add lookup fields to existing relationship
+- Add summary field to existing relationship
+- Add both lookup and summary fields
+
+**Error Cases:**
+- Relationship not found
+- Invalid lookup field IDs
+- Missing accumulation type when summary_field_id provided (must be validated via JSON Schema)
+
+**Edge Cases:**
+- Adding fields that already exist (additive behavior)
+- Empty update (no fields to add)
+
+### 4. Delete Relationship (CRITICAL - Extra Coverage Required)
+
+**Happy Path:**
+- Successful deletion returns relationship ID
+- All lookup/summary fields deleted
+
+**Error Cases:**
+- Relationship not found (404)
+- Unauthorized (401)
+- Forbidden (403)
+
+**Safety Verification:**
+- Tool description contains "WARNING"
+- Tool description contains "DESTRUCTIVE"
+- Tool description mentions lookup fields deletion
+- Tool description mentions summary fields deletion
+- Tool description mentions data loss is permanent
+- Tool description recommends `get_relationships` first
+- Tool description recommends user confirmation
+
+## Negative Testing Requirements
+
+### Invalid Inputs
+
+| Test Case | Input | Expected |
+|-----------|-------|----------|
+| Empty table_id | `""` | Validation error |
+| Missing table_id | `undefined` | Validation error |
+| Invalid table_id type | `123` (number) | Validation error |
+| Empty relationship_id (for update/delete) | `undefined` | Validation error |
+| Invalid accumulation_type | `"INVALID"` | API error or validation error |
+| Non-numeric field IDs | `["abc"]` | Validation error |
+
+### API Error Handling
+
+| Status Code | Scenario | Expected Behavior |
+|-------------|----------|-------------------|
+| 400 | Bad request | Return error with message |
+| 401 | Invalid token | Return auth error |
+| 403 | No permission | Return forbidden error |
+| 404 | Not found | Return not found error |
+| 429 | Rate limited | Retry (handled by client) |
+| 500 | Server error | Return server error |
+
+### Authorization Failures
+
+- Test with invalid/expired token (mocked)
+- Test access to table without permissions (mocked)
+
+### Resource Not Found
+
+- Non-existent table ID
+- Non-existent relationship ID
+- Non-existent parent table ID
+
+## Test Data Strategy
+
+### Mocking Approach
+
+All tests use mocked `QuickbaseClient`:
+
+```typescript
+jest.mock('../../client/quickbase');
+
+const mockClient = new QuickbaseClient(config) as jest.Mocked<QuickbaseClient>;
+mockClient.request = jest.fn().mockResolvedValue(mockResponse);
+```
+
+### Mock Response Templates
+
+```typescript
+// Relationship structure
+const mockRelationship = {
+  id: 123,
+  parentTableId: 'parent-table-id',
+  childTableId: 'child-table-id',
+  foreignKeyField: {
+    id: 123,
+    label: 'Related Parent',
+    type: 'numeric'
+  },
+  isCrossApp: false,
+  lookupFields: [
+    { id: 456, label: 'Parent Name', type: 'text' }
+  ],
+  summaryFields: [
+    { id: 789, label: 'Child Count', type: 'numeric' }
+  ]
+};
+
+// Get relationships response
+const mockGetResponse = {
+  success: true,
+  data: {
+    relationships: [mockRelationship],
+    metadata: {
+      totalRelationships: 1,
+      numRelationships: 1,
+      skip: 0
+    }
+  }
+};
+
+// Create/Update response
+const mockCreateResponse = {
+  success: true,
+  data: mockRelationship
+};
+
+// Delete response
+const mockDeleteResponse = {
+  success: true,
+  data: {
+    relationshipId: 123
+  }
+};
+
+// Error response
+const mockErrorResponse = {
+  success: false,
+  error: {
+    message: 'Table not found',
+    code: 404,
+    type: 'NotFoundError'
+  }
+};
+```
+
+## Quality Gates
+
+Before verification, all items must be checked:
+
+### Code Quality
+
+- [ ] All unit tests pass (`npm test`)
+- [ ] Coverage thresholds met (40% lines/functions/statements, 20% branches per jest.config.js)
+- [ ] No linting errors (`npm run lint`)
+- [ ] No TypeScript errors (`npm run build`)
+
+### Functional Completeness
+
+- [ ] All four tools implemented
+- [ ] All tools registered in toolRegistry
+- [ ] Parameter schemas match implementation
+- [ ] Response types match API responses
+
+### Critical Path Coverage
+
+- [ ] Get relationships: happy path + errors
+- [ ] Create relationship: all parameter combinations
+- [ ] Update relationship: additive behavior verified
+- [ ] Delete relationship: all error cases
+
+### Safety Verification
+
+- [ ] Delete tool description starts with WARNING
+- [ ] Delete tool description mentions DESTRUCTIVE
+- [ ] Delete tool description lists what is deleted
+- [ ] Delete tool description states data is permanent
+- [ ] Delete tool description recommends confirmation
+
+### Edge Cases
+
+- [ ] Empty results handled
+- [ ] Pagination works
+- [ ] Missing optional fields handled
+- [ ] API error messages preserved
+
+## Test File Organization
+
+```
+src/__tests__/tools/
+  relationships.test.ts           # All relationship tool tests
+    - describe('GetRelationshipsTool')
+      - describe('tool properties')
+      - describe('execute - success')
+      - describe('execute - errors')
+      - describe('execute - edge cases')
+    - describe('CreateRelationshipTool')
+      - describe('tool properties')
+      - describe('execute - success')
+      - describe('execute - errors')
+      - describe('validation')
+    - describe('UpdateRelationshipTool')
+      - describe('tool properties')
+      - describe('execute - success')
+      - describe('execute - errors')
+      - describe('additive behavior')
+    - describe('DeleteRelationshipTool')
+      - describe('tool properties')
+      - describe('tool description safety')  # CRITICAL
+      - describe('execute - success')
+      - describe('execute - errors')
+```

package/.sdd/tickets/RELS_relationship-management/planning/review-updates.md

@@ -0,0 +1,95 @@
+# Ticket Review Updates
+
+**Original Review Date:** 2025-12-28
+**Updates Completed:** 2025-12-28
+**Update Status:** Complete
+
+## Summary
+
+| Category | Issues Found | Issues Fixed |
+|----------|--------------|--------------|
+| Critical Issues | 0 | 0 |
+| Boundary Violations | 0 | 0 |
+| High-Risk Areas | 3 | 3 |
+| Gaps & Ambiguities | 5 | 3 |
+| Ticket Issues | 0 | 0 |
+
+## High-Risk Areas Addressed
+
+### Risk 1: API Response Structure Assumption (Low-Medium Risk)
+**Original Problem:** TypeScript interfaces based on documentation rather than live API testing. If actual API responses differ, tools may fail or return incorrect data.
+
+**Changes Made:**
+- **plan.md Phase 1**: Added explicit acceptance criterion requiring API response structure validation against TypeScript interfaces before proceeding to Phase 2
+- **plan.md Phase 1 deliverables**: Added task to validate actual API responses match documented interfaces
+
+**Result:** Phase 1 now includes explicit validation step to catch any documentation discrepancies early.
+
+### Risk 2: Test Coverage Threshold Discrepancy (Low Risk)
+**Original Problem:** Discrepancy between documented thresholds:
+- jest.config.js: 40% lines/functions/statements, 20% branches
+- quality-strategy.md: 35% minimum
+- plan.md: >= 35%
+
+**Changes Made:**
+- **quality-strategy.md**: Updated minimum thresholds to match jest.config.js exactly (40% lines/functions/statements, 20% branches)
+- **quality-strategy.md**: Clarified that 40% is the hard requirement from jest.config.js, with 80% as aspirational target for new relationship tools
+- **plan.md Phase 3**: Updated acceptance criteria from >= 35% to >= 40% for consistency
+- **plan.md Phase 4**: Updated acceptance criteria to reference jest.config.js thresholds (40% lines/functions/statements, 20% branches)
+
+**Result:** All documents now consistently reference jest.config.js as the authoritative source for coverage thresholds.
+
+### Risk 3: Conditional JSON Schema Validation for Summary Fields
+**Original Problem:** `summary_accumulation_type` documented as "Required if summary_field_id" but JSON Schema validation rules not explicitly defined.
+
+**Changes Made:**
+- **architecture.md CreateRelationshipParams**: Added explicit note about conditional validation requirement
+- **architecture.md UpdateRelationshipParams**: Added explicit note about conditional validation requirement
+- **plan.md Phase 2**: Added acceptance criterion to validate that summary field parameters enforce accumulation type requirement
+- **quality-strategy.md**: Added test case for missing accumulation type when summary_field_id is provided
+
+**Result:** Implementation requirements now explicitly state that JSON Schema must enforce conditional validation.
+
+## Gaps Filled
+
+### Gap 1: Cross-App Relationship Handling
+**Status:** Acknowledged as implementation-phase concern
+**Action:** No planning document changes needed; implementation will handle error messages as recommended in review
+
+### Gap 2: Relationship Field Type Validation
+**Status:** Acknowledged as implementation-phase concern
+**Action:** quality-strategy.md already includes tests for invalid field IDs
+
+### Gap 3: Summary Field Accumulation Type Validation
+**Status:** Fixed (see Risk 3 above)
+
+### Ambiguity 1: Reference Field Deletion Behavior
+**Changes Made:**
+- **architecture.md DeleteRelationshipTool description**: Enhanced to explicitly note that reference field remains and may need manual deletion
+
+**Result:** Tool description now clarifies cleanup steps after relationship deletion.
+
+### Ambiguity 2: Pagination Implementation
+**Changes Made:**
+- **plan.md Phase 1**: Added acceptance criterion to verify actual pagination behavior during implementation
+
+**Result:** Phase 1 will validate whether API supports limit parameter and adjust if needed.
+
+## Document Change Summary
+
+| Document | Lines Modified | Key Changes |
+|----------|----------------|-------------|
+| quality-strategy.md | ~8 | Updated coverage thresholds to match jest.config.js (40/40/40/20); added conditional validation test case |
+| architecture.md | ~6 | Added conditional validation notes to CreateRelationshipParams and UpdateRelationshipParams; enhanced DeleteRelationshipTool description |
+| plan.md | ~8 | Added API response validation to Phase 1; added conditional validation to Phase 2; updated Phase 3 and Phase 4 coverage thresholds; added pagination verification to Phase 1 |
+| analysis.md | 0 | No changes needed |
+| security-review.md | 0 | No changes needed |
+
+## Verification
+
+**Re-review Recommended:** Yes
+**Expected Result:** All low and low-medium risks should now be resolved
+
+## Next Steps
+1. Run `/sdd:review RELS_relationship-management` to verify all issues addressed
+2. If passes, proceed to `/sdd:create-tasks RELS_relationship-management`

package/.sdd/tickets/RELS_relationship-management/planning/security-review.md

@@ -0,0 +1,213 @@
+# Security Review: Relationship Management
+
+## Security Assessment
+
+### Authentication & Authorization
+
+**How Auth is Handled:**
+
+Authentication for all relationship operations flows through the existing `QuickbaseClient` which:
+
+1. Uses `QB-USER-TOKEN` header for authentication
+2. Uses `QB-Realm-Hostname` header to identify the target realm
+3. Token is provided via environment variable (`QUICKBASE_USER_TOKEN`)
+4. Token is never logged (redacted in all logging)
+
+**Authorization Model:**
+
+- Quickbase API enforces role-based permissions at the API level
+- Users can only access/modify relationships in tables they have permission to
+- The MCP server does not add additional authorization layers
+- Permission errors (403) are passed through to the agent
+
+**Security Considerations:**
+
+- Token stored in environment variables (standard practice)
+- No token validation performed client-side (delegated to Quickbase API)
+- All authorization errors from API are surfaced clearly
+
+### Data Protection
+
+**Sensitive Data Handling:**
+
+| Data Type | Protection Method |
+|-----------|-------------------|
+| User Token | Redacted in logs, stored in env var |
+| Realm Hostname | Partially redacted in logs |
+| Table IDs | Not considered sensitive, logged for debugging |
+| Relationship IDs | Not considered sensitive, logged for debugging |
+| Field Labels | Not considered sensitive |
+
+**Data in Transit:**
+
+- All API calls use HTTPS (enforced by QuickbaseClient base URL)
+- TLS/SSL certificate validation handled by Node.js fetch
+
+**Data at Rest:**
+
+- Response caching in memory only (CacheService)
+- No persistent storage of relationship data
+- Cache has configurable TTL (default 3600s)
+
+### Input Validation
+
+**Validation Approach:**
+
+All tools use the existing `BaseTool.validateParams()` method which:
+
+1. Validates against JSON Schema (`paramSchema`)
+2. Uses Zod for runtime type checking
+3. Provides descriptive error messages
+
+**Parameter Validation Rules:**
+
+| Parameter | Validation | Risk if Bypassed |
+|-----------|------------|------------------|
+| `table_id` | Required string | API error (400) |
+| `relationship_id` | Required number for update/delete | API error (400) |
+| `parent_table_id` | Required string for create | API error (400) |
+| `lookup_field_ids` | Optional array of numbers | API error if invalid |
+| `summary_accumulation_type` | Optional string | API error if invalid |
+
+**Injection Prevention:**
+
+- Parameters are passed as JSON body/query params
+- No string interpolation in SQL/query contexts
+- Quickbase API handles all query parsing
+
+### Known Gaps
+
+| Gap | Risk Level | Mitigation | Status |
+|-----|------------|------------|--------|
+| No rate limiting beyond API defaults | Low | Quickbase API has its own rate limiting; client has 10 req/sec default | Accepted |
+| Delete operation is irreversible | High | Tool description strongly warns agent; recommends user confirmation | Mitigated |
+| No role-based access control in MCP server | Medium | Relies on Quickbase API permissions; MCP server is trusted middleware | Accepted |
+| Cached relationship data may become stale | Low | Cache TTL limits staleness; operations can use `skipCache` | Accepted |
+| No audit logging of destructive operations | Medium | Quickbase API maintains audit trail; consider future enhancement | Deferred |
+
+## Initial Release Security Scope
+
+### In Scope
+
+- **Input Validation**: All parameters validated before API calls
+- **Error Handling**: API errors returned without sensitive data leakage
+- **Token Protection**: User token never exposed in logs or error messages
+- **HTTPS Enforcement**: All API calls over TLS
+- **Agent Safety**: Delete operation clearly marked as destructive
+
+### Out of Scope (Future Phases)
+
+- **Audit Logging**: Detailed logging of who requested what operations
+- **Additional Authorization**: Role-based restrictions beyond Quickbase API
+- **Dry-Run Mode**: Preview what would be deleted before actual deletion
+- **Undo/Recovery**: Ability to recover deleted relationships
+- **Rate Limiting UI**: Visibility into remaining API quota
+
+## Destructive Operation Security
+
+### Delete Relationship Risk Assessment
+
+**Risk:** Agents may delete relationships without understanding consequences, causing permanent data loss.
+
+**Impact:**
+- All lookup fields associated with relationship are deleted
+- All summary fields associated with relationship are deleted
+- Data in deleted fields is permanently lost
+- Cannot be recovered without Quickbase backup restore
+
+**Mitigations Implemented:**
+
+1. **Tool Description Warning**
+   ```
+   WARNING: DESTRUCTIVE OPERATION - Permanently deletes an entire
+   table-to-table relationship INCLUDING ALL LOOKUP AND SUMMARY FIELDS
+   associated with it. All data in those fields will be permanently
+   lost and CANNOT be recovered.
+   ```
+
+2. **Guidance for Safe Usage**
+   - Recommends using `get_relationships` first to review impact
+   - Recommends confirming with user before proceeding
+   - Suggests deleting individual fields instead if relationship should remain
+
+3. **No Automatic Execution**
+   - Agent must explicitly call the delete tool
+   - Human-in-the-loop confirmation recommended in description
+
+### Comparison with Other Delete Operations
+
+| Operation | Destructiveness | Current Mitigation | Recommendation |
+|-----------|-----------------|--------------------|--------------------|
+| Delete Record | Medium | Standard tool description | None needed |
+| Delete Field | High | Standard tool description | Consider adding warning |
+| Delete Table | Very High | Standard tool description | Consider adding warning |
+| Delete Relationship | High | WARNING in description | Implemented |
+| Delete App | Critical | Standard tool description | Strongly recommend warning |
+
+## Security Checklist
+
+### Code Security
+
+- [x] No hardcoded secrets (tokens from env vars)
+- [x] Input validation on all external inputs (BaseTool handles)
+- [x] Proper error handling without info leakage (existing pattern)
+- [x] Dependencies reviewed (existing deps, no new ones)
+- [x] No SQL injection vulnerabilities (N/A - JSON API)
+- [x] No XSS vulnerabilities (N/A - not a web UI)
+
+### API Security
+
+- [x] HTTPS enforced for all API calls
+- [x] Auth token properly passed in headers
+- [x] Auth token never logged
+- [x] API errors handled without token exposure
+- [x] Rate limiting in place (client default)
+
+### Agent Safety
+
+- [x] Destructive operations clearly labeled
+- [x] Delete tool warns about permanent data loss
+- [x] Delete tool lists what will be deleted
+- [x] Delete tool recommends confirmation workflow
+- [x] Non-destructive tools indicate they are safe
+
+## Security Testing Requirements
+
+### Authentication Tests
+
+- [ ] Verify token is not present in any log output
+- [ ] Verify 401 errors are handled gracefully
+- [ ] Verify 403 errors return permission-denied message
+
+### Input Validation Tests
+
+- [ ] Test with malformed table IDs
+- [ ] Test with injection attempts in string parameters
+- [ ] Test with oversized payloads
+
+### Error Handling Tests
+
+- [ ] Verify error messages don't contain token
+- [ ] Verify error messages don't contain realm details beyond necessary
+- [ ] Verify network errors don't leak internal details
+
+### Destructive Operation Tests
+
+- [ ] Verify delete tool description contains required warnings
+- [ ] Test delete returns clear confirmation of what was deleted
+- [ ] Test delete errors don't suggest partial completion without clarity
+
+## Recommendations
+
+### Immediate (This Release)
+
+1. **Implement comprehensive tool descriptions** - Done in design
+2. **Follow existing security patterns** - Using BaseTool, QuickbaseClient
+3. **Test error handling** - Ensure no sensitive data in errors
+
+### Future Enhancements
+
+1. **Audit Logging**: Add structured logging for relationship operations with timestamp, user (if available), and action
+2. **Dry-Run Mode**: Consider `--dry-run` or preview parameter for delete
+3. **Confirmation Token**: For extra safety, require a confirmation parameter for delete operations
+4. **Rate Limit Visibility**: Expose remaining API quota in responses