npm - @edcalderon/auth - Versions diffs - 1.3.0 → 1.4.1 - Mend

@edcalderon/auth 1.3.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/CHANGELOG.md +22 -0
package/README.md +4 -4
package/dist/AuthentikOidcClient.js +4 -2
package/dist/authentik/callback.d.ts +71 -0
package/dist/authentik/callback.js +163 -0
package/dist/authentik/config.d.ts +53 -0
package/dist/authentik/config.js +169 -0
package/dist/authentik/index.d.ts +17 -0
package/dist/authentik/index.js +22 -0
package/dist/authentik/logout.d.ts +50 -0
package/dist/authentik/logout.js +96 -0
package/dist/authentik/provisioning.d.ts +124 -0
package/dist/authentik/provisioning.js +342 -0
package/dist/authentik/redirect.d.ts +20 -0
package/dist/authentik/redirect.js +52 -0
package/dist/authentik/relay.d.ts +48 -0
package/dist/authentik/relay.js +146 -0
package/dist/authentik/types.d.ts +264 -0
package/dist/authentik/types.js +8 -0
package/docs/authentik-integration-guide.md +286 -0
package/docs/cig-reference-map.md +118 -0
package/docs/nextjs-examples.md +784 -0
package/docs/provisioning-model.md +416 -0
package/docs/upgrade-migration.md +256 -0
package/package.json +19 -1
package/supabase/migrations/003_authentik_shadow_auth_users.sql +81 -0

package/dist/authentik/relay.js ADDED Viewed

