auth.provider API
    Preparing search index...

    auth.provider API

    auth.provider

    CI npm codecov API Docs License

    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.

    • 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
    npx @o3co/create-auth-provider my-auth-app
    cd my-auth-app
    pnpm install
    pnpm build

    ┌──────────────────────────────────────────┐
│             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.
    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
    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

    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.

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

    npx @o3co/create-auth-provider my-auth-app
    cd my-auth-app
    docker build -t my-auth .
    • 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

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

    Settings

    Member Visibility

    On This Page

    auth.provider