Auth for apps and agents. Server-side sessions, OIDC discovery, encrypted cookies. Any OIDC provider. No vendor lock-in.

import { Hono } from 'hono'
import { createBffRoutes, requiresAuth } from 'fz-auth'
const app = new Hono()
app.route('/auth', await createBffRoutes({
 issuerUrl: process.env.ISSUER_URL!,
 clientId: process.env.CLIENT_ID!,
 encryptionKey: process.env.SESSION_SECRET!,
}))
app.get('/api/me', requiresAuth({ encryptionKey: process.env.SESSION_SECRET! }), (c) => {
 return c.json({ message: 'Authenticated!' })
})
export default app

That's a working auth server. SESSION_SECRET is a 32-byte hex key (openssl rand -hex 32). The issuerUrl is any OIDC provider — Google, Auth0, Keycloak, Ory, Cognito.

Browser → GET /auth/login → redirect to IdP (Google, Auth0, etc.)
User authenticates at the IdP
IdP → GET /auth/callback?code=X → server exchanges code for tokens
Server sets encrypted httpOnly cookie → redirect to app
Browser → GET /api/me (cookie sent automatically) → server decrypts, returns data

Tokens never reach the browser. This is the BFF pattern — the IETF-recommended approach for browser-based OAuth2.

• Any OIDC provider — endpoints discovered automatically via .well-known/openid-configuration
• No tokens in browser — httpOnly, Secure, SameSite=Lax, __Host- prefix cookies
• No database required — sessions stored in AES-256-GCM encrypted cookies
• Pluggable crypto — swap in AWS KMS, Vault, or any custom backend via SessionCrypto interface
• Rolling sessions — rollingDuration resets session expiry on activity
• Agent identity — API keys with agentId for non-human audit trails
• OIDC discovery — one issuerUrl, works with Google, Auth0, Keycloak, Ory, Cognito
• Silent refresh — server-side refresh token rotation, no user interaction

# Generate a session encryption key
openssl rand -hex 32
# Install
npm install fz-auth
# For React apps
npm install fz-auth-react
# For AWS KMS encryption (production)
npm install fz-auth-aws

The ory/ directory contains a production-ready Ory Kratos + Hydra configuration:

cd ory && docker compose up -d

This gives you a full identity provider on localhost with password login, email verification, and OAuth2 — ready for fz-auth to connect to.

fz-auth-core ← OIDC discovery, PKCE, session crypto (no framework dependency)
fz-auth ← Hono adapter: routes + middleware (~160 lines of glue)
fz-auth-react ← React AuthProvider + useAuth (~100 lines)
fz-auth-aws ← AWS KMS envelope encryption (~110 lines)

The core is framework-agnostic. The Hono adapter is thin. Building an Express or Fastify adapter means writing ~160 lines of cookie/redirect glue over createBffCore().

• Per IETF draft-ietf-oauth-browser-based-apps-26 §6.1 (BFF pattern)
• Per RFC 9700 (OAuth 2.0 Security BCP)
• AES-256-GCM with random IV per encryption
• __Host- cookie prefix (Secure, no Domain, Path=/)
• Pluggable SessionCrypto for KMS/Vault/HSM backends
• PKCE (S256) on all authorization flows
• No tokens in localStorage or sessionStorage

Apache 2.0