OAuth2

Installation

bun add @strav/oauth2
bun strav install oauth2

• config/oauth2.ts — token lifetimes, scopes, rate limits.
• database/schemas/oauth_client.ts, oauth_token.ts, oauth_auth_code.ts — the three database schemas.
• actions/oauth2.ts — the actions contract (how your User model works).

Setup

1. Implement the actions contract

// actions/oauth2.ts
import { defineActions } from '@strav/oauth2'
import User from '../models/user'

export default defineActions({
  async findById(id) {
    return await User.find(id)
  },

  identifierOf(user) {
    return user.email
  },
})

Only two methods are required:

One method is optional:

2. Register the provider

import { OAuth2Provider } from '@strav/oauth2'
import actions from './actions/oauth2'

app.use(new OAuth2Provider(actions))

3. Run initial setup

bun strav oauth2:setup

personalAccessClient: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',

4. Create your first client

bun strav oauth2:client --name "Mobile App" --redirect "myapp://callback" --public

Store the client secret securely — it is shown only once.

Configuration

import { env } from '@strav/kernel'

export default {
  // Token lifetimes (in minutes)
  accessTokenLifetime: 60,            // 1 hour
  refreshTokenLifetime: 43_200,       // 30 days
  authCodeLifetime: 10,               // 10 minutes
  personalAccessTokenLifetime: 525_600, // 1 year

  // Route prefix for all OAuth2 endpoints
  prefix: '/oauth',

  // Available scopes
  scopes: {
    'read': 'Read access to your data',
    'write': 'Write access to your data',
    'repos:read': 'Read your repositories',
    'repos:write': 'Create and update repositories',
  },

  // Scopes granted when none are explicitly requested
  defaultScopes: [] as string[],

  // Client ID for personal access tokens (created by oauth2:setup)
  personalAccessClient: env('OAUTH2_PERSONAL_CLIENT') ?? null,

  // Rate limiting
  rateLimit: {
    authorize: { max: 30, window: 60 },
    token: { max: 20, window: 60 },
  },

  // Cleanup: delete revoked tokens older than this many days
  pruneRevokedAfterDays: 7,
}

Configuration reference

Routes

OAuth2 API routes (oauth2.api alias)

Client management routes (oauth2.admin alias)

Route configuration

Configure route prefixes, aliases, and subdomains in your OAuth2 config:

// config/oauth2.ts
export default {
  prefix: '/oauth',
  routes: {
    aliases: {
      api: 'oauth2.api',     // OAuth2 API endpoints
      admin: 'oauth2.admin'  // Client management endpoints
    },
    subdomain: 'oauth'       // Optional: mount on oauth.example.com
  }
}

Custom route aliases

Customize the route aliases to match your application's naming:

// config/oauth2.ts
export default {
  routes: {
    aliases: {
      api: 'oauth',          // Routes named: oauth.authorize, oauth.token, etc.
      admin: 'oauth.admin'   // Routes named: oauth.admin.clients, etc.
    }
  }
}

// Or for a multi-tenant app
export default {
  routes: {
    aliases: {
      api: 'api.oauth',      // Routes named: api.oauth.authorize, etc.
      admin: 'admin.oauth'   // Routes named: admin.oauth.clients, etc.
    }
  }
}

Using named routes

With route aliases configured, you can use OAuth2 endpoints with the route helpers:

import { route, routeUrl } from '@strav/http'

// OAuth2 API calls
const tokenResponse = await route('oauth2.api.token', {
  grant_type: 'authorization_code',
  code: 'auth_code_here',
  redirect_uri: 'https://app.com/callback',
  client_id: 'client_id',
  client_secret: 'client_secret'
})

// Revoke a token
await route('oauth2.api.revoke', { token: 'token_to_revoke' })

// Introspect a token
const introspection = await route('oauth2.api.introspect', {
  token: 'token_to_check'
})

// Client management
const clients = await route('oauth2.admin.clients')

const newClient = await route('oauth2.admin.create_client', {
  name: 'My Application',
  redirect_uris: ['https://app.com/callback'],
  scopes: ['read', 'write']
})

await route('oauth2.admin.delete_client', {
  params: { id: 'client_id' }
})

// Personal access tokens
const pat = await route('oauth2.admin.create_personal_token', {
  name: 'CLI Tool',
  scopes: ['read']
})

await route('oauth2.admin.revoke_personal_token', {
  params: { id: 'token_id' }
})

// Generate URLs for OAuth2 flows
const authUrl = routeUrl('oauth2.api.authorize', {
  client_id: 'client123',
  redirect_uri: 'https://app.com/callback',
  scope: 'read write',
  state: 'csrf_token',
  code_challenge: 'challenge',
  code_challenge_method: 'S256'
})

