@udibo/oauth2 0.4.0 → 0.5.0

package/esm/models/client.d.ts

@@ -33,7 +33,9 @@ export interface ClientInterface {
      * the request when none authorizes it.
      *
      * An ordinary entry is a **literal**, compared by exact string match (RFC
-     * 6749 §3.1.2.3), and an exact match always wins. An entry may instead be a
+     * 6749 §3.1.2.3), and an exact match always wins. A literal on a loopback
+     * IP host (`127.0.0.1` or `[::1]`) also matches the same URI on any port,
+     * for native apps (RFC 8252 §7.3). An entry may instead be a
      * **pattern** — one `*` in the leftmost host label, `https` only, over a
      * single registrable domain (`https://myapp-*.myorg.deno.net/cb`) — so one
      * registration covers the per-deploy hostnames a preview environment
@@ -48,9 +50,10 @@ export interface ClientInterface {
      * **literal** entry, so order the array with that default first. When omitted
      * or empty, no redirect URI is authorized at all.
      *
-     * A legacy literal entry containing a `*` (registrable before patterns
-     * existed) now matches **nothing** — the value reads as a pattern and fails
-     * the rules. That fails closed, but silently: re-register such a client.
+     * Any entry containing a `*` is read as a pattern, so a literal URI that
+     * happens to contain one matches **nothing** unless it also satisfies the
+     * pattern rules. That fails closed, but silently: register such a URI in a
+     * form without `*`.
      */
     redirectUris?: string[];
     /**

package/esm/models/token.d.ts

@@ -62,9 +62,8 @@ export interface RefreshToken<Client extends ClientInterface, User, Scope extend
      * service that persists refresh tokens **must** persist and restore it —
      * dropping it on the round trip disables the cap.
      *
-     * A record without an anchor (one stored before the cap existed) rotates
-     * once uncapped; that rotation is issued with a fresh anchor, so the family
-     * is capped from then on.
+     * A record without an anchor rotates once uncapped; that rotation is issued
+     * with a fresh anchor, so the family is capped from then on.
      */
     familyCreatedAt?: Date;
 }

package/esm/react/callback.d.ts

@@ -7,9 +7,9 @@
  * component renders its `fallback` with a clear error rather than pretend
  * otherwise.
  *
- * Idempotent against React 18 strict-mode double-mounts because the
- * client itself dedupes by `code` — the second invocation returns the
- * first call's promise.
+ * Idempotent against React strict-mode double-mounts because the client
+ * dedupes by `code`: a second call while the first exchange is still in
+ * flight returns the first call's promise.
  *
  * @module
  */

package/esm/react/callback.js

@@ -9,9 +9,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * component renders its `fallback` with a clear error rather than pretend
  * otherwise.
  *
- * Idempotent against React 18 strict-mode double-mounts because the
- * client itself dedupes by `code` — the second invocation returns the
- * first call's promise.
+ * Idempotent against React strict-mode double-mounts because the client
+ * dedupes by `code`: a second call while the first exchange is still in
+ * flight returns the first call's promise.
  *
  * @module
  */

package/esm/react/components/class-names.d.ts

@@ -18,8 +18,7 @@ import type { AuthFormClassNames } from "./types.js";
  * {@link AuthFormClassNamesProvider}'s map with `overrides` applied slot by
  * slot. An absent or `undefined` slot in `overrides` keeps the inherited value,
  * and with no provider above the map is empty (every slot `undefined`), so the
- * hook is safe to call anywhere. This is the only place the precedence rule is
- * implemented.
+ * hook is safe to call anywhere.
  *
  * The result is cached on the slot values, so passing a fresh `overrides`
  * literal every render returns the identical map.
