auth.access-token

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

import { type AccessToken } from "./auth_access_token_types.ts";
import { signJwt } from "./auth_jwt_sign_jwt.ts";
import { unixToIso } from "./time_unix_to_iso.ts";  ← from time.unix-to-iso ^1.0.0 · built alongside by fune

function isWhole(value: unknown): value is number {
  return typeof value === "number" && Number.isInteger(value);
}

/**
 * A signed access token for a user who has just logged in, with the claims
 * this API relies on: sub, name, email, ver (token version), jti, iat and
 * exp. Everything that varies (the time, the random jti) is passed in.
 */
export function issueAccessToken(
  subject: string,
  name: string,
  email: string,
  tokenVersion: number,
  jti: string,
  now: number,
  ttlSeconds: number,
  secret: readonly number[],
): AccessToken {
  if (typeof subject !== "string" || subject.length === 0) throw new TypeError("subject must be a non-empty string");
  if (typeof name !== "string") throw new TypeError("name must be a string");
  if (typeof email !== "string") throw new TypeError("email must be a string");
  if (!isWhole(tokenVersion) || tokenVersion < 0) throw new RangeError("tokenVersion must be a whole number, 0 or more");
  if (typeof jti !== "string" || jti.length === 0) throw new TypeError("jti must be a non-empty string");
  if (!isWhole(now)) throw new TypeError("now must be a whole number of Unix seconds");
  if (!isWhole(ttlSeconds) || ttlSeconds < 1) throw new RangeError("ttlSeconds must be a whole number of at least 1");
  const exp = now + ttlSeconds;
  const expiresAt = unixToIso(exp);
  const accessToken = signJwt({ sub: subject, name, email, ver: tokenVersion, jti, iat: now, exp }, secret);
  return { accessToken, tokenType: "Bearer", expiresAt, expiresIn: ttlSeconds };
}

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

import { type AccessCheck, type AccessError } from "./auth_access_token_types.ts";
import { parseBearerToken } from "./auth_bearer_token.ts";  ← from auth.bearer-token ^1.0.0 · built alongside by fune
import { checkJwtSecret } from "./auth_jwt_decode_jwt.ts";
import { verifyJwt } from "./auth_jwt_verify_jwt.ts";
import { unixToIso } from "./time_unix_to_iso.ts";  ← from time.unix-to-iso ^1.0.0 · built alongside by fune

/** The latest second time.unix-to-iso can write. */
const MAX_EXP = 253402300799;

/** A failed check: every field but the reason is null. */
export function accessDenied(error: AccessError, message: string): AccessCheck {
  return { ok: false, subject: null, tokenVersion: null, jti: null, expiresAt: null, claims: null, error, message };
}

function isWhole(value: unknown): value is number {
  return typeof value === "number" && Number.isInteger(value);
}

/**
 * Who is making this request? The Bearer token from the Authorization
 * header, verified (signature, algorithm, exp, nbf, iat), and required to
 * carry the claims issueAccessToken writes. A missing or bad token is an
 * answer (401), never an exception.
 */
export function readAccessToken(authorization: string | null, secret: readonly number[], now: number, leewaySeconds: number): AccessCheck {
  checkJwtSecret(secret);
  if (!isWhole(now)) throw new TypeError("now must be a whole number of Unix seconds");
  if (!isWhole(leewaySeconds) || leewaySeconds < 0) throw new RangeError("leewaySeconds must be a whole number, 0 or more");

  const token = parseBearerToken(authorization);
  if (token === null) return accessDenied("missing_token", "the request has no Bearer token");
  const verified = verifyJwt(token, secret, now, leewaySeconds);
  if (!verified.valid || verified.claims === null) {
    return accessDenied(verified.error ?? "malformed_token", verified.message ?? "the token is not a well-formed JWT");
  }
  const claims = verified.claims;
  const { sub, jti, ver, exp } = claims as Record<string, unknown>;
  if (
    typeof sub !== "string" || sub.length === 0 ||
    typeof jti !== "string" || jti.length === 0 ||
    !isWhole(ver) || ver < 0 ||
    !isWhole(exp) || exp < 0 || exp > MAX_EXP
  ) {
    return accessDenied("invalid_claims", "the token lacks the sub, jti, ver or exp this API issues");
  }
  return { ok: true, subject: sub, tokenVersion: ver, jti, expiresAt: unixToIso(exp), claims, error: null, message: null };
}

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

import { type AccessCheck } from "./auth_access_token_types.ts";
import { accessDenied } from "./auth_access_token_read_access_token.ts";  ← readAccessToken, another function of this group · built into the same file, even by a slim install

/**
 * The last word on a token readAccessToken accepted, once the caller has
 * looked up the user and the revoked list: a logged-out token, or one
 * issued before the user's token version was bumped (a password change),
 * no longer stands.
 */
export function confirmAccessToken(check: AccessCheck, currentTokenVersion: number | null, revoked: boolean): AccessCheck {
  if (typeof check !== "object" || check === null) throw new TypeError("check must be an AccessCheck");
  if (currentTokenVersion !== null && (typeof currentTokenVersion !== "number" || !Number.isInteger(currentTokenVersion))) {
    throw new TypeError("currentTokenVersion must be a whole number or null");
  }
  if (typeof revoked !== "boolean") throw new TypeError("revoked must be true or false");
  if (!check.ok) return check;
  if (currentTokenVersion === null) return accessDenied("user_not_found", "the token's user no longer exists");
  if (revoked) return accessDenied("token_revoked", "the token has been revoked by logging out");
  if (check.tokenVersion !== currentTokenVersion) {
    return accessDenied("token_revoked", "the token was issued before the user's tokens were revoked (password changed)");
  }
  return check;
}