@edcalderon/auth 1.2.2 → 1.4.0

package/dist/authentik/provisioning.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Provisioning adapters for Authentik ↔ application user sync.
+ *
+ * This module provides pluggable adapters that run **server-side** after
+ * a successful Authentik callback to ensure the authenticated user exists
+ * in the application's local user store.
+ *
+ * Adapters are **idempotent** and **fail-closed**: if sync fails the
+ * callback handler must not redirect the user into the protected app.
+ *
+ * Reference:
+ * - CIG apps/dashboard/app/api/auth/sync/route.ts
+ * - CIG apps/dashboard/lib/authSync.ts
+ */
+import type { ProvisioningAdapter, ProvisioningPayload, ProvisioningResult, SupabaseSyncConfig } from "./types";
+/**
+ * A no-op provisioning adapter that always succeeds.
+ *
+ * Use this when the app does not need post-login user sync.
+ */
+export declare class NoopProvisioningAdapter implements ProvisioningAdapter {
+    sync(_payload: ProvisioningPayload): Promise<ProvisioningResult>;
+}
+/**
+ * Create a provisioning adapter from a plain function.
+ *
+ * ```ts
+ * const adapter = createProvisioningAdapter(async (payload) => {
+ *   await myDb.upsertUser(payload);
+ *   return { synced: true, appUserId: "..." };
+ * });
+ * ```
+ */
+export declare function createProvisioningAdapter(syncFn: (payload: ProvisioningPayload) => Promise<ProvisioningResult>): ProvisioningAdapter;
+/**
+ * Normalise a provisioning payload for Supabase sync.
+ * - Lowercases email
+ * - Resolves name from multiple claim fields
+ * - Applies default issuer and provider
+ */
+export declare function normalizePayload(payload: ProvisioningPayload, defaultIssuer?: string): ProvisioningPayload;
+/**
+ * SupabaseClient interface — minimal subset of `@supabase/supabase-js`
+ * needed for the sync adapter. This avoids a hard dependency.
+ */
+interface SupabaseAdminClient {
+    auth: {
+        admin: {
+            listUsers(params?: {
+                page?: number;
+                perPage?: number;
+            }): Promise<{
+                data: {
+                    users: SupabaseAuthUser[];
+                };
+                error: SupabaseError | null;
+            }>;
+            createUser(params: Record<string, unknown>): Promise<{
+                data: {
+                    user: SupabaseAuthUser | null;
+                };
+                error: SupabaseError | null;
+            }>;
+            updateUserById(id: string, params: Record<string, unknown>): Promise<{
+                data: {
+                    user: SupabaseAuthUser | null;
+                };
+                error: SupabaseError | null;
+            }>;
+            deleteUser(id: string): Promise<{
+                error: SupabaseError | null;
+            }>;
+        };
+    };
+    rpc(fn: string, params: Record<string, unknown>): Promise<{
+        data: unknown;
+        error: SupabaseError | null;
+    }>;
+}
+interface SupabaseAuthUser {
+    id: string;
+    email?: string;
+    app_metadata?: Record<string, unknown>;
+    user_metadata?: Record<string, unknown>;
+}
+interface SupabaseError {
+    message: string;
+    code?: string;
+}
+/**
+ * Authentik ↔ Supabase integrated sync adapter.
+ *
+ * This adapter implements the full CIG-proven sync flow:
+ *
+ * 1. Normalise the OIDC payload
+ * 2. Ensure a shadow auth.users record (identity-first matching)
+ * 3. Call the `upsert_oidc_user` RPC to sync into public.users
+ * 4. Roll back the shadow auth.users record if the RPC fails
+ *
+ * The adapter requires a `SupabaseClient` created with `service_role` key.
+ */
+export declare class SupabaseSyncAdapter implements ProvisioningAdapter {
+    private config;
+    private client;
+    constructor(client: SupabaseAdminClient, config: SupabaseSyncConfig);
+    sync(payload: ProvisioningPayload): Promise<ProvisioningResult>;
+}
+/**
+ * Create a Supabase sync adapter from a client and config.
+ *
+ * This is a convenience factory that avoids direct `new SupabaseSyncAdapter(...)`.
+ *
+ * ```ts
+ * import { createClient } from "@supabase/supabase-js";
+ *
+ * const supabase = createClient(url, serviceRoleKey);
+ * const adapter = createSupabaseSyncAdapter(supabase, {
+ *   supabaseUrl: url,
+ *   supabaseServiceRoleKey: serviceRoleKey,
+ * });
+ * ```
+ */
+export declare function createSupabaseSyncAdapter(client: SupabaseAdminClient, config: SupabaseSyncConfig): SupabaseSyncAdapter;
+export {};

