@udibo/oauth2 0.7.0 → 0.9.0

package/README.md

@@ -76,6 +76,11 @@ a browser app with a backend, start with the BFF guide.
 authorization server. The framework-independent core accepts standard `Request`
 and `Response` objects; Hono adapters add routing and middleware.
 
+For app-owned login, `CaptchaProvider` and `verifyCaptcha` let your route check
+a client-issued bot-challenge token before calling `IdentityService`. The
+package does not include a challenge provider; see the
+[CAPTCHA route example](docs/guides/add-login.md#captcha-at-the-route-boundary).
+
 ## Examples
 
 From a checkout of this repository:

package/esm/_dnt.polyfills.d.ts

@@ -15,3 +15,17 @@ declare global {
     }
 }
 export {};
+declare global {
+    interface PromiseConstructor {
+        /**
+         * Creates a Promise that can be resolved or rejected using provided functions.
+         * @returns An object containing `promise` promise object, `resolve` and `reject` functions.
+         */
+        withResolvers<T>(): {
+            promise: Promise<T>;
+            resolve: (value: T | PromiseLike<T>) => void;
+            reject: (reason?: any) => void;
+        };
+    }
+}
+export {};

package/esm/_dnt.polyfills.js

@@ -12,4 +12,15 @@ if (!Object.hasOwn) {
         writable: true,
     });
 }
+// https://github.com/tc39/proposal-promise-with-resolvers/blob/3a78801e073e99217dbeb2c43ba7212f3bdc8b83/polyfills.js#L1C1-L9C2
+if (Promise.withResolvers === undefined) {
+    Promise.withResolvers = () => {
+        const out = {};
+        out.promise = new Promise((resolve_, reject_) => {
+            out.resolve = resolve_;
+            out.reject = reject_;
+        });
+        return out;
+    };
+}
 export {};

package/esm/adapters/hono/bff/bff.d.ts

@@ -49,7 +49,7 @@
  */
 import { Hono } from "hono";
 import type { Context, Handler, MiddlewareHandler } from "hono";
-import type { DirectClient, TokenBundle, UserInfoClaims } from "../../../client/mod.js";
+import type { DirectClient, SessionState, TokenBundle, UserInfoClaims } from "../../../client/mod.js";
 import type { ClientInterface } from "../../../models/client.js";
 import type { AbstractScope, BasicScope } from "../../../models/scope.js";
 import type { HonoAuthorizationServer } from "../authorization-server.js";
