oauth4webapi 2.15.0 → 2.16.0

package/README.md

@@ -60,8 +60,9 @@ import * as oauth from 'oauth4webapi'
   - Device Authorization Grant - [source](examples/device_authorization_grant.ts)
   - Refresh Token Grant - [source](examples/refresh_token.ts) | [diff](examples/refresh_token.diff)
 - FAPI
-  - FAPI 1.0 Advanced (Private Key JWT, MTLS, JAR) - [source](examples/fapi1-advanced.ts) | [diff](examples/fapi1-advanced.diff)
-  - FAPI 2.0 Security Profile (Private Key JWT, PAR, DPoP) - [source](examples/fapi2.ts) | [diff](examples/fapi2.diff)
+  - FAPI 1.0 Advanced - [source](examples/fapi1-advanced.ts) | [diff](examples/fapi1-advanced.diff)
+  - FAPI 2.0 Security Profile - [source](examples/fapi2.ts) | [diff](examples/fapi2.diff)
+  - FAPI 2.0 Message Signing - [source](examples/fapi2-message-signing.ts) | [diff](examples/fapi2-message-signing.diff)
 
 
 ## Supported Runtimes

package/build/index.d.ts

@@ -16,6 +16,17 @@ export type JsonPrimitive = string | number | boolean | null;
  * JSON Values
  */
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export interface ModifyAssertionFunction {
+    (
+    /**
+     * JWS Header to modify right before it is signed.
+     */
+    header: Record<string, JsonValue | undefined>, 
+    /**
+     * JWT Claims Set to modify right before it is signed.
+     */
+    payload: Record<string, JsonValue | undefined>): void;
+}
 /**
  * Interface to pass an asymmetric private key and, optionally, its associated JWK Key ID to be
  * added as a `kid` JOSE Header Parameter.
@@ -32,6 +43,12 @@ export interface PrivateKey {
      * ID) will be added to the JOSE Header.
      */
     kid?: string;
+    /**
+     * Use to modify the JWT signed by this key right before it is signed.
+     *
+     * @see {@link modifyAssertion}
+     */
+    [modifyAssertion]?: ModifyAssertionFunction;
 }
 /**
  * Supported Client Authentication Methods.
@@ -278,6 +295,100 @@ export declare const clockTolerance: unique symbol;
  * ```
  */
 export declare const customFetch: unique symbol;
