@mantiq/core 0.5.22 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/core",
-  "version": "0.5.22",
+  "version": "0.6.0",
   "description": "Service container, router, middleware, HTTP kernel, config, and exception handler",
   "type": "module",
   "license": "MIT",

package/src/application/Application.ts

@@ -210,11 +210,64 @@ export class Application extends ContainerImpl {
     coreProviders: Constructor<ServiceProvider>[] = [],
     userProviders: Constructor<ServiceProvider>[] = [],
   ): Promise<void> {
+    this.validateEnvironment()
     const packageProviders = await this.discoverPackageProviders()
     await this.registerProviders([...coreProviders, ...packageProviders, ...userProviders])
     await this.bootProviders()
   }
 
+  /**
+   * Validate environment variables on startup.
+   * Called at the beginning of bootstrap() to catch misconfigurations early.
+   *
+   * Checks:
+   * - APP_ENV must be set
+   * - APP_KEY format (if set): must start with 'base64:' and decode to exactly 32 bytes
+   * - Warns if APP_DEBUG=true in production
+   */
+  validateEnvironment(): void {
+    // APP_ENV must be set
+    if (!process.env['APP_ENV']) {
+      throw new Error(
+        'APP_ENV is not set. Set it in your .env file (e.g., APP_ENV=local).',
+      )
+    }
+
+    // Validate APP_KEY format when present
+    const appKey = process.env['APP_KEY']
+    if (appKey) {
+      if (!appKey.startsWith('base64:')) {
+        throw new Error(
+          'APP_KEY must start with "base64:". Generate one with: bun mantiq key:generate',
+        )
+      }
+
+      try {
+        const decoded = Buffer.from(appKey.slice(7), 'base64')
+        if (decoded.length !== 32) {
+          throw new Error(
+            `APP_KEY must decode to exactly 32 bytes (got ${decoded.length}). ` +
+            'Generate one with: bun mantiq key:generate',
+          )
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.startsWith('APP_KEY must')) {
+          throw e
+        }
+        throw new Error(
+          'APP_KEY contains invalid base64 data. Generate one with: bun mantiq key:generate',
+        )
+      }
+    }
+
+    // Warn on APP_DEBUG=true in production
+    if (process.env['APP_ENV'] === 'production' && process.env['APP_DEBUG'] === 'true') {
+      console.warn(
+        '[Mantiq] WARNING: APP_DEBUG=true in production. This may expose sensitive data.',
+      )
+    }
+  }
+
   // ── Provider lifecycle ────────────────────────────────────────────────────
 
   /**
@@ -245,14 +298,22 @@ export class Application extends ContainerImpl {
   /**
    * Boot all registered (non-deferred) providers.
    * Called after ALL providers have been registered.
+   *
+   * Errors are re-thrown with descriptive messages so they surface
+   * immediately rather than being silently swallowed.
    */
   async bootProviders(): Promise<void> {
     for (const provider of this.providers) {
+      const name = provider.constructor?.name ?? 'Unknown'
       try {
         await provider.boot()
       } catch (e) {
-        const name = provider.constructor?.name ?? 'Unknown'
-        console.error(`[Mantiq] ${name}.boot() failed:`, (e as Error)?.stack ?? e)
+        // Re-throw with context so the developer knows which provider failed.
+        // Previously errors were only logged, masking critical boot failures.
+        throw new Error(
+          `[Mantiq] ${name}.boot() failed: ${(e as Error)?.message ?? e}`,
+          { cause: e },
+        )
       }
     }
     this.booted = true
@@ -277,6 +338,10 @@ export class Application extends ContainerImpl {
   /**
    * Override make() to handle deferred provider loading.
    * If a binding isn't found in the container, check deferred providers.
+   *
+   * Deferred providers are registered and booted synchronously where possible.
+   * If register() or boot() return a Promise, this method will throw — callers
+   * must use makeAsync() for providers that require async initialization.
    */
   override make<T>(abstract: Bindable<T>): T {
     try {
@@ -292,17 +357,74 @@ export class Application extends ContainerImpl {
           for (const [key, p] of this.deferredProviders.entries()) {
             if (p === deferredProvider) this.deferredProviders.delete(key)
           }
-          // Register + boot the deferred provider now
-          const boot = async () => {
+
+          const providerName = deferredProvider.constructor?.name ?? 'DeferredProvider'
+
+          // Register the deferred provider synchronously. If register()
+          // returns a Promise, it means the provider requires async init —
+          // we cannot silently fire-and-forget because make() would return
+          // before the binding is registered.
+          const registerResult = deferredProvider.register()
+          if (registerResult && typeof (registerResult as any).then === 'function') {
+            throw new Error(
+              `[Mantiq] ${providerName}.register() is async but was triggered via synchronous make(). ` +
+              `Use await app.makeAsync(${String((abstract as any)?.name ?? abstract)}) instead.`,
+            )
+          }
+
+          // Boot the deferred provider synchronously.
+          const bootResult = deferredProvider.boot()
+          if (bootResult && typeof (bootResult as any).then === 'function') {
+            throw new Error(
+              `[Mantiq] ${providerName}.boot() is async but was triggered via synchronous make(). ` +
+              `Use await app.makeAsync(${String((abstract as any)?.name ?? abstract)}) instead.`,
+            )
+          }
+
+          this.providers.push(deferredProvider)
+          return super.make(abstract)
+        }
+      }
+      throw err
+    }
+  }
+
+  /**
+   * Async version of make() that properly awaits deferred provider boot.
+   *
+   * Use this when the deferred provider's register() or boot() may be async.
+   * For synchronous providers, make() is sufficient and faster.
+   */
+  async makeAsync<T>(abstract: Bindable<T>): Promise<T> {
+    try {
+      return super.make(abstract)
+    } catch (err) {
+      if (
+        err instanceof ContainerResolutionError &&
+        err.reason === 'not_bound'
+      ) {
+        const deferredProvider = this.deferredProviders.get(abstract)
+        if (deferredProvider) {
+          // Remove from deferred map so we don't loop
+          for (const [key, p] of this.deferredProviders.entries()) {
+            if (p === deferredProvider) this.deferredProviders.delete(key)
+          }
+
+          const providerName = deferredProvider.constructor?.name ?? 'DeferredProvider'
+
+          // Await register + boot so the binding is fully available
+          // before we resolve it. Errors propagate to the caller.
+          try {
             await deferredProvider.register()
             await deferredProvider.boot()
-            this.providers.push(deferredProvider)
+          } catch (e) {
+            throw new Error(
+              `[Mantiq] ${providerName} deferred boot failed: ${(e as Error)?.message ?? e}`,
+              { cause: e },
+            )
           }
-          // Deferred boot — catch and log errors instead of swallowing
-          boot().catch((e) => {
-            const name = deferredProvider.constructor?.name ?? 'DeferredProvider'
-            console.error(`[Mantiq] ${name} deferred boot failed:`, (e as Error)?.stack ?? e)
-          })
+
+          this.providers.push(deferredProvider)
           return super.make(abstract)
         }
       }

package/src/cache/FileCacheStore.ts

@@ -1,6 +1,7 @@
 import type { CacheStore } from '../contracts/Cache.ts'
 import { join } from 'node:path'
-import { mkdir, rm, readdir } from 'node:fs/promises'
+import { mkdir, rm, readdir, rename } from 'node:fs/promises'
+import { randomBytes } from 'node:crypto'
 
 interface FileCachePayload {
   value: unknown
@@ -80,10 +81,42 @@ export class FileCacheStore implements CacheStore {
     }
   }
 
+  /**
+   * Fix #194: Atomic increment using write-to-temp + rename to prevent
+   * TOCTOU race conditions where concurrent increments could lose updates.
+   */
   async increment(key: string, value = 1): Promise<number> {
-    const current = await this.get<number>(key)
-    const newValue = (current ?? 0) + value
-    await this.put(key, newValue)
+    await this.ensureDirectory()
+    const targetPath = this.path(key)
+    const file = Bun.file(targetPath)
+
+    let current = 0
+    if (await file.exists()) {
+      try {
+        const payload: FileCachePayload = await file.json()
+        if (payload.expiresAt !== null && Date.now() > payload.expiresAt) {
+          // Expired — treat as 0
+        } else {
+          current = (payload.value as number) ?? 0
+        }
+      } catch {
+        // Corrupted file — start from 0
+      }
+    }
+
+    const newValue = current + value
+
+    // Atomic write: temp file + rename to avoid partial reads by concurrent operations
+    const tmpPath = join(this.directory, `_tmp_${randomBytes(8).toString('hex')}.cache`)
+    const payload: FileCachePayload = { value: newValue, expiresAt: null }
+    await Bun.write(tmpPath, JSON.stringify(payload))
+
+    try {
+      await rename(tmpPath, targetPath)
+    } catch {
+      try { await rm(tmpPath) } catch { /* ignore */ }
+    }
+
     return newValue
   }
 
@@ -94,13 +127,44 @@ export class FileCacheStore implements CacheStore {
   /**
    * Store an item in the cache if the key does not already exist.
    *
-   * Note: File-based storage cannot guarantee atomicity. Between the existence
-   * check and the write, another process could set the key. For truly atomic
-   * add semantics, use the Redis or Memcached cache driver.
+   * Uses write-to-temp + rename to avoid TOCTOU race conditions.
+   * If the key already exists (and is not expired), returns false.
    */
   async add(key: string, value: unknown, ttl?: number): Promise<boolean> {
-    if (await this.has(key)) return false
-    await this.put(key, value, ttl)
+    await this.ensureDirectory()
+
+    const targetPath = this.path(key)
+
+    // Check if key already exists and is not expired
+    const file = Bun.file(targetPath)
+    if (await file.exists()) {
+      try {
+        const payload: FileCachePayload = await file.json()
+        if (payload.expiresAt === null || Date.now() <= payload.expiresAt) {
+          return false
+        }
+        // Expired — fall through to overwrite
+      } catch {
+        // Corrupted file — fall through to overwrite
+      }
+    }
+
+    // Write to a temp file first, then atomically rename into place
+    const tmpPath = join(this.directory, `_tmp_${randomBytes(8).toString('hex')}.cache`)
+    const payload: FileCachePayload = {
+      value,
+      expiresAt: ttl != null ? Date.now() + ttl * 1000 : null,
+    }
+    await Bun.write(tmpPath, JSON.stringify(payload))
+
+    try {
+      await rename(tmpPath, targetPath)
+    } catch {
+      // Cleanup temp file on failure
+      try { await rm(tmpPath) } catch { /* ignore */ }
+      return false
+    }
+
     return true
   }
 

package/src/cache/MemoryCacheStore.ts

@@ -43,6 +43,14 @@ export class MemoryCacheStore implements CacheStore {
     this.store.clear()
   }
 
+  /**
+   * Increment a cached numeric value.
+   *
+   * Note (#194): This get-then-put is safe in single-threaded Bun because
+   * there is no I/O between the read and write — the event loop cannot
+   * yield to another task mid-execution. If Bun gains multi-threaded
+   * workers sharing memory, this would need a lock or atomic operation.
+   */
   async increment(key: string, value = 1): Promise<number> {
     const current = await this.get<number>(key)
     const newValue = (current ?? 0) + value

package/src/contracts/Request.ts

@@ -11,8 +11,8 @@ export interface MantiqRequest {
   // ── Input ────────────────────────────────────────────────────────────────
   query(key: string, defaultValue?: string): string
   query(): Record<string, string>
-  input(key: string, defaultValue?: any): Promise<any>
-  input(): Promise<Record<string, any>>
+  input<T = any>(key: string, defaultValue?: any): Promise<T>
+  input<T = Record<string, any>>(): Promise<T>
   only(...keys: string[]): Promise<Record<string, any>>
   except(...keys: string[]): Promise<Record<string, any>>
   has(...keys: string[]): boolean
@@ -42,6 +42,7 @@ export interface MantiqRequest {
   param(key: string, defaultValue?: any): any
   params(): Record<string, any>
   setRouteParams(params: Record<string, any>): void
+  setRouteParam(key: string, value: any): void
 
   // ── Session ──────────────────────────────────────────────────────────────
   session(): SessionStore

package/src/contracts/Router.ts

@@ -21,6 +21,7 @@ export interface RouteMatch {
   params: Record<string, any>
   middleware: string[]
   routeName?: string | undefined
+  bindings?: Map<string, { model: any; key: string }>
 }
 
 export interface RouteDefinition {
@@ -60,4 +61,5 @@ export interface RouterRoute {
   whereNumber(param: string): this
   whereAlpha(param: string): this
   whereUuid(param: string): this
+  bind(param: string, model: any, key?: string): this
 }

package/src/encryption/errors.ts

@@ -1,11 +1,12 @@
 import { MantiqError } from '../errors/MantiqError.ts'
+import { ErrorCodes } from '../errors/ErrorCodes.ts'
 
 /**
  * Thrown when encryption fails (e.g. invalid key, algorithm error).
  */
 export class EncryptionError extends MantiqError {
   constructor(message = 'Could not encrypt the data.', context?: Record<string, any>) {
-    super(message, context)
+    super(message, context, ErrorCodes.ENCRYPTION_FAILED)
   }
 }
 
@@ -14,7 +15,7 @@ export class EncryptionError extends MantiqError {
  */
 export class DecryptionError extends MantiqError {
   constructor(message = 'Could not decrypt the data.', context?: Record<string, any>) {
-    super(message, context)
+    super(message, context, ErrorCodes.DECRYPTION_FAILED)
   }
 }
 
@@ -25,6 +26,8 @@ export class MissingAppKeyError extends MantiqError {
   constructor() {
     super(
       'No application encryption key has been specified. Set the APP_KEY environment variable (use "base64:<key>" format for raw keys).',
+      undefined,
+      ErrorCodes.MISSING_APP_KEY,
     )
   }
 }

package/src/errors/ConfigKeyNotFoundError.ts

@@ -1,7 +1,12 @@
 import { MantiqError } from './MantiqError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ConfigKeyNotFoundError extends MantiqError {
   constructor(public readonly key: string) {
-    super(`Config key '${key}' not found and no default value provided.`)
+    super(
+      `Config key '${key}' not found and no default value provided.`,
+      undefined,
+      ErrorCodes.CONFIG_NOT_FOUND,
+    )
   }
 }

package/src/errors/ContainerResolutionError.ts

@@ -1,4 +1,5 @@
 import { MantiqError } from './MantiqError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ContainerResolutionError extends MantiqError {
   constructor(
@@ -8,6 +9,8 @@ export class ContainerResolutionError extends MantiqError {
   ) {
     super(
       `Cannot resolve ${String(abstract)}: ${reason}.${details ? ' ' + details : ''}`,
+      undefined,
+      ErrorCodes.CONTAINER_RESOLUTION,
     )
   }
 }

package/src/errors/ErrorCodes.ts

@@ -0,0 +1,27 @@
+/**
+ * Structured error codes for all MantiqJS framework errors.
+ *
+ * Each error code follows the pattern `E_{CATEGORY}_{DESCRIPTION}`.
+ */
+export const ErrorCodes = {
+  AUTH_UNAUTHENTICATED: 'E_AUTH_UNAUTHENTICATED',
+  AUTH_UNAUTHORIZED: 'E_AUTH_UNAUTHORIZED',
+  AUTH_FORBIDDEN: 'E_AUTH_FORBIDDEN',
+  VALIDATION_FAILED: 'E_VALIDATION_FAILED',
+  MODEL_NOT_FOUND: 'E_MODEL_NOT_FOUND',
+  ROUTE_NOT_FOUND: 'E_ROUTE_NOT_FOUND',
+  CSRF_MISMATCH: 'E_CSRF_MISMATCH',
+  ENCRYPTION_FAILED: 'E_ENCRYPTION_FAILED',
+  DECRYPTION_FAILED: 'E_DECRYPTION_FAILED',
+  MISSING_APP_KEY: 'E_MISSING_APP_KEY',
+  RATE_LIMITED: 'E_RATE_LIMITED',
+  CONTAINER_RESOLUTION: 'E_CONTAINER_RESOLUTION',
+  CONFIG_NOT_FOUND: 'E_CONFIG_NOT_FOUND',
+  QUERY_ERROR: 'E_QUERY_ERROR',
+  CONNECTION_LOST: 'E_CONNECTION_LOST',
+  CONNECTION_FAILED: 'E_CONNECTION_FAILED',
+  DRIVER_NOT_SUPPORTED: 'E_DRIVER_NOT_SUPPORTED',
+  HTTP_ERROR: 'E_HTTP_ERROR',
+} as const
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes]

package/src/errors/ForbiddenError.ts

@@ -1,7 +1,8 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ForbiddenError extends HttpError {
   constructor(message = 'Forbidden', headers?: Record<string, string>) {
-    super(403, message, headers)
+    super(403, message, headers, undefined, ErrorCodes.AUTH_FORBIDDEN)
   }
 }

package/src/errors/HttpError.ts

@@ -1,4 +1,6 @@
 import { MantiqError } from './MantiqError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
+import type { ErrorCode } from './ErrorCodes.ts'
 
 /**
  * Base class for all HTTP-facing errors.
@@ -10,7 +12,8 @@ export class HttpError extends MantiqError {
     message: string,
     public readonly headers?: Record<string, string>,
     context?: Record<string, any>,
+    errorCode?: ErrorCode | string,
   ) {
-    super(message, context)
+    super(message, context, errorCode ?? ErrorCodes.HTTP_ERROR)
   }
 }

package/src/errors/MantiqError.ts

@@ -1,14 +1,25 @@
+import type { ErrorCode } from './ErrorCodes.ts'
+
 /**
  * Base error class for all MantiqJS errors.
- * All packages must throw subclasses of this — never raw Error.
+ * All packages must throw subclasses of this -- never raw Error.
  */
 export class MantiqError extends Error {
+  /**
+   * Machine-readable error code for structured error handling.
+   * Subclasses should set this to the appropriate `ErrorCodes.*` value.
+   * Accepts any string to allow packages like OAuth to use spec-defined codes.
+   */
+  public readonly errorCode: ErrorCode | string | undefined
+
   constructor(
     message: string,
     public readonly context?: Record<string, any>,
+    errorCode?: ErrorCode | string,
   ) {
     super(message)
     this.name = this.constructor.name
+    this.errorCode = errorCode
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, this.constructor)
     }

package/src/errors/NotFoundError.ts

@@ -1,7 +1,8 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class NotFoundError extends HttpError {
   constructor(message = 'Not Found', headers?: Record<string, string>) {
-    super(404, message, headers)
+    super(404, message, headers, undefined, ErrorCodes.ROUTE_NOT_FOUND)
   }
 }

package/src/errors/TokenMismatchError.ts

@@ -1,10 +1,11 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 /**
  * Thrown when the CSRF token is missing or invalid.
  */
 export class TokenMismatchError extends HttpError {
   constructor(message = 'CSRF token mismatch.') {
-    super(419, message)
+    super(419, message, undefined, undefined, ErrorCodes.CSRF_MISMATCH)
   }
 }

package/src/errors/TooManyRequestsError.ts

@@ -1,10 +1,11 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class TooManyRequestsError extends HttpError {
   constructor(
     message = 'Too Many Requests',
     public readonly retryAfter?: number,
   ) {
-    super(429, message, retryAfter ? { 'Retry-After': String(retryAfter) } : undefined)
+    super(429, message, retryAfter ? { 'Retry-After': String(retryAfter) } : undefined, undefined, ErrorCodes.RATE_LIMITED)
   }
 }

package/src/errors/UnauthorizedError.ts

@@ -1,7 +1,8 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class UnauthorizedError extends HttpError {
   constructor(message = 'Unauthorized', headers?: Record<string, string>) {
-    super(401, message, headers)
+    super(401, message, headers, undefined, ErrorCodes.AUTH_UNAUTHENTICATED)
   }
 }

package/src/errors/ValidationError.ts

@@ -1,10 +1,11 @@
 import { HttpError } from './HttpError.ts'
+import { ErrorCodes } from './ErrorCodes.ts'
 
 export class ValidationError extends HttpError {
   constructor(
     public readonly errors: Record<string, string[]>,
     message = 'The given data was invalid.',
   ) {
-    super(422, message, undefined, { errors })
+    super(422, message, undefined, { errors }, ErrorCodes.VALIDATION_FAILED)
   }
 }

package/src/exceptions/Handler.ts

@@ -8,6 +8,11 @@ import { UnauthorizedError } from '../errors/UnauthorizedError.ts'
 import { MantiqResponse } from '../http/Response.ts'
 import { renderDevErrorPage } from './DevErrorPage.ts'
 
+/** Security: escape HTML special characters to prevent XSS in error pages. */
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+}
+
 export class DefaultExceptionHandler implements ExceptionHandler {
   dontReport: Constructor<Error>[] = [
     NotFoundError,
@@ -102,12 +107,15 @@ export class DefaultExceptionHandler implements ExceptionHandler {
   }
 
   private genericHtmlPage(status: number, message: string): string {
+    // Security: escape message to prevent XSS — error messages may contain
+    // user-controlled input (e.g., URL paths, query parameters).
+    const safeMessage = escapeHtml(message)
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${status} ${message}</title>
+  <title>${status} ${safeMessage}</title>
   <style>
     body { font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f7fafc; color: #2d3748; }
     .box { text-align: center; }
@@ -118,7 +126,7 @@ export class DefaultExceptionHandler implements ExceptionHandler {
 <body>
   <div class="box">
     <h1>${status}</h1>
-    <p>${message}</p>
+    <p>${safeMessage}</p>
   </div>
 </body>
 </html>`

package/src/helpers/signedUrl.ts

@@ -0,0 +1,26 @@
+import { Application } from '../application/Application.ts'
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
+import { UrlSigner } from '../url/UrlSigner.ts'
+import { ENCRYPTER } from './encrypt.ts'
+
+/**
+ * Create a signed URL.
+ *
+ * @example const url = await signedUrl('https://example.com/verify?user=42')
+ */
+export async function signedUrl(url: string, expiresAt?: Date): Promise<string> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.sign(url, expiresAt)
+}
+
+/**
+ * Validate a signed URL.
+ *
+ * @example const valid = await hasValidSignature('https://example.com/verify?user=42&signature=...')
+ */
+export async function hasValidSignature(url: string): Promise<boolean> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.validate(url)
+}

package/src/helpers/url.ts

@@ -0,0 +1,31 @@
+import { Application } from '../application/Application.ts'
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
+import { UrlSigner } from '../url/UrlSigner.ts'
+import { ENCRYPTER } from './encrypt.ts'
+
+/**
+ * Create a signed URL.
+ *
+ * @example
+ * const url = await signedUrl('https://example.com/unsubscribe?user=42')
+ * const temp = await signedUrl('https://example.com/download', new Date(Date.now() + 3600_000))
+ */
+export async function signedUrl(url: string, expiresAt?: Date): Promise<string> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.sign(url, expiresAt)
+}
+
+/**
+ * Validate a signed URL: verify signature and check expiration.
+ *
+ * @example
+ * if (await hasValidSignature(request.fullUrl())) {
+ *   // URL is authentic and not expired
+ * }
+ */
+export async function hasValidSignature(url: string): Promise<boolean> {
+  const encrypter = Application.getInstance().make<AesEncrypter>(ENCRYPTER)
+  const signer = new UrlSigner(encrypter)
+  return signer.validate(url)
+}