@udibo/oauth2 0.6.0 → 0.8.0

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

@@ -248,6 +248,26 @@ export interface AuthorizationServerOptions<Client extends ClientInterface, User
      * bundle.
      */
     isPublicSuffix?: IsPublicSuffix;
+    /**
+     * The largest request body, in bytes, the server reads at the token,
+     * revocation, introspection, device authorization and end-session
+     * endpoints. Each reads its form body before it has authenticated the
+     * caller, so the cap bounds what an anonymous request can make the server
+     * buffer. Bytes are counted as they arrive, so a chunked body or a
+     * `Content-Length` that understates the body cannot get past it. A larger
+     * body is refused with `413` and `invalid_request` before the request's
+     * context is resolved or any client is authenticated.
+     *
+     * The default fits every body these endpoints legitimately receive: the
+     * largest field is a JWT (`id_token_hint`, or a token presented for
+     * introspection or revocation), a few KiB even with a large claim set.
+     * Raise it only if your clients send larger ones.
+     *
+     * @default 65536
+     * @throws {RangeError} From the constructor when it is not a positive
+     *   integer.
+     */
+    maxBodyBytes?: number;
 }
 /**
  * Function to authenticate the user during authorization.
@@ -407,6 +427,7 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      *
      * @throws {Error} If any grant's map key does not equal its `grantType`.
      * @throws {Error} If `requireOidc` is set without `signingKeys`.
+     * @throws {RangeError} If `maxBodyBytes` is not a positive integer.
      */
     constructor(options: AuthorizationServerOptions<Client, User, S>);
     /**
@@ -453,7 +474,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * `application/x-www-form-urlencoded`, or no `grant_type` — is a 400
      * `invalid_request`. A `grant_type` with no registered grant is
      * `unsupported_grant_type`, checked before client authentication; a client
-     * not registered for the grant is `unauthorized_client`.
+     * not registered for the grant is `unauthorized_client`. A body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before the request context is resolved.
      */
     handleTokenRequest(request: Request): Promise<Response>;
     /**
@@ -522,7 +545,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * when sent, names the client ahead of the hint's audience, and when both
      * are sent `client_id` must be one of the hint's audiences — a mismatch is
      * a 400 `invalid_request` (OIDC RP-Initiated Logout 1.0 §2). `state` rides
-     * along only to a URI that passed authorization.
+     * along only to a URI that passed authorization. A POST body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before `endSession` runs.
      *
      * Wire the app's session teardown through the `endSession` **constructor
      * option**; this method answers 404 without it, and the discovery document

package/esm/server/authorization-server.js

@@ -29,6 +29,7 @@ import { DeviceAuthorizationGrant } from "./grants/device-authorization.js";
 import { ResourceServer, } from "./resource-server.js";
 import { defaultSubjectOf, signJwt, verifyJwt, } from "./signing-keys.js";
 import { validateCodeChallenge } from "../utils/pkce.js";
+import { assertMaxBodyBytes, DEFAULT_MAX_BODY_BYTES, readBoundedBody, } from "../utils/_body.js";
 const ENDPOINTS = {
     authorization: {
         option: "authorizationEndpoint",
@@ -186,6 +187,7 @@ export class AuthorizationServer extends ResourceServer {
     signingKeys;
     #endSession;
     #isPublicSuffix;
+    #maxBodyBytes;
     #subjectOf;
     #userClaims;
     #introspectionClaims;
@@ -197,6 +199,7 @@ export class AuthorizationServer extends ResourceServer {
      *
      * @throws {Error} If any grant's map key does not equal its `grantType`.
      * @throws {Error} If `requireOidc` is set without `signingKeys`.
+     * @throws {RangeError} If `maxBodyBytes` is not a positive integer.
      */
     constructor(options) {
         super({
@@ -227,6 +230,8 @@ export class AuthorizationServer extends ResourceServer {
                 "plain OAuth2.");
         }
         this.#isPublicSuffix = options.isPublicSuffix;
+        this.#maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        assertMaxBodyBytes(this.#maxBodyBytes, "maxBodyBytes");
         this.#subjectOf = options.subjectOf ?? defaultSubjectOf;
         this.#userClaims = options.userClaims;
         this.#introspectionClaims = options.introspectionClaims;
@@ -343,6 +348,18 @@ export class AuthorizationServer extends ResourceServer {
         }
         return grant;
     }
+    async #readBody(request, options = {}) {
+        const bytes = await readBoundedBody(request, this.#maxBodyBytes, options)
+            .catch((cause) => {
+            throw new InvalidRequestError("request body could not be read", {
+                cause,
+            });
+        });
+        if (!bytes) {
+            throw new InvalidRequestError(413, `request body exceeds ${this.#maxBodyBytes} bytes`);
+        }
+        return bytes;
+    }
     async #beginClientAuthenticatedRequest(request, options = {}) {
         if (request.method !== "POST") {
             throw new InvalidRequestError("method must be POST");
@@ -351,10 +368,13 @@ export class AuthorizationServer extends ResourceServer {
         if (!contentType?.includes("application/x-www-form-urlencoded")) {
             throw new InvalidRequestError("content-type header must be application/x-www-form-urlencoded");
         }
-        const context = await this.authorizationContext(request);
-        const body = await request.clone().formData().catch(() => {
+        const bytes = await this.#readBody(request, { keepReadable: true });
+        const body = await new Response(bytes, {
+            headers: { "content-type": contentType },
+        }).formData().catch(() => {
             throw new InvalidRequestError("body must be application/x-www-form-urlencoded");
         });
+        const context = await this.authorizationContext(request);
         const grant = options.grantFromBody?.(body);
         const client = grant
             ? await grant.getAuthenticatedClient(request, body)
@@ -372,7 +392,9 @@ export class AuthorizationServer extends ResourceServer {
      * `application/x-www-form-urlencoded`, or no `grant_type` — is a 400
      * `invalid_request`. A `grant_type` with no registered grant is
      * `unsupported_grant_type`, checked before client authentication; a client
-     * not registered for the grant is `unauthorized_client`.
+     * not registered for the grant is `unauthorized_client`. A body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before the request context is resolved.
      */
     async handleTokenRequest(request) {
         try {
@@ -523,7 +545,9 @@ export class AuthorizationServer extends ResourceServer {
      * when sent, names the client ahead of the hint's audience, and when both
      * are sent `client_id` must be one of the hint's audiences — a mismatch is
      * a 400 `invalid_request` (OIDC RP-Initiated Logout 1.0 §2). `state` rides
-     * along only to a URI that passed authorization.
+     * along only to a URI that passed authorization. A POST body over
+     * {@linkcode AuthorizationServerOptions.maxBodyBytes} is a 413
+     * `invalid_request`, refused before `endSession` runs.
      *
      * Wire the app's session teardown through the `endSession` **constructor
      * option**; this method answers 404 without it, and the discovery document
@@ -572,7 +596,7 @@ export class AuthorizationServer extends ResourceServer {
     async #endSessionParameters(request) {
         const url = new URL(request.url);
         const params = request.method === "POST"
-            ? new URLSearchParams(await request.text())
+            ? new URLSearchParams(new TextDecoder().decode(await this.#readBody(request)))
             : url.searchParams;
         const idTokenHint = params.get("id_token_hint");
         const hint = idTokenHint ? await this.#readIdTokenHint(idTokenHint) : null;

package/esm/testing/contract/auth-request-storage.d.ts

@@ -22,6 +22,20 @@
  * });
  * ```
  *
+ * @example Verify a store shared between users, whose `clear()` removes only expired records
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshSharedAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "SharedAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshSharedAuthRequestStorage,
+ *   clear: "scoped",
+ * });
+ * ```
+ *
  * @module
  */
 import type { AuthRequestStorage } from "../../client/storage.js";
@@ -41,6 +55,18 @@ export interface AuthRequestStorageContractOptions {
      * that meant to implement it and does not fails loudly.
      */
     take?: boolean;
+    /**
+     * What the store's {@link AuthRequestStorage.clear} removes. Defaults to
+     * `"all"`: every record, as a store private to one browser or session
+     * does. Pass `"scoped"` for a store shared between users whose `clear()`
+     * deliberately removes less — only expired records, say — because a
+     * `DirectClient` clears it on every sign-out, and removing everything would
+     * cancel other users' sign-ins still in progress. The suite then drops the
+     * clear-everything case and instead requires that `clear()` leaves every
+     * record still inside its lifetime readable and redeemable, and removes a
+     * record created at the epoch (`createdAt: 0`), which is past any lifetime.
+     */
+    clear?: "all" | "scoped";
     /**
      * Overrides the name passed to the outer `describe` block. Defaults to
      * `"AuthRequestStorage contract"`.

package/esm/testing/contract/auth-request-storage.js

@@ -22,6 +22,20 @@
  * });
  * ```
  *
+ * @example Verify a store shared between users, whose `clear()` removes only expired records
+ * ```ts
+ * import { runAuthRequestStorageContractTests } from "@udibo/oauth2/testing/contract";
+ * import type { AuthRequestStorage } from "@udibo/oauth2/client";
+ *
+ * declare function freshSharedAuthRequestStorage(): Promise<AuthRequestStorage>;
+ *
+ * runAuthRequestStorageContractTests({
+ *   describeName: "SharedAuthRequestStorage satisfies AuthRequestStorage contract",
+ *   makeStore: freshSharedAuthRequestStorage,
+ *   clear: "scoped",
+ * });
+ * ```
+ *
  * @module
  */
 import { assert, assertEquals, assertStrictEquals } from "../../deps/jsr.io/@std/assert/1.0.19/mod.js";
@@ -47,6 +61,7 @@ function record(overrides = {}) {
  */
 export function runAuthRequestStorageContractTests(options) {
     const expectTake = options.take ?? true;
+    const clearScope = options.clear ?? "all";
     describe(options.describeName ?? "AuthRequestStorage contract", () => {
         let store;
         beforeEach(async () => {
@@ -74,13 +89,35 @@ export function runAuthRequestStorageContractTests(options) {
                 assertStrictEquals(await store.get("state-1"), null);
                 assert(await store.get("state-2") !== null, "delete must remove only the named state");
             });
-            it("clears every record", async () => {
-                await store.set("state-1", record());
-                await store.set("state-2", record());
-                await store.clear();
-                assertStrictEquals(await store.get("state-1"), null);
-                assertStrictEquals(await store.get("state-2"), null);
-            });
+            if (clearScope === "all") {
+                it("clears every record", async () => {
+                    await store.set("state-1", record());
+                    await store.set("state-2", record());
+                    await store.clear();
+                    assertStrictEquals(await store.get("state-1"), null);
+                    assertStrictEquals(await store.get("state-2"), null);
+                });
+            }
+            else {
+                it('leaves every in-progress record in place (clear: "scoped")', async () => {
+                    const first = record({ codeVerifier: "verifier-1" });
+                    const second = record({ codeVerifier: "verifier-2" });
+                    await store.set("state-1", first);
+                    await store.set("state-2", second);
+                    await store.clear();
+                    const message = "clear() on a shared store must not cancel another user's sign-in " +
+                        "that is still in progress";
+                    assertEquals(await store.get("state-2"), second, message);
+                    assertEquals(expectTake
+                        ? await store.take("state-1")
+                        : await store.get("state-1"), first, message);
+                });
+                it('removes a record past any lifetime (clear: "scoped")', async () => {
+                    await store.set("expired", record({ createdAt: 0 }));
+                    await store.clear();
+                    assertStrictEquals(await store.get("expired"), null, "a scoped clear() must still remove expired records");
+                });
+            }
         });
         if (expectTake) {
             describe("take", () => {

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. */