package/dist/authentik/provisioning.js

@@ -0,0 +1,342 @@
+/**
+ * Provisioning adapters for Authentik ↔ application user sync.
+ *
+ * This module provides pluggable adapters that run **server-side** after
+ * a successful Authentik callback to ensure the authenticated user exists
+ * in the application's local user store.
+ *
+ * Adapters are **idempotent** and **fail-closed**: if sync fails the
+ * callback handler must not redirect the user into the protected app.
+ *
+ * Reference:
+ * - CIG apps/dashboard/app/api/auth/sync/route.ts
+ * - CIG apps/dashboard/lib/authSync.ts
+ */
+/* ------------------------------------------------------------------ */
+/*  No-op adapter                                                      */
+/* ------------------------------------------------------------------ */
+/**
+ * A no-op provisioning adapter that always succeeds.
+ *
+ * Use this when the app does not need post-login user sync.
+ */
+export class NoopProvisioningAdapter {
+    async sync(_payload) {
+        return { synced: true };
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Custom adapter (function-based)                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Create a provisioning adapter from a plain function.
+ *
+ * ```ts
+ * const adapter = createProvisioningAdapter(async (payload) => {
+ *   await myDb.upsertUser(payload);
+ *   return { synced: true, appUserId: "..." };
+ * });
+ * ```
+ */
+export function createProvisioningAdapter(syncFn) {
+    return { sync: syncFn };
+}
+/* ------------------------------------------------------------------ */
+/*  Supabase sync adapter                                              */
+/* ------------------------------------------------------------------ */
+/**
+ * Normalise a provisioning payload for Supabase sync.
+ * - Lowercases email
+ * - Resolves name from multiple claim fields
+ * - Applies default issuer and provider
+ */
+export function normalizePayload(payload, defaultIssuer) {
+    const rawClaims = payload.rawClaims || {};
+    const name = payload.name ||
+        rawClaims.preferred_username ||
+        rawClaims.name ||
+        payload.email?.split("@")[0] ||
+        "";
+    return {
+        ...payload,
+        email: (payload.email || "").toLowerCase().trim(),
+        name: name.trim() || undefined,
+        iss: payload.iss || defaultIssuer || "",
+        provider: payload.provider || "authentik",
+    };
+}
+/**
+ * Build the user_metadata and app_metadata objects for a Supabase
+ * auth.users shadow record.
+ */
+function buildShadowMetadata(payload) {
+    return {
+        user_metadata: {
+            name: payload.name,
+            full_name: payload.name,
+            avatar_url: payload.picture,
+            oidc_sub: payload.sub,
+            oidc_issuer: payload.iss,
+            upstream_provider: payload.provider,
+        },
+        app_metadata: {
+            provider: "authentik",
+            auth_source: "authentik",
+            oidc_sub: payload.sub,
+            oidc_issuer: payload.iss,
+            upstream_provider: payload.provider,
+        },
+    };
+}
+/**
+ * Find an existing shadow auth.users record by OIDC identity or email.
+ *
+ * Matching strategy (identity-first, per CIG production rules):
+ * 1. Match by (oidc_sub + oidc_issuer) in app_metadata
+ * 2. Fall back to email only when reusing an existing shadow user
+ *
+ * Paginates through all auth.users pages so that matches beyond the first
+ * page are not missed in larger Supabase projects.
+ */
+async function findShadowAuthUser(client, payload) {
+    const perPage = 1000;
+    let page = 1;
+    let emailMatch = null;
+    // Paginate through all auth.users
+    while (true) {
+        const { data, error } = await client.auth.admin.listUsers({ page, perPage });
+        if (error) {
+            throw new Error(`Failed to list auth users: ${error.message}`);
+        }
+        const users = data.users;
+        // 1. Identity-first match
+        const identityMatch = users.find((u) => {
+            const meta = u.app_metadata || {};
+            return (meta.auth_source === "authentik" &&
+                meta.oidc_sub === payload.sub &&
+                meta.oidc_issuer === payload.iss);
+        });
+        if (identityMatch) {
+            return { user: identityMatch, matchedBy: "identity" };
+        }
+        // 2. Accumulate email fallback (first match wins across pages)
+        if (!emailMatch && payload.email) {
+            const match = users.find((u) => u.email?.toLowerCase() === payload.email.toLowerCase());
+            if (match) {
+                emailMatch = match;
+            }
+        }
+        // No more pages
+        if (users.length < perPage) {
+            break;
+        }
+        page++;
+    }
+    if (emailMatch) {
+        return { user: emailMatch, matchedBy: "email" };
+    }
+    return { user: null, matchedBy: null };
+}
+/**
+ * Ensure a shadow auth.users record exists and is up-to-date.
+ *
+ * Returns the auth user ID and whether the record was newly created
+ * (important for rollback on downstream failure).
+ */
+async function ensureShadowAuthUser(client, payload) {
+    const { user: existing, matchedBy } = await findShadowAuthUser(client, payload);
+    const metadata = buildShadowMetadata(payload);
+    if (existing) {
+        // Check if metadata needs updating
+        const currentMeta = existing.app_metadata || {};
+        const needsUpdate = currentMeta.oidc_sub !== payload.sub ||
+            currentMeta.oidc_issuer !== payload.iss ||
+            (existing.user_metadata || {}).avatar_url !== payload.picture ||
+            (existing.user_metadata || {}).name !== payload.name;
+        if (needsUpdate || matchedBy === "email") {
+            const { error } = await client.auth.admin.updateUserById(existing.id, {
+                email: payload.email || existing.email,
+                email_confirm: payload.emailVerified ?? false,
+                ...metadata,
+            });
+            if (error) {
+                throw new Error(`Failed to update shadow auth user: ${error.message}`);
+            }
+            return { authUserId: existing.id, created: false, updated: true };
+        }
+        return { authUserId: existing.id, created: false, updated: false };
+    }
+    // Create new shadow user
+    const { data, error } = await client.auth.admin.createUser({
+        email: payload.email,
+        email_confirm: payload.emailVerified ?? false,
+        role: "authenticated",
+        ...metadata,
+    });
+    if (error) {
+        throw new Error(`Failed to create shadow auth user: ${error.message}`);
+    }
+    if (!data.user) {
+        throw new Error("Shadow auth user creation returned no user");
+    }
+    return { authUserId: data.user.id, created: true, updated: false };
+}
+/**
+ * Authentik ↔ Supabase integrated sync adapter.
+ *
+ * This adapter implements the full CIG-proven sync flow:
+ *
+ * 1. Normalise the OIDC payload
+ * 2. Ensure a shadow auth.users record (identity-first matching)
+ * 3. Call the `upsert_oidc_user` RPC to sync into public.users
+ * 4. Roll back the shadow auth.users record if the RPC fails
+ *
+ * The adapter requires a `SupabaseClient` created with `service_role` key.
+ */
+export class SupabaseSyncAdapter {
+    config;
+    client;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    async sync(payload) {
+        const normalized = normalizePayload(payload, this.config.defaultIssuer);
+        if (!normalized.sub || !normalized.iss) {
+            return {
+                synced: false,
+                error: "Missing required sub or iss in provisioning payload",
+                errorCode: "invalid_payload",
+            };
+        }
+        let shadowResult = null;
+        // Step 1: Shadow auth.users (optional, default: true)
+        if (this.config.createShadowAuthUser !== false) {
+            try {
+                shadowResult = await ensureShadowAuthUser(this.client, normalized);
+            }
+            catch (err) {
+                return {
+                    synced: false,
+                    error: err instanceof Error ? err.message : "Shadow auth user sync failed",
+                    errorCode: "shadow_auth_failed",
+                };
+            }
+        }
+        // Step 2: public.users upsert via RPC
+        const rpcName = this.config.upsertRpcName || "upsert_oidc_user";
+        const rpcParams = {
+            p_sub: normalized.sub,
+            p_iss: normalized.iss,
+            p_email: normalized.email || null,
+            p_email_verified: normalized.emailVerified ?? false,
+            p_name: normalized.name || null,
+            p_picture: normalized.picture || null,
+            p_provider: normalized.provider || null,
+            p_raw_claims: {
+                ...(normalized.rawClaims || {}),
+                ...(shadowResult
+                    ? {
+                        shadow_supabase_auth_user_id: shadowResult.authUserId,
+                        shadow_supabase_auth_user_created: shadowResult.created,
+                        shadow_supabase_auth_user_updated: shadowResult.updated,
+                    }
+                    : {}),
+            },
+        };
+        const { error: rpcError } = await this.client.rpc(rpcName, rpcParams);
+        if (rpcError) {
+            // Rollback: delete newly created shadow auth.users row
+            if (shadowResult?.created &&
+                this.config.rollbackOnFailure !== false) {
+                try {
+                    await this.client.auth.admin.deleteUser(shadowResult.authUserId);
+                }
+                catch {
+                    // Best-effort rollback — log but don't mask the original error
+                }
+            }
+            return {
+                synced: false,
+                authUserId: shadowResult?.authUserId,
+                authUserCreated: shadowResult?.created,
+                error: `RPC ${rpcName} failed: ${rpcError.message}`,
+                errorCode: "rpc_upsert_failed",
+            };
+        }
+        // Step 3: Link shadow auth.users ID to public.users row
+        if (shadowResult) {
+            const linkRpcName = this.config.linkShadowRpcName || "link_shadow_auth_user";
+            try {
+                const { error: linkError } = await this.client.rpc(linkRpcName, {
+                    p_sub: normalized.sub,
+                    p_iss: normalized.iss,
+                    p_shadow_auth_user_id: shadowResult.authUserId,
+                });
+                if (linkError) {
+                    // Rollback: delete newly created shadow auth.users row
+                    if (shadowResult.created &&
+                        this.config.rollbackOnFailure !== false) {
+                        try {
+                            await this.client.auth.admin.deleteUser(shadowResult.authUserId);
+                        }
+                        catch {
+                            // Best-effort rollback
+                        }
+                    }
+                    return {
+                        synced: false,
+                        authUserId: shadowResult.authUserId,
+                        authUserCreated: shadowResult.created,
+                        error: `${linkRpcName} failed: ${linkError.message}`,
+                        errorCode: "shadow_link_failed",
+                    };
+                }
+            }
+            catch (err) {
+                // Rollback: delete newly created shadow auth.users row
+                if (shadowResult.created &&
+                    this.config.rollbackOnFailure !== false) {
+                    try {
+                        await this.client.auth.admin.deleteUser(shadowResult.authUserId);
+                    }
+                    catch {
+                        // Best-effort rollback
+                    }
+                }
+                return {
+                    synced: false,
+                    authUserId: shadowResult.authUserId,
+                    authUserCreated: shadowResult.created,
+                    error: err instanceof Error ? err.message : `${linkRpcName} failed`,
+                    errorCode: "shadow_link_failed",
+                };
+            }
+        }
+        return {
+            synced: true,
+            authUserId: shadowResult?.authUserId,
+            authUserCreated: shadowResult?.created,
+            authUserUpdated: shadowResult?.updated,
+        };
+    }
+}
+/**
+ * Create a Supabase sync adapter from a client and config.
+ *
+ * This is a convenience factory that avoids direct `new SupabaseSyncAdapter(...)`.
+ *
+ * ```ts
+ * import { createClient } from "@supabase/supabase-js";
+ *
+ * const supabase = createClient(url, serviceRoleKey);
+ * const adapter = createSupabaseSyncAdapter(supabase, {
+ *   supabaseUrl: url,
+ *   supabaseServiceRoleKey: serviceRoleKey,
+ * });
+ * ```
+ */
+export function createSupabaseSyncAdapter(client, config) {
+    return new SupabaseSyncAdapter(client, config);
+}
+//# sourceMappingURL=provisioning.js.map

package/dist/authentik/redirect.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Safe redirect resolver.
+ *
+ * Prevents open-redirect vulnerabilities by validating that the target URL
+ * is within one of the allowed origins.
+ *
+ * Reference: CIG callback + logout redirect patterns.
+ */
+import type { SafeRedirectConfig } from "./types";
+/**
+ * Resolve a redirect URL, falling back to `fallbackUrl` if the target
+ * is not within one of the allowed origins.
+ *
+ * Rules:
+ * - Relative paths (e.g. "/dashboard") are always allowed
+ * - Absolute URLs must have an origin in `allowedOrigins`
+ * - Invalid URLs fall back to fallbackUrl
+ * - Empty / null targets fall back to fallbackUrl
+ */
+export declare function resolveSafeRedirect(target: string | null | undefined, config: SafeRedirectConfig): string;

package/dist/authentik/redirect.js

@@ -0,0 +1,52 @@
+/**
+ * Safe redirect resolver.
+ *
+ * Prevents open-redirect vulnerabilities by validating that the target URL
+ * is within one of the allowed origins.
+ *
+ * Reference: CIG callback + logout redirect patterns.
+ */
+/**
+ * Resolve a redirect URL, falling back to `fallbackUrl` if the target
+ * is not within one of the allowed origins.
+ *
+ * Rules:
+ * - Relative paths (e.g. "/dashboard") are always allowed
+ * - Absolute URLs must have an origin in `allowedOrigins`
+ * - Invalid URLs fall back to fallbackUrl
+ * - Empty / null targets fall back to fallbackUrl
+ */
+export function resolveSafeRedirect(target, config) {
+    if (!target || !target.trim()) {
+        return config.fallbackUrl;
+    }
+    const trimmed = target.trim();
+    // Relative paths are always safe
+    if (trimmed.startsWith("/") && !trimmed.startsWith("//")) {
+        return trimmed;
+    }
+    // Validate absolute URLs
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return config.fallbackUrl;
+    }
+    // Check protocol
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return config.fallbackUrl;
+    }
+    // Check origin — strip trailing slashes without regex (avoids CodeQL polynomial-regex flag)
+    const normalised = config.allowedOrigins.map((o) => {
+        let s = o;
+        while (s.endsWith("/"))
+            s = s.slice(0, -1);
+        return s;
+    });
+    if (normalised.includes(parsed.origin)) {
+        return trimmed;
+    }
+    return config.fallbackUrl;
+}
+//# sourceMappingURL=redirect.js.map

