@stravigor/core 0.1.0

package/src/encryption/helpers.ts

@@ -0,0 +1,158 @@
+import EncryptionManager from './encryption_manager.ts'
+
+/**
+ * Encryption helper — the primary API for all cryptographic operations.
+ *
+ * Uses the configured APP_KEY for symmetric encryption and HMAC signing.
+ * Password hashing uses argon2id via Bun.password (no key needed).
+ *
+ * @example
+ * import { encrypt } from '@stravigor/core/encryption'
+ *
+ * // Encrypt & decrypt strings
+ * const encrypted = encrypt.encrypt('sensitive data')
+ * const decrypted = encrypt.decrypt(encrypted)
+ *
+ * // Seal & unseal objects (JSON + encryption)
+ * const token = encrypt.seal({ userId: 123 })
+ * const data = encrypt.unseal<{ userId: number }>(token)
+ *
+ * // Password hashing
+ * const hash = await encrypt.hash('password123')
+ * const valid = await encrypt.verify('password123', hash)
+ *
+ * // HMAC signing
+ * const sig = encrypt.sign('payload')
+ * const ok = encrypt.verifySignature('payload', sig)
+ */
+export const encrypt = {
+  /**
+   * Encrypt a string using AES-256-GCM. Returns a base64url-encoded payload.
+   *
+   * @example
+   * const encrypted = encrypt.encrypt('my secret')
+   * // Store `encrypted` in the database — it's a safe, opaque string
+   */
+  encrypt(plaintext: string): string {
+    return EncryptionManager.encrypt(plaintext)
+  },
+
+  /**
+   * Decrypt a payload encrypted with `encrypt()`.
+   * Supports key rotation — tries previous keys if the current key fails.
+   *
+   * @example
+   * const original = encrypt.decrypt(encrypted) // 'my secret'
+   */
+  decrypt(payload: string): string {
+    return EncryptionManager.decrypt(payload)
+  },
+
+  /**
+   * Encrypt and serialize an object. Perfect for tamper-proof cookies or tokens.
+   *
+   * @example
+   * const token = encrypt.seal({ userId: 123, role: 'admin' })
+   * // Send `token` to the client — it's encrypted and tamper-proof
+   */
+  seal(data: unknown): string {
+    return EncryptionManager.seal(data)
+  },
+
+  /**
+   * Decrypt and deserialize an object sealed with `seal()`.
+   *
+   * @example
+   * const data = encrypt.unseal<{ userId: number }>(token)
+   * console.log(data.userId) // 123
+   */
+  unseal<T = unknown>(payload: string): T {
+    return EncryptionManager.unseal<T>(payload)
+  },
+
+  /**
+   * Hash a password using argon2id. Returns an encoded hash string.
+   *
+   * @example
+   * const hash = await encrypt.hash(formData.password)
+   * await db.sql`UPDATE users SET password = ${hash} WHERE id = ${userId}`
+   */
+  hash(password: string): Promise<string> {
+    return EncryptionManager.hash(password)
+  },
+
+  /**
+   * Verify a password against a hash. Works with argon2id and bcrypt.
+   *
+   * @example
+   * const valid = await encrypt.verify(formData.password, user.password)
+   * if (!valid) throw new Error('Invalid credentials')
+   */
+  verify(password: string, hash: string): Promise<boolean> {
+    return EncryptionManager.verify(password, hash)
+  },
+
+  /**
+   * Create an HMAC-SHA256 signature. Returns a hex string.
+   *
+   * @example
+   * const sig = encrypt.sign(`${webhookId}:${timestamp}:${body}`)
+   * response.headers.set('X-Signature', sig)
+   */
+  sign(data: string): string {
+    return EncryptionManager.sign(data)
+  },
+
+  /**
+   * Verify an HMAC-SHA256 signature (timing-safe).
+   * Supports key rotation — tries previous keys if the current key fails.
+   *
+   * @example
+   * const valid = encrypt.verifySignature(body, req.headers.get('X-Signature')!)
+   * if (!valid) return new Response('Invalid signature', { status: 401 })
+   */
+  verifySignature(data: string, signature: string): boolean {
+    return EncryptionManager.verifySignature(data, signature)
+  },
+
+  /**
+   * SHA-256 hash. Returns a hex string.
+   *
+   * @example
+   * const checksum = encrypt.sha256(fileContents)
+   */
+  sha256(data: string): string {
+    return EncryptionManager.sha256(data)
+  },
+
+  /**
+   * SHA-512 hash. Returns a hex string.
+   *
+   * @example
+   * const hash = encrypt.sha512(data)
+   */
+  sha512(data: string): string {
+    return EncryptionManager.sha512(data)
+  },
+
+  /**
+   * Generate a random hex string. Default: 32 bytes → 64 hex chars.
+   *
+   * @example
+   * const apiKey = encrypt.random()       // 64-char hex (32 bytes)
+   * const shortToken = encrypt.random(16) // 32-char hex (16 bytes)
+   */
+  random(bytes: number = 32): string {
+    return EncryptionManager.random(bytes)
+  },
+
+  /**
+   * Generate raw random bytes.
+   *
+   * @example
+   * const iv = encrypt.randomBytes(12)
+   */
+  randomBytes(bytes: number = 32): Uint8Array {
+    return EncryptionManager.randomBytes(bytes)
+  },
+}