+/**
+ * Use to mutate JWT header and payload before they are signed. Its intended use is working around
+ * non-conform server behaviours, such as modifying JWT "aud" (audience) claims, or otherwise
+ * changing fixed claims used by this library.
+ *
+ * @example
+ *
+ * Changing Private Key JWT client assertion audience issued from an array to a string
+ *
+ * ```ts
+ * import * as oauth from 'oauth4webapi'
+ *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let client!: oauth.Client
+ * let parameters!: URLSearchParams
+ * let clientPrivateKey!: CryptoKey
+ *
+ * const response = await oauth.pushedAuthorizationRequest(as, client, parameters, {
+ *   clientPrivateKey: {
+ *     key: clientPrivateKey,
+ *     [oauth.modifyAssertion](header, payload) {
+ *       payload.aud = as.issuer
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ *
+ * Changing Request Object issued by {@link issueRequestObject} to have an expiration of 5 minutes
+ *
+ * ```ts
+ * import * as oauth from 'oauth4webapi'
+ *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let client!: oauth.Client
+ * let parameters!: URLSearchParams
+ * let jarPrivateKey!: CryptoKey
+ *
+ * const request = await oauth.issueRequestObject(as, client, parameters, {
+ *   key: jarPrivateKey,
+ *   [oauth.modifyAssertion](header, payload) {
+ *     payload.exp = <number>payload.iat + 300
+ *   },
+ * })
+ * ```
+ */
+export declare const modifyAssertion: unique symbol;
+/**
+ * Use to add support for decrypting JWEs the client encounters, namely
+ *
+ * - Encrypted ID Tokens returned by the Token Endpoint
+ * - Encrypted ID Tokens returned as part of FAPI 1.0 Advanced Detached Signature authorization
+ *   responses
+ * - Encrypted JWT UserInfo responses
+ * - Encrypted JWT Introspection responses
+ * - Encrypted JARM Responses
+ *
+ * @example
+ *
+ * Decrypting JARM responses
+ *
+ * ```ts
+ * import * as oauth from 'oauth4webapi'
+ * import * as jose from 'jose'
+ *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let key!: CryptoKey
+ * let alg!: string
+ * let enc!: string
+ *
+ * const decoder = new TextDecoder()
+ *
+ * const client: oauth.Client = {
+ *   client_id: 'urn:example:client_id',
+ *   async [oauth.jweDecrypt](jwe) {
+ *     const { plaintext } = await compactDecrypt(jwe, key, {
+ *       keyManagementAlgorithms: [alg],
+ *       contentEncryptionAlgorithms: [enc],
+ *     }).catch((cause) => {
+ *       throw new oauth.OperationProcessingError('decryption failed', { cause })
+ *     })
+ *
+ *     return decoder.decode(plaintext)
+ *   },
+ * }
+ *
+ * const params = await oauth.validateJwtAuthResponse(as, client, currentUrl)
+ * ```
+ */
+export declare const jweDecrypt: unique symbol;
 /**
  * DANGER ZONE - This option has security implications that must be understood, assessed for
  * applicability, and accepted before use. It is critical that the JSON Web Key Set cache only be
@@ -347,48 +458,45 @@ export declare const jwksCache: unique symbol;
  * (Node.js) Using [nodejs/undici](https://github.com/nodejs/undici) for Mutual-TLS Client
  * Authentication and Certificate-Bound Access Tokens support.
  *
- * ```js
+ * ```ts
  * import * as undici from 'undici'
  * import * as oauth from 'oauth4webapi'
  *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let client!: oauth.Client
+ * let params!: URLSearchParams
+ * let key!: string // PEM-encoded key
+ * let cert!: string // PEM-encoded certificate
+ *
+ * const agent = new undici.Agent({ connect: { key, cert } })
+ *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
  *   [oauth.useMtlsAlias]: true,
- *   [oauth.customFetch]: (...args) => {
- *     return undici.fetch(args[0], {
- *       ...args[1],
- *       dispatcher: new undici.Agent({
- *         connect: {
- *           key: clientKey,
- *           cert: clientCertificate,
- *         },
- *       }),
- *     })
- *   },
+ *   [oauth.customFetch]: (...args) => undici.fetch(args[0], { ...args[1], dispatcher: agent }),
  * })
  * ```
  *
  * @example
  *
  * (Deno) Using Deno.createHttpClient API for Mutual-TLS Client Authentication and Certificate-Bound
- * Access Tokens support. This is currently (Jan 2023) locked behind the --unstable command line
- * flag.
+ * Access Tokens support.
  *
- * ```js
+ * ```ts
  * import * as oauth from 'oauth4webapi'
  *
- * const agent = Deno.createHttpClient({
- *   certChain: clientCertificate,
- *   privateKey: clientKey,
- * })
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let client!: oauth.Client
+ * let params!: URLSearchParams
+ * let key!: string // PEM-encoded key
+ * let cert!: string // PEM-encoded certificate
+ *
+ * const agent = Deno.createHttpClient({ key, cert })
  *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
  *   [oauth.useMtlsAlias]: true,
- *   [oauth.customFetch]: (...args) => {
- *     return fetch(args[0], {
- *       ...args[1],
- *       client: agent,
- *     })
- *   },
+ *   [oauth.customFetch]: (...args) => fetch(args[0], { ...args[1], client: agent }),
  * })
  * ```
  *
@@ -782,6 +890,10 @@ export interface Client {
      * See {@link clockTolerance}.
      */
     [clockTolerance]?: number;
+    /**
+     * See {@link jweDecrypt}.
+     */
+    [jweDecrypt]?: JweDecryptFunction;
     [metadata: string]: JsonValue | undefined;
 }
 /**
@@ -923,6 +1035,12 @@ export interface DPoPOptions extends CryptoKeyPair {
      * will be used automatically.
      */
     nonce?: string;
