@luminaryworks/auth-react 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,356 @@
+import { UserManager } from 'oidc-client-ts';
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+interface LuminaryIdpConfig {
+    /**
+     * OIDC issuer. Prefer Auth Gateway (`http://localhost:3010/oidc`) so products
+     * stay IdP-agnostic; direct Logto issuer is OK for local MVP.
+     */
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+    /**
+     * Popup OIDC callback. Defaults to `redirectUri` (same `/auth/callback`).
+     * Must be registered on the IdP application.
+     */
+    popupRedirectUri?: string;
+    postLogoutRedirectUri?: string;
+    scopes?: string;
+    /** API resource indicator (access token `aud`) */
+    audience?: string;
+    /** localStorage key for access token */
+    tokenStorageKey?: string;
+    /**
+     * Logto Experience API base (no trailing slash), e.g. Auth Gateway
+     * `http://localhost:3010` or direct Logto `http://localhost:3001`.
+     * When set, Headless password sign-in is attempted before OIDC popup fallback.
+     */
+    experienceApiBase?: string;
+}
+interface LuminaryAuthSession {
+    accessToken: string;
+    idToken?: string;
+    expiresAt?: number;
+    profile?: Record<string, unknown>;
+}
+declare function isIdpConfigured(config: Partial<LuminaryIdpConfig>): config is LuminaryIdpConfig;
+/** Resolve issuer from Auth Gateway base URL or direct IDP_ISSUER. */
+declare function resolveIssuer(env: Record<string, string | undefined>): string | undefined;
+/** Derive Experience API host from Gateway URL or by stripping `/oidc` from issuer. */
+declare function resolveExperienceApiBase(env: Record<string, string | undefined>): string | undefined;
+declare function readIdpConfigFromEnv(env: Record<string, string | undefined>): Partial<LuminaryIdpConfig>;
+
+declare function createUserManager(config: LuminaryIdpConfig): UserManager;
+declare function resetUserManager(): void;
+interface SignInOptions {
+    returnUrl?: string;
+    /**
+     * Logto direct sign-in, e.g. `social:google` / `social:github` / `sso:<connectorId>`.
+     * Skips the hosted password page and opens the provider immediately.
+     */
+    directSignIn?: string;
+}
+declare function signInRedirect(config: LuminaryIdpConfig, returnUrlOrOptions?: string | SignInOptions): Promise<void>;
+/**
+ * Persist PKCE state (same store as {@link createUserManager}) and return the
+ * authorize URL — used by Experience headless bootstrap before navigating to
+ * `redirectTo` from `/api/experience/submit`.
+ */
+declare function prepareSignInRequestUrl(config: LuminaryIdpConfig, returnUrlOrOptions?: string | SignInOptions): Promise<string>;
+/**
+ * OIDC login in a popup window (not an iframe). Opener keeps SPA state;
+ * callback page in the popup must call {@link handleSignInPopupCallback}.
+ */
+declare function signInPopup(config: LuminaryIdpConfig, returnUrlOrOptions?: string | SignInOptions): Promise<{
+    session: LuminaryAuthSession;
+    returnUrl?: string;
+}>;
+declare function handleSignInCallback(config: LuminaryIdpConfig): Promise<{
+    session: LuminaryAuthSession;
+    returnUrl?: string;
+}>;
+/**
+ * Complete popup OIDC in the popup window. Notifies the opener and closes.
+ * Do not run product SSO exchange here — the opener handles that after signInPopup resolves.
+ */
+declare function handleSignInPopupCallback(config: LuminaryIdpConfig): Promise<void>;
+/** True when this window is likely an OIDC popup callback. */
+declare function isOidcPopupWindow(): boolean;
+declare function signOutRedirect(config: LuminaryIdpConfig): Promise<void>;
+declare function getStoredAccessToken(config: LuminaryIdpConfig): string | null;
+declare function clearStoredSession(config: LuminaryIdpConfig): void;
+declare function getCurrentUser(config: LuminaryIdpConfig): Promise<LuminaryAuthSession | null>;
+
+/**
+ * Logto Experience API (Headless) client.
+ * Prefer same-origin Experience base (SPA proxies /api/experience) so cookies work on HTTP localhost.
+ * @see https://docs.logto.io/docs/recipes/customize-token-claims (Experience API recipes)
+ */
+type ExperienceIdentifierType = "email" | "username" | "phone";
+interface ExperiencePasswordSignInInput {
+    /** Experience API origin (no trailing slash). Prefer SPA origin when proxied. */
+    apiBase: string;
+    identifier: string;
+    password: string;
+    identifierType?: ExperienceIdentifierType;
+    /** Required to bootstrap the OIDC interaction cookie before Experience calls. */
+    issuer?: string;
+    clientId?: string;
+    redirectUri?: string;
+    audience?: string;
+    scopes?: string;
+    /** Carried in OIDC state for post-login return (UserManager PKCE). */
+    returnUrl?: string;
+}
+interface ExperiencePasswordSignInResult {
+    /** Continue URL from Experience submit (complete OIDC interaction). */
+    redirectTo?: string;
+    raw?: unknown;
+}
+/**
+ * Force authorize onto the Experience/SPA origin so Set-Cookie lands on the same
+ * host as subsequent `/api/experience` calls (dev proxy strips Domain).
+ */
+declare function sameOriginAuthorizeUrl(authorizeUrl: string, apiBase: string): string;
+/**
+ * Headless password sign-in via Logto Experience API.
+ * Requires an OIDC interaction cookie (see {@link bootstrapOidcInteraction}) and
+ * same-site Experience calls (SPA proxy or Auth Gateway on the SPA origin).
+ *
+ * On success, follow {@link ExperiencePasswordSignInResult.redirectTo} in the same
+ * window — that URL completes the PKCE round-trip started by createSigninRequest.
+ * Do not start a second authorize (that shows Logto `/sign-in` again).
+ *
+ * Tries the guessed identifier type first, then the alternate email/username so
+ * users can sign in with either when both methods are enabled on the IdP.
+ */
+declare function experiencePasswordSignIn(input: ExperiencePasswordSignInInput): Promise<ExperiencePasswordSignInResult>;
+interface ExperienceSocialConnector {
+    id: string;
+    target: string;
+    name: string;
+    logo?: string;
+}
+/**
+ * Public Logto sign-in experience (no auth). Returns enabled social connectors
+ * in SIE order — use for Headless social buttons (google / github / x / …).
+ */
+declare function fetchSocialConnectors(input: {
+    /** Same origin as Experience / IdP (e.g. SPA proxy or http://localhost:3001). */
+    apiBase: string;
+    appId?: string;
+}): Promise<ExperienceSocialConnector[]>;
+
+/**
+ * AuthGate — single-flight 401 recovery with optional token refresh + reauth UI.
+ * Products wire tryRefresh / onReauthRequired; API clients call handleUnauthorized + waitIfBlocked.
+ */
+type AuthGatePhase = "idle" | "refreshing" | "reauth";
+type UnauthorizedDisposition = "retry" | "fail";
+interface AuthGateSnapshot {
+    phase: AuthGatePhase;
+    /** True while refresh or interactive reauth is in flight. */
+    blocked: boolean;
+    lastError?: string;
+}
+interface AuthGateConfig {
+    /**
+     * Attempt silent product-token (or OIDC) refresh before showing reauth UI.
+     * Return true if a new session was established.
+     */
+    tryRefresh?: () => Promise<boolean>;
+    /** Called once when interactive reauth is required (open modal / popup). */
+    onReauthRequired?: () => void;
+    /** Called when reauth succeeds or is cancelled (phase back to idle). */
+    onSettled?: (ok: boolean) => void;
+}
+declare class AuthGateCoordinator {
+    private phase;
+    private lastError?;
+    /** Cached for useSyncExternalStore — must keep referential equality when unchanged. */
+    private snapshot;
+    private config;
+    private flight;
+    private reauthWaiters;
+    private listeners;
+    configure(config: AuthGateConfig): void;
+    getSnapshot: () => AuthGateSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    private emit;
+    private setPhase;
+    /** Await while a recovery is in flight (pause outbound API traffic). */
+    waitIfBlocked(): Promise<void>;
+    /**
+     * Single-flight 401 handler.
+     * Concurrent callers share one recovery; all receive the same disposition.
+     */
+    handleUnauthorized(errorMessage?: string): Promise<UnauthorizedDisposition>;
+    /** Open reauth UI without a preceding 401 (cold start / deep link). */
+    requestReauth(errorMessage?: string): Promise<UnauthorizedDisposition>;
+    /** Product calls after popup / Headless login restored the session. */
+    completeReauth(): void;
+    /** User dismissed reauth; fail queued recovery waiters. */
+    cancelReauth(errorMessage?: string): void;
+    private runRecovery;
+}
+/** Process-wide gate (one per SPA bundle). */
+declare const authGate: AuthGateCoordinator;
+/**
+ * Run an async request; on 401, recover via AuthGate and retry once.
+ * `isUnauthorized` defaults to checking `status === 401` or `statusCode === 401`.
+ */
+declare function withAuthGateRetry<T>(execute: () => Promise<T>, options?: {
+    isUnauthorized?: (error: unknown) => boolean;
+    /** Skip gate (e.g. refresh / sso / login endpoints). */
+    bypass?: boolean;
+}): Promise<T>;
+
+interface LuminaryAuthContextValue {
+    configured: boolean;
+    session: LuminaryAuthSession | null;
+    accessToken: string | null;
+    loading: boolean;
+    login: (returnUrl?: string) => Promise<void>;
+    /** Popup OIDC — keeps the opener SPA mounted. */
+    loginPopup: (returnUrl?: string) => Promise<LuminaryAuthSession>;
+    logout: () => Promise<void>;
+    completeCallback: () => Promise<{
+        returnUrl?: string;
+    }>;
+    refreshSession: () => Promise<void>;
+}
+interface LuminaryAuthProviderProps {
+    config?: Partial<LuminaryIdpConfig>;
+    children: React.ReactNode;
+}
+declare function LuminaryAuthProvider({ config: configProp, children }: LuminaryAuthProviderProps): react.JSX.Element;
+declare function useLuminaryAuth(): LuminaryAuthContextValue;
+
+/** @deprecated Prefer dynamic connectors from IdP; kept for prop typing. */
+type SocialProviderTarget = string;
+interface HeadlessLoginLabels {
+    title?: string;
+    subtitle?: string;
+    identifierPlaceholder?: string;
+    passwordPlaceholder?: string;
+    submitPassword?: string;
+    /** @deprecated Use social buttons; kept for backward-compatible label overrides. */
+    submitSso?: string;
+    submitGoogle?: string;
+    submitGithub?: string;
+    socialDivider?: string;
+    hint?: string;
+    cancel?: string;
+    experienceUnavailable?: string;
+    showPassword?: string;
+    hidePassword?: string;
+}
+interface HeadlessLoginPanelProps {
+    config: Partial<LuminaryIdpConfig>;
+    /** Product display name shown as brand signal */
+    productName: string;
+    logoSrc?: string;
+    labels?: HeadlessLoginLabels;
+    returnUrl?: string;
+    /** Prefer popup (default) for reauth; use redirect for full-page login. */
+    mode?: "popup" | "redirect";
+    /**
+     * Show Experience social connectors (Google / GitHub / …).
+     * Default `true`. Set `false` for admin / internal consoles that only allow
+     * password (or enterprise SSO via IdP) — hides divider + social buttons and
+     * skips fetching connectors.
+     * Equivalent to `socialProviders={[]}` when false.
+     */
+    showSocialConnectors?: boolean;
+    /**
+     * Social providers (when `showSocialConnectors` is not `false`):
+     * - omit / `"auto"` — load enabled connectors from IdP (google, github, x, …)
+     * - `string[]` — only these targets (still prefers IdP logos/names when available)
+     * - `[]` — hide social buttons
+     */
+    socialProviders?: "auto" | SocialProviderTarget[];
+    showCancel?: boolean;
+    onCancel?: () => void;
+    /**
+     * Called after OIDC session is obtained (popup) or before redirect navigation.
+     * Products typically exchange OIDC access token → product JWT here.
+     */
+    onOidcSession?: (session: LuminaryAuthSession, returnUrl?: string) => Promise<void> | void;
+    /** When Experience returns redirectTo, open it (default: same-tab assign). */
+    onExperienceRedirect?: (redirectTo: string) => void;
+    footer?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Brand accent for primary CTA / focus / product label.
+     * Defaults to `#3a84ff` (DataLuminary / BlockyEdu).
+     */
+    themeColor?: string;
+}
+/** Shared default accent for product login panels. */
+declare const DEFAULT_LOGIN_THEME_COLOR = "#3a84ff";
+declare function HeadlessLoginPanel({ config, productName, logoSrc, labels: labelsProp, returnUrl, mode, showSocialConnectors, socialProviders, showCancel, onCancel, onOidcSession, onExperienceRedirect, footer, className, style, themeColor, }: HeadlessLoginPanelProps): react.JSX.Element;
+
+interface ReauthOverlayProps {
+    config: Partial<LuminaryIdpConfig>;
+    productName: string;
+    logoSrc?: string;
+    labels?: HeadlessLoginLabels;
+    returnUrl?: string;
+    /** Brand accent forwarded to HeadlessLoginPanel (default `#3a84ff`). */
+    themeColor?: string;
+    /** Exchange OIDC token / persist product session, then AuthGate completes. */
+    onOidcSession: (session: LuminaryAuthSession, returnUrl?: string) => Promise<void> | void;
+    /** Optional custom body instead of HeadlessLoginPanel */
+    children?: ReactNode;
+    /** Allow dismiss → cancelReauth (default true for mid-session; false for hard gate). */
+    dismissible?: boolean;
+    onDismiss?: () => void;
+}
+/**
+ * Full-viewport soft gate shown while AuthGate phase is `reauth` (or `refreshing` spinner).
+ * Does not iframe the IdP — uses Headless panel + OIDC popup.
+ */
+declare function ReauthOverlay({ config, productName, logoSrc, labels, returnUrl, themeColor, onOidcSession, children, dismissible, onDismiss, }: ReauthOverlayProps): react.JSX.Element | null;
+
+interface AuthGateContextValue {
+    snapshot: AuthGateSnapshot;
+    requestReauth: (message?: string) => Promise<"retry" | "fail">;
+    completeReauth: () => void;
+    cancelReauth: (message?: string) => void;
+}
+interface AuthGateProviderProps extends AuthGateConfig {
+    children: ReactNode;
+    /** When set, mounts {@link ReauthOverlay} automatically. */
+    overlay?: Omit<ReauthOverlayProps, "onOidcSession"> & {
+        onOidcSession: (session: LuminaryAuthSession, returnUrl?: string) => Promise<void> | void;
+        config: Partial<LuminaryIdpConfig>;
+    };
+}
+declare function AuthGateProvider({ children, tryRefresh, onReauthRequired, onSettled, overlay, }: AuthGateProviderProps): react.JSX.Element;
+declare function useAuthGate(): AuthGateContextValue;
+/** Optional hook — returns null outside provider (for shared API helpers). */
+declare function useAuthGateOptional(): AuthGateContextValue | null;
+
+interface PostLoginPathOptions {
+    /** sessionStorage key (product-scoped), e.g. `dv:postLoginPath` */
+    storageKey: string;
+    /** Default destination when nothing remembered */
+    defaultPath?: string;
+    /** Extra paths that must not be used as return targets */
+    unsafePrefixes?: string[];
+}
+/**
+ * sessionStorage helpers for OIDC redirect return paths.
+ * Product-specific ACL checks (e.g. 403 fallback) stay in the product.
+ */
+declare function createPostLoginPathHelpers(options: PostLoginPathOptions): {
+    rememberPostLoginPath: (path: string) => void;
+    peekPostLoginPath: () => string | undefined;
+    consumePostLoginPath: (fallback?: string) => string;
+    normalizeAppPath: (path: string) => string;
+    isUnsafeReturnPath: (path: string) => boolean;
+};
+
+export { type AuthGateConfig, type AuthGatePhase, AuthGateProvider, type AuthGateProviderProps, type AuthGateSnapshot, DEFAULT_LOGIN_THEME_COLOR, type ExperienceIdentifierType, type ExperiencePasswordSignInInput, type ExperiencePasswordSignInResult, type ExperienceSocialConnector, type HeadlessLoginLabels, HeadlessLoginPanel, type HeadlessLoginPanelProps, LuminaryAuthProvider, type LuminaryAuthProviderProps, type LuminaryAuthSession, type LuminaryIdpConfig, type PostLoginPathOptions, ReauthOverlay, type ReauthOverlayProps, type SignInOptions, type SocialProviderTarget, type UnauthorizedDisposition, authGate, clearStoredSession, createPostLoginPathHelpers, createUserManager, experiencePasswordSignIn, fetchSocialConnectors, getCurrentUser, getStoredAccessToken, handleSignInCallback, handleSignInPopupCallback, isIdpConfigured, isOidcPopupWindow, prepareSignInRequestUrl, readIdpConfigFromEnv, resetUserManager, resolveExperienceApiBase, resolveIssuer, sameOriginAuthorizeUrl, signInPopup, signInRedirect, signOutRedirect, useAuthGate, useAuthGateOptional, useLuminaryAuth, withAuthGateRetry };