@luminaryworks/auth-react 0.3.1 → 0.4.1

package/README.md

@@ -1,64 +1,97 @@
-# `@luminaryworks/auth-react`
-
-LuminaryWorks unified OIDC SPA client + **AuthGate** (401 pause / single-flight reauth).
-
-## AuthGate
-
-```ts
-import { authGate, withAuthGateRetry, AuthGateProvider, ReauthOverlay } from "@luminaryworks/auth-react";
-
-authGate.configure({
-  tryRefresh: async () => {
-    /* refresh product JWT; return true if ok */
-    return false;
-  },
-});
-
-// In API client:
-await withAuthGateRetry(() => fetch(...), {
-  isUnauthorized: (e) => e.status === 401,
-});
-```
-
-On first 401: try refresh → else open reauth UI (overlay + OIDC **popup**, not IdP iframe) → retry queued callers.
-
-## Headless login panel
-
-Branded panel with **social buttons** (auto-loaded from IdP `socialSignInConnectorTargets` — google / github / x / …) plus **unified account** password. Social uses `direct_sign_in=social:<target>`.
-
-Styles ship as **CSS Modules (SCSS)**. The built bundle auto-injects panel CSS in the browser. Optional explicit import (SSR / style control):
-
-```ts
-import "@luminaryworks/auth-react/style.css";
-```
-
-Override layout via `className` / `style` on the root.
-
-```tsx
-// End-user product login (social on by default)
-<HeadlessLoginPanel
-  config={idpConfig}
-  productName="DataLuminary"
-  mode="redirect"
-  // socialProviders: "auto" | ["google","github"] | []
-/>
-
-// Admin / internal console — hide Experience social connectors
-<HeadlessLoginPanel
-  config={idpConfig}
-  productName="DataLuminary Admin"
-  mode="redirect"
-  showSocialConnectors={false}
-/>
-```
-
-| Prop | Default | Notes |
-|------|---------|--------|
-| `showSocialConnectors` | `true` | `false` skips fetch and hides divider + social buttons |
-| `socialProviders` | `"auto"` | allowlist, or `[]` (same effect as `showSocialConnectors={false}`) |
-
-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`.
-
-## Popup callback
-
-Callback route must detect popup windows and call `handleSignInPopupCallback` (do not SSO-exchange inside the popup).
+# `@luminaryworks/auth-react`
+
+LuminaryWorks unified OIDC SPA client + **AuthGate** (401 pause / single-flight reauth).
+
+## AuthGate
+
+```ts
+import { authGate, withAuthGateRetry, AuthGateProvider, ReauthOverlay } from "@luminaryworks/auth-react";
+
+authGate.configure({
+  tryRefresh: async () => {
+    /* refresh product JWT; return true if ok */
+    return false;
+  },
+});
+
+// In API client:
+await withAuthGateRetry(() => fetch(...), {
+  isUnauthorized: (e) => e.status === 401,
+});
+```
+
+On first 401: try refresh → else open reauth UI (overlay + OIDC **popup**, not IdP iframe) → retry queued callers.
+
+## Headless login panel
+
+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):
+
+```ts
+import "@luminaryworks/auth-react/style.css";
+```
+
+Override layout via `className` / `style` on the root.
+
+```tsx
+// End-user product login (social on by default)
+<HeadlessLoginPanel
+  config={idpConfig}
+  productName="DataLuminary"
+  mode="redirect"
+  // socialProviders: "auto" | ["google","github"] | []
+/>
+
+// Admin / internal console — hide Experience social connectors
+<HeadlessLoginPanel
+  config={idpConfig}
+  productName="DataLuminary Admin"
+  mode="redirect"
+  showSocialConnectors={false}
+/>
+```
+
+| Prop | Default | Notes |
+|------|---------|--------|
+| `showSocialConnectors` | `true` | `false` skips fetch and hides divider + social buttons |
+| `socialProviders` | `"auto"` | allowlist, or `[]` (same effect as `showSocialConnectors={false}`) |
+| `experienceAdapter` | `LogtoExperienceAdapter` | optional custom `LoginExperienceAdapter` |
+
+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. Logto is the
+only built-in provider:
+
+```ts
+import {
+  createLoginExperienceAdapter,
+  LogtoExperienceAdapter,
+  resolveLoginExperienceAdapter,
+  type LoginExperienceAdapter,
+  type LoginExperienceCapability,
+} from "@luminaryworks/auth-react";
+
+const logto = new LogtoExperienceAdapter();
+const sameDefault = createLoginExperienceAdapter("logto");
+const resolved = resolveLoginExperienceAdapter(logto);
+
+// 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

@@ -45,9 +45,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 +86,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 +118,69 @@ 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";
+/**
+ * Factory for built-in providers. Logto is intentionally the only built-in
+ * adapter; products can supply their own adapter without shipping fake stubs.
+ */
+declare function createLoginExperienceAdapter(provider?: LoginExperienceProvider): LoginExperienceAdapter;
+/** Resolve an explicit product adapter, or the backward-compatible Logto default. */
+declare function resolveLoginExperienceAdapter(adapter?: LoginExperienceAdapter | null): LoginExperienceAdapter;
+
+/**
+ * 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;
+}
+
+/** @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 +275,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 +288,8 @@ interface HeadlessLoginLabels {
 }
 interface HeadlessLoginPanelProps {
     config: Partial<LuminaryIdpConfig>;
+    /** Login-experience provider. Defaults to the built-in Logto adapter. */
+    experienceAdapter?: LoginExperienceAdapter;
     /** Product display name shown as brand signal */
     productName: string;
     logoSrc?: string;
@@ -290,7 +332,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 +395,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, 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, sameOriginAuthorizeUrl, signInPopup, signInRedirect, signOutRedirect, useAuthGate, useAuthGateOptional, useLuminaryAuth, withAuthGateRetry };