@udibo/oauth2 0.11.1 → 0.12.1

package/esm/server/_clock-skew.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validates clock-skew configuration shared by token readers and resource
+ * servers.
+ *
+ * @module
+ */
+/** Throws `RangeError` unless the leeway is non-negative, finite seconds whose millisecond conversion is finite. */
+export declare function assertClockSkewSeconds(clockSkewSeconds: number): void;

package/esm/server/_clock-skew.js

@@ -0,0 +1,13 @@
+/**
+ * Validates clock-skew configuration shared by token readers and resource
+ * servers.
+ *
+ * @module
+ */
+/** Throws `RangeError` unless the leeway is non-negative, finite seconds whose millisecond conversion is finite. */
+export function assertClockSkewSeconds(clockSkewSeconds) {
+    if (!Number.isFinite(clockSkewSeconds) || clockSkewSeconds < 0 ||
+        !Number.isFinite(clockSkewSeconds * 1000)) {
+        throw new RangeError("clockSkewSeconds must be non-negative finite seconds with a finite millisecond conversion");
+    }
+}

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

@@ -489,7 +489,8 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * Supports multiple grant types based on the configured grants.
      *
      * A malformed request — wrong method, a content-type other than
-     * `application/x-www-form-urlencoded`, or no `grant_type` — is a 400
+     * `application/x-www-form-urlencoded`, no `grant_type`, or a repeated
+     * recognized singleton form parameter — 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`. A body over
@@ -643,7 +644,8 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * endpoint cannot be used as an oracle for whether a token value is live or
      * whose it is. That covers the token only: a malformed request — wrong
      * method, a content-type other than `application/x-www-form-urlencoded`, or
-     * no `token` parameter — is a 400 `invalid_request`, as on the token
+     * no `token` parameter, or repeated `token`, `token_type_hint`, `client_id` or
+     * `client_secret` — is a 400 `invalid_request`, as on the token
      * endpoint.
      *
      * `token_type_hint` orders the lookup rather than restricting it, so a client
@@ -684,6 +686,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * `application/x-www-form-urlencoded`, is a 400 `invalid_request`, as on the
      * token endpoint.
      *
+     * Repeated `token`, `token_type_hint`, `client_id` or `client_secret` form
+     * parameters are refused before the context is resolved.
+     *
      * @see https://datatracker.ietf.org/doc/html/rfc7662
      */
     handleIntrospectionRequest(request: Request): Promise<Response>;
@@ -739,6 +744,9 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * `application/x-www-form-urlencoded`, is a 400 `invalid_request`, as on the
      * token endpoint.
      *
+     * Repeated `scope`, `client_id` or `client_secret` form parameters are
+     * refused before the context is resolved.
+     *
      * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
      * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.2
      */

package/esm/server/authorization-server.js

@@ -348,6 +348,37 @@ export class AuthorizationServer extends ResourceServer {
         }
         return grant;
     }
+    #assertSingletonParameters(body, parameters) {
+        for (const parameter of parameters) {
+            if (body.getAll(parameter).length > 1) {
+                throw new InvalidRequestError(`${parameter} parameter must not be repeated`);
+            }
+        }
+    }
+    #assertTokenSingletonParameters(body) {
+        this.#assertSingletonParameters(body, ["grant_type"]);
+        let parameters;
+        switch (body.get("grant_type")) {
+            case "authorization_code":
+                parameters = ["code", "redirect_uri", "code_verifier"];
+                break;
+            case "refresh_token":
+                parameters = ["refresh_token", "scope"];
+                break;
+            case "password":
+                parameters = ["username", "password", "scope"];
+                break;
+            case "client_credentials":
+                parameters = ["scope"];
+                break;
+            case DEVICE_AUTHORIZATION_GRANT_TYPE:
+                parameters = ["device_code"];
+                break;
+            default:
+                parameters = [];
+        }
+        this.#assertSingletonParameters(body, parameters);
+    }
     async #readBody(request, options = {}) {
         const bytes = await readBoundedBody(request, this.#maxBodyBytes, options)
             .catch((cause) => {
@@ -374,6 +405,8 @@ export class AuthorizationServer extends ResourceServer {
         }).formData().catch(() => {
             throw new InvalidRequestError("body must be application/x-www-form-urlencoded");
         });
+        this.#assertSingletonParameters(body, ["client_id", "client_secret"]);
+        options.validateBody?.(body);
         const context = await this.authorizationContext(request);
         const grant = options.grantFromBody?.(body);
         const client = grant
@@ -389,7 +422,8 @@ export class AuthorizationServer extends ResourceServer {
      * Supports multiple grant types based on the configured grants.
      *
      * A malformed request — wrong method, a content-type other than
-     * `application/x-www-form-urlencoded`, or no `grant_type` — is a 400
+     * `application/x-www-form-urlencoded`, no `grant_type`, or a repeated
+     * recognized singleton form parameter — 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`. A body over
@@ -401,6 +435,7 @@ export class AuthorizationServer extends ResourceServer {
             const { context, body, client, grant } = await this
                 .#beginClientAuthenticatedRequest(request, {
                 grantFromBody: (body) => this.#grantFromBody(body),
+                validateBody: (body) => this.#assertTokenSingletonParameters(body),
             });
             const token = await grant.token(request, client, body);
             return await this.createTokenResponse(token, context, grant);
