bazis 0.96.1

package/library/jsonapi/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Types of the universal list request in the style of the JSON:API specification.
+ *
+ * The request is described by query parameters:
+ * - `?sort=name,-createdAt`: sorting (minus = descending);
+ * - `?filter[age][gte]=18&filter[name]=Bob`: filtering (no operator = `eq`),
+ *   top-level conditions are joined with AND;
+ * - `?filter[or][0][age][lte]=19&filter[or][1][age][gte]=41`: OR groups:
+ *   AND inside a group, OR between groups (`filters AND (g0 OR g1 ...)`);
+ * - `?page[number]=2&page[size]=20` or `?page[offset]=40&page[limit]=20`: paging;
+ * - `?include=posts,author`: eager loading of relations;
+ * - `?fields[users]=name,age`: sparse fieldsets (projection).
+ *
+ * The types are pure (no dependencies on the kernel/environment): the parser and
+ * the response builder use only Web APIs (`URLSearchParams`).
+ */
+
+/** Sort direction. */
+export type SortDirection = "asc" | "desc";
+
+/** One sort key. */
+export interface SortField {
+  readonly field: string;
+  readonly dir: SortDirection;
+}
+
+/**
+ * Filter operator. The names match the comparison operators of most ORMs:
+ * - `eq`/`ne`: equal/not equal (a `null` value means IS [NOT] NULL);
+ * - `gt`/`gte`/`lt`/`lte`: comparisons;
+ * - `like`: LIKE with a user pattern; `contains`/`startsWith`/`endsWith`:
+ *   LIKE with escaped wildcards;
+ * - `in`/`nin`: in/not in a list (comma-separated value);
+ * - `isNull`/`isNotNull`: NULL check (no value needed).
+ */
+export type FilterOperator =
+  | "eq"
+  | "ne"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "like"
+  | "contains"
+  | "startsWith"
+  | "endsWith"
+  | "in"
+  | "nin"
+  | "isNull"
+  | "isNotNull";
+
+/** One filter condition on a field. */
+export interface FilterRule {
+  readonly field: string;
+  readonly op: FilterOperator;
+  /** An array for `in`/`nin`; an empty string for `isNull`/`isNotNull`. */
+  readonly value: string | readonly string[];
+}
+
+/**
+ * A group of conditions joined with **AND**: one branch of an OR expression.
+ * Several groups are joined with **OR** (see {@link ListQuery.or}).
+ */
+export type FilterGroup = readonly FilterRule[];
+
+/**
+ * Normalized paging. Either JSON:API style (`page[number]/size` or
+ * `page[offset]/limit`) is brought to one form: `offset`/`limit` for the
+ * database, `number`/`size` for the response.
+ */
+export interface PageParams {
+  /** Page number (1-based). */
+  readonly number: number;
+  /** Page size. */
+  readonly size: number;
+  /** Offset (0-based) = `(number - 1) * size`. */
+  readonly offset: number;
+  /** Limit = `size`. */
+  readonly limit: number;
+}
+
+/** A fully parsed and validated list request. */
+export interface ListQuery {
+  readonly sort: readonly SortField[];
+  /**
+   * Top-level conditions (`filter[field][op]=v`) joined with **AND**.
+   * Always applied.
+   */
+  readonly filters: readonly FilterRule[];
+  /**
+   * OR groups (`filter[or][N][field][op]=v`): conditions inside a group are joined
+   * with AND, different groups with OR. The whole OR expression is joined with
+   * {@link filters} by AND: `filters AND (group0 OR group1 OR ...)`. Empty means
+   * no OR logic.
+   */
+  readonly or: readonly FilterGroup[];
+  readonly page: PageParams;
+  readonly include: readonly string[];
+  /** Sparse fieldsets per resource type (`fields[type]=a,b`). */
+  readonly fields: Readonly<Record<string, readonly string[]>>;
+}
+
+/** Paging limits and defaults. */
+export interface PageOptions {
+  /** Default page size (if the client did not set one). Defaults to 20. */
+  readonly defaultSize?: number;
+  /** Maximum allowed page size. Defaults to 100. */
+  readonly maxSize?: number;
+}
+
+/**
+ * Contract of what the request may use. Secure by default: anything not listed
+ * explicitly is forbidden (sorting/filtering/include by unlisted fields results
+ * in 400), so the client cannot reach internal columns.
+ */
+export interface ListQueryOptions {
+  /** Fields that allow sorting (`?sort=`). Not set: sorting is forbidden. */
+  readonly sort?: readonly string[];
+  /** Fields → allowed filter operators. Not set: filtering is forbidden. */
+  readonly filter?: Readonly<Record<string, readonly FilterOperator[]>>;
+  /** Allowed include paths (`?include=`). Not set: include is forbidden. */
+  readonly include?: readonly string[];
+  /** Paging limits. */
+  readonly page?: PageOptions;
+}

