oauth4webapi 2.5.0 → 2.6.0

package/README.md

@@ -43,7 +43,7 @@ import * as oauth2 from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.5.0/mod.ts'
+import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.6.0/mod.ts'
 ```
 
 - Authorization Code Flow - OpenID Connect [source](examples/code.ts), or plain OAuth 2 [source](examples/oauth.ts)
@@ -53,7 +53,8 @@ import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.5.0/mod.ts'
 - Pushed Authorization Request (PAR) - [source](examples/par.ts) | [diff from code flow](examples/par.diff)
 - Client Credentials Grant - [source](examples/client_credentials.ts)
 - Device Authorization Grant - [source](examples/device_authorization_grant.ts)
-- FAPI 2.0 (Private Key JWT, PAR, DPoP) - [source](examples/fapi2.ts)
+- FAPI 1.0 Advanced (Private Key JWT, MTLS, JAR) - [source](examples/fapi1-advanced.ts)
+- FAPI 2.0 Security Profile (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)
 
 ## Supported Runtimes

package/build/index.d.ts

@@ -169,7 +169,7 @@ export declare const clockTolerance: unique symbol;
  *
  * // example use
  * await oauth.discoveryRequest(new URL('https://as.example.com'), {
- *   [oauth.experimentalCustomFetch]: (...args) =>
+ *   [oauth.experimental_customFetch]: (...args) =>
  *     ky(args[0], {
  *       ...args[1],
  *       hooks: {
@@ -210,16 +210,20 @@ export declare const clockTolerance: unique symbol;
  *
  * // example use
  * await oauth.discoveryRequest(new URL('https://as.example.com'), {
- *   [oauth.experimentalCustomFetch]: undici.fetch,
+ *   [oauth.experimental_customFetch]: undici.fetch,
  * })
  * ```
+ *
+ * @group Experimental
  */
-export declare const experimentalCustomFetch: unique symbol;
+export declare const experimental_customFetch: unique symbol;
+/** @ignore */
+export declare const experimentalCustomFetch: symbol;
 /**
  * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
  * compatible changes or removal may occur in any future release.
  *
- * When combined with {@link experimentalCustomFetch} (to use a Fetch API implementation that
+ * When combined with {@link experimental_customFetch} (to use a Fetch API implementation that
  * supports client certificates) this can be used to target FAPI 2.0 profiles that utilize
  * Mutual-TLS for either client authentication or sender constraining. FAPI 1.0 Advanced profiles
  * that use PAR and JARM can also be targetted.
@@ -238,8 +242,8 @@ export declare const experimentalCustomFetch: unique symbol;
  * import * as oauth from 'oauth4webapi'
  *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
- *   [oauth.experimentalUseMtlsAlias]: true,
- *   [oauth.experimentalCustomFetch]: (...args) => {
+ *   [oauth.experimental_useMtlsAlias]: true,
+ *   [oauth.experimental_customFetch]: (...args) => {
  *     return undici.fetch(args[0], {
  *       ...args[1],
  *       dispatcher: new undici.Agent({
@@ -268,8 +272,8 @@ export declare const experimentalCustomFetch: unique symbol;
  * })
  *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
- *   [oauth.experimentalUseMtlsAlias]: true,
- *   [oauth.experimentalCustomFetch]: (...args) => {
+ *   [oauth.experimental_useMtlsAlias]: true,
+ *   [oauth.experimental_customFetch]: (...args) => {
  *     return fetch(args[0], {
  *       ...args[1],
  *       client: agent,
@@ -278,9 +282,13 @@ export declare const experimentalCustomFetch: unique symbol;
  * })
  * ```
  *
+ * @group Experimental
+ *
  * @see [RFC 8705 - OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
  */
-export declare const experimentalUseMtlsAlias: unique symbol;
+export declare const experimental_useMtlsAlias: unique symbol;
+/** @ignore */
+export declare const experimentalUseMtlsAlias: symbol;
 /**
  * Authorization Server Metadata
  *
@@ -680,9 +688,11 @@ export interface HttpRequestOptions {
      * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
      * compatible changes or removal may occur in any future release.
      *
-     * See {@link experimentalCustomFetch} for its documentation.
+     * See {@link experimental_customFetch} for its documentation.
+     *
+     * @group Experimental
      */