@@ -894,7 +929,8 @@ export class AuthorizationServer extends ResourceServer {
      * endpoint cannot be used as an oracle for whether a token value is live or
      * whose it is. That covers the token only: a malformed request — wrong
      * method, a content-type other than `application/x-www-form-urlencoded`, or
-     * no `token` parameter — is a 400 `invalid_request`, as on the token
+     * no `token` parameter, or repeated `token`, `token_type_hint`, `client_id` or
+     * `client_secret` — is a 400 `invalid_request`, as on the token
      * endpoint.
      *
      * `token_type_hint` orders the lookup rather than restricting it, so a client
@@ -905,7 +941,12 @@ export class AuthorizationServer extends ResourceServer {
     async handleRevocationRequest(request) {
         try {
             const { context, body, client } = await this
-                .#beginClientAuthenticatedRequest(request);
+                .#beginClientAuthenticatedRequest(request, {
+                validateBody: (body) => this.#assertSingletonParameters(body, [
+                    "token",
+                    "token_type_hint",
+                ]),
+            });
             const token = body.get("token");
             if (typeof token !== "string") {
                 throw new InvalidRequestError("token parameter required");
@@ -979,12 +1020,20 @@ export class AuthorizationServer extends ResourceServer {
      * `application/x-www-form-urlencoded`, is a 400 `invalid_request`, as on the
      * token endpoint.
      *
+     * Repeated `token`, `token_type_hint`, `client_id` or `client_secret` form
+     * parameters are refused before the context is resolved.
+     *
      * @see https://datatracker.ietf.org/doc/html/rfc7662
      */
     async handleIntrospectionRequest(request) {
         try {
             const { context, body, client } = await this
-                .#beginClientAuthenticatedRequest(request);
+                .#beginClientAuthenticatedRequest(request, {
+                validateBody: (body) => this.#assertSingletonParameters(body, [
+                    "token",
+                    "token_type_hint",
+                ]),
+            });
             const tokenValue = body.get("token");
             if (typeof tokenValue !== "string") {
                 throw new InvalidRequestError("token parameter required");
@@ -1164,6 +1213,9 @@ export class AuthorizationServer extends ResourceServer {
      * `application/x-www-form-urlencoded`, is a 400 `invalid_request`, as on the
      * token endpoint.
      *
+     * Repeated `scope`, `client_id` or `client_secret` form parameters are
+     * refused before the context is resolved.
+     *
      * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.1
      * @see https://datatracker.ietf.org/doc/html/rfc8628#section-3.2
      */
@@ -1172,6 +1224,7 @@ export class AuthorizationServer extends ResourceServer {
             const { context, body, client } = await this
                 .#beginClientAuthenticatedRequest(request, {
                 requiredGrantType: DEVICE_AUTHORIZATION_GRANT_TYPE,
+                validateBody: (body) => this.#assertSingletonParameters(body, ["scope"]),
             });
             const grant = this.#deviceAuthorizationGrant();
             const scopeText = body.get("scope");

package/esm/server/jwks-token-reader.d.ts

@@ -110,7 +110,9 @@ export interface JwksTokenReaderOptions<Client extends ClientInterface, User, S
     clientIdClaim?: string;
     /**
      * Leeway in seconds applied to `exp` and `nbf` to absorb clock drift
-     * between the issuer and this server. Defaults to 30.
+     * between the issuer and this server. Defaults to 30. Must be finite and
+     * non-negative, with a finite millisecond conversion; fractional seconds
+     * are supported.
      *
      * This governs this reader's own claim checks. The token it returns carries
      * the issuer's `exp` verbatim, and {@linkcode ResourceServer} re-checks that
@@ -237,6 +239,8 @@ export declare class JwksTokenReader<Client extends ClientInterface, User, S ext
      * @throws {TypeError} If `issuer` is not an absolute URL, `audience` is
      *   empty, or `algorithms` names an algorithm this package cannot verify
      *   (a silently ignored entry would read as a policy that isn't enforced).
+     * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
+     *   overflows when converted to milliseconds.
      */
     constructor(options: JwksTokenReaderOptions<Client, User, S>);
     /**

package/esm/server/jwks-token-reader.js

@@ -17,6 +17,7 @@ import { BasicScope } from "../models/scope.js";
 import { toArrayBuffer } from "../utils/_buffer.js";
 import { base64urlDecode } from "../utils/crypto.js";
 import { defaultFetch, packageDeadlineSignal, } from "../utils/_default-fetch.js";
+import { assertClockSkewSeconds } from "./_clock-skew.js";
 const ALGORITHMS = {
     ES256: {
         kty: "EC",
@@ -229,6 +230,8 @@ export class JwksTokenReader {
      * @throws {TypeError} If `issuer` is not an absolute URL, `audience` is
      *   empty, or `algorithms` names an algorithm this package cannot verify
      *   (a silently ignored entry would read as a policy that isn't enforced).
+     * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
+     *   overflows when converted to milliseconds.
      */
     constructor(options) {
         this.#issuer = options.issuer;
@@ -248,6 +251,7 @@ export class JwksTokenReader {
         this.#types = (options.types ?? ["at+jwt"]).map(normalizeType);
         this.#clientIdClaim = options.clientIdClaim ?? "client_id";
         this.#clockSkewSeconds = options.clockSkewSeconds ?? 30;
+        assertClockSkewSeconds(this.#clockSkewSeconds);
         this.#cacheMaxAgeMs = options.cacheMaxAgeMs ?? 600_000;
         this.#minFetchIntervalMs = options.minFetchIntervalMs ?? 30_000;
         this.#fetchTimeoutMs = options.fetchTimeoutMs ?? 5_000;

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

@@ -43,7 +43,9 @@ export interface ResourceServerOptions<Client extends ClientInterface, User, S e
     /**
      * Leeway in seconds applied to the access token's expiry, to absorb clock
      * drift between whoever issued the token and this server. Defaults to `0`:
-     * a token whose expiry has passed is refused immediately.
+     * a token whose expiry has passed is refused immediately. Must be finite and
+     * non-negative, with a finite millisecond conversion; fractional seconds
+     * are supported.
      *
      * This is the one expiry check every token reader's result passes through,
      * which is why the leeway belongs here rather than in a reader:
@@ -138,15 +140,31 @@ export declare class ResourceServer<Client extends ClientInterface, User, S exte
     Scope: ScopeConstructor<S>;
     /** Protection space named in `WWW-Authenticate` challenges. */
     realm: string;
-    /** Leeway in seconds applied to the access token's expiry. Defaults to `0`. */
-    clockSkewSeconds: number;
     /** Body format used for error responses: OAuth2 or RFC 9457 problem details. */
     errorFormat: "oauth2" | "problem-details";
     /** When true, handler boundaries rethrow {@linkcode OAuth2Error} instead of returning a response. */
     throwOnError: boolean;
     /** Resolves the per-request {@link ResourceServerContext}. */
     protected resolveContext: (request: Request) => ResourceServerContext<Client, User, S> | Promise<ResourceServerContext<Client, User, S>>;
-    /** Creates a resource server from the given {@linkcode ResourceServerOptions}. */
+    /**
+     * Leeway in seconds applied to the access token's expiry. Defaults to `0`.
+     * May be reassigned to any non-negative finite number with a finite
+     * millisecond conversion, including fractional seconds.
+     */
+    get clockSkewSeconds(): number;
+    /**
+     * Sets the expiry leeway, preserving the previous value if validation fails.
+     *
+     * @throws {RangeError} If the value is negative, non-finite, or overflows
+     *   when converted to milliseconds.
+     */
+    set clockSkewSeconds(value: number);
+    /**
+     * Creates a resource server from the given {@linkcode ResourceServerOptions}.
+     *
+     * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
+     *   overflows when converted to milliseconds.
+     */
     constructor(options: ResourceServerOptions<Client, User, S>);
     /**
      * Builds a WWW-Authenticate header value per RFC 6750 Section 3.

package/esm/server/resource-server.js

@@ -10,6 +10,7 @@ import "../_dnt.polyfills.js";
 import { BasicScope } from "../models/scope.js";
 import { AccessDeniedError, InsufficientPermissionsError, InsufficientScopeError, InvalidTokenError, toOAuth2Error, } from "../errors.js";
 import { authorizationFromClaims, } from "../models/authorization.js";
+import { assertClockSkewSeconds } from "./_clock-skew.js";
 /** Bearer token regex pattern. */
 export const BEARER_TOKEN = /^ *(?:[Bb][Ee][Aa][Rr][Ee][Rr]) +([\w-.~+/]+=*) *$/;
 const FAILURE_LABELS = {
@@ -73,15 +74,37 @@ export class ResourceServer {
     Scope;
     /** Protection space named in `WWW-Authenticate` challenges. */
     realm;
-    /** Leeway in seconds applied to the access token's expiry. Defaults to `0`. */
-    clockSkewSeconds;
     /** Body format used for error responses: OAuth2 or RFC 9457 problem details. */
     errorFormat;
     /** When true, handler boundaries rethrow {@linkcode OAuth2Error} instead of returning a response. */
     throwOnError;
     /** Resolves the per-request {@link ResourceServerContext}. */
     resolveContext;
-    /** Creates a resource server from the given {@linkcode ResourceServerOptions}. */
+    #clockSkewSeconds = 0;
+    /**
+     * Leeway in seconds applied to the access token's expiry. Defaults to `0`.
+     * May be reassigned to any non-negative finite number with a finite
+     * millisecond conversion, including fractional seconds.
+     */
+    get clockSkewSeconds() {
+        return this.#clockSkewSeconds;
+    }
+    /**
+     * Sets the expiry leeway, preserving the previous value if validation fails.
+     *
+     * @throws {RangeError} If the value is negative, non-finite, or overflows
+     *   when converted to milliseconds.
+     */
+    set clockSkewSeconds(value) {
+        assertClockSkewSeconds(value);
+        this.#clockSkewSeconds = value;
+    }
+    /**
+     * Creates a resource server from the given {@linkcode ResourceServerOptions}.
+     *
+     * @throws {RangeError} If `clockSkewSeconds` is negative, non-finite, or
+     *   overflows when converted to milliseconds.
+     */
     constructor(options) {
         this.Scope = options.Scope ??
             BasicScope;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "repository": {
     "type": "git",