package/library/jwt/JwtEncoder.ts

@@ -0,0 +1,40 @@
+import { base64UrlEncode, base64UrlEncodeString } from "./base64url";
+import type { JwtHeader, JwtPayload } from "./claims";
+import type { SigningAlgorithm } from "./signing/SigningAlgorithm";
+import { JwtKeyRing } from "./JwtKeyRing";
+import { resolveMaxTokenLength } from "./limits";
+
+/**
+ * Serialises a claim set into a signed compact JWS (`header.payload.signature`).
+ *
+ * Stateless and bound to a single {@link SigningAlgorithm}; the caller owns
+ * claim construction (timestamps, issuer, audience). One encoder per algorithm.
+ */
+export class JwtEncoder {
+  private readonly maxTokenLength: number;
+
+  public constructor(private readonly algorithm: SigningAlgorithm | JwtKeyRing, options: { readonly maxTokenLength?: number } = {}) {
+    this.maxTokenLength = resolveMaxTokenLength(options.maxTokenLength);
+    if (!(algorithm instanceof JwtKeyRing) && !algorithm.canSign) {
+      throw new Error(`Signing algorithm '${algorithm.alg}' has no signing key`);
+    }
+  }
+
+  public async encode(payload: JwtPayload): Promise<string> {
+    const algorithm = this.algorithm instanceof JwtKeyRing ? this.algorithm.signingKey() : this.algorithm;
+    const header: JwtHeader = {
+      alg: algorithm.alg,
+      typ: "JWT",
+      ...(algorithm.keyId === undefined ? {} : { kid: algorithm.keyId }),
+    };
+    const signingInput = `${base64UrlEncodeString(JSON.stringify(header))}.${base64UrlEncodeString(
+      JSON.stringify(payload),
+    )}`;
+    if (signingInput.length >= this.maxTokenLength) throw new RangeError("JWT exceeds maxTokenLength");
+    const signature = await algorithm.sign(signingInput);
+    if (this.algorithm instanceof JwtKeyRing) this.algorithm.assertCurrent(algorithm);
+    const token = `${signingInput}.${base64UrlEncode(signature)}`;
+    if (token.length > this.maxTokenLength) throw new RangeError("JWT exceeds maxTokenLength");
+    return token;
+  }
+}

package/library/jwt/JwtKeyRing.ts

