Authentication Flow

Relevant source files

The following files were used as context for generating this wiki page:

• web/lib/auth/providers/supabase.ts
• web/utils/supabase/middleware.ts
• web/app/auth/signin/page.tsx
• GEMINI.md
• README.md
• conductor/tracks.md

The Authentication Flow in hex-yt-intel is a centralized system designed to manage user identity and access control across the "Hybrid Edge" architecture. It primary relies on Supabase Auth as the sole authentication provider, following the removal of alternative patterns like next-auth to maintain high performance and bundle compression ratios.

The flow ensures that every request, whether to the Next.js frontend or the Cloudflare Worker streaming engine, is cryptographically verified and bound by atomic quota enforcement. This system is critical for securing "Vercel Bouncer" operations and protecting high-latency LLM synthesis routes.

Sources: GEMINI.md:38-41, README.md:20-25, conductor/tracks.md:14-18

System Architecture

The project utilizes a stratified authentication model where Supabase acts as the authority for user sessions. The architecture is defined by the "Vercel Bouncer" pattern, which handles high-security authentication checks before allowing access to long-running edge processes.

Core Authentication Components

Component	Responsibility
Supabase Auth	The exclusive authentication pattern for the project.
Vercel Bouncer	Executes atomic quota enforcement and security verification (~8s).
Middleware	Intercepts requests to refresh sessions and enforce access rules.
StreamToken	HMAC-signed tokens generated by Vercel to authorize Cloudflare Worker requests.

Sources: GEMINI.md:41, README.md:21-23, conductor/tracks.md:31-33

Authentication Lifecycle

The following diagram illustrates the sequence from user login to authorized edge execution:

The diagram shows how the Vercel Bouncer acts as a gateway, validating the Supabase session before issuing a secondary StreamToken for the edge.

Sources: GEMINI.md:41-45, README.md:21-25, conductor/tracks.md:31-35

Implementation Details

Server-Side Authentication

Authentication is enforced server-side using the getSupabaseClientWithAuth() pattern. This ensures that database interactions and sensitive route handling are protected by the native Supabase security perimeter.

// Pattern used for server-side auth enforcement
// Source: GEMINI.md:41
const supabase = getSupabaseClientWithAuth();

Hybrid Edge Security (ADR 005)

Under ADR 005 (Hybrid Edge Architecture), the system bridges two different cloud environments:

1. Vercel (The Authenticator): Authenticates the user and checks if they have enough credits (quota).
2. Cloudflare (The Executor): Receives a cryptographically signed StreamToken and validates the HMAC signature before starting the LLM synthesis.

This dual-layer approach prevents unauthorized access to expensive LLM resources and ensures that persistence endpoints only accept updates with valid content signatures.

Sources: README.md:21-25, GEMINI.md:105-110, conductor/tracks.md:31-36

Middleware and Session Management

Middleware is employed to maintain session persistence. It captures the user's session and ensures it is refreshed during the request lifecycle, preventing unexpected logouts during long synthesis sessions.

This flow ensures that session health is verified at the earliest possible stage of the request.

Sources: web/utils/supabase/middleware.ts, README.md:22, conductor/tracks.md:15

Security Mandates

The project enforces strict "Core Laws" regarding authentication and backend interactions:

• Law #1: Pre-Query Cache Hit Circuit: Before processing, the system must query Supabase analyses matching video_id and user_id to return cached results, saving token costs.
• Law #2: Stratified Dual-Timeouts: Authentication handshakes have a 3-second hard timeout to detect network faults early.
• HMAC Persistence: All S2S (Server-to-Server) /persist endpoint writes require a ContentSignature to prevent spoofed analysis data from entering the database.

Sources: GEMINI.md:82-90, README.md:24, conductor/tracks.md:34

Summary

The Authentication Flow of hex-yt-intel is a robust, multi-stage system that leverages Supabase for identity and HMAC signatures for cross-platform authorization. By separating the "Bouncer" logic on Vercel from the "Streaming" logic on Cloudflare, the architecture maintains high security and performance while overcoming standard serverless timeout limitations.