This eliminates hardcoded URLs and provides type-safe, refactorable route references throughout your OAuth2 integrations.

Grant flows

Authorization Code + PKCE

The standard flow for web and mobile apps. PKCE is required for public clients.

Step 1: Redirect the user

GET /oauth/authorize?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://example.com/callback
  &scope=read write
  &state=random-csrf-string
  &code_challenge=BASE64URL_SHA256_HASH
  &code_challenge_method=S256

{
  "authorization_required": true,
  "client": { "id": "...", "name": "Third Party App" },
  "scopes": [
    { "name": "read", "description": "Read access to your data" },
    { "name": "write", "description": "Write access to your data" }
  ],
  "state": "random-csrf-string"
}

Step 2: User approves

POST /oauth/authorize
Content-Type: application/json

{ "approved": true }

Step 3: Exchange the code for tokens

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "https://example.com/callback",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "code_verifier": "ORIGINAL_RANDOM_STRING"
}

Response:

{
  "access_token": "a1b2c3d4...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "e5f6g7h8...",
  "scope": "read write"
}

Client Credentials

Machine-to-machine authentication with no user context.

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "scope": "read"
}

Requirements:

• Client must be confidential (has a secret).
• client_credentials must be in the client's allowed grantTypes.

Refresh Token

Exchange a refresh token for a new access + refresh token pair. The old pair is revoked (rotation).

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "e5f6g7h8...",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "scope": "read"
}

Scopes can be narrowed on refresh but not widened beyond the original grant.

Token Revocation (RFC 7009)

POST /oauth/revoke
Content-Type: application/json

{ "token": "a1b2c3d4..." }

Token Introspection (RFC 7662)

POST /oauth/introspect
Content-Type: application/json

{ "token": "a1b2c3d4..." }

Response for a valid token:

{
  "active": true,
  "scope": "read write",
  "client_id": "CLIENT_ID",
  "sub": "USER_ID",
  "exp": 1700000000,
  "iat": 1699996400
}

Personal access tokens

Users can create long-lived tokens for API access (like GitHub PATs).

Create

POST /oauth/personal-tokens
Authorization: Bearer 
Content-Type: application/json

{
  "name": "CLI Tool",
  "scopes": ["read", "write"]
}

Response:

{
  "token": "a1b2c3d4...",
  "accessToken": {
    "id": "...",
    "name": "CLI Tool",
    "scopes": ["read", "write"],
    "expires_at": "...",
    "created_at": "..."
  }
}

> The plain-text token is shown only once. Store it securely.

List

GET /oauth/personal-tokens

Returns all active personal access tokens for the authenticated user. Token hashes are never exposed.

Revoke

DELETE /oauth/personal-tokens/:id

Middleware

oauth()

import { router } from '@strav/http'
import { oauth } from '@strav/oauth2'

router.group({ prefix: '/api', middleware: [oauth()] }, r => {
  r.get('/me', ctx => {
    const user = ctx.get('user')
    return ctx.json({ user })
  })
})

scopes(...required)

import { oauth, scopes } from '@strav/oauth2'
import { compose } from '@strav/http'

router.group({ prefix: '/api', middleware: [oauth()] }, r => {
  r.get('/repos', compose([scopes('repos:read')], listRepos))
  r.post('/repos', compose([scopes('repos:write')], createRepo))
  r.delete('/repos/:id', compose([scopes('repos:read', 'repos:write')], deleteRepo))
})

Events

import Emitter from '@strav/kernel'
import { OAuth2Events } from '@strav/oauth2'

Emitter.on(OAuth2Events.TOKEN_ISSUED, async ({ ctx, userId, clientId, grantType }) => {
  console.log(`Token issued for user ${userId} via ${grantType}`)
})

Emitter.on(OAuth2Events.ACCESS_DENIED, async ({ ctx, clientId }) => {
  console.log(`User denied access to client ${clientId}`)
})

oauth2 helper

import { oauth2 } from '@strav/oauth2'

// Client management
const { client, plainSecret } = await oauth2.createClient({
  name: 'My App',
  redirectUris: ['https://example.com/callback'],
})
const clients = await oauth2.listClients()
await oauth2.revokeClient(client.id)

// Personal access tokens
const { token, tokenData } = await oauth2.createPersonalToken(user, 'CLI Tool', ['read'])

// Token operations
await oauth2.revokeToken(tokenData.id)
await oauth2.revokeAllFor(user)
const data = await oauth2.validateToken(plainToken)

