shelving/util/jwtmodule

Encode, decode, and verify JSON Web Tokens signed with HMAC SHA-512. Also provides convenience helpers for reading and writing Bearer tokens on Request objects.

Things to know:

  • Only HMAC SHA-512 (HS512) is supported — the algorithm is fixed.
  • Secrets must be at least 64 bytes (512 bits); shorter values throw ValueError.
  • exp defaults to 30 days from "now"; nbf and iat both default to "now".
  • Verification allows a 1-minute clock skew for nbf/exp.
  • Expired or tampered tokens throw UnauthorizedError, not a generic error.

Usage

Signing and verifying tokens

ts
import { encodeToken, verifyToken } from "shelving/util";

const secret = crypto.getRandomValues(new Uint8Array(64));

// Create a token with custom claims.
const token = await encodeToken({ sub: "user_123", role: "admin" }, secret);

// Verify and decode — returns the payload as Data.
const payload = await verifyToken(token, secret);
// { sub: "user_123", role: "admin", nbf: ..., iat: ..., exp: ... }

Parsing a token without verifying

ts
import { splitToken } from "shelving/util";

const { headerData, payloadData } = splitToken(token);

Working with Bearer tokens on requests

ts
import {
  setRequestToken,
  getRequestToken,
  requireRequestToken,
  verifyRequestToken,
} from "shelving/util";

// Attach a token to an outgoing request.
setRequestToken(request, token);

// Read the raw token string from an incoming request (or undefined).
const raw = getRequestToken(request);

// Read and verify in one step — throws UnauthorizedError if missing or invalid.
const claims = await verifyRequestToken(request, secret);

Functions

Go

encodeToken()function

Encode a JWT and return the string token.

encodeToken({ nbf = "now", iat = "now", exp = DAY * 30, ...claims }: TokenClaims, secret: PossibleBytes): Promise<string>
Go

splitToken()function

Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.

splitToken(token: string, caller: AnyCaller = splitToken): TokenData
Go

verifyToken()function

Decode a JWT, verify it, and return the full payload data.

verifyToken(token: string, secret: PossibleBytes, caller: AnyCaller = verifyToken): Promise<Data>
Go

setRequestToken()function

Set the Authorization: Bearer {token} on a Request object (by reference).

setRequestToken(request: Request, token: string): Request
Go

getRequestToken()function

Extract the Authorization: Bearer {token} from a Request object, or return undefined if not set.

getRequestToken(request: Request): string | undefined
Go

requireRequestToken()function

Extract the Authorization: Bearer {token} from a Request object, or throw UnauthorizedError if not set or malformed.

requireRequestToken(request: Request, caller: AnyCaller = requireRequestToken): string
Go

verifyRequestToken()function

Extract the Authorization: Bearer {token} from a Request object and verify it using a signature, or throw UnauthorizedError if not set, malformed, or invalid.

verifyRequestToken(request: Request, secret: PossibleBytes, caller: AnyCaller = verifyRequestToken): Promise<Data>

Interfaces

Go

TokenClaimsinterface

Claims payload accepted when encoding a JWT.

{
	readonly iat?: PossibleDate;
	readonly nbf?: PossibleDate;
	readonly exp?: number;
}

Types

Go

TokenDatatype

Parts that make up a JSON Web Token — the raw encoded segments plus their decoded contents.

{
	header: string;
	payload: string;
	signature: string;
	headerData: Data;
	payloadData: Data;
	signatureBytes: Bytes;
}