@mantiq/oauth 0.1.0

package/src/grants/ClientCredentialsGrant.ts

@@ -0,0 +1,79 @@
+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 { AccessToken } from '../models/AccessToken.ts'
+import { OAuthError } from '../errors/OAuthError.ts'
+
+/**
+ * Client Credentials grant — machine-to-machine authentication.
+ * No user involved, no refresh token issued.
+ */
+export class ClientCredentialsGrant implements GrantHandler {
+  readonly grantType = 'client_credentials'
+
+  constructor(
+    private readonly signer: JwtSigner,
+    private readonly server: OAuthServer,
+  ) {}
+
+  async handle(request: MantiqRequest): Promise<OAuthTokenResponse> {
+    const clientId = await request.input('client_id') as string | undefined
+    const clientSecret = await request.input('client_secret') as string | undefined
+    const scopeParam = await request.input('scope') as string | undefined
+
+    if (!clientId) throw new OAuthError('The client_id parameter is required.', 'invalid_request')
+    if (!clientSecret) throw new OAuthError('The client_secret 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 secret
+    if (clientSecret !== client.getAttribute('secret')) {
+      throw new OAuthError('Invalid client credentials.', 'invalid_client', 401)
+    }
+
+    // Parse requested scopes
+    const scopes = scopeParam ? scopeParam.split(' ').filter(Boolean) : []
+
+    // Validate scopes
+    for (const scope of scopes) {
+      if (!this.server.hasScope(scope)) {
+        throw new OAuthError(`Invalid scope: ${scope}`, 'invalid_scope')
+      }
+    }
+
+    const tokenId = crypto.randomUUID()
+    const now = Math.floor(Date.now() / 1000)
+
+    // Create access token record (no user_id for client credentials)
+    await AccessToken.create({
+      id: tokenId,
+      user_id: null,
+      client_id: clientId,
+      name: null,
+      scopes: JSON.stringify(scopes),
+      revoked: false,
+      expires_at: new Date((now + this.server.tokenLifetime) * 1000).toISOString(),
+    })
+
+    // Sign JWT (no sub — no user)
+    const jwt = await this.signer.sign({
+      iss: 'mantiq-oauth',
+      aud: clientId,
+      exp: now + this.server.tokenLifetime,
+      iat: now,
+      jti: tokenId,
+      scopes,
+    })
+
+    return {
+      token_type: 'Bearer',
+      expires_in: this.server.tokenLifetime,
+      access_token: jwt,
+      scope: scopes.join(' ') || undefined,
+    }
+  }
+}

package/src/grants/GrantHandler.ts

@@ -0,0 +1,14 @@
+import type { MantiqRequest } from '@mantiq/core'
+
+export interface OAuthTokenResponse {
+  token_type: 'Bearer'
+  expires_in: number
+  access_token: string
+  refresh_token?: string
+  scope?: string
+}
+
+export interface GrantHandler {
+  readonly grantType: string
+  handle(request: MantiqRequest): Promise<OAuthTokenResponse>
+}

package/src/grants/PersonalAccessGrant.ts

@@ -0,0 +1,72 @@
+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 { AccessToken } from '../models/AccessToken.ts'
+import { OAuthError } from '../errors/OAuthError.ts'
+
+/**
+ * Personal Access Token grant — for authenticated users creating
+ * their own API tokens with specific scopes.
+ */
+export class PersonalAccessGrant implements GrantHandler {
+  readonly grantType = 'personal_access'
+
+  constructor(
+    private readonly signer: JwtSigner,
+    private readonly server: OAuthServer,
+  ) {}
+
+  async handle(request: MantiqRequest): Promise<OAuthTokenResponse> {
+    const user = request.user<any>()
+    if (!user) throw new OAuthError('User must be authenticated.', 'invalid_request', 401)
+
+    const scopeParam = await request.input('scope') as string | undefined
+    const name = await request.input('name') as string | undefined
+
+    // Parse requested scopes
+    const scopes = scopeParam ? scopeParam.split(' ').filter(Boolean) : []
+
+    // Validate scopes
+    for (const scope of scopes) {
+      if (!this.server.hasScope(scope)) {
+        throw new OAuthError(`Invalid scope: ${scope}`, 'invalid_scope')
+      }
+    }
+
+    const userId = typeof user.getAuthIdentifier === 'function'
+      ? user.getAuthIdentifier()
+      : user.id ?? user.getAttribute?.('id')
+
+    const tokenId = crypto.randomUUID()
+    const now = Math.floor(Date.now() / 1000)
+
+    // Create access token record
+    await AccessToken.create({
+      id: tokenId,
+      user_id: String(userId),
+      client_id: null,
+      name: name ?? 'Personal Access Token',
+      scopes: JSON.stringify(scopes),
+      revoked: false,
+      expires_at: new Date((now + this.server.tokenLifetime) * 1000).toISOString(),
+    })
+
+    // Sign JWT
+    const jwt = await this.signer.sign({
+      iss: 'mantiq-oauth',
+      sub: String(userId),
+      exp: now + this.server.tokenLifetime,
+      iat: now,
+      jti: tokenId,
+      scopes,
+    })
+
+    return {
+      token_type: 'Bearer',
+      expires_in: this.server.tokenLifetime,
+      access_token: jwt,
+      scope: scopes.join(' ') || undefined,
+    }
+  }
+}

package/src/grants/RefreshTokenGrant.ts

@@ -0,0 +1,129 @@
+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 { AccessToken } from '../models/AccessToken.ts'
+import { RefreshToken } from '../models/RefreshToken.ts'
+import { OAuthError } from '../errors/OAuthError.ts'
+
+/**
+ * Refresh Token grant — exchange a refresh token for a new token pair.
+ * Revokes the old access + refresh tokens and issues new ones.
+ */
+export class RefreshTokenGrant implements GrantHandler {
+  readonly grantType = 'refresh_token'
+
+  constructor(
+    private readonly signer: JwtSigner,
+    private readonly server: OAuthServer,
+  ) {}
+
+  async handle(request: MantiqRequest): Promise<OAuthTokenResponse> {
+    const refreshTokenId = await request.input('refresh_token') as string | undefined
+    const clientId = await request.input('client_id') as string | undefined
+    const clientSecret = await request.input('client_secret') as string | undefined
+    const scopeParam = await request.input('scope') as string | undefined
+
+    if (!refreshTokenId) throw new OAuthError('The refresh_token parameter is required.', 'invalid_request')
+    if (!clientId) throw new OAuthError('The client_id 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 secret for confidential clients
+    if (client.confidential()) {
+      if (!clientSecret || clientSecret !== client.getAttribute('secret')) {
+        throw new OAuthError('Invalid client credentials.', 'invalid_client', 401)
+      }
+    }
+
+    // Resolve refresh token
+    const refreshToken = await RefreshToken.find(refreshTokenId)
+    if (!refreshToken) throw new OAuthError('Invalid refresh token.', 'invalid_grant')
+
+    if (refreshToken.getAttribute('revoked')) {
+      throw new OAuthError('Refresh token has been revoked.', 'invalid_grant')
+    }
+
+    // Check expiration
+    const expiresAt = refreshToken.getAttribute('expires_at')
+    if (expiresAt && new Date(expiresAt) < new Date()) {
+      throw new OAuthError('Refresh token has expired.', 'invalid_grant')
+    }
+
+    // Resolve the original access token
+    const oldAccessTokenId = refreshToken.getAttribute('access_token_id') as string
+    const oldAccessToken = await AccessToken.find(oldAccessTokenId)
+    if (!oldAccessToken) throw new OAuthError('Associated access token not found.', 'invalid_grant')
+
+    // Verify the token belongs to this client
+    if (oldAccessToken.getAttribute('client_id') !== clientId) {
+      throw new OAuthError('Refresh token does not belong to this client.', 'invalid_grant')
+    }
+
+    // Revoke old tokens
+    await refreshToken.revoke()
+    if (!oldAccessToken.getAttribute('revoked')) {
+      await oldAccessToken.revoke()
+    }
+
+    // Determine scopes (keep original scopes, or narrow if requested)
+    const originalScopes = (oldAccessToken.getAttribute('scopes') as string[]) || []
+    let scopes = originalScopes
+
+    if (scopeParam) {
+      const requestedScopes = scopeParam.split(' ').filter(Boolean)
+      // Can only request a subset of original scopes
+      for (const scope of requestedScopes) {
+        if (!originalScopes.includes('*') && !originalScopes.includes(scope)) {
+          throw new OAuthError(`Scope "${scope}" was not granted on the original token.`, 'invalid_scope')
+        }
+      }
+      scopes = requestedScopes
+    }
+
+    // Issue new tokens
+    const userId = oldAccessToken.getAttribute('user_id') as string | null
+    const tokenId = crypto.randomUUID()
+    const now = Math.floor(Date.now() / 1000)
+
+    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(),
+    })
+
+    const newRefreshTokenId = crypto.randomUUID()
+    await RefreshToken.create({
+      id: newRefreshTokenId,
+      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 ?? undefined,
+      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: newRefreshTokenId,
+      scope: scopes.join(' '),
+    }
+  }
+}

package/src/guards/JwtGuard.ts

@@ -0,0 +1,95 @@
+import type { Guard } from '@mantiq/auth'
+import type { Authenticatable, UserProvider } from '@mantiq/auth'
+import type { MantiqRequest } from '@mantiq/core'
+import type { JwtSigner } from '../jwt/JwtSigner.ts'
+import { AccessToken } from '../models/AccessToken.ts'
+
+/**
+ * JWT-based stateless guard for OAuth access tokens.
+ * Extracts the bearer token, verifies the JWT signature,
+ * checks the token record in the database, and resolves the user.
+ */
+export class JwtGuard implements Guard {
+  private _user: Authenticatable | null = null
+  private _request: MantiqRequest | null = null
+  private _resolved = false
+
+  constructor(
+    private readonly signer: JwtSigner,
+    private readonly provider: UserProvider,
+  ) {}
+
+  async check(): Promise<boolean> {
+    return (await this.user()) !== null
+  }
+
+  async guest(): Promise<boolean> {
+    return !(await this.check())
+  }
+
+  async user(): Promise<Authenticatable | null> {
+    if (this._resolved) return this._user
+    this._resolved = true
+
+    if (!this._request) return null
+
+    const bearerToken = this._request.bearerToken()
+    if (!bearerToken) return null
+
+    // Verify JWT signature and expiration
+    const payload = await this.signer.verify(bearerToken)
+    if (!payload || !payload.jti) return null
+
+    // Look up the access token in the database
+    const accessToken = await AccessToken.find(payload.jti)
+    if (!accessToken) return null
+
+    // Check if revoked
+    if (accessToken.getAttribute('revoked')) return null
+
+    // Check if expired (belt-and-suspenders — JWT exp is already checked)
+    if (accessToken.isExpired()) return null
+
+    // For client_credentials tokens with no user
+    const userId = payload.sub
+    if (!userId) return null
+
+    // Resolve user from provider
+    const user = await this.provider.retrieveById(userId)
+    if (!user) return null
+
+    // Attach token info to the user if it supports it
+    if (typeof (user as any).withAccessToken === 'function') {
+      (user as any).withAccessToken(accessToken)
+    }
+
+    this._user = user
+    return user
+  }
+
+  async id(): Promise<string | number | null> {
+    const user = await this.user()
+    return user?.getAuthIdentifier() ?? null
+  }
+
+  async validate(credentials: Record<string, any>): Promise<boolean> {
+    const user = await this.provider.retrieveByCredentials(credentials)
+    if (!user) return false
+    return this.provider.validateCredentials(user, credentials)
+  }
+
+  setUser(user: Authenticatable): void {
+    this._user = user
+    this._resolved = true
+  }
+
+  hasUser(): boolean {
+    return this._user !== null
+  }
+
+  setRequest(request: MantiqRequest): void {
+    this._request = request
+    this._user = null
+    this._resolved = false
+  }
+}

package/src/helpers/oauth.ts

@@ -0,0 +1,15 @@
+import { Application } from '@mantiq/core'
+import type { OAuthServer } from '../OAuthServer.ts'
+
+export const OAUTH_SERVER = Symbol('OAuthServer')
+
+/**
+ * Access the OAuthServer singleton.
+ *
+ * @example
+ *   const server = oauth()
+ *   server.tokensCan({ 'read': 'Read data', 'write': 'Write data' })
+ */
+export function oauth(): OAuthServer {
+  return Application.getInstance().make<OAuthServer>(OAUTH_SERVER)
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+// ── JWT ──────────────────────────────────────────────────────────────────────
+export type { JwtPayload } from './jwt/JwtPayload.ts'
+export { base64UrlEncode, base64UrlDecode, base64UrlEncodeString, base64UrlDecodeString } from './jwt/JwtEncoder.ts'
+export { JwtSigner } from './jwt/JwtSigner.ts'
+
+// ── Models ───────────────────────────────────────────────────────────────────
+export { Client } from './models/Client.ts'
+export { AccessToken } from './models/AccessToken.ts'
+export { AuthCode } from './models/AuthCode.ts'
+export { RefreshToken } from './models/RefreshToken.ts'
+
+// ── Server ───────────────────────────────────────────────────────────────────
+export { OAuthServer } from './OAuthServer.ts'
+export type { OAuthConfig } from './OAuthServer.ts'
+
+// ── Grants ───────────────────────────────────────────────────────────────────
+export type { GrantHandler, OAuthTokenResponse } from './grants/GrantHandler.ts'
+export { AuthCodeGrant } from './grants/AuthCodeGrant.ts'
+export { ClientCredentialsGrant } from './grants/ClientCredentialsGrant.ts'
+export { RefreshTokenGrant } from './grants/RefreshTokenGrant.ts'
+export { PersonalAccessGrant } from './grants/PersonalAccessGrant.ts'
+
+// ── Guards ───────────────────────────────────────────────────────────────────
+export { JwtGuard } from './guards/JwtGuard.ts'
+
+// ── Middleware ────────────────────────────────────────────────────────────────
+export { CheckScopes } from './middleware/CheckScopes.ts'
+export { CheckForAnyScope } from './middleware/CheckForAnyScope.ts'
+export { CheckClientCredentials } from './middleware/CheckClientCredentials.ts'
+
+// ── Routes ───────────────────────────────────────────────────────────────────
+export { oauthRoutes } from './routes/oauthRoutes.ts'
+export type { OAuthRouteOptions } from './routes/oauthRoutes.ts'
+export { TokenController } from './routes/TokenController.ts'
+export { AuthorizationController } from './routes/AuthorizationController.ts'
+export { ClientController } from './routes/ClientController.ts'
+export { ScopeController } from './routes/ScopeController.ts'
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+export { OAuthInstallCommand } from './commands/OAuthInstallCommand.ts'
+export { OAuthKeysCommand } from './commands/OAuthKeysCommand.ts'
+export { OAuthClientCommand } from './commands/OAuthClientCommand.ts'
+export { OAuthPurgeCommand } from './commands/OAuthPurgeCommand.ts'
+
+// ── Migrations ───────────────────────────────────────────────────────────────
+export { CreateOAuthClientsTable } from './migrations/CreateOAuthClientsTable.ts'
+export { CreateOAuthAccessTokensTable } from './migrations/CreateOAuthAccessTokensTable.ts'
+export { CreateOAuthAuthCodesTable } from './migrations/CreateOAuthAuthCodesTable.ts'
+export { CreateOAuthRefreshTokensTable } from './migrations/CreateOAuthRefreshTokensTable.ts'
+
+// ── Errors ───────────────────────────────────────────────────────────────────
+export { OAuthError } from './errors/OAuthError.ts'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+export { oauth, OAUTH_SERVER } from './helpers/oauth.ts'
+
+// ── Service Provider ─────────────────────────────────────────────────────────
+export { OAuthServiceProvider } from './OAuthServiceProvider.ts'

package/src/jwt/JwtEncoder.ts

@@ -0,0 +1,51 @@
+/**
+ * Base64URL encode/decode utilities for JWT.
+ * No external dependencies — uses standard APIs only.
+ */
+
+/**
+ * Encode a Uint8Array to a Base64URL string (no padding).
+ */
+export function base64UrlEncode(data: Uint8Array): string {
+  let binary = ''
+  for (let i = 0; i < data.length; i++) {
+    binary += String.fromCharCode(data[i]!)
+  }
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+/**
+ * Decode a Base64URL string to a Uint8Array.
+ */
+export function base64UrlDecode(str: string): Uint8Array {
+  // Restore standard Base64 characters
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/')
+  // Restore padding
+  const pad = base64.length % 4
+  if (pad === 2) base64 += '=='
+  else if (pad === 3) base64 += '='
+
+  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
+}
+
+/**
+ * Encode a UTF-8 string to Base64URL.
+ */
+export function base64UrlEncodeString(str: string): string {
+  return base64UrlEncode(new TextEncoder().encode(str))
+}
+
+/**
+ * Decode a Base64URL string to a UTF-8 string.
+ */
+export function base64UrlDecodeString(str: string): string {
+  return new TextDecoder().decode(base64UrlDecode(str))
+}

package/src/jwt/JwtPayload.ts

@@ -0,0 +1,9 @@
+export interface JwtPayload {
+  iss?: string
+  sub?: string
+  aud?: string
+  exp?: number
+  iat?: number
+  jti?: string
+  scopes?: string[]
+}