@edcalderon/auth 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [1.3.0] - 2026-03-19
+
+### Added
+
+- Added canonical `AuthentikOidcClient` browser helpers with PKCE-only OAuth flow utilities (`isAuthentikConfigured`, `startAuthentikOAuthFlow`, `handleAuthentikCallback`, `readOidcSession`, `clearOidcSession`, `hasPendingAuthentikCallback`, `OIDC_INITIAL_SEARCH`).
+- Added exported Authentik OIDC types: `OidcClaims`, `OidcSession`, `OidcProvider`.
+- Added README guidance for Authentik setup and the known Authentik `2026.2.1` social re-link bug workaround.
+
+## [1.2.2] - 2026-03-19
+
+### Added
+
+- Added `packages/auth/supabase/` SQL templates for a vendor-independent `public.users` table and optional Supabase Auth sync trigger.
+
+### Fixed
+
+- Hardened the OIDC upsert migration so identity writes require a trusted server-side caller instead of the `anon` role.
+- Preserved existing user profile fields when optional claims are omitted during upserts or Supabase sync updates.
+
 ## [1.2.1] - 2026-03-02
 
 ### Changed

package/README.md

@@ -11,12 +11,13 @@ Swap between Supabase, Firebase, Hybrid, or any custom provider without changing
 
 ---
 
-## 📋 Latest Changes (v1.2.1)
+## 📋 Latest Changes (v1.3.0)
 
-### Changed
+### Added
 
