Investigation: web compatibililty - Work in Progress

.github/ISSUE_TEMPLATE/bug-report.md

@@ -11,7 +11,9 @@ Please provide a clear and concise description of what the bug is.
 
 **Versions**
 Which version of `aws-jwt-verify` are you using?
-Which version of Node.js are you using? (Should be at least 14)
+Are you using the library in Node.js or in the Web browser?
+If Node.js, which version of Node.js are you using? (Should be at least 14)
+If Web browser, which web browser and which version of it are you using?
 If using TypeScript, which version of TypeScript are you using? (Should be at least 4)
 
 **To Reproduce**

.github/ISSUE_TEMPLATE/question.md

@@ -11,5 +11,7 @@ How can we help you?
 
 **Versions**
 Which version of `aws-jwt-verify` are you using?
-Which version of Node.js are you using? (Should be at least 14)
+Are you using the library in Node.js or in the Web browser?
+If Node.js, which version of Node.js are you using? (Should be at least 14)
+If Web browser, which web browser and which version of it are you using?
 If using TypeScript, which version of TypeScript are you using? (Should be at least 4)

.github/workflows/main.yml

@@ -26,3 +26,6 @@ jobs:
           npm run pack-for-tests
           npm run test:install
           npm run test:import
+          npm run test:browser
+        env:
+          CI: "true"

.gitignore

@@ -16,12 +16,15 @@ asn1.d.ts
 assert.d.ts
 cognito-verifier.d.ts
 error.d.ts
+https-common.d.ts
+https-node.d.ts
 https.d.ts
 index.d.ts
 jwk.d.ts
 jwt-model.d.ts
 jwt-rsa.d.ts
 jwt.d.ts
+node-web-compat*.d.ts
 safe-json-parse.d.ts
 test-util.d.ts
 typing-util.d.ts

.prettierignore

@@ -8,19 +8,25 @@ asn1.d.ts
 assert.d.ts
 cognito-verifier.d.ts
 error.d.ts
+https-common.d.ts
+https-node.d.ts
 https.d.ts
 index.d.ts
 jwk.d.ts
 jwt-model.d.ts
 jwt-rsa.d.ts
 jwt.d.ts
