@edcalderon/auth 1.2.2 → 1.4.0

package/dist/authentik/callback.js

@@ -0,0 +1,163 @@
+/**
+ * Enhanced Authentik callback handler with blocking provisioning support.
+ *
+ * This module handles the OIDC authorization code exchange and optionally
+ * calls a provisioning adapter **before** allowing the app to redirect
+ * into the protected product.
+ *
+ * Reference: CIG apps/dashboard/app/auth/callback/page.tsx
+ */
+/* ------------------------------------------------------------------ */
+/*  Token exchange                                                     */
+/* ------------------------------------------------------------------ */
+/**
+ * Exchange an authorization code for tokens using PKCE.
+ *
+ * This is a pure server-safe function — it does not touch sessionStorage.
+ */
+export async function exchangeCode(config, code, codeVerifier) {
+    const tokenUrl = config.tokenEndpoint;
+    const fetchFn = config.fetchFn || fetch;
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: config.redirectUri,
+        client_id: config.clientId,
+        code_verifier: codeVerifier,
+    });
+    const response = await fetchFn(tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    if (!response.ok) {
+        throw new Error(`NETWORK_ERROR: Token exchange failed (HTTP ${response.status})`);
+    }
+    const json = (await response.json());
+    if (!json.access_token || typeof json.access_token !== "string") {
+        throw new Error("SESSION_ERROR: Token response missing access_token");
+    }
+    return {
+        access_token: json.access_token,
+        token_type: json.token_type ?? undefined,
+        refresh_token: json.refresh_token ?? undefined,
+        id_token: json.id_token ?? undefined,
+        expires_in: typeof json.expires_in === "number" ? json.expires_in : undefined,
+        scope: json.scope ?? undefined,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  Userinfo                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * Fetch OIDC claims from the Authentik userinfo endpoint.
+ */
+export async function fetchClaims(config, accessToken) {
+    const userinfoUrl = config.userinfoEndpoint;
+    const fetchFn = config.fetchFn || fetch;
+    const response = await fetchFn(userinfoUrl, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) {
+        throw new Error(`NETWORK_ERROR: Userinfo request failed (HTTP ${response.status})`);
+    }
+    const claims = (await response.json());
+    if (!claims.sub || !claims.iss) {
+        throw new Error("SESSION_ERROR: Userinfo response missing required claims (sub, iss)");
+    }
+    return claims;
+}
+/**
+ * Process an Authentik OIDC callback end-to-end:
+ *
+ * 1. Validate state matches
+ * 2. Exchange the authorization code for tokens
+ * 3. Fetch OIDC claims from userinfo
+ * 4. (Optional) Run the provisioning adapter — blocks until complete
+ * 5. Return the combined result
+ *
+ * If any step fails the function returns `{ success: false, error }`.
+ * It does **not** throw so that callers can present structured error UI.
+ */
+export async function processCallback(options) {
+    // 1. State validation
+    if (options.state !== options.expectedState) {
+        return {
+            success: false,
+            error: "Invalid callback state — possible CSRF or expired session",
+            errorCode: "state_mismatch",
+        };
+    }
+    // 2. Token exchange
+    let tokens;
+    try {
+        tokens = await exchangeCode(options.config, options.code, options.codeVerifier);
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : "Token exchange failed",
+            errorCode: "token_exchange_failed",
+        };
+    }
+    // 3. Fetch claims
+    let claims;
+    try {
+        claims = await fetchClaims(options.config, tokens.access_token);
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : "Userinfo fetch failed",
+            errorCode: "userinfo_failed",
+        };
+    }
+    const callbackResult = {
+        tokens,
+        claims,
+        provider: options.provider,
+    };
+    // 4. Provisioning gate
+    if (options.provisioningAdapter) {
+        const payload = {
+            sub: claims.sub,
+            iss: claims.iss,
+            email: (claims.email || "").toLowerCase(),
+            emailVerified: claims.email_verified,
+            name: claims.name || claims.preferred_username,
+            picture: claims.picture,
+            provider: options.provider,
+            rawClaims: claims,
+        };
+        let provisioningResult;
+        try {
+            provisioningResult = await options.provisioningAdapter.sync(payload);
+        }
+        catch (err) {
+            return {
+                success: false,
+                callbackResult,
+                error: err instanceof Error ? err.message : "Provisioning failed",
+                errorCode: "provisioning_error",
+            };
+        }
+        if (!provisioningResult.synced) {
+            return {
+                success: false,
+                callbackResult,
+                provisioningResult,
+                error: provisioningResult.error || "User provisioning did not complete",
+                errorCode: provisioningResult.errorCode || "provisioning_failed",
+            };
+        }
+        return {
+            success: true,
+            callbackResult,
+            provisioningResult,
+        };
+    }
+    // No adapter — exchange-only mode
+    return { success: true, callbackResult };
+}
+//# sourceMappingURL=callback.js.map

