@jamroast/jamauth-react 0.0.0-stage → 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,218 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+/**
+ * Framework-agnostic OIDC authorization-code (PKCE) + embedded-iframe
+ * `postMessage` bridge for `@jamroast/jamauth-react`.
+ *
+ * Generalizes the PKCE S256 + `localStorage` token pattern from jamauth's own
+ * SPA (`web/src/lib/oidc-capture.ts`) so any client app (Next/Vite/Remix/etc.)
+ * can render a branded `SignIn`/`SignUp` on its own domain while every
+ * credential form (email+password, MFA, forgot/reset/verify) stays on the
+ * jamauth authority inside an embedded `<iframe>` that completes the OIDC
+ * authorization-code flow and relays `{ code, state }` to the parent via
+ * `postMessage`.
+ *
+ * Pure React + `window`/`postMessage`/`localStorage` with `typeof window`
+ * guards so it is SSR-safe. No credential inputs live here — credentials are
+ * typed only inside the jamauth frame (server-rendered interaction HTML).
+ */
+declare const STORAGE_KEYS: {
+    readonly userToken: "jamauth.userToken";
+    readonly refreshToken: "jamauth.refreshToken";
+    readonly tokenExpiresIn: "jamauth.tokenExpiresIn";
+    readonly pkceVerifier: "jamauth.pkceVerifier";
+};
+/** Custom event fired whenever the stored session changes (sign-in/sign-out). */
+declare const SESSION_CHANGED_EVENT = "jamauth:session-changed";
+/** Caller-supplied OIDC client identity (never a hardcoded first-party default). */
+interface OidcClientParams {
+    /** The jamauth issuer/authority origin, e.g. `https://jamauth.net`. */
+    authority: string;
+    clientId: string;
+    redirectUri: string;
+    /** RFC 8707 resource indicator; only needed for RS256 human-token minting. */
+    resource?: string;
+    /** OIDC `login_hint` — the invitee email, prefilled on sign-in. */
+    loginHint?: string;
+    /** OIDC scope; defaults to `openid profile email offline_access`. */
+    scope?: string;
+    /** Token endpoint override; defaults to `${authority}/token`. */
+    tokenEndpoint?: string;
+    /** OIDC `prompt` value (e.g. `'register'` for the sign-up surface). */
+    prompt?: string;
+}
+interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+}
+type AuthorizeMessage = {
+    type: 'jamauth:authorize';
+    code: string;
+    state: string;
+};
+type ReadyMessage = {
+    type: 'jamauth:ready';
+};
+/**
+ * Derive the configured authority origin. The handshake validates incoming
+ * `postMessage` events against this origin — never a hardcoded `jamauth.net`
+ * literal.
+ */
+declare function authorityOrigin(authority: string): string;
+/** Build the top-level `/auth` authorization URL (PKCE S256, `response_type=code`). */
+declare function buildAuthorizeUrl(params: OidcClientParams): Promise<URL>;
+/** Build the embedded `/embed/authorize` iframe URL (same PKCE S256 params). */
+declare function buildEmbedUrl(params: OidcClientParams): Promise<URL>;
+/**
+ * Validate an incoming `postMessage` event against the configured authority
+ * origin (never hardcoded) AND the iframe's `contentWindow` (so a same-origin
+ * event from an unexpected frame is ignored).
+ */
+declare function isTrustedBridgeMessage(event: MessageEvent, authority: string, iframe: HTMLIFrameElement): boolean;
+/** Parse a `jamauth:authorize` relay payload; returns `null` for other types. */
+declare function parseAuthorizeMessage(data: unknown): {
+    code: string;
+    state: string;
+} | null;
+/** Parse a `jamauth:ready` handshake payload; returns `true` for the handshake. */
+declare function isReadyMessage(data: unknown): data is ReadyMessage;
+/** Store a minted token response (mirrors `oidc-capture.ts`). */
+declare function storeTokenResponse(response: TokenResponse): void;
+/** Clear the stored session tokens (sign-out). */
+declare function clearStoredTokens(): void;
+/**
+ * Exchange an authorization `code` for tokens via a PUBLIC PKCE request
+ * (`grant_type=authorization_code`, no client_secret, no Authorization header).
+ * The token endpoint defaults to `${authority}/token` (CORS-allowed for the
+ * registered client origin via `clientBasedCORS`).
+ */
+declare function exchangeCodeForToken(params: OidcClientParams, code: string): Promise<TokenResponse>;
+/**
+ * Fallback to a top-level redirect with a fresh PKCE `authorizeUrl`. Used when
+ * the embedded iframe is blocked (or fails to handshake) — idempotent and
+ * correct, so a false positive degrades to the top-level flow rather than a
+ * broken UX.
+ */
+declare function fallbackToTopLevelRedirect(authorizeUrl: URL): void;
+
+/** Configuration carried by `JamauthProvider`. */
+interface JamauthConfig {
+    /** The jamauth issuer/authority origin, e.g. `https://jamauth.net`. */
+    authority: string;
+    clientId: string;
+    redirectUri: string;
+    resource?: string;
+    scope?: string;
+    tokenEndpoint?: string;
+    loginHint?: string;
+    /** Blocked-iframe handshake timeout in ms (default 5000). */
+    handshakeTimeoutMs?: number;
+    /** Called once the authorization code is exchanged for tokens. */
+    onToken?: (response: TokenResponse) => void;
+}
+/** Provide the jamauth authority + client identity to the embedded auth surface. */
+declare function JamauthProvider({ config, children, }: {
+    config: JamauthConfig;
+    children: ReactNode;
+}): react.JSX.Element;
+/** Read the configured jamauth client identity (throws outside a provider). */
+declare function useJamauth(): JamauthConfig;
+interface SessionState {
+    isAuthenticated: boolean;
+    token: string | null;
+}
+/** Reactive session state sourced from the stored access token. */
+declare function useSession(): SessionState;
+/** High-level auth surface: session state plus sign-out. */
+declare function useAuth(): SessionState & {
+    signOut: () => void;
+};
+/** Low-level OIDC bridge bound to the configured authority/client identity. */
+declare function useOidc(): {
+    authorityOrigin: () => string;
+    buildAuthorizeUrl: () => Promise<URL>;
+    buildEmbedUrl: (prompt?: string) => Promise<URL>;
+    exchangeCodeForToken: (code: string) => Promise<TokenResponse>;
+};
+/** Renders `children` only while authenticated (access token present). */
+declare function SignedIn({ children }: {
+    children: ReactNode;
+}): react.JSX.Element | null;
+/** Renders `children` only while signed out (no access token present). */
+declare function SignedOut({ children }: {
+    children: ReactNode;
+}): react.JSX.Element | null;
+
+interface SignInProps {
+    /** Override the handshake timeout (ms) for this surface. */
+    handshakeTimeoutMs?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Embedded sign-in surface — an iframe wrapper around the jamauth
+ * `/embed/authorize` flow. This component renders **no credential inputs**:
+ * the email+password form (and MFA / forgot / reset / verify) lives on the
+ * jamauth authority inside the frame, and the completed authorization code is
+ * relayed back to the parent via `postMessage`.
+ */
+declare function SignIn({ className, style }: SignInProps): react.JSX.Element;
+
+interface SignUpProps {
+    /** Override the handshake timeout (ms) for this surface. */
+    handshakeTimeoutMs?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Embedded sign-up surface — an iframe wrapper around the jamauth
+ * `/embed/authorize` flow with `prompt=register`. Like `SignIn`, this renders
+ * **no credential inputs**; the sign-up form lives on the jamauth authority
+ * inside the frame and the completed authorization code is relayed back via
+ * `postMessage`.
+ */
+declare function SignUp({ className, style }: SignUpProps): react.JSX.Element;
+
+interface UserButtonProps {
+    /** Label shown when signed out (default "Sign in"). */
+    signInLabel?: ReactNode;
+    /** Label shown when signed in (default "Sign out"). */
+    signOutLabel?: ReactNode;
+    /** Called instead of the default sign-out when the user is signed in. */
+    onSignOut?: () => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A minimal, framework-agnostic account button. It reflects the stored session
+ * state and, when signed in, signs the user out (or delegates to `onSignOut`).
+ * It renders no credential inputs.
+ */
+declare function UserButton({ signInLabel, signOutLabel, onSignOut, className, style, }: UserButtonProps): react.JSX.Element;
+
+type EmbeddedStatus = 'loading' | 'ready' | 'authenticated' | 'fallback';
+interface EmbeddedAuthState {
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    src: string;
+    status: EmbeddedStatus;
+}
+/**
+ * Mount the embedded `/embed/authorize` iframe and drive the confirmation
+ * handshake + timeout fallback:
+ *
+ * - `iframe.onload` is NOT authoritative (a `frame-ancestors`-blocked frame
+ *   still fires `onload`). Instead the parent validates
+ *   `event.origin === authorityOrigin` (derived from the configured authority,
+ *   never hardcoded) **and** `event.source === iframe.contentWindow`.
+ * - A `handshakeTimeoutMs` timer (default ~5s) falls back to a top-level
+ *   `window.location.assign(freshPkceAuthorizeUrl)` when no `jamauth:ready`
+ *   arrives — idempotent and correct, so a false positive degrades to the
+ *   top-level flow rather than a broken UX.
+ * - On `jamauth:authorize`, the code is exchanged via public PKCE and the
+ *   tokens are stored.
+ */
+declare function useEmbeddedAuth(prompt?: string): EmbeddedAuthState;
+
+export { type AuthorizeMessage, type EmbeddedAuthState, type EmbeddedStatus, type JamauthConfig, JamauthProvider, type OidcClientParams, type ReadyMessage, SESSION_CHANGED_EVENT, STORAGE_KEYS, type SessionState, SignIn, type SignInProps, SignUp, type SignUpProps, SignedIn, SignedOut, type TokenResponse, UserButton, type UserButtonProps, authorityOrigin, buildAuthorizeUrl, buildEmbedUrl, clearStoredTokens, exchangeCodeForToken, fallbackToTopLevelRedirect, isReadyMessage, isTrustedBridgeMessage, parseAuthorizeMessage, storeTokenResponse, useAuth, useEmbeddedAuth, useJamauth, useOidc, useSession };

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+/**
+ * Framework-agnostic OIDC authorization-code (PKCE) + embedded-iframe
+ * `postMessage` bridge for `@jamroast/jamauth-react`.
+ *
+ * Generalizes the PKCE S256 + `localStorage` token pattern from jamauth's own
+ * SPA (`web/src/lib/oidc-capture.ts`) so any client app (Next/Vite/Remix/etc.)
+ * can render a branded `SignIn`/`SignUp` on its own domain while every
+ * credential form (email+password, MFA, forgot/reset/verify) stays on the
+ * jamauth authority inside an embedded `<iframe>` that completes the OIDC
+ * authorization-code flow and relays `{ code, state }` to the parent via
+ * `postMessage`.
+ *
+ * Pure React + `window`/`postMessage`/`localStorage` with `typeof window`
+ * guards so it is SSR-safe. No credential inputs live here — credentials are
+ * typed only inside the jamauth frame (server-rendered interaction HTML).
+ */
+declare const STORAGE_KEYS: {
+    readonly userToken: "jamauth.userToken";
+    readonly refreshToken: "jamauth.refreshToken";
+    readonly tokenExpiresIn: "jamauth.tokenExpiresIn";
+    readonly pkceVerifier: "jamauth.pkceVerifier";
+};
+/** Custom event fired whenever the stored session changes (sign-in/sign-out). */
+declare const SESSION_CHANGED_EVENT = "jamauth:session-changed";
+/** Caller-supplied OIDC client identity (never a hardcoded first-party default). */
+interface OidcClientParams {
+    /** The jamauth issuer/authority origin, e.g. `https://jamauth.net`. */
+    authority: string;
+    clientId: string;
+    redirectUri: string;
+    /** RFC 8707 resource indicator; only needed for RS256 human-token minting. */
+    resource?: string;
+    /** OIDC `login_hint` — the invitee email, prefilled on sign-in. */
+    loginHint?: string;
+    /** OIDC scope; defaults to `openid profile email offline_access`. */
+    scope?: string;
+    /** Token endpoint override; defaults to `${authority}/token`. */
+    tokenEndpoint?: string;
+    /** OIDC `prompt` value (e.g. `'register'` for the sign-up surface). */
+    prompt?: string;
+}
+interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+}
+type AuthorizeMessage = {
+    type: 'jamauth:authorize';
+    code: string;
+    state: string;
+};
+type ReadyMessage = {
+    type: 'jamauth:ready';
+};
+/**
+ * Derive the configured authority origin. The handshake validates incoming
+ * `postMessage` events against this origin — never a hardcoded `jamauth.net`
+ * literal.
+ */
+declare function authorityOrigin(authority: string): string;
+/** Build the top-level `/auth` authorization URL (PKCE S256, `response_type=code`). */
+declare function buildAuthorizeUrl(params: OidcClientParams): Promise<URL>;
+/** Build the embedded `/embed/authorize` iframe URL (same PKCE S256 params). */
+declare function buildEmbedUrl(params: OidcClientParams): Promise<URL>;
+/**
+ * Validate an incoming `postMessage` event against the configured authority
+ * origin (never hardcoded) AND the iframe's `contentWindow` (so a same-origin
+ * event from an unexpected frame is ignored).
+ */
+declare function isTrustedBridgeMessage(event: MessageEvent, authority: string, iframe: HTMLIFrameElement): boolean;
+/** Parse a `jamauth:authorize` relay payload; returns `null` for other types. */
+declare function parseAuthorizeMessage(data: unknown): {
+    code: string;
+    state: string;
+} | null;
+/** Parse a `jamauth:ready` handshake payload; returns `true` for the handshake. */
+declare function isReadyMessage(data: unknown): data is ReadyMessage;
+/** Store a minted token response (mirrors `oidc-capture.ts`). */
+declare function storeTokenResponse(response: TokenResponse): void;
+/** Clear the stored session tokens (sign-out). */
+declare function clearStoredTokens(): void;
+/**
+ * Exchange an authorization `code` for tokens via a PUBLIC PKCE request
+ * (`grant_type=authorization_code`, no client_secret, no Authorization header).
+ * The token endpoint defaults to `${authority}/token` (CORS-allowed for the
+ * registered client origin via `clientBasedCORS`).
+ */
+declare function exchangeCodeForToken(params: OidcClientParams, code: string): Promise<TokenResponse>;
+/**
+ * Fallback to a top-level redirect with a fresh PKCE `authorizeUrl`. Used when
+ * the embedded iframe is blocked (or fails to handshake) — idempotent and
+ * correct, so a false positive degrades to the top-level flow rather than a
+ * broken UX.
+ */
+declare function fallbackToTopLevelRedirect(authorizeUrl: URL): void;
+
+/** Configuration carried by `JamauthProvider`. */
+interface JamauthConfig {
+    /** The jamauth issuer/authority origin, e.g. `https://jamauth.net`. */
+    authority: string;
+    clientId: string;
+    redirectUri: string;
+    resource?: string;
+    scope?: string;
+    tokenEndpoint?: string;
+    loginHint?: string;
+    /** Blocked-iframe handshake timeout in ms (default 5000). */
+    handshakeTimeoutMs?: number;
+    /** Called once the authorization code is exchanged for tokens. */
+    onToken?: (response: TokenResponse) => void;
+}
+/** Provide the jamauth authority + client identity to the embedded auth surface. */
+declare function JamauthProvider({ config, children, }: {
+    config: JamauthConfig;
+    children: ReactNode;
+}): react.JSX.Element;
+/** Read the configured jamauth client identity (throws outside a provider). */
+declare function useJamauth(): JamauthConfig;
+interface SessionState {
+    isAuthenticated: boolean;
+    token: string | null;
+}
+/** Reactive session state sourced from the stored access token. */
+declare function useSession(): SessionState;
+/** High-level auth surface: session state plus sign-out. */
+declare function useAuth(): SessionState & {
+    signOut: () => void;
+};
+/** Low-level OIDC bridge bound to the configured authority/client identity. */
+declare function useOidc(): {
+    authorityOrigin: () => string;
+    buildAuthorizeUrl: () => Promise<URL>;
+    buildEmbedUrl: (prompt?: string) => Promise<URL>;
+    exchangeCodeForToken: (code: string) => Promise<TokenResponse>;
+};
+/** Renders `children` only while authenticated (access token present). */
+declare function SignedIn({ children }: {
+    children: ReactNode;
+}): react.JSX.Element | null;
+/** Renders `children` only while signed out (no access token present). */
+declare function SignedOut({ children }: {
+    children: ReactNode;
+}): react.JSX.Element | null;
+
+interface SignInProps {
+    /** Override the handshake timeout (ms) for this surface. */
+    handshakeTimeoutMs?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Embedded sign-in surface — an iframe wrapper around the jamauth
+ * `/embed/authorize` flow. This component renders **no credential inputs**:
+ * the email+password form (and MFA / forgot / reset / verify) lives on the
+ * jamauth authority inside the frame, and the completed authorization code is
+ * relayed back to the parent via `postMessage`.
+ */
+declare function SignIn({ className, style }: SignInProps): react.JSX.Element;
+
+interface SignUpProps {
+    /** Override the handshake timeout (ms) for this surface. */
+    handshakeTimeoutMs?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Embedded sign-up surface — an iframe wrapper around the jamauth
+ * `/embed/authorize` flow with `prompt=register`. Like `SignIn`, this renders
+ * **no credential inputs**; the sign-up form lives on the jamauth authority
+ * inside the frame and the completed authorization code is relayed back via
+ * `postMessage`.
+ */
+declare function SignUp({ className, style }: SignUpProps): react.JSX.Element;
+
+interface UserButtonProps {
+    /** Label shown when signed out (default "Sign in"). */
+    signInLabel?: ReactNode;
+    /** Label shown when signed in (default "Sign out"). */
+    signOutLabel?: ReactNode;
+    /** Called instead of the default sign-out when the user is signed in. */
+    onSignOut?: () => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A minimal, framework-agnostic account button. It reflects the stored session
+ * state and, when signed in, signs the user out (or delegates to `onSignOut`).
+ * It renders no credential inputs.
+ */
+declare function UserButton({ signInLabel, signOutLabel, onSignOut, className, style, }: UserButtonProps): react.JSX.Element;
+
+type EmbeddedStatus = 'loading' | 'ready' | 'authenticated' | 'fallback';
+interface EmbeddedAuthState {
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    src: string;
+    status: EmbeddedStatus;
+}
+/**
+ * Mount the embedded `/embed/authorize` iframe and drive the confirmation
+ * handshake + timeout fallback:
+ *
+ * - `iframe.onload` is NOT authoritative (a `frame-ancestors`-blocked frame
+ *   still fires `onload`). Instead the parent validates
+ *   `event.origin === authorityOrigin` (derived from the configured authority,
+ *   never hardcoded) **and** `event.source === iframe.contentWindow`.
+ * - A `handshakeTimeoutMs` timer (default ~5s) falls back to a top-level
+ *   `window.location.assign(freshPkceAuthorizeUrl)` when no `jamauth:ready`
+ *   arrives — idempotent and correct, so a false positive degrades to the
+ *   top-level flow rather than a broken UX.
+ * - On `jamauth:authorize`, the code is exchanged via public PKCE and the
+ *   tokens are stored.
+ */
+declare function useEmbeddedAuth(prompt?: string): EmbeddedAuthState;
+
+export { type AuthorizeMessage, type EmbeddedAuthState, type EmbeddedStatus, type JamauthConfig, JamauthProvider, type OidcClientParams, type ReadyMessage, SESSION_CHANGED_EVENT, STORAGE_KEYS, type SessionState, SignIn, type SignInProps, SignUp, type SignUpProps, SignedIn, SignedOut, type TokenResponse, UserButton, type UserButtonProps, authorityOrigin, buildAuthorizeUrl, buildEmbedUrl, clearStoredTokens, exchangeCodeForToken, fallbackToTopLevelRedirect, isReadyMessage, isTrustedBridgeMessage, parseAuthorizeMessage, storeTokenResponse, useAuth, useEmbeddedAuth, useJamauth, useOidc, useSession };