@mantiq/auth 0.2.1 → 0.3.0

package/package.json

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

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/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/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/index.ts

@@ -10,6 +10,12 @@ export type { NewAccessToken } from './contracts/NewAccessToken.ts'
 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'
@@ -25,6 +31,7 @@ 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'
@@ -37,6 +44,7 @@ export { PersonalAccessToken } from './models/PersonalAccessToken.ts'
 
 // ── Mixins ────────────────────────────────────────────────────────────────────
 export { applyHasApiTokens } from './HasApiTokens.ts'
+export { applyAuthorizable } from './Authorizable.ts'
 
 // ── Migrations ────────────────────────────────────────────────────────────────
 export { CreatePersonalAccessTokensTable } from './migrations/CreatePersonalAccessTokensTable.ts'
@@ -44,3 +52,4 @@ export { CreatePersonalAccessTokensTable } from './migrations/CreatePersonalAcce
 // ── 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()
+  }
+}