@mantiq/oauth 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mantiq/oauth",
+  "version": "0.1.0",
+  "description": "OAuth 2.0 server — authorization code (PKCE), client credentials, JWT access tokens, scopes",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/mantiqjs/mantiq/tree/main/packages/oauth",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mantiqjs/mantiq.git",
+    "directory": "packages/oauth"
+  },
+  "bugs": {
+    "url": "https://github.com/mantiqjs/mantiq/issues"
+  },
+  "keywords": ["mantiq", "oauth", "oauth2", "jwt", "authorization", "token"],
+  "engines": { "bun": ">=1.1.0" },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": { ".": { "bun": "./src/index.ts", "default": "./src/index.ts" } },
+  "files": ["src/", "package.json", "README.md"],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --packages=external",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@mantiq/core": "^0.2.0",
+    "@mantiq/database": "^0.2.0",
+    "@mantiq/auth": "^0.2.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0",
+    "@mantiq/core": "workspace:*",
+    "@mantiq/database": "workspace:*",
+    "@mantiq/auth": "workspace:*"
+  }
+}

package/src/OAuthServer.ts

@@ -0,0 +1,75 @@
+export interface OAuthConfig {
+  /**
+   * Lifetime of access tokens in seconds.
+   * @default 3600 (1 hour)
+   */
+  tokenLifetime?: number
+
+  /**
+   * Lifetime of refresh tokens in seconds.
+   * @default 1209600 (14 days)
+   */
+  refreshTokenLifetime?: number
+
+  /**
+   * Path to the RSA private key PEM file.
+   */
+  privateKeyPath?: string
+
+  /**
+   * Path to the RSA public key PEM file.
+   */
+  publicKeyPath?: string
+}
+
+/**
+ * Central OAuth server configuration holder.
+ * Manages scopes and token lifetimes.
+ */
+export class OAuthServer {
+  private _scopes = new Map<string, string>()
+
+  constructor(private config: OAuthConfig) {}
+
+  get tokenLifetime(): number {
+    return this.config.tokenLifetime ?? 3600
+  }
+
+  get refreshTokenLifetime(): number {
+    return this.config.refreshTokenLifetime ?? 1209600
+  }
+
+  get privateKeyPath(): string {
+    return this.config.privateKeyPath ?? 'storage/oauth-private.key'
+  }
+
+  get publicKeyPath(): string {
+    return this.config.publicKeyPath ?? 'storage/oauth-public.key'
+  }
+
+  /**
+   * Register scopes that tokens can be issued with.
+   */
+  tokensCan(scopes: Record<string, string>): void {
+    for (const [id, description] of Object.entries(scopes)) {
+      this._scopes.set(id, description)
+    }
+  }
+
+  /**
+   * Check if a scope is registered.
+   */
+  hasScope(scope: string): boolean {
+    return this._scopes.has(scope)
+  }
+
+  /**
+   * Get all registered scopes.
+   */
+  scopes(): Array<{ id: string; description: string }> {
+    return Array.from(this._scopes.entries()).map(([id, description]) => ({
+      id,
+      description,
+    }))
+  }
+}

package/src/OAuthServiceProvider.ts