@@ -0,0 +1,146 @@
+/**
+ * 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
+ */
+const DEFAULT_SCOPE = "openid profile email";
+const DEFAULT_STORAGE_KEY_PREFIX = "authentik_relay";
+/**
+ * Resolve the Authentik flow URL for a provider.
+ *
+ * If `providerFlowSlugs` maps the provider to a custom flow, the URL is:
+ *   `{issuerOrigin}/if/flow/{flowSlug}/?next={authorizeUrl}`
+ *
+ * Otherwise falls back to the Authentik source-based social login:
+ *   `{issuerOrigin}/source/oauth/login/{provider}/?next={authorizeUrl}`
+ */
+function buildFlowUrl(config, provider, authorizeUrl) {
+    const issuerOrigin = new URL(config.issuer).origin;
+    const flowSlug = config.providerFlowSlugs?.[provider];
+    if (flowSlug) {
+        const url = new URL(`/if/flow/${encodeURIComponent(flowSlug)}/`, issuerOrigin);
+        url.searchParams.set("next", authorizeUrl);
+        return url.toString();
+    }
+    const url = new URL(`/source/oauth/login/${encodeURIComponent(provider)}/`, issuerOrigin);
+    url.searchParams.set("next", authorizeUrl);
+    return url.toString();
+}
+/**
+ * Build the OIDC authorize URL that Authentik will redirect to after the
+ * social-provider flow completes.
+ */
+function buildAuthorizeUrl(config, params) {
+    const url = new URL(config.authorizePath);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", config.clientId);
+    url.searchParams.set("redirect_uri", config.redirectUri);
+    url.searchParams.set("scope", config.scope || DEFAULT_SCOPE);
+    url.searchParams.set("state", params.state);
+    url.searchParams.set("code_challenge", params.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    return url.toString();
+}
+/**
+ * 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 function createRelayPageHtml(config, params) {
+    const authorizeUrl = buildAuthorizeUrl(config, params);
+    const flowUrl = buildFlowUrl(config, params.provider, authorizeUrl);
+    const prefix = config.storageKeyPrefix || DEFAULT_STORAGE_KEY_PREFIX;
+    // Escape for safe embedding in a <script> block
+    const safeJson = (v) => JSON.stringify(v).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+    const html = [
+        "<!DOCTYPE html>",
+        "<html><head><meta charset=\"utf-8\"><title>Redirecting…</title></head>",
+        "<body>",
+        "<p>Redirecting to login…</p>",
+        "<script>",
+        "(function(){",
+        `  try{`,
+        `    var s=window.sessionStorage;`,
+        `    s.setItem(${safeJson(`${prefix}:verifier`)},${safeJson(params.codeVerifier)});`,
+        `    s.setItem(${safeJson(`${prefix}:state`)},${safeJson(params.state)});`,
+        `    s.setItem(${safeJson(`${prefix}:provider`)},${safeJson(params.provider)});`,
+        params.next
+            ? `    s.setItem(${safeJson(`${prefix}:next`)},${safeJson(params.next)});`
+            : "",
+        `  }catch(e){console.error("relay storage error",e);}`,
+        `  window.location.replace(${safeJson(flowUrl)});`,
+        "})();",
+        "</script>",
+        "</body></html>",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return { html };
+}
+/**
+ * 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 function parseRelayParams(searchParams) {
+    const get = (key) => {
+        if (searchParams instanceof URLSearchParams) {
+            return searchParams.get(key) ?? undefined;
+        }
+        return searchParams[key];
+    };
+    const codeVerifier = get("code_verifier");
+    const codeChallenge = get("code_challenge");
+    const state = get("state");
+    const provider = get("provider");
+    if (!codeVerifier || !codeChallenge || !state || !provider) {
+        return null;
+    }
+    return {
+        provider,
+        codeVerifier,
+        codeChallenge,
+        state,
+        next: get("next"),
+    };
+}
+/**
+ * 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 function readRelayStorage(storage, prefix = DEFAULT_STORAGE_KEY_PREFIX) {
+    const codeVerifier = storage.getItem(`${prefix}:verifier`);
+    const state = storage.getItem(`${prefix}:state`);
+    const provider = storage.getItem(`${prefix}:provider`);
+    if (!codeVerifier || !state || !provider) {
+        return null;
+    }
+    const next = storage.getItem(`${prefix}:next`) ?? undefined;
+    return { codeVerifier, state, provider, next };
+}
+/**
+ * Clean up relay storage after a successful callback exchange.
+ */
+export function clearRelayStorage(storage, prefix = DEFAULT_STORAGE_KEY_PREFIX) {
+    storage.removeItem(`${prefix}:verifier`);
+    storage.removeItem(`${prefix}:state`);
+    storage.removeItem(`${prefix}:provider`);
+    storage.removeItem(`${prefix}:next`);
+}
+//# sourceMappingURL=relay.js.map

package/dist/authentik/types.d.ts ADDED Viewed

@@ -0,0 +1,264 @@
+/**
+ * @edcalderon/auth — Authentik flow + provisioning kit types.
+ *
+ * Generalised from the production CIG implementation:
+ * https://github.com/edwardcalderon/ComputeIntelligenceGraph/tree/main/packages/auth
+ */
+/** Well-known social-login provider slugs, plus any custom string. */
+export type AuthentikProvider = "google" | "github" | "discord" | (string & {});
+/**
+ * Resolved OIDC endpoint URLs for an Authentik provider.
+ *
+ * These can be obtained from `.well-known/openid-configuration`
+ * via `discoverEndpoints()`, or supplied manually.
+ *
+ * **Important:** Authentik places most OIDC endpoints at the
+ * `/application/o/` level, *not* under the per-app issuer path.
+ * E.g. with issuer `https://auth.example.com/application/o/my-app/`,
+ * the token endpoint is `https://auth.example.com/application/o/token/`.
+ * Always use explicit URLs or discovery — do not guess from the issuer.
+ */
+export interface AuthentikEndpoints {
+    /** Authorization endpoint (full URL). */
+    authorization: string;
+    /** Token endpoint (full URL). */
+    token: string;
+    /** Userinfo endpoint (full URL). */
+    userinfo: string;
+    /** Token revocation endpoint (full URL). */
+    revocation?: string;
+    /** RP-initiated logout / end-session endpoint (full URL). */
+    endSession?: string;
+}
+/** Configuration for the cross-origin relay handler. */
+export interface AuthentikRelayConfig {
+    /** Authentik issuer base URL (e.g. "https://auth.example.com"). */
+    issuer: string;
+    /** OIDC Application client_id registered in Authentik. */
+    clientId: string;
+    /** The callback URL that will receive the authorization code. */
+    redirectUri: string;
+    /** OIDC scopes (default: "openid profile email"). */
+    scope?: string;
+    /**
+     * Explicit OIDC authorize endpoint URL.
+     * Required — use `discoverEndpoints()` or supply manually.
+     */
+    authorizePath: string;
+    /**
+     * Map of provider slug → Authentik flow slug.
+     * E.g. `{ google: "my-app-google-login", github: "my-app-github-login" }`.
+     * When a provider is not in the map the provider string is used as-is.
+     */
+    providerFlowSlugs?: Record<string, string>;
+    /**
+     * Storage key prefix used for PKCE state in sessionStorage.
+     * Default: "authentik_relay".
+     */
+    storageKeyPrefix?: string;
+}
+/** Parsed query params forwarded from the login origin to the relay. */
+export interface RelayIncomingParams {
+    provider: string;
+    codeVerifier: string;
+    codeChallenge: string;
+    state: string;
+    /** Optional post-login redirect target within the app. */
+    next?: string;
+}
+/** Result of the relay handler — an HTML snippet or a redirect URL. */
+export interface RelayHandlerResult {
+    /** Minimal HTML page that stores PKCE params and redirects to Authentik. */
+    html: string;
+}
+/** Configuration for the enhanced callback handler. */
+export interface AuthentikCallbackConfig {
+    /** Authentik issuer base URL. */
+    issuer: string;
+    /** OIDC Application client_id. */
+    clientId: string;
+    /** The callback URL that received the authorization code. */
+    redirectUri: string;
+    /** OIDC scopes (default: "openid profile email"). */
+    scope?: string;
+    /**
+     * Explicit token endpoint URL.
+     * Required — use `discoverEndpoints()` or supply manually.
+     */
+    tokenEndpoint: string;
+    /**
+     * Explicit userinfo endpoint URL.
+     * Required — use `discoverEndpoints()` or supply manually.
+     */
+    userinfoEndpoint: string;
+    /** Fetch implementation override (for testing or server runtimes). */
+    fetchFn?: typeof fetch;
+}
+/** The raw OIDC token response from Authentik. */
+export interface AuthentikTokenResponse {
+    access_token: string;
+    token_type?: string;
+    refresh_token?: string;
+    id_token?: string;
+    expires_in?: number;
+    scope?: string;
+}
+/** Parsed OIDC claims from the userinfo endpoint. */
+export interface AuthentikClaims {
+    sub: string;
+    iss: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    preferred_username?: string;
+    picture?: string;
+    [key: string]: unknown;
+}
+/** Tokens + claims obtained after a successful callback exchange. */
+export interface AuthentikCallbackResult {
+    tokens: AuthentikTokenResponse;
+    claims: AuthentikClaims;
+    provider: string;
+}
+/** Configuration for the logout orchestrator. */
+export interface AuthentikLogoutConfig {
+    /** Authentik issuer base URL. */
+    issuer: string;
+    /** URL the browser should land on after Authentik clears its session. */
+    postLogoutRedirectUri: string;
+    /**
+     * Explicit RP-initiated end-session endpoint URL.
+     * Required — use `discoverEndpoints()` or supply manually.
+     */
+    endSessionEndpoint: string;
+    /**
+     * Explicit token revocation endpoint URL.
+     * Optional — when omitted, revocation is skipped.
+     */
+    revocationEndpoint?: string;
+    /** OIDC Application client_id (used in token revocation). */
+    clientId?: string;
+    /** Fetch implementation override. */
+    fetchFn?: typeof fetch;
+}
+/** Result of a logout orchestration. */
+export interface AuthentikLogoutResult {
+    /** The full RP-initiated logout URL the browser should navigate to. */
+    endSessionUrl: string;
+    /** Whether the access-token revocation succeeded. */
+    tokenRevoked: boolean;
+}
+/**
+ * Payload sent to the provisioning adapter after a successful callback.
+ * Modelled after CIG's OidcSyncPayload.
+ */
+export interface ProvisioningPayload {
+    /** OIDC subject identifier. */
+    sub: string;
+    /** OIDC issuer URL. */
+    iss: string;
+    /** User email (normalised 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", "authentik"). */
+    provider?: string;
+    /** The full set of OIDC claims as received from Authentik. */
+    rawClaims?: Record<string, unknown>;
+}
+/**
+ * Result returned by a provisioning adapter.
+ * The `synced` flag **must** be `true` for the callback to proceed with redirect.
+ */
+export interface ProvisioningResult {
+    /** Whether the sync completed successfully. */
+    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 (for rollback tracking). */
+    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;
+}
+/**
+ * A provisioning adapter is a server-side function that ensures the
+ * Authentik-authenticated user exists in the application's local user store.
+ *
+ * Adapters must be **idempotent** and **fail-closed**: if provisioning fails
+ * the callback must not redirect the user into the protected app.
+ */
+export interface ProvisioningAdapter {
+    /**
+     * Sync the Authentik identity into the local user store.
+     * Must return `{ synced: true }` for the callback flow to succeed.
+     */
+    sync(payload: ProvisioningPayload): Promise<ProvisioningResult>;
+}
+/** Config for the Authentik ↔ Supabase integrated sync adapter. */
+export interface SupabaseSyncConfig {
+    /** Supabase project URL. */
+    supabaseUrl: string;
+    /** Supabase service_role key (server-side only). */
+    supabaseServiceRoleKey: string;
+    /**
+     * Name of the Supabase RPC function that upserts into public.users.
+     * Default: "upsert_oidc_user".
+     */
+    upsertRpcName?: string;
+    /**
+     * Name of the Supabase RPC function that links the shadow auth.users
+     * ID to the public.users row.
+     * Default: "link_shadow_auth_user".
+     */
+    linkShadowRpcName?: string;
+    /**
+     * Whether to create a shadow user in auth.users.
+     * Default: true (recommended for CIG-style setups).
+     */
+    createShadowAuthUser?: boolean;
+    /**
+     * Default OIDC issuer to use when payload.iss is not provided.
+     * Falls back to the Authentik issuer configured elsewhere.
+     */
+    defaultIssuer?: string;
+    /**
+     * Whether to rollback newly created shadow auth.users rows
+     * when downstream public.users sync fails.
+     * Default: true.
+     */
+    rollbackOnFailure?: boolean;
+}
+/** Diagnostic result from the config-validation doctor helper. */
+export interface ConfigValidationResult {
+    /** Whether the configuration is valid. */
+    valid: boolean;
+    /** Individual check results. */
+    checks: ConfigCheck[];
+}
+export interface ConfigCheck {
+    /** Short name of the check. */
+    name: string;
+    /** Whether this check passed. */
+    passed: boolean;
+    /** Human-readable message. */
+    message: string;
+    /** Severity when check fails. */
+    severity: "error" | "warning";
+}
+/** Configuration for the safe redirect resolver. */
+export interface SafeRedirectConfig {
+    /** Allowed origin(s) for redirects. */
+    allowedOrigins: string[];
+    /** Fallback URL when the requested redirect is not safe. */
+    fallbackUrl: string;
+}

package/dist/authentik/types.js ADDED Viewed

@@ -0,0 +1,8 @@
+/**
+ * @edcalderon/auth — Authentik flow + provisioning kit types.
+ *
+ * Generalised from the production CIG implementation:
+ * https://github.com/edwardcalderon/ComputeIntelligenceGraph/tree/main/packages/auth
+ */
+export {};
+//# sourceMappingURL=types.js.map