Kitto.Web.JWT

JWT runtime infrastructure for KittoX authentication. Wraps the delphi-jose-jwt library (paolo-rossi) with KittoX-specific configuration parsing, key resolution, claims construction, validation and cookie issuance helpers.

EKJWTError class

Exception type raised for JWT configuration and key-resolution errors.

TKJWTAclEntry record

Single ACL row carried by the kx_acl claim. Mirrors the three columns of the KITTO_PERMISSIONS table the DB access controller reads: Pattern — RESOURCE_URI_PATTERN (wildcards * ?, REGEX:, ~ negation) Modes — comma-separated list of ACM_* mode codes (V/M/E/A/D/R) GrantValue — '0' / '1' for boolean grants, any string for non-standard modes Serialised in the JWT as a 3-element JSON array [pattern, modes, grant].

TKJWTContext record

Strongly-typed view of validated JWT claims used by the KittoX runtime. Populated by TKJWTValidator on a successful Validate call.

procedure Clear;

Resets all fields to empty/invalid.

function HasRole(const ARole: string): Boolean;

True if the Roles list contains ARole (case-insensitive).

TKJWTSigningKey record

Resolved signing material. For HS* algorithms only PrivateKey is used. For RS*/ES* PrivateKey is the PEM private key, PublicKey is the PEM public key (verifier-only deploys can configure PublicKey alone).

function HasPrivateKey: Boolean;

True if a private (or symmetric) key is present.

function HasPublicKey: Boolean;

True if a public key is present (asymmetric verifier).

function IsSymmetric: Boolean;

True for symmetric (HS*) algorithms.

procedure Clear;

Zeroes and clears the key material.

TKJWTSigningKeyRegistry class

Process-wide registry of signing key providers, scoped by app name.

procedure RegisterProvider(const AAppName: string;

Registers a signing-key provider for the given app name (replaces any existing).

procedure UnregisterProvider(const AAppName: string);

Removes the signing-key provider registered for the given app name.

function FindProvider(const AAppName: string): TKJWTSigningKeyProvider;

Returns the provider registered for the app name, or nil.

TKJWTConfig class

Parsed configuration extracted from the Auth/JWT YAML node.

constructor Create(const AAppName: string;

Parses the Auth/JWT config node for the given app.

property AppName: string read FAppName;

The application name this config belongs to.

property Algorithm: TJOSEAlgorithmId read FAlgorithm;

The JOSE signing algorithm (HS256, RS256, …).

property Issuer: string read FIssuer;

Expected/emitted 'iss' (issuer) claim.

property Audience: string read FAudience;

Expected/emitted 'aud' (audience) claim.

property TokenLifetimeSeconds: Integer read FTokenLifetimeSeconds;

Token lifetime in seconds (exp = iat + this).

property SlidingThresholdSeconds: Integer read FSlidingThresholdSeconds;

Remaining-lifetime threshold (seconds) below which the cookie is slid/refreshed.

property MaxSessionLifetimeSeconds: Integer read FMaxSessionLifetimeSeconds;

Absolute cap (seconds) on the total session length: past this, sliding stops renewing the token and a fresh login is required. 0 = no cap. Default DEFAULT_MAX_SESSION_LIFETIME (12h).

property ClockSkewSeconds: Integer read FClockSkewSeconds;

Allowed clock skew (seconds) when validating exp/nbf.

property CookieName: string read FCookieName;

Name of the cookie carrying the token (default 'kx_token').

property CookiePath: string read FCookiePath write FCookiePath;

Cookie Path attribute.

property CookieSecure: Boolean read FCookieSecure;

Cookie Secure attribute.

property CookieHttpOnly: Boolean read FCookieHttpOnly;

Cookie HttpOnly attribute.

property CookieSameSite: string read FCookieSameSite;

Cookie SameSite attribute ('Strict'/'Lax'/'None'/'').

property IncludeRoles: Boolean read FIncludeRoles;

Include the user's roles as a claim.

property IncludeDB: Boolean read FIncludeDB;

Include the active database name as a claim ('db').

property IncludeDisplayName: Boolean read FIncludeDisplayName;

Include the user's display name as a claim.

property IncludeLanguage: Boolean read FIncludeLanguage;

Include the language as a claim.

property IncludeACL: Boolean read FIncludeACL;

Include the ACL grant rows as a claim (when AccessControl: JWT).

function GetSigningKey: TKJWTSigningKey;

Returns the resolved signing key (from config spec or a registered provider).

TKJWTBuilder class

Builds a compact JWT from a TKJWTContext + signing config. Stateless.

class function Build(const AContext: TKJWTContext;

Builds and signs a compact JWT from the context + config (plus any extra claims).

TKJWTValidator class

Validates a compact JWT against config + signing key. Stateless.

class function Validate(const ACompactToken: string;

Verifies the token's signature and claims against AConfig; on success fills AContext and returns True, else returns False with AErrorMessage set.

TKJWTCookieHelper class

Cookie helpers.

class procedure Issue(const ACompactToken: string;

Writes the token to the response as the configured secure cookie.

class procedure Clear(const AConfig: TKJWTConfig);

Clears (expires) the token cookie on the response.

class function ReadFromRequest(const AConfig: TKJWTConfig): string;

Reads the token from the request's configured cookie ('' if absent).

class function ShouldSlide(const AContext: TKJWTContext;

True if the token is close enough to expiry that the cookie should be re-issued (slid).

class function IsSessionCapReached(const AContext: TKJWTContext;

True when the absolute session cap is configured (>0) and the time since SessionStart has reached it: the token must no longer be slid, and is refused, so a fresh login is required.

TKJWTRevocation class

Process-wide denylist of revoked token ids (jti). Logout and password change add the current token's jti; the validator refuses a token whose jti is listed. Each entry carries the token's own expiry and is purged lazily, so the list never grows past the set of still-valid revoked tokens. v1 is single-instance: the list lives in this process only, so behind a load balancer a revocation does not propagate to other nodes.

class function Instance: TKJWTRevocation;

The process-wide singleton.

procedure Revoke(const AJti: string;

Revokes AJti until AExpiry (the token's own exp), after which the entry is dropped because a token that old would be rejected anyway.

function IsRevoked(const AJti: string): Boolean;

True if AJti is currently revoked (and not yet past its expiry).

Routines

function StringToAlgorithmId(const S: string): TJOSEAlgorithmId;

Maps an algorithm name (e.g. 'HS256') to its TJOSEAlgorithmId.

function ResolveKeySpec(const ASpec: string): TBytes;

Resolves a key spec (inline value, file: or env: reference) to raw key bytes.

function TryDecodeSidFromJWT(const ACompactToken: string;

Decodes the payload portion of a compact JWT without verifying the signature, and extracts the 'sid' custom claim if present. Used by the engine to correlate the request to a server-side TKWebSession before the JWT signature is verified by the application's auth gate. Safety: signature is still verified later before any authenticated operation, so the unsafe decode here only affects which session object is bound to the current thread — it cannot grant any privilege.