@@ -0,0 +1,164 @@
+import { JwtAlgorithmError, JwtClaimError } from "./errors";
+import type { SigningAlgorithm } from "./signing/SigningAlgorithm";
+
+export interface JwtKeyEntry {
+  readonly keyId: string;
+  readonly algorithm: SigningAlgorithm;
+}
+
+export interface JwtKeyRingConfig {
+  readonly keys: readonly JwtKeyEntry[];
+  /** Omit for a verifier-only ring. */
+  readonly activeKeyId?: string;
+  /** Explicit, time-bounded migration of tokens issued without kid. Never used for unknown ids. */
+  readonly legacy?: { readonly keyId: string; readonly acceptUntil: number };
+}
+
+/** A prepared, immutable binding between an id and one crypto strategy. */
+export interface SelectedJwtKey extends SigningAlgorithm {
+  readonly keyId: string;
+}
+
+interface KeySnapshot {
+  readonly keys: ReadonlyMap<string, SelectedJwtKey>;
+  readonly sources: ReadonlyMap<string, SigningAlgorithm>;
+  readonly activeKeyId?: string;
+  readonly legacy?: { readonly keyId: string; readonly acceptUntil: number };
+}
+
+/** Trusted local key lifecycle. Never resolves token-provided URLs or key material. */
+export class JwtKeyRing {
+  private revision = 0;
+  private readonly revoked = new Set<string>();
+
+  private constructor(private snapshot: KeySnapshot) {}
+
+  /** Checks all keys before exposing the ring to token consumers. */
+  public static async create(config: JwtKeyRingConfig): Promise<JwtKeyRing> {
+    return new JwtKeyRing(await prepare(config));
+  }
+
+  /** Prepare, then publish once. A concurrent replacement/revocation wins over stale work. */
+  public async replace(config: JwtKeyRingConfig): Promise<void> {
+    const revision = this.revision;
+    const candidate = await prepare(config, this.snapshot);
+    if (this.revision !== revision) throw new Error("JWT key ring changed during preparation; retry with current configuration");
+    for (const id of candidate.keys.keys()) {
+      if (this.revoked.has(id)) throw new Error("A revoked JWT key id cannot be restored");
+    }
+    // Retired ids are never reused during this ring's lifetime.
+    for (const id of this.snapshot.keys.keys()) {
+      if (!candidate.keys.has(id)) this.revoked.add(id);
+    }
+    this.snapshot = candidate;
+    this.revision += 1;
+  }
+
+  /** Immediately distrust an id, including any in-flight use. No crypto or I/O. */
+  public revoke(keyId: string): boolean {
+    requireKeyId(keyId);
+    const keys = new Map(this.snapshot.keys);
+    const sources = new Map(this.snapshot.sources);
+    const existed = keys.delete(keyId);
+    sources.delete(keyId);
+    this.revoked.add(keyId);
+    this.snapshot = { keys, sources, activeKeyId: this.snapshot.activeKeyId === keyId ? undefined : this.snapshot.activeKeyId,
+      legacy: this.snapshot.legacy?.keyId === keyId ? undefined : this.snapshot.legacy };
+    this.revision += 1;
+    return existed;
+  }
+
+  /** Safe operational metadata; no secrets, PEM, or token values. */
+  public status() {
+    return Object.freeze({
+      revision: this.revision,
+      activeKeyId: this.snapshot.activeKeyId,
+      ...(this.snapshot.legacy === undefined ? {} : { legacy: this.snapshot.legacy }),
+      keys: Object.freeze([...this.snapshot.keys.values()].map(key => Object.freeze({ keyId: key.keyId, alg: key.alg, canSign: key.canSign }))),
+    });
+  }
+
+  /** @internal Captured once by JwtEncoder, before its first await. */
+  public signingKey(): SelectedJwtKey {
+    const key = this.snapshot.activeKeyId === undefined ? undefined : this.snapshot.keys.get(this.snapshot.activeKeyId);
+    if (key === undefined) throw new Error("JWT key ring has no active signing key");
+    return key;
+  }
+
+  /** @internal The untrusted id selects only an explicitly configured key. */
+  public verificationKey(keyId: string | undefined, alg: string): SelectedJwtKey {
+    const legacy = this.snapshot.legacy;
+    const selectedId = keyId === undefined && legacy !== undefined && Date.now() / 1000 < legacy.acceptUntil
+      ? legacy.keyId : keyId;
+    const key = selectedId === undefined ? undefined : this.snapshot.keys.get(selectedId);
+    if (key === undefined) throw new JwtClaimError("kid", "unknown or missing key id");
+    if (alg !== key.alg) throw new JwtAlgorithmError("JWT algorithm does not match the selected key");
+    return key;
+  }
+
+  /** @internal Linearization check after asynchronous crypto. */
+  public assertCurrent(key: SigningAlgorithm): void {
+    if (key.keyId === undefined || this.snapshot.keys.get(key.keyId) !== key) throw new JwtClaimError("kid", "key was removed during the operation");
+  }
+}
+
+async function prepare(config: JwtKeyRingConfig, previous?: KeySnapshot): Promise<KeySnapshot> {
+  if (config === null || typeof config !== "object" || Array.isArray(config) ||
+      !Array.isArray(config.keys) || config.keys.length < 1 || config.keys.length > 32) {
+    throw new TypeError("JWT key ring requires between 1 and 32 keys");
+  }
+  const activeKeyId = config.activeKeyId;
+  if (activeKeyId !== undefined) requireKeyId(activeKeyId);
+  let legacy: KeySnapshot["legacy"];
+  if (config.legacy !== undefined) {
+    if (config.legacy === null || typeof config.legacy !== "object" || Array.isArray(config.legacy)) throw new TypeError("Invalid JWT legacy key policy");
+    const { keyId, acceptUntil } = config.legacy;
+    requireKeyId(keyId);
+    if (typeof acceptUntil !== "number" || !Number.isFinite(acceptUntil) || acceptUntil <= 0) throw new TypeError("JWT legacy acceptUntil must be a positive finite NumericDate");
+    legacy = Object.freeze({ keyId, acceptUntil });
+  }
+  const keys = new Map<string, SelectedJwtKey>();
+  const sources = new Map<string, SigningAlgorithm>();
+  // Take all metadata snapshots synchronously before calling user crypto strategies.
+  for (const entry of [...config.keys]) {
+    if (entry === null || typeof entry !== "object") throw new TypeError("Invalid JWT key entry");
+    const { keyId, algorithm } = entry;
+    requireKeyId(keyId);
+    if (keys.has(keyId)) throw new TypeError("Duplicate JWT key id");
+    if (algorithm === null || typeof algorithm !== "object" || typeof algorithm.alg !== "string" ||
+        algorithm.alg.length === 0 || algorithm.alg.toLowerCase() === "none" ||
+        typeof algorithm.canSign !== "boolean" || typeof algorithm.sign !== "function" || typeof algorithm.verify !== "function") {
+      throw new TypeError("Invalid JWT signing algorithm");
+    }
+    if (algorithm.keyId !== undefined && algorithm.keyId !== keyId) throw new TypeError("JWT key id conflicts with algorithm key id");
+    const prior = previous?.keys.get(keyId);
+    if (prior !== undefined && prior.alg !== algorithm.alg) throw new TypeError("Use a new key id when changing the algorithm");
+    const key = prior !== undefined && previous?.sources.get(keyId) === algorithm ? prior : Object.freeze({
+      keyId, alg: algorithm.alg, canSign: algorithm.canSign,
+      sign: algorithm.sign.bind(algorithm), verify: algorithm.verify.bind(algorithm),
+    });
+    keys.set(keyId, key);
+    sources.set(keyId, algorithm);
+  }
+  if (activeKeyId !== undefined && !keys.get(activeKeyId)?.canSign) throw new TypeError("Active JWT key must exist and support signing");
+  if (legacy !== undefined && !keys.has(legacy.keyId)) throw new TypeError("Legacy JWT key must exist in the trusted set");
+  for (const key of keys.values()) {
+    if (key === previous?.keys.get(key.keyId)) continue;
+    const challenge = `bazis-key-check.${crypto.randomUUID()}`;
+    if (key.canSign) {
+      const signature = await key.sign(challenge);
+      if (!await key.verify(challenge, signature) || await key.verify(`${challenge}.changed`, signature)) {
+        throw new Error("JWT signing key self-test failed");
+      }
+    } else if (await key.verify(challenge, new Uint8Array(0))) {
+      throw new Error("JWT verification key accepted an empty signature");
+    }
+  }
+  return { keys, sources, activeKeyId, legacy };
+}
+
+function requireKeyId(value: string): void {
+  if (typeof value !== "string" || value.length < 1 || value.length > 128 || /[^A-Za-z0-9._-]/.test(value)) {
+    throw new TypeError("JWT key id must contain 1 to 128 ASCII letters, digits, dots, underscores or hyphens");
+  }
+}

