@udibo/oauth2 0.1.0

package/esm/react/testing.js

@@ -0,0 +1,461 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Testing helpers for the `@udibo/oauth2/react` adapter.
+ *
+ * Three mock clients and a provider:
+ *
+ * - {@link createMockOAuth2Client} — an `OAuth2ClientBase` with no HTTP,
+ *   PKCE, or storage behind it. Use it for a component written against the
+ *   shared surface.
+ * - {@link createMockBffClient} / {@link createMockDirectClient} — the same
+ *   mock behavior on a real `BffClient` / `DirectClient` subclass, so
+ *   `useBffClient()`, `useDirectClient()`, and `<OAuth2Callback>` accept them.
+ *   Reach for these when the component under test narrows.
+ * - {@link MockOAuth2Provider} — drop-in replacement for `<OAuth2Provider>`
+ *   that skips the initial session probe and accepts any of the three. Use it
+ *   to unit-test components that consume `useOAuth2()` / `<RequireAuth>`
+ *   without any network.
+ *
+ * Every mock emits on the same event bus the real clients use, so a subtree
+ * under a real `<OAuth2Provider>` re-renders just as it would in production.
+ * {@link MockOAuth2Provider} is not live: it seeds its context once from the
+ * client and keeps that snapshot, so a test that needs the state to *change*
+ * mid-render should mount a real `<OAuth2Provider>` around the mock client and
+ * call `signIn` / `signOut` on it. Configure `sessionExpiresIn` to exercise
+ * `<OAuth2Provider>`'s pre-expiry renew timer, and read
+ * {@link MockOAuth2Controls.renewCount} to assert it fired.
+ *
+ * **JSDOM recipes** for component tests in this adapter:
+ *
+ * - `window.location.assign` — the adapter's `login()` / `logout()` (via
+ *   `useOAuth2()` and `<RequireAuth>`) navigate by calling
+ *   `window.location.assign(url)`. JSDOM throws on unhandled navigation;
+ *   stub it: `stub(window.location, "assign", () => {})` (or the
+ *   equivalent for your runner).
+ * - `crypto.subtle` — required for PKCE in a real `DirectClient`. The mocks
+ *   don't use it, so JSDOM tests of components-with-mock-client are
+ *   safe out of the box.
+ * - `sessionStorage` — needed by
+ *   `SessionStorageAuthRequestStorage`. JSDOM ships one; the mocks
+ *   never touch it.
+ * - `history.replaceState` — `<OAuth2Callback>`'s default `onNavigate`
+ *   uses it. JSDOM ships it.
+ *
+ * @module
+ */
+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;
+    #user;
+    #isAuthenticated;
+    #logoutUrl;
+    #sessionExpiresIn;
+    #emit;
+    constructor(state, emit) {
+        this.#user = state.user ?? null;
+        this.#isAuthenticated = state.isAuthenticated ?? this.#user !== null;
+        this.#logoutUrl = state.logoutUrl ?? "/auth/logout";
+        this.#sessionExpiresIn = state.sessionExpiresIn ?? null;
+        this.#emit = emit;
+        this.initialState = {
+            isAuthenticated: this.#isAuthenticated,
+            user: this.#user,
+        };
+    }
+    session() {
+        return {
+            isAuthenticated: this.#isAuthenticated,
+            user: this.#isAuthenticated ? this.#user : null,
+            sessionExpiresIn: this.#isAuthenticated ? this.#sessionExpiresIn : null,
+            logoutUrl: this.#isAuthenticated ? this.#logoutUrl : null,
+        };
+    }
+    user() {
+        return this.#isAuthenticated ? this.#user : null;
+    }
+    renew() {
+        this.renewCount++;
+        return this.session();
+    }
+    signIn(user) {
+        this.#isAuthenticated = true;
+        this.#user = user ?? this.#user ?? { sub: "mock-user" };
+        this.#emit({ type: "authenticated", tokens: this.#tokens() });
+    }
+    signOut() {
+        this.#isAuthenticated = false;
+        this.#user = null;
+        this.#emit({ type: "logged_out", reason: "user" });
+    }
+    refreshTokens(expiresIn) {
+        if (expiresIn !== undefined)
+            this.#sessionExpiresIn = expiresIn;
+        this.#emit({ type: "token_refreshed", tokens: this.#tokens() });
+    }
+    setError(error) {
+        this.#emit({ type: "error", error });
+    }
+    setUser(user) {
+        this.#user = user;
+    }
+    setSessionExpiresIn(seconds) {
+        this.#sessionExpiresIn = seconds;
+    }
+    #tokens() {
+        return {
+            accessToken: "mock-access-token",
+            tokenType: "Bearer",
+            accessTokenExpiresAt: this.#sessionExpiresIn === null
+                ? undefined
+                : Date.now() + this.#sessionExpiresIn * 1000,
+        };
+    }
+}
+const MOCK_LOGIN_URL = "mock://login";
+/**
+ * A client that satisfies the shared `OAuth2ClientBase` surface without making
+ * a single request.
+ *
+ * Neither a `BffClient` nor a `DirectClient`, so `useBffClient()` and
+ * `useDirectClient()` reject it — that is deliberate, and
+ * {@link createMockBffClient} / {@link createMockDirectClient} are what a
+ * narrowing component wants.
+ */
+export class MockOAuth2Client extends OAuth2ClientBase {
+    #core;
+    /**
+     * Builds a mock client and snapshots its starting state.
+     *
+     * @param state Where the mock starts. Everything is optional; the default
+     * is a signed-out client.
+     */
+    constructor(state = {}) {
+        super();
+        this.#core = new MockCore(state, (event) => this.emit(event));
+    }
+    /** The starting state, defaults applied. */
+    get initialState() {
+        return this.#core.initialState;
+    }
+    /** How many times `renewSession()` has been called. */
+    get renewCount() {
+        return this.#core.renewCount;
+    }
+    /** Resolves a fixed `mock://login` URL without touching any network. */
+    login(_options) {
+        return Promise.resolve({ url: MOCK_LOGIN_URL });
+    }
+    /** Drops to signed out, emits `logged_out`, and returns no redirect URL. */
+    logout() {
+        this.signOut();
+        return Promise.resolve({});
+    }
+    /** The mock's current user, or `null` while signed out. */
+    getUser() {
+        return Promise.resolve(this.#core.user());
+    }
+    /** The mock's current state. */
+    getSession() {
+        return Promise.resolve(this.#core.session());
+    }
+    /** Counts the call and re-reads {@link getSession}. */
+    renewSession() {
+        return Promise.resolve(this.#core.renew());
+    }
+    /** Passes straight through to `globalThis.fetch` with no auth attached. */
+    fetch(input, init) {
+        return globalThis.fetch(input, init);
+    }
+    /** Pushes the mock into an authenticated state and emits `authenticated`. */
+    signIn(user) {
+        this.#core.signIn(user);
+    }
+    /** Pushes the mock into an unauthenticated state and emits `logged_out`. */
+    signOut() {
+        this.#core.signOut();
+    }
+    /** Emits `token_refreshed` with a bundle expiring in `expiresIn` seconds. */
+    refreshTokens(expiresIn) {
+        this.#core.refreshTokens(expiresIn);
+    }
+    /** Surfaces an error through the event bus. */
+    setError(error) {
+        this.#core.setError(error);
+    }
+    /** Replaces the cached user without changing authentication status. */
+    setUser(user) {
+        this.#core.setUser(user);
+    }
+    /** Replaces the reported seconds-to-expiry. */
+    setSessionExpiresIn(seconds) {
+        this.#core.setSessionExpiresIn(seconds);
+    }
+}
+/**
+ * A real `BffClient` whose four session operations answer from mock state
+ * instead of the BFF. `useBffClient()` accepts it.
+ */
+export class MockBffClient extends BffClient {
+    #core;
+    /**
+     * Builds a mock client and snapshots its starting state.
+     *
+     * @param state Where the mock starts. Everything is optional; the default
+     * is a signed-out client.
+     */
+    constructor(state = {}) {
+        super();
+        this.#core = new MockCore(state, (event) => this.emit(event));
+    }
+    /** The starting state, defaults applied. */
+    get initialState() {
+        return this.#core.initialState;
+    }
+    /** How many times `renewSession()` has been called. */
+    get renewCount() {
+        return this.#core.renewCount;
+    }
+    /** Resolves a fixed `mock://login` URL, bypassing the BFF's URL builder. */
+    login(_options) {
+        return Promise.resolve({ url: MOCK_LOGIN_URL });
+    }
+    /** Drops to signed out and returns no redirect URL. */
+    logout() {
+        this.signOut();
+        return Promise.resolve({});
+    }
+    /** The mock's current user, with no session probe. */
+    getUser() {
+        return Promise.resolve(this.#core.user());
+    }
+    /** The mock's current state, with no session probe. */
+    getSession() {
+        return Promise.resolve(this.#core.session());
+    }
+    /** Counts the call and re-reads {@link getSession}. */
+    renewSession() {
+        return Promise.resolve(this.#core.renew());
+    }
+    /** Passes straight through to `globalThis.fetch`. */
+    fetch(input, init) {
+        return globalThis.fetch(input, init);
+    }
+    /** Pushes the mock into an authenticated state and emits `authenticated`. */
+    signIn(user) {
+        this.#core.signIn(user);
+    }
+    /** Pushes the mock into an unauthenticated state and emits `logged_out`. */
+    signOut() {
+        this.#core.signOut();
+    }
+    /** Emits `token_refreshed` with a bundle expiring in `expiresIn` seconds. */
+    refreshTokens(expiresIn) {
+        this.#core.refreshTokens(expiresIn);
+    }
+    /** Surfaces an error through the event bus. */
+    setError(error) {
+        this.#core.setError(error);
+    }
+    /** Replaces the cached user without changing authentication status. */
+    setUser(user) {
+        this.#core.setUser(user);
+    }
+    /** Replaces the reported seconds-to-expiry. */
+    setSessionExpiresIn(seconds) {
+        this.#core.setSessionExpiresIn(seconds);
+    }
+}
+/**
+ * A real `DirectClient` whose session operations answer from mock state
+ * instead of a token endpoint. `useDirectClient()` and `<OAuth2Callback>`
+ * accept it.
+ *
+ * The token-holding methods it does **not** override (`refresh`,
+ * `handleAuthorizationCallback`, `introspect`, …) still reach for the network.
+ * Stub the one your test drives, or point a real `DirectClient` at
+ * `createMemoryAuthorizationServer().fetch` instead.
+ */
+export class MockDirectClient extends DirectClient {
+    #core;
+    /**
+     * Builds a mock client and snapshots its starting state.
+     *
+     * @param state Where the mock starts. Everything is optional; the default
+     * is a signed-out client.
+     */
+    constructor(state = {}) {
+        super({ clientId: "mock-client", endpoints: { token: "mock://token" } });
+        this.#core = new MockCore(state, (event) => this.emit(event));
+    }
+    /** The starting state, defaults applied. */
+    get initialState() {
+        return this.#core.initialState;
+    }
+    /** How many times `renewSession()` has been called. */
+    get renewCount() {
+        return this.#core.renewCount;
+    }
+    /** Resolves a fixed `mock://login` URL, skipping PKCE and storage. */
+    login(_options) {
+        return Promise.resolve({ url: MOCK_LOGIN_URL, state: "mock-state" });
+    }
+    /** Drops to signed out without revoking anything. */
+    logout() {
+        this.signOut();
+        return Promise.resolve({});
+    }
+    /** The mock's current user, with no token read. */
+    getUser() {
+        return Promise.resolve(this.#core.user());
+    }
+    /** The mock's current state, with no token read. */
+    getSession() {
+        return Promise.resolve(this.#core.session());
+    }
+    /** Counts the call and re-reads {@link getSession}. */
+    renewSession() {
+        return Promise.resolve(this.#core.renew());
+    }
+    /** Passes straight through to `globalThis.fetch`, attaching no bearer. */
+    fetch(input, init) {
+        return globalThis.fetch(input, init);
+    }
+    /** Resolves the mock access token without touching storage. */
+    getAccessToken() {
+        return Promise.resolve("mock-access-token");
+    }
+    /** Pushes the mock into an authenticated state and emits `authenticated`. */
+    signIn(user) {
+        this.#core.signIn(user);
+    }
+    /** Pushes the mock into an unauthenticated state and emits `logged_out`. */
+    signOut() {
+        this.#core.signOut();
+    }
+    /** Emits `token_refreshed` with a bundle expiring in `expiresIn` seconds. */
+    refreshTokens(expiresIn) {
+        this.#core.refreshTokens(expiresIn);
+    }
+    /** Surfaces an error through the event bus. */
+    setError(error) {
+        this.#core.setError(error);
+    }
+    /** Replaces the cached user without changing authentication status. */
+    setUser(user) {
+        this.#core.setUser(user);
+    }
+    /** Replaces the reported seconds-to-expiry. */
+    setSessionExpiresIn(seconds) {
+        this.#core.setSessionExpiresIn(seconds);
+    }
+}
+/**
+ * Builds a {@link MockOAuth2Client}. No HTTP, no storage, no PKCE — just
+ * state and an event bus that the React adapter reads through the provider.
+ *
+ * @param initialState Where the mock starts.
+ * @returns The mock client, ready to hand to a provider.
+ *
+ * @example
+ * ```tsx
+ * import { createMockOAuth2Client, MockOAuth2Provider } from
+ *   "@udibo/oauth2/react/testing";
+ *
+ * const client = createMockOAuth2Client({ user: { sub: "u1" } });
+ * render(
+ *   <MockOAuth2Provider client={client}>
+ *     <Header />
+ *   </MockOAuth2Provider>,
+ * );
+ * ```
+ */
+export function createMockOAuth2Client(initialState = {}) {
+    return new MockOAuth2Client(initialState);
+}
+/**
+ * Builds a {@link MockBffClient} — mock state on a real `BffClient`, so a
+ * component that calls `useBffClient()` can be unit-tested.
+ *
+ * @param initialState Where the mock starts.
+ * @returns The mock client, ready to hand to a provider.
+ *
+ * @example
+ * ```tsx
+ * import { createMockBffClient, MockOAuth2Provider } from
+ *   "@udibo/oauth2/react/testing";
+ *
+ * const client = createMockBffClient({ user: { sub: "u1" } });
+ * render(
+ *   <MockOAuth2Provider client={client}>
+ *     <SignInLink returnTo="/dashboard" />
+ *   </MockOAuth2Provider>,
+ * );
+ * ```
+ */
+export function createMockBffClient(initialState = {}) {
+    return new MockBffClient(initialState);
+}
+/**
+ * Builds a {@link MockDirectClient} — mock state on a real `DirectClient`, so
+ * a component that calls `useDirectClient()` (or mounts `<OAuth2Callback>`)
+ * can be unit-tested.
+ *
+ * @param initialState Where the mock starts.
+ * @returns The mock client, ready to hand to a provider.
+ *
+ * @example
+ * ```tsx
+ * import { createMockDirectClient, MockOAuth2Provider } from
+ *   "@udibo/oauth2/react/testing";
+ *
+ * const client = createMockDirectClient({ user: { sub: "u1" } });
+ * render(
+ *   <MockOAuth2Provider client={client}>
+ *     <TokenReadout />
+ *   </MockOAuth2Provider>,
+ * );
+ * ```
+ */
+export function createMockDirectClient(initialState = {}) {
+    return new MockDirectClient(initialState);
+}
+/**
+ * Drop-in replacement for `<OAuth2Provider>` that skips the on-mount
+ * session probe (the mock clients don't issue one) and surfaces the
+ * mock state synchronously.
+ *
+ * The context it publishes is a snapshot of the client as it was built (plus
+ * any `state` overrides): it subscribes to nothing, so calling `signIn` /
+ * `signOut` on the client afterwards does not re-render the subtree. Render
+ * the state you want, or use a real `<OAuth2Provider>` when the test is about
+ * a transition.
+ *
+ * @param props A mock client, optional state overrides, and children.
+ * @returns The subtree wrapped in a pre-resolved OAuth2 context.
+ */
+export function MockOAuth2Provider(props) {
+    const { client, state, children } = props;
+    const value = useMemo(() => {
+        const override = state ?? {};
+        const overrides = (key) => key in override;
+        return {
+            client,
+            isAuthenticated: overrides("isAuthenticated")
+                ? override.isAuthenticated === true
+                : client.initialState.isAuthenticated,
+            isLoading: override.isLoading ?? false,
+            user: overrides("user")
+                ? override.user ?? null
+                : client.initialState.user,
+            error: override.error ?? null,
+            sessionExpiresIn: override.sessionExpiresIn ?? null,
+            logoutUrl: override.logoutUrl ?? null,
+        };
+    }, [client, state]);
+    return (_jsx(OAuth2Context.Provider, { value: value, children: children }));
+}

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

@@ -0,0 +1,31 @@
+/**
+ * React hook exposing the signed-in user's {@link Authorization} — the same
+ * checkable object the resource server derives from an access token, built
+ * here from the session's id_token claims.
+ *
+ * @module
+ */
+import { type Authorization } from "../models/authorization.js";
+/**
+ * The signed-in user's authorization, derived from the session's claims.
+ *
+ * Browser checks are **rendering hints only** — show or hide an affordance,
+ * never gate the action itself; the API's middleware is the enforcement. An
+ * unauthenticated session yields an empty authorization (every predicate
+ * `false`), and id_token claims carry no OAuth2 scope, so
+ * {@link Authorization.hasScope} answers `false` here — scope is the API's
+ * check, not the browser's.
+ *
+ * @throws {Error} when called outside an `<OAuth2Provider>`.
+ *
+ * @example
+ * ```tsx
+ * import { useAuthorization } from "@udibo/oauth2/react";
+ *
+ * function PostActions() {
+ *   const authorization = useAuthorization();
+ *   return authorization.can("posts:write") ? <button>Edit</button> : null;
+ * }
+ * ```
+ */
+export declare function useAuthorization(): Authorization;

package/esm/react/use-authorization.js

@@ -0,0 +1,36 @@
+/**
+ * React hook exposing the signed-in user's {@link Authorization} — the same
+ * checkable object the resource server derives from an access token, built
+ * here from the session's id_token claims.
+ *
+ * @module
+ */
+import { useMemo } from "react";
+import { authorizationFromClaims, } from "../models/authorization.js";
+import { useOAuth2 } from "./use-oauth2.js";
+/**
+ * The signed-in user's authorization, derived from the session's claims.
+ *
+ * Browser checks are **rendering hints only** — show or hide an affordance,
+ * never gate the action itself; the API's middleware is the enforcement. An
+ * unauthenticated session yields an empty authorization (every predicate
+ * `false`), and id_token claims carry no OAuth2 scope, so
+ * {@link Authorization.hasScope} answers `false` here — scope is the API's
+ * check, not the browser's.
+ *
+ * @throws {Error} when called outside an `<OAuth2Provider>`.
+ *
+ * @example
+ * ```tsx
+ * import { useAuthorization } from "@udibo/oauth2/react";
+ *
+ * function PostActions() {
+ *   const authorization = useAuthorization();
+ *   return authorization.can("posts:write") ? <button>Edit</button> : null;
+ * }
+ * ```
+ */
+export function useAuthorization() {
+    const { user } = useOAuth2();
+    return useMemo(() => authorizationFromClaims(user), [user]);
+}

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

@@ -0,0 +1,112 @@
+import { type BaseLoginOptions, BffClient, DirectClient, type LogoutOptions, type OAuth2ClientBase, type OAuth2Error, type UserInfoClaims } from "../client/mod.js";
+/** Return value of {@link useOAuth2}. */
+export interface UseOAuth2Result {
+    /** True iff a user is authenticated. */
+    isAuthenticated: boolean;
+    /** True during the initial probe / a refresh in progress. */
+    isLoading: boolean;
+    /** Current user claims, or `null`. */
+    user: UserInfoClaims | null;
+    /** Last error surfaced by the client, or `null`. */
+    error: OAuth2Error | null;
+    /**
+     * Seconds until the session's access token expires, or `null` when unknown.
+     * The provider renews shortly before this elapses.
+     */
+    sessionExpiresIn: number | null;
+    /** A URL that ends the session, or `null` when the client offers none. */
+    logoutUrl: string | null;
+    /**
+     * Start a login. Calls `client.login(opts)` and, in the browser, navigates
+     * to the returned URL (the BFF login endpoint, or the authorization
+     * endpoint). Returns the `{ url }` so non-browser callers (SSR) can
+     * navigate themselves.
+     *
+     * Takes only what both clients understand. For a `DirectClient`'s per-call
+     * `scope` / `prompt` / `extraParams`, go through
+     * {@link useDirectClient}`().login(...)` — those options have no meaning to
+     * a BFF, which builds its own authorize request server-side.
+     */
+    login(opts?: BaseLoginOptions): Promise<{
+        url?: string;
+    }>;
+    /**
+     * Start a logout. Calls `client.logout(opts)` and, in the browser,
+     * navigates to the returned URL if the flow needs a redirect (the BFF
+     * logout endpoint, or the IDP end-session URL). Returns `{ url }` for
+     * SSR callers.
+     */
+    logout(opts?: LogoutOptions): Promise<{
+        url?: string;
+    }>;
+    /** Bound `client.fetch` — the request-with-auth helper. */
+    fetch: typeof fetch;
+    /**
+     * The underlying client. Narrow it with {@link useBffClient} or
+     * {@link useDirectClient} to reach transport-specific methods.
+     */
+    client: OAuth2ClientBase;
+}
+/**
+ * Reads the OAuth2 context, returning the current state and bound convenience
+ * methods. Works with either client, so components written against it don't
+ * care whether a BFF or this process holds the tokens.
+ *
+ * @returns Auth state plus `login` / `logout` / `fetch` and the raw client.
+ * @throws {Error} when called outside an `<OAuth2Provider>`.
+ *
+ * @example
+ * ```tsx
+ * import { useOAuth2 } from "@udibo/oauth2/react";
+ *
+ * function Header() {
+ *   const { isAuthenticated, user, login, logout } = useOAuth2();
+ *   return isAuthenticated
+ *     ? <button onClick={() => logout()}>Sign out {String(user?.sub)}</button>
+ *     : <button onClick={() => login()}>Sign in</button>;
+ * }
+ * ```
+ */
+export declare function useOAuth2(): UseOAuth2Result;
+/**
+ * The context's client, narrowed to a `BffClient`. Use it for the BFF-only
+ * surface — chiefly `loginContinuation`, for a "Sign in" link from your own
+ * create-account or forgot-password page.
+ *
+ * @returns The provider's `BffClient`.
+ * @throws {Error} when called outside an `<OAuth2Provider>`, or when the
+ * provider was given a `DirectClient` — the BFF routes it targets don't exist
+ * in that deployment.
+ *
+ * @example
+ * ```tsx
+ * import { useBffClient } from "@udibo/oauth2/react";
+ *
+ * function SignInLink({ returnTo }: { returnTo: string }) {
+ *   const client = useBffClient();
+ *   return <a href={client.loginContinuation(returnTo)}>Sign in</a>;
+ * }
+ * ```
+ */
+export declare function useBffClient(): BffClient;
+/**
+ * The context's client, narrowed to a `DirectClient`. Use it for the surface
+ * that only exists when this process holds the tokens — `getAccessToken`,
+ * `handleAuthorizationCallback`, `refresh`, `introspect`, `revoke`.
+ *
+ * @returns The provider's `DirectClient`.
+ * @throws {Error} when called outside an `<OAuth2Provider>`, or when the
+ * provider was given a `BffClient` — the browser never sees a token in that
+ * deployment, so there is none to hand back.
+ *
+ * @example
+ * ```tsx
+ * import { useDirectClient } from "@udibo/oauth2/react";
+ *
+ * function useBearer() {
+ *   const client = useDirectClient();
+ *   return () => client.getAccessToken();
+ * }
+ * ```
+ */
+export declare function useDirectClient(): DirectClient;