// Scopes
oauth2.defineScopes({ admin: 'Full admin access' })
const descriptions = oauth2.scopeDescriptions(['read', 'write'])

CLI commands

oauth2:setup

Create the OAuth2 tables and a default personal access client:

bun strav oauth2:setup

oauth2:client

Create a new OAuth2 client:

# Confidential client (default)
bun strav oauth2:client --name "Web App" --redirect "https://app.com/callback"

# Public client (SPA / mobile)
bun strav oauth2:client --name "Mobile App" --redirect "myapp://callback" --public

# First-party (skip consent)
bun strav oauth2:client --name "Admin Dashboard" --redirect "https://admin.com/callback" --first-party

# Machine-to-machine
bun strav oauth2:client --name "Worker Service" --credentials

oauth2:purge

Delete expired tokens and used authorization codes:

bun strav oauth2:purge
bun strav oauth2:purge --days 30

Clients

Confidential vs. public

First-party vs. third-party

Scopes per client

Restrict a client to specific scopes:

const { client } = await oauth2.createClient({
  name: 'Limited App',
  redirectUris: ['https://example.com/callback'],
  scopes: ['read'],  // can only request 'read' scope
})

Database tables

The package creates three tables:

Error handling

All errors follow the RFC 6749 error format:

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, or revoked."
}

Error classes:

import { OAuth2Error, InvalidGrantError } from '@strav/oauth2'

// Errors expose .toJSON() for RFC-compliant responses
const error = new InvalidGrantError('Authorization code expired.')
console.log(error.toJSON())
// { error: 'invalid_grant', error_description: 'Authorization code expired.' }

Security

• Token hashing: All tokens (access, refresh, authorization codes) are stored as SHA-256 hashes. Plain-text tokens are returned only once at creation time.
• Timing-safe comparison: Token lookups use crypto.timingSafeEqual to prevent timing attacks.
• PKCE (RFC 7636): Public clients must use PKCE with S256 or plain code challenge methods. The code verifier is validated against the stored challenge before issuing tokens.
• Code replay prevention: Authorization codes are single-use. Once consumed, the used_at timestamp prevents reuse.
• Refresh token rotation: On refresh, the old token pair is revoked and a new pair is issued. Compromised refresh tokens cannot be reused.
• Scope narrowing only: Refreshed tokens can narrow scopes but never widen them beyond the original grant.
• Redirect URI validation: The redirect_uri must exactly match one of the client's registered URIs.
• CSRF protection: The authorize POST endpoint uses csrf() middleware. The authorization code flow supports the state parameter.
• Rate limiting: Both the authorize and token endpoints are rate-limited by default.
• Client secret hashing: Client secrets are stored as bcrypt hashes via Bun.password.hash.

Integration with existing auth

• Works alongside Jina: The authorize endpoint uses auth() middleware from @strav/http. Jina handles the login flow — OAuth2 picks up from the authenticated session.
• Separate from AccessToken: OAuth2 tokens are stored in _strav_oauth_tokens, not _strav_access_tokens. They are a different system with scopes, clients, and refresh tokens.
• Coexistence: Use oauth() for OAuth2-protected API routes and auth() for session-based routes. They can coexist on different route groups.
• Session-aware: The authorize flow uses sessions (CSRF, consent state). Token endpoints are stateless.

Full example

import { router } from '@strav/http'
import { session } from '@strav/http'
import { auth } from '@strav/http'
import { compose } from '@strav/http'
import { OAuth2Provider, oauth, scopes, oauth2 } from '@strav/oauth2'
import actions from './actions/oauth2'

// Register the provider
app.use(new OAuth2Provider(actions))

// Define scopes (also configurable in config/oauth2.ts)
oauth2.defineScopes({
  'repos:read': 'Read your repositories',
  'repos:write': 'Create and update repositories',
  'user:email': 'Read your email address',
})

// Session-based routes (your web app)
router.group({ middleware: [session(), auth()] }, r => {
  r.get('/dashboard', dashboardHandler)
})

// OAuth2-protected API routes
router.group({ prefix: '/api/v1', middleware: [oauth()] }, r => {
  // Any valid token can access
  r.get('/user', ctx => {
    return ctx.json({ user: ctx.get('user') })
  })

  // Requires specific scopes
  r.get('/repos', compose([scopes('repos:read')], async ctx => {
    const repos = await Repo.query().where('user_id', ctx.get('user').id).get()
    return ctx.json({ repos })
  }))

  r.post('/repos', compose([scopes('repos:write')], async ctx => {
    const data = await ctx.body()
    const repo = await Repo.create({ ...data, userId: ctx.get('user').id })
    return ctx.json({ repo }, 201)
  }))
})