Xentitlement — Shared RSA-signed entitlement token library for distributed services.

This library provides a reusable entitlement system for validating cryptographically signed tokens across multiple applications. An entitlement is a JSON document signed with RSA-SHA256 that carries authorization metadata (user ID, operation type, resource constraints, expiration, etc.).

Usage

Validate a token received via HTTP header:

case Xentitlement.validate(token_json, public_key_pem, entitlement_id) do
  {:ok, claims} -> handle_authorized_request(claims)
  {:error, reason} -> reject_request(reason)
end

Extract the token from an HTTP header (e.g., X-Entitlement):

case Xentitlement.extract_from_header(conn) do
  {:ok, token} -> validate_token(token)
  {:error, _} -> reject_no_header()
end

Token Format

An entitlement token is a JSON object with these fields:

{
  "entitlement_id": "967376a7-6a33-4bc8-846c-ca443c5c56eb",
  "user_id": "user-123",
  "operation": "file_upload",
  "expires_at": "2026-12-31",
  "signature": "base64-encoded-rsa-sha256-signature",
  ...additional business fields...
}

The signature is computed over the canonical JSON representation (all fields except "signature", sorted by key). This ensures that the token payload cannot be tampered with without detection.

Key Functions

• validate/3 — Core validation function (signature + entitlement ID check)
• extract_from_header/2 — Extract token from HTTP header (e.g., X-Entitlement)