auth.jwt

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { checkJwtSecret } from "./auth_jwt_decode_jwt.ts";  ← decodeJwt, another function of this group · built into the same file, even by a slim install
import { base64UrlEncode } from "./encoding_base64_base64_url_encode.ts";
import { utf8Encode } from "./encoding_utf8_utf8_encode.ts";
import { hmacSha256 } from "./crypto_hmac_sha256.ts";  ← from crypto.hmac-sha256 ^1.0.0 · built alongside by fune

/** base64url of {"alg":"HS256","typ":"JWT"}: the header is fixed, so it is written once. */
const HEADER = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
const MAX_DEPTH = 32;
const MAX_SAFE = 9007199254740991;

/** Code point order, which is how Python and Rust sort strings; JavaScript's default sort compares UTF-16 units. */
function compareCodePoints(a: string, b: string): number {
  const x = Array.from(a);
  const y = Array.from(b);
  for (let i = 0; i < x.length && i < y.length; i++) {
    const d = (x[i].codePointAt(0) as number) - (y[i].codePointAt(0) as number);
    if (d !== 0) return d;
  }
  return x.length - y.length;
}

function quote(text: string): string {
  let out = '"';
  for (let i = 0; i < text.length; i++) {
    const ch = text[i];
    const c = text.charCodeAt(i);
    if (ch === '"') out += '\\"';
    else if (ch === "\\") out += "\\\\";
    else if (ch === "\n") out += "\\n";
    else if (ch === "\r") out += "\\r";
    else if (ch === "\t") out += "\\t";
    else if (ch === "\b") out += "\\b";
    else if (ch === "\f") out += "\\f";
    else if (c < 0x20) out += "\\u" + c.toString(16).padStart(4, "0");
    else out += ch;
  }
  return out + '"';
}

/**
 * One canonical JSON text for a value: no spaces, object keys sorted by code
 * point, whole numbers only, non-ASCII written as UTF-8 rather than escaped.
 * Every language writes the same bytes, so the same claims sign to the same
 * token everywhere.
 */
function canonicalJson(value: unknown, depth: number): string {
  if (value === null) return "null";
  if (value === true) return "true";
  if (value === false) return "false";
  if (typeof value === "number") {
    if (!Number.isInteger(value) || Math.abs(value) > MAX_SAFE) {
      throw new RangeError("claims may only hold whole numbers from -(2^53 - 1) to 2^53 - 1");
    }
    return String(value === 0 ? 0 : value);
  }
  if (typeof value === "string") return quote(value);
  if (typeof value !== "object") throw new TypeError("claims must hold only JSON values");
  if (depth > MAX_DEPTH) throw new RangeError("claims are nested more than 32 deep");
  if (Array.isArray(value)) return "[" + value.map((item) => canonicalJson(item, depth + 1)).join(",") + "]";
  const entries = Object.keys(value as object)
    .sort(compareCodePoints)
    .map((key) => quote(key) + ":" + canonicalJson((value as Record<string, unknown>)[key], depth + 1));
  return "{" + entries.join(",") + "}";
}

/**
 * An HS256 JWT for the claims: header {"alg":"HS256","typ":"JWT"}, the
 * claims as canonical JSON, and the HMAC-SHA256 of the two under the secret.
 * Put exp (and usually iat, sub and jti) in the claims yourself, or use
 * auth.access-token, which does.
 */
