@luminaryworks/auth-react 0.3.2 → 0.4.2

package/README.md

@@ -24,7 +24,7 @@ On first 401: try refresh → else open reauth UI (overlay + OIDC **popup**, not
 
 ## Headless login panel
 
-Branded panel with **social buttons** (auto-loaded from IdP Experience `socialConnectors` — google / github / x / …) plus **unified account** password. Social uses `direct_sign_in=social:<target>`. Buttons are hidden when the IdP has no social connectors (do not invent Google/GitHub — that dumped users on Logto `/sign-in`).
+Branded panel with **social buttons** (auto-loaded from IdP Experience `socialConnectors` — google / github / x / …) plus **unified account** password. The default `LogtoExperienceAdapter` keeps Logto's `direct_sign_in=social:<target>` parameter inside provider-specific code. Buttons are hidden when the IdP has no social connectors (do not invent Google/GitHub — that dumped users on Logto `/sign-in`).
 
 Styles ship as **CSS Modules (SCSS)**. The built bundle auto-injects panel CSS in the browser. Optional explicit import (SSR / style control):
 
@@ -56,9 +56,46 @@ Override layout via `className` / `style` on the root.
 |------|---------|--------|
 | `showSocialConnectors` | `true` | `false` skips fetch and hides divider + social buttons |
 | `socialProviders` | `"auto"` | allowlist, or `[]` (same effect as `showSocialConnectors={false}`) |
+| `experienceAdapter` | catalog default | optional custom `LoginExperienceAdapter`; otherwise `config.iamProvider` |
+| `config.iamProvider` | `logto` | `logto` Headless; `oidc` / `zitadel` Hosted Redirect |
 
 IdP hosted `/sign-in` social row layout: `node scripts/apply-branding.mjs` (customCss wrap). Enable connectors: `ensure-sign-in-experience.mjs` + `verify-social-direct-signin.mjs`.
 
+### Login experience adapters
+
+`HeadlessLoginPanel` delegates non-standard password and social-connector flows
+to `LoginExperienceAdapter`; standard OIDC authorization code + PKCE remains in
+the OIDC client. Adapter methods are optional and are used only when both the
+matching capability and method are present. Without password support, the panel
+renders `labels.submitSso` and starts a standard hosted OIDC flow. Built-in
+factory ids: `logto` (default Headless), `hosted` / `oidc` / `zitadel` (Hosted
+Redirect). ZITADEL is a reserved plugin — there is no empty Experience stub:
+
+```ts
+import {
+  createLoginExperienceAdapter,
+  HostedOidcExperienceAdapter,
+  LogtoExperienceAdapter,
+  resolveLoginExperienceAdapter,
+  type LoginExperienceAdapter,
+  type LoginExperienceCapability,
+} from "@luminaryworks/auth-react";
+
+const logto = new LogtoExperienceAdapter();
+const sameDefault = createLoginExperienceAdapter("logto");
+const resolved = resolveLoginExperienceAdapter(logto);
+const zitadelLogin = createLoginExperienceAdapter("zitadel"); // HostedOidcExperienceAdapter
+
+// Hosted-only enterprise IdP: no Experience API methods are required.
+const hostedOnly = {
+  provider: "enterprise",
+  capabilities: [],
+} satisfies LoginExperienceAdapter;
+```
+
+Existing `experiencePasswordSignIn` and `fetchSocialConnectors` imports remain
+available as compatibility functions backed by the default Logto adapter.
+
 ## Popup callback
 
 Callback route must detect popup windows and call `handleSignInPopupCallback` (do not SSO-exchange inside the popup).

package/dist/index.d.ts

@@ -27,6 +27,11 @@ interface LuminaryIdpConfig {
      * When set, Headless password sign-in is attempted before OIDC popup fallback.
      */
     experienceApiBase?: string;
+    /**
+     * IAM catalog id: `logto` (default Headless), `oidc` / `zitadel` (Hosted Redirect).
+     * Ignored when `HeadlessLoginPanel` receives an explicit `experienceAdapter`.
+     */
+    iamProvider?: string;
 }
 interface LuminaryAuthSession {
     accessToken: string;
@@ -45,9 +50,12 @@ declare function createUserManager(config: LuminaryIdpConfig): UserManager;
 declare function resetUserManager(): void;
 interface SignInOptions {
     returnUrl?: string;
+    /** Provider-specific authorize parameters supplied by an experience adapter. */
+    extraQueryParams?: Record<string, string>;
     /**
      * Logto direct sign-in, e.g. `social:google` / `social:github` / `sso:<connectorId>`.
      * Skips the hosted password page and opens the provider immediately.
+     * @deprecated Prefer a LoginExperienceAdapter, which supplies extraQueryParams.
      */
     directSignIn?: string;
 }
@@ -83,10 +91,17 @@ 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)
+ * Capabilities exposed by a headless login-experience provider.
+ *
+ * Consumers can use these flags to avoid assuming that every provider supports
+ * Logto's password, connector-discovery, or direct social-login flows.
  */
+declare const LOGIN_EXPERIENCE_CAPABILITIES: {
+    readonly passwordSignIn: "password-sign-in";
+    readonly socialConnectors: "social-connectors";
+    readonly socialDirectSignIn: "social-direct-sign-in";
+};
+type LoginExperienceCapability = (typeof LOGIN_EXPERIENCE_CAPABILITIES)[keyof typeof LOGIN_EXPERIENCE_CAPABILITIES];
 type ExperienceIdentifierType = "email" | "username" | "phone";
 interface ExperiencePasswordSignInInput {
     /** Experience API origin (no trailing slash). Prefer SPA origin when proxied. */
@@ -108,39 +123,91 @@ interface ExperiencePasswordSignInResult {
     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: {
+interface FetchSocialConnectorsInput {
     /** Same origin as Experience / IdP (e.g. SPA proxy or http://localhost:3001). */
     apiBase: string;
     appId?: string;
-}): Promise<ExperienceSocialConnector[]>;
+}
+interface SocialSignInRequest {
+    /** Provider-specific authorize parameters, passed through by the OIDC client. */
+    extraQueryParams?: Record<string, string>;
+}
+/**
+ * Provider boundary for non-standard login-experience APIs.
+ *
+ * Standard OIDC redirect/popup and PKCE handling intentionally remain in the
+ * OIDC client. Only provider-specific Experience operations belong here.
+ */
+interface LoginExperienceAdapter {
+    readonly provider: string;
+    readonly capabilities: readonly LoginExperienceCapability[];
+    experiencePasswordSignIn?(input: ExperiencePasswordSignInInput): Promise<ExperiencePasswordSignInResult>;
+    fetchSocialConnectors?(input: FetchSocialConnectorsInput): Promise<ExperienceSocialConnector[]>;
+    createSocialSignInRequest?(target: string): SocialSignInRequest;
+}
+type LoginExperienceProvider = "logto" | "hosted" | "oidc" | "zitadel" | (string & {});
+/**
+ * Factory for built-in login adapters.
+ *
+ * - `logto`: Experience API Headless (password + social connectors)
+ * - `hosted` / `oidc` / `zitadel`: standard OIDC Hosted Redirect (no empty vendor SDK)
+ *
+ * Products may still pass a custom `LoginExperienceAdapter`. Do not add stub
+ * adapters for unintegrated Headless APIs.
+ */
+declare function createLoginExperienceAdapter(provider?: LoginExperienceProvider): LoginExperienceAdapter;
+/**
+ * Resolve an explicit product adapter, or the catalog adapter for `iamProvider`.
+ * Defaults to Logto for backward compatibility.
+ */
+declare function resolveLoginExperienceAdapter(adapter?: LoginExperienceAdapter | null, iamProvider?: string | null): LoginExperienceAdapter;
+/** `VITE_IAM_PROVIDER` / `IAM_PROVIDER` / older `IDP_MODE`. */
+declare function resolveLoginExperienceProviderFromEnv(env?: Record<string, string | undefined>): LoginExperienceProvider;
+
+/**
+ * Logto Experience API (Headless) adapter.
+ * Prefer same-origin Experience base (SPA proxies /api/experience) so cookies
+ * work on HTTP localhost.
+ */
+
+/**
+ * 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;
+/** Build Logto's provider-specific direct sign-in authorize parameter. */
+declare function createLogtoDirectSignInRequest(directSignIn: string): SocialSignInRequest;
+/** Built-in adapter for Logto's non-standard Experience API. */
+declare class LogtoExperienceAdapter implements LoginExperienceAdapter {
+    readonly provider = "logto";
+    readonly capabilities: readonly LoginExperienceCapability[];
+    experiencePasswordSignIn(input: ExperiencePasswordSignInInput): Promise<ExperiencePasswordSignInResult>;
+    fetchSocialConnectors(input: FetchSocialConnectorsInput): Promise<ExperienceSocialConnector[]>;
+    createSocialSignInRequest(target: string): SocialSignInRequest;
+}
+
+/**
+ * Standard OIDC Hosted Redirect adapter.
+ *
+ * Used for enterprise OIDC and reserved IAM plugins (ZITADEL) that have no
+ * shipped Headless Experience API. Password and social stay on the IdP hosted UI.
+ */
+declare class HostedOidcExperienceAdapter implements LoginExperienceAdapter {
+    readonly provider: string;
+    readonly capabilities: readonly LoginExperienceCapability[];
+    constructor(provider?: string);
+}
+
+/** @deprecated Use a LoginExperienceAdapter instance. */
+declare function experiencePasswordSignIn(input: ExperiencePasswordSignInInput): Promise<ExperiencePasswordSignInResult>;
+/** @deprecated Use a LoginExperienceAdapter instance. */
+declare function fetchSocialConnectors(input: FetchSocialConnectorsInput): Promise<ExperienceSocialConnector[]>;
 
 /**
  * AuthGate — single-flight 401 recovery with optional token refresh + reauth UI.
@@ -235,7 +302,7 @@ interface HeadlessLoginLabels {
     identifierPlaceholder?: string;
     passwordPlaceholder?: string;
     submitPassword?: string;
-    /** @deprecated Use social buttons; kept for backward-compatible label overrides. */
+    /** Hosted OIDC button shown when the adapter has no password capability. */
     submitSso?: string;
     submitGoogle?: string;
     submitGithub?: string;
@@ -248,6 +315,8 @@ interface HeadlessLoginLabels {
 }
 interface HeadlessLoginPanelProps {
     config: Partial<LuminaryIdpConfig>;
+    /** Login-experience provider. Defaults to the catalog adapter for `config.iamProvider`. */
+    experienceAdapter?: LoginExperienceAdapter;
     /** Product display name shown as brand signal */
     productName: string;
     logoSrc?: string;
@@ -290,7 +359,7 @@ interface HeadlessLoginPanelProps {
 }
 /** 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;
+declare function HeadlessLoginPanel({ config, experienceAdapter: experienceAdapterProp, 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>;
@@ -353,4 +422,4 @@ declare function createPostLoginPathHelpers(options: PostLoginPathOptions): {
     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 };
+export { type AuthGateConfig, type AuthGatePhase, AuthGateProvider, type AuthGateProviderProps, type AuthGateSnapshot, DEFAULT_LOGIN_THEME_COLOR, type ExperienceIdentifierType, type ExperiencePasswordSignInInput, type ExperiencePasswordSignInResult, type ExperienceSocialConnector, type FetchSocialConnectorsInput, type HeadlessLoginLabels, HeadlessLoginPanel, type HeadlessLoginPanelProps, HostedOidcExperienceAdapter, LOGIN_EXPERIENCE_CAPABILITIES, type LoginExperienceAdapter, type LoginExperienceCapability, type LoginExperienceProvider, LogtoExperienceAdapter, LuminaryAuthProvider, type LuminaryAuthProviderProps, type LuminaryAuthSession, type LuminaryIdpConfig, type PostLoginPathOptions, ReauthOverlay, type ReauthOverlayProps, type SignInOptions, type SocialProviderTarget, type SocialSignInRequest, type UnauthorizedDisposition, authGate, clearStoredSession, createLoginExperienceAdapter, createLogtoDirectSignInRequest, createPostLoginPathHelpers, createUserManager, experiencePasswordSignIn, fetchSocialConnectors, getCurrentUser, getStoredAccessToken, handleSignInCallback, handleSignInPopupCallback, isIdpConfigured, isOidcPopupWindow, prepareSignInRequestUrl, readIdpConfigFromEnv, resetUserManager, resolveExperienceApiBase, resolveIssuer, resolveLoginExperienceAdapter, resolveLoginExperienceProviderFromEnv, sameOriginAuthorizeUrl, signInPopup, signInRedirect, signOutRedirect, useAuthGate, useAuthGateOptional, useLuminaryAuth, withAuthGateRetry };