@confighub/react-auth 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -2,19 +2,97 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { ConfigHubClient } from '@confighub/api';
 
+interface Discovery {
+    AuthIssuer?: string;
+    TokenExchangeEndpoint?: string;
+    TokenExchangeAudience?: string;
+}
+interface MintedSession {
+    accessToken: string;
+    organizationId: string;
+    /** Claims of the validated IdP token (owning-org, audience, organization shape). */
+    idpClaims: Record<string, unknown>;
+    /**
+     * The IdP's ID token, kept only so logout can pass it as `id_token_hint` to the
+     * end-session endpoint. Absent for sessions that did not come from an OIDC login.
+     */
+    idToken?: string;
+}
+interface LoginOptions {
+    /**
+     * Where to land after login, as a same-origin path (`/space/x?tab=units`). Carried
+     * through the authorize round trip in the PKCE state, never in the redirect URI:
+     * OAuth clients register exact redirect URIs, so the URI itself must not vary with
+     * the page the user started from. Defaults to the current path and query.
+     */
+    returnTo?: string;
+    /**
+     * Keycloak organization alias to sign in to, sent as the `organization:<alias>`
+     * scope. Without it Keycloak prompts a multi-org user to pick one (or uses the
+     * organization already selected in the SSO session).
+     */
+    organization?: string;
+    /**
+     * `'none'` asks the IdP to re-authenticate without any UI, failing with
+     * `login_required` if the SSO session is gone -- the way to refresh an expired
+     * ConfigHub token when the user is still signed in at the IdP. `'login'` forces the
+     * login form even with a live SSO session.
+     */
+    prompt?: 'none' | 'login';
+}
+interface FlowOptions {
+    /**
+     * Same-origin path the IdP redirects back to, and therefore the redirect URI to
+     * register for the client: `{origin}{callbackPath}`. Defaults to `/`.
+     */
+    callbackPath?: string;
+}
+/** The fixed callback URI: the page origin plus the configured callback path. */
+declare const callbackUri: (opts?: FlowOptions) => string;
+/** Decode a JWT's claims without verifying it. Returns {} for anything malformed. */
+declare function decodeJwtClaims(token: string): Record<string, unknown>;
+/** Whether a JWT's `exp` is in the past (with a small skew allowance). */
+declare function isExpired(token: string, skewSeconds?: number): boolean;
+
 type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated' | 'error';
 interface ConfigHubUser {
     organizationId: string;
     idpClaims: Record<string, unknown>;
 }