@@ -731,6 +731,48 @@ export declare class HonoBff {
      * `logoutUrl` when signed in. Never returns tokens.
      */
     sessionHandler(): Handler;
+    /**
+     * Who is signed in on this request, for a server that renders pages: the
+     * answer `GET /auth/session` gives the browser, read without a round trip to
+     * it. Seed the React provider's `initialState` with it so a signed-in page
+     * renders signed in on the first paint.
+     *
+     * A session counts exactly when the probe would count it. In `sessionMode:
+     * "own"`, a session older than `sessionMaxAgeMs` is destroyed and its cookie
+     * cleared on this response, just as the probe does. Shared mode leaves
+     * lifetime enforcement to the application and its session store.
+     * It never returns a token, and it does
+     * not refresh one: `sessionExpiresIn` is `0` once the access token has
+     * expired, and the next `attachToken` or `protect` refreshes it when the
+     * session holds a refresh token.
+     *
+     * It skips the CSRF header check, because the answer goes to your server,
+     * not to a page that could read it cross-site. Call it only on the server.
+     * It sets no caching policy. A response built from its answer is one
+     * person's, so send it with a private or `no-store` `Cache-Control`.
+     *
+     * @param c The request's Hono context. The session cookie is read from it.
+     * @returns The same fields as `BffClient.getSession()`. Signed out,
+     * `user`, `sessionExpiresIn` and `logoutUrl` are all `null`.
+     *
+     * @example Seed the React provider from a server-rendered page
+     * ```ts
+     * import { Hono } from "hono";
+     * import type { SessionState } from "@udibo/oauth2/client";
+     * import type { HonoBff } from "@udibo/oauth2/hono/bff";
+     *
+     * declare const bff: HonoBff;
+     * declare function renderPage(initialState: SessionState): string;
+     *
+     * const app = new Hono();
+     * app.route("/auth", bff.routes());
+     * app.get("/", async (c) => {
+     *   c.header("Cache-Control", "private, no-store");
+     *   return c.html(renderPage(await bff.readSession(c)));
+     * });
+     * ```
+     */
+    readSession(c: Context): Promise<SessionState>;
     /**
      * OIDC Back-Channel Logout receiver. A server-to-server `POST` from the OP
      * carrying a signed `logout_token`; the configured verifier validates it (and

package/esm/adapters/hono/bff/bff.js

@@ -764,16 +764,74 @@ export class HonoBff {
             if (!data) {
                 return c.json({ isAuthenticated: false, user: null });
             }
-            const expiresAt = data.tokens.accessTokenExpiresAt;
-            const sessionExpiresIn = expiresAt !== undefined
+            return c.json(this.#signedInState(data));
+        };
+    }
+    /**
+     * Who is signed in on this request, for a server that renders pages: the
+     * answer `GET /auth/session` gives the browser, read without a round trip to
+     * it. Seed the React provider's `initialState` with it so a signed-in page
+     * renders signed in on the first paint.
+     *
+     * A session counts exactly when the probe would count it. In `sessionMode:
+     * "own"`, a session older than `sessionMaxAgeMs` is destroyed and its cookie
+     * cleared on this response, just as the probe does. Shared mode leaves
+     * lifetime enforcement to the application and its session store.
+     * It never returns a token, and it does
+     * not refresh one: `sessionExpiresIn` is `0` once the access token has
+     * expired, and the next `attachToken` or `protect` refreshes it when the
+     * session holds a refresh token.
+     *
+     * It skips the CSRF header check, because the answer goes to your server,
+     * not to a page that could read it cross-site. Call it only on the server.
+     * It sets no caching policy. A response built from its answer is one
+     * person's, so send it with a private or `no-store` `Cache-Control`.
+     *
+     * @param c The request's Hono context. The session cookie is read from it.
+     * @returns The same fields as `BffClient.getSession()`. Signed out,
+     * `user`, `sessionExpiresIn` and `logoutUrl` are all `null`.
+     *
+     * @example Seed the React provider from a server-rendered page
+     * ```ts
+     * import { Hono } from "hono";
+     * import type { SessionState } from "@udibo/oauth2/client";
+     * import type { HonoBff } from "@udibo/oauth2/hono/bff";
+     *
+     * declare const bff: HonoBff;
+     * declare function renderPage(initialState: SessionState): string;
+     *
+     * const app = new Hono();
+     * app.route("/auth", bff.routes());
+     * app.get("/", async (c) => {
+     *   c.header("Cache-Control", "private, no-store");
+     *   return c.html(renderPage(await bff.readSession(c)));
+     * });
+     * ```
+     */
+    async readSession(c) {
+        const cookieValue = getCookie(c, this.#cookieName);
+        const data = cookieValue
+            ? await this.#readLiveSession(c, cookieValue)
+            : null;
+        if (!data) {
+            return {
+                isAuthenticated: false,
+                user: null,
+                sessionExpiresIn: null,
+                logoutUrl: null,
+            };
+        }
+        return this.#signedInState(data);
+    }
+    #signedInState(data) {
+        const expiresAt = data.tokens.accessTokenExpiresAt;
+        return {
+            isAuthenticated: true,
+            user: data.user ?? null,
+            sessionExpiresIn: expiresAt !== undefined
                 ? Math.max(0, Math.round((expiresAt - Date.now()) / 1000))
-                : null;
-            return c.json({
-                isAuthenticated: true,
-                user: data.user ?? null,
-                sessionExpiresIn,
-                logoutUrl: this.#paths.logout,
-            });
+                : null,
+            logoutUrl: this.#paths.logout,
         };
     }
     /**

package/esm/server/authorization-server.d.ts

@@ -63,9 +63,19 @@ export interface EndSessionContext<Client extends ClientInterface> {
 }
 /** What an app's {@link EndSessionFn} may ask the server to do afterwards. */
 export interface EndSessionResult {
+    /**
+     * The app refused this logout (for example, the verified `id_token_hint`
+     * names a different person than the current session). Ignore the caller's
+     * redirect and all `headers`, including any `Set-Cookie`, so the response
+     * neither sends the browser to the RP nor clears the current session.
+     * Answer at `fallback` if supplied, otherwise 204. Omit or set `false` to
+     * preserve the normal logout behavior.
+     */
+    refused?: boolean;
     /**
      * Headers to merge into the response — the session-clearing `Set-Cookie`,
-     * typically. The server owns `Location`; anything else is yours.
+     * typically. The server owns `Location`; anything else is yours. Ignored
+     * when `refused` is true.
      */
     headers?: HeadersInit;
     /**

package/esm/server/authorization-server.js

@@ -580,8 +580,10 @@ export class AuthorizationServer extends ResourceServer {
                 subject: params.subject,
                 logoutHint: params.logoutHint,
             }) ?? {};
-            const headers = new Headers(result.headers);
-            const authorized = this.#postLogoutRedirect(client, params);
+            const headers = new Headers(result.refused ? undefined : result.headers);
+            const authorized = result.refused
+                ? undefined
+                : this.#postLogoutRedirect(client, params);
             const target = authorized ?? result.fallback;
             if (!target)
                 return new Response(null, { status: 204, headers });

package/esm/testing/contract/mod.d.ts

@@ -39,4 +39,4 @@ export { type OtpStoreContractOptions, runOtpStoreContractTests, } from "./otp-s
 export { type RateLimitStoreContractOptions, runRateLimitStoreContractTests, } from "./rate-limit-store.js";
 export { type LockoutStoreContractOptions, runLockoutStoreContractTests, } from "./lockout-store.js";
 export { type AuthRequestStorageContractOptions, runAuthRequestStorageContractTests, } from "./auth-request-storage.js";
-export { runTenantContractTests, type TenantContractFixture, type TenantContractOptions, type TenantContractTokens, } from "./tenant.js";
+export { runTenantContractTests, type TenantContractFixture, type TenantContractOptions, type TenantContractProfile, type TenantContractSignInOptions, type TenantContractTokens, } from "./tenant.js";

package/esm/testing/contract/tenant.d.ts

@@ -1,8 +1,9 @@
 /**
- * Contract test suite for a Udibo Identity tenant's authorization answers: what
- * introspection reports about a signed-in person, what `GET /api/memberships`
- * lists for them, and what `POST /api/check` and `POST /api/check/batch`
- * answer.
+ * Contract test suite for what a Udibo Identity tenant answers an application
+ * about its signed-in people: what introspection reports, what
+ * `GET /api/memberships` lists, what `POST /api/check` and
+ * `POST /api/check/batch` answer, the organization API under
+ * `/api/organizations`, and the account API under `/api/account`.
  *
  * It runs against `createFakeTenant` from `@udibo/oauth2/testing` and against the
  * real identity service in Udibo's own repository, so the fake an app tests
@@ -35,8 +36,9 @@ export interface TenantContractFixture {
     /** The tenant's origin; its RFC 8414 metadata is served beneath it. */
     issuer: string;
     /**
-     * A confidential client the suite signs in with, introspects with and
-     * refreshes with. It must be allowed the `refresh_token` grant.
+     * A confidential first-party client the suite signs in with, introspects
+     * with, refreshes with and revokes with. It must be allowed the
+     * `refresh_token` grant.
      */
     client: {
         id: string;
@@ -47,8 +49,19 @@ export interface TenantContractFixture {
      * one when the tenant's host resolves only through a proxy.
      */
     fetch?: typeof fetch;
-    /** Adds a person holding `permissions` tenant-wide, and returns their id. */
-    addUser(permissions: string[]): Promise<string>;
+    /**
+     * Adds a person holding `permissions` tenant-wide, and returns their id. The
+     * organization and account checks pass a `profile`; the others do not.
+     */
+    addUser(permissions: string[], profile?: TenantContractProfile): Promise<string>;
+    /**
+     * Links an external sign-in account to a person and returns the linked
+     * account's id.
+     */
+    linkAccount(userId: string, account: {
+        provider: string;
+        email: string | null;
+    }): Promise<string>;
     /** Adds an organization and returns its id. */
     addOrganization(): Promise<string>;
     /**
@@ -77,11 +90,38 @@ export interface TenantContractFixture {
      * Signs the person in through the authorization-code flow and returns the
      * tokens it issued. With an organization named, the credential is issued in
      * it; with none, the sign-in picks nothing, leaving the tenant to decide.
+     * Each sign-in comes from a new browser and so starts a login session of its
+     * own, unless `options.sameBrowser` says otherwise.
      */
-    signIn(userId: string, organizationId?: string): Promise<TenantContractTokens>;
+    signIn(userId: string, organizationId?: string, options?: TenantContractSignInOptions): Promise<TenantContractTokens>;
     /** Releases anything `setup` allocated. */
     cleanup?(): Promise<void> | void;
 }
+/** How `TenantContractFixture.signIn` signs a person in. */
+export interface TenantContractSignInOptions {
+    /**
+     * Sign in from the browser this person's previous sign-in used, so the
+     * tenant continues that login session instead of starting another. The
+     * suite asks for it only straight after that previous sign-in.
+     */
+    sameBrowser?: boolean;
+}
+/** Who a person added with `TenantContractFixture.addUser` is. */
+export interface TenantContractProfile {
+    /**
+     * The address the person holds. When it is omitted, the fixture may give them
+     * any address or none.
+     */
+    email?: string;
+    /** Whether that address is verified. Defaults to `true`. */
+    emailVerified?: boolean;
+    /**
+     * Whether the person has a password. Defaults to `true`. With `false`, the
+     * fixture must still be able to sign them in, the way a tenant signs such a
+     * person in through a linked account.
+     */
+    password?: boolean;
+}
 /** Options for {@link runTenantContractTests}. */
 export interface TenantContractOptions {
     /** Overrides the top-level `describe` name. */