auth.provider

This repository handles authentication and token issuance in the three-layer separation of concerns (authentication & token issuance / authorization decision / authorization enforcement) of the auth stack.

OAuth 2.0 / OIDC provider. Issue JWTs via session-based login or the authorization code flow — same token format, same introspection endpoint, same downstream verification.

Features

• Modular composition — Pick only the modules you need. Skip session, federation, or authorization code for API-only deployments.
• JWT algorithm selection — HS256, RS256, ES256, EdDSA. JWKS endpoint (/.well-known/jwks.json) for asymmetric algorithms.
• OAuth 2.0 compliance — Authorization code flow with PKCE (RFC 7636), token introspection (RFC 7662), refresh tokens
• Session authentication — Local username/password login + OAuth federation (Google, GitHub, and custom providers via per-federation defineModule(...) modules)
• Rate limiting — Per-endpoint configurable limits
• HOCON configuration — Type-safe config with Zod validation and environment variable overrides

Quick Start

npx @o3co/create-auth-provider my-auth-app
cd my-auth-app
pnpm install
pnpm build

Architecture

┌──────────────────────────────────────────┐
│             Composition Root              │
│  (standalone template or your own app)   │
├─────────┬───────────┬────────────────────┤
│  oauth  │  session  │    foundation      │
│ /oauth  │ /session  │  Redis, HTTP       │
│ routes  │  routes   │  adapters          │
├─────────┴───────────┴────────────────────┤
│                   core                    │
│  GrantRegistry · KeyStore · Repositories │
└──────────────────────────────────────────┘

• core — Interfaces, config schemas, token service, app factory. Always required.
• oauth — OAuth routes (/oauth/token, /oauth/authorize, /oauth/introspect). Required for any token issuance.
• session — Session login + provider-registered OAuth federation. Optional — skip for API-only deployments.
• federation-google / federation-github — Concrete OAuth federation providers. Optional — install only the providers you register.
• foundation — Production repository adapters (Redis code store, HTTP user lookup). Optional.

Packages

Package	npm	Description
packages/core	@o3co/auth-provider-core	Grant registry, token service, repository interfaces, config schemas
packages/oauth	@o3co/auth-provider-oauth	OAuth routes: /oauth/token, /oauth/authorize, /oauth/introspect
packages/session	@o3co/auth-provider-session	Session routes and provider-registered OAuth federation
packages/federation-google	@o3co/auth-provider-federation-google	Google OAuth/OIDC federation provider
packages/federation-github	@o3co/auth-provider-federation-github	GitHub OAuth federation provider
packages/foundation	@o3co/auth-provider-foundation	Redis code store, HTTP user/client repositories
templates/standalone	—	Deployable server template (composition root)
create-app	@o3co/create-auth-provider	CLI scaffolder

Endpoints

Endpoint	Module	Description
POST /oauth/token	oauth	Token issuance (session, authorization code, refresh)
GET /oauth/authorize	oauth	Authorization code flow (PKCE)
POST /oauth/introspect	oauth	Token introspection (RFC 7662)
GET /.well-known/jwks.json	core	JWKS endpoint (asymmetric algorithms only)
POST /session/login	session	Local authentication
POST /session/logout	session	Session destruction
GET /_healthcheck	core	Health check

Configuration

HOCON config file with environment variable overrides. The config schema depends on which modules are registered:

Core (always required):

http { port = 3000 }
oauth {
  jwt {
    issuer = ${?OAUTH_JWT_ISSUER}
    signingKey {
      provider = "local"           # "local" is the only built-in; extend via KeyStoreFactory
      local {
        algorithm = "HS256"        # HS256 | RS256 | ES256 | EdDSA
        secret = ${?OAUTH_JWT_SECRET}
        # For asymmetric: privateKey/privateKeyPath + publicKey/publicKeyPath
      }
    }
  }
  accessToken { expiresIn = 3600 }
  refreshToken { expiresIn = 86400 }
}

Authorization code grant (when oauthAuthorizationModule is registered):

oauth.grants.authorization_code {
  pkce {
    requireS256 = false   # Set to true to reject plain code_challenge_method (S256 only)
    requireS256 = ${?OAUTH_GRANTS_AUTHORIZATION_CODE_PKCE_REQUIRE_S256}
  }
}

Session (when sessionModule is registered):

session { secret = ${SESSION_SECRET} }

# Shorthand: key name = provider type (google, github, or any registered custom type)
federations {
  google {
    enabled = false
    # clientId, clientSecret, callbackURL — required when enabled = true
  }
  # github { enabled = false }
}

See templates/standalone/config/application.conf for a complete example.

Development

pnpm install
pnpm -r build     # build all packages
pnpm -r test      # test all packages

Docker

npx @o3co/create-auth-provider my-auth-app
cd my-auth-app
docker build -t my-auth .

Related Projects

• auth.policy-verifier — ABAC policy engine for authorization decisions
• auth.proxy — Token validation reverse proxy
• protobuf.interceptors — protobuf-option-driven authorization interceptors for gRPC / ConnectRPC (calls auth.provider for introspection, auth.policy-verifier for authorization)
• auth — Architecture docs and E2E tests

License

Apache License 2.0 — Copyright 2026 1o1 Co. Ltd.