google-drive-content-adapter/specs/001-gdrive-url-header/plan.md

Implementation Plan: Google Drive Original URL Header

Branch: 001-gdrive-url-header | Date: 2026-03-27 | Spec: spec.md Input: Feature specification from /specs/001-gdrive-url-header/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/plan-template.md for the execution workflow.

Summary

Add HTTP response header X-Verint-KAB-Original-URL to all document export responses, containing the original Google Drive URL for traceability and auditing. The implementation will modify the existing proxy.js request handler to construct and include the Google Drive URL based on the document's file ID, ensuring consistent header presence across all export formats with minimal performance overhead (< 5ms).

Technical Context

Language/Version: Node.js 18+ (ES2022+ JavaScript, no TypeScript)
Primary Dependencies: axios (HTTP client), jsonwebtoken (JWT), xmlbuilder2 (XML generation), uuid (UUID generation)
Storage: N/A (stateless HTTP service)
Testing: node:test (native Node.js test runner)
Target Platform: Linux server / Docker container
Project Type: HTTP web service (Google Drive content adapter/proxy)
Performance Goals: < 5ms overhead per request, support concurrent requests without degradation
Constraints: Monolithic architecture (all business logic in src/proxyScripts/proxy.js), VM isolation via vm.Script, zero imports/exports in proxy.js
Scale/Scope: Single-purpose service handling document export requests with header addition

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Core Architecture Compliance

✅ Monolithic Architecture: Feature adds header logic within existing src/proxyScripts/proxy.js (no new files)
✅ Zero Imports/Exports: Implementation will modify proxy.js without introducing any imports or exports
✅ VM Isolation: Changes remain within existing vm.Script execution context
✅ Helper Extraction: URL construction is simple enough to stay in proxy.js (no helper extraction needed)

Dependency Budget

✅ No New Dependencies: Implementation uses existing capabilities (string formatting, existing Google Drive file ID access)
✅ Node.js Built-ins Preferred: Uses standard JavaScript string operations only

Testing Requirements

✅ TDD Workflow: Tests will be written before implementation
✅ 80% Coverage Target: New code will be covered by contract and unit tests
✅ Test Structure: Contract tests for header presence, unit tests for URL construction logic

API Contract Consistency

✅ Header Addition: Adding response header is non-breaking (clients can ignore unknown headers)
✅ No Breaking Changes: Does not modify existing response body or behavior
✅ Consistent Behavior: Header will be present on all export responses (success cases)

Security & Data Protection

✅ No Credentials Exposed: Google Drive URLs are public identifiers (file IDs), not sensitive data
✅ Input Validation: Will validate file ID format before constructing URL
✅ No New Attack Surface: Header value is constructed server-side, not from user input

Performance Impact

✅ < 5ms Overhead: String formatting and header assignment is negligible
✅ No Additional API Calls: Uses file ID already available from existing Drive API response
✅ No Memory Impact: Single string per request, immediately garbage collected

Result: ALL GATES PASS ✅

No constitutional violations. Feature aligns with all architectural principles and quality requirements.

Project Structure

Documentation (this feature)

specs/001-gdrive-url-header/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
│   └── response-headers.md  # HTTP response header contract
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

src/
├── proxyScripts/
│   └── proxy.js              # MODIFIED: Add X-Verint-KAB-Original-URL header logic
├── globalVariables/
│   ├── googleDriveAdapterHelper.js  # No changes (unless URL construction helper added)
│   └── google_drive_settings.json   # No changes
├── logger.js                 # No changes
└── server.js                 # No changes

tests/
├── contract/
│   └── response-headers.test.js     # NEW: Test header presence and format
├── integration/
│   └── header-integration.test.js   # NEW: Test with real Drive API responses
└── unit/
    └── url-construction.test.js     # NEW: Test URL construction logic

config/
└── default.json             # No changes (infrastructure only)

Structure Decision: All implementation changes confined to src/proxyScripts/proxy.js following the monolithic architecture principle. URL construction logic will be added inline within the export response handler. No new files needed except tests. The feature leverages existing Drive API file ID extraction and adds minimal header-setting logic.

Complexity Tracking

No constitutional violations identified. This section is not applicable.

---

Phase 1 Design Complete - Constitution Re-Check

Date: 2026-03-27
Status: ✅ ALL GATES PASS

Post-Design Validation

After completing research.md, data-model.md, contracts/, and quickstart.md, re-validation confirms:

✅ No New Architecture Concerns:

• Implementation location confirmed (proxy.js lines 377-383)
• URL construction is simple string interpolation
• No helper function needed

✅ No New Dependencies:

• Confirmed: only standard JavaScript operations
• No npm packages required
• No Node.js modules needed beyond what's already available

✅ API Contract Well-Defined:

• contracts/response-headers.md provides complete specification
• Header format: https://drive.google.com/file/d/{fileId}
• Presence rules clearly defined (success only)

✅ Testing Strategy Clear:

• Contract tests for header presence/format
• Integration tests with Drive API
• No unit tests needed (too simple)

✅ Performance Validated:

• Research confirms < 1ms overhead (well within 5ms requirement)
• Single string concatenation operation
• ~100 bytes memory per request

✅ Implementation Path Validated:

• Exact code location identified (proxy.js line 377 or 383)
• Uses validated document.id from API response
• Omits header on error paths (cleaner contract)

Final Result: Feature design passes all constitutional requirements. Ready for Phase 2 (task breakdown).

---

Next Steps

1. Run /speckit.tasks to generate actionable task breakdown (tasks.md)
2. Execute tasks via /speckit.implement or manual implementation
3. TDD workflow: Write tests first, then implement
4. Validate: Ensure all acceptance criteria from spec.md are met

---

Summary of Artifacts Generated

Artifact	Status	Description
plan.md	✅ Complete	This file - implementation plan and architecture
research.md	✅ Complete	Research findings for URL format, ID availability, header patterns
data-model.md	✅ Complete	Data flow and entity descriptions (HTTP header, URL construction)
contracts/response-headers.md	✅ Complete	API contract for X-Verint-KAB-Original-URL header
quickstart.md	✅ Complete	User guide with examples and client integration code
tasks.md	⏳ Pending	To be generated by /speckit.tasks command

Implementation Ready: All design artifacts complete. Feature is ready for task breakdown and implementation.