add(std/jwt): Implement the new jwt module

std/jwt/README.md

@@ -0,0 +1,102 @@
+# jwt
+
+Create and verify JSON Web Tokens.
+
+## JSON Web Token
+
+### create
+
+Takes a `payload`, `key` and `header` and returns the url-safe encoded `jwt`.
+
+```typescript
+import { create } from "https://deno.land/std/jwt/mod.ts";
+
+const payload = { foo: "bar" };
+const key = "secret";
+
+const jwt = await create(payload, key); // eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.4i-Q1Y0oDZunLgaorkqbYNcNfn5CgdF49UvJ7dUQ4GVTQvpsMLHABkZBWp9sghy3qVOsec6hOcu4RnbFkS30zQ
+```
+
+**Specific algorithm**
+
+```typescript
+const jwt = await create(payload, key, { header: { alg: "HS256" } });
+```
+
+### verify
+
+Takes a `jwt`, `key` and an optional `options` object and returns the `payload`
+of the `jwt` if the `jwt` is valid. Otherwise it throws an `Error`.
+
+```typescript
+import { verify } from "https://deno.land/std/jwt/mod.ts";
+
+const jwt =
+  "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.4i-Q1Y0oDZunLgaorkqbYNcNfn5CgdF49UvJ7dUQ4GVTQvpsMLHABkZBWp9sghy3qVOsec6hOcu4RnbFkS30zQ";
+const key = "secret";
+
+const payload = await verify(jwt, key); // { foo: "bar" }
+```
+
+**Specific algorithm**
+
+```ts
+const payload = await verify(jwt, key, { algorithm: "HS256" });
+```
+
+### decode
+
+Takes a `jwt` to return an object with the `header`, `payload` and `signature`
+properties if the `jwt` is valid. Otherwise it throws an `Error`.
+
+```typescript
+import { decode } from "https://deno.land/std/jwt/mod.ts";
+
+const jwt =
+  "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.4i-Q1Y0oDZunLgaorkqbYNcNfn5CgdF49UvJ7dUQ4GVTQvpsMLHABkZBWp9sghy3qVOsec6hOcu4RnbFkS30zQ";
+
+const { payload, signature, header } = await decode(jwt); // { header: { alg: "HS512", typ: "JWT" }, payload: { foo: "bar" }, signature: "e22f90d58d280d9ba72e06a8ae4a9b60d70d7e7e4281d178f54bc9edd510e0655342fa6c30b1c00646415a9f6c821cb7a953ac79cea139cbb84676c5912df4cd" }
+```
+
+## Expiration
+
+### setExpiration
+
+Takes either an `Date` object or a `number` (in seconds) as argument and returns
+the number of seconds since January 1, 1970, 00:00:00 UTC
+
+```typescript
+import { setExpiration } from "https://deno.land/std/jwt/mod.ts";
+
+// A specific date:
+setExpiration(new Date("2025-07-01"));
+// One hour from now:
+setExpiration(60 * 60);
+```
+
+The optional **exp** claim in the payload that identifies the expiration time on
+or after which the JWT must not be accepted for processing. This module checks
+if the current date/time is before the expiration date/time listed in the
+**exp** claim.
+
+```typescript
+const jwt = await create({ exp: setExpiration(60 * 60) }, "secret");
+```
+
+## Algorithms
+
+The following signature and MAC algorithms have been implemented:
+
+- HS256 (HMAC SHA-256)
+- HS512 (HMAC SHA-512)
+- none ([_Unsecured JWTs_](https://tools.ietf.org/html/rfc7519#section-6)).
+
+## Serialization
+
+This application uses the JWS Compact Serialization only.
+
+## Specifications
+
+- [JSON Web Token](https://tools.ietf.org/html/rfc7519)
+- [JSON Web Signature](https://www.rfc-editor.org/rfc/rfc7515.html)
+- [JSON Web Algorithms](https://www.rfc-editor.org/rfc/rfc7518.html)

std/jwt/algorithm.ts

@@ -0,0 +1,20 @@
+/*
+ * JSW §1: Cryptographic algorithms and identifiers for use with this specification
+ * are described in the separate JSON Web Algorithms (JWA) specification:
+ * https://www.rfc-editor.org/rfc/rfc7518
+ */
+export type Algorithm = "none" | "HS256" | "HS512";
+
+/*
+ * Verify the algorithm
+ * @param algorithm as string or multiple algorithms in an array excluding 'none'
+ * @param the algorithm from the jwt header
+ */
+export function verify(
+  algorithm: Algorithm | Array<Exclude<Algorithm, "none">>,
+  jwtAlg: string,
+): boolean {
+  return Array.isArray(algorithm)
+    ? (algorithm as string[]).includes(jwtAlg)
+    : algorithm === jwtAlg;
+}

std/jwt/algorithm_test.ts

@@ -0,0 +1,11 @@
+import { assertEquals } from "../testing/asserts.ts";
+
+import { verify as verifyAlgorithm } from "./algorithm.ts";
+
+Deno.test("[jwt] verify algorithm", function () {
+  assertEquals(verifyAlgorithm("HS512", "HS512"), true);
+  assertEquals(verifyAlgorithm("HS512", "HS256"), false);
+  assertEquals(verifyAlgorithm(["HS512"], "HS512"), true);
+  assertEquals(verifyAlgorithm(["HS256", "HS512"], "HS512"), true);
+  assertEquals(verifyAlgorithm(["HS512"], "HS256"), false);
+});

std/jwt/mod.ts

@@ -0,0 +1,223 @@
+import type { Algorithm } from "./algorithm.ts";
+import * as base64url from "../encoding/base64url.ts";
+import { encodeToString as convertUint8ArrayToHex } from "../encoding/hex.ts";
+import {
+  create as createSignature,
+  verify as verifySignature,
+} from "./signature.ts";
+import { verify as verifyAlgorithm } from "./algorithm.ts";
+/*
+ * JWT §4.1: The following Claim Names are registered in the IANA
+ * "JSON Web Token Claims" registry established by Section 10.1. None of the
+ * claims defined below are intended to be mandatory to use or implement in all
+ * cases, but rather they provide a starting point for a set of useful,
+ * interoperable claims.
+ * Applications using JWTs should define which specific claims they use and when
+ * they are required or optional.
+ */
+export interface PayloadObject {
+  iss?: string;
+  sub?: string;
+  aud?: string[] | string;
+  exp?: number;
+  nbf?: number;
+  iat?: number;
+  jti?: string;
+  [key: string]: unknown;
+}
+
+export type Payload = PayloadObject | string;
+
+/*
+ * JWS §4.1.1: The "alg" value is a case-sensitive ASCII string containing a
+ * StringOrURI value. This Header Parameter MUST be present and MUST be
+ * understood and processed by implementations.
+ */
+export interface Header {
+  alg: Algorithm;
+  [key: string]: unknown;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/*
+ * JWT §4.1.4: Implementers MAY provide for some small leeway to account for
+ * clock skew.
+ */
+function isExpired(exp: number, leeway = 0): boolean {
+  return exp + leeway < Date.now() / 1000;
+}
+
+/*
+ * Helper function: setExpiration()
+ * returns the number of seconds since January 1, 1970, 00:00:00 UTC
+ * @param number in seconds or Date object
+ */
+export function setExpiration(exp: number | Date): number {
+  return Math.round(
+    (exp instanceof Date ? exp.getTime() : Date.now() + exp * 1000) / 1000,
+  );
+}
+
+function tryToParsePayload(input: string): unknown {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return input;
+  }
+}
+
+/*
+ * Decodes a jwt into an { header, payload, signature } object
+ * @param jwt
+ */
+export function decode(
+  jwt: string,
+): {
+  header: unknown;
+  payload: unknown;
+  signature: unknown;
+} {
+  const parsedArray = jwt
+    .split(".")
+    .map(base64url.decode)
+    .map((uint8Array, index) =>
+      index === 0
+        ? JSON.parse(decoder.decode(uint8Array))
+        : index === 1
+        ? tryToParsePayload(decoder.decode(uint8Array))
+        : convertUint8ArrayToHex(uint8Array)
+    );
+  if (parsedArray.length !== 3) {
+    throw TypeError("The serialization is invalid.");
+  }
+
+  return {
+    header: parsedArray[0],
+    payload: parsedArray[1],
+    signature: parsedArray[2],
+  };
+}
+
+export type TokenObject = {
+  header: Header;
+  payload: unknown;
+  signature: string;
+};
+
+/*
+ * @param object
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isTokenObject(object: any): object is TokenObject {
+  if (
+    !(
+      typeof object?.signature === "string" &&
+      typeof object?.header?.alg === "string"
+    )
+  ) {
+    throw new Error(`The jwt is invalid.`);
+  }
+  if (
+    typeof object?.payload?.exp === "number" && isExpired(object.payload.exp)
+  ) {
+    throw RangeError("The jwt is expired.");
+  }
+  return true;
+}
+
+/*
+ * Verify a jwt
+ * @param jwt
+ * @param key
+ * @param object with property 'algorithm'
+ */
+export async function verify(
+  jwt: string,
+  key: string,
+  {
+    algorithm = "HS512",
+  }: {
+    algorithm?: Algorithm | Array<Exclude<Algorithm, "none">>;
+  } = {},
+): Promise<unknown> {
+  const obj = decode(jwt);
+
+  if (isTokenObject(obj)) {
+    if (!verifyAlgorithm(algorithm, obj.header.alg)) {
+      throw new Error(
+        `The token's algorithm does not match the specified algorithm "${algorithm}".`,
+      );
+    }
+
+    const { header, payload, signature } = obj;
+
+    /*
+     * JWS §4.1.11: The "crit" (critical) Header Parameter indicates that
+     * extensions to this specification and/or [JWA] are being used that MUST be
+     * understood and processed.
+     */
+    if ("crit" in obj.header) {
+      throw new Error(
+        "The 'crit' header parameter is currently not supported by this library.",
+      );
+    }
+
+    if (
+      !(await verifySignature({
+        signature,
+        key,
+        alg: header.alg,
+        signingInput: jwt.slice(0, jwt.lastIndexOf(".")),
+      }))
+    ) {
+      throw new Error(
+        "The token's signature does not match the verification signature.",
+      );
+    }
+
+    return payload;
+  }
+}
+
+/*
+ * JSW §7.1: The JWS Compact Serialization represents digitally signed or MACed
+ * content as a compact, URL-safe string. This string is:
+ *       BASE64URL(UTF8(JWS Protected Header)) || '.' ||
+ *       BASE64URL(JWS Payload) || '.' ||
+ *       BASE64URL(JWS Signature)
+ */
+function createSigningInput(header: Header, payload: Payload): string {
+  return `${
+    base64url.encode(
+      encoder.encode(JSON.stringify(header)),
+    )
+  }.${
+    base64url.encode(
+      encoder.encode(
+        typeof payload === "string" ? payload : JSON.stringify(payload),
+      ),
+    )
+  }`;
+}
+
+/*
+ * Create a jwt
+ * @param payload
+ * @param key
+ * @param object with property 'header'
+ */
+export async function create(
+  payload: Payload,
+  key: string,
+  {
+    header = { alg: "HS512", typ: "JWT" },
+  }: {
+    header?: Header;
+  } = {},
+): Promise<string> {
+  const signingInput = createSigningInput(header, payload);
+  const signature = await createSignature(header.alg, key, signingInput);
+  return `${signingInput}.${signature}`;
+}