@strav/http 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@strav/http",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "HTTP layer for the Strav framework — router, server, middleware, authentication, sessions, validation, and views",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "framework",
+    "typescript",
+    "strav",
+    "http"
+  ],
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./http": "./src/http/index.ts",
+    "./http/*": "./src/http/*.ts",
+    "./view": "./src/view/index.ts",
+    "./view/*": "./src/view/*.ts",
+    "./session": "./src/session/index.ts",
+    "./session/*": "./src/session/*.ts",
+    "./validation": "./src/validation/index.ts",
+    "./validation/*": "./src/validation/*.ts",
+    "./policy": "./src/policy/index.ts",
+    "./policy/*": "./src/policy/*.ts",
+    "./auth": "./src/auth/index.ts",
+    "./auth/*": "./src/auth/*.ts",
+    "./providers": "./src/providers/index.ts",
+    "./providers/*": "./src/providers/*.ts"
+  },
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/database": "0.1.0"
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.28",
+    "luxon": "^3.7.2",
+    "@types/luxon": "^3.7.1"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/auth/access_token.ts

@@ -0,0 +1,122 @@
+import Auth, { extractUserId, randomHex } from './auth.ts'
+
+/** The DB record for an access token (never contains the plain token). */
+export interface AccessTokenData {
+  id: number
+  userId: string
+  name: string
+  lastUsedAt: Date | null
+  expiresAt: Date | null
+  createdAt: Date
+}
+
+function hashToken(plain: string): string {
+  return new Bun.CryptoHasher('sha256').update(plain).digest('hex')
+}
+
+/**
+ * Opaque, SHA-256-hashed access tokens stored in the database.
+ *
+ * The plain-text token is returned exactly once at creation time and
+ * is never stored. Even if the database leaks, tokens cannot be recovered.
+ *
+ * @example
+ * // Create
+ * const { token, accessToken } = await AccessToken.create(user, 'mobile-app')
+ * // token = 'a1b2c3...' (give to the client, shown once)
+ *
+ * // Validate (used internally by the auth middleware)
+ * const record = await AccessToken.validate(plainToken)
+ *
+ * // Revoke
+ * await AccessToken.revoke(accessToken.id)
+ */
+export default class AccessToken {
+  /**
+   * Generate a new access token for the given user.
+   * Returns the plain-text token (shown once) and the database record.
+   */
+  static async create(
+    user: unknown,
+    name: string
+  ): Promise<{ token: string; accessToken: AccessTokenData }> {
+    const userId = extractUserId(user)
+    const plain = randomHex(32) // 64-char hex string
+    const hash = hashToken(plain)
+
+    const expCfg = Auth.config.token.expiration
+    const expiresAt = expCfg ? new Date(Date.now() + expCfg * 60_000) : null
+
+    const rows = await Auth.db.sql`
+      INSERT INTO "_strav_access_tokens" ("user_id", "name", "token", "expires_at")
+      VALUES (${userId}, ${name}, ${hash}, ${expiresAt})
+      RETURNING *
+    `
+
+    return {
+      token: plain,
+      accessToken: AccessToken.hydrate(rows[0] as Record<string, unknown>),
+    }
+  }
+
+  /**
+   * Validate a plain-text token. Returns the token record if valid, null otherwise.
+   * Automatically rejects expired tokens and updates last_used_at.
+   */
+  static async validate(plainToken: string): Promise<AccessTokenData | null> {
+    const hash = hashToken(plainToken)
+
+    const rows = await Auth.db.sql`
+      SELECT * FROM "_strav_access_tokens" WHERE "token" = ${hash} LIMIT 1
+    `
+    if (rows.length === 0) return null
+
+    const record = AccessToken.hydrate(rows[0] as Record<string, unknown>)
+
+    if (record.expiresAt && record.expiresAt.getTime() < Date.now()) {
+      return null
+    }
+
+    // Update last_used_at (fire-and-forget)
+    Auth.db.sql`
+      UPDATE "_strav_access_tokens"
+      SET "last_used_at" = NOW()
+      WHERE "id" = ${record.id}
+    `.then(
+      () => {},
+      () => {}
+    )
+
+    return record
+  }
+
+  /** Revoke (delete) a single token by its database ID. */
+  static async revoke(id: number): Promise<void> {
+    await Auth.db.sql`
+      DELETE FROM "_strav_access_tokens" WHERE "id" = ${id}
+    `
+  }
+
+  /** Revoke all tokens belonging to a user. */
+  static async revokeAllFor(user: unknown): Promise<void> {
+    const userId = extractUserId(user)
+    await Auth.db.sql`
+      DELETE FROM "_strav_access_tokens" WHERE "user_id" = ${userId}
+    `
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): AccessTokenData {
+    return {
+      id: row.id as number,
+      userId: row.user_id as string,
+      name: row.name as string,
+      lastUsedAt: (row.last_used_at as Date) ?? null,
+      expiresAt: (row.expires_at as Date) ?? null,
+      createdAt: row.created_at as Date,
+    }
+  }
+}

