@stravigor/oauth2 0.4.5

package/src/handlers/authorize.ts

@@ -0,0 +1,243 @@
+import type Context from '@stravigor/core/http/context'
+import type Session from '@stravigor/core/session/session'
+import Emitter from '@stravigor/core/events/emitter'
+import { getUserId } from '../utils.ts'
+import OAuth2Manager from '../oauth2_manager.ts'
+import OAuthClient from '../client.ts'
+import AuthCode from '../auth_code.ts'
+import ScopeRegistry from '../scopes.ts'
+import { OAuth2Events } from '../types.ts'
+import {
+  InvalidRequestError,
+  InvalidClientError,
+  InvalidScopeError,
+  AccessDeniedError,
+} from '../errors.ts'
+
+/**
+ * GET /oauth/authorize
+ *
+ * Initiates the authorization code flow. Validates the request parameters,
+ * then either auto-approves (first-party client) or shows the consent screen.
+ */
+export async function authorizeHandler(ctx: Context): Promise<Response> {
+  const responseType = ctx.qs('response_type')
+  const clientId = ctx.qs('client_id')
+  const redirectUri = ctx.qs('redirect_uri')
+  const scopeParam = ctx.qs('scope')
+  const state = ctx.qs('state')
+  const codeChallenge = ctx.qs('code_challenge')
+  const codeChallengeMethod = ctx.qs('code_challenge_method') ?? 'plain'
+
+  // Validate required params
+  if (responseType !== 'code') {
+    return ctx.json(new InvalidRequestError('The response_type must be "code".').toJSON(), 400)
+  }
+
+  if (!clientId) {
+    return ctx.json(new InvalidRequestError('The client_id parameter is required.').toJSON(), 400)
+  }
+
+  // Look up client
+  const client = await OAuthClient.find(clientId)
+  if (!client || client.revoked) {
+    return ctx.json(new InvalidClientError().toJSON(), 401)
+  }
+
+  // Must support authorization_code grant
+  if (!client.grantTypes.includes('authorization_code')) {
+    return ctx.json(
+      new InvalidRequestError(
+        'This client does not support the authorization_code grant.'
+      ).toJSON(),
+      400
+    )
+  }
+
+  // Validate redirect URI
+  if (!redirectUri || !client.redirectUris.includes(redirectUri)) {
+    return ctx.json(
+      new InvalidRequestError(
+        'The redirect_uri is missing or not registered for this client.'
+      ).toJSON(),
+      400
+    )
+  }
+
+  // Public clients must use PKCE
+  if (!client.confidential && !codeChallenge) {
+    return errorRedirect(
+      redirectUri,
+      state,
+      'invalid_request',
+      'Public clients must use PKCE (code_challenge required).'
+    )
+  }
+
+  // Validate code_challenge_method
+  if (codeChallenge && codeChallengeMethod !== 'S256' && codeChallengeMethod !== 'plain') {
+    return errorRedirect(
+      redirectUri,
+      state,
+      'invalid_request',
+      'Unsupported code_challenge_method. Use "S256" or "plain".'
+    )
+  }
+
+  // Validate scopes
+  const requestedScopes = scopeParam ? scopeParam.split(' ').filter(Boolean) : []
+  let scopes: string[]
+  try {
+    scopes = ScopeRegistry.validate(
+      requestedScopes,
+      client.scopes,
+      OAuth2Manager.config.defaultScopes
+    )
+  } catch (err) {
+    if (err instanceof InvalidScopeError) {
+      return errorRedirect(redirectUri, state, 'invalid_scope', err.message)
+    }
+    throw err
+  }
+
+  // Store authorization request in session for the POST approval step
+  const session = ctx.get<Session>('session')
+  session.set('_oauth2_auth_request', {
+    clientId,
+    redirectUri,
+    scopes,
+    state: state ?? null,
+    codeChallenge: codeChallenge ?? null,
+    codeChallengeMethod: codeChallenge ? codeChallengeMethod : null,
+  })
+
+  // First-party clients skip consent
+  if (client.firstParty) {
+    return issueAuthorizationCode(
+      ctx,
+      client.id,
+      redirectUri,
+      scopes,
+      state,
+      codeChallenge,
+      codeChallengeMethod
+    )
+  }
+
+  // Third-party: render consent screen
+  const scopeDescriptions = ScopeRegistry.describe(scopes)
+  if (OAuth2Manager.actions.renderAuthorization) {
+    return OAuth2Manager.actions.renderAuthorization(ctx, client, scopeDescriptions)
+  }
+
+  // Default: JSON response for SPA-based consent
+  return ctx.json({
+    authorization_required: true,
+    client: { id: client.id, name: client.name },
+    scopes: scopeDescriptions,
+    state: state ?? null,
+  })
+}
+
+/**
+ * POST /oauth/authorize
+ *
+ * Handles the user's approval or denial of the authorization request.
+ */
+export async function approveHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{ approved?: boolean }>()
+  const session = ctx.get<Session>('session')
+
+  const authRequest = session.get<{
+    clientId: string
+    redirectUri: string
+    scopes: string[]
+    state: string | null
+    codeChallenge: string | null
+    codeChallengeMethod: string | null
+  }>('_oauth2_auth_request')
+
+  if (!authRequest) {
+    return ctx.json(new InvalidRequestError('No pending authorization request.').toJSON(), 400)
+  }
+
+  // Clear the session data
+  session.forget('_oauth2_auth_request')
+
+  // User denied
+  if (!body.approved) {
+    if (Emitter.listenerCount(OAuth2Events.ACCESS_DENIED) > 0) {
+      Emitter.emit(OAuth2Events.ACCESS_DENIED, { ctx, clientId: authRequest.clientId }).catch(
+        () => {}
+      )
+    }
+    return errorRedirect(
+      authRequest.redirectUri,
+      authRequest.state,
+      'access_denied',
+      'The resource owner denied the request.'
+    )
+  }
+
+  // User approved — issue code
+  return issueAuthorizationCode(
+    ctx,
+    authRequest.clientId,
+    authRequest.redirectUri,
+    authRequest.scopes,
+    authRequest.state,
+    authRequest.codeChallenge,
+    authRequest.codeChallengeMethod
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+async function issueAuthorizationCode(
+  ctx: Context,
+  clientId: string,
+  redirectUri: string,
+  scopes: string[],
+  state: string | null,
+  codeChallenge: string | null,
+  codeChallengeMethod: string | null
+): Promise<Response> {
+  const user = ctx.get('user')
+  const userId = getUserId(user)
+
+  const { code } = await AuthCode.create({
+    clientId,
+    userId,
+    redirectUri,
+    scopes,
+    codeChallenge,
+    codeChallengeMethod,
+  })
+
+  if (Emitter.listenerCount(OAuth2Events.CODE_ISSUED) > 0) {
+    Emitter.emit(OAuth2Events.CODE_ISSUED, { ctx, clientId, userId }).catch(() => {})
+  }
+
+  // Redirect back to client with code
+  const url = new URL(redirectUri)
+  url.searchParams.set('code', code)
+  if (state) url.searchParams.set('state', state)
+
+  return ctx.redirect(url.toString())
+}
+
+function errorRedirect(
+  redirectUri: string,
+  state: string | null,
+  error: string,
+  description: string
+): Response {
+  const url = new URL(redirectUri)
+  url.searchParams.set('error', error)
+  url.searchParams.set('error_description', description)
+  if (state) url.searchParams.set('state', state)
+
+  return Response.redirect(url.toString(), 302)
+}

package/src/handlers/clients.ts

@@ -0,0 +1,101 @@
+import type Context from '@stravigor/core/http/context'
+import Emitter from '@stravigor/core/events/emitter'
+import OAuthClient from '../client.ts'
+import { OAuth2Events } from '../types.ts'
+import type { GrantType } from '../types.ts'
+
+/**
+ * GET /oauth/clients
+ *
+ * List all non-revoked OAuth clients.
+ */
+export async function listClientsHandler(ctx: Context): Promise<Response> {
+  const clients = await OAuthClient.all()
+
+  return ctx.json({
+    clients: clients.map(c => ({
+      id: c.id,
+      name: c.name,
+      redirect_uris: c.redirectUris,
+      grant_types: c.grantTypes,
+      confidential: c.confidential,
+      first_party: c.firstParty,
+      created_at: c.createdAt,
+    })),
+  })
+}
+
+/**
+ * POST /oauth/clients
+ *
+ * Create a new OAuth client. Returns the client record and plain secret.
+ */
+export async function createClientHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{
+    name?: string
+    redirect_uris?: string[]
+    confidential?: boolean
+    first_party?: boolean
+    scopes?: string[] | null
+    grant_types?: GrantType[]
+  }>()
+
+  if (!body.name) {
+    return ctx.json({ message: 'The name field is required.' }, 422)
+  }
+
+  if (!body.redirect_uris || body.redirect_uris.length === 0) {
+    return ctx.json({ message: 'At least one redirect_uri is required.' }, 422)
+  }
+
+  const { client, plainSecret } = await OAuthClient.create({
+    name: body.name,
+    redirectUris: body.redirect_uris,
+    confidential: body.confidential,
+    firstParty: body.first_party,
+    scopes: body.scopes,
+    grantTypes: body.grant_types,
+  })
+
+  if (Emitter.listenerCount(OAuth2Events.CLIENT_CREATED) > 0) {
+    Emitter.emit(OAuth2Events.CLIENT_CREATED, { ctx, client }).catch(() => {})
+  }
+
+  return ctx.json(
+    {
+      client: {
+        id: client.id,
+        name: client.name,
+        redirect_uris: client.redirectUris,
+        grant_types: client.grantTypes,
+        confidential: client.confidential,
+        first_party: client.firstParty,
+        created_at: client.createdAt,
+      },
+      secret: plainSecret,
+    },
+    201
+  )
+}
+
+/**
+ * DELETE /oauth/clients/:id
+ *
+ * Soft-revoke an OAuth client and all its tokens.
+ */
+export async function deleteClientHandler(ctx: Context): Promise<Response> {
+  const id = ctx.params.id!
+
+  const client = await OAuthClient.findIncludingRevoked(id)
+  if (!client) {
+    return ctx.json({ message: 'Client not found.' }, 404)
+  }
+
+  await OAuthClient.revoke(id)
+
+  if (Emitter.listenerCount(OAuth2Events.CLIENT_REVOKED) > 0) {
+    Emitter.emit(OAuth2Events.CLIENT_REVOKED, { ctx, clientId: id }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Client revoked.' })
+}

package/src/handlers/introspect.ts

@@ -0,0 +1,61 @@
+import type Context from '@stravigor/core/http/context'
+import OAuthClient from '../client.ts'
+import OAuthToken from '../token.ts'
+import { InvalidClientError } from '../errors.ts'
+
+/**
+ * POST /oauth/introspect (RFC 7662)
+ *
+ * Returns metadata about a token. Used by resource servers to validate
+ * tokens without needing direct database access.
+ */
+export async function introspectHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{
+    token?: string
+    token_type_hint?: string
+    client_id?: string
+    client_secret?: string
+  }>()
+
+  const { token, client_id, client_secret } = body
+
+  if (!token) {
+    return ctx.json(
+      { error: 'invalid_request', error_description: 'The token parameter is required.' },
+      400
+    )
+  }
+
+  // Authenticate the requesting client
+  if (client_id) {
+    const client = await OAuthClient.find(client_id)
+    if (!client || client.revoked) {
+      return ctx.json(new InvalidClientError().toJSON(), 401)
+    }
+
+    if (client.confidential && client_secret) {
+      const valid = await OAuthClient.verifySecret(client, client_secret)
+      if (!valid) {
+        return ctx.json(new InvalidClientError().toJSON(), 401)
+      }
+    }
+  }
+
+  // Validate the token
+  const tokenData = await OAuthToken.validate(token)
+  if (!tokenData) {
+    // Inactive token — return minimal response per RFC 7662
+    return ctx.json({ active: false })
+  }
+
+  // Active token — return metadata
+  return ctx.json({
+    active: true,
+    scope: tokenData.scopes.join(' '),
+    client_id: tokenData.clientId,
+    token_type: 'Bearer',
+    exp: Math.floor(tokenData.expiresAt.getTime() / 1000),
+    iat: Math.floor(tokenData.createdAt.getTime() / 1000),
+    sub: tokenData.userId ?? undefined,
+  })
+}

package/src/handlers/personal_tokens.ts

@@ -0,0 +1,115 @@
+import type Context from '@stravigor/core/http/context'
+import Emitter from '@stravigor/core/events/emitter'
+import { getUserId } from '../utils.ts'
+import OAuth2Manager from '../oauth2_manager.ts'
+import OAuthToken from '../token.ts'
+import ScopeRegistry from '../scopes.ts'
+import { OAuth2Events } from '../types.ts'
+
+/**
+ * POST /oauth/personal-tokens
+ *
+ * Issue a personal access token for the authenticated user.
+ * Returns the plain-text token (shown once).
+ */
+export async function createPersonalTokenHandler(ctx: Context): Promise<Response> {
+  const config = OAuth2Manager.config
+
+  if (!config.personalAccessClient) {
+    return ctx.json(
+      { message: 'No personal access client configured. Run "strav oauth2:setup" first.' },
+      500
+    )
+  }
+
+  const body = await ctx.body<{ name?: string; scopes?: string[] }>()
+
+  if (!body.name) {
+    return ctx.json({ message: 'The name field is required.' }, 422)
+  }
+
+  // Validate scopes if provided
+  const scopes = body.scopes ?? []
+  if (scopes.length > 0) {
+    for (const scope of scopes) {
+      if (!ScopeRegistry.has(scope)) {
+        return ctx.json({ message: `Unknown scope: "${scope}".` }, 422)
+      }
+    }
+  }
+
+  const user = ctx.get('user')
+  const userId = getUserId(user)
+
+  const { accessToken, tokenData } = await OAuthToken.create({
+    userId,
+    clientId: config.personalAccessClient,
+    scopes,
+    name: body.name,
+    includeRefreshToken: false,
+    accessTokenLifetime: config.personalAccessTokenLifetime,
+  })
+
+  if (Emitter.listenerCount(OAuth2Events.TOKEN_ISSUED) > 0) {
+    Emitter.emit(OAuth2Events.TOKEN_ISSUED, {
+      ctx,
+      userId,
+      clientId: config.personalAccessClient,
+      grantType: 'personal_access_token',
+    }).catch(() => {})
+  }
+
+  return ctx.json(
+    {
+      token: accessToken,
+      accessToken: {
+        id: tokenData.id,
+        name: tokenData.name,
+        scopes: tokenData.scopes,
+        expires_at: tokenData.expiresAt,
+        created_at: tokenData.createdAt,
+      },
+    },
+    201
+  )
+}
+
+/**
+ * GET /oauth/personal-tokens
+ *
+ * List all active personal access tokens for the authenticated user.
+ */
+export async function listPersonalTokensHandler(ctx: Context): Promise<Response> {
+  const user = ctx.get('user')
+  const userId = getUserId(user)
+
+  const tokens = await OAuthToken.personalTokensFor(userId)
+
+  return ctx.json({
+    tokens: tokens.map(t => ({
+      id: t.id,
+      name: t.name,
+      scopes: t.scopes,
+      last_used_at: t.lastUsedAt,
+      expires_at: t.expiresAt,
+      created_at: t.createdAt,
+    })),
+  })
+}
+
+/**
+ * DELETE /oauth/personal-tokens/:id
+ *
+ * Revoke a specific personal access token.
+ */
+export async function revokePersonalTokenHandler(ctx: Context): Promise<Response> {
+  const tokenId = ctx.params.id!
+
+  await OAuthToken.revoke(tokenId)
+
+  if (Emitter.listenerCount(OAuth2Events.TOKEN_REVOKED) > 0) {
+    Emitter.emit(OAuth2Events.TOKEN_REVOKED, { ctx, tokenId }).catch(() => {})
+  }
+
+  return ctx.json({ message: 'Token revoked.' })
+}

package/src/handlers/revoke.ts

@@ -0,0 +1,71 @@
+import type Context from '@stravigor/core/http/context'
+import Emitter from '@stravigor/core/events/emitter'
+import OAuthClient from '../client.ts'
+import OAuthToken from '../token.ts'
+import { OAuth2Events } from '../types.ts'
+import { InvalidClientError } from '../errors.ts'
+
+/**
+ * POST /oauth/revoke (RFC 7009)
+ *
+ * Revokes an access token or refresh token.
+ * Always returns 200 regardless of whether the token existed
+ * (to prevent information leakage).
+ */
+export async function revokeHandler(ctx: Context): Promise<Response> {
+  const body = await ctx.body<{
+    token?: string
+    token_type_hint?: string
+    client_id?: string
+    client_secret?: string
+  }>()
+
+  const { token, client_id, client_secret } = body
+
+  if (!token) {
+    return ctx.json(
+      { error: 'invalid_request', error_description: 'The token parameter is required.' },
+      400
+    )
+  }
+
+  // Authenticate the client if credentials are provided
+  if (client_id) {
+    const client = await OAuthClient.find(client_id)
+    if (!client || client.revoked) {
+      return ctx.json(new InvalidClientError().toJSON(), 401)
+    }
+
+    if (client.confidential && client_secret) {
+      const valid = await OAuthClient.verifySecret(client, client_secret)
+      if (!valid) {
+        return ctx.json(new InvalidClientError().toJSON(), 401)
+      }
+    }
+  }
+
+  // Try revoking as access token first, then as refresh token
+  const tokenData = await OAuthToken.validate(token)
+  if (tokenData) {
+    await OAuthToken.revoke(tokenData.id)
+
+    if (Emitter.listenerCount(OAuth2Events.TOKEN_REVOKED) > 0) {
+      Emitter.emit(OAuth2Events.TOKEN_REVOKED, { ctx, tokenId: tokenData.id }).catch(() => {})
+    }
+
+    return ctx.json({})
+  }
+
+  // Try as refresh token
+  const refreshData = await OAuthToken.validateRefreshToken(token)
+  if (refreshData) {
+    await OAuthToken.revoke(refreshData.id)
+
+    if (Emitter.listenerCount(OAuth2Events.TOKEN_REVOKED) > 0) {
+      Emitter.emit(OAuth2Events.TOKEN_REVOKED, { ctx, tokenId: refreshData.id }).catch(() => {})
+    }
+  }
+
+  // RFC 7009: Always respond with 200 even if token not found
+  return ctx.json({})
+}