package/src/encryption/index.ts

@@ -0,0 +1,3 @@
+export { default, default as EncryptionManager } from './encryption_manager.ts'
+export { encrypt } from './helpers.ts'
+export type { EncryptionConfig } from './types.ts'

package/src/encryption/types.ts

@@ -0,0 +1,6 @@
+export interface EncryptionConfig {
+  /** The application key used for symmetric encryption and HMAC signing. Required. */
+  key: string
+  /** Previous keys for rotation — tried on decrypt/unseal failure before giving up. */
+  previousKeys: string[]
+}

package/src/events/emitter.ts

@@ -0,0 +1,101 @@
+/** A function that handles an event payload. */
+export type Listener<T = any> = (payload: T) => void | Promise<void>
+
+/**
+ * In-memory event bus — publish/subscribe with async support.
+ *
+ * All methods are static. No DI, no database, no configuration required.
+ * Listeners are awaited in parallel when an event is emitted.
+ * If any listener throws, the remaining listeners still execute
+ * and the first error is re-thrown after all complete.
+ *
+ * @example
+ * Emitter.on<{ user: User }>('user.registered', async ({ user }) => {
+ *   await sendWelcomeEmail(user)
+ * })
+ *
+ * await Emitter.emit('user.registered', { user })
+ */
+export default class Emitter {
+  private static _listeners = new Map<string, Set<Listener>>()
+  private static _once = new WeakSet<Listener>()
+
+  /** Register a listener for an event. */
+  static on<T = any>(event: string, listener: Listener<T>): void {
+    let set = Emitter._listeners.get(event)
+    if (!set) {
+      set = new Set()
+      Emitter._listeners.set(event, set)
+    }
+    set.add(listener)
+  }
+
+  /** Register a listener that is automatically removed after its first invocation. */
+  static once<T = any>(event: string, listener: Listener<T>): void {
+    Emitter._once.add(listener)
+    Emitter.on(event, listener)
+  }
+
+  /** Remove a specific listener for an event. */
+  static off<T = any>(event: string, listener: Listener<T>): void {
+    const set = Emitter._listeners.get(event)
+    if (!set) return
+    set.delete(listener)
+    if (set.size === 0) Emitter._listeners.delete(event)
+  }
+
+  /** Remove all listeners for a specific event, or all listeners entirely. */
+  static removeAllListeners(event?: string): void {
+    if (event) {
+      Emitter._listeners.delete(event)
+    } else {
+      Emitter._listeners.clear()
+    }
+  }
+
+  /**
+   * Emit an event. All registered listeners are invoked in parallel.
+   *
+   * If any listener throws, the other listeners still execute.
+   * After all listeners settle, the first error is re-thrown.
+   */
+  static async emit<T = any>(event: string, payload?: T): Promise<void> {
+    const set = Emitter._listeners.get(event)
+    if (!set || set.size === 0) return
+
+    const listeners = [...set]
+
+    // Remove one-time listeners before calling (avoids re-entrancy issues)
+    for (const fn of listeners) {
+      if (Emitter._once.has(fn)) {
+        Emitter._once.delete(fn)
+        set.delete(fn)
+      }
+    }
+    if (set.size === 0) Emitter._listeners.delete(event)
+
+    const results = await Promise.allSettled(
+      listeners.map(fn => {
+        try {
+          return fn(payload as T)
+        } catch (err) {
+          return Promise.reject(err)
+        }
+      })
+    )
+
+    const firstError = results.find((r): r is PromiseRejectedResult => r.status === 'rejected')
+    if (firstError) throw firstError.reason
+  }
+
+  /** Return the number of listeners registered for an event. */
+  static listenerCount(event: string): number {
+    return Emitter._listeners.get(event)?.size ?? 0
+  }
+
+  /** Clear all state. Intended for test teardown. */
+  static reset(): void {
+    Emitter._listeners.clear()
+    Emitter._once = new WeakSet()
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export { default as Emitter } from './emitter.ts'
+export type { Listener } from './emitter.ts'

package/src/exceptions/errors.ts

@@ -0,0 +1,75 @@
+import { StravError } from './strav_error.ts'
+
+/**
+ * Thrown when a framework service is used before being configured
+ * or when an unknown driver/store/transport is requested.
+ *
+ * @example
+ * throw new ConfigurationError('CacheManager not configured. Resolve it through the container first.')
+ */
+export class ConfigurationError extends StravError {}
+
+/**
+ * Thrown by `findOrFail` / `firstOrFail` when a model record is not found.
+ * The ExceptionHandler renders this as a 404.
+ *
+ * @example
+ * throw new ModelNotFoundError('User', id)
+ */
+export class ModelNotFoundError extends StravError {
+  constructor(
+    public readonly model: string,
+    public readonly id?: unknown
+  ) {
+    super(
+      id !== undefined
+        ? `${model} with ID ${id} not found`
+        : `${model} not found`
+    )
+  }
+}
+
+/**
+ * Thrown on database operation failures (migrations, queries).
+ *
+ * @example
+ * throw new DatabaseError(`Migration ${version} failed: ${cause}`)
+ */
+export class DatabaseError extends StravError {}
+
+/**
+ * Thrown on encryption/decryption/signing failures.
+ *
+ * @example
+ * throw new EncryptionError('Decryption failed: invalid payload or key.')
+ */
+export class EncryptionError extends StravError {}
+
+/**
+ * Thrown on view template compilation or rendering failures.
+ *
+ * @example
+ * throw new TemplateError(`Unclosed expression at line ${line}`)
+ */
+export class TemplateError extends StravError {}
+
+/**
+ * Thrown when an external service (AI provider, mail transport, webhook) returns an error.
+ * The ExceptionHandler renders this as a 502.
+ *
+ * @example
+ * throw new ExternalServiceError('Anthropic', 429, 'Rate limited')
+ */
+export class ExternalServiceError extends StravError {
+  constructor(
+    public readonly service: string,
+    public readonly statusCode?: number,
+    public readonly responseBody?: string
+  ) {
+    super(
+      statusCode
+        ? `${service} error (${statusCode}): ${responseBody ?? 'unknown'}`
+        : `${service} error: ${responseBody ?? 'unknown'}`
+    )
+  }
+}

package/src/exceptions/exception_handler.ts

@@ -0,0 +1,126 @@
+import type Context from '../http/context.ts'
+import { HttpException, ValidationError, RateLimitError } from './http_exception.ts'
+import { ModelNotFoundError, ConfigurationError, ExternalServiceError } from './errors.ts'
+
+/** Converts an error into an HTTP Response. */
+export type RenderFn = (error: any, ctx?: Context) => Response
+
+/** Reports an error (logging, external services, etc.). */
+export type ReportFn = (error: Error, ctx?: Context) => void
+
+/**
+ * Converts thrown errors into HTTP responses.
+ *
+ * Register with the router to catch all unhandled exceptions:
+ *
+ * @example
+ * import { ExceptionHandler } from '@stravigor/core/exceptions'
+ *
+ * const handler = new ExceptionHandler(config.get('app.env') === 'local')
+ * handler.report((error, ctx) => logger.error(error.message, { path: ctx?.path }))
+ * router.useExceptionHandler(handler)
+ */
+export class ExceptionHandler {
+  private renderers = new Map<Function, RenderFn>()
+  private reporters: ReportFn[] = []
+
+  constructor(private isDev = false) {}
+
+  /**
+   * Register a custom renderer for a specific error class.
+   * Custom renderers take precedence over built-in rendering.
+   *
+   * @example
+   * handler.render(PaymentError, (error) => {
+   *   return Response.json({ error: error.message, code: error.code }, { status: 402 })
+   * })
+   */
+  render<T extends Error>(
+    errorClass: new (...args: any[]) => T,
+    fn: (error: T, ctx?: Context) => Response
+  ): this {
+    this.renderers.set(errorClass, fn as RenderFn)
+    return this
+  }
+
+  /**
+   * Register a reporter. Runs for every error before rendering.
+   *
+   * @example
+   * handler.report((error, ctx) => {
+   *   logger.error(error.message, { path: ctx?.path, stack: error.stack })
+   * })
+   */
+  report(fn: ReportFn): this {
+    this.reporters.push(fn)
+    return this
+  }
+
+  /** Convert a thrown error into an HTTP Response. */
+  handle(error: unknown, ctx?: Context): Response {
+    const err = error instanceof Error ? error : new Error(String(error))
+
+    // Run reporters
+    for (const reporter of this.reporters) {
+      try {
+        reporter(err, ctx)
+      } catch {
+        // Reporters must not throw
+      }
+    }
+
+    // Check custom renderers (walk the prototype chain)
+    let proto = err.constructor
+    while (proto && proto !== Object) {
+      const renderer = this.renderers.get(proto)
+      if (renderer) return renderer(err, ctx)
+      proto = Object.getPrototypeOf(proto)
+    }
+
+    // Built-in rendering
+    if (err instanceof ValidationError) {
+      return json({ error: err.message, errors: err.errors }, err.status)
+    }
+
+    if (err instanceof RateLimitError) {
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+      if (err.retryAfter !== undefined) {
+        headers['Retry-After'] = String(err.retryAfter)
+      }
+      return new Response(JSON.stringify({ error: err.message }), {
+        status: err.status,
+        headers,
+      })
+    }
+
+    if (err instanceof HttpException) {
+      return json({ error: err.message }, err.status)
+    }
+
+    if (err instanceof ModelNotFoundError) {
+      return json({ error: err.message }, 404)
+    }
+
+    if (err instanceof ConfigurationError) {
+      // Always show config errors — they're developer mistakes
+      return json({ error: err.message }, 500)
+    }
+
+    if (err instanceof ExternalServiceError) {
+      return json({ error: 'Service unavailable' }, 502)
+    }
+
+    // Unknown error
+    if (this.isDev) {
+      return json({ error: err.message, stack: err.stack }, 500)
+    }
+    return json({ error: 'Internal Server Error' }, 500)
+  }
+}
+
+function json(data: unknown, status: number): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}

package/src/exceptions/helpers.ts

@@ -0,0 +1,25 @@
+import { HttpException, ValidationError } from './http_exception.ts'
+
+/**
+ * Throw an HTTP exception. Caught by the ExceptionHandler and rendered
+ * as a JSON error response.
+ *
+ * @example
+ * import { abort } from '@stravigor/core/exceptions'
+ *
+ * const project = await Project.find(id)
+ * if (!project) abort(404, 'Project not found')
+ *
+ * abort(403, 'You cannot access this resource')
+ *
+ * // Validation errors with structured field data
+ * abort(422, { email: ['Required'], name: ['Too short'] })
+ */
+export function abort(status: 422, errors: Record<string, string[]>): never
+export function abort(status: number, message?: string): never
+export function abort(status: number, messageOrErrors?: string | Record<string, string[]>): never {
+  if (status === 422 && typeof messageOrErrors === 'object') {
+    throw new ValidationError(messageOrErrors)
+  }
+  throw new HttpException(status, typeof messageOrErrors === 'string' ? messageOrErrors : undefined)
+}

package/src/exceptions/http_exception.ts

@@ -0,0 +1,129 @@
+import { StravError } from './strav_error.ts'
+
+const STATUS_MESSAGES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthenticated',
+  403: 'Forbidden',
+  404: 'Not Found',
+  409: 'Conflict',
+  422: 'Validation Failed',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+}
+
+/**
+ * HTTP-aware exception. Throw from handlers or middleware to produce
+ * an error response with the given status code.
+ *
+ * @example
+ * throw new HttpException(403, 'You cannot access this resource')
+ */
+export class HttpException extends StravError {
+  constructor(
+    public readonly status: number,
+    message?: string,
+    public readonly body?: unknown
+  ) {
+    super(message ?? STATUS_MESSAGES[status] ?? `HTTP Error ${status}`)
+  }
+}
+
+/**
+ * 400 Bad Request.
+ *
+ * @example
+ * throw new BadRequestError('Malformed JSON in request body')
+ */
+export class BadRequestError extends HttpException {
+  constructor(message?: string) {
+    super(400, message)
+  }
+}
+
+/**
+ * 401 Unauthenticated.
+ *
+ * @example
+ * throw new AuthenticationError()
+ * throw new AuthenticationError('Token expired')
+ */
+export class AuthenticationError extends HttpException {
+  constructor(message?: string) {
+    super(401, message)
+  }
+}
+
+/**
+ * 403 Forbidden.
+ *
+ * @example
+ * throw new AuthorizationError('You do not own this resource')
+ */
+export class AuthorizationError extends HttpException {
+  constructor(message?: string) {
+    super(403, message)
+  }
+}
+
+/**
+ * 404 Not Found.
+ *
+ * @example
+ * throw new NotFoundError('Project not found')
+ */
+export class NotFoundError extends HttpException {
+  constructor(message?: string) {
+    super(404, message)
+  }
+}
+
+/**
+ * 409 Conflict.
+ *
+ * @example
+ * throw new ConflictError('A project with this slug already exists')
+ */
+export class ConflictError extends HttpException {
+  constructor(message?: string) {
+    super(409, message)
+  }
+}
+
+/**
+ * 422 Validation Failed — carries structured field errors.
+ *
+ * @example
+ * throw new ValidationError({ email: ['Required'], name: ['Too short'] })
+ */
+export class ValidationError extends HttpException {
+  constructor(
+    public readonly errors: Record<string, string[]>,
+    message?: string
+  ) {
+    super(422, message ?? 'Validation Failed', errors)
+  }
+}
+
+/**
+ * 429 Too Many Requests — optionally carries a retry-after value.
+ *
+ * @example
+ * throw new RateLimitError(60)  // retry after 60 seconds
+ */
+export class RateLimitError extends HttpException {
+  constructor(public readonly retryAfter?: number, message?: string) {
+    super(429, message)
+  }
+}
+
+/**
+ * 500 Internal Server Error.
+ *
+ * @example
+ * throw new ServerError('Unexpected state in payment processor')
+ */
+export class ServerError extends HttpException {
+  constructor(message?: string) {
+    super(500, message)
+  }
+}

package/src/exceptions/index.ts

@@ -0,0 +1,23 @@
+export { StravError } from './strav_error.ts'
+export {
+  HttpException,
+  BadRequestError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+} from './http_exception.ts'
+export {
+  ConfigurationError,
+  ModelNotFoundError,
+  DatabaseError,
+  EncryptionError,
+  TemplateError,
+  ExternalServiceError,
+} from './errors.ts'
+export { ExceptionHandler } from './exception_handler.ts'
+export { abort } from './helpers.ts'
+export type { RenderFn, ReportFn } from './exception_handler.ts'

package/src/exceptions/strav_error.ts

@@ -0,0 +1,11 @@
+/**
+ * Base error class for all Strav framework errors.
+ *
+ * Enables `instanceof StravError` to catch any framework error.
+ */
+export class StravError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}