util — Code View¶
← Back to Container | ← Back to System
Component Information¶
| Field | Value |
|---|---|
| Component | util |
| Container | @chrislyons-dev/flarelette-jwt |
| Type | module |
| Description | High-level JWT utilities for creating, delegating, verifying, and authorizing JWT tokens | Key generation utility for EdDSA and ECDSA keys. Generates asymmetric key pairs and exports them in JWK format. Designed to be executed as a standalone Node.js script. | Secret generation and validation utilities. This module provides functions to generate secure secrets and validate base64url-encoded secrets. It ensures compatibility with JWT signing requirements. | Utility functions for JWT operations. This module provides helper functions for parsing JWTs, checking expiration, and mapping OAuth scopes. It is designed to support core JWT functionalities. |
| --- |
Code Structure¶
Class Diagram¶
Code Elements¶
13 code element(s)
#### Functions ##### `createToken()` Create a signed JWT token with optional claims | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Async** | Yes || **Returns** | `Promiseimport("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/types").JwtPayload — - Claims to include in the token (can include custom claims beyond standard JWT fields)- `opts`: Partial<{ iss: string; aud: string | string[]; ttlSeconds: number; }> — - Optional overrides for iss, aud, ttlSeconds --- ##### `createDelegatedToken()` Create a delegated JWT token following RFC 8693 actor claim pattern Mints a new short-lived token for use within service boundaries where a service acts on behalf of the original end user. This implements zero-trust delegation: - Preserves original user identity (sub) and permissions - Identifies the acting service via 'act' claim - Prevents permission escalation by copying original permissions Pattern: "I'm import("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/types").JwtPayload — - The verified JWT payload from external auth (e.g., Auth0)- `actorService`: string — - Identifier of the service creating this delegated token- `opts`: Partial<{ iss: string; aud: string | string[]; ttlSeconds: number; }> — - Optional overrides for iss, aud, ttlSeconds **Examples:** --- ##### `signWithRequestBinding()` Sign a JWT token bound to a specific HTTP request. Adds a `req` claim containing base64url(SHA-256(canonical request)) to prevent replay of a captured token against a different endpoint within the TTL window. Canonical form: METHOD + "\n" + pathname + search + "\n" + body bytes | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Async** | Yes || **Returns** | `Promiseimport("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/types").JwtPayload — - Claims to include in the token- `request`: Request — - The HTTP request this token is minted for- `opts`: Partial<{ iss: string; aud: string | string[]; ttlSeconds: number; }> — - Optional overrides for iss, aud, ttlSeconds --- ##### `verifyWithRequestBinding()` Verify a JWT token and validate its request binding. Re-computes the request hash and compares it with the `req` claim. Returns null on any mismatch (fail-silent, same as verify()). The `req` claim is stripped from the returned payload — it's an implementation detail that has already been validated. | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Async** | Yes || **Returns** | `Promisestring — - JWT token string to verify- `request`: Request — - The HTTP request to validate against- `opts`: Partial<{ iss: string; aud: string | string[]; leeway: number; jwksService: import("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/types").Fetcher; }> — - Optional overrides for iss, aud, leeway --- ##### `checkAuth()` Verify and authorize a JWT token with policy enforcement | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Async** | Yes || **Returns** | `Promisestring — - JWT token string to verify- `opts`: import("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/high").AuthzOpts — - Authorization options including verification and policy requirements --- ##### `policy()` Fluent builder for creating authorization policies | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Returns** | `{ base(b: Partial<{ iss: string; aud: string \| string[]; leeway: number; }>): any; needAll(...perms: string[]): any; needAny(...perms: string[]): any; rolesAll(...roles: string[]): any; rolesAny(...roles: string[]): any; where(fn: (payload: import("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/types").JwtPayload) => boolean): any; build(): import("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/high").AuthzOpts; }` - Policy builder with chainable methods || **Location** | `C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/high.ts:234` | --- ##### `main()` | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `private` | | **Async** | Yes || **Returns** | `Promisenumber --- ##### `isValidBase64UrlSecret()` | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Returns** | `boolean` || **Location** | `C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/secret.ts:25` | **Parameters:** - `s`: string- `minBytes`: number --- ##### `parse()` Parse a JWT token into header and payload without verification | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Returns** | `import("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/types").ParsedJwt` - Parsed header and payload || **Location** | `C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/util.ts:19` | **Parameters:** - `token`: string — - JWT token string --- ##### `isExpiringSoon()` Check if JWT payload will expire within specified seconds | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Returns** | `boolean` - True if token expires within the threshold || **Location** | `C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/util.ts:35` | **Parameters:** - `payload`: import("C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/types").JwtPayload — - JWT payload with 'exp' claim- `seconds`: number — - Number of seconds threshold --- ##### `mapScopesToPermissions()` Map OAuth scopes to permission strings | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Returns** | `string[]` - List of permission strings (currently identity mapping) || **Location** | `C:/Users/chris/git/flarelette-jwt-kit/packages/flarelette-jwt-ts/src/util.ts:47` | **Parameters:** - `scopes`: string[] — - List of OAuth scope strings --- ##### `computeRequestHash()` Compute a deterministic SHA-256 hash that binds a JWT to a specific HTTP request. Canonical form: UTF-8(METHOD + "\n" + pathname + search + "\n") || body_bytes - Method is uppercased - Binds to path and query string only (not host/scheme — internal Workers use different hostnames) - Body is consumed from a clone to preserve the original stream | Field | Value | | --- | --- | | **Type** | `function` | | **Visibility** | `public` | | **Async** | Yes || **Returns** | `PromiseRequest — - Fetch API Request object ---