+node-web-compat*.d.ts
 safe-json-parse.d.ts
 test-util.d.ts
 typing-util.d.ts
 
 # compiled js
 src/*.js
 tests/unit/*.js
+tests/util/*.js
 tests/installation-and-basic-usage/*.js
 tests/cognito/cdk.out/*
 tests/import-tests/typescript.js
+tests/import-tests/should-not-compile.js
+tests/vite-app/util/generateExampleTokens.js

README.md

@@ -1,12 +1,14 @@
 # AWS JWT Verify
 
-**Node.js** library for **verifying** JWTs signed by **Amazon Cognito**, and any **OIDC-compatible IDP** that signs JWTs with **RS256** / **RS384** / **RS512**.
+**JavaScript** library for **verifying** JWTs signed by **Amazon Cognito**, and any **OIDC-compatible IDP** that signs JWTs with **RS256** / **RS384** / **RS512**.
 
 ## Installation
 
 `npm install aws-jwt-verify`
 
-Note: this library can be used with Node.js 14 or higher. If used with TypeScript, TypeScript 4 or higher is required.
+This library can be used with Node.js 14 or higher. If used with TypeScript, TypeScript 4 or higher is required.
+
+This library can also be used in Web browsers (modern browsers that support e.g. `SubtleCrypto`).
 
 ## Basic usage
 
@@ -58,7 +60,7 @@ See all verify parameters for JWTs from any IDP [here](#jwtrsaverifier-verify-pa
 ## Philosophy of this library
 
 - Do one thing and do it well. Focus solely on **verifying** JWTs.
-- Pure **TypeScript** library that can be used in **Node.js** v14 and above (both CommonJS and ESM supported).
+- Pure **TypeScript** library that can be used in **Node.js** v14 and above (both CommonJS and ESM supported), as well in the modern evergreen Web browser.
 - Support both **Amazon Cognito** as well as any other **OIDC-compatible IDP** as first class citizen.
 - **0** runtime dependencies, batteries included. This library includes all necessary code to validate RS256/RS384/RS512-signed JWTs. E.g. it contains a simple (and pluggable) **HTTP** helper to fetch the **JWKS** from the JWKS URI, and it includes a simple **ASN.1** encoder to transform JWKs into **DER-encoded RSA public keys** (in order to verify JWTs with Node.js native crypto calls).
 - Opinionated towards the **best practices** as described by the IETF in [JSON Web Token Best Current Practices](https://tools.ietf.org/id/draft-ietf-oauth-jwt-bcp-02.html#rfc.section.3).
@@ -75,6 +77,12 @@ This library was specifically designed to be easy to use in:
 - [CloudFront Lambda@Edge](https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html)
 - Node.js APIs, e.g. running in AWS Fargate, that need to verify incoming JWTs
 
+## Usage in the Web browser
+
+Many webdev toolchains (e.g. [CreateReactApp](https://github.com/facebook/create-react-app)) make including `npm` libraries in your web app easy, in which case using this library in your web app should just work.
+
+If you need to bundle this library manually yourself, be aware that this library uses [subpath imports](https://nodejs.org/api/packages.html#subpath-imports), to automatically select the Web crypto implementation when bundling for the browser. This is supported out-of-the-box by [webpack](https://webpack.js.org/) and [esbuild](https://esbuild.github.io/). An example of using this library in a Vite web app, with Cypress tests, is included in this repository [here](tests/vite-app/).
+
 ## Table of Contents
 
 - [Verifying JWTs from Amazon Cognito](#Verifying-JWTs-from-Amazon-Cognito)

jest.config.js

@@ -2,7 +2,7 @@ module.exports = {
   preset: "ts-jest",
   testEnvironment: "node",
   moduleFileExtensions: ["ts", "js"],
-  collectCoverageFrom: ["src/*.ts"],
+  collectCoverageFrom: ["src/*.ts", "!src/node-web-compat-web.ts"],
   roots: ["src", "tests/unit"],
   resolver: "<rootDir>/tests/jest-ts-js-resolver.js",
 };

package.json

@@ -17,6 +17,8 @@
     "cognito-verifier.d.ts",
     "dist",
     "error.d.ts",
+    "https-common.d.ts",
+    "https-node.d.ts",
     "https.d.ts",
     "index.d.ts",
     "jwk.d.ts",
@@ -89,20 +91,21 @@
     "typescript": "^4.4.3"
   },
   "scripts": {
-    "dist:cjs": "tsc --module CommonJS --outDir dist/cjs && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
-    "dist:esm": "tsc --module ES2020 --outDir dist/esm && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "dist:cjs": "tsc --module CommonJS --outDir dist/cjs && echo '{\"type\":\"commonjs\",\"imports\":{\"#node-web-compat\":{\"browser\":\"./node-web-compat-web.js\",\"default\":\"./node-web-compat-node.js\"}}}' > dist/cjs/package.json",
+    "dist:esm": "tsc --module ES2020 --outDir dist/esm && echo '{\"type\":\"module\",\"imports\":{\"#node-web-compat\":{\"browser\":\"./node-web-compat-web.js\",\"default\":\"./node-web-compat-node.js\"}}}' > dist/esm/package.json",
     "dist:types": "tsc --declarationDir . --declaration --emitDeclarationOnly",
     "dist": "rm -rf dist && npm run dist:cjs && npm run dist:esm && npm run dist:types",
     "lint:check": "eslint . --ignore-path .gitignore --max-warnings 0",
     "lint": "eslint . --fix --ignore-path .gitignore --max-warnings 0",
-    "pack-for-tests": "rm -f 'aws-jwt-verify-?.?.?.tgz' && npm pack && mv aws-jwt-verify-*.tgz aws-jwt-verify.tgz",
+    "pack-for-tests": "rm -f aws-jwt-verify.tgz 'aws-jwt-verify-?.?.?.tgz' && npm pack && mv aws-jwt-verify-*.tgz aws-jwt-verify.tgz",
     "prepack": "npm run dist",
     "prettier:check": "prettier --check .",
     "prettier": "prettier -w .",
-    "test:all": "npm run prettier:check && npm run test:unit && npm run test:install && npm run test:import && npm run test:speed && npm run test:cognito",
-    "test:cognito": "cd tests/cognito && npm run test",
-    "test:import": "cd tests/import-tests && rm -rf node_modules package-lock.json && npm install && node esm.mjs && node commonjs.cjs && tsc && node typescript.js && COMPILE_ERRORS=$(2>&1 tsc -p tsconfig-should-not-compile.json || true) && ([ \"$COMPILE_ERRORS\" != \"\" ] || (echo \"Ooops I did compile successfully :(\"; false))",
+    "test:all": "npm run prettier:check && npm run test:unit && npm run test:install && npm run test:import && npm run test:browser && npm run test:cognito && npm run test:speed",
+    "test:cognito": "cd tests/cognito && npm remove aws-jwt-verify.tgz && npm i --no-package-lock ../../aws-jwt-verify.tgz && npm run test",
+    "test:import": "cd tests/import-tests && npm remove aws-jwt-verify.tgz && npm i --no-package-lock ../../aws-jwt-verify.tgz && node esm.mjs && node commonjs.cjs && tsc && node typescript.js && COMPILE_ERRORS=$(2>&1 tsc -p tsconfig-should-not-compile.json || true) && ([ \"$COMPILE_ERRORS\" != \"\" ] || (echo \"Ooops I did compile successfully :(\"; false))",
     "test:install": "./tests/installation-and-basic-usage/run-tests.sh",
+    "test:browser": "cd tests/vite-app && npm remove aws-jwt-verify.tgz && npm i --no-package-lock ../../aws-jwt-verify.tgz && ./run-tests.sh",
     "test:speed": "jest -t \"speed\"",
     "test:unit": "jest --collect-coverage -t \"unit\" --testMatch '**/*.test.ts' --reporters=\"jest-junit\" --reporters=\"default\"",
     "test": "npm run test:unit",