package/library/jwt/JwtValidator.ts

@@ -0,0 +1,210 @@
+import { base64UrlDecode, base64UrlDecodeToString } from "./base64url";
+import { RegisteredClaims, TOKEN_USE_CLAIM, type JwtHeader, type JwtPayload, type TokenUse } from "./claims";
+import {
+  JwtAlgorithmError,
+  JwtClaimError,
+  JwtExpiredError,
+  JwtMalformedError,
+  JwtNotYetValidError,
+  JwtSignatureError,
+} from "./errors";
+import type { SigningAlgorithm } from "./signing/SigningAlgorithm";
+import { JwtKeyRing } from "./JwtKeyRing";
+import { resolveMaxTokenLength } from "./limits";
+
+/** Default leeway (seconds) for `exp`/`nbf` to tolerate clock drift. */
+export const DEFAULT_CLOCK_SKEW_SECONDS = 60;
+
+export interface JwtValidationOptions {
+  /** Require `iss` to equal this value. */
+  readonly issuer?: string;
+  /** Require `aud` to contain at least one of these values. */
+  readonly audience?: string | readonly string[];
+  /** Require the `token_use` claim to equal this value. */
+  readonly expectedTokenUse?: TokenUse;
+  /** Finite, non-negative leeway in seconds (default {@link DEFAULT_CLOCK_SKEW_SECONDS}). */
+  readonly clockSkewSeconds?: number;
+  /** Require `exp` to be present as a NumericDate. Default true. */
+  readonly requireExpiration?: boolean;
+  /** Maximum compact JWS length, checked before parsing or crypto. Default 16384. */
+  readonly maxTokenLength?: number;
+}
+
+/** A successfully verified token: decoded header and payload. */
+export interface VerifiedToken {
+  readonly header: JwtHeader;
+  readonly payload: JwtPayload;
+}
+
+/**
+ * Verifies a compact JWS and validates its registered claims.
+ *
+ * Invalid tokens throw a {@link JwtError} subclass. Operational failures of
+ * the configured signing strategy propagate unchanged. The `alg` header must match the configured
+ * algorithm, which blocks algorithm-confusion attacks. Bound to one
+ * {@link SigningAlgorithm}; create separate validators for separate keys.
+ */
+export class JwtValidator {
+  private readonly clockSkewSeconds: number;
+  private readonly options: JwtValidationOptions;
+  private readonly maxTokenLength: number;
+
+  public constructor(
+    private readonly algorithm: SigningAlgorithm | JwtKeyRing,
+    options: JwtValidationOptions = {},
+  ) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+      throw new TypeError("JWT validation options must be an object");
+    }
+    const snapshot = { ...options };
+    if (snapshot.issuer !== undefined && (typeof snapshot.issuer !== "string" || snapshot.issuer.length === 0)) {
+      throw new TypeError("JWT issuer must be a non-empty string");
+    }
+    if (snapshot.audience !== undefined) {
+      const values = typeof snapshot.audience === "string" ? [snapshot.audience]
+        : Array.isArray(snapshot.audience) ? [...snapshot.audience] : snapshot.audience;
+      if (!Array.isArray(values) || values.length === 0 || values.some(value => typeof value !== "string" || value.length === 0)) {
+        throw new TypeError("JWT audience must be a non-empty string or array of non-empty strings");
+      }
+      if (Array.isArray(snapshot.audience)) snapshot.audience = Object.freeze(values);
+    }
+    if (snapshot.expectedTokenUse !== undefined && snapshot.expectedTokenUse !== "access" && snapshot.expectedTokenUse !== "refresh") {
+      throw new TypeError("JWT expectedTokenUse must be access or refresh");
+    }
+    if (snapshot.requireExpiration !== undefined && typeof snapshot.requireExpiration !== "boolean") {
+      throw new TypeError("JWT requireExpiration must be a boolean");
+    }
+    const skew = snapshot.clockSkewSeconds === undefined ? DEFAULT_CLOCK_SKEW_SECONDS : snapshot.clockSkewSeconds;
+    if (typeof skew !== "number" || !Number.isFinite(skew) || skew < 0) {
+      throw new RangeError("JWT clockSkewSeconds must be finite and non-negative");
+    }
+    this.options = Object.freeze(snapshot);
+    this.clockSkewSeconds = skew;
+    this.maxTokenLength = resolveMaxTokenLength(snapshot.maxTokenLength);
+  }
+
+  public async validate(token: string): Promise<VerifiedToken> {
+    if (typeof token !== "string") {
+      throw new JwtMalformedError("Malformed JWT: expected a string");
+    }
+    if (token.length > this.maxTokenLength) throw new JwtMalformedError("JWT exceeds maxTokenLength");
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts.some(part => part.length === 0)) {
+      throw new JwtMalformedError("Malformed JWT: expected three non-empty segments");
+    }
+    const [encodedHeader, encodedPayload, encodedSignature] = parts as [string, string, string];
+
+    const header = this.parseSegment<JwtHeader & Record<string, unknown>>(encodedHeader, "header");
+    if (typeof header.alg !== "string" || header.alg.length === 0) {
+      throw new JwtMalformedError("Malformed JWT algorithm");
+    }
+    for (const field of ["kid", "typ", "cty"] as const) {
+      if (header[field] !== undefined && typeof header[field] !== "string") {
+        throw new JwtMalformedError(`Malformed JWT ${field}`);
+      }
+    }
+    if (header.crit !== undefined) {
+      throw new JwtMalformedError("JWT critical extensions are not supported");
+    }
+    if (header.b64 !== undefined && header.b64 !== true) {
+      throw new JwtMalformedError("JWT unencoded payloads are not supported");
+    }
+    const algorithm = this.algorithm instanceof JwtKeyRing ? this.algorithm.verificationKey(header.kid, header.alg) : this.algorithm;
+    if (header.alg !== algorithm.alg) {
+      throw new JwtAlgorithmError(`Unexpected algorithm '${header.alg}', expected '${algorithm.alg}'`);
+    }
+    if (!(this.algorithm instanceof JwtKeyRing) && algorithm.keyId !== undefined && header.kid !== algorithm.keyId) {
+      throw new JwtClaimError("kid", "key id mismatch");
+    }
+
+    const signingInput = `${encodedHeader}.${encodedPayload}`;
+    let signature: Uint8Array;
+    try {
+      signature = base64UrlDecode(encodedSignature);
+    } catch {
+      throw new JwtMalformedError("Malformed JWT signature encoding");
+    }
+    if (!(await algorithm.verify(signingInput, signature))) {
+      throw new JwtSignatureError();
+    }
+    if (this.algorithm instanceof JwtKeyRing) {
+      this.algorithm.assertCurrent(algorithm);
+      // Recheck migration cutoff/policy after crypto, including a concurrent policy change.
+      if (this.algorithm.verificationKey(header.kid, header.alg) !== algorithm) throw new JwtClaimError("kid", "key policy changed during the operation");
+    }
+
+    const payload = this.parseSegment<JwtPayload>(encodedPayload, "payload");
+    this.validateClaims(payload);
+    return { header, payload };
+  }
+
+  private parseSegment<T>(segment: string, label: string): T {
+    try {
+      const value: unknown = JSON.parse(base64UrlDecodeToString(segment));
+      if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("Expected a JSON object");
+      }
+      return value as T;
+    } catch {
+      throw new JwtMalformedError(`Malformed JWT ${label}`);
+    }
+  }
+
+  private validateClaims(payload: JwtPayload): void {
+    const now = Date.now() / 1000;
+
+    for (const claim of [RegisteredClaims.Issuer, RegisteredClaims.Subject, RegisteredClaims.JwtId]) {
+      if (payload[claim] !== undefined && typeof payload[claim] !== "string") {
+        throw new JwtClaimError(claim, "must be a string");
+      }
+    }
+    const audience = payload[RegisteredClaims.Audience];
+    if (audience !== undefined && typeof audience !== "string" &&
+        (!Array.isArray(audience) || audience.length === 0 || audience.some(value => typeof value !== "string"))) {
+      throw new JwtClaimError(RegisteredClaims.Audience, "must be a string or non-empty array of strings");
+    }
+
+    if (this.options.issuer !== undefined && payload[RegisteredClaims.Issuer] !== this.options.issuer) {
+      throw new JwtClaimError(RegisteredClaims.Issuer, "issuer mismatch");
+    }
+
+    if (this.options.audience !== undefined) {
+      this.assertAudience(payload[RegisteredClaims.Audience]);
+    }
+
+    if (this.options.expectedTokenUse !== undefined && payload[TOKEN_USE_CLAIM] !== this.options.expectedTokenUse) {
+      throw new JwtClaimError(TOKEN_USE_CLAIM, `expected '${this.options.expectedTokenUse}'`);
+    }
+
+    const exp = this.numericDate(payload, RegisteredClaims.ExpiresAt);
+    if (exp === undefined) {
+      if (this.options.requireExpiration !== false) {
+        throw new JwtClaimError(RegisteredClaims.ExpiresAt, "expiration is required");
+      }
+    } else if (now - this.clockSkewSeconds >= exp) {
+      throw new JwtExpiredError();
+    }
+
+    const nbf = this.numericDate(payload, RegisteredClaims.NotBefore);
+    if (nbf !== undefined && now + this.clockSkewSeconds < nbf) {
+      throw new JwtNotYetValidError();
+    }
+    this.numericDate(payload, RegisteredClaims.IssuedAt);
+  }
+
+  private numericDate(payload: JwtPayload, claim: string): number | undefined {
+    const value = payload[claim];
+    if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value))) {
+      throw new JwtClaimError(claim, "must be a finite NumericDate");
+    }
+    return value;
+  }
+
+  private assertAudience(actual: JwtPayload[string]): void {
+    const expected = typeof this.options.audience === "string" ? [this.options.audience] : this.options.audience!;
+    const present = typeof actual === "string" ? [actual] : Array.isArray(actual) ? actual : [];
+    if (!present.some((value) => expected.includes(value))) {
+      throw new JwtClaimError(RegisteredClaims.Audience, "audience mismatch");
+    }
+  }
+}