@@ -0,0 +1,89 @@
+import { ServiceProvider, ConfigRepository } from '@mantiq/core'
+import type { Router } from '@mantiq/core'
+import { ROUTER } from '@mantiq/core'
+import { AuthManager } from '@mantiq/auth'
+import { OAuthServer } from './OAuthServer.ts'
+import type { OAuthConfig } from './OAuthServer.ts'
+import { JwtSigner } from './jwt/JwtSigner.ts'
+import { JwtGuard } from './guards/JwtGuard.ts'
+import { CheckScopes } from './middleware/CheckScopes.ts'
+import { CheckForAnyScope } from './middleware/CheckForAnyScope.ts'
+import { CheckClientCredentials } from './middleware/CheckClientCredentials.ts'
+import { AuthCodeGrant } from './grants/AuthCodeGrant.ts'
+import { ClientCredentialsGrant } from './grants/ClientCredentialsGrant.ts'
+import { RefreshTokenGrant } from './grants/RefreshTokenGrant.ts'
+import { PersonalAccessGrant } from './grants/PersonalAccessGrant.ts'
+import { oauthRoutes } from './routes/oauthRoutes.ts'
+import { OAUTH_SERVER } from './helpers/oauth.ts'
+import { readFile } from 'node:fs/promises'
+
+const DEFAULT_CONFIG: OAuthConfig = {
+  tokenLifetime: 3600,
+  refreshTokenLifetime: 1209600,
+  privateKeyPath: 'storage/oauth-private.key',
+  publicKeyPath: 'storage/oauth-public.key',
+}
+
+/**
+ * Service provider for the OAuth package.
+ *
+ * register(): binds OAuthServer + JwtSigner as singletons
+ * boot(): loads keys, registers the 'oauth' guard on AuthManager, registers routes, binds middleware
+ */
+export class OAuthServiceProvider extends ServiceProvider {
+  override register(): void {
+    // OAuthServer singleton
+    this.app.singleton(OAuthServer, (c) => {
+      const config = c.make(ConfigRepository).get<OAuthConfig>('oauth', DEFAULT_CONFIG)
+      return new OAuthServer(config)
+    })
+    this.app.alias(OAuthServer, OAUTH_SERVER)
+
+    // JwtSigner singleton
+    this.app.singleton(JwtSigner, () => new JwtSigner())
+
+    // Middleware bindings
+    this.app.bind(CheckScopes, () => new CheckScopes())
+    this.app.bind(CheckForAnyScope, () => new CheckForAnyScope())
+    this.app.bind(CheckClientCredentials, (c) => new CheckClientCredentials(c.make(JwtSigner)))
+  }
+
+  override async boot(): Promise<void> {
+    const server = this.app.make(OAuthServer)
+    const signer = this.app.make(JwtSigner)
+
+    // Load RSA keys if they exist
+    try {
+      const privateKey = await readFile(server.privateKeyPath, 'utf-8')
+      const publicKey = await readFile(server.publicKeyPath, 'utf-8')
+      await signer.loadKeys(privateKey, publicKey)
+    } catch {
+      // Keys not yet generated — oauth:install must be run first
+    }
+
+    // Register 'oauth' guard on AuthManager
+    try {
+      const authManager = this.app.make(AuthManager)
+      authManager.extend('oauth', () => {
+        const provider = authManager.createUserProvider('users')
+        return new JwtGuard(signer, provider)
+      })
+    } catch {
+      // AuthManager not available — @mantiq/auth may not be installed
+    }
+
+    // Register OAuth routes
+    try {
+      const router = this.app.make<Router>(ROUTER)
+      const grants = [
+        new AuthCodeGrant(signer, server),
+        new ClientCredentialsGrant(signer, server),
+        new RefreshTokenGrant(signer, server),
+        new PersonalAccessGrant(signer, server),
+      ]
+      oauthRoutes(router, { server, grants })
+    } catch {
+      // Router not available
+    }
+  }
+}

package/src/commands/OAuthClientCommand.ts

@@ -0,0 +1,50 @@
+import { Command } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+import { Client } from '../models/Client.ts'
+
+/**
+ * Create a new OAuth client.
+ *
+ * Usage: mantiq oauth:client <name> [--redirect=URL] [--personal] [--password]
+ */
+export class OAuthClientCommand extends Command {
+  override name = 'oauth:client'
+  override description = 'Create a new OAuth client'
+  override usage = 'oauth:client <name> [--redirect=URL] [--personal] [--password]'
+
+  override async handle(args: ParsedArgs): Promise<number> {
+    const name = args.args[0]
+    if (!name) {
+      this.io.error('Client name is required.')
+      this.io.muted('  Usage: mantiq oauth:client <name> [--redirect=URL]')
+      return 1
+    }
+
+    const redirect = (args.flags['redirect'] as string) || 'http://localhost'
+    const personal = !!args.flags['personal']
+    const password = !!args.flags['password']
+
+    const clientId = crypto.randomUUID()
+    const secret = crypto.randomUUID()
+
+    await Client.create({
+      id: clientId,
+      name,
+      secret,
+      redirect,
+      personal_access_client: personal,
+      password_client: password,
+      revoked: false,
+    })
+
+    this.io.success(`OAuth client "${name}" created successfully.`)
+    this.io.newLine()
+    this.io.twoColumn('Client ID:', clientId)
+    this.io.twoColumn('Client Secret:', secret)
+    this.io.twoColumn('Redirect URL:', redirect)
+    this.io.twoColumn('Personal Access:', personal ? 'Yes' : 'No')
+    this.io.twoColumn('Password Grant:', password ? 'Yes' : 'No')
+
+    return 0
+  }
+}

package/src/commands/OAuthInstallCommand.ts

