@stravigor/core 0.1.0

package/src/session/session.ts

@@ -0,0 +1,308 @@
+import type Context from '../http/context.ts'
+import { clearCookie } from '../http/cookie.ts'
+import { randomHex } from '../helpers/crypto.ts'
+import { extractUserId } from '../helpers/identity.ts'
+import SessionManager from './session_manager.ts'
+
+const FLASH_KEY = '_flash'
+const FLASH_OLD_KEY = '_flash_old'
+
+/**
+ * Unified server-side session backed by a database row and an HTTP-only cookie.
+ *
+ * Serves both anonymous visitors and authenticated users. Stores arbitrary
+ * key-value data in a JSONB column and supports flash data (available only
+ * on the next request).
+ *
+ * @example
+ * // Read / write data (anonymous or authenticated)
+ * const session = ctx.get<Session>('session')
+ * session.set('cart', [item])
+ * session.flash('success', 'Item added!')
+ *
+ * // Login
+ * session.authenticate(user)
+ * await session.regenerate()
+ *
+ * // Logout
+ * return Session.destroy(ctx, ctx.redirect('/login'))
+ */
+export default class Session {
+  private _id: string
+  private _userId: string | null
+  private _csrfToken: string
+  private _data: Record<string, unknown>
+  private _dirty = false
+
+  constructor(
+    id: string,
+    userId: string | null,
+    csrfToken: string,
+    data: Record<string, unknown>,
+    readonly ipAddress: string | null,
+    readonly userAgent: string | null,
+    readonly lastActivity: Date,
+    readonly createdAt: Date
+  ) {
+    this._id = id
+    this._userId = userId
+    this._csrfToken = csrfToken
+    this._data = data
+  }
+
+  // ---------------------------------------------------------------------------
+  // Getters
+  // ---------------------------------------------------------------------------
+
+  get id(): string {
+    return this._id
+  }
+
+  get userId(): string | null {
+    return this._userId
+  }
+
+  get csrfToken(): string {
+    return this._csrfToken
+  }
+
+  get isAuthenticated(): boolean {
+    return this._userId !== null
+  }
+
+  get isDirty(): boolean {
+    return this._dirty
+  }
+
+  // ---------------------------------------------------------------------------
+  // Data bag
+  // ---------------------------------------------------------------------------
+
+  /** Get a value from the session data. */
+  get<T = unknown>(key: string, defaultValue?: T): T {
+    return (this._data[key] as T) ?? (defaultValue as T)
+  }
+
+  /** Set a persistent session value. */
+  set(key: string, value: unknown): void {
+    this._data[key] = value
+    this._dirty = true
+  }
+
+  /** Check whether a key exists in the session data. */
+  has(key: string): boolean {
+    return key in this._data && !key.startsWith('_flash')
+  }
+
+  /** Remove a key from the session data. */
+  forget(key: string): void {
+    delete this._data[key]
+    this._dirty = true
+  }
+
+  /** Remove all session data (keeps the session row alive). */
+  flush(): void {
+    this._data = {}
+    this._dirty = true
+  }
+
+  /** Return all user-facing session data (excludes flash internals). */
+  all(): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(this._data)) {
+      if (!key.startsWith('_flash')) {
+        result[key] = value
+      }
+    }
+    return result
+  }
+
+  // ---------------------------------------------------------------------------
+  // Flash data
+  // ---------------------------------------------------------------------------
+
+  /** Set flash data that will be available only on the next request. */
+  flash(key: string, value: unknown): void {
+    const bag = (this._data[FLASH_KEY] ?? {}) as Record<string, unknown>
+    bag[key] = value
+    this._data[FLASH_KEY] = bag
+    this._dirty = true
+  }
+
+  /** Get flash data set by the previous request. */
+  getFlash<T = unknown>(key: string): T | undefined {
+    const old = this._data[FLASH_OLD_KEY] as Record<string, unknown> | undefined
+    return old?.[key] as T | undefined
+  }
+
+  /** Check if there is flash data for the given key (from previous request). */
+  hasFlash(key: string): boolean {
+    const old = this._data[FLASH_OLD_KEY] as Record<string, unknown> | undefined
+    return old !== undefined && key in old
+  }
+
+  /**
+   * Rotate flash data for the next request cycle. Called once per request
+   * by the session middleware before the handler runs.
+   *
+   * Moves `_flash` → `_flash_old` (readable this request), then clears `_flash`.
+   * Only marks dirty if there was actually flash data to rotate.
+   */
+  ageFlash(): void {
+    const current = this._data[FLASH_KEY]
+    const old = this._data[FLASH_OLD_KEY]
+
+    if (current !== undefined || old !== undefined) {
+      this._data[FLASH_OLD_KEY] = current ?? {}
+      delete this._data[FLASH_KEY]
+      this._dirty = true
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Authentication
+  // ---------------------------------------------------------------------------
+
+  /** Associate this session with a user (login). */
+  authenticate(user: unknown): void {
+    this._userId = extractUserId(user)
+    this._dirty = true
+  }
+
+  /** Disassociate the user from this session. */
+  clearUser(): void {
+    this._userId = null
+    this._dirty = true
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /** Whether this session has exceeded its configured lifetime. */
+  isExpired(): boolean {
+    const lifetimeMs = SessionManager.config.lifetime * 60_000
+    return Date.now() - this.lastActivity.getTime() > lifetimeMs
+  }
+
+  /** Update the last_activity timestamp to keep the session alive. */
+  async touch(): Promise<void> {
+    await SessionManager.db.sql`
+      UPDATE "_strav_sessions"
+      SET "last_activity" = NOW()
+      WHERE "id" = ${this._id}
+    `
+  }
+
+  /**
+   * Regenerate the session ID and CSRF token. Use after login to
+   * prevent session fixation attacks.
+   */
+  async regenerate(): Promise<void> {
+    const oldId = this._id
+    this._id = crypto.randomUUID()
+    this._csrfToken = randomHex(32)
+    this._dirty = true
+
+    await this.save()
+    await SessionManager.db.sql`
+      DELETE FROM "_strav_sessions" WHERE "id" = ${oldId}
+    `
+  }
+
+  /**
+   * Persist session data to the database. Uses an upsert so both new
+   * and existing sessions go through the same code path.
+   * No-op if the session has not been modified.
+   */
+  async save(): Promise<void> {
+    if (!this._dirty) return
+
+    const dataToSave = { ...this._data }
+    delete dataToSave[FLASH_OLD_KEY]
+
+    await SessionManager.db.sql`
+      INSERT INTO "_strav_sessions"
+        ("id", "user_id", "csrf_token", "data", "ip_address", "user_agent", "last_activity")
+      VALUES
+        (${this._id}, ${this._userId}, ${this._csrfToken},
+         ${JSON.stringify(dataToSave)}::jsonb, ${this.ipAddress}, ${this.userAgent}, NOW())
+      ON CONFLICT ("id") DO UPDATE SET
+        "user_id"       = EXCLUDED."user_id",
+        "csrf_token"    = EXCLUDED."csrf_token",
+        "data"          = EXCLUDED."data",
+        "last_activity" = NOW()
+    `
+    this._dirty = false
+  }
+
+  // ---------------------------------------------------------------------------
+  // Static API
+  // ---------------------------------------------------------------------------
+
+  /** Create a new anonymous session (not yet persisted — call save() or let the middleware handle it). */
+  static create(ctx: Context): Session {
+    const id = crypto.randomUUID()
+    const csrfToken = randomHex(32)
+    const ipAddress = ctx.header('x-forwarded-for') ?? null
+    const userAgent = ctx.header('user-agent') ?? null
+    const now = new Date()
+
+    const session = new Session(id, null, csrfToken, {}, ipAddress, userAgent, now, now)
+    session._dirty = true
+    return session
+  }
+
+  /** Look up a session by ID. Returns null if not found. */
+  static async find(id: string): Promise<Session | null> {
+    const rows = await SessionManager.db.sql`
+      SELECT * FROM "_strav_sessions" WHERE "id" = ${id} LIMIT 1
+    `
+    if (rows.length === 0) return null
+    return Session.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Read the session cookie from the request and look up the session. */
+  static async fromRequest(ctx: Context): Promise<Session | null> {
+    const sessionId = ctx.cookie(SessionManager.config.cookie)
+    if (!sessionId) return null
+    return Session.find(sessionId)
+  }
+
+  /** Delete the session from the database and clear the cookie on the response. */
+  static async destroy(ctx: Context, response: Response): Promise<Response> {
+    const cfg = SessionManager.config
+    const sessionId = ctx.cookie(cfg.cookie)
+
+    if (sessionId) {
+      await SessionManager.db.sql`
+        DELETE FROM "_strav_sessions" WHERE "id" = ${sessionId}
+      `
+    }
+
+    return clearCookie(response, cfg.cookie, { path: '/' })
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): Session {
+    const rawData = row.data
+    const data: Record<string, unknown> =
+      typeof rawData === 'string'
+        ? JSON.parse(rawData)
+        : ((rawData as Record<string, unknown>) ?? {})
+
+    return new Session(
+      row.id as string,
+      (row.user_id as string) ?? null,
+      row.csrf_token as string,
+      data,
+      (row.ip_address as string) ?? null,
+      (row.user_agent as string) ?? null,
+      row.last_activity as Date,
+      row.created_at as Date
+    )
+  }
+}

package/src/session/session_manager.ts

@@ -0,0 +1,81 @@
+import { inject } from '../core/inject.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+import Configuration from '../config/configuration.ts'
+import Database from '../database/database.ts'
+
+export interface SessionConfig {
+  cookie: string
+  lifetime: number
+  httpOnly: boolean
+  secure: boolean
+  sameSite: 'strict' | 'lax' | 'none'
+}
+
+/**
+ * Central session configuration hub.
+ *
+ * Resolved once via the DI container — stores the database reference
+ * and parsed config for Session and the session middleware.
+ *
+ * @example
+ * app.singleton(SessionManager)
+ * app.resolve(SessionManager)
+ * await SessionManager.ensureTable()
+ */
+@inject
+export default class SessionManager {
+  private static _db: Database
+  private static _config: SessionConfig
+
+  constructor(db: Database, config: Configuration) {
+    SessionManager._db = db
+    SessionManager._config = {
+      cookie: 'strav_session',
+      lifetime: 120,
+      httpOnly: true,
+      secure: true,
+      sameSite: 'lax',
+      ...(config.get('session', {}) as object),
+    }
+  }
+
+  static get db(): Database {
+    if (!SessionManager._db) {
+      throw new ConfigurationError('SessionManager not configured. Resolve it through the container first.')
+    }
+    return SessionManager._db
+  }
+
+  static get config(): SessionConfig {
+    return SessionManager._config
+  }
+
+  /** Create the sessions table if it does not exist. */
+  static async ensureTable(): Promise<void> {
+    await SessionManager.db.sql`
+      CREATE TABLE IF NOT EXISTS "_strav_sessions" (
+        "id"            UUID PRIMARY KEY,
+        "user_id"       VARCHAR(255),
+        "csrf_token"    VARCHAR(64) NOT NULL,
+        "data"          JSONB NOT NULL DEFAULT '{}',
+        "ip_address"    VARCHAR(45),
+        "user_agent"    TEXT,
+        "last_activity" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "created_at"    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+  }
+
+  /** Delete all expired sessions. Call periodically for housekeeping. */
+  static async gc(): Promise<number> {
+    const lifetimeMs = SessionManager.config.lifetime * 60_000
+    const cutoff = new Date(Date.now() - lifetimeMs)
+
+    const rows = await SessionManager.db.sql`
+      DELETE FROM "_strav_sessions"
+      WHERE "last_activity" < ${cutoff}
+      RETURNING "id"
+    `
+    return rows.length
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,13 @@
+export { default as Storage } from './storage.ts'
+export { Upload, FileTooLargeError, InvalidFileTypeError } from './upload.ts'
+export { default as StorageManager } from './storage_manager.ts'
+export { default as LocalDriver } from './local_driver.ts'
+export { default as S3Driver } from './s3_driver.ts'
+export type {
+  StorageDriver,
+  StorageConfig,
+  FileStats,
+  LocalDriverConfig,
+  S3DriverConfig,
+} from './types.ts'
+export type { UploadResult } from './upload.ts'

package/src/storage/local_driver.ts

@@ -0,0 +1,46 @@
+import { join, extname, resolve } from 'node:path'
+import { unlink } from 'node:fs/promises'
+import { randomHex } from '../helpers/crypto.ts'
+import type { StorageDriver, LocalDriverConfig } from './types.ts'
+
+export default class LocalDriver implements StorageDriver {
+  private root: string
+  private baseUrl: string
+
+  constructor(config: LocalDriverConfig) {
+    this.root = resolve(config.root)
+    this.baseUrl = config.baseUrl
+  }
+
+  async put(directory: string, file: File, name?: string): Promise<string> {
+    const ext = extname(file.name)
+    const filename = name ?? `${randomHex(8)}${ext}`
+    const relativePath = join(directory, filename)
+    const fullPath = join(this.root, relativePath)
+
+    await Bun.write(fullPath, file)
+
+    return relativePath
+  }
+
+  async get(path: string): Promise<Blob | null> {
+    const file = Bun.file(join(this.root, path))
+    if (!(await file.exists())) return null
+    return file
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return Bun.file(join(this.root, path)).exists()
+  }
+
+  async delete(path: string): Promise<void> {
+    const fullPath = join(this.root, path)
+    if (await Bun.file(fullPath).exists()) {
+      await unlink(fullPath)
+    }
+  }
+
+  url(path: string): string {
+    return `${this.baseUrl}/${path}`
+  }
+}

package/src/storage/s3_driver.ts

@@ -0,0 +1,51 @@
+import { S3Client } from 'bun'
+import { extname } from 'node:path'
+import { randomHex } from '../helpers/crypto.ts'
+import type { StorageDriver, S3DriverConfig } from './types.ts'
+
+export default class S3Driver implements StorageDriver {
+  private client: S3Client
+  private cdnUrl?: string
+
+  constructor(config: S3DriverConfig) {
+    this.cdnUrl = config.baseUrl ?? undefined
+
+    this.client = new S3Client({
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      region: config.region,
+      endpoint: config.endpoint ?? undefined,
+      bucket: config.bucket,
+    })
+  }
+
+  async put(directory: string, file: File, name?: string): Promise<string> {
+    const ext = extname(file.name)
+    const filename = name ?? `${randomHex(8)}${ext}`
+    const key = `${directory}/${filename}`
+
+    const s3File = this.client.file(key)
+    await s3File.write(file)
+
+    return key
+  }
+
+  async get(path: string): Promise<Blob | null> {
+    const s3File = this.client.file(path)
+    if (!(await s3File.exists())) return null
+    return new Blob([await s3File.arrayBuffer()])
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this.client.file(path).exists()
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.client.file(path).delete()
+  }
+
+  url(path: string, expiresIn = 3600): string {
+    if (this.cdnUrl) return `${this.cdnUrl}/${path}`
+    return this.client.file(path).presign({ expiresIn })
+  }
+}

package/src/storage/storage.ts

@@ -0,0 +1,43 @@
+import StorageManager from './storage_manager.ts'
+
+/**
+ * Static file storage API.
+ *
+ * Delegates all operations to the configured driver (local or S3).
+ *
+ * @example
+ * const path = await Storage.put('avatars', avatarFile)
+ * const url = Storage.url(path)
+ * await Storage.delete(path)
+ */
+export default class Storage {
+  /** Store a file with a random filename. */
+  static put(directory: string, file: File): Promise<string> {
+    return StorageManager.driver.put(directory, file)
+  }
+
+  /** Store a file with a custom filename. */
+  static putAs(directory: string, file: File, name: string): Promise<string> {
+    return StorageManager.driver.put(directory, file, name)
+  }
+
+  /** Retrieve file content, or null if not found. */
+  static get(path: string): Promise<Blob | null> {
+    return StorageManager.driver.get(path)
+  }
+
+  /** Check if a file exists. */
+  static exists(path: string): Promise<boolean> {
+    return StorageManager.driver.exists(path)
+  }
+
+  /** Delete a file. */
+  static delete(path: string): Promise<void> {
+    return StorageManager.driver.delete(path)
+  }
+
+  /** Generate a URL for the file. */
+  static url(path: string, expiresIn?: number): string {
+    return StorageManager.driver.url(path, expiresIn)
+  }
+}

package/src/storage/storage_manager.ts

@@ -0,0 +1,59 @@
+import { inject } from '../core/inject.ts'
+import Configuration from '../config/configuration.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+import LocalDriver from './local_driver.ts'
+import S3Driver from './s3_driver.ts'
+import type { StorageDriver, StorageConfig } from './types.ts'
+
+/**
+ * Central storage configuration hub.
+ *
+ * Resolved once via the DI container — reads the storage config
+ * and initializes the appropriate driver.
+ *
+ * @example
+ * app.singleton(StorageManager)
+ * app.resolve(StorageManager)
+ */
+@inject
+export default class StorageManager {
+  private static _driver: StorageDriver
+  private static _config: StorageConfig
+
+  constructor(config: Configuration) {
+    const driverName = config.get('storage.default', 'local') as string
+
+    StorageManager._config = {
+      default: driverName as 'local' | 's3',
+      local: {
+        root: 'storage',
+        baseUrl: '/storage',
+        ...(config.get('storage.local', {}) as object),
+      },
+      s3: {
+        bucket: '',
+        region: 'us-east-1',
+        accessKeyId: '',
+        secretAccessKey: '',
+        ...(config.get('storage.s3', {}) as object),
+      },
+    }
+
+    if (driverName === 's3') {
+      StorageManager._driver = new S3Driver(StorageManager._config.s3)
+    } else {
+      StorageManager._driver = new LocalDriver(StorageManager._config.local)
+    }
+  }
+
+  static get driver(): StorageDriver {
+    if (!StorageManager._driver) {
+      throw new ConfigurationError('StorageManager not configured. Resolve it through the container first.')
+    }
+    return StorageManager._driver
+  }
+
+  static get config(): StorageConfig {
+    return StorageManager._config
+  }
+}

package/src/storage/types.ts

@@ -0,0 +1,42 @@
+export interface StorageDriver {
+  /** Store a file and return its relative path/key. */
+  put(directory: string, file: File, name?: string): Promise<string>
+
+  /** Retrieve file content, or null if not found. */
+  get(path: string): Promise<Blob | null>
+
+  /** Check if a file exists. */
+  exists(path: string): Promise<boolean>
+
+  /** Delete a file. */
+  delete(path: string): Promise<void>
+
+  /** Generate a URL for the file. */
+  url(path: string, expiresIn?: number): string
+}
+
+export interface FileStats {
+  size: number
+  lastModified: Date
+  contentType?: string
+}
+
+export interface LocalDriverConfig {
+  root: string
+  baseUrl: string
+}
+
+export interface S3DriverConfig {
+  bucket: string
+  region: string
+  endpoint?: string | null
+  accessKeyId: string
+  secretAccessKey: string
+  baseUrl?: string | null
+}
+
+export interface StorageConfig {
+  default: 'local' | 's3'
+  local: LocalDriverConfig
+  s3: S3DriverConfig
+}