simple_jwt - JSON Web Tokens for Eiffel

Features

HS256 Algorithm - HMAC-SHA256 signing (most common)
Token Creation - Generate signed JWTs with custom claims
Token Verification - Validate signatures and expiration
Claims Decoding - Extract payload data from tokens
Design by Contract - Full preconditions and postconditions
Standards Compliant - RFC 7519 JSON Web Token

Quick Start

Installation

Add to your ECF:

<library name="simple_jwt" location="$SIMPLE_JWT\simple_jwt.ecf"/>

Dependencies (automatically included):

simple_base64 - For Base64URL encoding
simple_hash - For HMAC-SHA256 signatures
json - For JSON parsing

Create a Token

local
    jwt: SIMPLE_JWT
    token: STRING
do
    create jwt.make ("your-secret-key")

    -- Simple token with subject and expiration
    token := jwt.create_token_with_claims (
        "user@example.com",  -- subject
        "my-application",    -- issuer
        3600,                -- expires in 1 hour
        Void                 -- no custom claims
    )
    -- Result: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
end

Verify a Token

local
    jwt: SIMPLE_JWT
do
    create jwt.make ("your-secret-key")

    -- Check signature only
    if jwt.verify (token) then
        print ("Valid signature%N")
    end

    -- Check signature AND expiration
    if jwt.verify_with_expiration (token) then
        print ("Valid and not expired%N")
    end
end

Decode Claims

local
    jwt: SIMPLE_JWT
    subject: detachable STRING
    user_id: INTEGER_64
do
    create jwt.make ("secret")

    -- Get string claim
    subject := jwt.get_string_claim (token, "sub")

    -- Get integer claim
    user_id := jwt.get_integer_claim (token, "user_id")

    -- Get full claims object
    if attached jwt.decode_claims (token) as claims then
        -- Access any claim
    end
end

Custom Claims

local
    jwt: SIMPLE_JWT
    custom: JSON_OBJECT
    token: STRING
do
    create jwt.make ("secret")
    create custom.make_empty
    custom.put_string ("admin", "role")
    custom.put_integer (12345, "user_id")
    custom.put_boolean (True, "verified")

    token := jwt.create_token_with_claims (
        "admin@example.com",
        "my-app",
        7200,    -- 2 hours
        custom   -- custom claims merged in
    )
end

JWT Structure

A JWT consists of three Base64URL-encoded parts separated by dots:

header.payload.signature

Header

{"alg":"HS256","typ":"JWT"}

Payload (Claims)

Claim	Name	Description
`sub`	Subject	Who the token is about
`iss`	Issuer	Who issued the token
`iat`	Issued At	Unix timestamp of creation
`exp`	Expiration	Unix timestamp when token expires
`aud`	Audience	Intended recipient
`nbf`	Not Before	Token not valid before this time
`jti`	JWT ID	Unique token identifier

Signature

HMAC-SHA256(
    base64url(header) + "." + base64url(payload),
    secret
)

Use Cases

API Authentication - Stateless authentication for REST APIs
Single Sign-On - Share authentication across services
Information Exchange - Securely transmit claims between parties
Session Management - Alternative to server-side sessions

Security Notes

Keep your secret key secure and never expose it
Use HTTPS to transmit tokens
Set appropriate expiration times
Don't store sensitive data in the payload (it's encoded, not encrypted)
Verify tokens on every request

Specifications

RFC 7519 - JSON Web Token (JWT)
RFC 7515 - JSON Web Signature (JWS)
jwt.io - JWT Debugger and Documentation