@@ -0,0 +1,67 @@
+import { Command } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+import { JwtSigner } from '../jwt/JwtSigner.ts'
+import { Client } from '../models/Client.ts'
+import { writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+
+/**
+ * Generate OAuth RSA keys and create a personal access client.
+ *
+ * Usage: mantiq oauth:install
+ */
+export class OAuthInstallCommand extends Command {
+  override name = 'oauth:install'
+  override description = 'Run the commands necessary to prepare OAuth for use'
+
+  override async handle(_args: ParsedArgs): Promise<number> {
+    this.io.info('Installing OAuth server...')
+
+    // Generate keys
+    const signer = new JwtSigner()
+    const keyPair = await signer.generateKeyPair()
+
+    const privatePath = 'storage/oauth-private.key'
+    const publicPath = 'storage/oauth-public.key'
+
+    const privateExists = existsSync(privatePath)
+    const publicExists = existsSync(publicPath)
+
+    if (privateExists || publicExists) {
+      this.io.warn('OAuth keys already exist. Skipping key generation.')
+    } else {
+      await writeFile(privatePath, keyPair.privateKey, 'utf-8')
+      await writeFile(publicPath, keyPair.publicKey, 'utf-8')
+      this.io.success('OAuth keys generated successfully.')
+      this.io.muted(`  Private key: ${privatePath}`)
+      this.io.muted(`  Public key:  ${publicPath}`)
+    }
+
+    // Create personal access client
+    const existingClient = await Client.where('personal_access_client', true).first()
+    if (existingClient) {
+      this.io.warn('Personal access client already exists. Skipping.')
+    } else {
+      const clientId = crypto.randomUUID()
+      const secret = crypto.randomUUID()
+
+      await Client.create({
+        id: clientId,
+        name: 'Personal Access Client',
+        secret,
+        redirect: 'http://localhost',
+        personal_access_client: true,
+        password_client: false,
+        revoked: false,
+      })
+
+      this.io.success('Personal access client created successfully.')
+      this.io.muted(`  Client ID:     ${clientId}`)
+      this.io.muted(`  Client Secret: ${secret}`)
+    }
+
+    this.io.newLine()
+    this.io.success('OAuth installation complete.')
+    return 0
+  }
+}

package/src/commands/OAuthKeysCommand.ts

@@ -0,0 +1,43 @@
+import { Command } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+import { JwtSigner } from '../jwt/JwtSigner.ts'
+import { writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+
+/**
+ * Generate the RSA key pair for signing JWTs.
+ *
+ * Usage: mantiq oauth:keys [--force]
+ */
+export class OAuthKeysCommand extends Command {
+  override name = 'oauth:keys'
+  override description = 'Generate the encryption keys for API authentication'
+  override usage = 'oauth:keys [--force]'
+
+  override async handle(args: ParsedArgs): Promise<number> {
+    const force = !!args.flags['force']
+    const privatePath = 'storage/oauth-private.key'
+    const publicPath = 'storage/oauth-public.key'
+
+    if (!force) {
+      if (existsSync(privatePath) || existsSync(publicPath)) {
+        this.io.error('OAuth keys already exist. Use --force to overwrite.')
+        return 1
+      }
+    }
+
+    this.io.info('Generating RSA key pair...')
+
+    const signer = new JwtSigner()
+    const keyPair = await signer.generateKeyPair()
+
+    await writeFile(privatePath, keyPair.privateKey, 'utf-8')
+    await writeFile(publicPath, keyPair.publicKey, 'utf-8')
+
+    this.io.success('OAuth keys generated successfully.')
+    this.io.muted(`  Private key: ${privatePath}`)
+    this.io.muted(`  Public key:  ${publicPath}`)
+
+    return 0
+  }
+}

package/src/commands/OAuthPurgeCommand.ts

@@ -0,0 +1,89 @@
+import { Command } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+import { AccessToken } from '../models/AccessToken.ts'
+import { RefreshToken } from '../models/RefreshToken.ts'
+import { AuthCode } from '../models/AuthCode.ts'
+
+/**
+ * Purge expired and revoked OAuth tokens.
+ *
+ * Usage: mantiq oauth:purge [--revoked]
+ */
+export class OAuthPurgeCommand extends Command {
+  override name = 'oauth:purge'
+  override description = 'Purge revoked and/or expired tokens and auth codes'
+  override usage = 'oauth:purge [--revoked]'
+
+  override async handle(args: ParsedArgs): Promise<number> {
+    const revokedOnly = !!args.flags['revoked']
+
+    this.io.info('Purging OAuth tokens...')
+
+    const now = new Date().toISOString()
+    let purgedTokens = 0
+    let purgedRefresh = 0
+    let purgedCodes = 0
+
+    if (revokedOnly) {
+      // Only purge revoked tokens
+      const revokedAccessTokens = await AccessToken.where('revoked', true).get()
+      for (const token of revokedAccessTokens) {
+        await token.delete()
+        purgedTokens++
+      }
+
+      const revokedRefreshTokens = await RefreshToken.where('revoked', true).get()
+      for (const token of revokedRefreshTokens) {
+        await token.delete()
+        purgedRefresh++
+      }
+
+      const revokedAuthCodes = await AuthCode.where('revoked', true).get()
+      for (const code of revokedAuthCodes) {
+        await code.delete()
+        purgedCodes++
+      }
+    } else {
+      // Purge expired + revoked
+      const expiredAccessTokens = await AccessToken.where('expires_at', '<', now).get()
+      const revokedAccessTokens = await AccessToken.where('revoked', true).get()
+      const allAccessTokens = new Map<string, typeof expiredAccessTokens[0]>()
+      for (const t of [...expiredAccessTokens, ...revokedAccessTokens]) {
+        allAccessTokens.set(t.getKey() as string, t)
+      }
+      for (const token of allAccessTokens.values()) {
+        await token.delete()
+        purgedTokens++
+      }
+
+      const expiredRefreshTokens = await RefreshToken.where('expires_at', '<', now).get()
+      const revokedRefreshTokens = await RefreshToken.where('revoked', true).get()
+      const allRefreshTokens = new Map<string, typeof expiredRefreshTokens[0]>()
+      for (const t of [...expiredRefreshTokens, ...revokedRefreshTokens]) {
+        allRefreshTokens.set(t.getKey() as string, t)
+      }
+      for (const token of allRefreshTokens.values()) {
+        await token.delete()
+        purgedRefresh++
+      }
+
+      const expiredAuthCodes = await AuthCode.where('expires_at', '<', now).get()
+      const revokedAuthCodes = await AuthCode.where('revoked', true).get()
+      const allAuthCodes = new Map<string, typeof expiredAuthCodes[0]>()
+      for (const c of [...expiredAuthCodes, ...revokedAuthCodes]) {
+        allAuthCodes.set(c.getKey() as string, c)
+      }
+      for (const code of allAuthCodes.values()) {
+        await code.delete()
+        purgedCodes++
+      }
+    }
+
+    this.io.success('Purge complete.')
+    this.io.twoColumn('Access tokens purged:', String(purgedTokens))
+    this.io.twoColumn('Refresh tokens purged:', String(purgedRefresh))
+    this.io.twoColumn('Auth codes purged:', String(purgedCodes))
+
+    return 0
+  }
+}

package/src/errors/OAuthError.ts

@@ -0,0 +1,22 @@
+import { HttpError } from '@mantiq/core'
+
+/**
+ * OAuth-specific error.
+ * Defaults to 400 Bad Request. Use a different status code for specific cases.
+ */
+export class OAuthError extends HttpError {
+  constructor(
+    message: string,
+    public readonly errorCode: string = 'invalid_request',
+    statusCode = 400,
+  ) {
+    super(statusCode, message)
+  }
+
+  toJSON(): Record<string, any> {
+    return {
+      error: this.errorCode,
+      error_description: this.message,
+    }
+  }
+}

package/src/grants/AuthCodeGrant.ts

@@ -0,0 +1,159 @@
+import type { MantiqRequest } from '@mantiq/core'
+import type { GrantHandler, OAuthTokenResponse } from './GrantHandler.ts'
+import type { JwtSigner } from '../jwt/JwtSigner.ts'
+import type { OAuthServer } from '../OAuthServer.ts'
+import { Client } from '../models/Client.ts'
+import { AuthCode } from '../models/AuthCode.ts'
+import { AccessToken } from '../models/AccessToken.ts'
+import { RefreshToken } from '../models/RefreshToken.ts'
+import { OAuthError } from '../errors/OAuthError.ts'
+
+/**
+ * Authorization Code grant with PKCE support.
+ */
+export class AuthCodeGrant implements GrantHandler {
+  readonly grantType = 'authorization_code'
+
+  constructor(
+    private readonly signer: JwtSigner,
+    private readonly server: OAuthServer,
+  ) {}
+
+  async handle(request: MantiqRequest): Promise<OAuthTokenResponse> {
+    const code = await request.input('code') as string | undefined
+    const redirectUri = await request.input('redirect_uri') as string | undefined
+    const clientId = await request.input('client_id') as string | undefined
+    const clientSecret = await request.input('client_secret') as string | undefined
+    const codeVerifier = await request.input('code_verifier') as string | undefined
+
+    if (!code) throw new OAuthError('The code parameter is required.', 'invalid_request')
+    if (!clientId) throw new OAuthError('The client_id parameter is required.', 'invalid_request')
+    if (!redirectUri) throw new OAuthError('The redirect_uri parameter is required.', 'invalid_request')
+
+    // Resolve client
+    const client = await Client.find(clientId)
+    if (!client) throw new OAuthError('Client not found.', 'invalid_client', 401)
+
+    // Verify client secret for confidential clients
+    if (client.confidential()) {
+      if (!clientSecret || clientSecret !== client.getAttribute('secret')) {
+        throw new OAuthError('Invalid client credentials.', 'invalid_client', 401)
+      }
+    }
+
+    // Resolve auth code
+    const authCode = await AuthCode.where('id', code)
+      .where('revoked', false)
+      .first() as AuthCode | null
+
+    if (!authCode) throw new OAuthError('Invalid authorization code.', 'invalid_grant')
+
+    // Verify the code belongs to this client
+    if (authCode.getAttribute('client_id') !== clientId) {
+      throw new OAuthError('Authorization code does not belong to this client.', 'invalid_grant')
+    }
+
+    // Check expiration
+    const expiresAt = authCode.getAttribute('expires_at')
+    if (expiresAt && new Date(expiresAt) < new Date()) {
+      throw new OAuthError('Authorization code has expired.', 'invalid_grant')
+    }
+
+    // Verify PKCE code_challenge
+    const storedChallenge = authCode.getAttribute('code_challenge') as string | null
+    const challengeMethod = (authCode.getAttribute('code_challenge_method') as string) || 'plain'
+
+    if (storedChallenge) {
+      if (!codeVerifier) {
+        throw new OAuthError('The code_verifier parameter is required.', 'invalid_request')
+      }
+      const isValid = await this.verifyCodeChallenge(codeVerifier, storedChallenge, challengeMethod)
+      if (!isValid) {
+        throw new OAuthError('Invalid code verifier.', 'invalid_grant')
+      }
+    }
+
+    // Revoke the auth code (single use)
+    authCode.setAttribute('revoked', true)
+    await authCode.save()
+
+    // Issue tokens
+    const userId = authCode.getAttribute('user_id') as string
+    const scopes = (authCode.getAttribute('scopes') as string[]) || []
+    const tokenId = crypto.randomUUID()
+    const now = Math.floor(Date.now() / 1000)
+
+    // Create access token record
+    await AccessToken.create({
+      id: tokenId,
+      user_id: userId,
+      client_id: clientId,
+      name: null,
+      scopes: JSON.stringify(scopes),
+      revoked: false,
+      expires_at: new Date((now + this.server.tokenLifetime) * 1000).toISOString(),
+    })
+
+    // Create refresh token
+    const refreshTokenId = crypto.randomUUID()
+    await RefreshToken.create({
+      id: refreshTokenId,
+      access_token_id: tokenId,
+      revoked: false,
+      expires_at: new Date((now + this.server.refreshTokenLifetime) * 1000).toISOString(),
+    })
+
+    // Sign JWT
+    const jwt = await this.signer.sign({
+      iss: 'mantiq-oauth',
+      sub: userId,
+      aud: clientId,
+      exp: now + this.server.tokenLifetime,
+      iat: now,
+      jti: tokenId,
+      scopes,
+    })
+
+    return {
+      token_type: 'Bearer',
+      expires_in: this.server.tokenLifetime,
+      access_token: jwt,
+      refresh_token: refreshTokenId,
+      scope: scopes.join(' '),
+    }
+  }
+
+  /**
+   * Verify the PKCE code challenge.
+   */
+  private async verifyCodeChallenge(
+    codeVerifier: string,
+    codeChallenge: string,
+    method: string,
+  ): Promise<boolean> {
+    if (method === 'plain') {
+      return codeVerifier === codeChallenge
+    }
+
+    if (method === 'S256') {
+      const encoder = new TextEncoder()
+      const data = encoder.encode(codeVerifier)
+      const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+      const hashArray = new Uint8Array(hashBuffer)
+
+      // Base64URL encode the hash
+      let binary = ''
+      for (let i = 0; i < hashArray.length; i++) {
+        binary += String.fromCharCode(hashArray[i]!)
+      }
+      const base64url = btoa(binary)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '')
+
+      return base64url === codeChallenge
+    }
+
+    throw new OAuthError(`Unsupported code challenge method: ${method}`, 'invalid_request')
+  }
+}