@stravigor/core 0.1.0

package/src/database/query_builder.ts

@@ -0,0 +1,474 @@
+import { DateTime } from 'luxon'
+import { toSnakeCase } from '../helpers/strings.ts'
+import type BaseModel from '../orm/base_model.ts'
+import { ModelNotFoundError } from '../exceptions/errors.ts'
+
+type ModelStatic<T extends BaseModel> = (new (...args: any[]) => T) & typeof BaseModel
+
+// ---------------------------------------------------------------------------
+// Pagination
+// ---------------------------------------------------------------------------
+
+export interface PaginationMeta {
+  page: number
+  perPage: number
+  total: number
+  lastPage: number
+  from: number
+  to: number
+}
+
+export interface PaginationResult<T> {
+  data: T[]
+  meta: PaginationMeta
+}
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+type WhereClause =
+  | { kind: 'comparison'; column: string; operator: string; value: unknown }
+  | { kind: 'in' | 'not_in'; column: string; values: unknown[] }
+  | { kind: 'null' | 'not_null'; column: string }
+  | { kind: 'between'; column: string; low: unknown; high: unknown }
+  | { kind: 'raw'; sql: string; params: unknown[] }
+
+interface JoinClause {
+  type: 'LEFT JOIN' | 'INNER JOIN' | 'RIGHT JOIN'
+  table: string
+  alias: string
+  leftCol: string
+  operator: string
+  rightCol: string
+}
+
+interface OrderByClause {
+  column: string
+  direction: 'ASC' | 'DESC'
+}
+
+// ---------------------------------------------------------------------------
+// JoinBuilder
+// ---------------------------------------------------------------------------
+
+class JoinBuilder<T extends BaseModel> {
+  constructor(
+    private parent: QueryBuilder<T>,
+    private model: typeof BaseModel,
+    private joinType: 'LEFT JOIN' | 'INNER JOIN' | 'RIGHT JOIN'
+  ) {}
+
+  on(leftColumn: string, operator: string, rightColumn: string): QueryBuilder<T> {
+    return this.parent._addJoin({
+      type: this.joinType,
+      table: this.model.tableName,
+      alias: this.model.name,
+      leftCol: leftColumn,
+      operator,
+      rightCol: rightColumn,
+    })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// QueryBuilder
+// ---------------------------------------------------------------------------
+
+export default class QueryBuilder<T extends BaseModel> {
+  private modelClass: ModelStatic<T>
+  private primaryTable: string
+  private models: Map<string, typeof BaseModel> = new Map()
+
+  private wheres: WhereClause[] = []
+  private joins: JoinClause[] = []
+  private orderBys: OrderByClause[] = []
+  private groupBys: string[] = []
+  private selectColumns: string[] = []
+  private limitValue: number | null = null
+  private offsetValue: number | null = null
+  private isDistinct: boolean = false
+  private includeTrashed: boolean = false
+  private isOnlyTrashed: boolean = false
+
+  constructor(modelClass: ModelStatic<T>) {
+    this.modelClass = modelClass
+    this.primaryTable = modelClass.tableName
+    this.models.set(modelClass.name, modelClass)
+  }
+
+  // ---------------------------------------------------------------------------
+  // WHERE
+  // ---------------------------------------------------------------------------
+
+  where(column: string, operatorOrValue: unknown, value?: unknown): this {
+    if (value === undefined) {
+      this.wheres.push({ kind: 'comparison', column, operator: '=', value: operatorOrValue })
+    } else {
+      this.wheres.push({ kind: 'comparison', column, operator: operatorOrValue as string, value })
+    }
+    return this
+  }
+
+  whereIn(column: string, values: unknown[]): this {
+    this.wheres.push({ kind: 'in', column, values })
+    return this
+  }
+
+  whereNotIn(column: string, values: unknown[]): this {
+    this.wheres.push({ kind: 'not_in', column, values })
+    return this
+  }
+
+  whereNull(column: string): this {
+    this.wheres.push({ kind: 'null', column })
+    return this
+  }
+
+  whereNotNull(column: string): this {
+    this.wheres.push({ kind: 'not_null', column })
+    return this
+  }
+
+  whereBetween(column: string, low: unknown, high: unknown): this {
+    this.wheres.push({ kind: 'between', column, low, high })
+    return this
+  }
+
+  whereRaw(sql: string, params: unknown[] = []): this {
+    this.wheres.push({ kind: 'raw', sql, params })
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // JOIN
+  // ---------------------------------------------------------------------------
+
+  leftJoin(model: typeof BaseModel): JoinBuilder<T> {
+    this.models.set(model.name, model)
+    return new JoinBuilder(this, model, 'LEFT JOIN')
+  }
+
+  innerJoin(model: typeof BaseModel): JoinBuilder<T> {
+    this.models.set(model.name, model)
+    return new JoinBuilder(this, model, 'INNER JOIN')
+  }
+
+  rightJoin(model: typeof BaseModel): JoinBuilder<T> {
+    this.models.set(model.name, model)
+    return new JoinBuilder(this, model, 'RIGHT JOIN')
+  }
+
+  /** @internal Called by JoinBuilder to register a completed join. */
+  _addJoin(join: JoinClause): this {
+    this.joins.push(join)
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // SELECT, ORDER, GROUP, LIMIT, OFFSET
+  // ---------------------------------------------------------------------------
+
+  select(...columns: string[]): this {
+    this.selectColumns.push(...columns)
+    return this
+  }
+
+  orderBy(column: string, direction: 'asc' | 'desc' | 'ASC' | 'DESC' = 'ASC'): this {
+    this.orderBys.push({ column, direction: direction.toUpperCase() as 'ASC' | 'DESC' })
+    return this
+  }
+
+  groupBy(...columns: string[]): this {
+    this.groupBys.push(...columns)
+    return this
+  }
+
+  limit(n: number): this {
+    this.limitValue = n
+    return this
+  }
+
+  offset(n: number): this {
+    this.offsetValue = n
+    return this
+  }
+
+  distinct(): this {
+    this.isDistinct = true
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // Soft deletes
+  // ---------------------------------------------------------------------------
+
+  withTrashed(): this {
+    this.includeTrashed = true
+    return this
+  }
+
+  onlyTrashed(): this {
+    this.isOnlyTrashed = true
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // Terminal methods
+  // ---------------------------------------------------------------------------
+
+  async all(): Promise<T[]> {
+    const { sql, params } = this.build('select')
+    const db = this.modelClass.db
+    const rows = await db.sql.unsafe(sql, params)
+    const Model = this.modelClass as any
+    return rows.map((row: Record<string, unknown>) => Model.hydrate(row) as T)
+  }
+
+  async first(): Promise<T | null> {
+    const savedLimit = this.limitValue
+    this.limitValue = 1
+    const results = await this.all()
+    this.limitValue = savedLimit
+    return results[0] ?? null
+  }
+
+  async firstOrFail(): Promise<T> {
+    const result = await this.first()
+    if (!result) {
+      throw new ModelNotFoundError(this.modelClass.name)
+    }
+    return result
+  }
+
+  async count(): Promise<number> {
+    const { sql, params } = this.build('count')
+    const db = this.modelClass.db
+    const rows = await db.sql.unsafe(sql, params)
+    return Number(rows[0]?.count ?? 0)
+  }
+
+  async exists(): Promise<boolean> {
+    return (await this.count()) > 0
+  }
+
+  async paginate(page: number = 1, perPage: number = 15): Promise<PaginationResult<T>> {
+    const currentPage = Math.max(1, Math.floor(page))
+
+    const total = await this.count()
+    const lastPage = Math.max(1, Math.ceil(total / perPage))
+
+    const savedLimit = this.limitValue
+    const savedOffset = this.offsetValue
+    this.limitValue = perPage
+    this.offsetValue = (currentPage - 1) * perPage
+    const data = await this.all()
+    this.limitValue = savedLimit
+    this.offsetValue = savedOffset
+
+    const from = total > 0 ? (currentPage - 1) * perPage + 1 : 0
+    const to = Math.min(currentPage * perPage, total)
+
+    return {
+      data,
+      meta: { page: currentPage, perPage, total, lastPage, from, to },
+    }
+  }
+
+  /** Return the generated SQL and params without executing. */
+  toSQL(): { sql: string; params: unknown[] } {
+    return this.build('select')
+  }
+
+  // ---------------------------------------------------------------------------
+  // SQL building
+  // ---------------------------------------------------------------------------
+
+  private build(mode: 'select' | 'count'): { sql: string; params: unknown[] } {
+    const parts: string[] = []
+    const params: unknown[] = []
+    let paramIdx = 1
+
+    // SELECT
+    if (mode === 'count') {
+      parts.push('SELECT COUNT(*) AS "count"')
+    } else if (this.selectColumns.length > 0) {
+      const cols = this.selectColumns.map(c => this.resolveSelectColumn(c))
+      parts.push(`SELECT ${this.isDistinct ? 'DISTINCT ' : ''}${cols.join(', ')}`)
+    } else {
+      parts.push(`SELECT ${this.isDistinct ? 'DISTINCT ' : ''}"${this.primaryTable}".*`)
+    }
+
+    // FROM
+    parts.push(`FROM "${this.primaryTable}"`)
+
+    // JOINs
+    for (const join of this.joins) {
+      const left = this.resolveColumn(join.leftCol)
+      const right = this.resolveColumn(join.rightCol)
+      parts.push(`${join.type} "${join.table}" ON ${left} ${join.operator} ${right}`)
+    }
+
+    // WHERE
+    const whereParts: string[] = []
+
+    // Soft delete handling
+    if (this.modelClass.softDeletes && !this.includeTrashed) {
+      if (this.isOnlyTrashed) {
+        whereParts.push(`"${this.primaryTable}"."deleted_at" IS NOT NULL`)
+      } else {
+        whereParts.push(`"${this.primaryTable}"."deleted_at" IS NULL`)
+      }
+    }
+
+    for (const w of this.wheres) {
+      switch (w.kind) {
+        case 'comparison': {
+          const col = this.resolveColumn(w.column)
+          params.push(this.dehydrateValue(w.value))
+          whereParts.push(`${col} ${w.operator} $${paramIdx++}`)
+          break
+        }
+        case 'in': {
+          const col = this.resolveColumn(w.column)
+          const placeholders = w.values.map(v => {
+            params.push(this.dehydrateValue(v))
+            return `$${paramIdx++}`
+          })
+          whereParts.push(`${col} IN (${placeholders.join(', ')})`)
+          break
+        }
+        case 'not_in': {
+          const col = this.resolveColumn(w.column)
+          const placeholders = w.values.map(v => {
+            params.push(this.dehydrateValue(v))
+            return `$${paramIdx++}`
+          })
+          whereParts.push(`${col} NOT IN (${placeholders.join(', ')})`)
+          break
+        }
+        case 'null': {
+          const col = this.resolveColumn(w.column)
+          whereParts.push(`${col} IS NULL`)
+          break
+        }
+        case 'not_null': {
+          const col = this.resolveColumn(w.column)
+          whereParts.push(`${col} IS NOT NULL`)
+          break
+        }
+        case 'between': {
+          const col = this.resolveColumn(w.column)
+          params.push(this.dehydrateValue(w.low))
+          params.push(this.dehydrateValue(w.high))
+          whereParts.push(`${col} BETWEEN $${paramIdx++} AND $${paramIdx++}`)
+          break
+        }
+        case 'raw': {
+          let rawSql = w.sql
+          for (const p of w.params) {
+            rawSql = rawSql.replace(`$${w.params.indexOf(p) + 1}`, `$${paramIdx++}`)
+            params.push(this.dehydrateValue(p))
+          }
+          whereParts.push(rawSql)
+          break
+        }
+      }
+    }
+
+    if (whereParts.length > 0) {
+      parts.push(`WHERE ${whereParts.join(' AND ')}`)
+    }
+
+    // GROUP BY
+    if (this.groupBys.length > 0) {
+      const cols = this.groupBys.map(c => this.resolveColumn(c))
+      parts.push(`GROUP BY ${cols.join(', ')}`)
+    }
+
+    // count mode skips ORDER BY, LIMIT, OFFSET
+    if (mode === 'select') {
+      // ORDER BY
+      if (this.orderBys.length > 0) {
+        const clauses = this.orderBys.map(o => `${this.resolveColumn(o.column)} ${o.direction}`)
+        parts.push(`ORDER BY ${clauses.join(', ')}`)
+      }
+
+      // LIMIT
+      if (this.limitValue !== null) {
+        parts.push(`LIMIT ${this.limitValue}`)
+      }
+
+      // OFFSET
+      if (this.offsetValue !== null) {
+        parts.push(`OFFSET ${this.offsetValue}`)
+      }
+    }
+
+    return { sql: parts.join(' '), params }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Column resolution
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Resolve a user column reference to a fully qualified SQL identifier.
+   *
+   * - `'email'`            → `"user"."email"`
+   * - `'User.email'`       → `"user"."email"`
+   * - `'Project.userId'`   → `"project"."user_id"`
+   */
+  private resolveColumn(ref: string): string {
+    const dot = ref.indexOf('.')
+    if (dot === -1) {
+      return `"${this.primaryTable}"."${toSnakeCase(ref)}"`
+    }
+
+    const modelName = ref.substring(0, dot)
+    const propName = ref.substring(dot + 1)
+    const tableName = this.resolveModelTable(modelName)
+    return `"${tableName}"."${toSnakeCase(propName)}"`
+  }
+
+  /**
+   * Resolve a select column. Passes through raw expressions containing
+   * special characters (parentheses, asterisk, AS keyword).
+   */
+  private resolveSelectColumn(col: string): string {
+    if (/[(*)]/.test(col) || /\bAS\b/i.test(col)) {
+      return col
+    }
+    return this.resolveColumn(col)
+  }
+
+  /** Resolve a PascalCase model name to its table name. */
+  private resolveModelTable(modelName: string): string {
+    const model = this.models.get(modelName)
+    if (model) return model.tableName
+    return toSnakeCase(modelName)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Value helpers
+  // ---------------------------------------------------------------------------
+
+  private dehydrateValue(value: unknown): unknown {
+    if (value instanceof DateTime) return value.toJSDate()
+    return value
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new QueryBuilder for the given model class.
+ *
+ * @example
+ * const users = await query(User).where('email', 'test@example.com').all()
+ */
+export function query<T extends BaseModel>(model: ModelStatic<T>): QueryBuilder<T> {
+  return new QueryBuilder<T>(model)
+}

package/src/encryption/encryption_manager.ts

@@ -0,0 +1,209 @@
+import { hkdfSync, createCipheriv, createDecipheriv, createHmac, timingSafeEqual } from 'node:crypto'
+import { inject } from '../core/inject.ts'
+import Configuration from '../config/configuration.ts'
+import type { EncryptionConfig } from './types.ts'
+import { ConfigurationError, EncryptionError } from '../exceptions/errors.ts'
+
+const IV_LENGTH = 12
+const TAG_LENGTH = 16
+const KEY_LENGTH = 32
+const ALGORITHM = 'aes-256-gcm'
+const HKDF_SALT = 'strav-encryption-salt'
+
+function deriveKey(raw: string, info: string): Buffer {
+  return Buffer.from(hkdfSync('sha256', raw, HKDF_SALT, info, KEY_LENGTH))
+}
+
+function encryptWithKey(plaintext: string, key: Buffer): string {
+  const iv = Buffer.from(crypto.getRandomValues(new Uint8Array(IV_LENGTH)))
+  const cipher = createCipheriv(ALGORITHM, key, iv)
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  // iv (12) + ciphertext (variable) + tag (16)
+  const payload = Buffer.concat([iv, encrypted, tag])
+  return payload.toString('base64url')
+}
+
+function decryptWithKey(payload: string, key: Buffer): string {
+  const buf = Buffer.from(payload, 'base64url')
+  if (buf.length < IV_LENGTH + TAG_LENGTH) {
+    throw new EncryptionError('Invalid encrypted payload: too short.')
+  }
+  const iv = buf.subarray(0, IV_LENGTH)
+  const tag = buf.subarray(buf.length - TAG_LENGTH)
+  const ciphertext = buf.subarray(IV_LENGTH, buf.length - TAG_LENGTH)
+  const decipher = createDecipheriv(ALGORITHM, key, iv)
+  decipher.setAuthTag(tag)
+  return decipher.update(ciphertext) + decipher.final('utf8')
+}
+
+/**
+ * Central encryption configuration hub.
+ *
+ * Resolved once via the DI container — reads the encryption config
+ * and derives cryptographic keys from the application key.
+ *
+ * @example
+ * app.singleton(EncryptionManager)
+ * app.resolve(EncryptionManager)
+ *
+ * // Swap keys at runtime (e.g., for testing)
+ * EncryptionManager.useKey('test-key-here')
+ */
+@inject
+export default class EncryptionManager {
+  private static _config: EncryptionConfig
+  private static _encryptionKey: Buffer
+  private static _hmacKey: Buffer
+  private static _previousEncryptionKeys: Buffer[]
+  private static _previousHmacKeys: Buffer[]
+
+  constructor(config: Configuration) {
+    EncryptionManager._config = {
+      key: '',
+      previousKeys: [],
+      ...(config.get('encryption', {}) as object),
+    }
+
+    const raw = EncryptionManager._config.key
+    if (!raw) {
+      throw new ConfigurationError(
+        'Encryption key is not set. Set APP_KEY in your .env file or configure encryption.key.'
+      )
+    }
+
+    EncryptionManager._encryptionKey = deriveKey(raw, 'aes-256-gcm')
+    EncryptionManager._hmacKey = deriveKey(raw, 'hmac-sha256')
+
+    EncryptionManager._previousEncryptionKeys = EncryptionManager._config.previousKeys.map(k =>
+      deriveKey(k, 'aes-256-gcm')
+    )
+    EncryptionManager._previousHmacKeys = EncryptionManager._config.previousKeys.map(k =>
+      deriveKey(k, 'hmac-sha256')
+    )
+  }
+
+  static get config(): EncryptionConfig {
+    return EncryptionManager._config
+  }
+
+  /** Swap the application key at runtime (e.g., for testing). */
+  static useKey(key: string): void {
+    EncryptionManager._encryptionKey = deriveKey(key, 'aes-256-gcm')
+    EncryptionManager._hmacKey = deriveKey(key, 'hmac-sha256')
+  }
+
+  // ---------------------------------------------------------------------------
+  // Symmetric Encryption (AES-256-GCM)
+  // ---------------------------------------------------------------------------
+
+  /** Encrypt a plaintext string. Returns a base64url-encoded payload. */
+  static encrypt(plaintext: string): string {
+    return encryptWithKey(plaintext, EncryptionManager._encryptionKey)
+  }
+
+  /**
+   * Decrypt a payload. Tries the current key first, then previous keys for rotation.
+   * Throws if none of the keys can decrypt the payload.
+   */
+  static decrypt(payload: string): string {
+    try {
+      return decryptWithKey(payload, EncryptionManager._encryptionKey)
+    } catch {
+      // Try previous keys for rotation
+      for (const key of EncryptionManager._previousEncryptionKeys) {
+        try {
+          return decryptWithKey(payload, key)
+        } catch {
+          continue
+        }
+      }
+      throw new EncryptionError('Decryption failed: invalid payload or key.')
+    }
+  }
+
+  /** Encrypt and JSON-serialize an object. */
+  static seal(data: unknown): string {
+    return EncryptionManager.encrypt(JSON.stringify(data))
+  }
+
+  /** Decrypt and JSON-deserialize an object. */
+  static unseal<T = unknown>(payload: string): T {
+    return JSON.parse(EncryptionManager.decrypt(payload)) as T
+  }
+
+  // ---------------------------------------------------------------------------
+  // HMAC Signing
+  // ---------------------------------------------------------------------------
+
+  /** Create an HMAC-SHA256 signature. Returns a hex string. */
+  static sign(data: string): string {
+    return createHmac('sha256', EncryptionManager._hmacKey).update(data).digest('hex')
+  }
+
+  /**
+   * Verify an HMAC-SHA256 signature using timing-safe comparison.
+   * Tries the current key first, then previous keys for rotation.
+   */
+  static verifySignature(data: string, signature: string): boolean {
+    const expected = Buffer.from(EncryptionManager.sign(data), 'hex')
+    const actual = Buffer.from(signature, 'hex')
+    if (expected.length !== actual.length) {
+      // Try previous keys
+      for (const key of EncryptionManager._previousHmacKeys) {
+        const prev = Buffer.from(createHmac('sha256', key).update(data).digest('hex'), 'hex')
+        if (prev.length === actual.length && timingSafeEqual(prev, actual)) return true
+      }
+      return false
+    }
+    if (timingSafeEqual(expected, actual)) return true
+    // Try previous keys
+    for (const key of EncryptionManager._previousHmacKeys) {
+      const prev = Buffer.from(createHmac('sha256', key).update(data).digest('hex'), 'hex')
+      if (prev.length === actual.length && timingSafeEqual(prev, actual)) return true
+    }
+    return false
+  }
+
+  // ---------------------------------------------------------------------------
+  // Password Hashing (Bun.password — argon2id)
+  // ---------------------------------------------------------------------------
+
+  /** Hash a password using argon2id. Returns an encoded hash string. */
+  static hash(password: string): Promise<string> {
+    return Bun.password.hash(password, 'argon2id')
+  }
+
+  /** Verify a password against a hash. Works with argon2id and bcrypt hashes. */
+  static verify(password: string, hash: string): Promise<boolean> {
+    return Bun.password.verify(password, hash)
+  }
+
+  // ---------------------------------------------------------------------------
+  // One-way Hashing
+  // ---------------------------------------------------------------------------
+
+  /** SHA-256 hash. Returns a hex string. */
+  static sha256(data: string): string {
+    return new Bun.CryptoHasher('sha256').update(data).digest('hex')
+  }
+
+  /** SHA-512 hash. Returns a hex string. */
+  static sha512(data: string): string {
+    return new Bun.CryptoHasher('sha512').update(data).digest('hex')
+  }
+
+  // ---------------------------------------------------------------------------
+  // Random Generation
+  // ---------------------------------------------------------------------------
+
+  /** Generate a random hex string (2 hex chars per byte). */
+  static random(bytes: number = 32): string {
+    return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString('hex')
+  }
+
+  /** Generate raw random bytes. */
+  static randomBytes(bytes: number = 32): Uint8Array {
+    return crypto.getRandomValues(new Uint8Array(bytes))
+  }
+}