SIMPLE_JWT

API Reference

Class Overview

SIMPLE_JWT provides JWT creation, verification, and decoding using the HS256 (HMAC-SHA256) algorithm.

Creation

create jwt.make ("your-secret-key")

Initialize JWT handler with a secret key for HMAC signing.

Contracts

require: secret_not_void: a_secret /= Void
require: secret_not_empty: not a_secret.is_empty
ensure: secret_set: secret = a_secret
ensure: algorithm_hs256: algorithm.same_string ("HS256")

Token Creation

create_token (a_claims: JSON_OBJECT): STRING

token := jwt.create_token (claims)

Create a JWT with the given claims as payload.

Contracts

require: claims_not_void: a_claims /= Void
ensure: result_not_void: Result /= Void
ensure: has_three_parts: Result.occurrences ('.') = 2

create_token_with_claims (a_subject, a_issuer: detachable STRING; a_expiration_seconds: INTEGER; a_custom_claims: detachable JSON_OBJECT): STRING

token := jwt.create_token_with_claims ("user", "app", 3600, custom)

Create a JWT with standard claims. Set a_expiration_seconds to 0 for no expiration.

Automatically sets iat (issued at) to current time.

Contracts

ensure: result_not_void: Result /= Void

Token Verification

verify (a_token: STRING): BOOLEAN

if jwt.verify (token) then ...

Verify the token's signature is valid. Does NOT check expiration.

Contracts

require: token_not_void: a_token /= Void

verify_with_expiration (a_token: STRING): BOOLEAN

if jwt.verify_with_expiration (token) then ...

Verify the token's signature AND check that it hasn't expired.

Contracts

require: token_not_void: a_token /= Void

is_expired (a_token: STRING): BOOLEAN

if jwt.is_expired (token) then ...

Check if the token has expired. Returns False if no exp claim exists.

Contracts

require: token_not_void: a_token /= Void

Token Decoding

decode_claims (a_token: STRING): detachable JSON_OBJECT

claims := jwt.decode_claims (token)

Decode and return the payload claims as a JSON object. Returns Void if malformed.

Contracts

require: token_not_void: a_token /= Void

decode_header (a_token: STRING): detachable JSON_OBJECT

header := jwt.decode_header (token)

Decode and return the header as a JSON object.

Contracts

require: token_not_void: a_token /= Void

get_claim (a_token, a_claim_name: STRING): detachable JSON_VALUE

value := jwt.get_claim (token, "sub")

Get a specific claim as a JSON value.

Contracts

require: token_not_void: a_token /= Void
require: claim_name_not_void: a_claim_name /= Void

get_string_claim (a_token, a_claim_name: STRING): detachable STRING

subject := jwt.get_string_claim (token, "sub")

Get a string claim. Returns Void if claim doesn't exist or isn't a string.

Contracts

require: token_not_void: a_token /= Void
require: claim_name_not_void: a_claim_name /= Void

get_integer_claim (a_token, a_claim_name: STRING): INTEGER_64

exp := jwt.get_integer_claim (token, "exp")

Get an integer claim. Returns 0 if claim doesn't exist or isn't a number.

Contracts

require: token_not_void: a_token /= Void
require: claim_name_not_void: a_claim_name /= Void

Token Parts

extract_header (a_token: STRING): STRING

header_b64 := jwt.extract_header (token)

Extract the Base64URL-encoded header from the token.

extract_payload (a_token: STRING): STRING

payload_b64 := jwt.extract_payload (token)

Extract the Base64URL-encoded payload from the token.

extract_signature (a_token: STRING): STRING

sig_b64 := jwt.extract_signature (token)

Extract the Base64URL-encoded signature from the token.

Class Invariants

invariant: secret_exists: secret /= Void
invariant: secret_not_empty: not secret.is_empty
invariant: algorithm_set: algorithm /= Void
invariant: base64_exists: base64 /= Void
invariant: hasher_exists: hasher /= Void