@udibo/oauth2 0.1.0

package/esm/client/base.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The surface {@link BffClient} and {@link DirectClient} share: subscribing to
+ * authentication events, starting and ending a login, reading the current
+ * session, and issuing authenticated requests.
+ *
+ * Program against {@link OAuth2ClientBase} when the code shouldn't care which
+ * transport holds the tokens — the React adapter's `<OAuth2Provider>` does
+ * exactly this. Reach for the concrete class when you need transport-specific
+ * capability: {@link BffClient.loginContinuation} or
+ * {@link DirectClient.getAccessToken}.
+ *
+ * @module
+ */
+import { type OAuth2ClientEvent, type OAuth2ClientEventListener } from "./events.js";
+/** Generic user-info claims returned by the userinfo or `id_token` helpers. */
+export type UserInfoClaims = Record<string, unknown>;
+/**
+ * The headers a wrapped `fetch` should send for `(input, init)`: the ones
+ * already on a `Request` input, overlaid with `init.headers`.
+ *
+ * Both client `fetch` wrappers need this because passing `headers` in an init
+ * *replaces* a `Request` input's header list rather than adding to it, which
+ * silently drops every header a caller set on the `Request`.
+ */
+export declare function mergedHeaders(input: RequestInfo | URL, init: RequestInit): Headers;
+/** Options accepted by every client. */
+export interface BaseOptions {
+    /**
+     * Optional fetch implementation. Defaults to `globalThis.fetch`.
+     *
+     * Inject a custom `fetch` for:
+     *
+     * - **Co-located auth servers** — pass `localAuthServerFetch(authServer)`
+     *   to dispatch token-endpoint calls directly into an in-process
+     *   `AuthorizationServer` without a socket round-trip.
+     * - **Tests** — pass the `fetch` from `createMemoryAuthorizationServer()`
+     *   (or any other `fetch`-compatible responder) so the client talks to
+     *   an in-memory server. Preferred over stubbing `globalThis.fetch`,
+     *   which would also intercept unrelated outbound requests the app may
+     *   make.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * The `login` options every client understands.
+ *
+ * Named apart from {@link LoginOptions} — which keeps the richer
+ * `DirectClient` shape it has always had — so that a consumer importing
+ * `LoginOptions` and passing `scope` still compiles. Reach for this one only
+ * when writing against {@link OAuth2ClientBase}.
+ */
+export interface BaseLoginOptions {
+    /** Path or URL to return to after a successful login. */
+    returnTo?: string;
+}
+/** Options every client's `logout` accepts. */
+export interface LogoutOptions {
+    /** Path or URL to return to after logout. */
+    returnTo?: string;
+}
+/** A URL the caller must navigate the browser to. */
+export interface LoginRedirect {
+    /** Where to send the browser to start (or resume) sign-in. */
+    url: string;
+}
+/**
+ * Where to send the browser to finish signing out, if anywhere. `url` is
+ * absent when the sign-out completed locally with nothing left to visit.
+ */
+export interface LogoutRedirect {
+    /** The logout / end-session URL, when the flow needs a redirect. */
+    url?: string;
+}
+/**
+ * The signed-out {@link SessionState}, frozen because it is returned by
+ * reference from every client's `getSession`.
+ */
+export declare const SIGNED_OUT: Readonly<SessionState>;
+/** A snapshot of who is signed in, as the client currently understands it. */
+export interface SessionState {
+    /** True iff a session is active. */
+    isAuthenticated: boolean;
+    /** Cached user claims, or `null`. */
+    user: UserInfoClaims | null;
+    /**
+     * Seconds until the session's access token expires, or `null` when unknown.
+     * A UI can use it to schedule {@link OAuth2ClientBase.renewSession} before
+     * expiry.
+     */
+    sessionExpiresIn: number | null;
+    /**
+     * A URL that ends the session, or `null` when the client has no such URL to
+     * offer (a direct client revokes locally instead — see
+     * {@link OAuth2ClientBase.logout}).
+     */
+    logoutUrl: string | null;
+}
+/**
+ * Base class for the OAuth2 clients. Owns the event bus and the resolved
+ * `fetch`; subclasses supply the transport.
+ *
+ * Not constructible on its own — build a {@link BffClient} (tokens live
+ * server-side behind a session cookie) or a {@link DirectClient} (this
+ * process holds the tokens) and pass it wherever an `OAuth2ClientBase` is
+ * accepted.
+ *
+ * @example Accept either client
+ * ```ts
+ * import type { OAuth2ClientBase } from "@udibo/oauth2/client";
+ *
+ * async function greet(client: OAuth2ClientBase): Promise<string> {
+ *   const { isAuthenticated, user } = await client.getSession();
+ *   return isAuthenticated ? `hello ${user?.sub}` : "hello stranger";
+ * }
+ * ```
+ */
+export declare abstract class OAuth2ClientBase {
+    #private;
+    /**
+     * Called by the concrete clients; there is nothing to construct here on its
+     * own.
+     *
+     * @param options Only `fetch` is read at this level — subclasses consume
+     * the rest of their own options.
+     */
+    protected constructor(options?: BaseOptions);
+    /**
+     * Subscribes to `authenticated` / `logged_out` / `token_refreshed` /
+     * `error` events. Returns a function that removes the listener.
+     *
+     * @param listener Called for every event, in subscription order. One
+     * listener throwing does not stop delivery to the rest.
+     */
+    subscribe(listener: OAuth2ClientEventListener): () => void;
+    /** Publishes an event to every subscriber. */
+    protected emit(event: OAuth2ClientEvent): void;
+    /**
+     * The configured fetch, resolved at call time so the client picks up a
+     * polyfilled global if the runtime installs one after construction.
+     */
+    protected fetchImpl(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Builds the URL that starts sign-in. The caller navigates the browser
+     * there; nothing is signed in until that round trip completes.
+     */
+    abstract login(options?: BaseLoginOptions): Promise<LoginRedirect>;
+    /**
+     * Ends the session and returns the URL to finish signing out, if the flow
+     * needs one. Emits `logged_out`.
+     */
+    abstract logout(options?: LogoutOptions): Promise<LogoutRedirect>;
+    /**
+     * The claims of the signed-in user, or `null` when nobody is signed in.
+     * Use {@link getSession} when you also need expiry or the logout URL.
+     */
+    abstract getUser(): Promise<UserInfoClaims | null>;
+    /**
+     * The current {@link SessionState}, as this client can determine it.
+     *
+     * **Never rejects.** A transport failure, an unreadable response, or claims
+     * that cannot be decoded all report a signed-out session and emit an `error`
+     * event instead of throwing, so a caller holding an `OAuth2ClientBase` needs
+     * no per-subclass `try`/`catch` to ask who is signed in. Rejection is
+     * reserved for a programming error, never a remote one.
+     */
+    abstract getSession(): Promise<SessionState>;
+    /**
+     * Brings the session up to date — renewing credentials where this client
+     * owns them — and returns the resulting {@link SessionState}. Call it
+     * shortly before {@link SessionState.sessionExpiresIn} elapses.
+     *
+     * **Never rejects**, on the same terms as {@link getSession}. Because this
+     * runs on a background timer, a transport failure emits no `error` event
+     * either: a blip that will simply be retried must not surface as a
+     * user-visible error over a session that is still valid. A session that has
+     * genuinely ended still emits `logged_out`.
+     */
+    abstract renewSession(): Promise<SessionState>;
+    /**
+     * Drop-in `fetch` that authenticates the request the way this client's
+     * transport requires, and recovers from a `401` where it can.
+     */
+    abstract fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}

package/esm/client/base.js

@@ -0,0 +1,93 @@
+/**
+ * The surface {@link BffClient} and {@link DirectClient} share: subscribing to
+ * authentication events, starting and ending a login, reading the current
+ * session, and issuing authenticated requests.
+ *
+ * Program against {@link OAuth2ClientBase} when the code shouldn't care which
+ * transport holds the tokens — the React adapter's `<OAuth2Provider>` does
+ * exactly this. Reach for the concrete class when you need transport-specific
+ * capability: {@link BffClient.loginContinuation} or
+ * {@link DirectClient.getAccessToken}.
+ *
+ * @module
+ */
+import { EventBus, } from "./events.js";
+/**
+ * The headers a wrapped `fetch` should send for `(input, init)`: the ones
+ * already on a `Request` input, overlaid with `init.headers`.
+ *
+ * Both client `fetch` wrappers need this because passing `headers` in an init
+ * *replaces* a `Request` input's header list rather than adding to it, which
+ * silently drops every header a caller set on the `Request`.
+ */
+export function mergedHeaders(input, init) {
+    const headers = new Headers(input instanceof Request ? input.headers : undefined);
+    for (const [name, value] of new Headers(init.headers)) {
+        headers.set(name, value);
+    }
+    return headers;
+}
+/**
+ * The signed-out {@link SessionState}, frozen because it is returned by
+ * reference from every client's `getSession`.
+ */
+export const SIGNED_OUT = Object.freeze({
+    isAuthenticated: false,
+    user: null,
+    sessionExpiresIn: null,
+    logoutUrl: null,
+});
+/**
+ * Base class for the OAuth2 clients. Owns the event bus and the resolved
+ * `fetch`; subclasses supply the transport.
+ *
+ * Not constructible on its own — build a {@link BffClient} (tokens live
+ * server-side behind a session cookie) or a {@link DirectClient} (this
+ * process holds the tokens) and pass it wherever an `OAuth2ClientBase` is
+ * accepted.
+ *
+ * @example Accept either client
+ * ```ts
+ * import type { OAuth2ClientBase } from "@udibo/oauth2/client";
+ *
+ * async function greet(client: OAuth2ClientBase): Promise<string> {
+ *   const { isAuthenticated, user } = await client.getSession();
+ *   return isAuthenticated ? `hello ${user?.sub}` : "hello stranger";
+ * }
+ * ```
+ */
+export class OAuth2ClientBase {
+    #events = new EventBus();
+    #customFetch;
+    /**
+     * Called by the concrete clients; there is nothing to construct here on its
+     * own.
+     *
+     * @param options Only `fetch` is read at this level — subclasses consume
+     * the rest of their own options.
+     */
+    constructor(options = {}) {
+        this.#customFetch = options.fetch;
+    }
+    /**
+     * Subscribes to `authenticated` / `logged_out` / `token_refreshed` /
+     * `error` events. Returns a function that removes the listener.
+     *
+     * @param listener Called for every event, in subscription order. One
+     * listener throwing does not stop delivery to the rest.
+     */
+    subscribe(listener) {
+        return this.#events.subscribe(listener);
+    }
+    /** Publishes an event to every subscriber. */
+    emit(event) {
+        this.#events.emit(event);
+    }
+    /**
+     * The configured fetch, resolved at call time so the client picks up a
+     * polyfilled global if the runtime installs one after construction.
+     */
+    fetchImpl(input, init) {
+        return (this.#customFetch ?? globalThis.fetch)(input, init);
+    }
+}

package/esm/client/bff-client.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Browser client for an app fronted by a Backend-for-Frontend.
+ *
+ * The BFF holds the tokens; this client only ever talks to the BFF's
+ * `/auth/*` routes with the session cookie attached, so no token reaches the
+ * browser. Pair it with the `@udibo/oauth2/hono/bff` adapter, or any BFF
+ * serving the same four routes.
+ *
+ * @module
+ */
+import { type BaseLoginOptions, type BaseOptions, type LoginRedirect, type LogoutOptions, type LogoutRedirect, OAuth2ClientBase, type SessionState, type UserInfoClaims } from "./base.js";
+/** Paths (or absolute URLs) for the BFF session endpoints. */
+export interface BffEndpoints {
+    /** Base URL the BFF is mounted under (e.g. `""` for same-origin). */
+    baseUrl?: string;
+    /** Path to the BFF's login route. Defaults to `/auth/login`. */
+    login?: string;
+    /**
+     * Path to the BFF's logout route. Defaults to `/auth/logout`.
+     *
+     * {@link BffClient.logout} only builds this URL; the caller navigates to it,
+     * so sign-out travels the BFF's `GET` route and is guarded by its
+     * same-origin check rather than the `x-csrf` header. Post to this path
+     * yourself, with that header, for the stronger check.
+     */
+    logout?: string;
+    /** Path to `GET /auth/session`. Defaults to `/auth/session`. */
+    session?: string;
+}
+/** Options accepted by {@link BffClient}. */
+export interface BffClientOptions extends BaseOptions {
+    /** Override the default `/auth/*` BFF session endpoint paths. */
+    endpoints?: BffEndpoints;
+    /**
+     * Path (or URL) of the authorization endpoint the BFF redirects to (e.g.
+     * `"/api/oauth2/authorize"`). Lets {@link BffClient.loginContinuation}
+     * recognize an in-flight authorize URL to resume. Optional — without it,
+     * `loginContinuation` always starts a fresh login.
+     */
+    authorizePath?: string;
+    /**
+     * Custom header sent on credentialed BFF requests — the `GET /auth/session`
+     * probe and the wrapped {@link BffClient.fetch} — so the BFF's CSRF guard
+     * accepts them. The header makes the request "non-simple", forcing a CORS
+     * preflight a cross-site page cannot pass.
+     *
+     * Defaults to `{ name: "x-csrf", value: "1" }`, matching `HonoBff`'s
+     * default. Set `false` to send no header (only if the BFF disables its
+     * CSRF check).
+     */
+    csrfHeader?: {
+        name?: string;
+        value?: string;
+    } | false;
+}
+/**
+ * OAuth2 client for a browser app whose sessions live in a
+ * Backend-for-Frontend.
+ *
+ * Every method here is a same-origin call to the BFF with `credentials:
+ * "include"`, never a call to the authorization server. There is no token
+ * storage, no PKCE, and no access token to read — if you need one, the app
+ * wants a {@link DirectClient} instead.
+ *
+ * @example Same-origin BFF
+ * ```ts
+ * import { BffClient } from "@udibo/oauth2/client";
+ *
+ * const client = new BffClient();
+ *
+ * const session = await client.getSession();
+ * if (!session.isAuthenticated) {
+ *   const { url } = await client.login({ returnTo: location.pathname });
+ *   location.assign(url);
+ * }
+ *
+ * const res = await client.fetch("/api/items");
+ * ```
+ *
+ * @example BFF mounted elsewhere, with a custom CSRF header
+ * ```ts
+ * import { BffClient } from "@udibo/oauth2/client";
+ *
+ * const client = new BffClient({
+ *   endpoints: { baseUrl: "https://api.example.com", login: "/session/start" },
+ *   csrfHeader: { name: "x-requested-with", value: "spa" },
+ * });
+ * ```
+ */
+export declare class BffClient extends OAuth2ClientBase {
+    #private;
+    /**
+     * Builds a client against the BFF's `/auth/*` routes.
+     *
+     * @param options Endpoint overrides, the CSRF header to send, and the
+     * `fetch` to use. Every field is optional; the defaults match `HonoBff`
+     * mounted at `/auth` on the same origin.
+     */
+    constructor(options?: BffClientOptions);
+    /**
+     * Builds the BFF login URL. Navigate the browser there; the BFF runs the
+     * authorization-code flow and drops the session cookie before redirecting
+     * back to `returnTo`.
+     *
+     * @param options `returnTo` is passed through as the `return_to` query
+     * parameter. The BFF is responsible for validating it against open
+     * redirects.
+     * @returns The URL to navigate to.
+     *
+     * @example
+     * ```ts
+     * import { BffClient } from "@udibo/oauth2/client";
+     *
+     * const client = new BffClient();
+     * const { url } = await client.login({ returnTo: "/dashboard" });
+     * location.assign(url);
+     * ```
+     */
+    login(options?: BaseLoginOptions): Promise<LoginRedirect>;
+    /**
+     * Builds the BFF logout URL and emits `logged_out` so the UI can render
+     * signed-out immediately. Navigate the browser to the returned URL; the BFF
+     * destroys the session and clears the cookie.
+     *
+     * @param options `returnTo` is passed through as the `return_to` query
+     * parameter.
+     * @returns The URL to navigate to.
+     *
+     * @example
+     * ```ts
+     * import { BffClient } from "@udibo/oauth2/client";
+     *
+     * const client = new BffClient();
+     * const { url } = await client.logout({ returnTo: "/" });
+     * location.assign(url!);
+     * ```
+     */
+    logout(options?: LogoutOptions): Promise<LogoutRedirect>;
+    /**
+     * Probes `GET /auth/session` and returns the full {@link SessionState} —
+     * `isAuthenticated`, `user`, plus the `sessionExpiresIn` and `logoutUrl` a
+     * SPA uses to schedule a re-probe and render a sign-out link.
+     *
+     * **Never rejects**, per {@link OAuth2ClientBase.getSession}: an
+     * unreachable BFF, a non-OK status, and a body that is not a JSON object
+     * (an HTML error page from a misrouted path is the common one) all read as
+     * signed out. A failure that was not simply "nobody is signed in" — anything
+     * other than a `401` — also emits an `error` event so a UI can tell the two
+     * apart. The read is bounded and deadlined like every other call this
+     * package makes.
+     *
+     * Only `isAuthenticated: true` carries `user` / `sessionExpiresIn` /
+     * `logoutUrl` through; an anonymous payload always reports them as `null`,
+     * whatever the BFF put in the body.
+     *
+     * @returns The session as the BFF reports it. Tokens are never included.
+     *
+     * @example
+     * ```ts
+     * import { BffClient } from "@udibo/oauth2/client";
+     *
+     * const { isAuthenticated, logoutUrl } = await new BffClient().getSession();
+     * ```
+     */
+    getSession(): Promise<SessionState>;
+    /**
+     * The signed-in user's claims from the session probe, or `null`.
+     *
+     * @returns The `user` field of {@link getSession}.
+     */
+    getUser(): Promise<UserInfoClaims | null>;
+    /**
+     * Re-probes `GET /auth/session`.
+     *
+     * The BFF owns credential renewal — its `attachToken` middleware refreshes
+     * the access token server-side when a proxied call needs one — so this
+     * reports the current state rather than driving a refresh itself. Call it
+     * shortly before {@link SessionState.sessionExpiresIn} elapses to keep the
+     * UI honest about whether the session is still alive.
+     *
+     * Emits no `error` event, per {@link OAuth2ClientBase.renewSession}: this
+     * runs on a background timer, where a failed probe means "ask again shortly",
+     * not "show the user a problem".
+     *
+     * @returns The refreshed {@link SessionState}.
+     */
+    renewSession(): Promise<SessionState>;
+    /**
+     * Fetches with the session cookie and the CSRF header attached, so the BFF
+     * authenticates the call and its CSRF guard accepts it.
+     *
+     * A `401` emits `logged_out` with reason `session_expired` and is returned
+     * as-is — the BFF, not the browser, decides whether a refresh is possible.
+     *
+     * @param input Request target, as for `fetch`. A `Request` keeps the headers
+     * and body it was built with.
+     * @param init Request options. A caller-set CSRF header is left alone, and
+     * `init.headers` override same-named headers on a `Request` input.
+     * @returns The BFF's response, unmodified.
+     *
+     * @example
+     * ```ts
+     * import { BffClient } from "@udibo/oauth2/client";
+     *
+     * const res = await new BffClient().fetch("/api/items");
+     * ```
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Builds the URL that (re)starts sign-in toward `returnTo`, for an app whose
+     * own login surface (a sign-in form, create-account, forgot-password) hands
+     * back to the BFF flow after authenticating a user: resume an in-flight
+     * authorize URL, or start a fresh BFF login.
+     *
+     * Pure and synchronous — safe in render. The mirror of
+     * `HonoBff.loginContinuation`, so both sides of the app agree on where
+     * "sign in" goes.
+     *
+     * Recognizing an in-flight authorize URL requires `authorizePath` in the
+     * constructor options; without it every `returnTo` starts a fresh login.
+     *
+     * @param returnTo Where the user was headed. `null` / `undefined` fall back
+     * to `/`.
+     * @returns The URL to redirect to.
+     *
+     * @example
+     * ```ts
+     * import { BffClient } from "@udibo/oauth2/client";
+     *
+     * const client = new BffClient({ authorizePath: "/api/oauth2/authorize" });
+     * const href = client.loginContinuation("/api/oauth2/authorize?client_id=a");
+     * ```
+     */
+    loginContinuation(returnTo: string | null | undefined): string;
+}