src/assert.ts

@@ -14,12 +14,12 @@ import { AssertionErrorConstructor, FailedAssertionError } from "./error.js";
  * @param expected - The expected value
  * @param errorConstructor - Constructor for the concrete error to be thrown
  */
-export function assertStringEquals(
+export function assertStringEquals<T extends string>(
   name: string,
   actual: unknown,
-  expected: string,
+  expected: T,
   errorConstructor: AssertionErrorConstructor = FailedAssertionError
-): void {
+): asserts actual is T {
   if (!actual) {
     throw new errorConstructor(
       `Missing ${name}. Expected: ${expected}`,
@@ -53,12 +53,14 @@ export function assertStringEquals(
  * @param errorConstructor - Constructor for the concrete error to be thrown
  * a string here as well, which will mean an array with just that string
  */
-export function assertStringArrayContainsString(
+export function assertStringArrayContainsString<
+  T extends string | Readonly<string[]>
+>(
   name: string,
   actual: unknown,
-  expected: string | string[],
+  expected: T,
   errorConstructor: AssertionErrorConstructor = FailedAssertionError
-): void {
+): asserts actual is T extends Readonly<string[]> ? T[number] : T {
   if (!actual) {
     throw new errorConstructor(
       `Missing ${name}. ${expectationMessage(expected)}`,
@@ -92,9 +94,9 @@ export function assertStringArrayContainsString(
 export function assertStringArraysOverlap(
   name: string,
   actual: unknown,
-  expected: string | string[],
+  expected: string | Readonly<string[]>,
   errorConstructor: AssertionErrorConstructor = FailedAssertionError
-): void {
+): asserts actual is string | Readonly<string[]> {
   if (!actual) {
     throw new errorConstructor(
       `Missing ${name}. ${expectationMessage(expected)}`,
@@ -137,7 +139,7 @@ export function assertStringArraysOverlap(
  *
  * @param expected - The expected value.
  */
-function expectationMessage(expected: string | string[]) {
+function expectationMessage(expected: string | Readonly<string[]>) {
   if (Array.isArray(expected)) {
     if (expected.length > 1) {
       return `Expected one of: ${expected.join(", ")}`;

src/cognito-verifier.ts

@@ -168,7 +168,7 @@ function validateCognitoJwtFields(
   assertStringArrayContainsString(
     "Token use",
     payload.token_use,
-    ["id", "access"],
+    ["id", "access"] as const,
     CognitoJwtInvalidTokenUseError
   );
   if (options.tokenUse !== null) {

src/error.ts

@@ -14,7 +14,7 @@ export abstract class JwtBaseError extends Error {}
 interface AssertionError extends JwtBaseError {
   failedAssertion: {
     actual: unknown;
-    expected?: string | string[];
+    expected?: string | Readonly<string[]>;
   };
 }
 
@@ -25,7 +25,7 @@ export interface AssertionErrorConstructor {
   new (
     msg: string,
     actual: unknown,
-    expected?: string | string[]
+    expected?: string | Readonly<string[]>
   ): AssertionError;
 }
 
@@ -35,9 +35,13 @@ export interface AssertionErrorConstructor {
 export class FailedAssertionError extends JwtBaseError {
   failedAssertion: {
     actual: unknown;
-    expected?: string | string[];
+    expected?: string | Readonly<string[]>;
   };
-  constructor(msg: string, actual: unknown, expected?: string | string[]) {
+  constructor(
+    msg: string,
+    actual: unknown,
+    expected?: string | Readonly<string[]>
+  ) {
     super(msg);
     this.failedAssertion = {
       actual,
@@ -139,3 +143,9 @@ export class FetchError extends JwtBaseError {
 }
 
 export class NonRetryableFetchError extends FetchError {}
+
+/**
+ * Web compatibility errors
+ */
+
+export class NotSupportedError extends JwtBaseError {}

src/https-common.ts

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Lower-level HTTPS functionalities, common for Node.js and Web
+
+import { FetchError, NonRetryableFetchError } from "./error.js";
+
+/**
+ * Sanity check a HTTPS response where we expect to get JSON data back
+ *
+ * @param uri the uri that was being requested
+ * @param statusCode the HTTP status code, should be 200
+ * @param contentType the value of the "Content-Type" header in the response, should start with "application/json"
+ * @returns void - throws an error if the status code or content type aren't as expected
+ */
+export function validateHttpsJsonResponse(
+  uri: string,
+  statusCode?: number,
+  contentType?: string
+): void {
+  if (statusCode === 429) {
+    throw new FetchError(uri, "Too many requests");
+  } else if (statusCode !== 200) {
+    throw new NonRetryableFetchError(
+      uri,
+      `Status code is ${statusCode}, expected 200`
+    );
+  }
+  if (
+    !contentType ||
+    !contentType.toLowerCase().startsWith("application/json")
+  ) {
+    throw new NonRetryableFetchError(
+      uri,
+      `Content-type is "${contentType}", expected "application/json"`
+    );
+  }
+}