@edcalderon/auth 1.3.0 → 1.4.1

package/docs/provisioning-model.md

@@ -0,0 +1,416 @@
+# Provisioning Model
+
+> **Package:** `@edcalderon/auth/authentik` (v1.4.0+)
+> **Runtime:** Server-side only (requires `service_role` key)
+
+This document describes the Authentik-to-Supabase user provisioning model — a first-class path for ensuring every Authentik-authenticated user exists in your application's local user store before they can access protected resources.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Three-Layer Identity Model](#three-layer-identity-model)
+3. [Identity-First Match Strategy](#identity-first-match-strategy)
+4. [Provisioning Adapter Interface](#provisioning-adapter-interface)
+5. [SupabaseSyncAdapter](#supabasesyncadapter)
+6. [Rollback Behavior](#rollback-behavior)
+7. [SQL Migrations](#sql-migrations)
+8. [Runtime Requirements](#runtime-requirements)
+9. [Startup Validation](#startup-validation)
+
+---
+
+## Overview
+
+The provisioning model is **fail-closed**: if user sync fails, the callback handler does not redirect the user into the protected app. This ensures no user can access the application without a corresponding local user record.
+
+The `SupabaseSyncAdapter` is the production-grade adapter that implements the full CIG-proven sync flow:
+
+1. Normalize the OIDC payload (lowercase email, resolve name from claims)
+2. Ensure a shadow `auth.users` record exists (identity-first matching)
+3. Call `upsert_oidc_user()` RPC to sync into `public.users`
+4. Link the shadow auth user via `link_shadow_auth_user()` RPC
+5. Roll back on failure (delete newly created shadow records)
+
+---
+
+## Three-Layer Identity Model
+
+The provisioning system uses a three-layer identity architecture:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Layer 1: Authentik                      │
+│                                                            │
+│  The upstream OIDC identity provider. Users authenticate   │
+│  here via social login (Google, GitHub, Discord, etc.)     │
+│  or direct Authentik credentials.                          │
+│                                                            │
+│  Identity key: (sub, iss)                                  │
+│  ┌─────────────────────────────────────────────────┐       │
+│  │ sub: "google-oauth2|12345"                      │       │
+│  │ iss: "https://auth.example.com/application/o/…" │       │
+│  │ email: "user@example.com"                       │       │
+│  │ name: "Jane Doe"                                │       │
+│  └─────────────────────────────────────────────────┘       │
+└──────────────────────┬───────────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│                 Layer 2: public.users                      │
+│                                                            │
+│  Application-owned user table. This is the canonical       │
+│  user record for your app's business logic, RLS            │
+│  policies, and authorization.                              │
+│                                                            │
+│  Primary key: id (uuid)                                    │
+│  Unique key: (sub, iss)                                    │
+│  ┌─────────────────────────────────────────────────┐       │
+│  │ id: "uuid-abc-123"                              │       │
+│  │ sub: "google-oauth2|12345"                      │       │
+│  │ iss: "https://auth.example.com/application/o/…" │       │
+│  │ email: "user@example.com"                       │       │
+│  │ shadow_auth_user_id: "uuid-def-456" (optional)  │       │
+│  └─────────────────────────────────────────────────┘       │
+└──────────────────────┬───────────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│          Layer 3: auth.users (Shadow — Optional)          │
+│                                                            │
+│  Supabase's built-in auth.users table. A "shadow"          │
+│  record mirrors the Authentik identity so that Supabase    │
+│  RLS policies, storage rules, and realtime subscriptions   │
+│  work out of the box.                                      │
+│                                                            │
+│  ┌─────────────────────────────────────────────────┐       │
+│  │ id: "uuid-def-456"                              │       │
+│  │ email: "user@example.com"                       │       │
+│  │ app_metadata: {                                 │       │
+│  │   provider: "authentik",                        │       │
+│  │   oidc_sub: "google-oauth2|12345",              │       │
+│  │   oidc_issuer: "https://auth.example.com/…"     │       │
+│  │ }                                               │       │
+│  └─────────────────────────────────────────────────┘       │
+└──────────────────────────────────────────────────────────┘
+```
+
+**Why three layers?**
+
+- **Layer 1 (Authentik)** handles authentication — "who are you?"
+- **Layer 2 (`public.users`)** is your app's source of truth — "what can you do?"
+- **Layer 3 (`auth.users` shadow)** enables Supabase-native features (RLS, storage, realtime) without requiring users to sign up through Supabase Auth directly.
+
+The shadow layer is **optional** (controlled by `createShadowAuthUser` config, default: `true`). If your app does not use Supabase RLS or storage features, you can disable it.
+
+---
+
+## Identity-First Match Strategy
+
+The adapter uses a two-tier matching strategy when looking for existing user records:
+
+### Priority 1: OIDC Identity Match (sub + iss)
+
+```
+app_metadata.auth_source === "authentik"
+  AND app_metadata.oidc_sub === payload.sub
+  AND app_metadata.oidc_issuer === payload.iss
+```
+
+This is the **primary** and **safest** match. The OIDC `sub` claim is immutable for a given user at a given issuer. It cannot be changed by the user.
+
+### Priority 2: Email Fallback
+
+If no identity match is found, the adapter falls back to matching by email address:
+
+```
+user.email.toLowerCase() === payload.email.toLowerCase()
+```
+
+This handles the case where a shadow `auth.users` record already exists (e.g. from a previous Supabase Auth signup) but hasn't been linked to an Authentik identity yet. When matched by email, the adapter **updates** the record to include the OIDC identity markers.
+
+### Why Identity-First?
+
+Email-based matching alone is risky:
+- Users can change their email at the upstream provider
+- Different providers might have different emails for the same person
+- Email conflicts could lead to unauthorized access
+
+By matching on `(oidc_sub, oidc_issuer)` first, the adapter prevents these scenarios. Email fallback exists only as a migration path for pre-existing records.
+
+### Pagination
+
+The adapter paginates through **all** `auth.users` pages (1000 users per page) to ensure matches beyond the first page are not missed. This is critical for larger Supabase projects.
+
+---
+
+## Provisioning Adapter Interface
+
+All provisioning adapters implement the `ProvisioningAdapter` interface:
+
+```ts
+interface ProvisioningAdapter {
+  sync(payload: ProvisioningPayload): Promise<ProvisioningResult>;
+}
+```
+
+### ProvisioningPayload
+
+The input to every adapter:
+
+```ts
+interface ProvisioningPayload {
+  /** OIDC subject identifier. */
+  sub: string;
+  /** OIDC issuer URL. */
+  iss: string;
+  /** User email (normalized to lowercase). */
+  email: string;
+  /** Whether the email is verified by the OIDC provider. */
+  emailVerified?: boolean;
+  /** Display name. */
+  name?: string;
+  /** Avatar / profile picture URL. */
+  picture?: string;
+  /** Upstream social provider slug (e.g. "google", "github"). */
+  provider?: string;
+  /** The full set of OIDC claims as received from Authentik. */
+  rawClaims?: Record<string, unknown>;
+}
+```
+
+### ProvisioningResult
+
+The output from every adapter:
+
+```ts
+interface ProvisioningResult {
+  /** Must be true for the callback to proceed with redirect. */
+  synced: boolean;
+  /** The app-level user ID (from public.users or equivalent). */
+  appUserId?: string;
+  /** Supabase auth.users ID when shadow-user mode is used. */
+  authUserId?: string;
+  /** Whether a new shadow auth.users row was created. */
+  authUserCreated?: boolean;
+  /** Whether an existing shadow auth.users row was updated. */
+  authUserUpdated?: boolean;
+  /** Human-readable diagnostic on failure. */
+  error?: string;
+  /** Machine-readable error code. */
+  errorCode?: string;
+}
+```
+
+The `synced` flag is the gating condition: the callback handler will **not** redirect the user unless `synced === true`.
+
+### Built-in Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `NoopProvisioningAdapter` | No user sync needed — always returns `{ synced: true }` |
+| `createProvisioningAdapter(fn)` | Custom sync logic via a plain function |
+| `SupabaseSyncAdapter` | Full Authentik ↔ Supabase integrated sync |
+
+---
+
+## SupabaseSyncAdapter
+
+The `SupabaseSyncAdapter` is the production-grade adapter for Authentik ↔ Supabase integration:
+
+```ts
+import { createClient } from "@supabase/supabase-js";
+import { createSupabaseSyncAdapter } from "@edcalderon/auth/authentik";
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+);
+
+const adapter = createSupabaseSyncAdapter(supabase, {
+  supabaseUrl: process.env.SUPABASE_URL!,
+  supabaseServiceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  // Optional overrides:
+  createShadowAuthUser: true,      // default: true
+  rollbackOnFailure: true,          // default: true
+  upsertRpcName: "upsert_oidc_user",       // default
+  linkShadowRpcName: "link_shadow_auth_user", // default
+});
+```
+
+### Configuration (SupabaseSyncConfig)
+
+```ts
+interface SupabaseSyncConfig {
+  /** Supabase project URL. */
+  supabaseUrl: string;
+  /** Supabase service_role key (server-side only). */
+  supabaseServiceRoleKey: string;
+  /** RPC name for upserting into public.users. Default: "upsert_oidc_user". */
+  upsertRpcName?: string;
+  /** RPC name for linking shadow auth user. Default: "link_shadow_auth_user". */
+  linkShadowRpcName?: string;
+  /** Whether to create a shadow auth.users record. Default: true. */
+  createShadowAuthUser?: boolean;
+  /** Default OIDC issuer when payload.iss is not provided. */
+  defaultIssuer?: string;
+  /** Whether to rollback on failure. Default: true. */
+  rollbackOnFailure?: boolean;
+}
+```
+
+### Sync Flow
+
+1. **Normalize payload** — Lowercase email, resolve display name from multiple claim fields (`name`, `preferred_username`, email prefix), apply default issuer.
+
+2. **Ensure shadow `auth.users`** (when `createShadowAuthUser: true`):
+   - Search for existing record using identity-first matching
+   - If found and metadata needs updating (e.g. email matched but OIDC identity not set), update the record
+   - If not found, create a new shadow user with `role: "authenticated"`
+
+3. **Upsert `public.users`** via `upsert_oidc_user()` RPC:
+   - Inserts or updates the application user record keyed by `(sub, iss)`
+   - Merges `raw_claims` JSONB (additive, never destructive)
+   - `email_verified` flag ORs (once verified, stays verified)
+
+4. **Link shadow** via `link_shadow_auth_user()` RPC:
+   - Updates `public.users` to set `shadow_auth_user_id` and `shadow_linked_at`
+   - Enables cross-table joins between `public.users` and `auth.users`
+
+---
+
+## Rollback Behavior
+
+The adapter includes automatic rollback for newly created shadow `auth.users` rows when downstream sync fails:
+
+```
+Shadow auth.users created → upsert_oidc_user() RPC fails → Shadow deleted
+Shadow auth.users created → link_shadow_auth_user() RPC fails → Shadow deleted
+```
+
+**Key details:**
+
+- Rollback only applies to **newly created** shadow records (`authUserCreated: true`)
+- Pre-existing shadow records matched by identity or email are **never** deleted on failure
+- Rollback is **best-effort** — if the delete fails, the original error is still returned
+- Controlled by `rollbackOnFailure` config (default: `true`)
+
+This prevents orphaned `auth.users` records from accumulating when the downstream `public.users` sync fails.
+
+---
+
+## SQL Migrations
+
+The provisioning model requires two SQL migrations applied to your Supabase project:
+
+### Migration 001: `001_create_app_users.sql`
+
+Creates the `public.users` table and `upsert_oidc_user()` RPC:
+
+- Table keyed by `(sub, iss)` unique constraint
+- `upsert_oidc_user()` — security-definer RPC restricted to `service_role`
+- Indexes on `email` (lowercase) and `provider`
+- Auto-updating `updated_at` trigger
+
+### Migration 003: `003_authentik_shadow_auth_users.sql`
+
+Adds shadow auth user support:
+
+- `shadow_auth_user_id` (uuid) column on `public.users`
+- `shadow_linked_at` (timestamptz) column on `public.users`
+- Index on `shadow_auth_user_id` for lookup
+- `link_shadow_auth_user()` RPC — links a `public.users` row to its shadow `auth.users` record
+
+**Applying migrations:**
+
+```bash
+# Copy migrations to your Supabase project
+cp packages/auth/supabase/migrations/001_create_app_users.sql \
+   supabase/migrations/
+
+cp packages/auth/supabase/migrations/003_authentik_shadow_auth_users.sql \
+   supabase/migrations/
+
+# Apply
+supabase db push
+```
+
+### `link_shadow_auth_user()` RPC
+
+This RPC is called by `SupabaseSyncAdapter` after creating or finding the shadow `auth.users` record:
+
+```sql
+function link_shadow_auth_user(
+  p_sub                text,    -- OIDC subject identifier
+  p_iss                text,    -- OIDC issuer URL
+  p_shadow_auth_user_id uuid    -- Supabase auth.users ID
+) returns public.users
+```
+
+- **Security:** `SECURITY DEFINER` — requires `service_role` caller
+- **Behavior:** Updates `shadow_auth_user_id` and `shadow_linked_at` on the `public.users` row matching `(p_sub, p_iss)`
+- **Error:** Raises exception if no matching `public.users` row is found
+
+---
+
+## Runtime Requirements
+
+Server-side provisioning requires these environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SUPABASE_URL` | Yes | Supabase project URL (e.g. `https://xxx.supabase.co`) |
+| `SUPABASE_SERVICE_ROLE_KEY` | Yes | Supabase service_role JWT key |
+
+The `service_role` key grants admin access to the Supabase Admin API, which is needed to:
+- List, create, update, and delete `auth.users` records
+- Call security-definer RPCs that check for `service_role` in JWT claims
+
+> ⚠️ **Security:** The `service_role` key must never be exposed to the client. Provisioning must run exclusively in server-side code (API routes, server components, edge functions).
+
+---
+
+## Startup Validation
+
+Use `validateFullConfig()` at application startup to detect misconfigurations before users attempt to log in:
+
+```ts
+import { validateFullConfig } from "@edcalderon/auth/authentik";
+
+const result = validateFullConfig(
+  {
+    issuer: process.env.AUTHENTIK_ISSUER,
+    clientId: process.env.AUTHENTIK_CLIENT_ID,
+    redirectUri: process.env.AUTHENTIK_REDIRECT_URI,
+    tokenEndpoint: endpoints.token,
+    userinfoEndpoint: endpoints.userinfo,
+  },
+  {
+    supabaseUrl: process.env.SUPABASE_URL,
+    supabaseServiceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
+  },
+);
+
+if (!result.valid) {
+  for (const check of result.checks.filter(c => !c.passed)) {
+    console.error(`[config] ${check.name}: ${check.message}`);
+  }
+  // In production, fail fast:
+  throw new Error("Configuration validation failed — check environment variables");
+}
+```
+
+### The `supabase_not_configured` Error
+
+When Supabase URL or service role key is missing, the validation emits the `supabase_not_configured` error signature:
+
+```
+supabase_not_configured: Supabase URL is required for sync
+supabase_not_configured: Supabase service_role key is required for sync
+```
+
+This matches the CIG convention for detecting unconfigured Supabase environments. Use this error code to:
+- Gate provisioning routes at deploy time
+- Show a clear diagnostic in health-check endpoints
+- Prevent partial deployments where OIDC is configured but Supabase is not

package/docs/upgrade-migration.md

@@ -0,0 +1,256 @@
+# Upgrade & Migration Guide
+
+> **Package:** `@edcalderon/auth` v1.3.0 → v1.4.0
+
+This document covers the upgrade path from v1.3.0 to v1.4.0 and provides migration notes for teams adopting the new Authentik integration kit.
+
+---
+
+## Table of Contents
+
+1. [Upgrade Summary](#upgrade-summary)
+2. [What Changed in v1.4.0](#what-changed-in-v140)
+3. [Upgrade Steps](#upgrade-steps)
+4. [Impact on Existing Imports](#impact-on-existing-imports)
+5. [Migrating Custom Relay/Callback/Logout Code](#migrating-custom-relaycallbacklogout-code)
+6. [SQL Migration Path](#sql-migration-path)
+
+---
+
+## Upgrade Summary
+
+**v1.4.0 is fully additive.** There are no breaking changes to existing `@edcalderon/auth` exports. All existing imports, types, and behavior remain unchanged.
+
+| Aspect | Impact |
+|--------|--------|
+| Existing `@edcalderon/auth` imports | ✅ No changes required |
+| Existing `@edcalderon/auth/supabase` imports | ✅ No changes required |
+| Existing `@edcalderon/auth/firebase-*` imports | ✅ No changes required |
+| Existing `@edcalderon/auth/hybrid-*` imports | ✅ No changes required |
+| New subpath `@edcalderon/auth/authentik` | 🆕 Opt-in only |
+| SQL migrations 001-002 | ✅ Unchanged |
+| SQL migration 003 | 🆕 Optional, only needed for shadow auth user support |
+
+---
+
+## What Changed in v1.4.0
+
+### New Subpath Export: `@edcalderon/auth/authentik`
+
+v1.4.0 adds a new subpath export that provides a complete Authentik flow and provisioning kit:
+
+```ts
+import {
+  // Relay (cross-origin PKCE)
+  createRelayPageHtml, parseRelayParams, readRelayStorage, clearRelayStorage,
+  // Callback (token exchange + provisioning gate)
+  exchangeCode, fetchClaims, processCallback,
+  // Logout (token revocation + RP-initiated logout)
+  revokeToken, buildEndSessionUrl, orchestrateLogout,
+  // Provisioning adapters
+  NoopProvisioningAdapter, createProvisioningAdapter,
+  SupabaseSyncAdapter, createSupabaseSyncAdapter,
+  // Config validation
+  validateAuthentikConfig, validateSupabaseSyncConfig, validateFullConfig,
+  discoverEndpoints,
+  // Safe redirect
+  resolveSafeRedirect,
+} from "@edcalderon/auth/authentik";
+```
+
+This subpath is completely independent — importing from `@edcalderon/auth/authentik` does not affect any other subpath exports.
+
+### New SQL Migration
+
+`003_authentik_shadow_auth_users.sql` adds shadow auth user columns and the `link_shadow_auth_user()` RPC to `public.users`. This migration is **optional** and only needed if you use the `SupabaseSyncAdapter` with shadow auth users enabled (the default).
+
+### New Tests
+
+96 tests across 6 test suites covering all new functionality.
+
+---
+
+## Upgrade Steps
+
+### 1. Update the Package
+
+```bash
+npm install @edcalderon/auth@1.4.0
+# or
+pnpm add @edcalderon/auth@1.4.0
+```
+
+### 2. Verify Existing Functionality
+
+Your existing code should work exactly as before. No changes to existing imports or configuration are required.
+
+### 3. (Optional) Adopt the Authentik Kit
+
+If you want to use the new Authentik integration:
+
+1. Set up your Authentik resources — see the [Authentik Integration Guide](./authentik-integration-guide.md)
+2. Apply SQL migration 003 if using Supabase provisioning — see [SQL Migration Path](#sql-migration-path)
+3. Create your relay, callback, and logout routes — see [Next.js Examples](./nextjs-examples.md)
+
+---
+
+## Impact on Existing Imports
+
+### Unaffected Imports
+
+All of these continue to work without any changes:
+
+```ts
+// Core (unchanged)
+import { AuthProvider, useAuth } from "@edcalderon/auth";
+import type { AuthClient, User, SignInOptions } from "@edcalderon/auth";
+
+// Supabase adapter (unchanged)
+import { SupabaseClient } from "@edcalderon/auth/supabase";
+
+// Firebase adapters (unchanged)
+import { FirebaseWebClient } from "@edcalderon/auth/firebase-web";
+import { FirebaseNativeClient } from "@edcalderon/auth/firebase-native";
+
+// Hybrid adapters (unchanged)
+import { HybridWebClient } from "@edcalderon/auth/hybrid-web";
+import { HybridNativeClient } from "@edcalderon/auth/hybrid-native";
+```
+
+### New Import (Opt-in)
+
+The Authentik kit is available via a new subpath:
+
+```ts
+import { processCallback, orchestrateLogout } from "@edcalderon/auth/authentik";
+```
+
+This import is independent of all other subpaths. You can use it alongside any existing adapter configuration.
+
+---
+
+## Migrating Custom Relay/Callback/Logout Code
+
+If your app already has custom Authentik relay, callback, or logout code (e.g. copied from CIG), you can migrate it to use the package's standardized implementations.
+
+### Relay Migration
+
+**Before** (custom implementation):
+
+```ts
+// app/auth/login/[provider]/route.ts
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const provider = url.searchParams.get("provider");
+  // ... custom PKCE generation, sessionStorage manipulation, redirect logic
+}
+```
+
+**After** (using the package):
+
+```ts
+// app/auth/login/[provider]/route.ts
+import { parseRelayParams, createRelayPageHtml } from "@edcalderon/auth/authentik";
+
+export async function GET(request: Request) {
+  const params = parseRelayParams(new URL(request.url).searchParams);
+  if (!params) return new Response("Missing relay params", { status: 400 });
+
+  const { html } = createRelayPageHtml(relayConfig, params);
+  return new Response(html, {
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  });
+}
+```
+
+### Callback Migration
+
+**Before** (custom implementation):
+
+```ts
+// Manual token exchange, userinfo fetch, state validation, provisioning
+const tokens = await customExchangeCode(code, verifier);
+const claims = await customFetchUserInfo(tokens.access_token);
+await customSyncUser(claims);
+```
+
+**After** (using the package):
+
+```ts
+import { processCallback } from "@edcalderon/auth/authentik";
+
+const result = await processCallback({
+  config: callbackConfig,
+  code,
+  codeVerifier: verifier,
+  state,
+  expectedState,
+  provider,
+  provisioningAdapter: adapter, // optional
+});
+
+if (!result.success) {
+  // Structured error handling
+  console.error(result.errorCode, result.error);
+}
+```
+
+### Logout Migration
+
+**Before** (custom implementation):
+
+```ts
+// Manual token revocation, end-session URL construction
+await fetch(revocationEndpoint, { method: "POST", body: new URLSearchParams({ token }) });
+const logoutUrl = `${endSessionEndpoint}?id_token_hint=${idToken}&post_logout_redirect_uri=${redirectUri}`;
+window.location.href = logoutUrl;
+```
+
+**After** (using the package):
+
+```ts
+import { orchestrateLogout } from "@edcalderon/auth/authentik";
+
+const { endSessionUrl, tokenRevoked } = await orchestrateLogout(logoutConfig, {
+  accessToken,
+  idToken,
+});
+
+// Navigate to Authentik to clear the session
+window.location.href = endSessionUrl;
+```
+
+---
+
+## SQL Migration Path
+
+### If you already have migrations 001-002 applied
+
+Migration 003 is **additive** — it adds new columns to `public.users` without modifying existing ones:
+
+```bash
+cp packages/auth/supabase/migrations/003_authentik_shadow_auth_users.sql \
+   supabase/migrations/
+
+supabase db push
+```
+
+### If you are starting fresh
+
+Apply all migrations in order:
+
+```bash
+cp packages/auth/supabase/migrations/001_create_app_users.sql \
+   packages/auth/supabase/migrations/003_authentik_shadow_auth_users.sql \
+   supabase/migrations/
+
+# Optionally also copy 002 if you want the auth.users → public.users trigger
+cp packages/auth/supabase/migrations/002_sync_auth_users_to_app_users.sql \
+   supabase/migrations/
+
+supabase db push
+```
+
+### If you do not use Supabase provisioning
+
+You do not need migration 003. The Authentik kit works without Supabase — use `NoopProvisioningAdapter` or a custom adapter for your backend.