package/dist/authentik/config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Configuration validation / doctor helpers.
+ *
+ * These helpers detect missing or invalid configuration **before** the
+ * first real user login, so misconfigured environments fail fast.
+ *
+ * Reference: CIG `supabase_not_configured` callback error code.
+ */
+import type { ConfigValidationResult, AuthentikCallbackConfig, AuthentikEndpoints, SupabaseSyncConfig } from "./types";
+/**
+ * Validate that the core Authentik OIDC configuration is present and
+ * syntactically correct.
+ *
+ * This does **not** make network requests — it only checks that the
+ * required values are set and look reasonable.
+ */
+export declare function validateAuthentikConfig(config: Partial<AuthentikCallbackConfig>): ConfigValidationResult;
+/**
+ * Validate the server-side Supabase sync configuration.
+ *
+ * Returns a diagnostic result with the exact error code
+ * `supabase_not_configured` when the Supabase URL or service role key
+ * is missing, matching the CIG convention.
+ */
+export declare function validateSupabaseSyncConfig(config: Partial<SupabaseSyncConfig>): ConfigValidationResult;
+/**
+ * Validate both Authentik and Supabase sync configuration in one call.
+ *
+ * Useful as a startup / health-check / deploy-time validation gate.
+ */
+export declare function validateFullConfig(authentikConfig: Partial<AuthentikCallbackConfig>, supabaseConfig: Partial<SupabaseSyncConfig>): ConfigValidationResult;
+/**
+ * Discover OIDC endpoint URLs from an Authentik issuer's
+ * `.well-known/openid-configuration`.
+ *
+ * **Important:** Authentik places most OIDC endpoints (token, userinfo,
+ * authorize, revocation) at the `/application/o/` level, *not* under the
+ * per-app issuer path. For example, with:
+ *   issuer = `https://auth.example.com/application/o/my-app/`
+ * the token endpoint is:
+ *   `https://auth.example.com/application/o/token/`
+ *
+ * This function fetches the correct endpoint URLs from the well-known
+ * document so callers never need to guess.
+ *
+ * ```ts
+ * const endpoints = await discoverEndpoints("https://auth.example.com/application/o/my-app/");
+ * // endpoints.token      → "https://auth.example.com/application/o/token/"
+ * // endpoints.userinfo   → "https://auth.example.com/application/o/userinfo/"
+ * // endpoints.endSession → "https://auth.example.com/application/o/my-app/end-session/"
+ * ```
+ */
+export declare function discoverEndpoints(issuer: string, fetchFn?: typeof fetch): Promise<AuthentikEndpoints>;

package/dist/authentik/config.js

