@stravigor/oauth2 0.4.5

package/README.md

@@ -0,0 +1,72 @@
+# @stravigor/oauth2
+
+OAuth2 server for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Authorization Code + PKCE, Client Credentials, Refresh Token rotation, Token Revocation (RFC 7009), Token Introspection (RFC 7662), personal access tokens, and scoped API access.
+
+## Install
+
+```bash
+bun add @stravigor/oauth2
+bun strav package:install oauth2
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Setup
+
+```ts
+import { defineActions } from '@stravigor/oauth2'
+import User from './models/user'
+
+const actions = defineActions<User>({
+  async findById(id) { return User.find(id) },
+  identifierOf(user) { return user.email },
+})
+```
+
+```ts
+import { OAuth2Provider } from '@stravigor/oauth2'
+
+app.use(new OAuth2Provider(actions))
+```
+
+```bash
+bun strav oauth2:setup    # Create tables + personal access client
+bun strav oauth2:client --name "My App" --redirect "https://app.com/callback"
+```
+
+## Middleware
+
+```ts
+import { oauth, scopes } from '@stravigor/oauth2'
+import { compose } from '@stravigor/core/http/middleware'
+
+router.group({ prefix: '/api', middleware: [oauth()] }, r => {
+  r.get('/user', ctx => ctx.json({ user: ctx.get('user') }))
+  r.get('/repos', compose([scopes('repos:read')], listRepos))
+  r.post('/repos', compose([scopes('repos:write')], createRepo))
+})
+```
+
+## Personal Access Tokens
+
+```ts
+import { oauth2 } from '@stravigor/oauth2'
+
+const { token } = await oauth2.createPersonalToken(user, 'CLI Tool', ['read', 'write'])
+```
+
+## CLI
+
+```bash
+bun strav oauth2:setup     # Create tables and personal access client
+bun strav oauth2:client    # Create a new OAuth2 client
+bun strav oauth2:purge     # Clean up expired tokens and codes
+```
+
+## Documentation
+
+See the full [OAuth2 guide](../../guides/oauth2.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@stravigor/oauth2",
+  "version": "0.4.5",
+  "type": "module",
+  "description": "OAuth2 server implementation for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "strav": {
+    "commands": "src/commands"
+  },
+  "files": [
+    "src/",
+    "stubs/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "@stravigor/core": "0.4.4"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,20 @@
+import type { OAuth2Actions } from './types.ts'
+
+/**
+ * Type-safe identity function for defining OAuth2 actions.
+ * Zero runtime cost — just provides autocompletion and type checking.
+ *
+ * @example
+ * import { defineActions } from '@stravigor/oauth2'
+ * import { User } from '../models/user'
+ *
+ * export default defineActions<User>({
+ *   findById: (id) => User.find(id),
+ *   identifierOf: (user) => user.email,
+ * })
+ */
+export function defineActions<TUser = unknown>(
+  actions: OAuth2Actions<TUser>
+): OAuth2Actions<TUser> {
+  return actions
+}

package/src/auth_code.ts

@@ -0,0 +1,154 @@
+import OAuth2Manager from './oauth2_manager.ts'
+import { randomHex } from '@stravigor/core/helpers'
+import type { OAuthAuthCodeData } from './types.ts'
+
+function hashCode(plain: string): string {
+  return new Bun.CryptoHasher('sha256').update(plain).digest('hex')
+}
+
+/**
+ * Static helper for managing OAuth2 authorization codes.
+ *
+ * Codes are SHA-256 hashed before storage and are single-use.
+ *
+ * @example
+ * const { code, codeData } = await AuthCode.create({ ... })
+ * const record = await AuthCode.consume(plainCode, clientId, redirectUri, codeVerifier)
+ */
+export default class AuthCode {
+  /**
+   * Create a new authorization code.
+   * Returns the plain-text code (sent to client via redirect) and the DB record.
+   */
+  static async create(params: {
+    clientId: string
+    userId: string
+    redirectUri: string
+    scopes: string[]
+    codeChallenge?: string | null
+    codeChallengeMethod?: string | null
+  }): Promise<{ code: string; codeData: OAuthAuthCodeData }> {
+    const config = OAuth2Manager.config
+    const plainCode = randomHex(40)
+    const hashedCode = hashCode(plainCode)
+    const expiresAt = new Date(Date.now() + config.authCodeLifetime * 60_000)
+
+    const rows = await OAuth2Manager.db.sql`
+      INSERT INTO "_strav_oauth_auth_codes" (
+        "client_id", "user_id", "code", "redirect_uri", "scopes",
+        "code_challenge", "code_challenge_method", "expires_at"
+      )
+      VALUES (
+        ${params.clientId},
+        ${params.userId},
+        ${hashedCode},
+        ${params.redirectUri},
+        ${JSON.stringify(params.scopes)},
+        ${params.codeChallenge ?? null},
+        ${params.codeChallengeMethod ?? null},
+        ${expiresAt}
+      )
+      RETURNING *
+    `
+
+    return {
+      code: plainCode,
+      codeData: AuthCode.hydrate(rows[0] as Record<string, unknown>),
+    }
+  }
+
+  /**
+   * Consume an authorization code. Validates and marks it as used.
+   *
+   * Checks:
+   * - Code exists and belongs to the client
+   * - Code is not expired
+   * - Code has not been used before
+   * - Redirect URI matches
+   * - PKCE code_verifier matches (if code_challenge was set)
+   *
+   * Returns the code data if valid, null otherwise.
+   */
+  static async consume(
+    plainCode: string,
+    clientId: string,
+    redirectUri: string,
+    codeVerifier?: string | null
+  ): Promise<OAuthAuthCodeData | null> {
+    const hash = hashCode(plainCode)
+
+    const rows = await OAuth2Manager.db.sql`
+      SELECT * FROM "_strav_oauth_auth_codes"
+      WHERE "code" = ${hash} AND "client_id" = ${clientId}
+      LIMIT 1
+    `
+    if (rows.length === 0) return null
+
+    const record = AuthCode.hydrate(rows[0] as Record<string, unknown>)
+
+    // Already used — potential replay attack
+    if (record.usedAt) return null
+
+    // Expired
+    if (record.expiresAt.getTime() < Date.now()) return null
+
+    // Redirect URI mismatch
+    if (record.redirectUri !== redirectUri) return null
+
+    // PKCE verification
+    if (record.codeChallenge) {
+      if (!codeVerifier) return null
+
+      if (record.codeChallengeMethod === 'S256') {
+        const verifierHash = new Bun.CryptoHasher('sha256').update(codeVerifier).digest('base64url')
+        if (verifierHash !== record.codeChallenge) return null
+      } else {
+        // plain method
+        if (codeVerifier !== record.codeChallenge) return null
+      }
+    }
+
+    // Mark as used
+    await OAuth2Manager.db.sql`
+      UPDATE "_strav_oauth_auth_codes"
+      SET "used_at" = NOW()
+      WHERE "id" = ${record.id}
+    `
+
+    return record
+  }
+
+  /** Prune expired and used auth codes. Returns the number of deleted rows. */
+  static async prune(): Promise<number> {
+    const result = await OAuth2Manager.db.sql`
+      DELETE FROM "_strav_oauth_auth_codes"
+      WHERE "expires_at" < NOW() OR "used_at" IS NOT NULL
+    `
+    return result.count ?? 0
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  static hydrate(row: Record<string, unknown>): OAuthAuthCodeData {
+    return {
+      id: String(row.id),
+      clientId: String(row.client_id),
+      userId: row.user_id as string,
+      redirectUri: row.redirect_uri as string,
+      scopes: parseJsonb(row.scopes) as string[],
+      codeChallenge: (row.code_challenge as string) ?? null,
+      codeChallengeMethod: (row.code_challenge_method as string) ?? null,
+      expiresAt: row.expires_at as Date,
+      usedAt: (row.used_at as Date) ?? null,
+      createdAt: row.created_at as Date,
+    }
+  }
+}
+
+function parseJsonb(value: unknown): unknown {
+  if (value === null || value === undefined) return []
+  if (typeof value === 'string') return JSON.parse(value)
+  return value
+}

package/src/client.ts

@@ -0,0 +1,155 @@
+import { timingSafeEqual as nodeTimingSafeEqual } from 'node:crypto'
+import OAuth2Manager from './oauth2_manager.ts'
+import { randomHex } from '@stravigor/core/helpers'
+import type { OAuthClientData, CreateClientInput, GrantType } from './types.ts'
+
+function hashSecret(plain: string): string {
+  return new Bun.CryptoHasher('sha256').update(plain).digest('hex')
+}
+
+/**
+ * Static helper for managing OAuth2 clients.
+ *
+ * Client secrets are SHA-256 hashed before storage — the plain-text
+ * secret is returned exactly once at creation time.
+ *
+ * @example
+ * const { client, plainSecret } = await OAuthClient.create({ name: 'Mobile App', redirectUris: ['myapp://callback'] })
+ * const client = await OAuthClient.find(id)
+ * await OAuthClient.revoke(id)
+ */
+export default class OAuthClient {
+  /** Create a new OAuth client. Returns the client record and the plain secret (if confidential). */
+  static async create(input: CreateClientInput): Promise<{
+    client: OAuthClientData
+    plainSecret: string | null
+  }> {
+    const confidential = input.confidential ?? true
+    const firstParty = input.firstParty ?? false
+    const grantTypes = input.grantTypes ?? ['authorization_code', 'refresh_token']
+
+    let plainSecret: string | null = null
+    let hashedSecret: string | null = null
+
+    if (confidential) {
+      plainSecret = randomHex(32)
+      hashedSecret = hashSecret(plainSecret)
+    }
+
+    const rows = await OAuth2Manager.db.sql`
+      INSERT INTO "_strav_oauth_clients" (
+        "name", "secret", "redirect_uris", "scopes", "grant_types",
+        "confidential", "first_party", "revoked"
+      )
+      VALUES (
+        ${input.name},
+        ${hashedSecret},
+        ${JSON.stringify(input.redirectUris)},
+        ${input.scopes !== undefined ? JSON.stringify(input.scopes) : null},
+        ${JSON.stringify(grantTypes)},
+        ${confidential},
+        ${firstParty},
+        ${false}
+      )
+      RETURNING *
+    `
+
+    return {
+      client: OAuthClient.hydrate(rows[0] as Record<string, unknown>),
+      plainSecret,
+    }
+  }
+
+  /** Find a client by ID. Returns null if not found or revoked. */
+  static async find(id: string): Promise<OAuthClientData | null> {
+    const rows = await OAuth2Manager.db.sql`
+      SELECT * FROM "_strav_oauth_clients" WHERE "id" = ${id} LIMIT 1
+    `
+    if (rows.length === 0) return null
+    return OAuthClient.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Find a client by ID, including revoked clients. */
+  static async findIncludingRevoked(id: string): Promise<OAuthClientData | null> {
+    const rows = await OAuth2Manager.db.sql`
+      SELECT * FROM "_strav_oauth_clients" WHERE "id" = ${id} LIMIT 1
+    `
+    if (rows.length === 0) return null
+    return OAuthClient.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Verify a plain-text client secret against the stored hash. */
+  static async verifySecret(client: OAuthClientData, plainSecret: string): Promise<boolean> {
+    const rows = await OAuth2Manager.db.sql`
+      SELECT "secret" FROM "_strav_oauth_clients" WHERE "id" = ${client.id} LIMIT 1
+    `
+    if (rows.length === 0) return false
+    const stored = (rows[0] as Record<string, unknown>).secret as string | null
+    if (!stored) return false
+
+    const hash = hashSecret(plainSecret)
+    return timingSafeEqual(stored, hash)
+  }
+
+  /** List all non-revoked clients. */
+  static async all(): Promise<OAuthClientData[]> {
+    const rows = await OAuth2Manager.db.sql`
+      SELECT * FROM "_strav_oauth_clients" WHERE "revoked" = false ORDER BY "created_at" DESC
+    `
+    return (rows as Record<string, unknown>[]).map(OAuthClient.hydrate)
+  }
+
+  /** List all clients belonging to a user (clients they created). */
+  static async allForUser(userId: string): Promise<OAuthClientData[]> {
+    // All non-revoked clients visible to the user
+    return OAuthClient.all()
+  }
+
+  /** Soft-revoke a client. */
+  static async revoke(id: string): Promise<void> {
+    await OAuth2Manager.db.sql`
+      UPDATE "_strav_oauth_clients" SET "revoked" = true, "updated_at" = NOW()
+      WHERE "id" = ${id}
+    `
+  }
+
+  /** Hard-delete a client and all its tokens/codes. */
+  static async destroy(id: string): Promise<void> {
+    const db = OAuth2Manager.db
+    await db.sql`DELETE FROM "_strav_oauth_auth_codes" WHERE "client_id" = ${id}`
+    await db.sql`DELETE FROM "_strav_oauth_tokens" WHERE "client_id" = ${id}`
+    await db.sql`DELETE FROM "_strav_oauth_clients" WHERE "id" = ${id}`
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  static hydrate(row: Record<string, unknown>): OAuthClientData {
+    return {
+      id: String(row.id),
+      name: row.name as string,
+      redirectUris: parseJsonb(row.redirect_uris) as string[],
+      scopes: parseJsonb(row.scopes) as string[] | null,
+      grantTypes: parseJsonb(row.grant_types) as GrantType[],
+      confidential: row.confidential as boolean,
+      firstParty: row.first_party as boolean,
+      revoked: row.revoked as boolean,
+      createdAt: row.created_at as Date,
+      updatedAt: row.updated_at as Date,
+    }
+  }
+}
+
+/** Timing-safe string comparison. */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  return nodeTimingSafeEqual(Buffer.from(a), Buffer.from(b))
+}
+
+/** Parse a JSONB column that may already be an object or a string. */
+function parseJsonb(value: unknown): unknown {
+  if (value === null || value === undefined) return null
+  if (typeof value === 'string') return JSON.parse(value)
+  return value
+}

package/src/commands/oauth2_commands.ts

@@ -0,0 +1,152 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/core/cli/bootstrap'
+import OAuth2Manager from '../oauth2_manager.ts'
+import OAuthClient from '../client.ts'
+import OAuthToken from '../token.ts'
+import AuthCode from '../auth_code.ts'
+
+export function register(program: Command): void {
+  // ── oauth2:setup ────────────────────────────────────────────────────
+
+  program
+    .command('oauth2:setup')
+    .description('Create OAuth2 tables and a default personal access client')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new OAuth2Manager(db, config)
+
+        console.log(chalk.dim('Creating OAuth2 tables...'))
+        await OAuth2Manager.ensureTables()
+        console.log(chalk.green('OAuth2 tables created successfully.'))
+
+        // Create personal access client if not already configured
+        const patClientId = OAuth2Manager.config.personalAccessClient
+        if (!patClientId) {
+          console.log(chalk.dim('Creating personal access client...'))
+          const { client } = await OAuthClient.create({
+            name: 'Personal Access Client',
+            redirectUris: [],
+            confidential: true,
+            firstParty: true,
+            grantTypes: [],
+          })
+          console.log(chalk.green(`Personal access client created: ${chalk.bold(client.id)}`))
+          console.log(
+            chalk.yellow(
+              `\nAdd this to your config/oauth2.ts:\n  personalAccessClient: '${client.id}'`
+            )
+          )
+        } else {
+          console.log(chalk.dim(`Personal access client already configured: ${patClientId}`))
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+
+  // ── oauth2:client ───────────────────────────────────────────────────
+
+  program
+    .command('oauth2:client')
+    .description('Create a new OAuth2 client')
+    .requiredOption('--name <name>', 'Client name')
+    .option('--redirect <uris...>', 'Redirect URIs', [])
+    .option('--public', 'Create a public (non-confidential) client', false)
+    .option('--first-party', 'Mark as a first-party (trusted) client', false)
+    .option('--credentials', 'Enable client_credentials grant', false)
+    .action(
+      async (options: {
+        name: string
+        redirect: string[]
+        public: boolean
+        firstParty: boolean
+        credentials: boolean
+      }) => {
+        let db
+        try {
+          const { db: database, config } = await bootstrap()
+          db = database
+
+          new OAuth2Manager(db, config)
+          await OAuth2Manager.ensureTables()
+
+          const grantTypes = ['authorization_code', 'refresh_token'] as (
+            | 'authorization_code'
+            | 'client_credentials'
+            | 'refresh_token'
+          )[]
+          if (options.credentials) {
+            grantTypes.push('client_credentials')
+          }
+
+          const { client, plainSecret } = await OAuthClient.create({
+            name: options.name,
+            redirectUris: options.redirect,
+            confidential: !options.public,
+            firstParty: options.firstParty,
+            grantTypes,
+          })
+
+          console.log(chalk.green('\nOAuth2 client created successfully.\n'))
+          console.log(`  ${chalk.dim('Client ID:')}     ${chalk.bold(client.id)}`)
+
+          if (plainSecret) {
+            console.log(`  ${chalk.dim('Client Secret:')} ${chalk.bold(plainSecret)}`)
+            console.log(chalk.yellow('\n  Store the secret securely — it will not be shown again.'))
+          } else {
+            console.log(`  ${chalk.dim('Type:')}          Public (no secret)`)
+          }
+
+          console.log(
+            `  ${chalk.dim('Redirect URIs:')} ${client.redirectUris.join(', ') || '(none)'}`
+          )
+          console.log(`  ${chalk.dim('Grant Types:')}   ${client.grantTypes.join(', ')}`)
+          console.log(`  ${chalk.dim('First Party:')}   ${client.firstParty}`)
+        } catch (err) {
+          console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+          process.exit(1)
+        } finally {
+          if (db) await shutdown(db)
+        }
+      }
+    )
+
+  // ── oauth2:purge ────────────────────────────────────────────────────
+
+  program
+    .command('oauth2:purge')
+    .description('Purge expired tokens and used authorization codes')
+    .option('--days <days>', 'Delete revoked tokens older than N days', '7')
+    .action(async (options: { days: string }) => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new OAuth2Manager(db, config)
+
+        const days = parseInt(options.days, 10)
+
+        console.log(chalk.dim('Purging expired tokens...'))
+        const tokenCount = await OAuthToken.prune(days)
+        console.log(chalk.green(`  ${tokenCount} token(s) pruned.`))
+
+        console.log(chalk.dim('Purging used/expired authorization codes...'))
+        const codeCount = await AuthCode.prune()
+        console.log(chalk.green(`  ${codeCount} authorization code(s) pruned.`))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+}

package/src/errors.ts

@@ -0,0 +1,62 @@
+import { StravError } from '@stravigor/core/exceptions/strav_error'
+
+/** Base error for all OAuth2 errors. */
+export class OAuth2Error extends StravError {
+  constructor(
+    message: string,
+    public readonly errorCode: string = 'server_error',
+    public readonly statusCode: number = 400
+  ) {
+    super(message)
+  }
+
+  /** Build a JSON response matching RFC 6749 error format. */
+  toJSON(): Record<string, string> {
+    return {
+      error: this.errorCode,
+      error_description: this.message,
+    }
+  }
+}
+
+/** The authorization grant type is not supported. */
+export class UnsupportedGrantError extends OAuth2Error {
+  constructor() {
+    super('The authorization grant type is not supported.', 'unsupported_grant_type')
+  }
+}
+
+/** Client authentication failed. */
+export class InvalidClientError extends OAuth2Error {
+  constructor(message = 'Client authentication failed.') {
+    super(message, 'invalid_client', 401)
+  }
+}
+
+/** The provided authorization grant is invalid or expired. */
+export class InvalidGrantError extends OAuth2Error {
+  constructor(message = 'The provided authorization grant is invalid, expired, or revoked.') {
+    super(message, 'invalid_grant')
+  }
+}
+
+/** The request is missing a required parameter or is malformed. */
+export class InvalidRequestError extends OAuth2Error {
+  constructor(message = 'The request is missing a required parameter.') {
+    super(message, 'invalid_request')
+  }
+}
+
+/** The requested scope is invalid or unknown. */
+export class InvalidScopeError extends OAuth2Error {
+  constructor(message = 'The requested scope is invalid or unknown.') {
+    super(message, 'invalid_scope')
+  }
+}
+
+/** The resource owner denied the authorization request. */
+export class AccessDeniedError extends OAuth2Error {
+  constructor(message = 'The resource owner denied the request.') {
+    super(message, 'access_denied', 403)
+  }
+}