@mantiq/auth 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/auth
+
+Session & token authentication, guards, providers, and middleware for MantiqJS.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/auth
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mantiq/auth",
+  "version": "0.0.1",
+  "description": "Session & token auth, guards, providers",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/auth",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/auth"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "auth"
+  ],
+  "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",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mantiq/core": "workspace:*",
+    "@mantiq/database": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/AuthManager.ts

@@ -0,0 +1,219 @@
+import type { DriverManager, Container, MantiqRequest } from '@mantiq/core'
+import { HashManager, ENCRYPTER } from '@mantiq/core'
+import type { Guard } from './contracts/Guard.ts'
+import type { StatefulGuard } from './contracts/StatefulGuard.ts'
+import type { UserProvider } from './contracts/UserProvider.ts'
+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 { DatabaseUserProvider } from './providers/DatabaseUserProvider.ts'
+
+type RequestGuardCallback = (
+  request: MantiqRequest,
+  provider: UserProvider,
+) => Authenticatable | null | Promise<Authenticatable | null>
+
+/**
+ * Multi-driver authentication manager (Laravel-style).
+ *
+ * Manages guards (session, request, custom) and user providers.
+ * Also proxies Guard/StatefulGuard methods to the default guard
+ * for convenience (e.g. `auth().check()`, `auth().attempt()`).
+ */
+export class AuthManager implements DriverManager<Guard> {
+  private readonly guards = new Map<string, Guard>()
+  private readonly customCreators = new Map<string, (name: string, config: any) => Guard>()
+  private readonly requestGuards = new Map<string, RequestGuardCallback>()
+  private readonly userProviders = new Map<string, UserProvider>()
+  private defaultGuardName: string
+  private currentRequest: MantiqRequest | null = null
+
+  constructor(
+    private readonly config: AuthConfig,
+    private readonly container: Container,
+  ) {
+    this.defaultGuardName = config.defaults.guard
+  }
+
+  // ── DriverManager ───────────────────────────────────────────────────────
+
+  driver(name?: string): Guard {
+    return this.guard(name)
+  }
+
+  extend(name: string, factory: () => Guard): void {
+    this.customCreators.set(name, () => factory())
+  }
+
+  getDefaultDriver(): string {
+    return this.defaultGuardName
+  }
+
+  // ── Guard resolution ────────────────────────────────────────────────────
+
+  guard(name?: string): Guard {
+    const guardName = name ?? this.defaultGuardName
+
+    if (!this.guards.has(guardName)) {
+      const newGuard = this.createGuard(guardName)
+      if (this.currentRequest) {
+        newGuard.setRequest(this.currentRequest)
+      }
+      this.guards.set(guardName, newGuard)
+    }
+
+    return this.guards.get(guardName)!
+  }
+
+  /**
+   * Set the default guard for the current request.
+   */
+  shouldUse(name: string): void {
+    this.defaultGuardName = name
+  }
+
+  /**
+   * Register a closure-based guard via `viaRequest()`.
+   */
+  viaRequest(name: string, callback: RequestGuardCallback): void {
+    this.requestGuards.set(name, callback)
+  }
+
+  /**
+   * Set the request on all resolved guards (call per-request from middleware).
+   */
+  setRequest(request: MantiqRequest): void {
+    this.currentRequest = request
+    for (const guard of this.guards.values()) {
+      guard.setRequest(request)
+    }
+  }
+
+  /**
+   * Clear all cached guard instances (useful for testing).
+   */
+  forgetGuards(): void {
+    this.guards.clear()
+    this.defaultGuardName = this.config.defaults.guard
+  }
+
+  // ── User provider resolution ────────────────────────────────────────────
+
+  createUserProvider(providerName: string): UserProvider {
+    if (this.userProviders.has(providerName)) {
+      return this.userProviders.get(providerName)!
+    }
+
+    const providerConfig = this.config.providers[providerName]
+    if (!providerConfig) {
+      throw new Error(`Auth provider "${providerName}" is not configured.`)
+    }
+
+    let provider: UserProvider
+
+    switch (providerConfig.driver) {
+      case 'database': {
+        const hasher = this.container.make(HashManager)
+        provider = new DatabaseUserProvider(providerConfig.model as any, hasher)
+        break
+      }
+      default:
+        throw new Error(`Unsupported auth provider driver: ${providerConfig.driver}`)
+    }
+
+    this.userProviders.set(providerName, provider)
+    return provider
+  }
+
+  // ── Proxied Guard methods (delegate to default guard) ───────────────────
+
+  async check(): Promise<boolean> {
+    return this.guard().check()
+  }
+
+  async guest(): Promise<boolean> {
+    return this.guard().guest()
+  }
+
+  async user(): Promise<Authenticatable | null> {
+    return this.guard().user()
+  }
+
+  async id(): Promise<string | number | null> {
+    return this.guard().id()
+  }
+
+  async validate(credentials: Record<string, any>): Promise<boolean> {
+    return this.guard().validate(credentials)
+  }
+
+  /**
+   * Attempt to authenticate (only works with StatefulGuard — the default is usually session).
+   */
+  async attempt(credentials: Record<string, any>, remember = false): Promise<boolean> {
+    const g = this.guard() as StatefulGuard
+    if (!g.attempt) {
+      throw new Error(`The "${this.defaultGuardName}" guard does not support attempt(). Use a stateful guard.`)
+    }
+    return g.attempt(credentials, remember)
+  }
+
+  async login(user: Authenticatable, remember = false): Promise<void> {
+    const g = this.guard() as StatefulGuard
+    if (!g.login) {
+      throw new Error(`The "${this.defaultGuardName}" guard does not support login(). Use a stateful guard.`)
+    }
+    return g.login(user, remember)
+  }
+
+  async logout(): Promise<void> {
+    const g = this.guard() as StatefulGuard
+    if (!g.logout) {
+      throw new Error(`The "${this.defaultGuardName}" guard does not support logout(). Use a stateful guard.`)
+    }
+    return g.logout()
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  private createGuard(name: string): Guard {
+    // Check custom creators first
+    const custom = this.customCreators.get(name)
+    if (custom) return custom(name, {})
+
+    // Check viaRequest guards
+    const requestCallback = this.requestGuards.get(name)
+    if (requestCallback) {
+      const guardConfig = this.config.guards[name]
+      const providerName = guardConfig?.provider ?? Object.keys(this.config.providers)[0]!
+      const provider = this.createUserProvider(providerName)
+      return new RequestGuard(requestCallback, provider)
+    }
+
+    // Built-in guard from config
+    const guardConfig = this.config.guards[name]
+    if (!guardConfig) {
+      throw new Error(`Auth guard "${name}" is not configured. Check your auth config.`)
+    }
+
+    switch (guardConfig.driver) {
+      case 'session': {
+        const provider = this.createUserProvider(guardConfig.provider)
+        let encrypter: any = undefined
+        try {
+          encrypter = this.container.make(ENCRYPTER)
+        } catch {
+          // Encrypter not available — remember cookies won't be encrypted
+        }
+        return new SessionGuard(name, provider, encrypter)
+      }
+      default: {
+        throw new Error(
+          `Unsupported auth guard driver: "${guardConfig.driver}". ` +
+          'Use extend() or viaRequest() to register custom guard drivers.',
+        )
+      }
+    }
+  }
+}

package/src/AuthServiceProvider.ts

@@ -0,0 +1,41 @@
+import { ServiceProvider, ConfigRepository } 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 type { AuthConfig } from './contracts/AuthConfig.ts'
+
+const DEFAULT_CONFIG: AuthConfig = {
+  defaults: { guard: 'web' },
+  guards: {
+    web: { driver: 'session', provider: 'users' },
+  },
+  providers: {
+    users: { driver: 'database', model: class {} as any },
+  },
+}
+
+/**
+ * Registers authentication bindings in the container.
+ *
+ * Config file: config/auth.ts
+ * Required config: guards, providers, defaults.guard
+ */
+export class AuthServiceProvider extends ServiceProvider {
+  override register(): void {
+    // AuthManager — singleton
+    this.app.singleton(AuthManager, (c) => {
+      const config = c.make(ConfigRepository).get<AuthConfig>('auth', DEFAULT_CONFIG)
+      return new AuthManager(config, c)
+    })
+    this.app.alias(AuthManager, AUTH_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())
+  }
+}

package/src/contracts/AuthConfig.ts

@@ -0,0 +1,19 @@
+import type { Constructor } from '@mantiq/core'
+
+export interface GuardConfig {
+  driver: string    // 'session' | custom driver name
+  provider: string  // Name referencing a provider in config.providers
+}
+
+export interface ProviderConfig {
+  driver: string           // 'database' | custom driver name
+  model: Constructor<any>  // The User model class
+}
+
+export interface AuthConfig {
+  defaults: {
+    guard: string
+  }
+  guards: Record<string, GuardConfig>
+  providers: Record<string, ProviderConfig>
+}

package/src/contracts/Authenticatable.ts

@@ -0,0 +1,29 @@
+/**
+ * Contract for authenticatable entities (typically the User model).
+ *
+ * Implement this interface on your Model subclass. For conventional
+ * column names (id, password, remember_token), the methods are
+ * straightforward one-liners.
+ */
+export interface Authenticatable {
+  /** Return the name of the unique identifier column (e.g. 'id'). */
+  getAuthIdentifierName(): string
+
+  /** Return the unique identifier value. */
+  getAuthIdentifier(): string | number
+
+  /** Return the name of the password column (e.g. 'password'). */
+  getAuthPasswordName(): string
+
+  /** Return the hashed password. */
+  getAuthPassword(): string
+
+  /** Return the remember me token value. */
+  getRememberToken(): string | null
+
+  /** Set the remember me token value. */
+  setRememberToken(token: string | null): void
+
+  /** Return the column name for the remember token (e.g. 'remember_token'). */
+  getRememberTokenName(): string
+}

package/src/contracts/Guard.ts

@@ -0,0 +1,31 @@
+import type { MantiqRequest } from '@mantiq/core'
+import type { Authenticatable } from './Authenticatable.ts'
+
+/**
+ * Base guard contract — read-only authentication checks.
+ */
+export interface Guard {
+  /** Determine if the current user is authenticated. */
+  check(): Promise<boolean>
+
+  /** Determine if the current user is a guest. */
+  guest(): Promise<boolean>
+
+  /** Get the currently authenticated user. */
+  user(): Promise<Authenticatable | null>
+
+  /** Get the ID of the currently authenticated user. */
+  id(): Promise<string | number | null>
+
+  /** Validate credentials without logging in. */
+  validate(credentials: Record<string, any>): Promise<boolean>
+
+  /** Set the current user explicitly. */
+  setUser(user: Authenticatable): void
+
+  /** Check if a user instance is already resolved (without hitting provider). */
+  hasUser(): boolean
+
+  /** Set the current request on the guard (resets per-request state). */
+  setRequest(request: MantiqRequest): void
+}

package/src/contracts/StatefulGuard.ts

@@ -0,0 +1,22 @@
+import type { Guard } from './Guard.ts'
+import type { Authenticatable } from './Authenticatable.ts'
+
+/**
+ * Contract for stateful (session-based) guards that support login/logout.
+ */
+export interface StatefulGuard extends Guard {
+  /** Attempt to authenticate using credentials. Returns true on success. */
+  attempt(credentials: Record<string, any>, remember?: boolean): Promise<boolean>
+
+  /** Log a user in (set session, optionally set remember cookie). */
+  login(user: Authenticatable, remember?: boolean): Promise<void>
+
+  /** Log a user in by their identifier. */
+  loginUsingId(id: string | number, remember?: boolean): Promise<Authenticatable | null>
+
+  /** Log the user out (flush session, clear remember cookie). */
+  logout(): Promise<void>
+
+  /** Determine if the user was authenticated via remember me cookie. */
+  viaRemember(): boolean
+}

package/src/contracts/UserProvider.ts

@@ -0,0 +1,25 @@
+import type { Authenticatable } from './Authenticatable.ts'
+
+/**
+ * Contract for user retrieval and credential validation.
+ * Each provider implementation resolves users from a different source.
+ */
+export interface UserProvider {
+  /** Retrieve a user by their unique identifier. */
+  retrieveById(identifier: string | number): Promise<Authenticatable | null>
+
+  /** Retrieve a user by their identifier and remember token. */
+  retrieveByToken(identifier: string | number, token: string): Promise<Authenticatable | null>
+
+  /** Update the remember me token on the user. */
+  updateRememberToken(user: Authenticatable, token: string): Promise<void>
+
+  /** Retrieve a user by credentials (e.g. email). Does NOT check password. */
+  retrieveByCredentials(credentials: Record<string, any>): Promise<Authenticatable | null>
+
+  /** Validate a user against the given credentials (checks password). */
+  validateCredentials(user: Authenticatable, credentials: Record<string, any>): Promise<boolean>
+
+  /** Re-hash the password if the hasher's cost has changed. */
+  rehashPasswordIfRequired(user: Authenticatable, credentials: Record<string, any>): Promise<void>
+}

package/src/errors/AuthenticationError.ts

@@ -0,0 +1,15 @@
+import { UnauthorizedError } from '@mantiq/core'
+
+/**
+ * Thrown when authentication fails.
+ * For web routes, includes a redirect URL. For API routes, returns 401.
+ */
+export class AuthenticationError extends UnauthorizedError {
+  constructor(
+    message = 'Unauthenticated.',
+    public readonly redirectTo: string = '/login',
+    public readonly guards: string[] = [],
+  ) {
+    super(message)
+  }
+}

package/src/events/AuthEvents.ts

@@ -0,0 +1,86 @@
+import { Event } from '@mantiq/core'
+import type { Authenticatable } from '../contracts/Authenticatable.ts'
+
+/**
+ * Fired when an authentication attempt begins.
+ */
+export class Attempting extends Event {
+  constructor(
+    public readonly guard: string,
+    public readonly credentials: Record<string, any>,
+    public readonly remember: boolean,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a user is successfully authenticated (session or remember cookie).
+ */
+export class Authenticated extends Event {
+  constructor(
+    public readonly guard: string,
+    public readonly user: Authenticatable,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a user logs in via attempt() or login().
+ */
+export class Login extends Event {
+  constructor(
+    public readonly guard: string,
+    public readonly user: Authenticatable,
+    public readonly remember: boolean,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when an authentication attempt fails (wrong credentials).
+ */
+export class Failed extends Event {
+  constructor(
+    public readonly guard: string,
+    public readonly credentials: Record<string, any>,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a user logs out.
+ */
+export class Logout extends Event {
+  constructor(
+    public readonly guard: string,
+    public readonly user: Authenticatable | null,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a new user registers.
+ */
+export class Registered extends Event {
+  constructor(
+    public readonly user: Authenticatable,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a user is locked out due to too many failed attempts.
+ */
+export class Lockout extends Event {
+  constructor(
+    public readonly request: any,
+  ) {
+    super()
+  }
+}

package/src/guards/RequestGuard.ts

@@ -0,0 +1,81 @@
+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'
+
+type RequestGuardCallback = (
+  request: MantiqRequest,
+  provider: UserProvider,
+) => Authenticatable | null | Promise<Authenticatable | null>
+
+/**
+ * Closure-based guard for custom authentication logic.
+ *
+ * Register via `auth().viaRequest('custom', (request, provider) => { ... })`.
+ */
+export class RequestGuard implements Guard {
+  private _user: Authenticatable | null = null
+  private _resolved = false
+  private _request: MantiqRequest | null = null
+
+  constructor(
+    private readonly callback: RequestGuardCallback,
+    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
+
+    const request = this.getRequest()
+    this._user = await this.callback(request, this.provider) ?? null
+    this._resolved = true
+
+    if (this._user) {
+      request.setUser(this._user as any)
+    }
+
+    return this._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
+    // Reset per-request state
+    this._user = null
+    this._resolved = false
+  }
+
+  private getRequest(): MantiqRequest {
+    if (!this._request) {
+      throw new Error('No request set on the guard.')
+    }
+    return this._request
+  }
+}

package/src/guards/SessionGuard.ts

@@ -0,0 +1,309 @@
+import type { StatefulGuard } from '../contracts/StatefulGuard.ts'
+import type { Authenticatable } from '../contracts/Authenticatable.ts'
+import type { UserProvider } from '../contracts/UserProvider.ts'
+import type { MantiqRequest, EventDispatcher } from '@mantiq/core'
+import type { Encrypter } from '@mantiq/core'
+import { Attempting, Authenticated, Login as LoginEvent, Failed, Logout as LogoutEvent } from '../events/AuthEvents.ts'
+
+/**
+ * Session-based authentication guard.
+ *
+ * Resolves the authenticated user from the session. Supports login/logout,
+ * remember me cookies, and session fixation prevention via regeneration.
+ *
+ * Remember me cookie handling: the guard stores flags that middleware reads
+ * after the response to set/clear cookies. Guards never touch Response directly.
+ */
+export class SessionGuard implements StatefulGuard {
+  private _user: Authenticatable | null = null
+  private _loggedOut = false
+  private _viaRemember = false
+  private _recallAttempted = false
+  private _request: MantiqRequest | null = null
+
+  /** Pending remember cookie data (set during login, read by middleware). */
+  private _pendingRememberCookie: { id: string | number; token: string; hash: string } | null = null
+  /** Flag to clear the remember cookie (set during logout). */
+  private _clearRememberCookie = false
+
+  /** Optional event dispatcher. Set by @mantiq/events when installed. */
+  static _dispatcher: EventDispatcher | null = null
+
+  constructor(
+    private readonly name: string,
+    private readonly provider: UserProvider,
+    private readonly encrypter?: Encrypter,
+  ) {}
+
+  // ── Guard contract ──────────────────────────────────────────────────────
+
+  async check(): Promise<boolean> {
+    return (await this.user()) !== null
+  }
+
+  async guest(): Promise<boolean> {
+    return !(await this.check())
+  }
+
+  async user(): Promise<Authenticatable | null> {
+    if (this._loggedOut) return null
+    if (this._user !== null) return this._user
+
+    const request = this.getRequest()
+
+    // 1. Try to resolve from session
+    const userId = request.session().get<string | number>(this.sessionKey())
+    if (userId !== undefined && userId !== null) {
+      this._user = await this.provider.retrieveById(userId)
+      if (this._user) {
+        request.setUser(this._user as any)
+        await SessionGuard._dispatcher?.emit(new Authenticated(this.name, this._user))
+      }
+    }
+
+    // 2. Try to recall from remember cookie
+    if (this._user === null && !this._recallAttempted) {
+      this._recallAttempted = true
+      this._user = await this.recallFromCookie()
+      if (this._user) {
+        this._viaRemember = true
+        // Re-store in session so subsequent requests don't need the cookie
+        this.updateSession(this._user.getAuthIdentifier())
+        request.setUser(this._user as any)
+        await SessionGuard._dispatcher?.emit(new Authenticated(this.name, this._user))
+      }
+    }
+
+    return this._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._loggedOut = false
+    if (this._request) {
+      this._request.setUser(user as any)
+    }
+  }
+
+  hasUser(): boolean {
+    return this._user !== null
+  }
+
+  setRequest(request: MantiqRequest): void {
+    this._request = request
+    // Reset per-request state
+    this._user = null
+    this._loggedOut = false
+    this._viaRemember = false
+    this._recallAttempted = false
+    this._pendingRememberCookie = null
+    this._clearRememberCookie = false
+  }
+
+  // ── StatefulGuard contract ──────────────────────────────────────────────
+
+  async attempt(credentials: Record<string, any>, remember = false): Promise<boolean> {
+    await SessionGuard._dispatcher?.emit(new Attempting(this.name, credentials, remember))
+
+    const user = await this.provider.retrieveByCredentials(credentials)
+    if (!user) {
+      await SessionGuard._dispatcher?.emit(new Failed(this.name, credentials))
+      return false
+    }
+
+    if (await this.provider.validateCredentials(user, credentials)) {
+      await this.provider.rehashPasswordIfRequired(user, credentials)
+      await this.login(user, remember)
+      return true
+    }
+
+    await SessionGuard._dispatcher?.emit(new Failed(this.name, credentials))
+    return false
+  }
+
+  async login(user: Authenticatable, remember = false): Promise<void> {
+    const request = this.getRequest()
+
+    // Regenerate session to prevent fixation
+    await request.session().regenerate(true)
+
+    // Store user ID in session
+    this.updateSession(user.getAuthIdentifier())
+
+    // Handle remember me
+    if (remember) {
+      await this.ensureRememberTokenIsSet(user)
+      this.queueRememberCookie(user)
+    }
+
+    this._user = user
+    this._loggedOut = false
+    request.setUser(user as any)
+
+    await SessionGuard._dispatcher?.emit(new LoginEvent(this.name, user, remember))
+    await SessionGuard._dispatcher?.emit(new Authenticated(this.name, user))
+  }
+
+  async loginUsingId(id: string | number, remember = false): Promise<Authenticatable | null> {
+    const user = await this.provider.retrieveById(id)
+    if (!user) return null
+    await this.login(user, remember)
+    return user
+  }
+
+  async logout(): Promise<void> {
+    const user = this._user
+
+    // Cycle the remember token to invalidate any existing remember cookies
+    if (user) {
+      await this.cycleRememberToken(user)
+    }
+
+    // Clear session
+    const request = this.getRequest()
+    request.session().forget(this.sessionKey())
+    await request.session().invalidate()
+
+    // Flag remember cookie for clearing
+    this._clearRememberCookie = true
+
+    await SessionGuard._dispatcher?.emit(new LogoutEvent(this.name, user))
+
+    // Reset state
+    this._user = null
+    this._loggedOut = true
+  }
+
+  viaRemember(): boolean {
+    return this._viaRemember
+  }
+
+  // ── Remember me ─────────────────────────────────────────────────────────
+
+  /**
+   * Get the name of the remember me cookie for this guard.
+   */
+  getRememberCookieName(): string {
+    return `remember_${this.name}`
+  }
+
+  /**
+   * Get pending remember cookie data (read by middleware to set cookie).
+   */
+  getPendingRememberCookie(): { id: string | number; token: string; hash: string } | null {
+    return this._pendingRememberCookie
+  }
+
+  /**
+   * Check if the remember cookie should be cleared (read by middleware).
+   */
+  shouldClearRememberCookie(): boolean {
+    return this._clearRememberCookie
+  }
+
+  /**
+   * Get the guard name.
+   */
+  getName(): string {
+    return this.name
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  private getRequest(): MantiqRequest {
+    if (!this._request) {
+      throw new Error('No request set on the guard. Ensure Authenticate middleware is active.')
+    }
+    return this._request
+  }
+
+  private sessionKey(): string {
+    return `login_${this.name}`
+  }
+
+  private updateSession(userId: string | number): void {
+    this.getRequest().session().put(this.sessionKey(), userId)
+  }
+
+  /**
+   * Ensure the user has a remember token. If not, generate and persist one.
+   */
+  private async ensureRememberTokenIsSet(user: Authenticatable): Promise<void> {
+    if (!user.getRememberToken()) {
+      await this.cycleRememberToken(user)
+    }
+  }
+
+  /**
+   * Generate a new remember token and save it to the database.
+   */
+  private async cycleRememberToken(user: Authenticatable): Promise<void> {
+    const token = generateRandomToken(60)
+    await this.provider.updateRememberToken(user, token)
+  }
+
+  /**
+   * Queue the remember cookie for the middleware to set.
+   * Cookie value format: userId|rememberToken|passwordHash
+   */
+  private queueRememberCookie(user: Authenticatable): void {
+    this._pendingRememberCookie = {
+      id: user.getAuthIdentifier(),
+      token: user.getRememberToken()!,
+      hash: user.getAuthPassword(),
+    }
+  }
+
+  /**
+   * Attempt to recall the user from the remember me cookie.
+   */
+  private async recallFromCookie(): Promise<Authenticatable | null> {
+    const request = this.getRequest()
+    const cookieValue = request.cookie(this.getRememberCookieName())
+    if (!cookieValue) return null
+
+    // Cookie format: userId|rememberToken|passwordHash
+    const parts = cookieValue.split('|')
+    if (parts.length !== 3) return null
+
+    const [userId, token, hash] = parts
+
+    if (!userId || !token) return null
+
+    const user = await this.provider.retrieveByToken(
+      isNaN(Number(userId)) ? userId : Number(userId),
+      token,
+    )
+
+    if (!user) return null
+
+    // Validate the password hash hasn't changed (tamper detection)
+    if (hash !== user.getAuthPassword()) return null
+
+    return user
+  }
+}
+
+/**
+ * Generate a random hex token of the given length.
+ */
+function generateRandomToken(length: number): string {
+  const bytes = new Uint8Array(Math.ceil(length / 2))
+  crypto.getRandomValues(bytes)
+  let token = ''
+  for (let i = 0; i < bytes.length; i++) {
+    token += bytes[i]!.toString(16).padStart(2, '0')
+  }
+  return token.slice(0, length)
+}

package/src/helpers/auth.ts

@@ -0,0 +1,19 @@
+import { Application } from '@mantiq/core'
+import type { AuthManager } from '../AuthManager.ts'
+import type { Guard } from '../contracts/Guard.ts'
+
+export const AUTH_MANAGER = Symbol('AuthManager')
+
+/**
+ * Access the auth manager or a specific guard.
+ *
+ * @example auth()           // AuthManager (proxies to default guard)
+ * @example auth('api')      // Specific guard instance
+ */
+export function auth(): AuthManager
+export function auth(guard: string): Guard
+export function auth(guard?: string): AuthManager | Guard {
+  const manager = Application.getInstance().make<AuthManager>(AUTH_MANAGER)
+  if (guard === undefined) return manager
+  return manager.guard(guard)
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// ── Contracts ─────────────────────────────────────────────────────────────────
+export type { Authenticatable } from './contracts/Authenticatable.ts'
+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'
+
+// ── Core ──────────────────────────────────────────────────────────────────────
+export { AuthManager } from './AuthManager.ts'
+export { AuthServiceProvider } from './AuthServiceProvider.ts'
+
+// ── Guards ────────────────────────────────────────────────────────────────────
+export { SessionGuard } from './guards/SessionGuard.ts'
+export { RequestGuard } from './guards/RequestGuard.ts'
+
+// ── Providers ─────────────────────────────────────────────────────────────────
+export { DatabaseUserProvider } from './providers/DatabaseUserProvider.ts'
+
+// ── Middleware ─────────────────────────────────────────────────────────────────
+export { Authenticate } from './middleware/Authenticate.ts'
+export { RedirectIfAuthenticated } from './middleware/RedirectIfAuthenticated.ts'
+export { EnsureEmailIsVerified } from './middleware/EnsureEmailIsVerified.ts'
+export { ConfirmPassword } from './middleware/ConfirmPassword.ts'
+
+// ── Errors ────────────────────────────────────────────────────────────────────
+export { AuthenticationError } from './errors/AuthenticationError.ts'
+
+// ── Events ────────────────────────────────────────────────────────────────────
+export { Attempting, Authenticated, Login, Failed, Logout, Registered, Lockout } from './events/AuthEvents.ts'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+export { auth, AUTH_MANAGER } from './helpers/auth.ts'

package/src/middleware/Authenticate.ts

@@ -0,0 +1,113 @@
+import type { Middleware, NextFunction, MantiqRequest } from '@mantiq/core'
+import { UnauthorizedError, serializeCookie } from '@mantiq/core'
+import type { AuthManager } from '../AuthManager.ts'
+import { SessionGuard } from '../guards/SessionGuard.ts'
+import { AuthenticationError } from '../errors/AuthenticationError.ts'
+
+const REMEMBER_DURATION = 60 * 60 * 24 * 365 * 5 // 5 years in seconds
+
+/**
+ * Authentication middleware.
+ *
+ * Verifies that the request is authenticated via one of the specified guards.
+ * Usage: `auth` (default guard) or `auth:web,api` (try specific guards).
+ *
+ * For web routes (non-JSON): throws AuthenticationError with redirect to /login.
+ * For API routes (JSON): throws UnauthorizedError (401).
+ *
+ * Also handles setting/clearing the remember me cookie on the response.
+ */
+export class Authenticate implements Middleware {
+  private guardNames: string[] = []
+
+  constructor(private readonly authManager: AuthManager) {}
+
+  setParameters(params: string[]): void {
+    this.guardNames = params
+  }
+
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    // Set request on all guards (resets per-request state)
+    this.authManager.setRequest(request)
+
+    const guards = this.guardNames.length > 0
+      ? this.guardNames
+      : [this.authManager.getDefaultDriver()]
+
+    let authenticatedGuard: string | null = null
+
+    for (const guardName of guards) {
+      const guard = this.authManager.guard(guardName)
+
+      if (await guard.check()) {
+        authenticatedGuard = guardName
+        this.authManager.shouldUse(guardName)
+
+        const user = await guard.user()
+        if (user) request.setUser(user as any)
+        break
+      }
+    }
+
+    if (authenticatedGuard === null) {
+      this.unauthenticated(request, guards)
+    }
+
+    // Process request
+    const response = await next()
+
+    // Handle remember me cookies
+    return this.handleRememberCookie(response, authenticatedGuard!)
+  }
+
+  private unauthenticated(request: MantiqRequest, guards: string[]): never {
+    if (request.expectsJson()) {
+      throw new UnauthorizedError('Unauthenticated.')
+    }
+    throw new AuthenticationError('Unauthenticated.', '/login', guards)
+  }
+
+  private handleRememberCookie(response: Response, guardName: string): Response {
+    const guard = this.authManager.guard(guardName)
+
+    if (!(guard instanceof SessionGuard)) return response
+
+    const headers = new Headers(response.headers)
+
+    // Set remember cookie
+    const pending = guard.getPendingRememberCookie()
+    if (pending) {
+      const cookieValue = `${pending.id}|${pending.token}|${pending.hash}`
+      headers.append(
+        'Set-Cookie',
+        serializeCookie(guard.getRememberCookieName(), cookieValue, {
+          path: '/',
+          httpOnly: true,
+          sameSite: 'Lax',
+          maxAge: REMEMBER_DURATION,
+        }),
+      )
+    }
+
+    // Clear remember cookie
+    if (guard.shouldClearRememberCookie()) {
+      headers.append(
+        'Set-Cookie',
+        serializeCookie(guard.getRememberCookieName(), '', {
+          path: '/',
+          httpOnly: true,
+          sameSite: 'Lax',
+          maxAge: 0, // Expire immediately
+        }),
+      )
+    }
+
+    if (!pending && !guard.shouldClearRememberCookie()) return response
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+}

package/src/middleware/ConfirmPassword.ts

@@ -0,0 +1,40 @@
+import type { Middleware, NextFunction, MantiqRequest } from '@mantiq/core'
+import { MantiqResponse } from '@mantiq/core'
+
+const DEFAULT_TIMEOUT = 10800 // 3 hours in seconds
+
+/**
+ * Requires the user to confirm their password before proceeding.
+ *
+ * Checks `auth.password_confirmed_at` in the session against a timeout.
+ * Usage: `password.confirm` or `password.confirm:7200` (custom timeout).
+ */
+export class ConfirmPassword implements Middleware {
+  private timeoutSeconds = DEFAULT_TIMEOUT
+
+  setParameters(params: string[]): void {
+    if (params[0]) {
+      this.timeoutSeconds = parseInt(params[0], 10) || DEFAULT_TIMEOUT
+    }
+  }
+
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    if (this.shouldConfirm(request)) {
+      if (request.expectsJson()) {
+        return new Response(JSON.stringify({ message: 'Password confirmation required.' }), {
+          status: 423,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      }
+      return MantiqResponse.redirect('/confirm-password')
+    }
+
+    return next()
+  }
+
+  private shouldConfirm(request: MantiqRequest): boolean {
+    const confirmedAt = request.session().get<number>('auth.password_confirmed_at', 0)
+    const elapsed = Math.floor(Date.now() / 1000) - confirmedAt
+    return elapsed > this.timeoutSeconds
+  }
+}

package/src/middleware/EnsureEmailIsVerified.ts

@@ -0,0 +1,22 @@
+import type { Middleware, NextFunction, MantiqRequest } from '@mantiq/core'
+import { ForbiddenError, MantiqResponse } from '@mantiq/core'
+
+/**
+ * Ensures the authenticated user has a verified email address.
+ *
+ * The user model must have a `hasVerifiedEmail()` method.
+ */
+export class EnsureEmailIsVerified implements Middleware {
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    const user = request.user<any>()
+
+    if (!user || typeof user.hasVerifiedEmail !== 'function' || !user.hasVerifiedEmail()) {
+      if (request.expectsJson()) {
+        throw new ForbiddenError('Your email address is not verified.')
+      }
+      return MantiqResponse.redirect('/email/verify')
+    }
+
+    return next()
+  }
+}

package/src/middleware/RedirectIfAuthenticated.ts

@@ -0,0 +1,36 @@
+import type { Middleware, NextFunction, MantiqRequest } from '@mantiq/core'
+import { MantiqResponse } from '@mantiq/core'
+import type { AuthManager } from '../AuthManager.ts'
+
+/**
+ * Guest middleware — redirects authenticated users away (e.g. from login page).
+ *
+ * Usage: `guest` (default guard) or `guest:web,api` (check specific guards).
+ */
+export class RedirectIfAuthenticated implements Middleware {
+  private guardNames: string[] = []
+  private redirectTo = '/dashboard'
+
+  constructor(private readonly authManager: AuthManager) {}
+
+  setParameters(params: string[]): void {
+    this.guardNames = params
+  }
+
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    this.authManager.setRequest(request)
+
+    const guards = this.guardNames.length > 0
+      ? this.guardNames
+      : [this.authManager.getDefaultDriver()]
+
+    for (const guardName of guards) {
+      const guard = this.authManager.guard(guardName)
+      if (await guard.check()) {
+        return MantiqResponse.redirect(this.redirectTo)
+      }
+    }
+
+    return next()
+  }
+}

package/src/providers/DatabaseUserProvider.ts

@@ -0,0 +1,74 @@
+import type { UserProvider } from '../contracts/UserProvider.ts'
+import type { Authenticatable } from '../contracts/Authenticatable.ts'
+import type { Constructor } from '@mantiq/core'
+import type { HashManager } from '@mantiq/core'
+
+/**
+ * Retrieves users from the database via a Model class.
+ * The model must implement the Authenticatable interface.
+ */
+export class DatabaseUserProvider implements UserProvider {
+  constructor(
+    private readonly modelClass: Constructor<any> & { where: any; query: any },
+    private readonly hasher: HashManager,
+  ) {}
+
+  async retrieveById(identifier: string | number): Promise<Authenticatable | null> {
+    const model = this.modelClass as any
+    const instance = await model.find(identifier)
+    return instance ?? null
+  }
+
+  async retrieveByToken(identifier: string | number, token: string): Promise<Authenticatable | null> {
+    const model = this.modelClass as any
+    // Use a fresh instance to get the remember token column name
+    const instance = new this.modelClass() as Authenticatable
+    const identifierName = instance.getAuthIdentifierName()
+    const tokenName = instance.getRememberTokenName()
+
+    const result = await model
+      .where(identifierName, identifier)
+      .where(tokenName, token)
+      .first()
+
+    return result ?? null
+  }
+
+  async updateRememberToken(user: Authenticatable, token: string): Promise<void> {
+    user.setRememberToken(token)
+    // The user is a Model instance — forceFill bypasses guarded, then save
+    const model = user as any
+    model.forceFill({ [user.getRememberTokenName()]: token })
+    await model.save()
+  }
+
+  async retrieveByCredentials(credentials: Record<string, any>): Promise<Authenticatable | null> {
+    const model = this.modelClass as any
+
+    // Filter out password — we only query by non-password fields
+    const query = Object.entries(credentials)
+      .filter(([key]) => key !== 'password')
+      .reduce((q, [key, value]) => q.where(key, value), model.query())
+
+    const result = await query.first()
+    return result ?? null
+  }
+
+  async validateCredentials(user: Authenticatable, credentials: Record<string, any>): Promise<boolean> {
+    const password = credentials.password
+    if (!password) return false
+    return this.hasher.check(password, user.getAuthPassword())
+  }
+
+  async rehashPasswordIfRequired(user: Authenticatable, credentials: Record<string, any>): Promise<void> {
+    const password = credentials.password
+    if (!password) return
+
+    if (this.hasher.needsRehash(user.getAuthPassword())) {
+      const newHash = await this.hasher.make(password)
+      const model = user as any
+      model.forceFill({ [user.getAuthPasswordName()]: newHash })
+      await model.save()
+    }
+  }
+}