npm - @edcalderon/auth - Versions diffs - 1.2.2 → 1.4.0 - Mend

@edcalderon/auth 1.2.2 → 1.4.0

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 (24) hide show

package/CHANGELOG.md +23 -0
package/README.md +73 -7
package/dist/AuthentikOidcClient.d.ts +58 -0
package/dist/AuthentikOidcClient.js +284 -0
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/dist/index.d.ts +1 -0
package/dist/index.js +1 -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

package/dist/index.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@edcalderon/auth",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "A universal, provider-agnostic authentication package (Web + Next.js + Expo/React Native)",
   "exports": {
     ".": {
@@ -9,6 +9,11 @@
       "require": "./dist/index.js",
       "react-native": "./dist/index.js"
     },
+    "./authentik": {
+      "types": "./dist/authentik/index.d.ts",
+      "import": "./dist/authentik/index.js",
+      "require": "./dist/authentik/index.js"
+    },
     "./supabase": {
       "types": "./dist/providers/SupabaseClient.d.ts",
       "import": "./dist/providers/SupabaseClient.js",
@@ -42,6 +47,9 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "prepublishOnly": "npm run build",
     "update-readme": "versioning update-readme"
   },
@@ -90,10 +98,20 @@
     }
   },
   "devDependencies": {
+    "@types/jest": "^29.5.12",
     "@types/react": "^19.2.7",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
     "typescript": "^5.9.3"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": ["**/__tests__/**/*.test.ts"],
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    }
   }
 }

package/supabase/migrations/003_authentik_shadow_auth_users.sql ADDED Viewed

@@ -0,0 +1,81 @@
+-- ============================================================================
+-- 003_authentik_shadow_auth_users.sql
+-- Optional migration for projects using the Authentik ↔ Supabase integrated
+-- sync mode in @edcalderon/auth.
+--
+-- This migration adds app_metadata columns and an index to support the
+-- shadow auth.users pattern where Authentik-authenticated users are mirrored
+-- into Supabase auth.users with identity-first matching.
+--
+-- The public.users table is already created by 001_create_app_users.sql.
+-- This migration adds columns to support the shadow-user linkage and
+-- rollback-safe provisioning.
+--
+-- Reference: CIG apps/dashboard/lib/authSync.ts
+-- ============================================================================
+-- Add optional column to track the linked Supabase auth.users shadow ID
+alter table public.users
+  add column if not exists shadow_auth_user_id uuid;
+-- Add optional column to record when the shadow link was established
+alter table public.users
+  add column if not exists shadow_linked_at timestamptz;
+-- Index for quick lookup by shadow auth user ID
+create index if not exists users_shadow_auth_user_id_idx
+  on public.users (shadow_auth_user_id)
+  where shadow_auth_user_id is not null;
+-- ============================================================================
+-- Helper RPC: link a public.users row to a Supabase auth.users shadow record.
+-- Called by the SupabaseSyncAdapter after creating/finding the shadow user.
+--
+-- This is an additive helper — the core upsert_oidc_user RPC from migration
+-- 001 continues to work unchanged.  The raw_claims payload can optionally
+-- carry shadow_supabase_auth_user_id to record the linkage.
+-- ============================================================================
+create or replace function public.link_shadow_auth_user(
+  p_sub               text,
+  p_iss               text,
+  p_shadow_auth_user_id uuid
+)
+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 'link_shadow_auth_user() requires a trusted server-side caller';
+  end if;
+  update public.users
+    set shadow_auth_user_id = p_shadow_auth_user_id,
+        shadow_linked_at    = timezone('utc', now()),
+        updated_at          = timezone('utc', now())
+  where sub = p_sub
+    and iss = p_iss
+  returning * into v_user;
+  if not found then
+    raise exception 'No public.users row found for sub=% iss=%', p_sub, p_iss;
+  end if;
+  return v_user;
+end;
+$$;
+revoke all on function public.link_shadow_auth_user(text, text, uuid)
+  from public, anon, authenticated;
+grant execute on function public.link_shadow_auth_user(text, text, uuid)
+  to service_role;