@mantiq/oauth 0.1.0

package/src/jwt/JwtSigner.ts

@@ -0,0 +1,175 @@
+import type { JwtPayload } from './JwtPayload.ts'
+import { base64UrlEncode, base64UrlDecode, base64UrlEncodeString } from './JwtEncoder.ts'
+
+const ALGORITHM: RsaHashedImportParams = {
+  name: 'RSASSA-PKCS1-v1_5',
+  hash: 'SHA-256',
+}
+
+/**
+ * RS256 JWT signer/verifier using the Web Crypto API.
+ * No external dependencies.
+ */
+export class JwtSigner {
+  private privateKey: CryptoKey | null = null
+  private publicKey: CryptoKey | null = null
+
+  /**
+   * Import RSA keys from PEM strings.
+   */
+  async loadKeys(privatePem: string, publicPem: string): Promise<void> {
+    this.privateKey = await importPrivateKey(privatePem)
+    this.publicKey = await importPublicKey(publicPem)
+  }
+
+  /**
+   * Create a signed JWT string (header.payload.signature).
+   */
+  async sign(payload: JwtPayload): Promise<string> {
+    if (!this.privateKey) {
+      throw new Error('Private key not loaded. Call loadKeys() first.')
+    }
+
+    // Auto-set iat if not provided
+    if (!payload.iat) {
+      payload = { ...payload, iat: Math.floor(Date.now() / 1000) }
+    }
+
+    const header = { alg: 'RS256', typ: 'JWT' }
+    const headerEncoded = base64UrlEncodeString(JSON.stringify(header))
+    const payloadEncoded = base64UrlEncodeString(JSON.stringify(payload))
+
+    const signingInput = `${headerEncoded}.${payloadEncoded}`
+    const data = new TextEncoder().encode(signingInput)
+
+    const signature = await crypto.subtle.sign(
+      ALGORITHM.name,
+      this.privateKey,
+      data,
+    )
+
+    const signatureEncoded = base64UrlEncode(new Uint8Array(signature))
+    return `${signingInput}.${signatureEncoded}`
+  }
+
+  /**
+   * Verify a JWT token and return the decoded payload.
+   * Returns null if the token is invalid or expired.
+   */
+  async verify(token: string): Promise<JwtPayload | null> {
+    if (!this.publicKey) {
+      throw new Error('Public key not loaded. Call loadKeys() first.')
+    }
+
+    const parts = token.split('.')
+    if (parts.length !== 3) return null
+
+    const [headerEncoded, payloadEncoded, signatureEncoded] = parts as [string, string, string]
+
+    try {
+      const signingInput = `${headerEncoded}.${payloadEncoded}`
+      const data = new TextEncoder().encode(signingInput)
+      const signature = base64UrlDecode(signatureEncoded)
+
+      const valid = await crypto.subtle.verify(
+        ALGORITHM.name,
+        this.publicKey,
+        signature,
+        data,
+      )
+
+      if (!valid) return null
+
+      const payloadJson = new TextDecoder().decode(base64UrlDecode(payloadEncoded))
+      const payload: JwtPayload = JSON.parse(payloadJson)
+
+      // Check expiration
+      if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
+        return null
+      }
+
+      return payload
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Generate a new RSA key pair and return as PEM strings.
+   */
+  async generateKeyPair(): Promise<{ privateKey: string; publicKey: string }> {
+    const keyPair = await crypto.subtle.generateKey(
+      {
+        name: 'RSASSA-PKCS1-v1_5',
+        modulusLength: 2048,
+        publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+        hash: 'SHA-256',
+      },
+      true, // extractable
+      ['sign', 'verify'],
+    )
+
+    const privateDer = await crypto.subtle.exportKey('pkcs8', keyPair.privateKey)
+    const publicDer = await crypto.subtle.exportKey('spki', keyPair.publicKey)
+
+    return {
+      privateKey: derToPem(privateDer, 'PRIVATE'),
+      publicKey: derToPem(publicDer, 'PUBLIC'),
+    }
+  }
+}
+
+// ── PEM helpers ────────────────────────────────────────────────────────────────
+
+function pemToDer(pem: string): ArrayBuffer {
+  const lines = pem.split('\n').filter(
+    (line) => !line.startsWith('-----') && line.trim().length > 0,
+  )
+  const base64 = lines.join('')
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes.buffer
+}
+
+function derToPem(der: ArrayBuffer, type: 'PRIVATE' | 'PUBLIC'): string {
+  const bytes = new Uint8Array(der)
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!)
+  }
+  const base64 = btoa(binary)
+
+  // Wrap at 64 characters
+  const lines: string[] = []
+  for (let i = 0; i < base64.length; i += 64) {
+    lines.push(base64.slice(i, i + 64))
+  }
+
+  const label = type === 'PRIVATE' ? 'PRIVATE KEY' : 'PUBLIC KEY'
+  return `-----BEGIN ${label}-----\n${lines.join('\n')}\n-----END ${label}-----`
+}
+
+async function importPrivateKey(pem: string): Promise<CryptoKey> {
+  const der = pemToDer(pem)
+  return crypto.subtle.importKey(
+    'pkcs8',
+    der,
+    ALGORITHM,
+    false,
+    ['sign'],
+  )
+}
+
+async function importPublicKey(pem: string): Promise<CryptoKey> {
+  const der = pemToDer(pem)
+  return crypto.subtle.importKey(
+    'spki',
+    der,
+    ALGORITHM,
+    false,
+    ['verify'],
+  )
+}