+    /**
+     * Use to modify the DPoP Proof JWT right before it is signed.
+     *
+     * @see {@link modifyAssertion}
+     */
+    [modifyAssertion]?: ModifyAssertionFunction;
 }
 export interface DPoPRequestOptions {
     /**
@@ -1611,6 +1729,9 @@ export declare function processIntrospectionResponse(as: AuthorizationServer, cl
 export interface JWKS {
     readonly keys: JWK[];
 }
+export interface JweDecryptFunction {
+    (jwe: string): Promise<string>;
+}
 /**
  * Same as {@link validateAuthResponse} but for signed JARM responses.
  *

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.15.0';
+    const VERSION = 'v2.16.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -19,6 +19,8 @@ function looseInstanceOf(input, expected) {
 export const clockSkew = Symbol();
 export const clockTolerance = Symbol();
 export const customFetch = Symbol();
+export const modifyAssertion = Symbol();
+export const jweDecrypt = Symbol();
 export const jwksCache = Symbol();
 export const useMtlsAlias = Symbol();
 const encoder = new TextEncoder();
@@ -279,7 +281,11 @@ function getKeyAndKid(input) {
     if (input.kid !== undefined && !validateString(input.kid)) {
         throw new TypeError('"kid" must be a non-empty string');
     }
-    return { key: input.key, kid: input.kid };
+    return {
+        key: input.key,
+        kid: input.kid,
+        modifyAssertion: input[modifyAssertion],
+    };
 }
 function formUrlEncode(token) {
     return encodeURIComponent(token).replace(/%20/g, '+');
@@ -366,11 +372,11 @@ function clientAssertion(as, client) {
         sub: client.client_id,
     };
 }
-async function privateKeyJwt(as, client, key, kid) {
-    return jwt({
-        alg: keyToJws(key),
-        kid,
-    }, clientAssertion(as, client), key);
+async function privateKeyJwt(as, client, key, kid, modifyAssertion) {
+    const header = { alg: keyToJws(key), kid };
+    const payload = clientAssertion(as, client);
+    modifyAssertion?.(header, payload);
+    return jwt(header, payload, key);
 }
 function assertAs(as) {
     if (typeof as !== 'object' || as === null) {
@@ -428,13 +434,13 @@ async function clientAuthentication(as, client, body, headers, clientPrivateKey)
             if (clientPrivateKey === undefined) {
                 throw new TypeError('"options.clientPrivateKey" must be provided when "client.token_endpoint_auth_method" is "private_key_jwt"');
             }
-            const { key, kid } = getKeyAndKid(clientPrivateKey);
+            const { key, kid, modifyAssertion } = getKeyAndKid(clientPrivateKey);
             if (!isPrivateKey(key)) {
                 throw new TypeError('"options.clientPrivateKey.key" must be a private CryptoKey');
             }
             body.set('client_id', client.client_id);
             body.set('client_assertion_type', 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer');
-            body.set('client_assertion', await privateKeyJwt(as, client, key, kid));
+            body.set('client_assertion', await privateKeyJwt(as, client, key, kid, modifyAssertion));
             break;
         }
         case 'tls_client_auth':
@@ -449,11 +455,11 @@ async function clientAuthentication(as, client, body, headers, clientPrivateKey)
             throw new UnsupportedOperationError('unsupported client token_endpoint_auth_method');
     }
 }
-async function jwt(header, claimsSet, key) {
+async function jwt(header, payload, key) {
     if (!key.usages.includes('sign')) {
         throw new TypeError('CryptoKey instances used for signing assertions must include "sign" in their "usages"');
     }
-    const input = `${b64u(buf(JSON.stringify(header)))}.${b64u(buf(JSON.stringify(claimsSet)))}`;
+    const input = `${b64u(buf(JSON.stringify(header)))}.${b64u(buf(JSON.stringify(payload)))}`;
     const signature = b64u(await crypto.subtle.sign(keyToSubtle(key), key, buf(input)));
     return `${input}.${signature}`;
 }
@@ -461,7 +467,7 @@ export async function issueRequestObject(as, client, parameters, privateKey) {
     assertAs(as);
     assertClient(client);
     parameters = new URLSearchParams(parameters);
-    const { key, kid } = getKeyAndKid(privateKey);
+    const { key, kid, modifyAssertion } = getKeyAndKid(privateKey);
     if (!isPrivateKey(key)) {
         throw new TypeError('"privateKey.key" must be a private CryptoKey');
     }
@@ -519,11 +525,13 @@ export async function issueRequestObject(as, client, parameters, privateKey) {
             }
         }
     }
-    return jwt({
+    const header = {
         alg: keyToJws(key),
         typ: 'oauth-authz-req+jwt',
         kid,
-    }, claims, key);
+    };
+    modifyAssertion?.(header, claims);
+    return jwt(header, claims, key);
 }
 async function dpopProofJwt(headers, options, url, htm, clockSkew, accessToken) {
     const { privateKey, publicKey, nonce = dpopNonces.get(url.origin) } = options;
@@ -540,19 +548,21 @@ async function dpopProofJwt(headers, options, url, htm, clockSkew, accessToken)
         throw new TypeError('"DPoP.publicKey.extractable" must be true');
     }
     const now = epochTime() + clockSkew;
-    const proof = await jwt({
+    const header = {
         alg: keyToJws(privateKey),
         typ: 'dpop+jwt',
         jwk: await publicJwk(publicKey),
-    }, {
+    };
+    const payload = {
         iat: now,
         jti: randomBytes(),
         htm,
         nonce,
         htu: `${url.origin}${url.pathname}`,
         ath: accessToken ? b64u(await crypto.subtle.digest('SHA-256', buf(accessToken))) : undefined,
-    }, privateKey);
-    headers.set('dpop', proof);
+    };
+    options[modifyAssertion]?.(header, payload);
+    headers.set('dpop', await jwt(header, payload, privateKey));
 }
 let jwkCache;
 async function getSetPublicJwkCache(key) {
@@ -858,8 +868,7 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
     let json;
     if (getContentType(response) === 'application/jwt') {
         assertReadableResponse(response);
-        const jwt = await response.text();
-        const { claims } = await validateJwt(jwt, checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
+        const { claims, jwt } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client), client[jweDecrypt])
             .then(validateOptionalAudience.bind(undefined, client.client_id))
             .then(validateOptionalIssuer.bind(undefined, as.issuer));
         jwtResponseBodies.set(response, jwt);
@@ -937,14 +946,14 @@ export function getValidatedIdTokenClaims(ref) {
     if (!claims) {
         throw new TypeError('"ref" was already garbage collected or did not resolve from the proper sources');
     }
-    return claims;
+    return claims[0];
 }
 export async function validateIdTokenSignature(as, ref, options) {
     assertAs(as);
-    if (!getValidatedIdTokenClaims(ref)) {
+    if (!idTokenClaims.has(ref)) {
         throw new OPE('"ref" does not contain an ID Token to verify the signature of');
     }
-    const { 0: protectedHeader, 1: payload, 2: encodedSignature } = ref.id_token.split('.');
+    const { 0: protectedHeader, 1: payload, 2: encodedSignature, } = idTokenClaims.get(ref)[1].split('.');
     const header = JSON.parse(buf(b64u(protectedHeader)));
     if (header.alg.startsWith('HS')) {
         throw new UnsupportedOperationError();
@@ -1024,7 +1033,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, getClockSkew(client), getClockTolerance(client))
+            const { claims, jwt } = 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), client[jweDecrypt])
                 .then(validatePresence.bind(undefined, ['aud', 'exp', 'iat', 'iss', 'sub']))
                 .then(validateIssuer.bind(undefined, as.issuer))
                 .then(validateAudience.bind(undefined, client.client_id));
@@ -1040,7 +1049,7 @@ async function processGenericAccessTokenResponse(as, client, response, ignoreIdT
                 (!Number.isFinite(claims.auth_time) || Math.sign(claims.auth_time) !== 1)) {
                 throw new OPE('ID Token "auth_time" (authentication time) must be a positive number');
             }
-            idTokenClaims.set(json, claims);
+            idTokenClaims.set(json, [claims, jwt]);
         }
     }
     return json;
@@ -1278,8 +1287,7 @@ export async function processIntrospectionResponse(as, client, response) {
     let json;
     if (getContentType(response) === 'application/token-introspection+jwt') {
         assertReadableResponse(response);
-        const jwt = await response.text();
-        const { claims } = await validateJwt(jwt, checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
+        const { claims, jwt } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client), client[jweDecrypt])
             .then(checkJwtType.bind(undefined, 'token-introspection+jwt'))
             .then(validatePresence.bind(undefined, ['aud', 'iat', 'iss']))
             .then(validateIssuer.bind(undefined, as.issuer))
@@ -1432,10 +1440,16 @@ async function validateJwsSignature(protectedHeader, payload, key, signature) {
         throw new OPE('JWT signature verification failed');
     }
 }
-async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
-    const { 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.');
+async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance, decryptJwt) {
+    let { 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.');
     if (length === 5) {
-        throw new UnsupportedOperationError('JWE structure JWTs are not supported');
+        if (decryptJwt !== undefined) {
+            jws = await decryptJwt(jws);
+            ({ 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.'));
+        }
+        else {
+            throw new UnsupportedOperationError('JWE structure JWTs are not supported');
+        }
     }
     if (length !== 3) {
         throw new OPE('Invalid JWT');
@@ -1502,7 +1516,7 @@ async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
             throw new OPE('unexpected JWT "aud" (audience) claim type');
         }
     }
-    return { header, claims, signature, key };
+    return { header, claims, signature, key, jwt: jws };
 }
 export async function validateJwtAuthResponse(as, client, parameters, expectedState, options) {
     assertAs(as);
@@ -1517,7 +1531,7 @@ export async function validateJwtAuthResponse(as, client, parameters, expectedSt
     if (!response) {
         throw new OPE('"parameters" does not contain a JARM response');
     }
-    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))
+    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), client[jweDecrypt])
         .then(validatePresence.bind(undefined, ['aud', 'exp', 'iss']))
         .then(validateIssuer.bind(undefined, as.issuer))
         .then(validateAudience.bind(undefined, client.client_id));
@@ -1613,7 +1627,7 @@ export async function validateDetachedSignatureResponse(as, client, parameters,
     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))
+    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), client[jweDecrypt])
         .then(validatePresence.bind(undefined, requiredClaims))
         .then(validateIssuer.bind(undefined, as.issuer))
         .then(validateAudience.bind(undefined, client.client_id));
@@ -1890,7 +1904,7 @@ async function validateDPoP(as, request, accessToken, accessTokenClaims, options
             throw new OPE('DPoP Proof jwk header parameter must contain a public key');
         }
         return key;
-    }, clockSkew, getClockTolerance(options))
+    }, clockSkew, getClockTolerance(options), undefined)
         .then(checkJwtType.bind(undefined, 'dpop+jwt'))
         .then(validatePresence.bind(undefined, ['iat', 'jti', 'ath', 'htm', 'htu']));
     const now = epochTime() + clockSkew;
@@ -1981,7 +1995,7 @@ export async function validateJwtAccessToken(as, request, expectedAudience, opti
     if (options?.requireDPoP || scheme === 'dpop' || request.headers.has('dpop')) {
         requiredClaims.push('cnf');
     }
-    const { claims } = await validateJwt(accessToken, checkSigningAlgorithm.bind(undefined, undefined, SUPPORTED_JWS_ALGS), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(options), getClockTolerance(options))
+    const { claims } = await validateJwt(accessToken, checkSigningAlgorithm.bind(undefined, undefined, SUPPORTED_JWS_ALGS), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(options), getClockTolerance(options), undefined)
         .then(checkJwtType.bind(undefined, 'at+jwt'))
         .then(validatePresence.bind(undefined, requiredClaims))
         .then(validateIssuer.bind(undefined, as.issuer))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "access token",