export function signJwt(claims: Readonly<Record<string, unknown>>, secret: readonly number[]): string {
  checkJwtSecret(secret);
  if (typeof claims !== "object" || claims === null || Array.isArray(claims)) {
    throw new TypeError("claims must be a JSON object");
  }
  const signingInput = HEADER + "." + base64UrlEncode(utf8Encode(canonicalJson(claims, 1)));
  return signingInput + "." + base64UrlEncode(hmacSha256(secret, utf8Encode(signingInput)));
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { checkJwtSecret, splitJwt } from "./auth_jwt_decode_jwt.ts";  ← decodeJwt, another function of this group · built into the same file, even by a slim install
import { type JwtError, type JwtVerification } from "./auth_jwt_types.ts";
import { hmacSha256 } from "./crypto_hmac_sha256.ts";  ← from crypto.hmac-sha256 ^1.0.0 · built alongside by fune
import { constantTimeEqual } from "./crypto_constant_time_equal.ts";  ← from crypto.constant-time-equal ^1.0.0 · built alongside by fune
import { utf8Encode } from "./encoding_utf8_utf8_encode.ts";

function fail(error: JwtError, message: string): JwtVerification {
  return { valid: false, claims: null, error, message };
}

/**
 * Check an HS256 token: its shape, that it says HS256 (so "none" and
 * algorithm-confusion tokens are refused before any key is used), its
 * signature in constant time, then exp, nbf and iat against `now` with
 * leeway. A bad token is an answer, never an exception; only a bad secret,
 * `now` or leeway (the caller's own mistake) throws.
 */
export function verifyJwt(token: string, secret: readonly number[], now: number, leewaySeconds: number): JwtVerification {
  checkJwtSecret(secret);
  if (typeof now !== "number" || !Number.isInteger(now)) {
    throw new TypeError("now must be a whole number of Unix seconds");
  }
  if (typeof leewaySeconds !== "number" || !Number.isInteger(leewaySeconds) || leewaySeconds < 0) {
    throw new RangeError("leewaySeconds must be a whole number, 0 or more");
  }

  const parts = splitJwt(token);
  if (parts === null) return fail("malformed_token", "the token is not a well-formed JWT");
  if (parts.header.alg !== "HS256") return fail("unsupported_algorithm", "only HS256 tokens are accepted");
  if (Object.prototype.hasOwnProperty.call(parts.header, "crit")) {
    return fail("unsupported_algorithm", "the token requires header extensions (crit) this verifier does not support");
  }

  const expected = hmacSha256(secret, utf8Encode(parts.signingInput));
  if (!constantTimeEqual(expected, parts.signature)) {
    return fail("invalid_signature", "the token's signature does not match");
  }

  const claims = parts.claims;
  for (const name of ["exp", "nbf", "iat"]) {
    if (Object.prototype.hasOwnProperty.call(claims, name) && typeof claims[name] !== "number") {
      return fail("invalid_claims", `the token's ${name} claim is not a number`);
    }
  }
  const has = (name: string): boolean => Object.prototype.hasOwnProperty.call(claims, name);
  // RFC 7519 4.1.4: the current time MUST be before exp.
  if (has("exp") && now >= (claims.exp as number) + leewaySeconds) {
    return fail("token_expired", "the token has expired");
  }
  // RFC 7519 4.1.5: the current time MUST be at or after nbf.
  if (has("nbf") && now + leewaySeconds < (claims.nbf as number)) {
    return fail("token_not_yet_valid", "the token is not valid yet");
  }
  if (has("iat") && (claims.iat as number) > now + leewaySeconds) {
    return fail("token_issued_in_future", "the token was issued in the future");
  }
  return { valid: true, claims, error: null, message: null };
}

import { base64UrlDecode } from "./encoding_base64_base64_url_decode.ts";
import { utf8Decode } from "./encoding_utf8_utf8_decode.ts";

/** Containers nested deeper than this are refused, in every language, rather than left to each parser's own limit. */
const MAX_DEPTH = 32;
const MAX_SAFE = 9007199254740991;

/**
 * Is this one canonical, unpadded base64url segment? Checked before decoding
 * so that a hostile token is an answer (null), never a thrown error, and so
 * a segment has exactly one spelling (the unused low bits must be zero).
 */
function isSegment(text: string, allowEmpty: boolean): boolean {
  if (text.length === 0) return allowEmpty;
  if (text.length % 4 === 1) return false;
  let last = 0;
  for (let i = 0; i < text.length; i++) {
    const c = text.charCodeAt(i);
    let v: number;
    if (c >= 65 && c <= 90) v = c - 65;
    else if (c >= 97 && c <= 122) v = c - 71;
    else if (c >= 48 && c <= 57) v = c + 4;
    else if (c === 45) v = 62;
    else if (c === 95) v = 63;
    else return false;
    last = v;
  }
  if (text.length % 4 === 2) return (last & 15) === 0;
  if (text.length % 4 === 3) return (last & 3) === 0;
  return true;
}

function hasLoneSurrogate(text: string): boolean {
  for (let i = 0; i < text.length; i++) {
    const c = text.charCodeAt(i);
    if (c >= 0xd800 && c <= 0xdbff) {
      const next = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
      if (next >= 0xdc00 && next <= 0xdfff) {
        i++;
        continue;
      }
      return true;
    }
    if (c >= 0xdc00 && c <= 0xdfff) return true;
  }
  return false;
}

/**
 * JSON.parse accepts some things Python's and Rust's parsers answer
 * differently: integers beyond 2^53 (silently rounded here), overflowing
 * exponents (Infinity), escaped lone surrogates and unbounded nesting. Each
 * is refused in all three, so a token decodes the same everywhere.
 */
function isPortable(value: unknown, depth: number): boolean {
  if (typeof value === "number") {
    return Number.isFinite(value) && (!Number.isInteger(value) || Math.abs(value) <= MAX_SAFE);
  }
  if (typeof value === "string") return !hasLoneSurrogate(value);
  if (value === null || typeof value === "boolean") return true;
  if (depth > MAX_DEPTH) return false;
  if (Array.isArray(value)) return value.every((item) => isPortable(item, depth + 1));
  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
    if (hasLoneSurrogate(key) || !isPortable(item, depth + 1)) return false;
  }
  return true;
}

