@edcalderon/auth 1.2.2 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [1.4.0] - 2026-03-23
+
+### Added
+
+- ✨ **Authentik flow + provisioning kit** (`@edcalderon/auth/authentik`) — a reusable set of helpers generalised from the production CIG Authentik implementation.
+- 🔀 **Cross-origin PKCE relay** — `createRelayPageHtml()`, `parseRelayParams()`, `readRelayStorage()`, `clearRelayStorage()` for apps where login UI and callback handler live on different origins.
+- 🔄 **Enhanced callback handler** — `exchangeCode()`, `fetchClaims()`, `processCallback()` with blocking provisioning gate that prevents redirect until user sync completes.
+- 🚪 **Logout orchestrator** — `revokeToken()`, `buildEndSessionUrl()`, `orchestrateLogout()` implementing the full RP-initiated logout flow.
+- 🔌 **Provisioning adapter layer** — pluggable adapters: `NoopProvisioningAdapter`, `createProvisioningAdapter()`, `SupabaseSyncAdapter` with identity-first matching and rollback on failure.
+- 🏥 **Config validation / doctor** — `validateAuthentikConfig()`, `validateSupabaseSyncConfig()`, `validateFullConfig()` for startup / deploy-time validation (detects `supabase_not_configured`).
+- 🛡️ **Safe redirect resolver** — `resolveSafeRedirect()` with origin allowlist to prevent open-redirect vulnerabilities.
+- 📦 **New subpath export** — `@edcalderon/auth/authentik` barrel export for all Authentik-specific modules.
+- 🗄️ **SQL migration 003** — `003_authentik_shadow_auth_users.sql` adds shadow auth user linkage columns and `link_shadow_auth_user()` RPC.
+- 🧪 **96 tests** across 6 test suites covering relay, callback, logout, provisioning (incl. paginated page-2 lookups, shadow linkage RPC, rollback), config validation (incl. endpoint discovery), and redirect safety.
+
+## [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

package/README.md

@@ -11,16 +11,20 @@ Swap between Supabase, Firebase, Hybrid, or any custom provider without changing
 
 ---
 
-## 📋 Latest Changes (v1.2.2)
+## 📋 Latest Changes (v1.4.0)
 
 ### 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.
+- ✨ **Authentik flow + provisioning kit** (`@edcalderon/auth/authentik`) — a reusable set of helpers generalised from the production CIG Authentik implementation.
+- 🔀 **Cross-origin PKCE relay** — `createRelayPageHtml()`, `parseRelayParams()`, `readRelayStorage()`, `clearRelayStorage()` for apps where login UI and callback handler live on different origins.
+- 🔄 **Enhanced callback handler** — `exchangeCode()`, `fetchClaims()`, `processCallback()` with blocking provisioning gate that prevents redirect until user sync completes.
+- 🚪 **Logout orchestrator** — `revokeToken()`, `buildEndSessionUrl()`, `orchestrateLogout()` implementing the full RP-initiated logout flow.
+- 🔌 **Provisioning adapter layer** — pluggable adapters: `NoopProvisioningAdapter`, `createProvisioningAdapter()`, `SupabaseSyncAdapter` with identity-first matching and rollback on failure.
+- 🏥 **Config validation / doctor** — `validateAuthentikConfig()`, `validateSupabaseSyncConfig()`, `validateFullConfig()` for startup / deploy-time validation (detects `supabase_not_configured`).
+- 🛡️ **Safe redirect resolver** — `resolveSafeRedirect()` with origin allowlist to prevent open-redirect vulnerabilities.
+- 📦 **New subpath export** — `@edcalderon/auth/authentik` barrel export for all Authentik-specific modules.
+- 🗄️ **SQL migration 003** — `003_authentik_shadow_auth_users.sql` adds shadow auth user linkage columns and `link_shadow_auth_user()` RPC.
+- 🧪 **96 tests** across 6 test suites covering relay, callback, logout, provisioning (incl. paginated page-2 lookups, shadow linkage RPC, rollback), config validation (incl. endpoint discovery), and redirect safety.
 
 For full version history, see [CHANGELOG.md](./CHANGELOG.md) and [GitHub releases](https://github.com/edcalderon/my-second-brain/releases)
 
@@ -79,6 +83,68 @@ If you want an application-owned user table instead of coupling your identity mo
 - `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,284 @@
+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();
+    }
+    // Authentik OAuth endpoints (authorize, token, userinfo) live at the parent
+    // of the issuer path: issuer = /application/o/<slug>/, endpoint = /application/o/<ep>/.
+    const base = ensurePathSuffix(issuer);
+    return new URL(`../${fallbackPath}`, base).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/authentik/callback.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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
+ */
+import type { AuthentikCallbackConfig, AuthentikCallbackResult, AuthentikTokenResponse, AuthentikClaims, ProvisioningAdapter, ProvisioningResult } from "./types";
+/**
+ * Exchange an authorization code for tokens using PKCE.
+ *
+ * This is a pure server-safe function — it does not touch sessionStorage.
+ */
+export declare function exchangeCode(config: AuthentikCallbackConfig, code: string, codeVerifier: string): Promise<AuthentikTokenResponse>;
+/**
+ * Fetch OIDC claims from the Authentik userinfo endpoint.
+ */
+export declare function fetchClaims(config: AuthentikCallbackConfig, accessToken: string): Promise<AuthentikClaims>;
+/**
+ * Options for the full callback handler.
+ */
+export interface ProcessCallbackOptions {
+    /** Callback config (issuer, clientId, redirectUri, etc.). */
+    config: AuthentikCallbackConfig;
+    /** The authorization code from the callback query string. */
+    code: string;
+    /** The PKCE code verifier stored by the relay or startOAuthFlow. */
+    codeVerifier: string;
+    /** The state token from the callback query string. */
+    state: string;
+    /** The expected state token (from sessionStorage / relay). */
+    expectedState: string;
+    /** The social-login provider that initiated the flow. */
+    provider: string;
+    /**
+     * Optional provisioning adapter.
+     * When provided the callback will **block** until provisioning succeeds.
+     * If provisioning fails the result will contain the error.
+     */
+    provisioningAdapter?: ProvisioningAdapter;
+}
+/**
+ * Result of the full callback flow.
+ */
+export interface ProcessCallbackResult {
+    /** Whether the entire flow (exchange + provisioning) succeeded. */
+    success: boolean;
+    /** Tokens + claims from the exchange step. */
+    callbackResult?: AuthentikCallbackResult;
+    /** Provisioning result (only present when an adapter was provided). */
+    provisioningResult?: ProvisioningResult;
+    /** Error message on failure. */
+    error?: string;
+    /** Machine-readable error code on failure. */
+    errorCode?: string;
+}
+/**
+ * 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 declare function processCallback(options: ProcessCallbackOptions): Promise<ProcessCallbackResult>;