Environment & Secret Management
Relevant source files
The following files were used as context for generating this wiki page:
- GEMINI.md
- CLAUDE.md
- README.md
- web/tests/production-verification.spec.ts
- AGENTS.md
- docs/ops/DEPLOYMENT.md (Referenced via GEMINI.md)
- docs/specs/SECURITY.md (Referenced via GEMINI.md)
The Environment & Secret Management system in hex-yt-intel is a mission-critical infrastructure component designed to secure the "Hybrid Edge Symphony" architecture. It governs the distribution and protection of sensitive credentials across Vercel, Cloudflare, and Supabase environments, ensuring that high-latency LLM synthesis and server-to-server data persistence remain tamper-proof.
The system emphasizes "Transcript Absolutism" and strict boundary enforcement, utilizing HMAC-based signatures for secure communication between distributed services. This setup prevents unauthorized database access while enabling direct browser-to-edge connections for performance.
Sources: README.md:15-22, CLAUDE.md:16-19, GEMINI.md:43-46
Hybrid Infrastructure Secret Distribution
The project operates across multiple cloud providers, requiring a stratified approach to environment variables. Secrets are categorized by their role in authentication, quota enforcement, and cryptographic signing.
Core Security Components
The following diagram illustrates how secrets flow between the primary infrastructure components to facilitate the secure synthesis pipeline.
The "Hybrid Edge Symphony" uses STREAM_HMAC_SECRET for verifying communication between Vercel and Cloudflare, while server-to-server (S2S) persistence relies on content signatures.
Sources: README.md:18-22, AGENTS.md:20-25, CLAUDE.md:16-19
Key Environment Variables
| Variable Name | Scope | Description |
|---|---|---|
STREAM_HMAC_SECRET | Vercel / Worker | Shared secret used to generate and verify cryptographically signed tokens for edge streaming. |
NEXT_PUBLIC_SUPABASE_URL | Web / Worker | Public endpoint for Supabase database interactions. |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Web | Public anonymous key for client-side Supabase initialization. |
SUPABASE_SERVICE_ROLE_KEY | Web (Server) | High-privilege key used in bouncers and S2S persistence endpoints. |
UPSTASH_REDIS_REST_URL | Web / Worker | Endpoint for Upstash Redis, used for rate limiting and quota enforcement. |
DEV_BYPASS_TOKEN | Testing | Secret token used to bypass certain gates during Playwright production verification. |
Sources: CLAUDE.md:40-44, AGENTS.md:21, web/tests/production-verification.spec.ts:4, GEMINI.md:118-120
Cryptographic Signing and Persistence
A cornerstone of the secret management strategy is the use of Hash-based Message Authentication Codes (HMAC) to secure data persistence. This prevents "toe-stepping" or unauthorized data injection from external sources.
S2S Persistence Flow
The /api/analyses/persist endpoint is hardened using verifyContentSig, a function that ensures the incoming data has not been tampered with since leaving the Cloudflare Worker.
Sources: AGENTS.md:20-30, README.md:22, CLAUDE.md:16-19
Security Verification and Anti-Leak Protocols
The project maintains strict protocols to prevent the accidental exposure of environment variables or secrets in client-side code or public documentation.
Automated Verification Guards
Production verification tests specifically check for unpolyfilled environment variables in the rendered HTML to ensure process.env references do not leak to the browser.
Sources: web/tests/production-verification.spec.ts:48-53
// Example of a leak prevention check in production tests
const html = await page.content();
expect(html).not.toContain('process.env.NEXT_PUBLIC_SUPABASE_URL');
expect(html).not.toContain('process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY');
Sources: web/tests/production-verification.spec.ts:50-52
Root Directory Volume Restrictions
To maintain a high signal-to-noise ratio and prevent configuration sprawl, the repository root is restricted to a maximum of 4 Markdown files. All other documentation, including sensitive runbooks and secret rotation guides, must be nested in designated /docs/ sub-directories.
Sources: GEMINI.md:32-35, conductor/tracks.md:11-13
Secret Rotation and Lifecycle
Operational guides located in /docs/ops/ (such as REDIS_SETUP.md and VERCEL_ENV_SETUP.md) document the requirements for manual steps and secret rotation. The system utilizes pnpm type-check and pnpm build as quality gates to verify that environment configurations are valid before deployment.
Sources: GEMINI.md:43-46, conductor/tracks.md:15-18
Verification Checklist
Before every code mutation or pipeline operation, agents must verify:
git status: Confirming nothing uncommitted from other agents..memory/AGENT_LEDGER.md: Ensuring no concurrent secret modifications..vercelignore: Checking that ignore rules prevent secret leakage during deployment.
Sources: GEMINI.md:73-95, AGENTS.md:43-48
Conclusion
Environment and secret management in hex-yt-intel is centered on the principle of "Hybrid Edge Symphony" security. By combining HMAC-verified persistence, strict root-level file constraints, and automated production verification tests, the system ensures that sensitive credentials for Supabase, Cloudflare, and Upstash remain protected while facilitating high-performance content intelligence.