BleuAuth

A comprehensive OAuth2 Client/Server library for BleuMoon — the standalone Luau runtime.

Features

• OAuth2 Server — Authorization endpoint, token endpoint, introspection (RFC 7662), revocation (RFC 7009), and discovery (RFC 8414)
• OAuth2 Client — Authorization Code (with PKCE), Client Credentials, and Refresh Token grants
• Resource Server Middleware — Bearer token validation via JWT verification and token introspection
• JWT — Encode, decode, and verify JWTs (RFC 7519/7515/7518) with HMAC (HS256/384/512) and asymmetric (RS256/ES256/EdDSA) algorithms
• JWK/JWKS — Key pair generation and JSON Web Key Set endpoints (RFC 7517)
• PKCE — Proof Key for Code Exchange (RFC 7636) with S256 method, required by default (OAuth 2.1)
• Pluggable Storage — In-memory (testing) and SQLite (production) storage backends

Prerequisites

• BleuMoon v2.0.1 or later
• StyLua (for code formatting)

Tip: If you have Nix with flakes enabled, both tools are provided automatically via nix develop.

Quick Start

local bleuauth = require("./src")

-- Create an in-memory storage backend
local storage = bleuauth.createMemoryStorage()

-- Generate an RSA key pair for JWT signing
local keys = bleuauth.generateKeyPair("RS256")

-- Register a client
storage:createClient({
    clientId = "my-app",
    clientSecret = "secret",
    redirectUris = { "https://myapp.example.com/callback" },
    grantTypes = { "authorization_code", "client_credentials" },
    scopes = { "read", "write" },
    clientType = "confidential",
    createdAt = os.time(),
})

-- Create and start the OAuth2 server
local server = bleuauth.createServer({
    issuer = "https://auth.example.com",
    storage = storage,
    signingKey = keys.privateKey,
    signingAlgorithm = "RS256",
    signingKid = keys.kid,
    publicKey = keys.publicKey,
    supportedScopes = { "read", "write" },
    authenticateUser = function(request, clientId, scope)
        -- Your user authentication logic here
        return "user-id-123"
    end,
})

server:start(8080)

Architecture

src/
├── init.luau              # Library entry point (exports everything)
├── types/init.luau        # All shared type definitions
├── utils/
│   ├── init.luau          # Utility re-exports
│   ├── pkce.luau          # PKCE utilities (RFC 7636)
│   └── errors.luau        # OAuth2 error builders (RFC 6749 §5.2)
├── jwt/
│   ├── init.luau          # JWT encode/decode/verify
│   ├── algorithms.luau    # Algorithm implementations
│   └── jwk.luau           # JWK/JWKS key management
├── server/
│   ├── init.luau          # Server factory with HTTP binding
│   ├── config.luau        # Configuration defaults & validation
│   ├── authorize.luau     # Authorization endpoint (GET /authorize)
│   ├── token.luau         # Token endpoint (POST /token)
│   ├── introspect.luau    # Introspection endpoint (POST /introspect)
│   ├── revoke.luau        # Revocation endpoint (POST /revoke)
│   └── discovery.luau     # Metadata & JWKS endpoints
├── client/init.luau       # OAuth2 client implementation
├── middleware/init.luau    # Resource server middleware
└── storage/
    ├── init.luau          # Storage re-exports
    ├── memory.luau        # In-memory storage (testing)
    └── sqlite.luau        # SQLite storage (production)

Note: Base64url encoding and URL/form encoding utilities live in the bleuutils package and are re-exported from there.

Supported Grant Types

Grant Type	RFC	Description
Authorization Code	RFC 6749 §4.1	For server-side web apps (with mandatory PKCE)
Client Credentials	RFC 6749 §4.4	For machine-to-machine communication
Refresh Token	RFC 6749 §6	For obtaining new access tokens

Note: Implicit grant and ROPC are intentionally omitted per OAuth 2.1 recommendations.

JWT Algorithms

Algorithm	Type	Status
HS256 / HS384 / HS512	HMAC	✅ Fully working
RS256	RSA-SHA256	✅ Fully working
ES256	ECDSA P-256	✅ Fully working
EdDSA	Ed25519	✅ Fully working

Running Tests

bleumoon run tests/init

Formatting

stylua --check .   # Check
stylua .           # Apply

Known Issues

• crypto.randomBuffer() returns a string (not a buffer type) in BleuMoon v2.0.x. BleuAuth uses crypto.randomBytes() instead.

License

This project is licensed under the MIT License.