@stravigor/oauth2 0.4.5

package/src/handlers/token.ts

@@ -0,0 +1,290 @@
+import type Context from '@stravigor/core/http/context'
+import Emitter from '@stravigor/core/events/emitter'
+import OAuth2Manager from '../oauth2_manager.ts'
+import OAuthClient from '../client.ts'
+import OAuthToken from '../token.ts'
+import AuthCode from '../auth_code.ts'
+import ScopeRegistry from '../scopes.ts'
+import { OAuth2Events } from '../types.ts'
+import {
+  InvalidClientError,
+  InvalidGrantError,
+  InvalidRequestError,
+  UnsupportedGrantError,
+} from '../errors.ts'
+
+/**
+ * POST /oauth/token
+ *
+ * Token endpoint — handles all grant types:
+ * - authorization_code (+ PKCE)
+ * - client_credentials
+ * - refresh_token
+ */
+export async function tokenHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<Record<string, string>>()
+  const grantType = body.grant_type
+
+  if (!grantType) {
+    return errorResponse(ctx, new InvalidRequestError('The grant_type parameter is required.'))
+  }
+
+  switch (grantType) {
+    case 'authorization_code':
+      return handleAuthorizationCode(ctx, body)
+    case 'client_credentials':
+      return handleClientCredentials(ctx, body)
+    case 'refresh_token':
+      return handleRefreshToken(ctx, body)
+    default:
+      return errorResponse(ctx, new UnsupportedGrantError())
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Authorization Code Grant
+// ---------------------------------------------------------------------------
+
+async function handleAuthorizationCode(
+  ctx: Context,
+  body: Record<string, string>
+): Promise<Response> {
+  const { code, redirect_uri, client_id, client_secret, code_verifier } = body
+
+  if (!code || !redirect_uri || !client_id) {
+    return errorResponse(
+      ctx,
+      new InvalidRequestError('The code, redirect_uri, and client_id parameters are required.')
+    )
+  }
+
+  // Look up client
+  const client = await OAuthClient.find(client_id)
+  if (!client || client.revoked) {
+    return errorResponse(ctx, new InvalidClientError())
+  }
+
+  // Authenticate client
+  if (client.confidential) {
+    if (!client_secret) {
+      return errorResponse(
+        ctx,
+        new InvalidClientError('Client secret is required for confidential clients.')
+      )
+    }
+    const valid = await OAuthClient.verifySecret(client, client_secret)
+    if (!valid) {
+      return errorResponse(ctx, new InvalidClientError())
+    }
+  }
+
+  // Consume auth code (validates expiry, redirect_uri, PKCE)
+  const codeData = await AuthCode.consume(code, client_id, redirect_uri, code_verifier)
+  if (!codeData) {
+    return errorResponse(ctx, new InvalidGrantError())
+  }
+
+  // Issue tokens
+  const { accessToken, refreshToken, tokenData } = await OAuthToken.create({
+    userId: codeData.userId,
+    clientId: client_id,
+    scopes: codeData.scopes,
+    includeRefreshToken: client.grantTypes.includes('refresh_token'),
+  })
+
+  if (Emitter.listenerCount(OAuth2Events.TOKEN_ISSUED) > 0) {
+    Emitter.emit(OAuth2Events.TOKEN_ISSUED, {
+      ctx,
+      userId: codeData.userId,
+      clientId: client_id,
+      grantType: 'authorization_code',
+    }).catch(() => {})
+  }
+
+  return tokenResponse(ctx, accessToken, refreshToken, tokenData.scopes, tokenData.expiresAt)
+}
+
+// ---------------------------------------------------------------------------
+// Client Credentials Grant
+// ---------------------------------------------------------------------------
+
+async function handleClientCredentials(
+  ctx: Context,
+  body: Record<string, string>
+): Promise<Response> {
+  const { client_id, client_secret, scope } = body
+
+  if (!client_id || !client_secret) {
+    return errorResponse(
+      ctx,
+      new InvalidRequestError('The client_id and client_secret parameters are required.')
+    )
+  }
+
+  const client = await OAuthClient.find(client_id)
+  if (!client || client.revoked) {
+    return errorResponse(ctx, new InvalidClientError())
+  }
+
+  if (!client.confidential) {
+    return errorResponse(
+      ctx,
+      new InvalidClientError('Client credentials grant requires a confidential client.')
+    )
+  }
+
+  if (!client.grantTypes.includes('client_credentials')) {
+    return errorResponse(
+      ctx,
+      new InvalidGrantError('This client does not support the client_credentials grant.')
+    )
+  }
+
+  const valid = await OAuthClient.verifySecret(client, client_secret)
+  if (!valid) {
+    return errorResponse(ctx, new InvalidClientError())
+  }
+
+  // Validate scopes
+  const requestedScopes = scope ? scope.split(' ').filter(Boolean) : []
+  let scopes: string[]
+  try {
+    scopes = ScopeRegistry.validate(
+      requestedScopes,
+      client.scopes,
+      OAuth2Manager.config.defaultScopes
+    )
+  } catch (err) {
+    return errorResponse(ctx, err as Error)
+  }
+
+  // Issue access token only (no refresh token, no user)
+  const { accessToken, tokenData } = await OAuthToken.create({
+    userId: null,
+    clientId: client_id,
+    scopes,
+    includeRefreshToken: false,
+  })
+
+  if (Emitter.listenerCount(OAuth2Events.TOKEN_ISSUED) > 0) {
+    Emitter.emit(OAuth2Events.TOKEN_ISSUED, {
+      ctx,
+      clientId: client_id,
+      grantType: 'client_credentials',
+    }).catch(() => {})
+  }
+
+  return tokenResponse(ctx, accessToken, null, tokenData.scopes, tokenData.expiresAt)
+}
+
+// ---------------------------------------------------------------------------
+// Refresh Token Grant
+// ---------------------------------------------------------------------------
+
+async function handleRefreshToken(ctx: Context, body: Record<string, string>): Promise<Response> {
+  const { refresh_token, client_id, client_secret, scope } = body
+
+  if (!refresh_token || !client_id) {
+    return errorResponse(
+      ctx,
+      new InvalidRequestError('The refresh_token and client_id parameters are required.')
+    )
+  }
+
+  const client = await OAuthClient.find(client_id)
+  if (!client || client.revoked) {
+    return errorResponse(ctx, new InvalidClientError())
+  }
+
+  // Authenticate confidential clients
+  if (client.confidential) {
+    if (!client_secret) {
+      return errorResponse(
+        ctx,
+        new InvalidClientError('Client secret is required for confidential clients.')
+      )
+    }
+    const valid = await OAuthClient.verifySecret(client, client_secret)
+    if (!valid) {
+      return errorResponse(ctx, new InvalidClientError())
+    }
+  }
+
+  // Validate refresh token
+  const oldToken = await OAuthToken.validateRefreshToken(refresh_token)
+  if (!oldToken || oldToken.clientId !== client_id) {
+    return errorResponse(ctx, new InvalidGrantError())
+  }
+
+  // Optionally narrow scopes (cannot widen)
+  let scopes = oldToken.scopes
+  if (scope) {
+    const requested = scope.split(' ').filter(Boolean)
+    const widened = requested.filter(s => !oldToken.scopes.includes(s))
+    if (widened.length > 0) {
+      return errorResponse(
+        ctx,
+        new InvalidRequestError(
+          `Cannot widen scopes on refresh. Unknown scopes: ${widened.join(', ')}`
+        )
+      )
+    }
+    scopes = requested
+  }
+
+  // Revoke old token (rotation)
+  await OAuthToken.revoke(oldToken.id)
+
+  // Issue new token pair
+  const { accessToken, refreshToken, tokenData } = await OAuthToken.create({
+    userId: oldToken.userId,
+    clientId: client_id,
+    scopes,
+    includeRefreshToken: true,
+  })
+
+  if (Emitter.listenerCount(OAuth2Events.TOKEN_REFRESHED) > 0) {
+    Emitter.emit(OAuth2Events.TOKEN_REFRESHED, {
+      ctx,
+      userId: oldToken.userId,
+      clientId: client_id,
+    }).catch(() => {})
+  }
+
+  return tokenResponse(ctx, accessToken, refreshToken, tokenData.scopes, tokenData.expiresAt)
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function tokenResponse(
+  ctx: Context,
+  accessToken: string,
+  refreshToken: string | null,
+  scopes: string[],
+  expiresAt: Date
+): Response {
+  const expiresIn = Math.floor((expiresAt.getTime() - Date.now()) / 1000)
+
+  const payload: Record<string, unknown> = {
+    access_token: accessToken,
+    token_type: 'Bearer',
+    expires_in: expiresIn,
+    scope: scopes.join(' '),
+  }
+
+  if (refreshToken) {
+    payload.refresh_token = refreshToken
+  }
+
+  return ctx.json(payload)
+}
+
+function errorResponse(ctx: Context, error: Error): Response {
+  if ('toJSON' in error && typeof error.toJSON === 'function') {
+    const statusCode = (error as any).statusCode ?? 400
+    return ctx.json(error.toJSON(), statusCode)
+  }
+  return ctx.json({ error: 'server_error', error_description: error.message }, 500)
+}

package/src/helpers.ts

@@ -0,0 +1,98 @@
+import OAuth2Manager from './oauth2_manager.ts'
+import { getUserId } from './utils.ts'
+import OAuthClient from './client.ts'
+import OAuthToken from './token.ts'
+import ScopeRegistry from './scopes.ts'
+import type {
+  OAuthClientData,
+  OAuthTokenData,
+  CreateClientInput,
+  ScopeDescription,
+} from './types.ts'
+
+/**
+ * OAuth2 helper — convenience API for common OAuth2 server operations.
+ *
+ * @example
+ * import { oauth2 } from '@stravigor/oauth2'
+ *
+ * const { client, plainSecret } = await oauth2.createClient({ name: 'My App', redirectUris: ['...'] })
+ * const { token } = await oauth2.createPersonalToken(user, 'CLI Tool', ['read'])
+ * await oauth2.revokeToken(tokenId)
+ */
+export const oauth2 = {
+  /** Create a new OAuth client. Returns the client and plain-text secret (if confidential). */
+  async createClient(
+    data: CreateClientInput
+  ): Promise<{ client: OAuthClientData; plainSecret: string | null }> {
+    return OAuthClient.create(data)
+  },
+
+  /** Find a client by ID. */
+  async findClient(id: string): Promise<OAuthClientData | null> {
+    return OAuthClient.find(id)
+  },
+
+  /** List all non-revoked clients. */
+  async listClients(): Promise<OAuthClientData[]> {
+    return OAuthClient.all()
+  },
+
+  /** Soft-revoke a client. */
+  async revokeClient(id: string): Promise<void> {
+    return OAuthClient.revoke(id)
+  },
+
+  /** Issue a personal access token for a user. Token is shown once. */
+  async createPersonalToken(
+    user: unknown,
+    name: string,
+    scopes: string[] = []
+  ): Promise<{ token: string; tokenData: OAuthTokenData }> {
+    const config = OAuth2Manager.config
+    if (!config.personalAccessClient) {
+      throw new Error(
+        'No personal access client configured. Run "strav oauth2:setup" or set oauth2.personalAccessClient in config.'
+      )
+    }
+
+    const userId = getUserId(user)
+    const { accessToken, tokenData } = await OAuthToken.create({
+      userId,
+      clientId: config.personalAccessClient,
+      scopes,
+      name,
+      includeRefreshToken: false,
+      accessTokenLifetime: config.personalAccessTokenLifetime,
+    })
+
+    return { token: accessToken, tokenData }
+  },
+
+  /** Revoke a specific token by ID. */
+  async revokeToken(tokenId: string): Promise<void> {
+    return OAuthToken.revoke(tokenId)
+  },
+
+  /** Revoke all tokens for a user. */
+  async revokeAllFor(user: unknown): Promise<void> {
+    const userId = getUserId(user)
+    return OAuthToken.revokeAllFor(userId)
+  },
+
+  /** Register available scopes. */
+  defineScopes(scopes: Record<string, string>): void {
+    ScopeRegistry.define(scopes)
+  },
+
+  /** Get descriptions for registered scopes. */
+  scopeDescriptions(names?: string[]): ScopeDescription[] {
+    if (names) return ScopeRegistry.describe(names)
+    return ScopeRegistry.all()
+  },
+
+  /** Validate a plain-text access token and return its data. */
+  async validateToken(plainToken: string): Promise<OAuthTokenData | null> {
+    return OAuthToken.validate(plainToken)
+  },
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+// Manager & provider
+export { default, default as OAuth2Manager } from './oauth2_manager.ts'
+export { default as OAuth2Provider } from './oauth2_provider.ts'
+
+// Helper
+export { oauth2 } from './helpers.ts'
+
+// Actions
+export { defineActions } from './actions.ts'
+
+// Middleware
+export { oauth } from './middleware/oauth.ts'
+export { scopes } from './middleware/scopes.ts'
+
+// Data helpers
+export { default as OAuthClient } from './client.ts'
+export { default as OAuthToken } from './token.ts'
+export { default as AuthCode } from './auth_code.ts'
+
+// Scope registry
+export { default as ScopeRegistry } from './scopes.ts'
+
+// Handlers (for manual route registration)
+export { authorizeHandler, approveHandler } from './handlers/authorize.ts'
+export { tokenHandler } from './handlers/token.ts'
+export { revokeHandler } from './handlers/revoke.ts'
+export { introspectHandler } from './handlers/introspect.ts'
+export { listClientsHandler, createClientHandler, deleteClientHandler } from './handlers/clients.ts'
+export {
+  createPersonalTokenHandler,
+  listPersonalTokensHandler,
+  revokePersonalTokenHandler,
+} from './handlers/personal_tokens.ts'
+
+// Errors
+export {
+  OAuth2Error,
+  UnsupportedGrantError,
+  InvalidClientError,
+  InvalidGrantError,
+  InvalidRequestError,
+  InvalidScopeError,
+  AccessDeniedError,
+} from './errors.ts'
+
+// Types
+export type {
+  GrantType,
+  OAuth2Actions,
+  OAuth2Config,
+  OAuth2Event,
+  OAuthClientData,
+  OAuthTokenData,
+  OAuthAuthCodeData,
+  ScopeDescription,
+  CreateClientInput,
+  RateLimitConfig,
+} from './types.ts'
+export { OAuth2Events } from './types.ts'

package/src/middleware/oauth.ts

@@ -0,0 +1,61 @@
+import type { Middleware } from '@stravigor/core/http/middleware'
+import OAuth2Manager from '../oauth2_manager.ts'
+import OAuthClient from '../client.ts'
+import OAuthToken from '../token.ts'
+
+/**
+ * OAuth2 Bearer token authentication middleware.
+ *
+ * Validates the `Authorization: Bearer <token>` header, loads the
+ * associated user (if any), and sets `oauth_token` and `oauth_client`
+ * on the context state bag.
+ *
+ * @example
+ * import { oauth } from '@stravigor/oauth2'
+ *
+ * router.group({ prefix: '/api', middleware: [oauth()] }, r => {
+ *   r.get('/me', (ctx) => ctx.json({ user: ctx.get('user') }))
+ * })
+ */
+export function oauth(): Middleware {
+  return async (ctx, next) => {
+    const header = ctx.header('authorization')
+    if (!header || !header.startsWith('Bearer ')) {
+      return ctx.json(
+        { error: 'unauthenticated', error_description: 'Bearer token required.' },
+        401
+      )
+    }
+
+    const plain = header.slice(7)
+    const tokenData = await OAuthToken.validate(plain)
+    if (!tokenData) {
+      return ctx.json(
+        { error: 'invalid_token', error_description: 'The access token is invalid or expired.' },
+        401
+      )
+    }
+
+    // Load user for user-bound tokens (not client_credentials)
+    if (tokenData.userId) {
+      const user = await OAuth2Manager.actions.findById(tokenData.userId)
+      if (!user) {
+        return ctx.json(
+          { error: 'invalid_token', error_description: 'The token owner no longer exists.' },
+          401
+        )
+      }
+      ctx.set('user', user)
+    }
+
+    // Set token and client on context for downstream use
+    ctx.set('oauth_token', tokenData)
+
+    const client = await OAuthClient.find(tokenData.clientId)
+    if (client) {
+      ctx.set('oauth_client', client)
+    }
+
+    return next()
+  }
+}

package/src/middleware/scopes.ts

@@ -0,0 +1,37 @@
+import type { Middleware } from '@stravigor/core/http/middleware'
+import type { OAuthTokenData } from '../types.ts'
+
+/**
+ * Scope enforcement middleware.
+ *
+ * Checks that the current OAuth token has all the required scopes.
+ * Must be used after `oauth()` middleware.
+ *
+ * @example
+ * import { oauth, scopes } from '@stravigor/oauth2'
+ * import { compose } from '@stravigor/core/http/middleware'
+ *
+ * r.get('/repos', compose([oauth(), scopes('repos:read')], handler))
+ * r.post('/repos', compose([oauth(), scopes('repos:read', 'repos:write')], handler))
+ */
+export function scopes(...required: string[]): Middleware {
+  return (ctx, next) => {
+    const token = ctx.get<OAuthTokenData>('oauth_token')
+    if (!token) {
+      return ctx.json({ error: 'unauthenticated', error_description: 'OAuth token required.' }, 401)
+    }
+
+    const missing = required.filter(s => !token.scopes.includes(s))
+    if (missing.length > 0) {
+      return ctx.json(
+        {
+          error: 'insufficient_scope',
+          error_description: `Missing required scopes: ${missing.join(', ')}`,
+        },
+        403
+      )
+    }
+
+    return next()
+  }
+}