-    [experimentalCustomFetch]?: typeof fetch;
+    [experimental_customFetch]?: typeof fetch;
 }
 export interface DiscoveryRequestOptions extends HttpRequestOptions {
     /** The issuer transformation algorithm to use. */
@@ -786,9 +796,11 @@ export interface ExperimentalUseMTLSAliasOptions {
      * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
      * compatible changes or removal may occur in any future release.
      *
-     * See {@link experimentalUseMtlsAlias} for its documentation.
+     * See {@link experimental_useMtlsAlias} for its documentation.
+     *
+     * @group Experimental
      */
-    [experimentalUseMtlsAlias]?: boolean;
+    [experimental_useMtlsAlias]?: boolean;
 }
 export interface AuthenticatedRequestOptions extends ExperimentalUseMTLSAliasOptions {
     /**
@@ -1349,6 +1361,32 @@ export declare function processIntrospectionResponse(as: AuthorizationServer, cl
  * @see [JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
  */
 export declare function validateJwtAuthResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedState?: string | typeof expectNoState | typeof skipStateCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
+/**
+ * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
+ * compatible changes or removal may occur in any future release.
+ *
+ * Same as {@link validateAuthResponse} but for FAPI 1.0 Advanced Detached Signature authorization
+ * responses.
+ *
+ * @param as Authorization Server Metadata.
+ * @param client Client Metadata.
+ * @param parameters Authorization Response.
+ * @param expectedNonce Expected ID Token `nonce` claim value.
+ * @param expectedState Expected `state` parameter value. Default is {@link expectNoState}.
+ * @param maxAge ID Token {@link IDToken.auth_time `auth_time`} claim value will be checked to be
+ *   present and conform to the `maxAge` value. Use of this option is required if you sent a
+ *   `max_age` parameter in an authorization request. Default is
+ *   {@link Client.default_max_age `client.default_max_age`} and falls back to
+ *   {@link skipAuthTimeCheck}.
+ *
+ * @returns Validated Authorization Response parameters or Authorization Error Response.
+ *
+ * @group FAPI 1.0 Advanced
+ * @group Experimental
+ *
+ * @see [Financial-grade API Security Profile 1.0 - Part 2: Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html#id-token-as-detached-signature)
+ */
+export declare function experimental_validateDetachedSignatureResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams, expectedNonce: string, expectedState?: string | typeof expectNoState, maxAge?: number | typeof skipAuthTimeCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
  * DANGER ZONE
  *

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 = 'v2.5.0';
+    const VERSION = 'v2.6.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -18,8 +18,10 @@ function looseInstanceOf(input, expected) {
 }
 export const clockSkew = Symbol();
 export const clockTolerance = Symbol();
-export const experimentalCustomFetch = Symbol();
-export const experimentalUseMtlsAlias = Symbol();
+export const experimental_customFetch = Symbol();
+export const experimentalCustomFetch = experimental_customFetch;
+export const experimental_useMtlsAlias = Symbol();
+export const experimentalUseMtlsAlias = experimental_useMtlsAlias;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 function buf(input) {
@@ -212,7 +214,7 @@ export async function discoveryRequest(issuerIdentifier, options) {
     }
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
-    return (options?.[experimentalCustomFetch] || fetch)(url.href, {
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
         headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
@@ -548,7 +550,7 @@ async function publicJwk(key) {
 }
 function validateEndpoint(value, endpoint, options) {
     if (typeof value !== 'string') {
-        if (options?.[experimentalUseMtlsAlias]) {
+        if (options?.[experimental_useMtlsAlias]) {
             throw new TypeError(`"as.mtls_endpoint_aliases.${endpoint}" must be a string`);
         }
         else {
@@ -558,7 +560,7 @@ function validateEndpoint(value, endpoint, options) {
     return new URL(value);
 }
 function resolveEndpoint(as, endpoint, options) {
-    if (options?.[experimentalUseMtlsAlias] &&
+    if (options?.[experimental_useMtlsAlias] &&
         as.mtls_endpoint_aliases &&
         endpoint in as.mtls_endpoint_aliases) {
         return validateEndpoint(as.mtls_endpoint_aliases[endpoint], endpoint, options);
@@ -690,7 +692,7 @@ export async function protectedResourceRequest(accessToken, method, url, headers
         await dpopProofJwt(headers, options.DPoP, url, 'GET', getClockSkew({ [clockSkew]: options?.[clockSkew] }), accessToken);
         headers.set('authorization', `DPoP ${accessToken}`);
     }
-    return (options?.[experimentalCustomFetch] || fetch)(url.href, {
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
         body,
         headers: Object.fromEntries(headers.entries()),
         method,
@@ -853,7 +855,7 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
 async function authenticatedRequest(as, client, method, url, body, headers, options) {
     await clientAuthentication(as, client, body, headers, options?.clientPrivateKey);
     headers.set('content-type', 'application/x-www-form-urlencoded;charset=UTF-8');
-    return (options?.[experimentalCustomFetch] || fetch)(url.href, {
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
         body,
         headers: Object.fromEntries(headers.entries()),
         method,
@@ -1017,17 +1019,20 @@ export async function authorizationCodeGrantRequest(as, client, callbackParamete
     parameters.set('code', code);
     return tokenEndpointRequest(as, client, 'authorization_code', parameters, options);
 }
-const claimNames = {
+const idTokenClaimNames = {
     aud: 'audience',
     exp: 'expiration time',
     iat: 'issued at',
     iss: 'issuer',
     sub: 'subject',
+    nonce: 'nonce',
+    s_hash: 'state hash',
+    c_hash: 'code hash',
 };
 function validatePresence(required, result) {
     for (const claim of required) {
         if (result.claims[claim] === undefined) {
-            throw new OPE(`JWT "${claim}" (${claimNames[claim]}) claim missing`);
+            throw new OPE(`JWT "${claim}" (${idTokenClaimNames[claim]}) claim missing`);
         }
     }
     return result;
@@ -1207,7 +1212,7 @@ async function jwksRequest(as, options) {
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
     headers.append('accept', 'application/jwk-set+json');
-    return (options?.[experimentalCustomFetch] || fetch)(url.href, {
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
         headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
@@ -1342,8 +1347,9 @@ async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
         throw new OPE('unexpected JWT "crit" header parameter');
     }
     const signature = b64u(encodedSignature);
+    let key;
     if (getKey !== noSignatureCheck) {
-        const key = await getKey(header);
+        key = await getKey(header);
         const input = `${protectedHeader}.${payload}`;
         const verified = await crypto.subtle.verify(keyToSubtle(key), key, signature, buf(input));
         if (!verified) {
@@ -1392,7 +1398,7 @@ async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
             throw new OPE('unexpected JWT "aud" (audience) claim type');
         }
     }
-    return { header, claims, signature };
+    return { header, claims, signature, key };
 }
 export async function validateJwtAuthResponse(as, client, parameters, expectedState, options) {
     assertAs(as);
@@ -1422,6 +1428,137 @@ export async function validateJwtAuthResponse(as, client, parameters, expectedSt
     }
     return validateAuthResponse(as, client, result, expectedState);
 }
+async function idTokenHash(alg, data, key) {
+    let algorithm;
+    switch (alg) {
+        case 'RS256':
+        case 'PS256':
+        case 'ES256':
+            algorithm = 'SHA-256';
+            break;
+        case 'RS384':
+        case 'PS384':
+        case 'ES384':
+            algorithm = 'SHA-384';
+            break;
+        case 'RS512':
+        case 'PS512':
+        case 'ES512':
+            algorithm = 'SHA-512';
+            break;
+        case 'EdDSA':
+            if (key.algorithm.name === 'Ed25519') {
+                algorithm = 'SHA-512';
+                break;
+            }
+            throw new UnsupportedOperationError();
+        default:
+            throw new UnsupportedOperationError();
+    }
+    const digest = await crypto.subtle.digest(algorithm, buf(data));
+    return b64u(digest.slice(0, digest.byteLength / 2));
+}
+async function idTokenHashMatches(data, actual, alg, key) {
+    const expected = await idTokenHash(alg, data, key);
+    return actual === expected;
+}
+export async function experimental_validateDetachedSignatureResponse(as, client, parameters, expectedNonce, expectedState, maxAge, options) {
+    assertAs(as);
+    assertClient(client);
+    if (!(parameters instanceof URLSearchParams)) {
+        throw new TypeError('"parameters" must be an instance of URLSearchParams');
+    }
+    parameters = new URLSearchParams(parameters);
+    const id_token = getURLSearchParameter(parameters, 'id_token');
+    parameters.delete('id_token');
+    switch (expectedState) {
+        case undefined:
+        case expectNoState:
+            break;
+        default:
+            if (!validateString(expectedState)) {
+                throw new TypeError('"expectedState" must be a non-empty string');
+            }
+    }
+    const result = validateAuthResponse({
+        ...as,
+        authorization_response_iss_parameter_supported: false,
+    }, client, parameters, expectedState);
+    if (isOAuth2Error(result)) {
+        return result;
+    }
+    if (!id_token) {
+        throw new OPE('"parameters" does not contain an ID Token');
+    }
+    const code = getURLSearchParameter(parameters, 'code');
+    if (!code) {
+        throw new OPE('"parameters" does not contain an Authorization Code');
+    }
+    if (typeof as.jwks_uri !== 'string') {
+        throw new TypeError('"as.jwks_uri" must be a string');
+    }
+    const requiredClaims = [
+        'aud',
+        'exp',
+        'iat',
+        'iss',
+        'sub',
+        'nonce',
+        'c_hash',
+    ];
+    if (typeof expectedState === 'string') {
+        requiredClaims.push('s_hash');
+    }
+    const { claims, header, key } = await validateJwt(id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(client), getClockTolerance(client))
+        .then(validatePresence.bind(undefined, requiredClaims))
+        .then(validateIssuer.bind(undefined, as.issuer))
+        .then(validateAudience.bind(undefined, client.client_id));
+    const clockSkew = getClockSkew(client);
+    const now = epochTime() + clockSkew;
+    if (claims.iat < now - 3600) {
+        throw new OPE('unexpected JWT "iat" (issued at) claim value, it is too far in the past');
+    }
+    if (typeof claims.c_hash !== 'string' ||
+        (await idTokenHashMatches(code, claims.c_hash, header.alg, key)) !== true) {
+        throw new OPE('invalid ID Token "c_hash" (code hash) claim value');
+    }
+    if (claims.s_hash !== undefined && typeof expectedState !== 'string') {
+        throw new OPE('could not verify ID Token "s_hash" (state hash) claim value');
+    }
+    if (typeof expectedState === 'string' &&
+        (typeof claims.s_hash !== 'string' ||
+            (await idTokenHashMatches(expectedState, claims.s_hash, header.alg, key)) !== true)) {
+        throw new OPE('invalid ID Token "s_hash" (state hash) claim value');
+    }
+    if (client.require_auth_time !== undefined && typeof claims.auth_time !== 'number') {
+        throw new OPE('unexpected ID Token "auth_time" (authentication time) claim value');
+    }
+    maxAge ?? (maxAge = client.default_max_age ?? skipAuthTimeCheck);
+    if ((client.require_auth_time || maxAge !== skipAuthTimeCheck) &&
+        claims.auth_time === undefined) {
+        throw new OPE('ID Token "auth_time" (authentication time) claim missing');
+    }
+    if (maxAge !== skipAuthTimeCheck) {
+        if (typeof maxAge !== 'number' || maxAge < 0) {
+            throw new TypeError('"options.max_age" must be a non-negative number');
+        }
+        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');
+        }
+    }
+    if (!validateString(expectedNonce)) {
+        throw new TypeError('"expectedNonce" must be a non-empty string');
+    }
+    if (claims.nonce !== expectedNonce) {
+        throw new OPE('unexpected ID Token "nonce" claim value');
+    }
+    if (Array.isArray(claims.aud) && claims.aud.length !== 1 && claims.azp !== client.client_id) {
+        throw new OPE('unexpected ID Token "azp" (authorized party) claim value');
+    }
+    return result;
+}
 function checkSigningAlgorithm(client, issuer, header) {
     if (client !== undefined) {
         if (header.alg !== client) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "auth",
@@ -68,6 +68,7 @@
     "@types/node": "^20.10.8",
     "@types/oidc-provider": "^8.4.3",
     "@types/qunit": "^2.19.9",
+    "archiver": "^6.0.1",
     "ava": "^5.3.1",
     "chrome-launcher": "^1.1.0",
     "edge-runtime": "^2.5.7",