Auth Patterns

Auth Patterns — Authentication & Authorisation Guide

Purpose

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: middleware.ts Purpose: Route-level access control for pages and API preflight How it works: Creates a Supabase SSR client from cookies, calls getSession(), redirects unauthenticated users to /login.

Request → middleware.ts → Supabase SSR client → getSession()
  → Authenticated: pass through with security headers
  → Unauthenticated: redirect to /login

Key details:

• Runs in Edge Runtime (limited Node.js APIs)
• Sets security headers (CSP, HSTS, X-Frame-Options)
• 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.ts Purpose: 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.

const security = await APISecurityChecker.check(
  request,
  DEFAULT_POLICIES.AUTHENTICATED_WRITE
);
if (!security.allowed) {
  return APISecurityChecker.createSecureResponse(
    { error: security.error },
    security.error === 'Authentication required' ? 401 : 403
  );
}
const userId = security.context.userId;

Default policies:

• PUBLIC_READ — No auth required, rate limited
• AUTHENTICATED_READ — JWT required, read-only
• AUTHENTICATED_WRITE — JWT required, CSRF protection
• ADMIN_ONLY — JWT + admin role required

When to use: Every API route. No exceptions.

Layer 3: RBAC (Fine-Grained Permissions)

Files:

• lib/auth/rbac/permission-engine.ts — Permission matching with wildcards
• lib/auth/rbac/role-manager.ts — Role CRUD, user-role assignment
• lib/auth/rbac/access-control.ts — Middleware-style access control

Permission format: resource:action (e.g., posts:create, billing:manage)

Resources: posts, campaigns, analytics, personas, settings, users, roles, integrations, billing, organization

Actions: create, read, update, delete, manage, export, invite, approve

Wildcard: * grants all permissions (owner-level)

Fail-secure: On any error, access is denied. Never fails open.

When to use: Multi-tenant features where different team roles need different access levels within an organisation.

Layer 4: Owner Bypass

File: lib/auth/jwt-utils.ts (line 46-57) Purpose: Platform owner gets full access without Stripe or onboarding gates

import { isOwnerEmail } from '@/lib/auth/jwt-utils';

if (!isOwnerEmail(user.email)) {
  return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
}

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.ts Purpose: 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
• generatePKCEChallenge() — Returns { codeVerifier, codeChallenge, method: 'S256' }

Storage fallback chain: Redis → Database (OAuthPKCEState table) → In-memory

When to use: All OAuth flows for social platform connections.

OAuth Handler (Client-Side)

File: lib/auth/oauth-handler.ts Purpose: Unified client-side OAuth initiation for social login

Providers: Google, GitHub, Twitter, LinkedIn, Facebook

Pattern: Calls /api/auth/oauth/{provider}, receives redirect URL, handles errors with sonner toasts.

Common Mistakes

Environment Variables

File Index

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.