oauth4webapi 1.2.2 → 1.3.0

package/README.md

@@ -52,26 +52,18 @@ import * as oauth2 from 'https://deno.land/x/oauth4webapi/src/index.ts'
 - FAPI 2.0 (Private Key JWT, PAR, DPoP) - [source](examples/fapi2.ts)
 - FAPI 2.0 Message Signing (Private Key JWT, PAR, DPoP, JAR, JARM) - [source](examples/fapi2-message-signing.ts) | [diff](examples/fapi2-message-signing.diff)
 
-## Runtime requirements
-
-The supported JavaScript runtimes include ones that
-
-- are reasonably up to date ECMAScript (targets ES2020, but may be further transpiled for compatibility)
-- support required Web API globals and standard built-in objects
-  - [Fetch API][] and its related globals [fetch][], [Response][], [Headers][]
-  - [Web Crypto API][] and its related globals [crypto][], [CryptoKey][]
-  - [Encoding API][] and its related globals [TextEncoder][], [TextDecoder][]
-  - [URL API][] and its related globals [URL][], [URLSearchParams][]
-  - [atob][] and [btoa][]
-  - [Uint8Array][]
-- These are (not an exhaustive list):
-  - Browsers
-  - Cloudflare Workers
-  - Deno
-  - Electron
-  - Next.js Middlewares
-  - Node.js ([runtime flags may be needed](https://github.com/panva/oauth4webapi/issues/8))
-  - Vercel Edge Functions
+## Supported Runtimes
+
+The supported JavaScript runtimes include ones that support the utilized Web API globals and standard built-in objects
+
+These are _(this is not an exhaustive list)_:
+- Browsers
+- Cloudflare Workers
+- Deno
+- Electron
+- Netlify Edge
+- Node.js ([runtime flags may be needed](https://github.com/panva/oauth4webapi/issues/8))
+- Vercel's Edge Runtime
 
 ## Out of scope
 
@@ -81,20 +73,3 @@ The supported JavaScript runtimes include ones that
 - JSON Web Encryption (JWE)
 - JSON Web Signature (JWS) rarely used algorithms and HMAC
 - Automatic polyfills of any kind
-
-[web crypto api]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API
-[fetch api]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
-[fetch]: https://developer.mozilla.org/en-US/docs/Web/API/fetch
-[textdecoder]: https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder
-[textencoder]: https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder
-[btoa]: https://developer.mozilla.org/en-US/docs/Web/API/btoa
-[atob]: https://developer.mozilla.org/en-US/docs/Web/API/atob
-[uint8array]: https://developer.mozilla.org/en-US/docs/Web/API/Uint8Array
-[response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
-[headers]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
-[crypto]: https://developer.mozilla.org/en-US/docs/Web/API/crypto
-[cryptokey]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey
-[urlsearchparams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
-[encoding api]: https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API
-[url api]: https://developer.mozilla.org/en-US/docs/Web/API/URL_API
-[url]: https://developer.mozilla.org/en-US/docs/Web/API/URL

package/build/index.d.ts

@@ -703,6 +703,31 @@ export interface UserInfoResponse {
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse)
  */
 export declare const skipSubjectCheck: unique symbol;
+export interface SkipJWTSignatureCheckOptions {
+    /**
+     * DANGER ZONE
+     *
+     * When JWT assertions are received via direct communication between the Client and the
+     * Token/UserInfo/Introspection endpoint (which they are in this library's supported profiles and
+     * exposed functions) the TLS server validation MAY be used to validate the issuer in place of
+     * checking the assertion's signature.
+     *
+     * Set this to `true` to omit verifying the JWT assertion's signature (e.g. ID Token, JWT Signed
+     * Introspection, or JWT Signed UserInfo Response).
+     *
+     * Setting this to `true` also means that:
+     *
+     * - The Authorization Server's JSON Web Key Set will not be requested. That is useful for
+     *   javascript runtimes that execute on the edge and cannot reliably share an in-memory cache of
+     *   the JSON Web Key Set in between invocations.
+     * - Any JWS Algorithm may be used, not just the {@link JWSAlgorithm supported ones}.
+     *
+     * Default is `false`.
+     */
+    skipJwtSignatureCheck?: boolean;
+}
+export interface ProcessUserInfoResponseOptions extends HttpRequestOptions, SkipJWTSignatureCheckOptions {
+}
 /**
  * Validates Response instance to be one coming from the
  * {@link AuthorizationServer.userinfo_endpoint `as.userinfo_endpoint`}.
@@ -719,7 +744,7 @@ export declare const skipSubjectCheck: unique symbol;
  *   OAuth 2.0 error was returned.
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
  */
-export declare function processUserInfoResponse(as: AuthorizationServer, client: Client, expectedSubject: string | typeof skipSubjectCheck, response: Response, options?: HttpRequestOptions): Promise<UserInfoResponse>;
+export declare function processUserInfoResponse(as: AuthorizationServer, client: Client, expectedSubject: string | typeof skipSubjectCheck, response: Response, options?: ProcessUserInfoResponseOptions): Promise<UserInfoResponse>;
 export interface TokenEndpointRequestOptions extends HttpRequestOptions, AuthenticatedRequestOptions, DPoPRequestOptions {
     /** Any additional parameters to send. This cannot override existing parameter values. */
     additionalParameters?: URLSearchParams;
@@ -755,6 +780,8 @@ export declare function getValidatedIdTokenClaims(ref: OpenIDTokenEndpointRespon
  * @returns JWT Claims Set from an ID Token, or undefined if there is no ID Token in `ref`.
  */
 export declare function getValidatedIdTokenClaims(ref: TokenEndpointResponse): IDToken | undefined;
+export interface ProcessRefreshTokenResponseOptions extends HttpRequestOptions, SkipJWTSignatureCheckOptions {
+}
 /**
  * Validates Refresh Token Grant Response instance to be one coming from the
  * {@link AuthorizationServer.token_endpoint `as.token_endpoint`}.
@@ -769,7 +796,7 @@ export declare function getValidatedIdTokenClaims(ref: TokenEndpointResponse): I
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-6)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens)
  */
-export declare function processRefreshTokenResponse(as: AuthorizationServer, client: Client, response: Response, options?: HttpRequestOptions): Promise<TokenEndpointResponse | OAuth2Error>;
+export declare function processRefreshTokenResponse(as: AuthorizationServer, client: Client, response: Response, options?: ProcessRefreshTokenResponseOptions): Promise<TokenEndpointResponse | OAuth2Error>;
 /**
  * Performs an Authorization Code grant request at the
  * {@link AuthorizationServer.token_endpoint `as.token_endpoint`}.
@@ -856,6 +883,8 @@ export declare const expectNoNonce: unique symbol;
  * indicate no `auth_time` ID Token claim value check should be performed.
  */
 export declare const skipAuthTimeCheck: unique symbol;
+export interface ProcessAuthorizationCodeOpenIDResponseOptions extends HttpRequestOptions, SkipJWTSignatureCheckOptions {
+}
 /**
  * (OpenID Connect only) Validates Authorization Code Grant Response instance to be one coming from
  * the {@link AuthorizationServer.token_endpoint `as.token_endpoint`}.
@@ -876,7 +905,7 @@ export declare const skipAuthTimeCheck: unique symbol;
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
  */
-export declare function processAuthorizationCodeOpenIDResponse(as: AuthorizationServer, client: Client, response: Response, expectedNonce?: string | typeof expectNoNonce, maxAge?: number | typeof skipAuthTimeCheck, options?: HttpRequestOptions): Promise<OpenIDTokenEndpointResponse | OAuth2Error>;
+export declare function processAuthorizationCodeOpenIDResponse(as: AuthorizationServer, client: Client, response: Response, expectedNonce?: string | typeof expectNoNonce, maxAge?: number | typeof skipAuthTimeCheck, options?: ProcessAuthorizationCodeOpenIDResponseOptions): Promise<OpenIDTokenEndpointResponse | OAuth2Error>;
 /**
  * (OAuth 2.0 without OpenID Connect only) Validates Authorization Code Grant Response instance to
  * be one coming from the {@link AuthorizationServer.token_endpoint `as.token_endpoint`}.
@@ -991,6 +1020,8 @@ export interface IntrospectionResponse {
     };
     readonly [claim: string]: JsonValue | undefined;
 }
+export interface ProcessIntrospectionResponseOptions extends HttpRequestOptions, SkipJWTSignatureCheckOptions {
+}
 /**
  * Validates Response instance to be one coming from the
  * {@link AuthorizationServer.introspection_endpoint `as.introspection_endpoint`}.
@@ -1005,7 +1036,7 @@ export interface IntrospectionResponse {
  * @see [RFC 7662 - OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662.html#section-2)
  * @see [draft-ietf-oauth-jwt-introspection-response-12 - JWT Response for OAuth Token Introspection](https://www.ietf.org/archive/id/draft-ietf-oauth-jwt-introspection-response-12.html#section-5)
  */
-export declare function processIntrospectionResponse(as: AuthorizationServer, client: Client, response: Response, options?: HttpRequestOptions): Promise<IntrospectionResponse | OAuth2Error>;
+export declare function processIntrospectionResponse(as: AuthorizationServer, client: Client, response: Response, options?: ProcessIntrospectionResponseOptions): Promise<IntrospectionResponse | OAuth2Error>;
 /** @ignore */
 export interface JwksRequestOptions extends HttpRequestOptions {
 }
@@ -1140,6 +1171,8 @@ export declare function processDeviceAuthorizationResponse(as: AuthorizationServ
  * @see [draft-ietf-oauth-dpop-10 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.ietf.org/archive/id/draft-ietf-oauth-dpop-10.html#name-dpop-access-token-request)
  */
 export declare function deviceCodeGrantRequest(as: AuthorizationServer, client: Client, deviceCode: string, options?: TokenEndpointRequestOptions): Promise<Response>;
+export interface ProcessDeviceCodeResponseOptions extends HttpRequestOptions, SkipJWTSignatureCheckOptions {
+}
 /**
  * Validates Device Authorization Grant Response instance to be one coming from the
  * {@link AuthorizationServer.token_endpoint `as.token_endpoint`}.
@@ -1153,7 +1186,7 @@ export declare function deviceCodeGrantRequest(as: AuthorizationServer, client:
  *   OAuth 2.0 error was returned.
  * @see [RFC 8628 - OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628.html#section-3.4)
  */
-export declare function processDeviceCodeResponse(as: AuthorizationServer, client: Client, response: Response, options?: HttpRequestOptions): Promise<TokenEndpointResponse | OAuth2Error>;
+export declare function processDeviceCodeResponse(as: AuthorizationServer, client: Client, response: Response, options?: ProcessDeviceCodeResponseOptions): Promise<TokenEndpointResponse | OAuth2Error>;
 export interface GenerateKeyPairOptions {
     /** Indicates whether or not the private key may be exported. Default is `false`. */
     extractable?: boolean;

package/build/index.js

@@ -1,7 +1,7 @@
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'oauth4webapi';
-    const VERSION = 'v1.2.2';
+    const VERSION = 'v1.3.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 const encoder = new TextEncoder();
@@ -732,10 +732,9 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
     }
     let json;
     if (getContentType(response) === 'application/jwt') {
-        if (typeof as.jwks_uri !== 'string') {
-            throw new TypeError('"as.jwks_uri" must be a string');
-        }
-        const { claims } = await validateJwt(await preserveBodyStream(response).text(), checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options))
+        const { claims } = await validateJwt(await preserveBodyStream(response).text(), checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), options?.skipJwtSignatureCheck !== true
+            ? getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options)
+            : noSignatureCheck)
             .then(validateOptionalAudience.bind(undefined, client.client_id))
             .then(validateOptionalIssuer.bind(undefined, as.issuer));
         json = claims;
@@ -770,43 +769,6 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
     }
     return json;
 }
-function padded(buf, length) {
-    const out = new Uint8Array(length);
-    out.set(buf);
-    return out;
-}
-function timingSafeEqual(a, b) {
-    const len = Math.max(a.byteLength, b.byteLength);
-    a = padded(a, len);
-    b = padded(b, len);
-    let out = 0;
-    let i = -1;
-    while (++i < len) {
-        out |= a[i] ^ b[i];
-    }
-    return out === 0;
-}
-async function idTokenHash(alg, data) {
-    let algorithm;
-    switch (alg) {
-        case 'RS256':
-        case 'PS256':
-        case 'ES256':
-            algorithm = { name: 'SHA-256' };
-            break;
-        case 'EdDSA':
-            algorithm = { name: 'SHA-512' };
-            break;
-        default:
-            throw new UnsupportedOperationError();
-    }
-    const digest = await crypto.subtle.digest(algorithm, buf(data));
-    return b64u(digest.slice(0, digest.byteLength / 2));
-}
-async function idTokenHashMatches(alg, data, actual) {
-    const expected = await idTokenHash(alg, data);
-    return timingSafeEqual(buf(actual), buf(expected));
-}
 async function authenticatedRequest(as, client, method, url, body, headers, options) {
     await clientAuthentication(as, client, body, headers, options?.clientPrivateKey);
     return fetch(url.href, {
@@ -847,7 +809,7 @@ export function getValidatedIdTokenClaims(ref) {
     }
     return idTokenClaims.get(ref);
 }
-async function processGenericAccessTokenResponse(as, client, response, options, ignoreIdToken = false, ignoreRefreshToken = false) {
+async function processGenericAccessTokenResponse(as, client, response, options, ignoreIdToken = false, ignoreRefreshToken = false, skipSignatureCheck = false) {
     assertAs(as);
     assertClient(client);
     if (!(response instanceof Response)) {
@@ -897,10 +859,9 @@ async function processGenericAccessTokenResponse(as, client, response, options,
             throw new OPE('"response" body "id_token" property must be a non-empty string');
         }
         if (json.id_token) {
-            if (typeof as.jwks_uri !== 'string') {
-                throw new TypeError('"as.jwks_uri" must be a string');
-            }
-            const { header, claims } = await validateJwt(json.id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options))
+            const { claims } = await validateJwt(json.id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), skipSignatureCheck !== true
+                ? getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options)
+                : noSignatureCheck)
                 .then(validatePresence.bind(undefined, ['aud', 'exp', 'iat', 'iss', 'sub']))
                 .then(validateIssuer.bind(undefined, as.issuer))
                 .then(validateAudience.bind(undefined, client.client_id));
@@ -910,19 +871,13 @@ async function processGenericAccessTokenResponse(as, client, response, options,
             if (client.require_auth_time && typeof claims.auth_time !== 'number') {
                 throw new OPE('unexpected ID Token "auth_time" (authentication time) claim value');
             }
-            if (claims.at_hash !== undefined) {
-                if (typeof claims.at_hash !== 'string' ||
-                    !(await idTokenHashMatches(header.alg, json.access_token, claims.at_hash))) {
-                    throw new OPE('unexpected ID Token "at_hash" (access token hash) claim value');
-                }
-            }
             idTokenClaims.set(json, claims);
         }
     }
     return json;
 }
 export async function processRefreshTokenResponse(as, client, response, options) {
-    return processGenericAccessTokenResponse(as, client, response, options);
+    return processGenericAccessTokenResponse(as, client, response, options, undefined, undefined, options?.skipJwtSignatureCheck === true);
 }
 function validateOptionalAudience(expected, result) {
     if (result.claims.aud !== undefined) {
@@ -993,7 +948,7 @@ function validatePresence(required, result) {
 export const expectNoNonce = Symbol();
 export const skipAuthTimeCheck = Symbol();
 export async function processAuthorizationCodeOpenIDResponse(as, client, response, expectedNonce, maxAge, options) {
-    const result = await processGenericAccessTokenResponse(as, client, response, options);
+    const result = await processGenericAccessTokenResponse(as, client, response, options, undefined, undefined, options?.skipJwtSignatureCheck === true);
     if (isOAuth2Error(result)) {
         return result;
     }
@@ -1137,10 +1092,9 @@ export async function processIntrospectionResponse(as, client, response, options
     }
     let json;
     if (getContentType(response) === 'application/token-introspection+jwt') {
-        if (typeof as.jwks_uri !== 'string') {
-            throw new TypeError('"as.jwks_uri" must be a string');
-        }
-        const { claims } = await validateJwt(await preserveBodyStream(response).text(), checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options))
+        const { claims } = await validateJwt(await preserveBodyStream(response).text(), checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), options?.skipJwtSignatureCheck !== true
+            ? getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options)
+            : noSignatureCheck)
             .then(checkJwtType.bind(undefined, 'token-introspection+jwt'))
             .then(validatePresence.bind(undefined, ['aud', 'iat', 'iss']))
             .then(validateIssuer.bind(undefined, as.issuer))
@@ -1260,8 +1214,9 @@ function subtleAlgorithm(key) {
     }
     throw new UnsupportedOperationError();
 }
+const noSignatureCheck = Symbol();
 async function validateJwt(jws, checkAlg, getKey) {
-    const { 0: protectedHeader, 1: payload, 2: signature, length } = jws.split('.');
+    const { 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.');
     if (length === 5) {
         throw new UnsupportedOperationError('JWE structure JWTs are not supported');
     }
@@ -1282,11 +1237,14 @@ async function validateJwt(jws, checkAlg, getKey) {
     if (header.crit !== undefined) {
         throw new OPE('unexpected JWT "crit" header parameter');
     }
-    const key = await getKey(header);
-    const input = `${protectedHeader}.${payload}`;
-    const verified = await crypto.subtle.verify(subtleAlgorithm(key), key, b64u(signature), buf(input));
-    if (!verified) {
-        throw new OPE('JWT signature verification failed');
+    const signature = b64u(encodedSignature);
+    if (getKey !== noSignatureCheck) {
+        const key = await getKey(header);
+        const input = `${protectedHeader}.${payload}`;
+        const verified = await crypto.subtle.verify(subtleAlgorithm(key), key, signature, buf(input));
+        if (!verified) {
+            throw new OPE('JWT signature verification failed');
+        }
     }
     let claims;
     try {
@@ -1331,7 +1289,7 @@ async function validateJwt(jws, checkAlg, getKey) {
             throw new OPE('unexpected JWT "aud" (audience) claim type');
         }
     }
-    return { header, claims };
+    return { header, claims, signature };
 }
 export async function validateJwtAuthResponse(as, client, parameters, expectedState, options) {
     assertAs(as);
@@ -1536,7 +1494,7 @@ export async function deviceCodeGrantRequest(as, client, deviceCode, options) {
     return tokenEndpointRequest(as, client, 'urn:ietf:params:oauth:grant-type:device_code', parameters, options);
 }
 export async function processDeviceCodeResponse(as, client, response, options) {
-    return processGenericAccessTokenResponse(as, client, response, options);
+    return processGenericAccessTokenResponse(as, client, response, options, undefined, undefined, options?.skipJwtSignatureCheck === true);
 }
 export async function generateKeyPair(alg, options) {
     let algorithm;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "OAuth 2 / OpenID Connect for Web Platform API JavaScript runtimes",
   "keywords": [
     "auth",
@@ -10,11 +10,14 @@
     "browser",
     "certified",
     "client",
-    "cloudflare-workers",
+    "cloudflare",
     "deno",
+    "edge",
     "electron",
     "fapi",
     "javascript",
+    "netlify",
+    "next",
     "nextjs",
     "node",
     "nodejs",
@@ -23,7 +26,8 @@
     "oidc",
     "openid-connect",
     "openid",
-    "vercel-edge"
+    "vercel",
+    "workers"
   ],
   "homepage": "https://github.com/panva/oauth4webapi",
   "repository": "panva/oauth4webapi",
@@ -57,22 +61,22 @@
   },
   "devDependencies": {
     "@esbuild-kit/esm-loader": "^2.5.0",
-    "@types/node": "^18.11.2",
+    "@types/node": "^18.11.7",
     "@types/qunit": "^2.19.3",
-    "ava": "^4.3.3",
-    "edge-runtime": "^1.1.0-beta.40",
-    "jose": "^4.10.0",
-    "patch-package": "^6.4.7",
+    "ava": "^5.0.1",
+    "edge-runtime": "^2.0.0",
+    "jose": "^4.10.4",
+    "patch-package": "^6.5.0",
     "prettier": "^2.7.1",
     "prettier-plugin-jsdoc": "^0.4.2",
-    "qunit": "^2.19.2",
+    "qunit": "^2.19.3",
     "testcafe": "^2.0.1",
     "testcafe-browser-provider-browserstack": "^1.14.0",
     "timekeeper": "^2.2.0",
-    "typedoc": "^0.23.17",
+    "typedoc": "^0.23.19",
     "typedoc-plugin-markdown": "^3.13.6",
     "typescript": "^4.8.4",
-    "undici": "^5.11.0",
+    "undici": "^5.12.0",
     "workerd": "^1.20220926.3"
   }
 }