oauth4webapi 2.1.0 → 2.2.0

package/README.md

@@ -39,7 +39,7 @@ import * as oauth2 from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.1.0/mod.ts'
+import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.2.0/mod.ts'
 ```
 
 - Authorization Code Flow - OpenID Connect [source](examples/code.ts), or plain OAuth 2 [source](examples/oauth.ts)

package/build/index.d.ts

@@ -121,6 +121,10 @@ export type ClientAuthenticationMethod = 'client_secret_basic' | 'client_secret_
  * ```
  */
 export type JWSAlgorithm = 'PS256' | 'ES256' | 'RS256' | 'EdDSA' | 'ES384' | 'PS384' | 'RS384' | 'ES512' | 'PS512' | 'RS512';
+/** @ignore during Documentation generation but part of the public API */
+export declare const clockSkew: unique symbol;
+/** @ignore during Documentation generation but part of the public API */
+export declare const clockTolerance: unique symbol;
 /**
  * Authorization Server Metadata
  *
@@ -442,6 +446,50 @@ export interface Client {
     introspection_signed_response_alg?: string;
     /** Default Maximum Authentication Age. */
     default_max_age?: number;
+    /**
+     * Use to adjust the client's assumed current time. Positive and negative finite values
+     * representing seconds are allowed. Default is `0` (Date.now() + 0 seconds is used).
+     *
+     * @ignore during Documentation generation but part of the public API
+     *
+     * @example Client's local clock is mistakenly 1 hour in the past
+     *
+     * ```ts
+     * const client: oauth.Client = {
+     *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
+     *   // ... other metadata
+     *   [oauth.clockSkew]: +(60 * 60),
+     * }
+     * ```
+     *
+     * @example Client's local clock is mistakenly 1 hour in the future
+     *
+     * ```ts
+     * const client: oauth.Client = {
+     *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
+     *   // ... other metadata
+     *   [oauth.clockSkew]: -(60 * 60),
+     * }
+     * ```
+     */
+    [clockSkew]?: number;
+    /**
+     * Use to set allowed client's clock tolerance when checking DateTime JWT Claims. Only positive
+     * finite values representing seconds are allowed. Default is `30` (30 seconds).
+     *
+     * @ignore during Documentation generation but part of the public API
+     *
+     * @example Tolerate 30 seconds clock skew when validating JWT claims like `exp` or `nbf`.
+     *
+     * ```ts
+     * const client: oauth.Client = {
+     *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
+     *   // ... other metadata
+     *   [oauth.clockTolerance]: 30,
+     * }
+     * ```
+     */
+    [clockTolerance]?: number;
     [metadata: string]: JsonValue | undefined;
 }
 export declare class UnsupportedOperationError extends Error {
@@ -629,6 +677,16 @@ export declare function parseWwwAuthenticateChallenges(response: Response): WWWA
  */
 export declare function processPushedAuthorizationResponse(as: AuthorizationServer, client: Client, response: Response): Promise<PushedAuthorizationResponse | OAuth2Error>;
 export interface ProtectedResourceRequestOptions extends Omit<HttpRequestOptions, 'headers'>, DPoPRequestOptions {
+    /**
+     * Use to adjust the client's assumed current time. Positive and negative finite values
+     * representing seconds are allowed. Default is `0` (Date.now() + 0 seconds is used).
+     *
+     * This option only affects the request if the {@link ProtectedResourceRequestOptions.DPoP DPoP}
+     * option is also used.
+     *
+     * @ignore during Documentation generation but part of the public API
+     */
+    clockSkew?: number;
 }
 /**
  * Performs a protected resource request at an arbitrary URL.

package/build/index.js

@@ -1,9 +1,11 @@
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'oauth4webapi';
-    const VERSION = 'v2.1.0';
+    const VERSION = 'v2.2.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
+export const clockSkew = Symbol();
+export const clockTolerance = Symbol();
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 function buf(input) {
@@ -321,11 +323,24 @@ function keyToJws(key) {
             throw new UnsupportedOperationError('unsupported CryptoKey algorithm name');
     }
 }
+function getClockSkew(client) {
+    if (Number.isFinite(client[clockSkew])) {
+        return client[clockSkew];
+    }
+    return 0;
+}
+function getClockTolerance(client) {
+    const tolerance = client[clockTolerance];
+    if (Number.isFinite(tolerance) && Math.sign(tolerance) !== -1) {
+        return tolerance;
+    }
+    return 30;
+}
 function epochTime() {
     return Math.floor(Date.now() / 1000);
 }
 function clientAssertion(as, client) {
-    const now = epochTime();
+    const now = epochTime() + getClockSkew(client);
     return {
         jti: randomBytes(),
         aud: [as.issuer, as.token_endpoint],
@@ -437,7 +452,7 @@ export async function issueRequestObject(as, client, parameters, privateKey) {
         throw new TypeError('"privateKey.key" must be a private CryptoKey');
     }
     parameters.set('client_id', client.client_id);
-    const now = epochTime();
+    const now = epochTime() + getClockSkew(client);
     const claims = {
         ...Object.fromEntries(parameters.entries()),
         jti: randomBytes(),
@@ -474,7 +489,7 @@ export async function issueRequestObject(as, client, parameters, privateKey) {
         kid,
     }, claims, key);
 }
-async function dpopProofJwt(headers, options, url, htm, accessToken) {
+async function dpopProofJwt(headers, options, url, htm, clockSkew, accessToken) {
     const { privateKey, publicKey, nonce = dpopNonces.get(url.origin) } = options;
     if (!isPrivateKey(privateKey)) {
         throw new TypeError('"DPoP.privateKey" must be a private CryptoKey');
@@ -488,7 +503,7 @@ async function dpopProofJwt(headers, options, url, htm, accessToken) {
     if (!publicKey.extractable) {
         throw new TypeError('"DPoP.publicKey.extractable" must be true');
     }
-    const now = epochTime();
+    const now = epochTime() + clockSkew;
     const proof = await jwt({
         alg: keyToJws(privateKey),
         typ: 'dpop+jwt',
@@ -531,7 +546,7 @@ export async function pushedAuthorizationRequest(as, client, parameters, options
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
     if (options?.DPoP !== undefined) {
-        await dpopProofJwt(headers, options.DPoP, url, 'POST');
+        await dpopProofJwt(headers, options.DPoP, url, 'POST', getClockSkew(client));
     }
     return authenticatedRequest(as, client, 'POST', url, body, headers, options);
 }
@@ -644,7 +659,7 @@ export async function protectedResourceRequest(accessToken, method, url, headers
         headers.set('authorization', `Bearer ${accessToken}`);
     }
     else {
-        await dpopProofJwt(headers, options.DPoP, url, 'GET', accessToken);
+        await dpopProofJwt(headers, options.DPoP, url, 'GET', getClockSkew({ [clockSkew]: options?.clockSkew }), accessToken);
         headers.set('authorization', `DPoP ${accessToken}`);
     }
     return fetch(url.href, {
@@ -670,7 +685,10 @@ export async function userInfoRequest(as, client, accessToken, options) {
         headers.set('accept', 'application/json');
         headers.append('accept', 'application/jwt');
     }
-    return protectedResourceRequest(accessToken, 'GET', url, headers, null, options);
+    return protectedResourceRequest(accessToken, 'GET', url, headers, null, {
+        ...options,
+        clockSkew: getClockSkew(client),
+    });
 }
 let jwksCache;
 async function getPublicSigKeyFromIssuerJwksUri(as, options, header) {
@@ -771,7 +789,7 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
     let json;
     if (getContentType(response) === 'application/jwt') {
         assertReadableResponse(response);
-        const { claims } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), noSignatureCheck)
+        const { claims } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
             .then(validateOptionalAudience.bind(undefined, client.client_id))
             .then(validateOptionalIssuer.bind(undefined, as.issuer));
         json = claims;
@@ -827,7 +845,7 @@ async function tokenEndpointRequest(as, client, grantType, parameters, options)
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
     if (options?.DPoP !== undefined) {
-        await dpopProofJwt(headers, options.DPoP, url, 'POST');
+        await dpopProofJwt(headers, options.DPoP, url, 'POST', getClockSkew(client));
     }
     return authenticatedRequest(as, client, 'POST', url, parameters, headers, options);
 }
@@ -899,7 +917,7 @@ async function processGenericAccessTokenResponse(as, client, response, ignoreIdT
             throw new OPE('"response" body "id_token" property must be a non-empty string');
         }
         if (json.id_token) {
-            const { claims } = await validateJwt(json.id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), noSignatureCheck)
+            const { claims } = await validateJwt(json.id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
                 .then(validatePresence.bind(undefined, ['aud', 'exp', 'iat', 'iss', 'sub']))
                 .then(validateIssuer.bind(undefined, as.issuer))
                 .then(validateAudience.bind(undefined, client.client_id));
@@ -1003,8 +1021,8 @@ export async function processAuthorizationCodeOpenIDResponse(as, client, respons
         if (typeof maxAge !== 'number' || maxAge < 0) {
             throw new TypeError('"options.max_age" must be a non-negative number');
         }
-        const now = epochTime();
-        const tolerance = 30;
+        const now = epochTime() + getClockSkew(client);
+        const tolerance = getClockTolerance(client);
         if (claims.auth_time + maxAge < now - tolerance) {
             throw new OPE('too much time has elapsed since the last End-User authentication');
         }
@@ -1131,7 +1149,7 @@ export async function processIntrospectionResponse(as, client, response) {
     let json;
     if (getContentType(response) === 'application/token-introspection+jwt') {
         assertReadableResponse(response);
-        const { claims } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), noSignatureCheck)
+        const { claims } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
             .then(checkJwtType.bind(undefined, 'token-introspection+jwt'))
             .then(validatePresence.bind(undefined, ['aud', 'iat', 'iss']))
             .then(validateIssuer.bind(undefined, as.issuer))
@@ -1279,7 +1297,7 @@ function keyToSubtle(key) {
     throw new UnsupportedOperationError();
 }
 const noSignatureCheck = Symbol();
-async function validateJwt(jws, checkAlg, getKey) {
+async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
     const { 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.');
     if (length === 5) {
         throw new UnsupportedOperationError('JWE structure JWTs are not supported');
@@ -1320,13 +1338,12 @@ async function validateJwt(jws, checkAlg, getKey) {
     if (!isJsonObject(claims)) {
         throw new OPE('JWT Payload must be a top level object');
     }
-    const now = epochTime();
-    const tolerance = 30;
+    const now = epochTime() + clockSkew;
     if (claims.exp !== undefined) {
         if (typeof claims.exp !== 'number') {
             throw new OPE('unexpected JWT "exp" (expiration time) claim type');
         }
-        if (claims.exp <= now - tolerance) {
+        if (claims.exp <= now - clockTolerance) {
             throw new OPE('unexpected JWT "exp" (expiration time) claim value, timestamp is <= now()');
         }
     }
@@ -1344,7 +1361,7 @@ async function validateJwt(jws, checkAlg, getKey) {
         if (typeof claims.nbf !== 'number') {
             throw new OPE('unexpected JWT "nbf" (not before) claim type');
         }
-        if (claims.nbf > now + tolerance) {
+        if (claims.nbf > now + clockTolerance) {
             throw new OPE('unexpected JWT "nbf" (not before) claim value, timestamp is > now()');
         }
     }
@@ -1371,7 +1388,7 @@ export async function validateJwtAuthResponse(as, client, parameters, expectedSt
     if (typeof as.jwks_uri !== 'string') {
         throw new TypeError('"as.jwks_uri" must be a string');
     }
-    const { claims } = await validateJwt(response, checkSigningAlgorithm.bind(undefined, client.authorization_signed_response_alg, as.authorization_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options))
+    const { claims } = await validateJwt(response, checkSigningAlgorithm.bind(undefined, client.authorization_signed_response_alg, as.authorization_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(client), getClockTolerance(client))
         .then(validatePresence.bind(undefined, ['aud', 'exp', 'iss']))
         .then(validateIssuer.bind(undefined, as.issuer))
         .then(validateAudience.bind(undefined, client.client_id));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "OAuth 2 / OpenID Connect for Web Platform API JavaScript runtimes",
   "keywords": [
     "auth",
@@ -62,21 +62,21 @@
     "test": "bash -c 'source .node_flags.sh && ava'"
   },
   "devDependencies": {
-    "@esbuild-kit/esm-loader": "^2.5.1",
-    "@types/node": "^18.11.9",
-    "@types/qunit": "^2.19.3",
-    "ava": "^5.1.0",
-    "edge-runtime": "^2.0.4",
-    "esbuild": "^0.17.0",
-    "jose": "^4.11.1",
-    "patch-package": "^6.5.0",
-    "prettier": "^2.8.0",
+    "@esbuild-kit/esm-loader": "^2.5.5",
+    "@types/node": "^18.15.0",
+    "@types/qunit": "^2.19.4",
+    "ava": "^5.2.0",
+    "edge-runtime": "^2.1.2",
+    "esbuild": "^0.17.11",
+    "jose": "^4.13.1",
+    "patch-package": "^6.5.1",
+    "prettier": "^2.8.4",
     "prettier-plugin-jsdoc": "^0.4.2",
-    "qunit": "^2.19.3",
+    "qunit": "^2.19.4",
     "timekeeper": "^2.2.0",
-    "typedoc": "^0.23.21",
-    "typedoc-plugin-markdown": "^3.13.6",
-    "typescript": "^4.9.3",
-    "undici": "^5.13.0"
+    "typedoc": "^0.23.26",
+    "typedoc-plugin-markdown": "^3.14.0",
+    "typescript": "^4.9.5",
+    "undici": "^5.20.0"
   }
 }