+interface LogoutOptions {
+    /**
+     * Also end the IdP session (RP-initiated logout), so the next login asks for
+     * credentials instead of riding the SSO cookie. Redirects the page; the landing
+     * URI must be registered for the client. Default: false, which only forgets the
+     * token in this tab.
+     */
+    endSession?: boolean;
+    /** Where to land after IdP logout. Defaults to the callback URI. */
+    postLogoutRedirectUri?: string;
+}
 interface ConfigHubAuthContextValue {
     status: AuthStatus;
     user: ConfigHubUser | null;
     error: Error | null;
     /** Begin login: redirects the page to the IdP. */
-    login: () => Promise<void>;
-    /** Clear the in-memory session. Does not call the IdP end-session endpoint. */
-    logout: () => void;
+    login: (options?: LoginOptions) => Promise<void>;
+    /** Forget the session in this tab and, optionally, end the IdP session too. */
+    logout: (options?: LogoutOptions) => Promise<void>;
+    /**
+     * Re-mint the ConfigHub token for another organization the user belongs to. The
+     * IdP session is untouched. Rejects with the server's error if the user is not a
+     * member; the current session stays as it was.
+     */
+    switchOrganization: (organizationId: string) => Promise<void>;
+    /**
+     * The ConfigHub token stopped working (a 401). Try to get a new one without any
+     * UI: a `prompt=none` round trip through the IdP, for the organization the session
+     * already had. Status goes to `loading` meanwhile, not `unauthenticated`, so an
+     * app that auto-logs-in on `unauthenticated` does not race this with an
+     * interactive login. If the IdP session is gone too, the page comes back
+     * `unauthenticated`. Redirects the page.
+     */
+    reauthenticate: () => Promise<void>;
     /** Current bearer token, or undefined when unauthenticated. */
     getToken: () => string | undefined;
     /** A typed API client pre-wired with the current token. Stable across renders. */
@@ -26,14 +104,33 @@ interface ConfigHubAuthProviderProps {
     baseUrl: string;
     /** This app's registered OAuth `client_id` (from `cub oauthclient create`). */
     clientId: string;
+    /**
+     * Same-origin path the IdP redirects back to; `{origin}{callbackPath}` is the
+     * redirect URI to register. Defaults to `/`. Fixed on purpose: the page a user
+     * starts login from travels in the PKCE state, not in the redirect URI.
+     */
+    callbackPath?: string;
+    /**
+     * `'session'` keeps the minted token in `sessionStorage` so a reload or an in-tab
+     * navigation does not round-trip through the IdP. Tab-scoped and gone when the tab
+     * closes. Default `'none'`: memory only, a reload starts unauthenticated.
+     */
+    persist?: 'none' | 'session';
+    /**
+     * What a 401 from the API means. `'login'` (default): the token is stale, try a
+     * silent re-authentication (`prompt=none`) and fall back to unauthenticated if the
+     * IdP session is gone too. `'logout'`: just drop the session.
+     */
+    onUnauthorized?: 'login' | 'logout';
     children: ReactNode;
 }
 /**
  * Runs the browser-direct auth flow and manages the token lifecycle. On mount it
- * completes a redirect if the page is the IdP callback; otherwise it starts
- * unauthenticated until `login()` is called.
+ * completes a redirect if the page is the IdP callback, restores a persisted
+ * session if there is one, and otherwise starts unauthenticated until `login()`
+ * is called.
  */
-declare function ConfigHubAuthProvider({ baseUrl, clientId, children, }: ConfigHubAuthProviderProps): JSX.Element;
+declare function ConfigHubAuthProvider({ baseUrl, clientId, callbackPath, persist, onUnauthorized, children, }: ConfigHubAuthProviderProps): JSX.Element;
 
 /**
  * Access the ConfigHub auth state and actions. Must be called under a
@@ -63,16 +160,4 @@ declare function useConfigHub(): ConfigHubClient;
  */
 declare function getAccessToken(): string | undefined;
 
-interface Discovery {
-    AuthIssuer?: string;
-    TokenExchangeEndpoint?: string;
-    TokenExchangeAudience?: string;
-}
-interface MintedSession {
-    accessToken: string;
-    organizationId: string;
-    /** Claims of the validated IdP token (owning-org, audience, organization shape). */
-    idpClaims: Record<string, unknown>;
-}
-
-export { type AuthStatus, ConfigHubAuthContext, type ConfigHubAuthContextValue, ConfigHubAuthProvider, type ConfigHubAuthProviderProps, type ConfigHubUser, type Discovery, type MintedSession, getAccessToken, useAuth, useConfigHub };
+export { type AuthStatus, ConfigHubAuthContext, type ConfigHubAuthContextValue, ConfigHubAuthProvider, type ConfigHubAuthProviderProps, type ConfigHubUser, type Discovery, type FlowOptions, type LoginOptions, type LogoutOptions, type MintedSession, callbackUri, decodeJwtClaims, getAccessToken, isExpired, useAuth, useConfigHub };

package/dist/index.d.ts

@@ -2,19 +2,97 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { ConfigHubClient } from '@confighub/api';
 
+interface Discovery {
+    AuthIssuer?: string;
+    TokenExchangeEndpoint?: string;
+    TokenExchangeAudience?: string;
+}
+interface MintedSession {
+    accessToken: string;
+    organizationId: string;
+    /** Claims of the validated IdP token (owning-org, audience, organization shape). */
+    idpClaims: Record<string, unknown>;
+    /**
+     * The IdP's ID token, kept only so logout can pass it as `id_token_hint` to the
+     * end-session endpoint. Absent for sessions that did not come from an OIDC login.
+     */
+    idToken?: string;
+}
+interface LoginOptions {
+    /**
+     * Where to land after login, as a same-origin path (`/space/x?tab=units`). Carried
+     * through the authorize round trip in the PKCE state, never in the redirect URI:
+     * OAuth clients register exact redirect URIs, so the URI itself must not vary with
+     * the page the user started from. Defaults to the current path and query.
+     */
+    returnTo?: string;
+    /**
+     * Keycloak organization alias to sign in to, sent as the `organization:<alias>`
+     * scope. Without it Keycloak prompts a multi-org user to pick one (or uses the
+     * organization already selected in the SSO session).
+     */
+    organization?: string;
+    /**
+     * `'none'` asks the IdP to re-authenticate without any UI, failing with
+     * `login_required` if the SSO session is gone -- the way to refresh an expired
+     * ConfigHub token when the user is still signed in at the IdP. `'login'` forces the
+     * login form even with a live SSO session.
+     */
+    prompt?: 'none' | 'login';
+}
+interface FlowOptions {
+    /**
+     * Same-origin path the IdP redirects back to, and therefore the redirect URI to
+     * register for the client: `{origin}{callbackPath}`. Defaults to `/`.
+     */
+    callbackPath?: string;
+}
+/** The fixed callback URI: the page origin plus the configured callback path. */
+declare const callbackUri: (opts?: FlowOptions) => string;
+/** Decode a JWT's claims without verifying it. Returns {} for anything malformed. */
+declare function decodeJwtClaims(token: string): Record<string, unknown>;
+/** Whether a JWT's `exp` is in the past (with a small skew allowance). */
+declare function isExpired(token: string, skewSeconds?: number): boolean;
+
 type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated' | 'error';
 interface ConfigHubUser {
     organizationId: string;
     idpClaims: Record<string, unknown>;
 }
+interface LogoutOptions {
+    /**
+     * Also end the IdP session (RP-initiated logout), so the next login asks for
+     * credentials instead of riding the SSO cookie. Redirects the page; the landing
+     * URI must be registered for the client. Default: false, which only forgets the
+     * token in this tab.
+     */
+    endSession?: boolean;
+    /** Where to land after IdP logout. Defaults to the callback URI. */
+    postLogoutRedirectUri?: string;
+}
 interface ConfigHubAuthContextValue {
     status: AuthStatus;
     user: ConfigHubUser | null;
     error: Error | null;
     /** Begin login: redirects the page to the IdP. */
-    login: () => Promise<void>;
-    /** Clear the in-memory session. Does not call the IdP end-session endpoint. */
-    logout: () => void;
+    login: (options?: LoginOptions) => Promise<void>;
+    /** Forget the session in this tab and, optionally, end the IdP session too. */
+    logout: (options?: LogoutOptions) => Promise<void>;
+    /**
+     * Re-mint the ConfigHub token for another organization the user belongs to. The
+     * IdP session is untouched. Rejects with the server's error if the user is not a
+     * member; the current session stays as it was.
+     */
+    switchOrganization: (organizationId: string) => Promise<void>;
+    /**
+     * The ConfigHub token stopped working (a 401). Try to get a new one without any
+     * UI: a `prompt=none` round trip through the IdP, for the organization the session
+     * already had. Status goes to `loading` meanwhile, not `unauthenticated`, so an
+     * app that auto-logs-in on `unauthenticated` does not race this with an
+     * interactive login. If the IdP session is gone too, the page comes back
+     * `unauthenticated`. Redirects the page.
+     */
+    reauthenticate: () => Promise<void>;
     /** Current bearer token, or undefined when unauthenticated. */
     getToken: () => string | undefined;
     /** A typed API client pre-wired with the current token. Stable across renders. */
@@ -26,14 +104,33 @@ interface ConfigHubAuthProviderProps {
     baseUrl: string;
     /** This app's registered OAuth `client_id` (from `cub oauthclient create`). */
     clientId: string;
+    /**
+     * Same-origin path the IdP redirects back to; `{origin}{callbackPath}` is the
+     * redirect URI to register. Defaults to `/`. Fixed on purpose: the page a user
+     * starts login from travels in the PKCE state, not in the redirect URI.
+     */
+    callbackPath?: string;
+    /**
+     * `'session'` keeps the minted token in `sessionStorage` so a reload or an in-tab
+     * navigation does not round-trip through the IdP. Tab-scoped and gone when the tab
+     * closes. Default `'none'`: memory only, a reload starts unauthenticated.
+     */
+    persist?: 'none' | 'session';
+    /**
+     * What a 401 from the API means. `'login'` (default): the token is stale, try a
+     * silent re-authentication (`prompt=none`) and fall back to unauthenticated if the
+     * IdP session is gone too. `'logout'`: just drop the session.
+     */
+    onUnauthorized?: 'login' | 'logout';
     children: ReactNode;
 }
 /**
  * Runs the browser-direct auth flow and manages the token lifecycle. On mount it
- * completes a redirect if the page is the IdP callback; otherwise it starts
- * unauthenticated until `login()` is called.
+ * completes a redirect if the page is the IdP callback, restores a persisted
+ * session if there is one, and otherwise starts unauthenticated until `login()`
+ * is called.
  */
-declare function ConfigHubAuthProvider({ baseUrl, clientId, children, }: ConfigHubAuthProviderProps): JSX.Element;
+declare function ConfigHubAuthProvider({ baseUrl, clientId, callbackPath, persist, onUnauthorized, children, }: ConfigHubAuthProviderProps): JSX.Element;
 
 /**
  * Access the ConfigHub auth state and actions. Must be called under a
@@ -63,16 +160,4 @@ declare function useConfigHub(): ConfigHubClient;
  */
 declare function getAccessToken(): string | undefined;
 
-interface Discovery {
-    AuthIssuer?: string;
-    TokenExchangeEndpoint?: string;
-    TokenExchangeAudience?: string;
-}
-interface MintedSession {
-    accessToken: string;
-    organizationId: string;
-    /** Claims of the validated IdP token (owning-org, audience, organization shape). */
-    idpClaims: Record<string, unknown>;
-}
-
-export { type AuthStatus, ConfigHubAuthContext, type ConfigHubAuthContextValue, ConfigHubAuthProvider, type ConfigHubAuthProviderProps, type ConfigHubUser, type Discovery, type MintedSession, getAccessToken, useAuth, useConfigHub };
+export { type AuthStatus, ConfigHubAuthContext, type ConfigHubAuthContextValue, ConfigHubAuthProvider, type ConfigHubAuthProviderProps, type ConfigHubUser, type Discovery, type FlowOptions, type LoginOptions, type LogoutOptions, type MintedSession, callbackUri, decodeJwtClaims, getAccessToken, isExpired, useAuth, useConfigHub };