@@ -48,10 +47,8 @@ import type { AuthFormClassNames } from "./types.js";
  */
 export declare function useAuthFormClassNames(overrides?: AuthFormClassNames): Readonly<AuthFormClassNames>;
 /**
- * Publishes an already-resolved map verbatim, without merging. A form and
- * `AuthFormShell` resolve once through {@link useAuthFormClassNames} and
- * publish through this, so the precedence rule keeps exactly one
- * implementation. App code wants {@link AuthFormClassNamesProvider}.
+ * Publishes an already-resolved map (from {@link useAuthFormClassNames})
+ * verbatim, without merging. App code wants {@link AuthFormClassNamesProvider}.
  */
 export declare function AuthFormClassNamesScope(props: {
     classNames: Readonly<AuthFormClassNames>;

package/esm/react/components/class-names.js

@@ -35,8 +35,7 @@ function slotKey(classNames) {
  * {@link AuthFormClassNamesProvider}'s map with `overrides` applied slot by
  * slot. An absent or `undefined` slot in `overrides` keeps the inherited value,
  * and with no provider above the map is empty (every slot `undefined`), so the
- * hook is safe to call anywhere. This is the only place the precedence rule is
- * implemented.
+ * hook is safe to call anywhere.
  *
  * The result is cached on the slot values, so passing a fresh `overrides`
  * literal every render returns the identical map.
@@ -78,10 +77,8 @@ export function useAuthFormClassNames(overrides) {
     return held.current.resolved;
 }
 /**
- * Publishes an already-resolved map verbatim, without merging. A form and
- * `AuthFormShell` resolve once through {@link useAuthFormClassNames} and
- * publish through this, so the precedence rule keeps exactly one
- * implementation. App code wants {@link AuthFormClassNamesProvider}.
+ * Publishes an already-resolved map (from {@link useAuthFormClassNames})
+ * verbatim, without merging. App code wants {@link AuthFormClassNamesProvider}.
  */
 export function AuthFormClassNamesScope(props) {
     const { classNames, children } = props;

package/esm/react/components/internal.d.ts

@@ -2,17 +2,10 @@ import { type ReactNode, type Ref } from "react";
 import type { AuthFieldProps, AuthFormState } from "./use-auth-form.js";
 import type { AuthFormClassNames, AuthFormValues, SocialProvidersProps } from "./types.js";
 /**
- * The single exit every default form component returns through — it owns both
- * outcomes, so a form has one `return` and cannot leave a subtree unscoped.
- *
- * With no `render`, it lays out the markup the forms share: the root wrapper
- * carrying `data-oauth2-form={name}`, then the `<form>` with its error summary
- * and the caller's fields. Use `aboveForm` for content that belongs inside the
- * root but outside the form (social buttons, an enrollment secret), and
- * `succeeded` for a terminal state that replaces the form entirely. With a
- * `render` — the form's render-prop `children` — that markup is skipped for the
- * caller's own. Either way the already-resolved `classNames` is published to
- * what renders, so the elements inside take their classes from the tree.
+ * What every default form component returns: the shared root, `<form>` and
+ * error summary, or the caller's `render` output instead, with the resolved
+ * `classNames` published to either. `aboveForm` sits inside the root but
+ * outside the form; `succeeded` replaces the form.
  */
 export declare function AuthFormShell<V extends AuthFormValues>(props: {
     name: string;
@@ -48,12 +41,9 @@ export declare function ErrorSummary(props: {
     focusTrigger?: number;
 }): ReactNode;
 /**
- * Moves keyboard focus to the first field that came back with an error after a
- * failed submit, so a screen-reader / keyboard user lands on the control to fix
- * (its label + error are read via `aria-describedby`) instead of being left on
- * the submit button. No-ops on the initial render and when the form
- * carries a form-level error ({@link ErrorSummary} owns that focus). Call it
- * once, unconditionally, from a form component built on {@link useAuthForm}.
+ * After a failed submit, focuses the first field with an error; does nothing
+ * when there is a form-level error, which {@link ErrorSummary} focuses. Call
+ * once, unconditionally, from a form built on {@link useAuthForm}.
  */
 export declare function useFocusFirstError<V extends AuthFormValues>(form: AuthFormState<V>): void;
 export declare function SocialButtons(props: SocialProvidersProps): ReactNode;

package/esm/react/components/internal.js

@@ -2,17 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useRef, } from "react";
 import { AuthFormClassNamesScope, useAuthFormClassNames, } from "./class-names.js";
 /**
- * The single exit every default form component returns through — it owns both
- * outcomes, so a form has one `return` and cannot leave a subtree unscoped.
- *
- * With no `render`, it lays out the markup the forms share: the root wrapper
- * carrying `data-oauth2-form={name}`, then the `<form>` with its error summary
- * and the caller's fields. Use `aboveForm` for content that belongs inside the
- * root but outside the form (social buttons, an enrollment secret), and
- * `succeeded` for a terminal state that replaces the form entirely. With a
- * `render` — the form's render-prop `children` — that markup is skipped for the
- * caller's own. Either way the already-resolved `classNames` is published to
- * what renders, so the elements inside take their classes from the tree.
+ * What every default form component returns: the shared root, `<form>` and
+ * error summary, or the caller's `render` output instead, with the resolved
+ * `classNames` published to either. `aboveForm` sits inside the root but
+ * outside the form; `succeeded` replaces the form.
  */
 export function AuthFormShell(props) {
     const { name, form, className, classNames, render, rootProps, aboveForm, succeeded, children, action, method, formRef, } = props;
@@ -46,12 +39,9 @@ export function ErrorSummary(props) {
     return (_jsx("div", { ref: ref, tabIndex: -1, "data-oauth2-error-summary": "", className: classNames.errorSummary, children: _jsx("span", { role: "alert", "data-oauth2-error-summary-message": "", children: error }) }));
 }
 /**
- * Moves keyboard focus to the first field that came back with an error after a
- * failed submit, so a screen-reader / keyboard user lands on the control to fix
- * (its label + error are read via `aria-describedby`) instead of being left on
- * the submit button. No-ops on the initial render and when the form
- * carries a form-level error ({@link ErrorSummary} owns that focus). Call it
- * once, unconditionally, from a form component built on {@link useAuthForm}.
+ * After a failed submit, focuses the first field with an error; does nothing
+ * when there is a form-level error, which {@link ErrorSummary} focuses. Call
+ * once, unconditionally, from a form built on {@link useAuthForm}.
  */
 export function useFocusFirstError(form) {
     const handled = useRef(0);

package/esm/react/components/mod.d.ts

@@ -27,9 +27,12 @@
  * ## Server-rendered pages
  *
  * Pass `action` + `method` and the rendered `<form>` carries them, so a
- * server-rendered page still posts when JavaScript never arrives — every field
- * carries its `name`, so the native post sends the same keys `onSubmit`
- * receives. Once React is running, `onSubmit` handles the submit and the
+ * server-rendered page still posts when JavaScript never arrives — every
+ * rendered field carries its `name`, so the native post sends those fields
+ * under the keys `onSubmit` receives. Values a form holds without rendering a
+ * field for them are absent from a native post: `ResetPasswordForm`'s
+ * `token`, `MfaChallengeForm`'s `method`, and any `SignUpForm` field left
+ * hidden. Once React is running, `onSubmit` handles the submit and the
  * native post is suppressed. `formRef` hands you the same `<form>` element, for
  * example to trigger a native `submit()` yourself.
  *
@@ -56,8 +59,7 @@
  * - One-time-code fields use `autocomplete="one-time-code"` and **never block
  *   paste** (WCAG 2.2 §3.3.8 Accessible Authentication).
  * - Section titles carry heading semantics; the components ship unstyled, so
- *   **contrast and visible focus are yours to satisfy** with your own theme —
- *   the ratios and focus rules Udibo uses are in its `DESIGN.md`.
+ *   **contrast and visible focus are yours to satisfy** with your own theme.
  *
  * @example Plain React Router v7
  * ```tsx

package/esm/react/components/mod.js

@@ -27,9 +27,12 @@
  * ## Server-rendered pages
  *
  * Pass `action` + `method` and the rendered `<form>` carries them, so a
- * server-rendered page still posts when JavaScript never arrives — every field
- * carries its `name`, so the native post sends the same keys `onSubmit`
- * receives. Once React is running, `onSubmit` handles the submit and the
+ * server-rendered page still posts when JavaScript never arrives — every
+ * rendered field carries its `name`, so the native post sends those fields
+ * under the keys `onSubmit` receives. Values a form holds without rendering a
+ * field for them are absent from a native post: `ResetPasswordForm`'s
+ * `token`, `MfaChallengeForm`'s `method`, and any `SignUpForm` field left
+ * hidden. Once React is running, `onSubmit` handles the submit and the
  * native post is suppressed. `formRef` hands you the same `<form>` element, for
  * example to trigger a native `submit()` yourself.
  *
@@ -56,8 +59,7 @@
  * - One-time-code fields use `autocomplete="one-time-code"` and **never block
  *   paste** (WCAG 2.2 §3.3.8 Accessible Authentication).
  * - Section titles carry heading semantics; the components ship unstyled, so
- *   **contrast and visible focus are yours to satisfy** with your own theme —
- *   the ratios and focus rules Udibo uses are in its `DESIGN.md`.
+ *   **contrast and visible focus are yours to satisfy** with your own theme.
  *
  * @example Plain React Router v7
  * ```tsx

package/esm/react/components/types.d.ts

@@ -107,7 +107,7 @@ export interface AuthFormClassNames extends BaseClassNames {
     /** Each inline field error (`data-oauth2-error`). */
     error?: string;
     /**
-     * Inline content rendered under a field — today the sign-in form's "Forgot
+     * Inline content rendered under a field — the sign-in form's "Forgot
      * password?" link (`data-oauth2-forgot-password`).
      */
     hint?: string;
@@ -186,17 +186,19 @@ export interface BaseAuthFormProps<V extends AuthFormValues> {
     /**
      * `action` for the rendered `<form>`. Set it (with {@link method}) on a
      * server-rendered page so the form still posts when JavaScript never
-     * arrives; every field carries its `name`, so a native post sends the same
-     * keys `onSubmit` receives. Once React is running, `onSubmit` handles the
-     * submit and the native post is suppressed.
+     * arrives; every rendered field carries its `name`, so a native post sends
+     * those fields under the keys `onSubmit` receives. A value the form holds
+     * without a rendered field (such as `ResetPasswordForm`'s `token`) is not
+     * posted, so the server's handler must obtain it another way. Once React is
+     * running, `onSubmit` handles the submit and the native post is suppressed.
      *
      * Ignored in render-prop mode — you own the `<form>` there.
      */
     action?: string;
     /**
      * `method` for the rendered `<form>`. Defaults to `"post"` whenever
-     * {@link action} is set, because the fields these forms render — passwords,
-     * one-time codes, reset tokens — must never reach a URL, where a `get` form
+     * {@link action} is set, because the fields these forms render — passwords
+     * and one-time codes — must never reach a URL, where a `get` form
      * would put them: browser history, the `Referer` sent to every third-party
      * asset on the destination page, and the server's access log.
      */

package/esm/react/context.d.ts

@@ -14,9 +14,9 @@ export interface OAuth2State {
     /** Whether a user is currently authenticated. */
     isAuthenticated: boolean;
     /**
-     * `true` during the initial session probe and during a token refresh
-     * with no currently valid access token. Settles to `false` once
-     * authentication state is known.
+     * `true` while the provider's initial session probe is in flight; `false`
+     * once it settles, and from the start when the provider is given
+     * `initialState`. A later token refresh does not set it.
      */
     isLoading: boolean;
     /**

package/esm/react/provider.d.ts

@@ -19,8 +19,9 @@ export interface OAuth2ProviderProps {
      * Optional pre-resolved auth state (typically from a server-side
      * session probe). Populating this skips the on-mount session probe
      * and renders the authenticated tree on the first paint — no
-     * hydration flash. Pass a stable reference (don't construct it inline
-     * in render) so the on-mount effect doesn't re-run.
+     * hydration flash. When a later render passes a different value, the
+     * provider re-seeds its state only if `isAuthenticated` or `user.sub`
+     * changed, so an object built inline in render is fine.
      */
     initialState?: Partial<OAuth2State>;
     /** The app subtree that reads auth state via `useOAuth2()`. */

package/esm/react/provider.js

@@ -19,24 +19,12 @@ const DEFAULT_STATE = {
 };
 const RENEW_SKEW_SECONDS = 30;
 const MIN_RENEW_MS = 5_000;
-/**
- * Fraction of the renew delay given up to jitter, applied one-sided so a renew
- * never lands later than the un-jittered schedule.
- */
 const RENEW_JITTER = 0.1;
 const isBrowser = () => typeof window !== "undefined";
-/**
- * Delay before renewing a session that expires in `expiresIn` seconds.
- *
- * Floors at {@link MIN_RENEW_MS}, so `0` — which a `DirectClient` reports for
- * an already-expired token a refresh token can still revive — schedules a
- * near-immediate renew rather than nothing at all.
- */
 function renewDelayMs(expiresIn) {
     const base = Math.max(MIN_RENEW_MS, (expiresIn - RENEW_SKEW_SECONDS) * 1000);
     return base * (1 - RENEW_JITTER * Math.random());
 }
-/** Seconds until `tokens` expires, or `null` when the server said nothing. */
 function expiresInFrom(tokens) {
     if (!tokens.accessTokenExpiresAt)
         return null;
@@ -65,7 +53,6 @@ export function OAuth2Provider(props) {
         let cancelled = false;
         const handle = (event) => {
             setState((prev) => reduce(prev, event));
-            // The `authenticated` event carries tokens only, so refetch user claims.
             if (event.type === "authenticated") {
                 client.getUser().then((user) => {
                     if (!cancelled)

package/esm/react/require-auth.d.ts

@@ -5,9 +5,6 @@
  * `returnTo` set to the current path, and renders a configurable
  * `fallback` while the redirect is in flight.
  *
- * Avoids the `withAuthenticationRequired` re-mount footgun (the HOC
- * isn't created in render; this component just gates its children).
- *
  * @module
  */
 import { type ReactNode } from "react";

package/esm/react/require-auth.js

@@ -6,9 +6,6 @@
  * `returnTo` set to the current path, and renders a configurable
  * `fallback` while the redirect is in flight.
  *
- * Avoids the `withAuthenticationRequired` re-mount footgun (the HOC
- * isn't created in render; this component just gates its children).
- *
  * @module
  */
 import { useEffect } from "react";

package/esm/react/testing.d.ts

@@ -132,8 +132,9 @@ export declare class MockOAuth2Client extends OAuth2ClientBase implements MockOA
     setSessionExpiresIn(seconds: number | null): void;
 }
 /**
- * A real `BffClient` whose four session operations answer from mock state
- * instead of the BFF. `useBffClient()` accepts it.
+ * A real `BffClient` whose session operations, `login`, `logout` and `fetch`
+ * answer from mock state or pass through instead of reaching the BFF.
+ * `useBffClient()` accepts it.
  */
 export declare class MockBffClient extends BffClient implements MockOAuth2Controls {
     #private;

package/esm/react/testing.js

@@ -47,7 +47,6 @@ import "../_dnt.polyfills.js";
 import { useMemo } from "react";
 import { BffClient, DirectClient, OAuth2ClientBase, } from "../client/mod.js";
 import { OAuth2Context } from "./context.js";
-/** The mock behavior each client class delegates to. */
 class MockCore {
     initialState;
     renewCount = 0;
@@ -197,8 +196,9 @@ export class MockOAuth2Client extends OAuth2ClientBase {
     }
 }
 /**
- * A real `BffClient` whose four session operations answer from mock state
- * instead of the BFF. `useBffClient()` accepts it.
+ * A real `BffClient` whose session operations, `login`, `logout` and `fetch`
+ * answer from mock state or pass through instead of reaching the BFF.
+ * `useBffClient()` accepts it.
  */
 export class MockBffClient extends BffClient {
     #core;

package/esm/react/use-oauth2.d.ts

@@ -3,7 +3,7 @@ import { type BaseLoginOptions, BffClient, DirectClient, type LogoutOptions, typ
 export interface UseOAuth2Result {
     /** True iff a user is authenticated. */
     isAuthenticated: boolean;
-    /** True during the initial probe / a refresh in progress. */
+    /** True while the provider's initial session probe is in flight. */
     isLoading: boolean;
     /** Current user claims, or `null`. */
     user: UserInfoClaims | null;