oauth4webapi 2.6.0 → 2.8.0

package/README.md

@@ -15,12 +15,13 @@ The following features are currently in scope and implemented in this software:
 - UserInfo and Protected Resource Requests
 - Authorization Server Issuer Identification
 - JWT Secured Introspection, Response Mode (JARM), Authorization Request (JAR), and UserInfo
+- Validating incoming JWT Access Tokens
 
 ## [Certification](https://openid.net/certification/faq/)
 
 [<img width="96" height="50" align="right" src="https://user-images.githubusercontent.com/241506/166977513-7cd710a9-7f60-4944-aebe-a658e9f36375.png" alt="OpenID Certification">](#certification)
 
-[Filip Skokan](https://github.com/panva) has certified that [this software](https://github.com/panva/oauth4webapi) conforms to the Basic RP Conformance Profile of the OpenID Connect™ protocol.
+[Filip Skokan](https://github.com/panva) has certified that [this software](https://github.com/panva/oauth4webapi) conforms to the Basic, FAPI 1.0 Advanced, FAPI 2.0 Security Profile, and FAPI 2.0 Message Signing Relying Party Conformance Profiles of the OpenID Connect™ protocol.
 
 ## [💗 Help the project](https://github.com/sponsors/panva)
 
@@ -43,7 +44,7 @@ import * as oauth2 from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.6.0/mod.ts'
+import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.8.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

@@ -1109,6 +1109,7 @@ interface JWTPayload {
     readonly nbf?: number;
     readonly exp?: number;
     readonly iat?: number;
+    readonly cnf?: ConfirmationClaims;
     readonly [claim: string]: JsonValue | undefined;
 }
 export interface IDToken extends JWTPayload {
@@ -1120,6 +1121,7 @@ export interface IDToken extends JWTPayload {
     readonly nonce?: string;
     readonly auth_time?: number;
     readonly azp?: string;
+    readonly [claim: string]: JsonValue | undefined;
 }
 export interface TokenEndpointResponse {
     readonly access_token: string;
@@ -1304,11 +1306,13 @@ export interface IntrospectionRequestOptions extends HttpRequestOptions, Authent
  * @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-4)
  */
 export declare function introspectionRequest(as: AuthorizationServer, client: Client, token: string, options?: IntrospectionRequestOptions): Promise<Response>;
-export interface IntrospectionConfirmationClaims {
+export interface ConfirmationClaims {
     readonly 'x5t#S256'?: string;
     readonly jkt?: string;
     readonly [claim: string]: JsonValue | undefined;
 }
+/** @ignore */
+export type IntrospectionConfirmationClaims = ConfirmationClaims;
 export interface IntrospectionResponse {
     readonly active: boolean;
     readonly client_id?: string;
@@ -1323,7 +1327,7 @@ export interface IntrospectionResponse {
     readonly sub?: string;
     readonly nbf?: number;
     readonly token_type?: string;
-    readonly cnf?: IntrospectionConfirmationClaims;
+    readonly cnf?: ConfirmationClaims;
     readonly [claim: string]: JsonValue | undefined;
 }
 /**
@@ -1370,7 +1374,8 @@ export declare function validateJwtAuthResponse(as: AuthorizationServer, client:
  *
  * @param as Authorization Server Metadata.
  * @param client Client Metadata.
- * @param parameters Authorization Response.
+ * @param parameters Authorization Response parameters as URLSearchParams or an instance of URL with
+ *   parameters in a fragment/hash.
  * @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
@@ -1386,7 +1391,7 @@ export declare function validateJwtAuthResponse(as: AuthorizationServer, client:
  *
  * @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>;
+export declare function experimental_validateDetachedSignatureResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedNonce: string, expectedState?: string | typeof expectNoState, maxAge?: number | typeof skipAuthTimeCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
  * DANGER ZONE
  *
@@ -1511,4 +1516,56 @@ export interface GenerateKeyPairOptions {
  * @group Utilities
  */
 export declare function generateKeyPair(alg: JWSAlgorithm, options?: GenerateKeyPairOptions): Promise<CryptoKeyPair>;
+export interface JWTAccessTokenClaims extends JWTPayload {
+    readonly iss: string;
+    readonly exp: number;
+    readonly aud: string | string[];
+    readonly sub: string;
+    readonly iat: number;
+    readonly jti: string;
+    readonly client_id: string;
+    readonly [claim: string]: JsonValue | undefined;
+}
+export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
+    /** Indicates whether DPoP use is required. */
+    requireDPoP?: boolean;
+    /** Same functionality as in {@link Client} */
+    [clockSkew]?: number;
+    /** Same functionality as in {@link Client} */
+    [clockTolerance]?: number;
+}
+/**
+ * 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.
+ *
+ * Validates use of JSON Web Token (JWT) OAuth 2.0 Access Tokens for a given {@link Request} as per
+ * RFC 9068 and optionally also RFC 9449.
+ *
+ * This does validate the presence and type of all required claims as well as the values of the
+ * {@link JWTAccessTokenClaims.iss `iss`}, {@link JWTAccessTokenClaims.exp `exp`},
+ * {@link JWTAccessTokenClaims.aud `aud`} claims.
+ *
+ * This does NOT validate the {@link JWTAccessTokenClaims.sub `sub`},
+ * {@link JWTAccessTokenClaims.jti `jti`}, and {@link JWTAccessTokenClaims.client_id `client_id`}
+ * claims beyond just checking that they're present and that their type is a string. If you need to
+ * validate these values further you would do so after this function's execution.
+ *
+ * This does NOT validate the DPoP Proof JWT nonce. If your server indicates RS-provided nonces to
+ * clients you would check these after this function's execution.
+ *
+ * This does NOT validate authorization claims such as `scope` either, you would do so after this
+ * function's execution.
+ *
+ * @param as Authorization Server to accept JWT Access Tokens from.
+ * @param request
+ * @param expectedAudience Audience identifier the resource server expects for itself.
+ * @param options
+ *
+ * @group JWT Access Tokens
+ * @group Experimental
+ *
+ * @see [RFC 9068 - JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://www.rfc-editor.org/rfc/rfc9068.html)
+ * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html)
+ */
+export declare function experimental_validateJwtAccessToken(as: AuthorizationServer, request: Request, expectedAudience: string, options?: ValidateJWTAccessTokenOptions): Promise<JWTAccessTokenClaims>;
 export {};

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.6.0';
+    const VERSION = 'v2.8.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -344,15 +344,19 @@ function keyToJws(key) {
     }
 }
 function getClockSkew(client) {
-    if (Number.isFinite(client[clockSkew])) {
-        return client[clockSkew];
+    if (client && clockSkew in 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;
+    if (client && clockTolerance in client) {
+        const tolerance = client[clockTolerance];
+        if (Number.isFinite(tolerance) && Math.sign(tolerance) !== -1) {
+            return tolerance;
+        }
     }
     return 30;
 }
@@ -1019,20 +1023,26 @@ export async function authorizationCodeGrantRequest(as, client, callbackParamete
     parameters.set('code', code);
     return tokenEndpointRequest(as, client, 'authorization_code', parameters, options);
 }
-const idTokenClaimNames = {
+const jwtClaimNames = {
     aud: 'audience',
+    c_hash: 'code hash',
+    client_id: 'client id',
     exp: 'expiration time',
     iat: 'issued at',
     iss: 'issuer',
-    sub: 'subject',
+    jti: 'jwt id',
     nonce: 'nonce',
     s_hash: 'state hash',
-    c_hash: 'code hash',
+    sub: 'subject',
+    ath: 'access token hash',
+    htm: 'http method',
+    htu: 'http uri',
+    cnf: 'confirmation',
 };
 function validatePresence(required, result) {
     for (const claim of required) {
         if (result.claims[claim] === undefined) {
-            throw new OPE(`JWT "${claim}" (${idTokenClaimNames[claim]}) claim missing`);
+            throw new OPE(`JWT "${claim}" (${jwtClaimNames[claim]}) claim missing`);
         }
     }
     return result;
@@ -1465,6 +1475,12 @@ async function idTokenHashMatches(data, actual, alg, key) {
 export async function experimental_validateDetachedSignatureResponse(as, client, parameters, expectedNonce, expectedState, maxAge, options) {
     assertAs(as);
     assertClient(client);
+    if (parameters instanceof URL) {
+        if (!parameters.hash.length) {
+            throw new TypeError('"parameters" as an instance of URL must contain a hash (fragment) with the Authorization Response parameters');
+        }
+        parameters = new URLSearchParams(parameters.hash.slice(1));
+    }
     if (!(parameters instanceof URLSearchParams)) {
         throw new TypeError('"parameters" must be an instance of URLSearchParams');
     }
@@ -1753,3 +1769,147 @@ export async function generateKeyPair(alg, options) {
     }
     return (crypto.subtle.generateKey(algorithm, options?.extractable ?? false, ['sign', 'verify']));
 }
+function normalizeHtu(htu) {
+    const url = new URL(htu);
+    url.search = '';
+    url.hash = '';
+    return url.href;
+}
+async function validateDPoP(as, request, accessTokenClaims, options) {
+    if (!request.headers.has('dpop')) {
+        throw new OPE('operation indicated DPoP use but the request has no DPoP HTTP Header');
+    }
+    if (request.headers.get('authorization')?.toLowerCase().startsWith('dpop ') === false) {
+        throw new OPE(`operation indicated DPoP use but the request's Authorization HTTP Header scheme is not DPoP`);
+    }
+    if (typeof accessTokenClaims.cnf?.jkt !== 'string') {
+        throw new OPE('operation indicated DPoP use but the JWT Access Token has no jkt confirmation claim');
+    }
+    const proof = await validateJwt(request.headers.get('dpop'), checkSigningAlgorithm.bind(undefined, undefined, as?.dpop_signing_alg_values_supported || SUPPORTED_JWS_ALGS), async ({ jwk, alg }) => {
+        if (!jwk) {
+            throw new OPE('DPoP Proof is missing the jwk header parameter');
+        }
+        const key = await importJwk(alg, jwk);
+        if (key.type !== 'public') {
+            throw new OPE('DPoP Proof jwk header parameter must contain a public key');
+        }
+        return key;
+    }, getClockSkew(options), getClockTolerance(options))
+        .then(checkJwtType.bind(undefined, 'dpop+jwt'))
+        .then(validatePresence.bind(undefined, ['iat', 'jti', 'ath', 'htm', 'htu']));
+    if (proof.claims.htm !== request.method) {
+        throw new OPE('DPoP Proof htm mismatch');
+    }
+    if (typeof proof.claims.htu !== 'string' ||
+        normalizeHtu(proof.claims.htu) !== normalizeHtu(request.url)) {
+        throw new OPE('DPoP Proof htu mismatch');
+    }
+    {
+        const accessToken = request.headers.get('authorization').split(' ')[1];
+        const expected = b64u(await crypto.subtle.digest('SHA-256', encoder.encode(accessToken)));
+        if (proof.claims.ath !== expected) {
+            throw new OPE('DPoP Proof ath mismatch');
+        }
+    }
+    {
+        let components;
+        switch (proof.header.jwk.kty) {
+            case 'EC':
+                components = {
+                    crv: proof.header.jwk.crv,
+                    kty: proof.header.jwk.kty,
+                    x: proof.header.jwk.x,
+                    y: proof.header.jwk.y,
+                };
+                break;
+            case 'OKP':
+                components = {
+                    crv: proof.header.jwk.crv,
+                    kty: proof.header.jwk.kty,
+                    x: proof.header.jwk.x,
+                };
+                break;
+            case 'RSA':
+                components = {
+                    e: proof.header.jwk.e,
+                    kty: proof.header.jwk.kty,
+                    n: proof.header.jwk.n,
+                };
+                break;
+            default:
+                throw new UnsupportedOperationError();
+        }
+        const expected = b64u(await crypto.subtle.digest('SHA-256', encoder.encode(JSON.stringify(components))));
+        if (accessTokenClaims.cnf.jkt !== expected) {
+            throw new OPE('JWT Access Token confirmation mismatch');
+        }
+    }
+}
+export async function experimental_validateJwtAccessToken(as, request, expectedAudience, options) {
+    assertAs(as);
+    if (!looseInstanceOf(request, Request)) {
+        throw new TypeError('"request" must be an instance of Request');
+    }
+    if (!validateString(expectedAudience)) {
+        throw new OPE('"expectedAudience" must be a non-empty string');
+    }
+    const authorization = request.headers.get('authorization');
+    if (!authorization) {
+        throw new OPE('"request" is missing an Authorization HTTP Header');
+    }
+    let { 0: scheme, 1: accessToken, length } = authorization.split(' ');
+    scheme = scheme.toLowerCase();
+    switch (scheme) {
+        case 'dpop':
+        case 'bearer':
+            break;
+        default:
+            throw new UnsupportedOperationError('unsupported Authorization HTTP Header scheme');
+    }
+    if (length !== 2) {
+        throw new OPE('invalid Authorization HTTP Header format');
+    }
+    const requiredClaims = [
+        'iss',
+        'exp',
+        'aud',
+        'sub',
+        'iat',
+        'jti',
+        'client_id',
+    ];
+    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))
+        .then(checkJwtType.bind(undefined, 'at+jwt'))
+        .then(validatePresence.bind(undefined, requiredClaims))
+        .then(validateIssuer.bind(undefined, as.issuer))
+        .then(validateAudience.bind(undefined, expectedAudience));
+    for (const claim of ['client_id', 'jti', 'sub']) {
+        if (typeof claims[claim] !== 'string') {
+            throw new OPE(`unexpected JWT "${claim}" claim type`);
+        }
+    }
+    if ('cnf' in claims) {
+        if (!isJsonObject(claims.cnf)) {
+            throw new OPE('unexpected JWT "cnf" (confirmation) claim value');
+        }
+        const { 0: cnf, length } = Object.keys(claims.cnf);
+        if (length) {
+            if (length !== 1) {
+                throw new UnsupportedOperationError('multiple confirmation claims are not supported');
+            }
+            if (cnf !== 'jkt') {
+                throw new UnsupportedOperationError('unsupported JWT Confirmation method');
+            }
+        }
+    }
+    if (options?.requireDPoP ||
+        scheme === 'dpop' ||
+        claims.cnf?.jkt !== undefined ||
+        request.headers.has('dpop')) {
+        await validateDPoP(as, request, claims, options);
+    }
+    return claims;
+}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "oauth4webapi",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
+    "access token",
     "auth",
     "authentication",
     "authorization",
@@ -17,6 +18,7 @@
     "electron",
     "fapi",
     "javascript",
+    "jwt",
     "netlify",
     "next",
     "nextjs",
@@ -65,18 +67,18 @@
   "devDependencies": {
     "@koa/cors": "^5.0.0",
     "@types/koa__cors": "^5.0.0",
-    "@types/node": "^20.10.8",
+    "@types/node": "^20.11.5",
     "@types/oidc-provider": "^8.4.3",
-    "@types/qunit": "^2.19.9",
+    "@types/qunit": "^2.19.10",
     "archiver": "^6.0.1",
     "ava": "^5.3.1",
     "chrome-launcher": "^1.1.0",
-    "edge-runtime": "^2.5.7",
+    "edge-runtime": "^2.5.8",
     "esbuild": "^0.19.11",
     "jose": "^5.2.0",
-    "oidc-provider": "^8.4.4",
+    "oidc-provider": "^8.4.5",
     "patch-package": "^8.0.0",
-    "prettier": "^3.1.1",
+    "prettier": "^3.2.4",
     "prettier-plugin-jsdoc": "^1.3.0",
     "puppeteer-core": "^21.7.0",
     "qunit": "^2.20.0",
@@ -86,7 +88,7 @@
     "tsx": "^4.7.0",
     "typedoc": "^0.25.7",
     "typedoc-plugin-markdown": "^3.17.1",
-    "typedoc-plugin-mdn-links": "^3.1.11",
+    "typedoc-plugin-mdn-links": "^3.1.13",
     "typescript": "^5.3.3",
     "undici": "^5.28.2"
   }