function parseObject(segment: string): Record<string, unknown> | null {
  let parsed: unknown;
  try {
    parsed = JSON.parse(utf8Decode(base64UrlDecode(segment)));
  } catch {
    return null;
  }
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
  return isPortable(parsed, 1) ? (parsed as Record<string, unknown>) : null;
}

/**
 * A compact JWT split into its decoded parts, or null when it is not three
 * canonical base64url segments whose first two are JSON objects. Nothing is
 * verified here; verifyJwt builds on it.
 */
export function splitJwt(token: string): { header: Record<string, unknown>; claims: Record<string, unknown>; signingInput: string; signature: readonly number[] } | null {
  if (typeof token !== "string") return null;
  const parts = token.split(".");
  if (parts.length !== 3) return null;
  if (!isSegment(parts[0], false) || !isSegment(parts[1], false) || !isSegment(parts[2], true)) return null;
  const header = parseObject(parts[0]);
  const claims = parseObject(parts[1]);
  if (header === null || claims === null) return null;
  return { header, claims, signingInput: parts[0] + "." + parts[1], signature: base64UrlDecode(parts[2]) };
}

/**
 * The secret check shared by signJwt and verifyJwt. RFC 7518 section 3.2:
 * an HS256 key MUST be at least as long as the hash, 256 bits.
 */
export function checkJwtSecret(secret: readonly number[]): void {
  if (!Array.isArray(secret) && !(secret instanceof Uint8Array)) {
    throw new TypeError("secret must be a list of integers from 0 to 255");
  }
  for (let i = 0; i < secret.length; i++) {
    const b = secret[i];
    if (typeof b !== "number" || !Number.isInteger(b) || b < 0 || b > 255) {
      throw new RangeError("secret must be a list of integers from 0 to 255");
    }
  }
  if (secret.length < 32) {
    throw new RangeError(`secret must be at least 32 bytes (RFC 7518 section 3.2), received ${secret.length}`);
  }
}

/**
 * The claims of a JWT WITHOUT checking its signature, or null when it is
 * malformed. For a browser that holds its own token and wants to read `exp`
 * or `name`; never for deciding whether to trust a token.
 */
export function decodeJwt(token: string): Readonly<Record<string, unknown>> | null {
  const parts = splitJwt(token);
  return parts === null ? null : parts.claims;
}