@stravigor/core 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @stravigor/core
+
+The Strav framework for Bun. A full-stack TypeScript framework built on [Bun](https://bun.sh) with PostgreSQL.
+
+## Install
+
+```bash
+bun add @stravigor/core
+```
+
+## Modules
+
+Import what you need via subpath exports:
+
+```ts
+import { router } from '@stravigor/core/http'
+import { defineSchema } from '@stravigor/core/schema'
+import BaseModel from '@stravigor/core/orm/base_model'
+import { session } from '@stravigor/core/session'
+import { auth } from '@stravigor/core/auth'
+import { cache } from '@stravigor/core/cache'
+import { mail } from '@stravigor/core/mail'
+import { broadcast } from '@stravigor/core/broadcast'
+import { env } from '@stravigor/core/helpers/env'
+```
+
+Available modules: `core`, `config`, `database`, `schema`, `orm`, `http`, `view`, `validation`, `session`, `auth`, `events`, `queue`, `policy`, `helpers`, `generators`, `logger`, `storage`, `cache`, `scheduler`, `mail`, `notification`, `broadcast`, `encryption`, `exceptions`, `i18n`, `cli`.
+
+## CLI
+
+```bash
+bunx strav migration:run
+bunx strav migration:generate
+bunx strav generate:models
+bunx strav generate:api
+```
+
+## Related Packages
+
+- [@stravigor/ai](https://www.npmjs.com/package/@stravigor/ai) - AI module (Anthropic, OpenAI)
+- [@stravigor/testing](https://www.npmjs.com/package/@stravigor/testing) - Testing utilities
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@stravigor/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The Strav framework for Bun",
+  "license": "MIT",
+  "keywords": ["bun", "framework", "typescript", "strav"],
+  "files": ["src/", "package.json", "tsconfig.json"],
+  "exports": {
+    "./core": "./src/core/index.ts",
+    "./core/*": "./src/core/*.ts",
+    "./config": "./src/config/index.ts",
+    "./config/*": "./src/config/*.ts",
+    "./database": "./src/database/index.ts",
+    "./database/*": "./src/database/*.ts",
+    "./schema": "./src/schema/index.ts",
+    "./schema/*": "./src/schema/*.ts",
+    "./orm": "./src/orm/index.ts",
+    "./orm/*": "./src/orm/*.ts",
+    "./http": "./src/http/index.ts",
+    "./http/*": "./src/http/*.ts",
+    "./view": "./src/view/index.ts",
+    "./view/*": "./src/view/*.ts",
+    "./validation": "./src/validation/index.ts",
+    "./validation/*": "./src/validation/*.ts",
+    "./session": "./src/session/index.ts",
+    "./session/*": "./src/session/*.ts",
+    "./auth": "./src/auth/index.ts",
+    "./auth/*": "./src/auth/*.ts",
+    "./events": "./src/events/index.ts",
+    "./events/*": "./src/events/*.ts",
+    "./queue": "./src/queue/index.ts",
+    "./queue/*": "./src/queue/*.ts",
+    "./policy": "./src/policy/index.ts",
+    "./policy/*": "./src/policy/*.ts",
+    "./helpers": "./src/helpers/index.ts",
+    "./helpers/*": "./src/helpers/*.ts",
+    "./generators": "./src/generators/index.ts",
+    "./generators/*": "./src/generators/*.ts",
+    "./logger": "./src/logger/index.ts",
+    "./logger/*": "./src/logger/*.ts",
+    "./storage": "./src/storage/index.ts",
+    "./storage/*": "./src/storage/*.ts",
+    "./cache": "./src/cache/index.ts",
+    "./cache/*": "./src/cache/*.ts",
+    "./scheduler": "./src/scheduler/index.ts",
+    "./scheduler/*": "./src/scheduler/*.ts",
+    "./mail": "./src/mail/index.ts",
+    "./mail/*": "./src/mail/*.ts",
+    "./notification": "./src/notification/index.ts",
+    "./notification/*": "./src/notification/*.ts",
+    "./broadcast": "./src/broadcast/index.ts",
+    "./broadcast/*": "./src/broadcast/*.ts",
+    "./encryption": "./src/encryption/index.ts",
+    "./encryption/*": "./src/encryption/*.ts",
+    "./exceptions": "./src/exceptions/index.ts",
+    "./exceptions/*": "./src/exceptions/*.ts",
+    "./i18n": "./src/i18n/index.ts",
+    "./i18n/*": "./src/i18n/*.ts",
+    "./cli": "./src/cli/strav.ts",
+    "./cli/*": "./src/cli/*.ts"
+  },
+  "bin": {
+    "strav": "./src/cli/strav.ts"
+  },
+  "dependencies": {
+    "@types/luxon": "^3.7.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "luxon": "^3.7.2",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "nodemailer": "^6.10.0",
+    "@types/nodemailer": "^6.4.0",
+    "juice": "^11.0.0",
+    "reflect-metadata": "^0.2.2",
+    "@vue/compiler-sfc": "^3.5.28"
+  },
+  "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,86 @@
+import { inject } from '../core/inject.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+import Configuration from '../config/configuration.ts'
+import Database from '../database/database.ts'
+
+// Re-export helpers that were originally defined here
+export { extractUserId } from '../helpers/identity.ts'
+export { randomHex } from '../helpers/crypto.ts'
+
+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()
+  }
+}