FoxAuth

OAuth-server.ts Source-available OAuth 2.0 and OpenID Connect authorization server — built with Bun and TypeScript.

Website · Features · Docs · Compare · OAuth 2.0 · OpenID Connect · Bun · FSL-1.1-ALv2 License

---

OAuth-server.ts is a source-available (FSL-1.1-ALv2), standards-compliant authorization server written in TypeScript and powered by Bun and Elysia. It implements OAuth 2.0 and OpenID Connect from the ground up, giving you complete control over your identity infrastructure — with no vendor lock-in.

Features

Most protocol capabilities are governed by a named feature flag, and a flag that is off means the capability's endpoint is not served at all. So this list is split by what you get on a default install versus what you switch on deliberately — the distinction is load-bearing, not editorial.

Out of the box

• Authorization Code flow with PKCE — PKCE is mandatory for every client, public or confidential, per OAuth 2.1
• OpenID Connect — OIDC Core 1.0 with ID tokens, UserInfo endpoint, and discovery
• Authorization-response issuer identification — iss on every authorization response (RFC 9207)
• Resource Indicators — audience-restricted tokens via resource (RFC 8707)
• Refresh Token grant — with rotation and reuse detection; offered while offline_access is among the supported scopes, which it is by default
• RP-initiated logout — by GET or form POST, with a confirmation step
• JWT tokens — access and ID tokens signed with the algorithms your key store holds; bun run db:setup provisions an initial RS256 key, and ES256 and EdDSA keys are supported. Keys live in the database, are generated on first run, and are published at /jwks — and each project with an address of its own publishes its own at its own jwks_uri
• Database-backed clients — clients live in this server's own store and are created through the admin API, dynamic registration, or bun run db:setup. There is no static client configuration file
• Administration console — projects, teams, OAuth clients and APIs, administrators, end-users and their groups, upstream identity providers, SCIM provisioning connections, settings, SMTP, signing keys and an append-only audit trail
• End-user self-service — email verification and password reset, each with per-identity attempt and cooldown caps
• TOTP second factor — per-project, optionally enforced for the admin console (RFC 6238)
• Pairwise subject identifiers — per-sector sub values, salted from the database
• Per-origin rate limiting — tiered by route class, on by default
• Sign-in brute-force throttle — persisted per-address failure counters with escalating lockouts, and no way to tell a throttled refusal from a wrong password
• Security headers — HSTS, Permissions-Policy, framing and content-type protections
• CORS closed by data — an origin is readable only if it is listed on the project owning the calling client
• Pluggable storage — adapter architecture with MongoDB, PostgreSQL and in-memory implementations
• Consent & login UI — built-in authentication and consent screens (React + Ant Design)
• Scope-based access control — fine-grained, per-client scope enforcement
• Extensible — 31 named behaviour seams (account lookup, interaction policy, refresh-token rotation, resource resolution, pairwise identifiers, RAR handling and more) replaced at call time via addons.override()

Opt-in capabilities

Implemented, and off until the flag is set. Set them in the console under Settings or on ApplicationConfig; a change saved in the console applies at once.

Quick Start

With Docker Compose

Prerequisites: Docker with Compose v2.

curl -O https://raw.githubusercontent.com/RedFox-Soft/OAuth-server.ts/main/docker-compose.yml

docker compose up

That starts MongoDB, provisions the schema and the admin panel (an idempotent one-shot step), and serves the server at http://localhost:3000. Open http://localhost:3000/admin — the first visit shows a one-time setup screen that creates the initial super administrator. Discovery is at http://localhost:3000/.well-known/openid-configuration. Set ISSUER in docker-compose.yml to its final public URL before this first docker compose up: the seeded admin client's redirect URI is derived from it once, and a later change is not repaired by re-running setup.

Images are published to ghcr.io/redfox-soft/oauth-server-ts on every release, tagged with the version and latest. To upgrade, pull and run docker compose up again; the setup step re-runs and is safe to repeat.

From source

Prerequisites: Bun v1.3+ and a running MongoDB or PostgreSQL instance.

git clone https://github.com/RedFox-Soft/OAuth-server.ts.git

cd OAuth-server.ts bun install

Create .env — set MONGODB_URI, DATABASE_NAME, and ISSUER (see Configuration)

bun run db:setup # collections, indexes, initial RS256 signing key, admin panel seed bun run build # bundles the console and sign-in screens into public/ bun start # http://localhost:3000

Schema provisioning creates the initial signing key, so no key configuration is required. If the server ever starts against an empty key store it also generates and persists one automatically.

Admin panel provisioning

bun run db:setup also provisions the admin panel: the reserved "Administrators" project and the first-party admin-panel OAuth client. The seed is idempotent — re-run `bun run db:setup` after upgrading an existing install so the admin client and project exist. On first visit to /admin, a one-time setup screen creates the first administrator and makes them a member of Super administrators; the setup route is closed once that team has an active member. The admin panel requires a database-backed deployment, MongoDB or PostgreSQL (the in-memory adapter does not persist seeded data across resta