Authentication and authorisation pattern guide for SYNTHEX. Documents the four auth layers (Supabase session, JWT token, RBAC permissions, owner bypass), when to use each, and the common mistakes that cause auth drift. Use when creating or modifying any authenticated endpoint or middleware logic.
Authentication and authorisation pattern guide for SYNTHEX. Documents the four auth layers (Supabase session, JWT token, RBAC permissions, owner bypass), when to use each, and the common mistakes that cause auth drift. Use when creating or modifying any authenticated endpoint or middleware logic.
SYNTHEX has four distinct auth layers that serve different purposes. Using the
wrong layer (or mixing them) causes auth drift — the #1 source of security
bugs in the codebase.
This skill documents which layer to use, where the code lives, and the
common mistakes to avoid.
Auth Layer Decision Tree
Is this a Next.js middleware route guard?
YES → Use Supabase session (middleware.ts)
Is this an API route?
YES → Does it use APISecurityChecker?
YES → Use DEFAULT_POLICIES.AUTHENTICATED_READ or AUTHENTICATED_WRITE
NO → Is it a legacy route?
YES → Migrate to APISecurityChecker
NO → Use APISecurityChecker (never raw jwt.verify)
Does it need fine-grained permission checks?
YES → Use RBAC (permission-engine.ts + role-manager.ts)
Does it need to gate on platform ownership?
YES → Use isOwnerEmail() from jwt-utils.ts
Layer 1: Supabase Session (Middleware)
File:
Route-level access control for pages and API preflight
Creates a Supabase SSR client from cookies, calls ,
redirects unauthenticated users to .
middleware.ts
Purpose:
How it works:
getSession()
/login
Request → middleware.ts → Supabase SSR client → getSession()
→ Authenticated: pass through with security headers
→ Unauthenticated: redirect to /login
Handles API key gate via checkApiKeyGate() for /dashboard routes
Checks supabase-auth-token cookie fallback for unified login
When to use: Page-level route protection only. Never for API authorisation.
Layer 2: APISecurityChecker (API Routes)
File:lib/security/api-security-checker.tsPurpose: Standardised auth + validation + rate limiting for all API routes
How it works: Accepts a SecurityPolicy config, verifies JWT from
Authorization header, applies rate limits, validates input schema.
How it works: Checks email against OWNER_EMAILS ReadonlySet. Owners get
onboardingComplete: true and apiKeyConfigured: true in their JWT regardless
of DB state.
When to use: Admin-only endpoints (model refresh, platform credentials,
system configuration).
PKCE (OAuth Security)
File:lib/auth/pkce.tsPurpose: RFC 7636 implementation for secure OAuth 2.0 code exchange
Key functions:
generateCodeVerifier() — 32 bytes of crypto-random, base64url encoded
generateCodeChallenge() — SHA-256 hash of verifier
Reference skill: This is a read-only architecture guide — it documents existing systems and does not generate creative or code output. No capability uplift block is needed.
