@udibo/oauth2 0.11.0 → 0.12.0

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/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.0",
+  "version": "0.12.0",
   "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",