@mantiq/auth 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/auth",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Session & token auth, guards, providers",
   "type": "module",
   "license": "MIT",

package/src/AuthManager.ts

@@ -7,6 +7,7 @@ import type { Authenticatable } from './contracts/Authenticatable.ts'
 import type { AuthConfig } from './contracts/AuthConfig.ts'
 import { SessionGuard } from './guards/SessionGuard.ts'
 import { RequestGuard } from './guards/RequestGuard.ts'
+import { TokenGuard } from './guards/TokenGuard.ts'
 import { DatabaseUserProvider } from './providers/DatabaseUserProvider.ts'
 
 type RequestGuardCallback = (
@@ -208,6 +209,10 @@ export class AuthManager implements DriverManager<Guard> {
         }
         return new SessionGuard(name, provider, encrypter)
       }
+      case 'token': {
+        const provider = this.createUserProvider(guardConfig.provider)
+        return new TokenGuard(name, provider, guardConfig.trackLastUsed ?? false)
+      }
       default: {
         throw new Error(
           `Unsupported auth guard driver: "${guardConfig.driver}". ` +

package/src/AuthServiceProvider.ts

@@ -1,10 +1,13 @@
-import { ServiceProvider, ConfigRepository } from '@mantiq/core'
+import { ServiceProvider, ConfigRepository, HttpKernel } from '@mantiq/core'
 import { AuthManager } from './AuthManager.ts'
 import { AUTH_MANAGER } from './helpers/auth.ts'
 import { Authenticate } from './middleware/Authenticate.ts'
 import { RedirectIfAuthenticated } from './middleware/RedirectIfAuthenticated.ts'
 import { EnsureEmailIsVerified } from './middleware/EnsureEmailIsVerified.ts'
 import { ConfirmPassword } from './middleware/ConfirmPassword.ts'
+import { Authorize } from './middleware/Authorize.ts'
+import { GateManager } from './authorization/GateManager.ts'
+import { setGateManager, GATE_MANAGER } from './helpers/gate.ts'
 import type { AuthConfig } from './contracts/AuthConfig.ts'
 
 const DEFAULT_CONFIG: AuthConfig = {
@@ -18,7 +21,7 @@ const DEFAULT_CONFIG: AuthConfig = {
 }
 
 /**
- * Registers authentication bindings in the container.
+ * Registers authentication and authorization bindings in the container.
  *
  * Config file: config/auth.ts
  * Required config: guards, providers, defaults.guard
@@ -32,10 +35,32 @@ export class AuthServiceProvider extends ServiceProvider {
     })
     this.app.alias(AuthManager, AUTH_MANAGER)
 
+    // GateManager — singleton
+    this.app.singleton(GateManager, () => {
+      const g = new GateManager()
+      setGateManager(g)
+      return g
+    })
+    this.app.alias(GateManager, GATE_MANAGER)
+
     // Middleware bindings
     this.app.bind(Authenticate, (c) => new Authenticate(c.make(AuthManager)))
     this.app.bind(RedirectIfAuthenticated, (c) => new RedirectIfAuthenticated(c.make(AuthManager)))
     this.app.bind(EnsureEmailIsVerified, () => new EnsureEmailIsVerified())
     this.app.bind(ConfirmPassword, () => new ConfirmPassword())
+    this.app.bind(Authorize, () => new Authorize())
+  }
+
+  override boot(): void {
+    // Resolve the GateManager so setGateManager() is called
+    this.app.make(GateManager)
+
+    // Register the 'can' middleware alias
+    try {
+      const kernel = this.app.make(HttpKernel)
+      kernel.registerMiddleware('can', Authorize)
+    } catch {
+      // HttpKernel may not be available in non-HTTP contexts (e.g., CLI)
+    }
   }
 }

package/src/Authorizable.ts

@@ -0,0 +1,22 @@
+import { gate } from './helpers/gate.ts'
+
+/**
+ * Mixin that adds `can()` / `cannot()` to model instances.
+ *
+ * Apply to any model class to allow authorization checks directly
+ * on the model instance:
+ *
+ * @example
+ * applyAuthorizable(User)
+ * const user = await User.find(1)
+ * if (await user.can('edit', post)) { ... }
+ */
+export function applyAuthorizable(ModelClass: any): void {
+  ModelClass.prototype.can = async function (ability: string, ...args: any[]): Promise<boolean> {
+    return gate().allows(ability, this, ...args)
+  }
+
+  ModelClass.prototype.cannot = async function (ability: string, ...args: any[]): Promise<boolean> {
+    return gate().denies(ability, this, ...args)
+  }
+}

package/src/HasApiTokens.ts

@@ -0,0 +1,58 @@
+import { PersonalAccessToken } from './models/PersonalAccessToken.ts'
+import { sha256 } from './helpers/hash.ts'
+import type { NewAccessToken } from './contracts/NewAccessToken.ts'
+
+export function applyHasApiTokens(ModelClass: any): void {
+  // Store current access token on instance
+  const proto = ModelClass.prototype
+
+  proto.createToken = async function(name: string, abilities: string[] = ['*'], expiresAt?: Date): Promise<NewAccessToken> {
+    // Generate 64 random hex characters
+    const randomBytes = new Uint8Array(32)
+    crypto.getRandomValues(randomBytes)
+    const plaintext = Array.from(randomBytes).map(b => b.toString(16).padStart(2, '0')).join('')
+
+    const hash = await sha256(plaintext)
+
+    const ctor = this.constructor as any
+    const token = await PersonalAccessToken.create({
+      tokenable_type: ctor.table ?? ctor.name?.toLowerCase() + 's',
+      tokenable_id: this.getKey(),
+      name,
+      token: hash,
+      abilities: JSON.stringify(abilities),
+      expires_at: expiresAt?.toISOString() ?? null,
+    })
+
+    const id = token.getKey()
+    return {
+      accessToken: token,
+      plainTextToken: `${id}|${plaintext}`,
+    }
+  }
+
+  proto.tokens = function() {
+    const ctor = this.constructor as any
+    return PersonalAccessToken.where('tokenable_type', ctor.table ?? ctor.name?.toLowerCase() + 's')
+      .where('tokenable_id', this.getKey())
+  }
+
+  proto.currentAccessToken = function(): PersonalAccessToken | null {
+    return this._currentAccessToken ?? null
+  }
+
+  proto.withAccessToken = function(token: PersonalAccessToken): any {
+    this._currentAccessToken = token
+    return this
+  }
+
+  proto.tokenCan = function(ability: string): boolean {
+    const token = this.currentAccessToken()
+    if (!token) return false
+    return token.can(ability)
+  }
+
+  proto.tokenCant = function(ability: string): boolean {
+    return !this.tokenCan(ability)
+  }
+}

package/src/authorization/AuthorizationResponse.ts

@@ -0,0 +1,35 @@
+export class AuthorizationResponse {
+  private _allowed: boolean
+  private _message: string | null
+  private _code: number | null
+
+  constructor(allowed: boolean, message?: string, code?: number) {
+    this._allowed = allowed
+    this._message = message ?? null
+    this._code = code ?? null
+  }
+
+  allowed(): boolean {
+    return this._allowed
+  }
+
+  denied(): boolean {
+    return !this._allowed
+  }
+
+  message(): string | null {
+    return this._message
+  }
+
+  code(): number | null {
+    return this._code
+  }
+
+  static allow(message?: string): AuthorizationResponse {
+    return new AuthorizationResponse(true, message)
+  }
+
+  static deny(message?: string, code?: number): AuthorizationResponse {
+    return new AuthorizationResponse(false, message ?? 'This action is unauthorized.', code ?? 403)
+  }
+}

package/src/authorization/GateManager.ts

@@ -0,0 +1,247 @@
+import { ForbiddenError } from '@mantiq/core'
+import { AuthorizationResponse } from './AuthorizationResponse.ts'
+import type { Policy } from './Policy.ts'
+import { UserGate } from './UserGate.ts'
+
+type GateCallback = (user: any, ...args: any[]) => boolean | AuthorizationResponse | Promise<boolean | AuthorizationResponse>
+type BeforeCallback = (user: any, ability: string, ...args: any[]) => boolean | null | undefined | Promise<boolean | null | undefined>
+type AfterCallback = (user: any, ability: string, result: boolean, ...args: any[]) => void | Promise<void>
+
+/**
+ * Central authorization manager — Laravel-style Gates & Policies.
+ *
+ * Gate closures handle simple ability checks.
+ * Policies handle model-based authorization — each policy maps to a model class.
+ *
+ * Resolution order:
+ * 1. Global `before` callbacks (short-circuit on non-null)
+ * 2. Policy `before()` hook (if a policy matches)
+ * 3. Policy method matching the ability name
+ * 4. Gate closure matching the ability name
+ * 5. Deny by default
+ * 6. Global `after` callbacks (for auditing, cannot change result)
+ */
+export class GateManager {
+  private gates = new Map<string, GateCallback>()
+  private policies = new Map<any, new () => Policy>()
+  private beforeCallbacks: BeforeCallback[] = []
+  private afterCallbacks: AfterCallback[] = []
+
+  // ── Registration ─────────────────────────────────────────────────────────
+
+  /**
+   * Define a gate closure for the given ability.
+   */
+  define(ability: string, callback: GateCallback): this {
+    this.gates.set(ability, callback)
+    return this
+  }
+
+  /**
+   * Register a policy class for a model constructor.
+   */
+  policy(modelClass: any, policyClass: new () => Policy): this {
+    this.policies.set(modelClass, policyClass)
+    return this
+  }
+
+  /**
+   * Register a global before callback.
+   * If the callback returns `true` or `false`, the check short-circuits.
+   * Return `null` or `undefined` to continue to the gate/policy check.
+   */
+  before(callback: BeforeCallback): this {
+    this.beforeCallbacks.push(callback)
+    return this
+  }
+
+  /**
+   * Register a global after callback (for logging/auditing).
+   * After callbacks cannot change the authorization result.
+   */
+  after(callback: AfterCallback): this {
+    this.afterCallbacks.push(callback)
+    return this
+  }
+
+  // ── Checking ─────────────────────────────────────────────────────────────
+
+  /**
+   * Check if the given ability is allowed for the user.
+   */
+  async allows(ability: string, user: any, ...args: any[]): Promise<boolean> {
+    const response = await this.resolve(ability, user, ...args)
+    return response.allowed()
+  }
+
+  /**
+   * Check if the given ability is denied for the user.
+   */
+  async denies(ability: string, user: any, ...args: any[]): Promise<boolean> {
+    return !(await this.allows(ability, user, ...args))
+  }
+
+  /**
+   * Authorize the ability or throw ForbiddenError.
+   * Returns the AuthorizationResponse if allowed.
+   */
+  async authorize(ability: string, user: any, ...args: any[]): Promise<AuthorizationResponse> {
+    const response = await this.resolve(ability, user, ...args)
+
+    if (response.denied()) {
+      throw new ForbiddenError(response.message() ?? 'This action is unauthorized.')
+    }
+
+    return response
+  }
+
+  /**
+   * Check multiple abilities — all must pass.
+   */
+  async check(abilities: string[], user: any, ...args: any[]): Promise<boolean> {
+    for (const ability of abilities) {
+      if (!(await this.allows(ability, user, ...args))) {
+        return false
+      }
+    }
+    return true
+  }
+
+  /**
+   * Check multiple abilities — at least one must pass.
+   */
+  async any(abilities: string[], user: any, ...args: any[]): Promise<boolean> {
+    for (const ability of abilities) {
+      if (await this.allows(ability, user, ...args)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  /**
+   * Returns a UserGate scoped to a specific user for convenience.
+   */
+  forUser(user: any): UserGate {
+    return new UserGate(this, user)
+  }
+
+  // ── Policy resolution ──────────────────────────────────────────────────
+
+  /**
+   * Resolve the policy class for a given model instance.
+   * Returns null if no policy is registered for this model's constructor.
+   */
+  getPolicyFor(model: any): Policy | null {
+    if (model === null || model === undefined) return null
+
+    const constructor = model.constructor
+    const PolicyClass = this.policies.get(constructor)
+
+    if (!PolicyClass) return null
+    return new PolicyClass()
+  }
+
+  // ── Internal resolution ────────────────────────────────────────────────
+
+  /**
+   * Core resolution logic.
+   */
+  private async resolve(ability: string, user: any, ...args: any[]): Promise<AuthorizationResponse> {
+    // 1. Run global before callbacks
+    for (const cb of this.beforeCallbacks) {
+      const result = await cb(user, ability, ...args)
+      if (result === true) {
+        const response = AuthorizationResponse.allow()
+        await this.runAfterCallbacks(user, ability, true, ...args)
+        return response
+      }
+      if (result === false) {
+        const response = AuthorizationResponse.deny()
+        await this.runAfterCallbacks(user, ability, false, ...args)
+        return response
+      }
+      // null/undefined → continue
+    }
+
+    // 2. Try policy-based authorization
+    const firstArg = args[0]
+    const policyResult = await this.tryPolicy(ability, user, firstArg, ...args)
+    if (policyResult !== null) {
+      const allowed = policyResult.allowed()
+      await this.runAfterCallbacks(user, ability, allowed, ...args)
+      return policyResult
+    }
+
+    // 3. Try gate closure
+    const gateResult = await this.tryGate(ability, user, ...args)
+    if (gateResult !== null) {
+      const allowed = gateResult.allowed()
+      await this.runAfterCallbacks(user, ability, allowed, ...args)
+      return gateResult
+    }
+
+    // 4. Deny by default
+    const denied = AuthorizationResponse.deny()
+    await this.runAfterCallbacks(user, ability, false, ...args)
+    return denied
+  }
+
+  /**
+   * Attempt policy-based authorization.
+   * Returns null if no matching policy or method.
+   */
+  private async tryPolicy(ability: string, user: any, firstArg: any, ...allArgs: any[]): Promise<AuthorizationResponse | null> {
+    if (firstArg === null || firstArg === undefined) return null
+
+    const policy = this.getPolicyFor(firstArg)
+    if (!policy) return null
+
+    // Policy before() hook
+    if (typeof policy.before === 'function') {
+      const beforeResult = await policy.before(user, ability, ...allArgs)
+      if (beforeResult === true) return AuthorizationResponse.allow()
+      if (beforeResult === false) return AuthorizationResponse.deny()
+      // null/undefined → continue to method
+    }
+
+    // Check if the policy has a method matching the ability name
+    const method = (policy as any)[ability]
+    if (typeof method !== 'function') {
+      // Policy exists but no matching method → deny
+      return AuthorizationResponse.deny(`Policy method "${ability}" not defined.`)
+    }
+
+    const result = await method.call(policy, user, ...allArgs)
+    return this.normalizeResult(result)
+  }
+
+  /**
+   * Attempt gate closure authorization.
+   * Returns null if no gate is defined for this ability.
+   */
+  private async tryGate(ability: string, user: any, ...args: any[]): Promise<AuthorizationResponse | null> {
+    const callback = this.gates.get(ability)
+    if (!callback) return null
+
+    const result = await callback(user, ...args)
+    return this.normalizeResult(result)
+  }
+
+  /**
+   * Normalize a boolean or AuthorizationResponse return value.
+   */
+  private normalizeResult(result: boolean | AuthorizationResponse): AuthorizationResponse {
+    if (result instanceof AuthorizationResponse) return result
+    return result ? AuthorizationResponse.allow() : AuthorizationResponse.deny()
+  }
+
+  /**
+   * Run all global after callbacks.
+   */
+  private async runAfterCallbacks(user: any, ability: string, result: boolean, ...args: any[]): Promise<void> {
+    for (const cb of this.afterCallbacks) {
+      await cb(user, ability, result, ...args)
+    }
+  }
+}

package/src/authorization/Policy.ts

@@ -0,0 +1,18 @@
+/**
+ * Base class for authorization policies.
+ *
+ * Subclass and define methods matching ability names.
+ * Each method receives the user + optional model arguments and returns
+ * a boolean or AuthorizationResponse.
+ *
+ * The optional `before()` hook is called before any policy method and
+ * can short-circuit the check: return `true` to allow, `false` to deny,
+ * or `null`/`undefined` to continue to the actual policy method.
+ */
+export abstract class Policy {
+  /**
+   * Called before any policy method.
+   * Return true to allow, false to deny, null/undefined to continue.
+   */
+  before?(user: any, ability: string, ...args: any[]): boolean | null | undefined | Promise<boolean | null | undefined>
+}

package/src/authorization/UserGate.ts

@@ -0,0 +1,28 @@
+import type { GateManager } from './GateManager.ts'
+import type { AuthorizationResponse } from './AuthorizationResponse.ts'
+
+/**
+ * A gate scoped to a specific user for convenience.
+ *
+ * @example
+ * const userGate = gate().forUser(user)
+ * if (await userGate.can('edit', post)) { ... }
+ */
+export class UserGate {
+  constructor(
+    private readonly gate: GateManager,
+    private readonly user: any,
+  ) {}
+
+  async can(ability: string, ...args: any[]): Promise<boolean> {
+    return this.gate.allows(ability, this.user, ...args)
+  }
+
+  async cannot(ability: string, ...args: any[]): Promise<boolean> {
+    return this.gate.denies(ability, this.user, ...args)
+  }
+
+  async authorize(ability: string, ...args: any[]): Promise<AuthorizationResponse> {
+    return this.gate.authorize(ability, this.user, ...args)
+  }
+}

package/src/contracts/AuthConfig.ts

@@ -3,6 +3,7 @@ import type { Constructor } from '@mantiq/core'
 export interface GuardConfig {
   driver: string    // 'session' | custom driver name
   provider: string  // Name referencing a provider in config.providers
+  trackLastUsed?: boolean | undefined
 }
 
 export interface ProviderConfig {

package/src/contracts/NewAccessToken.ts

@@ -0,0 +1,6 @@
+import type { PersonalAccessToken } from '../models/PersonalAccessToken.ts'
+
+export interface NewAccessToken {
+  accessToken: PersonalAccessToken
+  plainTextToken: string
+}

package/src/guards/TokenGuard.ts

@@ -0,0 +1,108 @@
+import type { Guard } from '../contracts/Guard.ts'
+import type { Authenticatable } from '../contracts/Authenticatable.ts'
+import type { UserProvider } from '../contracts/UserProvider.ts'
+import type { MantiqRequest } from '@mantiq/core'
+import { PersonalAccessToken } from '../models/PersonalAccessToken.ts'
+import { sha256 } from '../helpers/hash.ts'
+
+export class TokenGuard implements Guard {
+  private _user: Authenticatable | null = null
+  private _request: MantiqRequest | null = null
+  private _resolved = false
+
+  constructor(
+    private readonly name: string,
+    private readonly provider: UserProvider,
+    private readonly trackLastUsed = false,
+  ) {}
+
+  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
+
+    const token = await this.resolveToken(bearerToken)
+    if (!token) return null
+
+    // Check expiration
+    if (token.isExpired()) return null
+
+    // Optionally track last usage (disabled by default to avoid write-per-request)
+    if (this.trackLastUsed) {
+      token.setAttribute('last_used_at', new Date().toISOString())
+      token.save().catch(() => {})
+    }
+
+    // Resolve user
+    const userId = token.getAttribute('tokenable_id')
+    const user = await this.provider.retrieveById(userId)
+    if (!user) return null
+
+    // Attach token to user if it supports it
+    if (typeof (user as any).withAccessToken === 'function') {
+      (user as any).withAccessToken(token)
+    }
+
+    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
+  }
+
+  private async resolveToken(bearerToken: string): Promise<PersonalAccessToken | null> {
+    const parts = bearerToken.split('|')
+
+    if (parts.length === 2) {
+      // Format: {id}|{plaintext}
+      const [id, plaintext] = parts
+      const token = await PersonalAccessToken.find(Number(id))
+      if (!token) return null
+
+      const hash = await sha256(plaintext!)
+      const storedHash = token.getAttribute('token') as string
+      if (hash !== storedHash) return null
+
+      return token
+    }
+
+    // Fallback: hash the entire string and search by token hash
+    const hash = await sha256(bearerToken)
+    return await PersonalAccessToken.where('token', hash).first() as PersonalAccessToken | null
+  }
+}

package/src/helpers/gate.ts

@@ -0,0 +1,22 @@
+import type { GateManager } from '../authorization/GateManager.ts'
+
+let _gate: GateManager | null = null
+
+export const GATE_MANAGER = Symbol('GateManager')
+
+export function setGateManager(g: GateManager): void {
+  _gate = g
+}
+
+/**
+ * Access the gate manager singleton.
+ *
+ * @example gate().allows('edit-post', user, post)
+ * @example gate().forUser(user).can('edit-post', post)
+ */
+export function gate(): GateManager {
+  if (!_gate) {
+    throw new Error('Gate manager not initialized. Register AuthServiceProvider.')
+  }
+  return _gate
+}

package/src/helpers/hash.ts

@@ -0,0 +1,5 @@
+export async function sha256(input: string): Promise<string> {
+  const data = new TextEncoder().encode(input)
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+  return Array.from(new Uint8Array(hashBuffer)).map(b => b.toString(16).padStart(2, '0')).join('')
+}

package/src/index.ts

@@ -4,14 +4,22 @@ export type { Guard } from './contracts/Guard.ts'
 export type { StatefulGuard } from './contracts/StatefulGuard.ts'
 export type { UserProvider } from './contracts/UserProvider.ts'
 export type { AuthConfig, GuardConfig, ProviderConfig } from './contracts/AuthConfig.ts'
+export type { NewAccessToken } from './contracts/NewAccessToken.ts'
 
 // ── Core ──────────────────────────────────────────────────────────────────────
 export { AuthManager } from './AuthManager.ts'
 export { AuthServiceProvider } from './AuthServiceProvider.ts'
 
+// ── Authorization (Gates & Policies) ─────────────────────────────────────────
+export { GateManager } from './authorization/GateManager.ts'
+export { AuthorizationResponse } from './authorization/AuthorizationResponse.ts'
+export { Policy } from './authorization/Policy.ts'
+export { UserGate } from './authorization/UserGate.ts'
+
 // ── Guards ────────────────────────────────────────────────────────────────────
 export { SessionGuard } from './guards/SessionGuard.ts'
 export { RequestGuard } from './guards/RequestGuard.ts'
+export { TokenGuard } from './guards/TokenGuard.ts'
 
 // ── Providers ─────────────────────────────────────────────────────────────────
 export { DatabaseUserProvider } from './providers/DatabaseUserProvider.ts'
@@ -21,6 +29,9 @@ export { Authenticate } from './middleware/Authenticate.ts'
 export { RedirectIfAuthenticated } from './middleware/RedirectIfAuthenticated.ts'
 export { EnsureEmailIsVerified } from './middleware/EnsureEmailIsVerified.ts'
 export { ConfirmPassword } from './middleware/ConfirmPassword.ts'
+export { CheckAbilities } from './middleware/CheckAbilities.ts'
+export { CheckForAnyAbility } from './middleware/CheckForAnyAbility.ts'
+export { Authorize } from './middleware/Authorize.ts'
 
 // ── Errors ────────────────────────────────────────────────────────────────────
 export { AuthenticationError } from './errors/AuthenticationError.ts'
@@ -28,5 +39,17 @@ export { AuthenticationError } from './errors/AuthenticationError.ts'
 // ── Events ────────────────────────────────────────────────────────────────────
 export { Attempting, Authenticated, Login, Failed, Logout, Registered, Lockout } from './events/AuthEvents.ts'
 
+// ── Models ────────────────────────────────────────────────────────────────────
+export { PersonalAccessToken } from './models/PersonalAccessToken.ts'
+
+// ── Mixins ────────────────────────────────────────────────────────────────────
+export { applyHasApiTokens } from './HasApiTokens.ts'
+export { applyAuthorizable } from './Authorizable.ts'
+
+// ── Migrations ────────────────────────────────────────────────────────────────
+export { CreatePersonalAccessTokensTable } from './migrations/CreatePersonalAccessTokensTable.ts'
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
+export { sha256 } from './helpers/hash.ts'
 export { auth, AUTH_MANAGER } from './helpers/auth.ts'
+export { gate, setGateManager, GATE_MANAGER } from './helpers/gate.ts'

package/src/middleware/Authorize.ts

@@ -0,0 +1,41 @@
+import type { Middleware, NextFunction, MantiqRequest } from '@mantiq/core'
+import { gate } from '../helpers/gate.ts'
+
+/**
+ * Authorization middleware for routes.
+ *
+ * Checks that the authenticated user is authorized for the given ability.
+ * Returns 401 if unauthenticated, or throws ForbiddenError (via gate().authorize())
+ * if the user is not authorized.
+ *
+ * Usage: `.middleware('can:update,post')`
+ *
+ * - params[0] = ability name
+ * - params[1..] = optional extra arguments passed to the gate/policy
+ */
+export class Authorize implements Middleware {
+  private params: string[] = []
+
+  setParameters(params: string[]): void {
+    this.params = params
+  }
+
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    const user = request.user()
+    if (!user) {
+      return new Response(
+        JSON.stringify({ message: 'Unauthenticated.' }),
+        { status: 401, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    const ability = this.params[0]
+    if (!ability) return next()
+
+    const gateManager = gate()
+    // authorize() throws ForbiddenError if denied
+    await gateManager.authorize(ability, user, ...this.params.slice(1))
+
+    return next()
+  }
+}

package/src/middleware/CheckAbilities.ts

@@ -0,0 +1,24 @@
+import type { MantiqRequest } from '@mantiq/core'
+
+export class CheckAbilities {
+  private abilities: string[] = []
+
+  setParameters(...abilities: string[]): void {
+    this.abilities = abilities
+  }
+
+  async handle(request: MantiqRequest, next: () => Promise<Response>): Promise<Response> {
+    const user = request.user<any>()
+    if (!user || typeof user.tokenCan !== 'function') {
+      return new Response(JSON.stringify({ message: 'Unauthorized.' }), { status: 403, headers: { 'Content-Type': 'application/json' } })
+    }
+
+    for (const ability of this.abilities) {
+      if (!user.tokenCan(ability)) {
+        return new Response(JSON.stringify({ message: `Missing ability: ${ability}` }), { status: 403, headers: { 'Content-Type': 'application/json' } })
+      }
+    }
+
+    return next()
+  }
+}

package/src/middleware/CheckForAnyAbility.ts

@@ -0,0 +1,23 @@
+import type { MantiqRequest } from '@mantiq/core'
+
+export class CheckForAnyAbility {
+  private abilities: string[] = []
+
+  setParameters(...abilities: string[]): void {
+    this.abilities = abilities
+  }
+
+  async handle(request: MantiqRequest, next: () => Promise<Response>): Promise<Response> {
+    const user = request.user<any>()
+    if (!user || typeof user.tokenCan !== 'function') {
+      return new Response(JSON.stringify({ message: 'Unauthorized.' }), { status: 403, headers: { 'Content-Type': 'application/json' } })
+    }
+
+    const hasAny = this.abilities.some(ability => user.tokenCan(ability))
+    if (!hasAny) {
+      return new Response(JSON.stringify({ message: 'Insufficient abilities.' }), { status: 403, headers: { 'Content-Type': 'application/json' } })
+    }
+
+    return next()
+  }
+}

package/src/migrations/CreatePersonalAccessTokensTable.ts

@@ -0,0 +1,22 @@
+import { Migration } from '@mantiq/database'
+import type { SchemaBuilder } from '@mantiq/database'
+
+export class CreatePersonalAccessTokensTable extends Migration {
+  override async up(schema: SchemaBuilder): Promise<void> {
+    await schema.create('personal_access_tokens', (table) => {
+      table.id()
+      table.string('tokenable_type')
+      table.unsignedBigInteger('tokenable_id')
+      table.string('name')
+      table.string('token', 64).unique()
+      table.json('abilities').nullable()
+      table.timestamp('last_used_at').nullable()
+      table.timestamp('expires_at').nullable()
+      table.timestamps()
+    })
+  }
+
+  override async down(schema: SchemaBuilder): Promise<void> {
+    await schema.dropIfExists('personal_access_tokens')
+  }
+}

package/src/models/PersonalAccessToken.ts

@@ -0,0 +1,28 @@
+import { Model } from '@mantiq/database'
+
+export class PersonalAccessToken extends Model {
+  static override table = 'personal_access_tokens'
+  static override fillable = ['name', 'token', 'abilities', 'expires_at', 'last_used_at', 'tokenable_type', 'tokenable_id']
+  static override hidden = ['token']
+  static override casts = {
+    abilities: 'json' as const,
+    last_used_at: 'datetime' as const,
+    expires_at: 'datetime' as const,
+  }
+
+  can(ability: string): boolean {
+    const abilities = this.getAttribute('abilities') as string[] | null
+    if (!abilities) return false
+    return abilities.includes('*') || abilities.includes(ability)
+  }
+
+  cant(ability: string): boolean {
+    return !this.can(ability)
+  }
+
+  isExpired(): boolean {
+    const expiresAt = this.getAttribute('expires_at')
+    if (!expiresAt) return false
+    return new Date(expiresAt) < new Date()
+  }
+}