-- 🎨 Upgraded README badges and title to `for-the-badge` style with gold (#C8A84E) / dark (#0d1117) Alternun brand colors
-- 🔗 Added Web3 SIWE|SIWS badge linking to Supabase docs
+- Added canonical `AuthentikOidcClient` browser helpers with PKCE-only OAuth flow utilities (`isAuthentikConfigured`, `startAuthentikOAuthFlow`, `handleAuthentikCallback`, `readOidcSession`, `clearOidcSession`, `hasPendingAuthentikCallback`, `OIDC_INITIAL_SEARCH`).
+- Added exported Authentik OIDC types: `OidcClaims`, `OidcSession`, `OidcProvider`.
+- Added README guidance for Authentik setup and the known Authentik `2026.2.1` social re-link bug workaround.
 
 For full version history, see [CHANGELOG.md](./CHANGELOG.md) and [GitHub releases](https://github.com/edcalderon/my-second-brain/releases)
 
@@ -68,6 +69,75 @@ pnpm add firebase
 pnpm add react-native
 ```
 
+### Supabase SQL Templates
+
+If you want an application-owned user table instead of coupling your identity model to `auth.users`, copy the reference SQL templates in `packages/auth/supabase/` into your Supabase project and apply them with `supabase db push`.
+
+- `001_create_app_users.sql`: vendor-independent `public.users` table plus secure server-side OIDC upsert RPC
+- `002_sync_auth_users_to_app_users.sql`: optional trigger and backfill for projects using Supabase Auth
+
+### Authentik OIDC Client (Canonical)
+
+`@edcalderon/auth` exports a browser-first Authentik OIDC helper that is decoupled from Supabase and can be used with any backend session strategy.
+
+```ts
+import {
+    isAuthentikConfigured,
+    startAuthentikOAuthFlow,
+    handleAuthentikCallback,
+    readOidcSession,
+    clearOidcSession,
+    hasPendingAuthentikCallback,
+} from "@edcalderon/auth";
+
+if (isAuthentikConfigured()) {
+    await startAuthentikOAuthFlow("google", {
+        providerSourceSlugs: {
+            google: "google",
+            discord: "discord",
+        },
+    });
+}
+
+if (hasPendingAuthentikCallback(window.location.search)) {
+    const session = await handleAuthentikCallback(window.location.search, {
+        onSessionReady: async (claims, tokens) => {
+            // Optional hook for API upsert/session handoff.
+            console.log(claims.sub, tokens.accessToken);
+        },
+    });
+
+    console.log("OIDC session", session);
+}
+
+const existing = readOidcSession();
+if (!existing) {
+    clearOidcSession();
+}
+```
+
+Required env vars (defaults):
+
+| Var | Description |
+| --- | --- |
+| `EXPO_PUBLIC_AUTHENTIK_ISSUER` | `https://<host>/application/o/<app-slug>/` |
+| `EXPO_PUBLIC_AUTHENTIK_CLIENT_ID` | OAuth2 provider client ID |
+| `EXPO_PUBLIC_AUTHENTIK_REDIRECT_URI` | App redirect URI registered in Authentik |
+
+You can override env key names with `envKeys` and pass direct values with `issuer`, `clientId`, and `redirectUri`.
+
+Authentik setup checklist:
+
+1. Configure an OAuth2/OIDC provider in Authentik with PKCE enabled.
+2. Ensure redirect URIs match your app origin/path exactly.
+3. Configure source login slugs (`providerSourceSlugs`) for each social provider.
+4. Use `onSessionReady` to hand off claims/tokens to your backend session flow.
+
+Known Authentik `2026.2.1` bug workaround:
+
+- A production hot-patch may be needed in Authentik `flow_manager.py` around `handle_existing_link` to avoid duplicate `(user_id, source_id)` writes when re-linking existing social identities.
+- Track the upstream Authentik issue and re-apply the patch after container upgrades until a fixed release is available.
+
 ---
 
 ## Subpath Exports (Crucial for RN/Next.js compatibility)

package/dist/AuthentikOidcClient.d.ts

@@ -0,0 +1,58 @@
+export type OidcProvider = "google" | "discord" | string;
+export interface OidcClaims {
+    sub: string;
+    iss: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+    preferred_username?: string;
+    [key: string]: unknown;
+}
+export interface OidcTokens {
+    accessToken: string;
+    tokenType?: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresIn?: number;
+    expiresAt?: number;
+    scope?: string;
+}
+export interface OidcSession {
+    provider: OidcProvider;
+    issuer: string;
+    clientId: string;
+    claims: OidcClaims;
+    tokens: OidcTokens;
+    createdAt: number;
+}
+export interface AuthentikEnvKeys {
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+}
+export interface AuthentikOidcConfig {
+    issuer?: string;
+    clientId?: string;
+    redirectUri?: string;
+    scope?: string;
+    env?: Record<string, string | undefined>;
+    envKeys?: Partial<AuthentikEnvKeys>;
+    providerSourceSlugs?: Record<string, string>;
+    authorizePath?: string;
+    tokenPath?: string;
+    userinfoPath?: string;
+    onSessionReady?: (claims: OidcClaims, tokens: OidcTokens, session: OidcSession) => void | Promise<void>;
+    storageKey?: string;
+    pendingStorageKey?: string;
+    sessionStorage?: Storage;
+    localStorage?: Storage;
+    fetchFn?: typeof fetch;
+}
+export declare const OIDC_INITIAL_SEARCH = "authentik:oidc:initial-search";
+export declare function isAuthentikConfigured(config?: AuthentikOidcConfig): boolean;
+export declare function hasPendingAuthentikCallback(searchString?: string): boolean;
+export declare function readOidcSession(config?: AuthentikOidcConfig): OidcSession | null;
+export declare function clearOidcSession(config?: AuthentikOidcConfig): void;
+export declare function startAuthentikOAuthFlow(provider: OidcProvider, config?: AuthentikOidcConfig): Promise<void>;
+export declare function handleAuthentikCallback(searchString?: string, config?: AuthentikOidcConfig): Promise<OidcSession>;

package/dist/AuthentikOidcClient.js

@@ -0,0 +1,282 @@
+const DEFAULT_ENV_KEYS = {
+    issuer: "EXPO_PUBLIC_AUTHENTIK_ISSUER",
+    clientId: "EXPO_PUBLIC_AUTHENTIK_CLIENT_ID",
+    redirectUri: "EXPO_PUBLIC_AUTHENTIK_REDIRECT_URI"
+};
+const DEFAULT_SCOPE = "openid profile email";
+const DEFAULT_STORAGE_KEY = "authentik:oidc:session";
+const DEFAULT_PENDING_STORAGE_KEY = "authentik:oidc:pending";
+export const OIDC_INITIAL_SEARCH = "authentik:oidc:initial-search";
+function isBrowserRuntime() {
+    return typeof window !== "undefined";
+}
+function getProcessEnv() {
+    const maybeProcess = globalThis.process;
+    return maybeProcess?.env || {};
+}
+function resolveEnvValue(config, key) {
+    const envKeys = { ...DEFAULT_ENV_KEYS, ...(config.envKeys || {}) };
+    const explicit = key === "issuer" ? config.issuer : key === "clientId" ? config.clientId : config.redirectUri;
+    if (explicit && explicit.trim()) {
+        return explicit.trim();
+    }
+    const envSource = config.env || getProcessEnv();
+    const envKey = envKeys[key];
+    return envSource[envKey]?.trim();
+}
+function ensurePathSuffix(pathname) {
+    return pathname.endsWith("/") ? pathname : `${pathname}/`;
+}
+function resolveEndpoint(issuer, explicitPath, fallbackPath) {
+    const issuerUrl = new URL(issuer);
+    if (explicitPath) {
+        return new URL(explicitPath, `${issuerUrl.origin}/`).toString();
+    }
+    const normalizedBase = ensurePathSuffix(issuerUrl.pathname);
+    return new URL(`${normalizedBase}${fallbackPath}`, issuerUrl.origin).toString();
+}
+function getSessionStorage(config) {
+    if (config.sessionStorage) {
+        return config.sessionStorage;
+    }
+    if (!isBrowserRuntime() || !window.sessionStorage) {
+        throw new Error("CONFIG_ERROR: sessionStorage is unavailable in this runtime");
+    }
+    return window.sessionStorage;
+}
+function getLocalStorage(config) {
+    if (config.localStorage) {
+        return config.localStorage;
+    }
+    if (!isBrowserRuntime() || !window.localStorage) {
+        throw new Error("CONFIG_ERROR: localStorage is unavailable in this runtime");
+    }
+    return window.localStorage;
+}
+function getFetch(config) {
+    if (config.fetchFn) {
+        return config.fetchFn;
+    }
+    if (typeof fetch === "undefined") {
+        throw new Error("CONFIG_ERROR: fetch is unavailable in this runtime");
+    }
+    return fetch;
+}
+function resolveConfig(config = {}) {
+    const issuer = resolveEnvValue(config, "issuer");
+    const clientId = resolveEnvValue(config, "clientId");
+    const redirectUri = resolveEnvValue(config, "redirectUri");
+    if (!issuer || !clientId || !redirectUri) {
+        throw new Error("CONFIG_ERROR: Missing Authentik issuer, clientId, or redirectUri");
+    }
+    return {
+        issuer,
+        clientId,
+        redirectUri,
+        scope: config.scope || DEFAULT_SCOPE,
+        authorizePath: resolveEndpoint(issuer, config.authorizePath, "authorize/"),
+        tokenPath: resolveEndpoint(issuer, config.tokenPath, "token/"),
+        userinfoPath: resolveEndpoint(issuer, config.userinfoPath, "userinfo/"),
+        storageKey: config.storageKey || DEFAULT_STORAGE_KEY,
+        pendingStorageKey: config.pendingStorageKey || DEFAULT_PENDING_STORAGE_KEY,
+        providerSourceSlugs: config.providerSourceSlugs || {},
+        sessionStorage: getSessionStorage(config),
+        localStorage: getLocalStorage(config),
+        fetchFn: getFetch(config),
+        onSessionReady: config.onSessionReady
+    };
+}
+function encodeBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function randomString(length) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    return encodeBase64Url(bytes);
+}
+async function sha256(input) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+    return new Uint8Array(digest);
+}
+async function buildPkcePair() {
+    const verifier = randomString(64);
+    const challenge = encodeBase64Url(await sha256(verifier));
+    return { verifier, challenge };
+}
+function parsePendingState(rawValue) {
+    if (!rawValue) {
+        return null;
+    }
+    try {
+        return JSON.parse(rawValue);
+    }
+    catch {
+        return null;
+    }
+}
+function getSourceSlug(provider, config) {
+    return config.providerSourceSlugs[provider] || provider;
+}
+export function isAuthentikConfigured(config = {}) {
+    try {
+        const issuer = resolveEnvValue(config, "issuer");
+        const clientId = resolveEnvValue(config, "clientId");
+        const redirectUri = resolveEnvValue(config, "redirectUri");
+        return Boolean(issuer && clientId && redirectUri);
+    }
+    catch {
+        return false;
+    }
+}
+export function hasPendingAuthentikCallback(searchString) {
+    const rawSearch = typeof searchString === "string"
+        ? searchString
+        : isBrowserRuntime()
+            ? window.location.search
+            : "";
+    const params = new URLSearchParams(rawSearch.startsWith("?") ? rawSearch.slice(1) : rawSearch);
+    return Boolean(params.get("code") && params.get("state"));
+}
+export function readOidcSession(config = {}) {
+    const storage = config.localStorage || (isBrowserRuntime() ? window.localStorage : null);
+    if (!storage) {
+        return null;
+    }
+    const key = config.storageKey || DEFAULT_STORAGE_KEY;
+    const rawValue = storage.getItem(key);
+    if (!rawValue) {
+        return null;
+    }
+    try {
+        return JSON.parse(rawValue);
+    }
+    catch {
+        return null;
+    }
+}
+export function clearOidcSession(config = {}) {
+    const localStorageRef = config.localStorage || (isBrowserRuntime() ? window.localStorage : null);
+    const sessionStorageRef = config.sessionStorage || (isBrowserRuntime() ? window.sessionStorage : null);
+    const sessionKey = config.storageKey || DEFAULT_STORAGE_KEY;
+    const pendingKey = config.pendingStorageKey || DEFAULT_PENDING_STORAGE_KEY;
+    localStorageRef?.removeItem(sessionKey);
+    sessionStorageRef?.removeItem(pendingKey);
+    sessionStorageRef?.removeItem(OIDC_INITIAL_SEARCH);
+}
+export async function startAuthentikOAuthFlow(provider, config = {}) {
+    if (!isBrowserRuntime()) {
+        throw new Error("CONFIG_ERROR: startAuthentikOAuthFlow requires a browser runtime");
+    }
+    const resolved = resolveConfig(config);
+    const { verifier, challenge } = await buildPkcePair();
+    const state = randomString(32);
+    const pendingState = {
+        state,
+        provider,
+        codeVerifier: verifier,
+        createdAt: Date.now()
+    };
+    resolved.sessionStorage.setItem(resolved.pendingStorageKey, JSON.stringify(pendingState));
+    resolved.sessionStorage.setItem(OIDC_INITIAL_SEARCH, window.location.search || "");
+    const authorizeUrl = new URL(resolved.authorizePath);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("client_id", resolved.clientId);
+    authorizeUrl.searchParams.set("redirect_uri", resolved.redirectUri);
+    authorizeUrl.searchParams.set("scope", resolved.scope);
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("code_challenge", challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    const loginUrl = new URL(`/source/oauth/login/${encodeURIComponent(getSourceSlug(provider, resolved))}/`, new URL(resolved.issuer).origin);
+    loginUrl.searchParams.set("next", authorizeUrl.toString());
+    window.location.assign(loginUrl.toString());
+}
+export async function handleAuthentikCallback(searchString, config = {}) {
+    const resolved = resolveConfig(config);
+    const rawSearch = typeof searchString === "string"
+        ? searchString
+        : isBrowserRuntime()
+            ? window.location.search
+            : "";
+    const params = new URLSearchParams(rawSearch.startsWith("?") ? rawSearch.slice(1) : rawSearch);
+    const error = params.get("error");
+    if (error) {
+        const description = params.get("error_description") || "OAuth callback returned an error";
+        throw new Error(`PROVIDER_ERROR: ${error} (${description})`);
+    }
+    const code = params.get("code");
+    const state = params.get("state");
+    if (!code || !state) {
+        throw new Error("SESSION_ERROR: Missing code or state in Authentik callback");
+    }
+    const pending = parsePendingState(resolved.sessionStorage.getItem(resolved.pendingStorageKey));
+    if (!pending) {
+        throw new Error("SESSION_ERROR: Missing pending Authentik state in sessionStorage");
+    }
+    if (pending.state !== state) {
+        throw new Error("SESSION_ERROR: Invalid Authentik callback state");
+    }
+    const tokenPayload = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: resolved.redirectUri,
+        client_id: resolved.clientId,
+        code_verifier: pending.codeVerifier
+    });
+    const tokenResponse = await resolved.fetchFn(resolved.tokenPath, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: tokenPayload
+    });
+    if (!tokenResponse.ok) {
+        throw new Error(`NETWORK_ERROR: Token exchange failed with status ${tokenResponse.status}`);
+    }
+    const tokenJson = (await tokenResponse.json());
+    if (!tokenJson.access_token) {
+        throw new Error("SESSION_ERROR: Token response missing access_token");
+    }
+    const userinfoResponse = await resolved.fetchFn(resolved.userinfoPath, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${tokenJson.access_token}`
+        }
+    });
+    if (!userinfoResponse.ok) {
+        throw new Error(`NETWORK_ERROR: Userinfo request failed with status ${userinfoResponse.status}`);
+    }
+    const claims = (await userinfoResponse.json());
+    if (!claims.sub || !claims.iss) {
+        throw new Error("SESSION_ERROR: Userinfo response missing required claims (sub, iss)");
+    }
+    const now = Date.now();
+    const expiresAt = tokenJson.expires_in ? now + tokenJson.expires_in * 1000 : undefined;
+    const tokens = {
+        accessToken: tokenJson.access_token,
+        tokenType: tokenJson.token_type,
+        refreshToken: tokenJson.refresh_token,
+        idToken: tokenJson.id_token,
+        expiresIn: tokenJson.expires_in,
+        expiresAt,
+        scope: tokenJson.scope
+    };
+    const session = {
+        provider: pending.provider,
+        issuer: resolved.issuer,
+        clientId: resolved.clientId,
+        claims,
+        tokens,
+        createdAt: now
+    };
+    resolved.localStorage.setItem(resolved.storageKey, JSON.stringify(session));
+    resolved.sessionStorage.removeItem(resolved.pendingStorageKey);
+    if (resolved.onSessionReady) {
+        await resolved.onSessionReady(claims, tokens, session);
+    }
+    return session;
+}
+//# sourceMappingURL=AuthentikOidcClient.js.map

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./providers/FirebaseWebClient";
 export { FirebaseWebClient as FirebaseClient } from "./providers/FirebaseWebClient";
 export * from "./providers/HybridWebClient";
 export { HybridWebClient as HybridClient } from "./providers/HybridWebClient";
+export * from "./AuthentikOidcClient";

package/dist/index.js

@@ -7,4 +7,5 @@ export * from "./providers/FirebaseWebClient";
 export { FirebaseWebClient as FirebaseClient } from "./providers/FirebaseWebClient";
 export * from "./providers/HybridWebClient";
 export { HybridWebClient as HybridClient } from "./providers/HybridWebClient";
+export * from "./AuthentikOidcClient";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edcalderon/auth",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A universal, provider-agnostic authentication package (Web + Next.js + Expo/React Native)",
   "exports": {
     ".": {

package/supabase/README.md

@@ -0,0 +1,65 @@
+# @edcalderon/auth Supabase SQL Templates
+
+Copy these files into your own Supabase project. They are reference migrations for projects using @edcalderon/auth, not runtime imports.
+
+## Quick Setups
+
+| Use case | Apply | Result |
+| --- | --- | --- |
+| Supabase Auth quick setup | `001` + `002` | Vendor-independent `public.users` plus automatic `auth.users -> public.users` sync |
+| External OIDC only | `001` | Vendor-independent `public.users` plus a secure server-side upsert RPC |
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `migrations/001_create_app_users.sql` | Creates `public.users`, timestamps trigger, and `upsert_oidc_user()` |
+| `migrations/002_sync_auth_users_to_app_users.sql` | Optional trigger/backfill for projects that use Supabase Auth |
+
+## What You Get
+
+- A vendor-independent `public.users` table keyed by `(sub, iss)`.
+- A clean migration path away from Supabase Auth later.
+- An optional trigger that mirrors Supabase Auth users automatically.
+- Safe default behavior for optional profile fields so missing claims do not erase stored data.
+
+## Security Model
+
+`upsert_oidc_user()` is intentionally not callable by the `anon` role.
+
+- Supabase Auth users are synced automatically by migration `002`.
+- External OIDC users should be written by a trusted server or Edge Function after token verification.
+- Optional fields such as `email`, `name`, `picture`, and `provider` only overwrite stored values when a non-null value is provided.
+
+## Apply
+
+```bash
+# Copy into your project
+cp packages/auth/supabase/migrations/*.sql your-project/supabase/migrations/
+
+# Apply them with the Supabase CLI
+supabase db push
+```
+
+If you only want the vendor-independent table and are not using Supabase Auth as a provider, apply only `001_create_app_users.sql`.
+
+## Suggested External OIDC Flow
+
+1. Verify the provider token in your server or Edge Function.
+2. Extract `sub`, `iss`, and optional claims.
+3. Call `upsert_oidc_user()` with the service-role key.
+4. Use the returned `public.users.id` as your application user identifier.
+
+## Why `(sub, iss)`
+
+The `(sub, iss)` pair follows the OIDC identity model and allows multiple providers to coexist safely:
+
+| Provider | `sub` | `iss` |
+| --- | --- | --- |
+| Supabase Auth | `auth.users.id` | `supabase` |
+| Authentik | provider UUID | issuer URL |
+| Auth0 | provider user id | issuer URL |
+| Firebase | provider uid | issuer URL |
+| Custom OIDC | JWT `sub` | JWT `iss` |
+
+That gives you a stable application-owned identity layer even if you later replace the auth provider.

package/supabase/migrations/001_create_app_users.sql

@@ -0,0 +1,147 @@
+-- ============================================================================
+-- 001_create_app_users.sql
+-- Vendor-independent user registry for projects using @edcalderon/auth.
+--
+-- This creates an application-owned public.users table keyed by (sub, iss)
+-- and a secure upsert RPC intended for trusted server-side use.
+-- ============================================================================
+
+create extension if not exists pgcrypto;
+
+create table if not exists public.users (
+  id             uuid        primary key default gen_random_uuid(),
+  sub            text        not null,
+  iss            text        not null,
+  email          text,
+  email_verified boolean     not null default false,
+  name           text,
+  picture        text,
+  provider       text,
+  raw_claims     jsonb       not null default '{}'::jsonb,
+  created_at     timestamptz not null default timezone('utc', now()),
+  updated_at     timestamptz not null default timezone('utc', now()),
+
+  constraint users_sub_iss_uq unique (sub, iss),
+  constraint users_sub_len_chk check (char_length(sub) <= 256),
+  constraint users_iss_len_chk check (char_length(iss) <= 512),
+  constraint users_email_len_chk check (
+    email is null or char_length(email) <= 320
+  )
+);
+
+create index if not exists users_email_idx
+  on public.users (lower(email))
+  where email is not null;
+
+create index if not exists users_provider_idx
+  on public.users (provider)
+  where provider is not null;
+
+create or replace function public.users_set_updated_at()
+returns trigger
+language plpgsql
+as $$
+begin
+  new.updated_at = timezone('utc', now());
+  return new;
+end;
+$$;
+
+drop trigger if exists trg_users_set_updated_at on public.users;
+
+create trigger trg_users_set_updated_at
+before update on public.users
+for each row
+execute function public.users_set_updated_at();
+
+create or replace function public.upsert_oidc_user(
+  p_sub            text,
+  p_iss            text,
+  p_email          text          default null,
+  p_email_verified boolean       default false,
+  p_name           text          default null,
+  p_picture        text          default null,
+  p_provider       text          default null,
+  p_raw_claims     jsonb         default '{}'::jsonb
+)
+returns public.users
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  v_claims jsonb := coalesce(
+    nullif(current_setting('request.jwt.claims', true), ''),
+    '{}'
+  )::jsonb;
+  v_role text := coalesce(nullif(v_claims ->> 'role', ''), 'unknown');
+  v_user public.users;
+begin
+  if v_role <> 'service_role' then
+    raise exception 'upsert_oidc_user() requires a trusted server-side caller';
+  end if;
+
+  if nullif(trim(p_sub), '') is null or nullif(trim(p_iss), '') is null then
+    raise exception 'upsert_oidc_user() requires non-empty p_sub and p_iss';
+  end if;
+
+  insert into public.users (
+    sub,
+    iss,
+    email,
+    email_verified,
+    name,
+    picture,
+    provider,
+    raw_claims
+  )
+  values (
+    trim(p_sub),
+    trim(p_iss),
+    nullif(trim(p_email), ''),
+    p_email_verified,
+    nullif(trim(p_name), ''),
+    nullif(trim(p_picture), ''),
+    nullif(trim(p_provider), ''),
+    coalesce(p_raw_claims, '{}'::jsonb)
+  )
+  on conflict (sub, iss) do update
+    set email = coalesce(excluded.email, public.users.email),
+        email_verified = public.users.email_verified or excluded.email_verified,
+        name = coalesce(excluded.name, public.users.name),
+        picture = coalesce(excluded.picture, public.users.picture),
+        provider = coalesce(excluded.provider, public.users.provider),
+        raw_claims = case
+          when excluded.raw_claims = '{}'::jsonb then public.users.raw_claims
+          else public.users.raw_claims || excluded.raw_claims
+        end,
+        updated_at = timezone('utc', now())
+  returning * into v_user;
+
+  return v_user;
+end;
+$$;
+
+revoke all on function public.upsert_oidc_user(
+  text,
+  text,
+  text,
+  boolean,
+  text,
+  text,
+  text,
+  jsonb
+) from public, anon, authenticated;
+
+grant execute on function public.upsert_oidc_user(
+  text,
+  text,
+  text,
+  boolean,
+  text,
+  text,
+  text,
+  jsonb
+) to service_role;
+
+alter table public.users enable row level security;

package/supabase/migrations/002_sync_auth_users_to_app_users.sql

@@ -0,0 +1,101 @@
+-- ============================================================================
+-- 002_sync_auth_users_to_app_users.sql
+-- Optional trigger for projects that use Supabase Auth.
+-- Keeps auth.users mirrored into public.users and backfills existing users.
+-- ============================================================================
+
+create or replace function public.sync_auth_user_to_app_users()
+returns trigger
+language plpgsql
+security definer
+set search_path = public
+as $$
+begin
+  if new.is_anonymous then
+    return new;
+  end if;
+
+  insert into public.users (
+    sub,
+    iss,
+    email,
+    email_verified,
+    name,
+    picture,
+    provider,
+    raw_claims
+  )
+  values (
+    new.id::text,
+    'supabase',
+    new.email,
+    new.email_confirmed_at is not null,
+    coalesce(
+      new.raw_user_meta_data ->> 'name',
+      new.raw_user_meta_data ->> 'full_name',
+      split_part(coalesce(new.email, ''), '@', 1)
+    ),
+    new.raw_user_meta_data ->> 'avatar_url',
+    coalesce(new.raw_app_meta_data ->> 'provider', 'email'),
+    coalesce(new.raw_user_meta_data, '{}'::jsonb)
+  )
+  on conflict (sub, iss) do update
+    set email = coalesce(excluded.email, public.users.email),
+        email_verified = public.users.email_verified or excluded.email_verified,
+        name = coalesce(excluded.name, public.users.name),
+        picture = coalesce(excluded.picture, public.users.picture),
+        provider = coalesce(excluded.provider, public.users.provider),
+        raw_claims = case
+          when excluded.raw_claims = '{}'::jsonb then public.users.raw_claims
+          else public.users.raw_claims || excluded.raw_claims
+        end,
+        updated_at = timezone('utc', now());
+
+  return new;
+end;
+$$;
+
+drop trigger if exists trg_auth_users_sync_to_app_users on auth.users;
+
+create trigger trg_auth_users_sync_to_app_users
+after insert or update of email_confirmed_at, email, raw_user_meta_data, raw_app_meta_data
+on auth.users
+for each row
+execute function public.sync_auth_user_to_app_users();
+
+insert into public.users (
+  sub,
+  iss,
+  email,
+  email_verified,
+  name,
+  picture,
+  provider,
+  raw_claims
+)
+select
+  u.id::text,
+  'supabase',
+  u.email,
+  u.email_confirmed_at is not null,
+  coalesce(
+    u.raw_user_meta_data ->> 'name',
+    u.raw_user_meta_data ->> 'full_name',
+    split_part(coalesce(u.email, ''), '@', 1)
+  ),
+  u.raw_user_meta_data ->> 'avatar_url',
+  coalesce(u.raw_app_meta_data ->> 'provider', 'email'),
+  coalesce(u.raw_user_meta_data, '{}'::jsonb)
+from auth.users u
+where not u.is_anonymous
+on conflict (sub, iss) do update
+  set email = coalesce(excluded.email, public.users.email),
+      email_verified = public.users.email_verified or excluded.email_verified,
+      name = coalesce(excluded.name, public.users.name),
+      picture = coalesce(excluded.picture, public.users.picture),
+      provider = coalesce(excluded.provider, public.users.provider),
+      raw_claims = case
+        when excluded.raw_claims = '{}'::jsonb then public.users.raw_claims
+        else public.users.raw_claims || excluded.raw_claims
+      end,
+      updated_at = timezone('utc', now());