package/src/middleware/CheckClientCredentials.ts

@@ -0,0 +1,60 @@
+import type { MantiqRequest } from '@mantiq/core'
+import type { JwtSigner } from '../jwt/JwtSigner.ts'
+import { AccessToken } from '../models/AccessToken.ts'
+
+/**
+ * Middleware for client_credentials grant tokens.
+ * These tokens have no user — just a client.
+ * Validates the JWT and checks that the token exists and has the required scopes.
+ *
+ * Usage in route middleware: 'client:read,write'
+ */
+export class CheckClientCredentials {
+  private scopes: string[] = []
+
+  constructor(private readonly signer: JwtSigner) {}
+
+  setParameters(...scopes: string[]): void {
+    this.scopes = scopes
+  }
+
+  async handle(request: MantiqRequest, next: () => Promise<Response>): Promise<Response> {
+    const bearerToken = request.bearerToken()
+    if (!bearerToken) {
+      return new Response(
+        JSON.stringify({ message: 'Unauthenticated.' }),
+        { status: 401, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    // Verify JWT
+    const payload = await this.signer.verify(bearerToken)
+    if (!payload || !payload.jti) {
+      return new Response(
+        JSON.stringify({ message: 'Invalid token.' }),
+        { status: 401, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    // Look up the access token
+    const accessToken = await AccessToken.find(payload.jti)
+    if (!accessToken || accessToken.getAttribute('revoked') || accessToken.isExpired()) {
+      return new Response(
+        JSON.stringify({ message: 'Token is invalid or expired.' }),
+        { status: 401, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    // Check required scopes
+    for (const scope of this.scopes) {
+      if (accessToken.cant(scope)) {
+        return new Response(
+          JSON.stringify({ message: `Missing scope: ${scope}` }),
+          { status: 403, headers: { 'Content-Type': 'application/json' } },
+        )
+      }
+    }
+
+    return next()
+  }
+}

package/src/middleware/CheckForAnyScope.ts

@@ -0,0 +1,52 @@
+import type { MantiqRequest } from '@mantiq/core'
+import { AccessToken } from '../models/AccessToken.ts'
+
+/**
+ * Middleware that requires at least ONE of the listed scopes on the JWT token.
+ *
+ * Usage in route middleware: 'scope:read,write'
+ */
+export class CheckForAnyScope {
+  private scopes: string[] = []
+
+  setParameters(...scopes: string[]): void {
+    this.scopes = scopes
+  }
+
+  async handle(request: MantiqRequest, next: () => Promise<Response>): Promise<Response> {
+    const user = request.user<any>()
+    if (!user) {
+      return new Response(
+        JSON.stringify({ message: 'Unauthenticated.' }),
+        { status: 401, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    // Get the access token from the user
+    const token = this.resolveToken(user)
+    if (!token) {
+      return new Response(
+        JSON.stringify({ message: 'Token not found.' }),
+        { status: 403, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    const hasAny = this.scopes.some((scope) => token.can(scope))
+    if (!hasAny) {
+      return new Response(
+        JSON.stringify({ message: 'Insufficient scopes.' }),
+        { status: 403, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    return next()
+  }
+
+  private resolveToken(user: any): AccessToken | null {
+    if (typeof user.currentAccessToken === 'function') {
+      return user.currentAccessToken() as AccessToken | null
+    }
+    if (user._accessToken) return user._accessToken as AccessToken
+    return null
+  }
+}

package/src/middleware/CheckScopes.ts

@@ -0,0 +1,53 @@
+import type { MantiqRequest } from '@mantiq/core'
+import { AccessToken } from '../models/AccessToken.ts'
+
+/**
+ * Middleware that requires ALL listed scopes on the JWT token.
+ *
+ * Usage in route middleware: 'scopes:read,write'
+ */
+export class CheckScopes {
+  private scopes: string[] = []
+
+  setParameters(...scopes: string[]): void {
+    this.scopes = scopes
+  }
+
+  async handle(request: MantiqRequest, next: () => Promise<Response>): Promise<Response> {
+    const user = request.user<any>()
+    if (!user) {
+      return new Response(
+        JSON.stringify({ message: 'Unauthenticated.' }),
+        { status: 401, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    // Get the access token from the user
+    const token = this.resolveToken(user)
+    if (!token) {
+      return new Response(
+        JSON.stringify({ message: 'Token not found.' }),
+        { status: 403, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    for (const scope of this.scopes) {
+      if (token.cant(scope)) {
+        return new Response(
+          JSON.stringify({ message: `Missing scope: ${scope}` }),
+          { status: 403, headers: { 'Content-Type': 'application/json' } },
+        )
+      }
+    }
+
+    return next()
+  }
+
+  private resolveToken(user: any): AccessToken | null {
+    if (typeof user.currentAccessToken === 'function') {
+      return user.currentAccessToken() as AccessToken | null
+    }
+    if (user._accessToken) return user._accessToken as AccessToken
+    return null
+  }
+}

package/src/migrations/CreateOAuthAccessTokensTable.ts

@@ -0,0 +1,21 @@
+import { Migration } from '@mantiq/database'
+import type { SchemaBuilder } from '@mantiq/database'
+
+export class CreateOAuthAccessTokensTable extends Migration {
+  override async up(schema: SchemaBuilder): Promise<void> {
+    await schema.create('oauth_access_tokens', (table) => {
+      table.uuid('id').primary()
+      table.string('user_id').nullable()
+      table.uuid('client_id').nullable()
+      table.string('name').nullable()
+      table.json('scopes').nullable()
+      table.boolean('revoked').default(false)
+      table.timestamp('expires_at').nullable()
+      table.timestamps()
+    })
+  }
+
+  override async down(schema: SchemaBuilder): Promise<void> {
+    await schema.dropIfExists('oauth_access_tokens')
+  }
+}

package/src/migrations/CreateOAuthAuthCodesTable.ts

@@ -0,0 +1,22 @@
+import { Migration } from '@mantiq/database'
+import type { SchemaBuilder } from '@mantiq/database'
+
+export class CreateOAuthAuthCodesTable extends Migration {
+  override async up(schema: SchemaBuilder): Promise<void> {
+    await schema.create('oauth_auth_codes', (table) => {
+      table.uuid('id').primary()
+      table.string('user_id')
+      table.uuid('client_id')
+      table.json('scopes').nullable()
+      table.boolean('revoked').default(false)
+      table.timestamp('expires_at').nullable()
+      table.string('code_challenge').nullable()
+      table.string('code_challenge_method').nullable()
+      table.timestamps()
+    })
+  }
+
+  override async down(schema: SchemaBuilder): Promise<void> {
+    await schema.dropIfExists('oauth_auth_codes')
+  }
+}

package/src/migrations/CreateOAuthClientsTable.ts

@@ -0,0 +1,24 @@
+import { Migration } from '@mantiq/database'
+import type { SchemaBuilder } from '@mantiq/database'
+
+export class CreateOAuthClientsTable extends Migration {
+  override async up(schema: SchemaBuilder): Promise<void> {
+    await schema.create('oauth_clients', (table) => {
+      table.uuid('id').primary()
+      table.string('user_id').nullable()
+      table.string('name')
+      table.string('secret', 100).nullable()
+      table.string('redirect')
+      table.json('grant_types').nullable()
+      table.json('scopes').nullable()
+      table.boolean('personal_access_client').default(false)
+      table.boolean('password_client').default(false)
+      table.boolean('revoked').default(false)
+      table.timestamps()
+    })
+  }
+
+  override async down(schema: SchemaBuilder): Promise<void> {
+    await schema.dropIfExists('oauth_clients')
+  }
+}

package/src/migrations/CreateOAuthRefreshTokensTable.ts

@@ -0,0 +1,18 @@
+import { Migration } from '@mantiq/database'
+import type { SchemaBuilder } from '@mantiq/database'
+
+export class CreateOAuthRefreshTokensTable extends Migration {
+  override async up(schema: SchemaBuilder): Promise<void> {
+    await schema.create('oauth_refresh_tokens', (table) => {
+      table.uuid('id').primary()
+      table.uuid('access_token_id')
+      table.boolean('revoked').default(false)
+      table.timestamp('expires_at').nullable()
+      table.timestamps()
+    })
+  }
+
+  override async down(schema: SchemaBuilder): Promise<void> {
+    await schema.dropIfExists('oauth_refresh_tokens')
+  }
+}

package/src/models/AccessToken.ts

@@ -0,0 +1,52 @@
+import { Model } from '@mantiq/database'
+
+export class AccessToken extends Model {
+  static override table = 'oauth_access_tokens'
+  static override keyType = 'string' as const
+  static override incrementing = false
+  static override fillable = [
+    'user_id',
+    'client_id',
+    'name',
+    'scopes',
+    'revoked',
+    'expires_at',
+  ]
+  static override casts = {
+    scopes: 'json' as const,
+    revoked: 'boolean' as const,
+  }
+
+  /**
+   * Check if the token has the given scope.
+   */
+  can(scope: string): boolean {
+    const scopes = this.getAttribute('scopes') as string[] | null
+    if (!scopes) return false
+    return scopes.includes('*') || scopes.includes(scope)
+  }
+
+  /**
+   * Check if the token does NOT have the given scope.
+   */
+  cant(scope: string): boolean {
+    return !this.can(scope)
+  }
+
+  /**
+   * Revoke the access token.
+   */
+  async revoke(): Promise<void> {
+    this.setAttribute('revoked', true)
+    await this.save()
+  }
+
+  /**
+   * Check if the token has expired.
+   */
+  isExpired(): boolean {
+    const expiresAt = this.getAttribute('expires_at')
+    if (!expiresAt) return false
+    return new Date(expiresAt) < new Date()
+  }
+}

package/src/models/AuthCode.ts

@@ -0,0 +1,20 @@
+import { Model } from '@mantiq/database'
+
+export class AuthCode extends Model {
+  static override table = 'oauth_auth_codes'
+  static override keyType = 'string' as const
+  static override incrementing = false
+  static override fillable = [
+    'user_id',
+    'client_id',
+    'scopes',
+    'revoked',
+    'expires_at',
+    'code_challenge',
+    'code_challenge_method',
+  ]
+  static override casts = {
+    scopes: 'json' as const,
+    revoked: 'boolean' as const,
+  }
+}

package/src/models/Client.ts

@@ -0,0 +1,36 @@
+import { Model } from '@mantiq/database'
+
+export class Client extends Model {
+  static override table = 'oauth_clients'
+  static override keyType = 'string' as const
+  static override incrementing = false
+  static override fillable = [
+    'name',
+    'secret',
+    'redirect',
+    'personal_access_client',
+    'password_client',
+  ]
+  static override hidden = ['secret']
+  static override casts = {
+    grant_types: 'json' as const,
+    scopes: 'json' as const,
+    personal_access_client: 'boolean' as const,
+    password_client: 'boolean' as const,
+    revoked: 'boolean' as const,
+  }
+
+  /**
+   * Check if the client is a confidential client (has a secret).
+   */
+  confidential(): boolean {
+    return !!this.getAttribute('secret')
+  }
+
+  /**
+   * Check if the client is a first-party (personal access) client.
+   */
+  firstParty(): boolean {
+    return !!this.getAttribute('personal_access_client')
+  }
+}

package/src/models/RefreshToken.ts

@@ -0,0 +1,23 @@
+import { Model } from '@mantiq/database'
+
+export class RefreshToken extends Model {
+  static override table = 'oauth_refresh_tokens'
+  static override keyType = 'string' as const
+  static override incrementing = false
+  static override fillable = [
+    'access_token_id',
+    'revoked',
+    'expires_at',
+  ]
+  static override casts = {
+    revoked: 'boolean' as const,
+  }
+
+  /**
+   * Revoke the refresh token.
+   */
+  async revoke(): Promise<void> {
+    this.setAttribute('revoked', true)
+    await this.save()
+  }
+}