package/src/auth/auth.ts

@@ -0,0 +1,87 @@
+import { inject } from '@stravigor/kernel/core/inject'
+import { ConfigurationError } from '@stravigor/kernel/exceptions/errors'
+import Configuration from '@stravigor/kernel/config/configuration'
+import Database from '@stravigor/database/database/database'
+
+// Re-export helpers that were originally defined here
+export { extractUserId } from '@stravigor/database/helpers/identity'
+export { randomHex } from '@stravigor/kernel/helpers/crypto'
+
+export interface TokenConfig {
+  expiration: number | null
+}
+
+export interface AuthConfig {
+  default: string
+  token: TokenConfig
+}
+
+type UserResolver = (id: string | number) => Promise<unknown>
+
+/**
+ * Central auth configuration hub.
+ *
+ * Resolved once via the DI container — stores the database reference,
+ * parsed config, and user resolver for AccessToken and auth middleware.
+ *
+ * @example
+ * app.singleton(Auth)
+ * app.resolve(Auth)
+ * Auth.useResolver((id) => User.find(id))
+ * await Auth.ensureTables()
+ */
+@inject
+export default class Auth {
+  private static _db: Database
+  private static _config: AuthConfig
+  private static _resolver: UserResolver
+
+  constructor(db: Database, config: Configuration) {
+    Auth._db = db
+    Auth._config = {
+      default: config.get('auth.default', 'session') as string,
+      token: {
+        expiration: null,
+        ...(config.get('auth.token', {}) as object),
+      },
+    }
+  }
+
+  /** Register the function used to load a user by ID. */
+  static useResolver(resolver: UserResolver): void {
+    Auth._resolver = resolver
+  }
+
+  static get db(): Database {
+    if (!Auth._db)
+      throw new ConfigurationError('Auth not configured. Resolve Auth through the container first.')
+    return Auth._db
+  }
+
+  static get config(): AuthConfig {
+    return Auth._config
+  }
+
+  /** Load a user by ID using the registered resolver. */
+  static async resolveUser(id: string | number): Promise<unknown> {
+    if (!Auth._resolver) {
+      throw new ConfigurationError('Auth resolver not configured. Call Auth.useResolver() first.')
+    }
+    return Auth._resolver(id)
+  }
+
+  /** Create the internal access_tokens table if it doesn't exist. */
+  static async ensureTables(): Promise<void> {
+    await Auth.db.sql`
+      CREATE TABLE IF NOT EXISTS "_strav_access_tokens" (
+        "id" SERIAL PRIMARY KEY,
+        "user_id" VARCHAR(255) NOT NULL,
+        "name" VARCHAR(255) NOT NULL,
+        "token" VARCHAR(64) NOT NULL UNIQUE,
+        "last_used_at" TIMESTAMPTZ,
+        "expires_at" TIMESTAMPTZ,
+        "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,7 @@
+export { default as Auth } from './auth.ts'
+export { default as AccessToken } from './access_token.ts'
+export { auth } from './middleware/authenticate.ts'
+export { csrf } from './middleware/csrf.ts'
+export { guest } from './middleware/guest.ts'
+export type { AuthConfig, TokenConfig } from './auth.ts'
+export type { AccessTokenData } from './access_token.ts'

package/src/auth/middleware/authenticate.ts

@@ -0,0 +1,64 @@
+import type { Middleware } from '../../http/middleware.ts'
+import Auth from '../auth.ts'
+import type Session from '../../session/session.ts'
+import AccessToken from '../access_token.ts'
+
+/**
+ * Require the request to be authenticated.
+ *
+ * For the session guard, requires the `session()` middleware to run first
+ * so that `ctx.get('session')` is available. Checks that the session has
+ * a user associated with it.
+ *
+ * Sets:
+ * - `ctx.get('user')` — the resolved user object
+ * - `ctx.get('accessToken')` — the AccessTokenData (token guard only)
+ *
+ * @param guard  'session' | 'token' (defaults to config `auth.default`)
+ *
+ * @example
+ * router.group({ middleware: [session(), auth()] }, (r) => { ... })
+ * router.group({ middleware: [auth('token')] }, (r) => { ... })
+ */
+export function auth(guard?: string): Middleware {
+  return async (ctx, next) => {
+    const guardName = guard ?? Auth.config.default
+
+    if (guardName === 'session') {
+      const session = ctx.get<Session>('session')
+
+      if (!session || !session.isAuthenticated || session.isExpired()) {
+        return ctx.json({ error: 'Unauthenticated' }, 401)
+      }
+
+      const user = await Auth.resolveUser(session.userId!)
+      if (!user) return ctx.json({ error: 'Unauthenticated' }, 401)
+
+      ctx.set('user', user)
+
+      const response = await next()
+      await session.touch()
+      return response
+    }
+
+    if (guardName === 'token') {
+      const header = ctx.header('authorization')
+      if (!header?.startsWith('Bearer ')) {
+        return ctx.json({ error: 'Unauthenticated' }, 401)
+      }
+
+      const accessToken = await AccessToken.validate(header.slice(7))
+      if (!accessToken) return ctx.json({ error: 'Unauthenticated' }, 401)
+
+      const user = await Auth.resolveUser(accessToken.userId)
+      if (!user) return ctx.json({ error: 'Unauthenticated' }, 401)
+
+      ctx.set('user', user)
+      ctx.set('accessToken', accessToken)
+
+      return next()
+    }
+
+    return ctx.json({ error: `Unknown auth guard: ${guardName}` }, 500)
+  }
+}

package/src/auth/middleware/csrf.ts

@@ -0,0 +1,62 @@
+import type { Middleware } from '../../http/middleware.ts'
+import type Session from '../../session/session.ts'
+
+/**
+ * CSRF protection middleware.
+ *
+ * Must be placed **after** the `session()` middleware so that
+ * `ctx.get('session')` is available. Works for both anonymous and
+ * authenticated sessions.
+ *
+ * On safe methods (GET, HEAD, OPTIONS) the CSRF token is made available
+ * via `ctx.get('csrfToken')` for embedding in forms or meta tags.
+ *
+ * On state-changing methods, the middleware checks for a matching token in:
+ * 1. `X-CSRF-Token` header
+ * 2. `X-XSRF-Token` header
+ * 3. `_token` field in a JSON or form body
+ *
+ * @example
+ * router.group({ middleware: [session(), csrf()] }, (r) => {
+ *   r.post('/login', handleLogin)
+ * })
+ */
+export function csrf(): Middleware {
+  return async (ctx, next) => {
+    const session = ctx.get<Session>('session')
+
+    if (['GET', 'HEAD', 'OPTIONS'].includes(ctx.method)) {
+      if (session) ctx.set('csrfToken', session.csrfToken)
+      return next()
+    }
+
+    if (!session) {
+      return ctx.json({ error: 'Session required for CSRF protection' }, 403)
+    }
+
+    // Check headers first
+    let token = ctx.header('X-CSRF-Token') ?? ctx.header('X-XSRF-Token')
+
+    // Fall back to request body
+    if (!token) {
+      const contentType = ctx.header('content-type') ?? ''
+
+      if (contentType.includes('application/json')) {
+        const body = await ctx.body<Record<string, unknown>>()
+        if (typeof body._token === 'string') token = body._token
+      } else if (
+        contentType.includes('application/x-www-form-urlencoded') ||
+        contentType.includes('multipart/form-data')
+      ) {
+        const body = await ctx.body<FormData>()
+        if (body instanceof FormData) token = body.get('_token') as string | null
+      }
+    }
+
+    if (!token || token !== session.csrfToken) {
+      return ctx.json({ error: 'CSRF token mismatch' }, 403)
+    }
+
+    return next()
+  }
+}

package/src/auth/middleware/guest.ts

@@ -0,0 +1,46 @@
+import type { Middleware } from '../../http/middleware.ts'
+import Auth from '../auth.ts'
+import type Session from '../../session/session.ts'
+import AccessToken from '../access_token.ts'
+
+/**
+ * Only allow unauthenticated requests through.
+ *
+ * For the session guard, requires the `session()` middleware to run first
+ * so that `ctx.get('session')` is available.
+ *
+ * Useful for login/register pages that should not be accessible to
+ * users who are already logged in.
+ *
+ * @param redirectTo  If provided, authenticated users are redirected here
+ *                    instead of receiving a 403.
+ *
+ * @example
+ * router.group({ middleware: [session(), guest('/dashboard')] }, (r) => {
+ *   r.get('/login', showLoginPage)
+ * })
+ */
+export function guest(redirectTo?: string): Middleware {
+  return async (ctx, next) => {
+    const guardName = Auth.config.default
+    let isAuthenticated = false
+
+    if (guardName === 'session') {
+      const session = ctx.get<Session>('session')
+      isAuthenticated = session !== null && session.isAuthenticated && !session.isExpired()
+    } else if (guardName === 'token') {
+      const header = ctx.header('authorization')
+      if (header?.startsWith('Bearer ')) {
+        const accessToken = await AccessToken.validate(header.slice(7))
+        isAuthenticated = accessToken !== null
+      }
+    }
+
+    if (isAuthenticated) {
+      if (redirectTo) return ctx.redirect(redirectTo)
+      return ctx.json({ error: 'Already authenticated' }, 403)
+    }
+
+    return next()
+  }
+}

package/src/http/context.ts

@@ -0,0 +1,220 @@
+import { parseCookies } from './cookie.ts'
+import type { ViewEngine } from '@stravigor/view'
+import { ConfigurationError } from '@stravigor/kernel/exceptions/errors'
+
+/**
+ * HTTP request context — the primary object handlers interact with.
+ *
+ * Wraps Bun's native Request and adds route params, body parsing,
+ * response helpers, and a type-safe state bag for middleware.
+ */
+export default class Context {
+  private static _viewEngine: ViewEngine | null = null
+
+  static setViewEngine(engine: ViewEngine): void {
+    Context._viewEngine = engine
+  }
+
+  readonly url: URL
+  readonly method: string
+  readonly path: string
+  readonly headers: Headers
+
+  private _state = new Map<string, unknown>()
+  private _subdomain?: string
+  private _query?: URLSearchParams
+  private _cookies?: Map<string, string>
+  private _body?: unknown
+  private _bodyParsed = false
+
+  constructor(
+    readonly request: Request,
+    readonly params: Record<string, string> = {},
+    private domain: string = 'localhost'
+  ) {
+    this.url = new URL(request.url)
+    this.method = request.method
+    this.path = this.url.pathname
+    this.headers = request.headers
+  }
+
+  // ---------------------------------------------------------------------------
+  // Request helpers
+  // ---------------------------------------------------------------------------
+
+  /** Parsed query string parameters. */
+  get query(): URLSearchParams {
+    if (!this._query) this._query = this.url.searchParams
+    return this._query
+  }
+
+  /** Subdomain extracted from the Host header relative to the configured domain. */
+  get subdomain(): string {
+    if (this._subdomain !== undefined) return this._subdomain
+
+    const host = this.headers.get('host') ?? ''
+    const hostname = host.split(':')[0] ?? ''
+
+    if (hostname.endsWith(this.domain) && hostname.length > this.domain.length) {
+      this._subdomain = hostname.slice(0, -(this.domain.length + 1))
+    } else {
+      this._subdomain = ''
+    }
+
+    return this._subdomain
+  }
+
+  /** Shorthand for reading a single request header. */
+  header(name: string): string | null {
+    return this.headers.get(name)
+  }
+
+  /** Read a query string parameter, with optional typed default. */
+  qs(name: string): string | null
+  qs(name: string, defaultValue: number): number
+  qs(name: string, defaultValue: string): string
+  qs(name: string, defaultValue?: string | number): string | number | null {
+    const value = this.query.get(name)
+    if (value === null || value === '') return defaultValue ?? null
+    if (typeof defaultValue === 'number') {
+      const parsed = Number(value)
+      return Number.isNaN(parsed) ? defaultValue : parsed
+    }
+    return value
+  }
+
+  /** Read a cookie value by name from the Cookie header. */
+  cookie(name: string): string | null {
+    if (!this._cookies) {
+      this._cookies = parseCookies(this.headers.get('cookie') ?? '')
+    }
+    return this._cookies.get(name) ?? null
+  }
+
+  /** Extract named string fields from a form body. With no args, returns all non-file fields. */
+  async inputs<K extends string>(...keys: K[]): Promise<Record<K, string>> {
+    const form = await this.body<FormData>()
+    const result = {} as Record<K, string>
+    if (keys.length === 0) {
+      form.forEach((value, key) => {
+        if (typeof value === 'string') (result as Record<string, string>)[key] = value
+      })
+    } else {
+      for (const key of keys) {
+        const value = form.get(key)
+        result[key] = typeof value === 'string' ? value : ''
+      }
+    }
+    return result
+  }
+
+  /** Extract named file fields from a form body. With no args, returns all file fields. */
+  async files<K extends string>(...keys: K[]): Promise<Record<K, File | null>> {
+    const form = await this.body<FormData>()
+    const result = {} as Record<K, File | null>
+    if (keys.length === 0) {
+      form.forEach((value, key) => {
+        if (value instanceof File) (result as Record<string, File>)[key] = value
+      })
+    } else {
+      for (const key of keys) {
+        const value = form.get(key)
+        result[key] = value instanceof File ? value : null
+      }
+    }
+    return result
+  }
+
+  /**
+   * Parse the request body. Automatically detects JSON, form-data, and text.
+   * The result is cached — safe to call multiple times.
+   */
+  async body<T = unknown>(): Promise<T> {
+    if (!this._bodyParsed) {
+      const contentType = this.header('content-type') ?? ''
+
+      if (contentType.includes('application/json')) {
+        this._body = await this.request.json()
+      } else if (
+        contentType.includes('multipart/form-data') ||
+        contentType.includes('application/x-www-form-urlencoded')
+      ) {
+        const formData = await this.request.formData()
+        const obj: Record<string, unknown> = {}
+        formData.forEach((value, key) => {
+          obj[key] = value
+        })
+        this._body = obj
+      } else {
+        this._body = await this.request.text()
+      }
+
+      this._bodyParsed = true
+    }
+
+    return this._body as T
+  }
+
+  // ---------------------------------------------------------------------------
+  // Response helpers
+  // ---------------------------------------------------------------------------
+
+  json(data: unknown, status = 200): Response {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+
+  text(content: string, status = 200): Response {
+    return new Response(content, {
+      status,
+      headers: { 'Content-Type': 'text/plain' },
+    })
+  }
+
+  html(content: string, status = 200): Response {
+    return new Response(content, {
+      status,
+      headers: { 'Content-Type': 'text/html' },
+    })
+  }
+
+  redirect(url: string, status = 302): Response {
+    return new Response(null, {
+      status,
+      headers: { Location: url },
+    })
+  }
+
+  empty(status = 204): Response {
+    return new Response(null, { status })
+  }
+
+  async view(template: string, data?: Record<string, unknown>, status = 200): Promise<Response> {
+    if (!Context._viewEngine) {
+      throw new ConfigurationError('ViewEngine not configured. Register it in the container.')
+    }
+    const html = await Context._viewEngine.render(template, data)
+    return this.html(html, status)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Middleware state
+  // ---------------------------------------------------------------------------
+
+  /** Store a value for downstream middleware / handlers. */
+  set<T>(key: string, value: T): void {
+    this._state.set(key, value)
+  }
+
+  /** Retrieve a value set by upstream middleware. */
+  get<T>(key: string): T
+  get<T1, T2>(k1: string, k2: string): [T1, T2]
+  get<T1, T2, T3>(k1: string, k2: string, k3: string): [T1, T2, T3]
+  get<T1, T2, T3, T4>(k1: string, k2: string, k3: string, k4: string): [T1, T2, T3, T4]
+  get(...keys: string[]): unknown {
+    if (keys.length === 1) return this._state.get(keys[0]!)
+    return keys.map(k => this._state.get(k))
+  }
+}