@mantiq/core 0.0.1

package/src/middleware/VerifyCsrfToken.ts

@@ -0,0 +1,130 @@
+import type { Middleware, NextFunction } from '../contracts/Middleware.ts'
+import type { MantiqRequest } from '../contracts/Request.ts'
+import { TokenMismatchError } from '../errors/TokenMismatchError.ts'
+import { AesEncrypter } from '../encryption/Encrypter.ts'
+import { serializeCookie } from '../http/Cookie.ts'
+
+/**
+ * CSRF protection middleware.
+ *
+ * Verifies that state-changing requests (POST, PUT, PATCH, DELETE)
+ * include a valid CSRF token. The token is checked against the session.
+ *
+ * Token can be provided via:
+ * - `_token` field in the request body
+ * - `X-CSRF-TOKEN` header (plain token)
+ * - `X-XSRF-TOKEN` header (encrypted token — set from the XSRF-TOKEN cookie)
+ *
+ * Also sets the XSRF-TOKEN cookie (readable by JavaScript) on every response.
+ */
+export class VerifyCsrfToken implements Middleware {
+  /** URIs that should be excluded from CSRF verification. */
+  protected except: string[] = []
+
+  constructor(private readonly encrypter: AesEncrypter) {}
+
+  async handle(request: MantiqRequest, next: NextFunction): Promise<Response> {
+    if (this.shouldVerify(request) && !(await this.tokensMatch(request))) {
+      throw new TokenMismatchError()
+    }
+
+    const response = await next()
+
+    return this.addXsrfCookie(response, request)
+  }
+
+  private shouldVerify(request: MantiqRequest): boolean {
+    const method = request.method()
+
+    // Read-only methods don't need CSRF
+    if (['GET', 'HEAD', 'OPTIONS'].includes(method)) return false
+
+    // Check exclusions
+    const path = request.path()
+    return !this.except.some((pattern) => {
+      if (pattern.endsWith('*')) {
+        return path.startsWith(pattern.slice(0, -1))
+      }
+      return path === pattern
+    })
+  }
+
+  private async tokensMatch(request: MantiqRequest): Promise<boolean> {
+    if (!request.hasSession()) return false
+
+    const sessionToken = request.session().token()
+    const token = await this.getTokenFromRequest(request)
+
+    if (!token || !sessionToken) return false
+
+    return timingSafeEqual(token, sessionToken)
+  }
+
+  private async getTokenFromRequest(request: MantiqRequest): Promise<string | null> {
+    // 1. Check _token in body (form submission)
+    try {
+      const bodyToken = await request.input('_token')
+      if (bodyToken) return bodyToken
+    } catch {
+      // Body parsing might fail — continue
+    }
+
+    // 2. Check X-CSRF-TOKEN header (plain token, e.g. from meta tag)
+    const csrfHeader = request.header('x-csrf-token')
+    if (csrfHeader) return csrfHeader
+
+    // 3. Check X-XSRF-TOKEN header (encrypted, from cookie)
+    const xsrfHeader = request.header('x-xsrf-token')
+    if (xsrfHeader) {
+      try {
+        return await this.encrypter.decrypt(xsrfHeader)
+      } catch {
+        return null
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Add XSRF-TOKEN cookie to response (readable by JavaScript).
+   */
+  private addXsrfCookie(response: Response, request: MantiqRequest): Response {
+    if (!request.hasSession()) return response
+
+    const token = request.session().token()
+    const headers = new Headers(response.headers)
+
+    headers.append(
+      'Set-Cookie',
+      serializeCookie('XSRF-TOKEN', token, {
+        path: '/',
+        httpOnly: false, // Must be readable by JS
+        sameSite: 'Lax',
+      }),
+    )
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks on token verification.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+
+  const encoder = new TextEncoder()
+  const bufA = encoder.encode(a)
+  const bufB = encoder.encode(b)
+
+  let result = 0
+  for (let i = 0; i < bufA.length; i++) {
+    result |= bufA[i]! ^ bufB[i]!
+  }
+  return result === 0
+}

package/src/providers/CoreServiceProvider.ts

@@ -0,0 +1,97 @@
+import { ServiceProvider } from '../contracts/ServiceProvider.ts'
+import { RouterImpl } from '../routing/Router.ts'
+import { HttpKernel } from '../http/Kernel.ts'
+import { WebSocketKernel } from '../websocket/WebSocketKernel.ts'
+import { DefaultExceptionHandler } from '../exceptions/Handler.ts'
+import { ConfigRepository } from '../config/ConfigRepository.ts'
+import { CorsMiddleware } from '../middleware/Cors.ts'
+import { TrimStringsMiddleware } from '../middleware/TrimStrings.ts'
+import { StartSession } from '../middleware/StartSession.ts'
+import { EncryptCookies } from '../middleware/EncryptCookies.ts'
+import { VerifyCsrfToken } from '../middleware/VerifyCsrfToken.ts'
+import { ROUTER } from '../helpers/route.ts'
+import { ENCRYPTER } from '../helpers/encrypt.ts'
+import { AesEncrypter } from '../encryption/Encrypter.ts'
+import { HashManager } from '../hashing/HashManager.ts'
+import { CacheManager } from '../cache/CacheManager.ts'
+import { SessionManager } from '../session/SessionManager.ts'
+
+// Symbols used as abstract keys for non-class bindings
+export const HTTP_KERNEL = Symbol('HttpKernel')
+export const EXCEPTION_HANDLER = Symbol('ExceptionHandler')
+export const WS_KERNEL = Symbol('WebSocketKernel')
+
+/**
+ * The first provider loaded. Registers all core framework bindings.
+ *
+ * Binding order matters within register():
+ * - ConfigRepository is already bound by Application.loadConfig() before any provider runs
+ * - This provider registers Router, Kernels, ExceptionHandler
+ */
+export class CoreServiceProvider extends ServiceProvider {
+  override register(): void {
+    const configRepo = this.app.make(ConfigRepository)
+
+    // Router — singleton, receives config for URL generation
+    this.app.singleton(RouterImpl, (c) => {
+      const config = c.make(ConfigRepository)
+      return new RouterImpl(config)
+    })
+
+    // Alias the router under its symbol so route() helper can find it
+    this.app.alias(RouterImpl, ROUTER)
+
+    // WebSocket kernel — singleton, no deps
+    this.app.singleton(WebSocketKernel, () => new WebSocketKernel())
+
+    // Exception handler — singleton
+    this.app.singleton(DefaultExceptionHandler, () => new DefaultExceptionHandler())
+
+    // ── Encryption ────────────────────────────────────────────────────────
+    // AesEncrypter is async to create (key import), so we register a placeholder.
+    // Actual initialization happens in boot(). If no APP_KEY, encryption features
+    // will throw on use rather than on startup (graceful degradation for apps
+    // that don't need encryption).
+
+    // ── Hashing ───────────────────────────────────────────────────────────
+    this.app.singleton(HashManager, () => {
+      return new HashManager(configRepo.get('hashing', {}))
+    })
+
+    // ── Cache ─────────────────────────────────────────────────────────────
+    this.app.singleton(CacheManager, () => {
+      return new CacheManager(configRepo.get('cache', {}))
+    })
+
+    // ── Sessions ──────────────────────────────────────────────────────────
+    this.app.singleton(SessionManager, () => {
+      return new SessionManager(configRepo.get('session', {}))
+    })
+
+    // ── Built-in middleware ────────────────────────────────────────────────
+    this.app.singleton(CorsMiddleware, (c) => new CorsMiddleware(c.make(ConfigRepository)))
+    this.app.singleton(TrimStringsMiddleware, () => new TrimStringsMiddleware())
+    this.app.singleton(StartSession, (c) => new StartSession(c.make(SessionManager)))
+
+    // EncryptCookies and VerifyCsrfToken depend on AesEncrypter (set up in boot)
+    this.app.bind(EncryptCookies, (c) => new EncryptCookies(c.make<AesEncrypter>(ENCRYPTER)))
+    this.app.bind(VerifyCsrfToken, (c) => new VerifyCsrfToken(c.make<AesEncrypter>(ENCRYPTER)))
+
+    // HTTP kernel — singleton, depends on Router + ExceptionHandler + WsKernel
+    this.app.singleton(HttpKernel, (c) => {
+      const router = c.make(RouterImpl)
+      const exceptionHandler = c.make(DefaultExceptionHandler)
+      const wsKernel = c.make(WebSocketKernel)
+      return new HttpKernel(c, router, exceptionHandler, wsKernel)
+    })
+  }
+
+  override async boot(): Promise<void> {
+    // ── Encryption (async key import) ─────────────────────────────────────
+    const appKey = this.app.make(ConfigRepository).get('app.key', undefined) as string | undefined
+    if (appKey) {
+      const encrypter = await AesEncrypter.fromAppKey(appKey)
+      this.app.instance(ENCRYPTER, encrypter)
+    }
+  }
+}

package/src/routing/ResourceRegistrar.ts

@@ -0,0 +1,64 @@
+import type { Constructor } from '../contracts/Container.ts'
+import type { Router } from '../contracts/Router.ts'
+
+const RESOURCE_METHODS = ['index', 'create', 'store', 'show', 'edit', 'update', 'destroy'] as const
+const API_RESOURCE_METHODS = ['index', 'store', 'show', 'update', 'destroy'] as const
+
+/**
+ * Generates RESTful route sets for a controller.
+ *
+ * resource('photos', PhotoController) generates:
+ *   GET    /photos           → index    (photos.index)
+ *   GET    /photos/create    → create   (photos.create)
+ *   POST   /photos           → store    (photos.store)
+ *   GET    /photos/:photo    → show     (photos.show)
+ *   GET    /photos/:photo/edit → edit   (photos.edit)
+ *   PUT    /photos/:photo    → update   (photos.update)
+ *   DELETE /photos/:photo    → destroy  (photos.destroy)
+ *
+ * apiResource omits create + edit (those are frontend pages).
+ */
+export class ResourceRegistrar {
+  constructor(private readonly router: Router) {}
+
+  register(name: string, controller: Constructor<any>, apiOnly = false): void {
+    const methods = apiOnly ? API_RESOURCE_METHODS : RESOURCE_METHODS
+    const param = this.singularize(name)
+    const prefix = `/${name}`
+
+    for (const method of methods) {
+      switch (method) {
+        case 'index':
+          this.router.get(prefix, [controller, 'index']).name(`${name}.index`)
+          break
+        case 'create':
+          this.router.get(`${prefix}/create`, [controller, 'create']).name(`${name}.create`)
+          break
+        case 'store':
+          this.router.post(prefix, [controller, 'store']).name(`${name}.store`)
+          break
+        case 'show':
+          this.router.get(`${prefix}/:${param}`, [controller, 'show']).name(`${name}.show`)
+          break
+        case 'edit':
+          this.router.get(`${prefix}/:${param}/edit`, [controller, 'edit']).name(`${name}.edit`)
+          break
+        case 'update':
+          this.router.match(['PUT', 'PATCH'], `${prefix}/:${param}`, [controller, 'update']).name(`${name}.update`)
+          break
+        case 'destroy':
+          this.router.delete(`${prefix}/:${param}`, [controller, 'destroy']).name(`${name}.destroy`)
+          break
+      }
+    }
+  }
+
+  private singularize(name: string): string {
+    // Simple singularization for common cases
+    const last = name.split('/').pop() ?? name
+    if (last.endsWith('ies')) return last.slice(0, -3) + 'y'
+    if (last.endsWith('ses') || last.endsWith('xes') || last.endsWith('zes')) return last.slice(0, -2)
+    if (last.endsWith('s') && !last.endsWith('ss')) return last.slice(0, -1)
+    return last
+  }
+}

package/src/routing/Route.ts

@@ -0,0 +1,40 @@
+import type { HttpMethod, RouteAction, RouterRoute } from '../contracts/Router.ts'
+
+export class Route implements RouterRoute {
+  public routeName?: string
+  public middlewareList: string[] = []
+  public wheres: Record<string, RegExp> = {}
+
+  constructor(
+    public readonly methods: HttpMethod[],
+    public readonly path: string,
+    public readonly action: RouteAction,
+  ) {}
+
+  name(name: string): this {
+    this.routeName = name
+    return this
+  }
+
+  middleware(...middleware: string[]): this {
+    this.middlewareList.push(...middleware)
+    return this
+  }
+
+  where(param: string, pattern: string | RegExp): this {
+    this.wheres[param] = typeof pattern === 'string' ? new RegExp(pattern) : pattern
+    return this
+  }
+
+  whereNumber(param: string): this {
+    return this.where(param, /^\d+$/)
+  }
+
+  whereAlpha(param: string): this {
+    return this.where(param, /^[a-zA-Z]+$/)
+  }
+
+  whereUuid(param: string): this {
+    return this.where(param, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
+  }
+}

package/src/routing/RouteCollection.ts

@@ -0,0 +1,50 @@
+import type { HttpMethod } from '../contracts/Router.ts'
+import { Route } from './Route.ts'
+
+/**
+ * Stores all registered routes, indexed by HTTP method for fast lookup.
+ */
+export class RouteCollection {
+  private routes = new Map<HttpMethod, Route[]>()
+  private namedRoutes = new Map<string, Route>()
+
+  add(route: Route): void {
+    const methods = Array.isArray(route.methods) ? route.methods : [route.methods]
+    for (const method of methods) {
+      if (!this.routes.has(method)) this.routes.set(method, [])
+      this.routes.get(method)!.push(route)
+    }
+    if (route.routeName) {
+      this.namedRoutes.set(route.routeName, route)
+    }
+  }
+
+  getByMethod(method: HttpMethod): Route[] {
+    return this.routes.get(method) ?? []
+  }
+
+  getByName(name: string): Route | undefined {
+    return this.namedRoutes.get(name)
+  }
+
+  /** Update named route index when a name is set after route registration. */
+  indexName(route: Route): void {
+    if (route.routeName) {
+      this.namedRoutes.set(route.routeName, route)
+    }
+  }
+
+  all(): Route[] {
+    const seen = new Set<Route>()
+    const result: Route[] = []
+    for (const routes of this.routes.values()) {
+      for (const route of routes) {
+        if (!seen.has(route)) {
+          seen.add(route)
+          result.push(route)
+        }
+      }
+    }
+    return result
+  }
+}

package/src/routing/RouteMatcher.ts

@@ -0,0 +1,92 @@
+import type { Route } from './Route.ts'
+
+export interface MatchResult {
+  route: Route
+  params: Record<string, any>
+}
+
+/**
+ * Matches a URL path against a route pattern.
+ *
+ * Supported syntax:
+ * - Static segments: /users/profile
+ * - Required params: /users/:id
+ * - Optional params: /posts/:slug?
+ * - Wildcard (end only): /files/*
+ */
+export class RouteMatcher {
+  static match(route: Route, pathname: string): MatchResult | null {
+    const params: Record<string, any> = {}
+    const routeSegments = route.path.split('/').filter(Boolean)
+    const pathSegments = pathname.split('/').filter(Boolean)
+
+    let routeIdx = 0
+    let pathIdx = 0
+
+    while (routeIdx < routeSegments.length) {
+      const seg = routeSegments[routeIdx]!
+
+      // Wildcard — matches the rest
+      if (seg === '*') {
+        params['*'] = pathSegments.slice(pathIdx).join('/')
+        return this.checkConstraints(route, params) ? { route, params } : null
+      }
+
+      // Optional param
+      if (seg.startsWith(':') && seg.endsWith('?')) {
+        const name = seg.slice(1, -1)
+        if (pathIdx < pathSegments.length) {
+          params[name] = pathSegments[pathIdx]
+          pathIdx++
+        } else {
+          params[name] = undefined
+        }
+        routeIdx++
+        continue
+      }
+
+      // Required param
+      if (seg.startsWith(':')) {
+        const name = seg.slice(1)
+        if (pathIdx >= pathSegments.length) return null
+        params[name] = pathSegments[pathIdx]
+        pathIdx++
+        routeIdx++
+        continue
+      }
+
+      // Static segment
+      if (pathIdx >= pathSegments.length || pathSegments[pathIdx] !== seg) {
+        return null
+      }
+
+      pathIdx++
+      routeIdx++
+    }
+
+    // All route segments consumed — path must also be fully consumed
+    if (pathIdx !== pathSegments.length) return null
+
+    // Check constraints
+    if (!this.checkConstraints(route, params)) return null
+
+    // Coerce numeric params
+    for (const [key, regex] of Object.entries(route.wheres)) {
+      if (regex.source === '^\\d+$' && params[key] !== undefined) {
+        params[key] = Number(params[key])
+      }
+    }
+
+    return { route, params }
+  }
+
+  private static checkConstraints(route: Route, params: Record<string, any>): boolean {
+    for (const [param, pattern] of Object.entries(route.wheres)) {
+      const value = params[param]
+      if (value !== undefined && !pattern.test(String(value))) {
+        return false
+      }
+    }
+    return true
+  }
+}