package/dist/authentik/relay.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cross-origin PKCE relay handler for Authentik social login.
+ *
+ * When the login UI lives on a different origin than the callback handler,
+ * sessionStorage is origin-scoped. The relay stores the PKCE verifier and
+ * state on the callback origin before navigating to Authentik.
+ *
+ * Reference: CIG apps/dashboard/app/auth/login/[provider]/route.ts
+ */
+import type { AuthentikRelayConfig, RelayIncomingParams, RelayHandlerResult } from "./types";
+/**
+ * Generate the minimal HTML page that the relay route should serve.
+ *
+ * This page:
+ * 1. Stores PKCE params in the callback origin's sessionStorage
+ * 2. Redirects the browser to the Authentik social login flow
+ *
+ * The HTML is self-contained and does **not** load any external scripts.
+ */
+export declare function createRelayPageHtml(config: AuthentikRelayConfig, params: RelayIncomingParams): RelayHandlerResult;
+/**
+ * Parse the query parameters that the login origin sends to the relay.
+ *
+ * Expected query params:
+ *   - `code_verifier`  — PKCE verifier generated on the login origin
+ *   - `code_challenge` — PKCE challenge (SHA-256 of verifier, base64url)
+ *   - `state`          — CSRF state token
+ *   - `next`           — (optional) post-login redirect target
+ *
+ * Returns `null` if required params are missing.
+ */
+export declare function parseRelayParams(searchParams: URLSearchParams | Record<string, string | undefined>): RelayIncomingParams | null;
+/**
+ * Read PKCE params back from sessionStorage on the callback origin.
+ *
+ * This is called by the callback handler after Authentik redirects back
+ * with `?code=&state=`.
+ */
+export declare function readRelayStorage(storage: Storage, prefix?: string): {
+    codeVerifier: string;
+    state: string;
+    provider: string;
+    next?: string;
+} | null;
+/**
+ * Clean up relay storage after a successful callback exchange.
+ */
+export declare function clearRelayStorage(storage: Storage, prefix?: string): void;