@@ -0,0 +1,169 @@
+/**
+ * Configuration validation / doctor helpers.
+ *
+ * These helpers detect missing or invalid configuration **before** the
+ * first real user login, so misconfigured environments fail fast.
+ *
+ * Reference: CIG `supabase_not_configured` callback error code.
+ */
+/* ------------------------------------------------------------------ */
+/*  Authentik config validation                                        */
+/* ------------------------------------------------------------------ */
+/**
+ * Validate that the core Authentik OIDC configuration is present and
+ * syntactically correct.
+ *
+ * This does **not** make network requests — it only checks that the
+ * required values are set and look reasonable.
+ */
+export function validateAuthentikConfig(config) {
+    const checks = [];
+    // issuer
+    checks.push(config.issuer
+        ? isValidUrl(config.issuer)
+            ? { name: "issuer", passed: true, message: "Issuer URL is valid", severity: "error" }
+            : { name: "issuer", passed: false, message: `Issuer is not a valid URL: ${config.issuer}`, severity: "error" }
+        : { name: "issuer", passed: false, message: "Authentik issuer URL is required", severity: "error" });
+    // clientId
+    checks.push(config.clientId
+        ? { name: "clientId", passed: true, message: "Client ID is set", severity: "error" }
+        : { name: "clientId", passed: false, message: "Authentik client_id is required", severity: "error" });
+    // redirectUri
+    checks.push(config.redirectUri
+        ? isValidUrl(config.redirectUri)
+            ? { name: "redirectUri", passed: true, message: "Redirect URI is valid", severity: "error" }
+            : { name: "redirectUri", passed: false, message: `Redirect URI is not a valid URL: ${config.redirectUri}`, severity: "error" }
+        : { name: "redirectUri", passed: false, message: "Redirect URI is required", severity: "error" });
+    // tokenEndpoint
+    checks.push(config.tokenEndpoint
+        ? isValidUrl(config.tokenEndpoint)
+            ? { name: "tokenEndpoint", passed: true, message: "Token endpoint URL is valid", severity: "error" }
+            : { name: "tokenEndpoint", passed: false, message: `Token endpoint is not a valid URL: ${config.tokenEndpoint}`, severity: "error" }
+        : { name: "tokenEndpoint", passed: false, message: "Token endpoint URL is required — use discoverEndpoints() or supply manually", severity: "error" });
+    // userinfoEndpoint
+    checks.push(config.userinfoEndpoint
+        ? isValidUrl(config.userinfoEndpoint)
+            ? { name: "userinfoEndpoint", passed: true, message: "Userinfo endpoint URL is valid", severity: "error" }
+            : { name: "userinfoEndpoint", passed: false, message: `Userinfo endpoint is not a valid URL: ${config.userinfoEndpoint}`, severity: "error" }
+        : { name: "userinfoEndpoint", passed: false, message: "Userinfo endpoint URL is required — use discoverEndpoints() or supply manually", severity: "error" });
+    return {
+        valid: checks.every((c) => c.passed),
+        checks,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  Supabase sync config validation                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Validate the server-side Supabase sync configuration.
+ *
+ * Returns a diagnostic result with the exact error code
+ * `supabase_not_configured` when the Supabase URL or service role key
+ * is missing, matching the CIG convention.
+ */
+export function validateSupabaseSyncConfig(config) {
+    const checks = [];
+    // supabaseUrl
+    checks.push(config.supabaseUrl
+        ? isValidUrl(config.supabaseUrl)
+            ? { name: "supabaseUrl", passed: true, message: "Supabase URL is valid", severity: "error" }
+            : { name: "supabaseUrl", passed: false, message: `Supabase URL is not a valid URL: ${config.supabaseUrl}`, severity: "error" }
+        : { name: "supabaseUrl", passed: false, message: "supabase_not_configured: Supabase URL is required for sync", severity: "error" });
+    // supabaseServiceRoleKey
+    checks.push(config.supabaseServiceRoleKey
+        ? config.supabaseServiceRoleKey.length >= 20
+            ? { name: "supabaseServiceRoleKey", passed: true, message: "Service role key is set", severity: "error" }
+            : { name: "supabaseServiceRoleKey", passed: false, message: "Service role key appears too short", severity: "warning" }
+        : { name: "supabaseServiceRoleKey", passed: false, message: "supabase_not_configured: Supabase service_role key is required for sync", severity: "error" });
+    // upsertRpcName (optional, warn if customised)
+    if (config.upsertRpcName && config.upsertRpcName !== "upsert_oidc_user") {
+        checks.push({
+            name: "upsertRpcName",
+            passed: true,
+            message: `Custom RPC name: ${config.upsertRpcName}`,
+            severity: "warning",
+        });
+    }
+    return {
+        valid: checks.filter((c) => c.severity === "error").every((c) => c.passed),
+        checks,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  Combined validation                                                */
+/* ------------------------------------------------------------------ */
+/**
+ * Validate both Authentik and Supabase sync configuration in one call.
+ *
+ * Useful as a startup / health-check / deploy-time validation gate.
+ */
+export function validateFullConfig(authentikConfig, supabaseConfig) {
+    const authentik = validateAuthentikConfig(authentikConfig);
+    const supabase = validateSupabaseSyncConfig(supabaseConfig);
+    const checks = [...authentik.checks, ...supabase.checks];
+    return {
+        valid: checks.filter((c) => c.severity === "error").every((c) => c.passed),
+        checks,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+function isValidUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Endpoint discovery                                                 */
+/* ------------------------------------------------------------------ */
+/**
+ * Discover OIDC endpoint URLs from an Authentik issuer's
+ * `.well-known/openid-configuration`.
+ *
+ * **Important:** Authentik places most OIDC endpoints (token, userinfo,
+ * authorize, revocation) at the `/application/o/` level, *not* under the
+ * per-app issuer path. For example, with:
+ *   issuer = `https://auth.example.com/application/o/my-app/`
+ * the token endpoint is:
+ *   `https://auth.example.com/application/o/token/`
+ *
+ * This function fetches the correct endpoint URLs from the well-known
+ * document so callers never need to guess.
+ *
+ * ```ts
+ * const endpoints = await discoverEndpoints("https://auth.example.com/application/o/my-app/");
+ * // endpoints.token      → "https://auth.example.com/application/o/token/"
+ * // endpoints.userinfo   → "https://auth.example.com/application/o/userinfo/"
+ * // endpoints.endSession → "https://auth.example.com/application/o/my-app/end-session/"
+ * ```
+ */
+export async function discoverEndpoints(issuer, fetchFn = fetch) {
+    const base = issuer.endsWith("/") ? issuer : `${issuer}/`;
+    const wellKnownUrl = `${base}.well-known/openid-configuration`;
+    const response = await fetchFn(wellKnownUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch .well-known/openid-configuration from ${wellKnownUrl} (HTTP ${response.status})`);
+    }
+    const doc = (await response.json());
+    const authorization = doc.authorization_endpoint;
+    const token = doc.token_endpoint;
+    const userinfo = doc.userinfo_endpoint;
+    if (typeof authorization !== "string" ||
+        typeof token !== "string" ||
+        typeof userinfo !== "string") {
+        throw new Error("Well-known document missing required endpoints (authorization_endpoint, token_endpoint, userinfo_endpoint)");
+    }
+    return {
+        authorization,
+        token,
+        userinfo,
+        revocation: typeof doc.revocation_endpoint === "string" ? doc.revocation_endpoint : undefined,
+        endSession: typeof doc.end_session_endpoint === "string" ? doc.end_session_endpoint : undefined,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/authentik/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @edcalderon/auth — Authentik flow + provisioning kit.
+ *
+ * Barrel export that assembles all Authentik-specific modules into a
+ * single importable surface area.
+ *
+ * Usage:
+ *   import { processCallback, orchestrateLogout, ... } from "@edcalderon/auth/authentik";
+ */
+export type { AuthentikProvider, AuthentikEndpoints, AuthentikRelayConfig, RelayIncomingParams, RelayHandlerResult, AuthentikCallbackConfig, AuthentikTokenResponse, AuthentikClaims, AuthentikCallbackResult, AuthentikLogoutConfig, AuthentikLogoutResult, ProvisioningPayload, ProvisioningResult, ProvisioningAdapter, SupabaseSyncConfig, ConfigValidationResult, ConfigCheck, SafeRedirectConfig, } from "./types";
+export { createRelayPageHtml, parseRelayParams, readRelayStorage, clearRelayStorage, } from "./relay";
+export { exchangeCode, fetchClaims, processCallback, } from "./callback";
+export type { ProcessCallbackOptions, ProcessCallbackResult, } from "./callback";
+export { revokeToken, buildEndSessionUrl, orchestrateLogout, } from "./logout";
+export { NoopProvisioningAdapter, createProvisioningAdapter, normalizePayload, SupabaseSyncAdapter, createSupabaseSyncAdapter, } from "./provisioning";
+export { validateAuthentikConfig, validateSupabaseSyncConfig, validateFullConfig, discoverEndpoints, } from "./config";
+export { resolveSafeRedirect } from "./redirect";

package/dist/authentik/index.js

@@ -0,0 +1,22 @@
+/**
+ * @edcalderon/auth — Authentik flow + provisioning kit.
+ *
+ * Barrel export that assembles all Authentik-specific modules into a
+ * single importable surface area.
+ *
+ * Usage:
+ *   import { processCallback, orchestrateLogout, ... } from "@edcalderon/auth/authentik";
+ */
+// Relay
+export { createRelayPageHtml, parseRelayParams, readRelayStorage, clearRelayStorage, } from "./relay";
+// Callback
+export { exchangeCode, fetchClaims, processCallback, } from "./callback";
+// Logout
+export { revokeToken, buildEndSessionUrl, orchestrateLogout, } from "./logout";
+// Provisioning
+export { NoopProvisioningAdapter, createProvisioningAdapter, normalizePayload, SupabaseSyncAdapter, createSupabaseSyncAdapter, } from "./provisioning";
+// Config validation
+export { validateAuthentikConfig, validateSupabaseSyncConfig, validateFullConfig, discoverEndpoints, } from "./config";
+// Safe redirect
+export { resolveSafeRedirect } from "./redirect";
+//# sourceMappingURL=index.js.map

package/dist/authentik/logout.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Authentik logout orchestrator.
+ *
+ * A correct Authentik logout requires all of these steps in sequence:
+ * 1. Clear app-local session state
+ * 2. Revoke the access token (best-effort)
+ * 3. Build the RP-initiated logout URL with id_token_hint
+ * 4. Navigate the browser to the end-session URL
+ *
+ * Reference: CIG apps/landing/components/AuthProvider.tsx signOut()
+ */
+import type { AuthentikLogoutConfig, AuthentikLogoutResult } from "./types";
+/**
+ * Revoke an OAuth2 token at the Authentik revocation endpoint.
+ *
+ * This is a **best-effort** operation — revocation failures do not
+ * prevent logout from completing. Returns `true` if the server
+ * responded with 2xx.
+ *
+ * If `config.revocationEndpoint` is not set, revocation is skipped
+ * and the function returns `false`.
+ */
+export declare function revokeToken(config: AuthentikLogoutConfig, accessToken: string): Promise<boolean>;
+/**
+ * Build the Authentik RP-initiated logout URL.
+ *
+ * The resulting URL, when navigated to, will:
+ * 1. Clear the Authentik browser session
+ * 2. Redirect back to `postLogoutRedirectUri`
+ *
+ * Requires that the Authentik provider has an **invalidation flow**
+ * configured with a "User Logout" stage and a redirect stage.
+ */
+export declare function buildEndSessionUrl(config: AuthentikLogoutConfig, idToken?: string): string;
+/**
+ * Execute the full Authentik logout sequence:
+ *
+ * 1. Revoke the access token (best-effort)
+ * 2. Build the RP-initiated end-session URL
+ *
+ * The caller is responsible for:
+ * - Clearing app-local session state **before** calling this function
+ * - Navigating the browser to `result.endSessionUrl` **after** this returns
+ *
+ * This design keeps the orchestrator framework-agnostic.
+ */
+export declare function orchestrateLogout(config: AuthentikLogoutConfig, tokens: {
+    accessToken?: string;
+    idToken?: string;
+}): Promise<AuthentikLogoutResult>;

package/dist/authentik/logout.js

@@ -0,0 +1,96 @@
+/**
+ * Authentik logout orchestrator.
+ *
+ * A correct Authentik logout requires all of these steps in sequence:
+ * 1. Clear app-local session state
+ * 2. Revoke the access token (best-effort)
+ * 3. Build the RP-initiated logout URL with id_token_hint
+ * 4. Navigate the browser to the end-session URL
+ *
+ * Reference: CIG apps/landing/components/AuthProvider.tsx signOut()
+ */
+/* ------------------------------------------------------------------ */
+/*  Token revocation                                                   */
+/* ------------------------------------------------------------------ */
+/**
+ * Revoke an OAuth2 token at the Authentik revocation endpoint.
+ *
+ * This is a **best-effort** operation — revocation failures do not
+ * prevent logout from completing. Returns `true` if the server
+ * responded with 2xx.
+ *
+ * If `config.revocationEndpoint` is not set, revocation is skipped
+ * and the function returns `false`.
+ */
+export async function revokeToken(config, accessToken) {
+    if (!config.revocationEndpoint) {
+        return false;
+    }
+    const revocationUrl = config.revocationEndpoint;
+    const fetchFn = config.fetchFn || fetch;
+    const body = new URLSearchParams({
+        token: accessToken,
+        token_type_hint: "access_token",
+    });
+    if (config.clientId) {
+        body.set("client_id", config.clientId);
+    }
+    try {
+        const response = await fetchFn(revocationUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body,
+        });
+        return response.ok;
+    }
+    catch {
+        // Revocation is best-effort
+        return false;
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  RP-initiated logout URL                                            */
+/* ------------------------------------------------------------------ */
+/**
+ * Build the Authentik RP-initiated logout URL.
+ *
+ * The resulting URL, when navigated to, will:
+ * 1. Clear the Authentik browser session
+ * 2. Redirect back to `postLogoutRedirectUri`
+ *
+ * Requires that the Authentik provider has an **invalidation flow**
+ * configured with a "User Logout" stage and a redirect stage.
+ */
+export function buildEndSessionUrl(config, idToken) {
+    const endSessionUrl = config.endSessionEndpoint;
+    const url = new URL(endSessionUrl);
+    if (idToken) {
+        url.searchParams.set("id_token_hint", idToken);
+    }
+    url.searchParams.set("post_logout_redirect_uri", config.postLogoutRedirectUri);
+    return url.toString();
+}
+/* ------------------------------------------------------------------ */
+/*  Full logout orchestration                                          */
+/* ------------------------------------------------------------------ */
+/**
+ * Execute the full Authentik logout sequence:
+ *
+ * 1. Revoke the access token (best-effort)
+ * 2. Build the RP-initiated end-session URL
+ *
+ * The caller is responsible for:
+ * - Clearing app-local session state **before** calling this function
+ * - Navigating the browser to `result.endSessionUrl` **after** this returns
+ *
+ * This design keeps the orchestrator framework-agnostic.
+ */
+export async function orchestrateLogout(config, tokens) {
+    let tokenRevoked = false;
+    if (tokens.accessToken) {
+        tokenRevoked = await revokeToken(config, tokens.accessToken);
+    }
+    const endSessionUrl = buildEndSessionUrl(config, tokens.idToken);
+    return { endSessionUrl, tokenRevoked };
+}
+//# sourceMappingURL=logout.js.map