bunigniter 0.2.0

package/dist/helpers/csrf.ts

@@ -0,0 +1,155 @@
+/**
+ * CSRF middleware — Cross-Site Request Forgery protection.
+ *
+ * Generates and validates CSRF tokens for state-changing requests (POST, PUT, DELETE, PATCH).
+ *
+ * @example
+ * ```ts
+ * app.use(csrfMiddleware())
+ * ```
+ *
+ * Then in forms:
+ * ```html
+ * <input type="hidden" name="_token" value="{{csrfToken}}">
+ * ```
+ *
+ * Or in fetch:
+ * ```ts
+ * fetch('/api/users', {
+ *   method: 'POST',
+ *   headers: { 'X-CSRF-Token': csrfToken }
+ * })
+ * ```
+ */
+import { Elysia } from 'elysia'
+import { env } from './env'
+
+export interface CSRFOptions {
+	/** Secret key for token signing. Default: APP_KEY */
+	secret?: string
+
+	/** Cookie name for storing the token. Default: 'XSRF-TOKEN' */
+	cookieName?: string
+
+	/** Header name for token verification. Default: 'X-CSRF-Token' */
+	headerName?: string
+
+	/** Form field name for token verification. Default: '_token' */
+	formField?: string
+
+	/** Methods that require CSRF protection. Default: ['POST', 'PUT', 'PATCH', 'DELETE'] */
+	protectedMethods?: string[]
+
+	/** Paths to exclude from CSRF protection. */
+	exclude?: string[]
+}
+
+/**
+ * Create a CSRF protection middleware.
+ */
+export function csrfMiddleware(options: CSRFOptions = {}) {
+	const {
+		secret = env('APP_KEY', 'dev-csrf-secret'),
+		cookieName = 'XSRF-TOKEN',
+		headerName = 'X-CSRF-Token',
+		formField = '_token',
+		protectedMethods = ['POST', 'PUT', 'PATCH', 'DELETE'],
+		exclude = [],
+	} = options
+
+	const app = new Elysia({ name: 'nexus-csrf' })
+
+	app.derive(async ({ request, cookie: cookieJar }: any) => {
+		const url = new URL(request.url)
+		const path = url.pathname
+
+		// Generate CSRF token
+		const token = generateToken(secret)
+		const previousToken = cookieJar?.[cookieName]?.value
+
+		return {
+			csrfToken: token,
+			csrf: {
+				/**
+				 * Get the current CSRF token value.
+				 */
+				token: () => token,
+
+				/**
+				 * Validate the request's CSRF token.
+				 * Call this in your handler before mutations.
+				 */
+				validate: (request: Request) => {
+					// Skip excluded paths
+					if (exclude.some((s) => path.startsWith(s))) return true
+
+					// Only check protected methods
+					if (!protectedMethods.includes(request.method)) return true
+
+					const tokenHeader = request.headers.get(headerName)
+					const formData = request.headers.get('content-type')?.includes('urlencoded')
+					let tokenValue = tokenHeader
+
+					// Check form field
+					if (!tokenValue && formData) {
+						// _token is handled differently for form data
+					}
+
+					// Check cookie-based token (XSRF-TOKEN)
+					const cookieToken = previousToken
+
+					// If header token matches cookie token, it's valid
+					if (tokenValue && cookieToken && constantTimeCompare(tokenValue, cookieToken)) {
+						return true
+					}
+
+					return false
+				},
+			},
+		}
+	})
+
+	// Set CSRF cookie on every response
+	app.afterResponse(({ csrfToken, cookie: cookieJar }: any) => {
+		if (csrfToken && cookieJar?.[cookieName]) {
+			cookieJar[cookieName].value = csrfToken
+			cookieJar[cookieName].path = '/'
+			cookieJar[cookieName].httpOnly = false // Must be readable by JS
+			cookieJar[cookieName].sameSite = 'Lax'
+		}
+	})
+
+	return app
+}
+
+/**
+ * Generate a CSRF token.
+ * Combines a random value with an HMAC signature.
+ */
+function generateToken(secret: string): string {
+	const random = crypto.randomUUID().replace(/-/g, '')
+	const timestamp = Math.floor(Date.now() / 1000).toString(16)
+	const payload = `${timestamp}.${random}`
+	const sig = sign(payload, secret)
+	return `${payload}.${sig}`
+}
+
+/**
+ * Sign a value with HMAC-SHA256.
+ */
+function sign(value: string, secret: string): string {
+	const { createHmac } = require('node:crypto')
+	return createHmac('sha256', secret).update(value).digest('hex').slice(0, 16)
+}
+
+/**
+ * Constant-time string comparison.
+ */
+function constantTimeCompare(a: string, b: string): boolean {
+	if (a.length !== b.length) return false
+	let result = 0
+	for (let i = 0; i < a.length; i++) {
+		result |= a.charCodeAt(i) ^ b.charCodeAt(i)
+	}
+	return result === 0
+}

package/dist/helpers/debug.ts

@@ -0,0 +1,158 @@
+/**
+ * Debug Toolbar — CodeIgniter-style profiler.
+ *
+ * Collects SQL queries, timing, session data and injects a
+ * collapsible toolbar into HTML responses.
+ *
+ * Enable: `?debug=1` or `DEBUG=true` env var.
+ *
+ * To add SQL profiling, wrap your DB queries:
+ * ```ts
+ * import { debugQuery } from './debug'
+ * const start = performance.now()
+ * // ... execute query ...
+ * debugQuery(ctx, 'SELECT * FROM users', duration, rowCount)
+ * ```
+ */
+
+// ─── Types ─────────────────────────────────────────────────────
+
+export interface DebugQuery {
+	id: number
+	sql: string
+	duration: number
+	rows: number
+	params?: unknown[]
+	time: string
+}
+
+export interface DebugData {
+	method: string
+	path: string
+	status: number
+	duration: number
+	queries: DebugQuery[]
+	session: Record<string, any>
+	memory: string
+	headers: Record<string, string>
+	timestamp: string
+}
+
+// ─── Store ─────────────────────────────────────────────────────
+
+const store = new WeakMap<any, DebugData>()
+
+/** Store a debug data object for the current request context. */
+export function getStore(ctx: any): DebugData {
+	let d = store.get(ctx)
+	if (!d) {
+		d = {
+			method: ctx.request?.method ?? 'GET',
+			path: new URL(ctx.request?.url ?? 'http://localhost').pathname,
+			status: 200,
+			duration: 0,
+			queries: [],
+			session: {},
+			memory: '0 MB',
+			headers: {},
+			timestamp: new Date().toLocaleString(),
+		}
+		store.set(ctx, d)
+	}
+	return d
+}
+
+/** Log a database query for profiling. */
+export function debugQuery(ctx: any, sql: string, duration: number, rows: number, params?: unknown[]): void {
+	const data = getStore(ctx)
+	data.queries.push({
+		id: data.queries.length + 1,
+		sql,
+		duration: Math.round(duration * 100) / 100,
+		rows,
+		params,
+		time: new Date().toLocaleTimeString(),
+	})
+}
+
+// ─── Toolbar HTML (rendered via Rendu template) ──────────────
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Render the debug toolbar using the Rendu template at views/_debug.html.
+ * Falls back to inline generation if template not found.
+ */
+export async function generateToolbar(data: DebugData): Promise<string> {
+	// Try to use the Rendu template
+	const templatePath = join(process.cwd(), 'views', '_debug.html')
+	if (existsSync(templatePath)) {
+		try {
+			const { compileTemplate } = await import('rendu')
+			const source = readFileSync(templatePath, 'utf-8')
+			const fn = compileTemplate(source)
+
+			const maxDur = Math.max(...data.queries.map(q => q.duration), 1)
+			const slowCount = data.queries.filter(q => q.duration > 100).length
+			const totalTime = data.queries.reduce((s, q) => s + q.duration, 0)
+
+			const stream = await fn({
+				htmlspecialchars: (s: unknown) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'),
+				valEscaped: (v: any) => String(typeof v === 'object' ? JSON.stringify(v) : v ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'),
+				method: data.method,
+				path: data.path,
+				status: data.status,
+				duration: data.duration,
+				memory: data.memory,
+				timestamp: data.timestamp,
+				queries: data.queries.map(q => ({
+					...q,
+					barWidth: Math.max(3, (q.duration / maxDur) * 80),
+					color: q.duration > 100 ? '#f94860' : '#7bed9f',
+					pillClass: q.duration > 100 ? 'pill-slow' : 'pill-ok',
+					sqlEscaped: String(q.sql ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'),
+					paramsEscaped: q.params ? String(JSON.stringify(q.params)).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;') : '',
+				})),
+				session: data.session,
+				sessionKeys: String(Object.keys(data.session).length),
+				slowCount,
+				totalTime: Math.round(totalTime * 100) / 100,
+				runtime: typeof Bun !== 'undefined' ? 'Bun ' + Bun.version : 'Node.js',
+			})
+			const reader = stream.getReader()
+			const chunks: Uint8Array[] = []
+			while (true) { const { done, value } = await reader.read(); if (done) break; chunks.push(value) }
+			return new TextDecoder().decode(concatUint8Arrays(chunks))
+		} catch { /* fall through to inline */ }
+	}
+
+	// Inline fallback
+	return renderInline(data)
+}
+
+function renderInline(data: DebugData): string {
+	const slow = data.queries.filter(q => q.duration > 100)
+	const warn = slow.length > 0 ? ' ⚠️' : ''
+	const qtext = data.queries.length === 1 ? 'query' : 'queries'
+
+	return `<!-- Debug -->
+<div class="nexdb" id="__nexdb" style="all:initial;position:fixed;bottom:0;left:0;right:0;z-index:99999;font-family:system-ui,sans-serif;font-size:13px;color:#e0e0e0;background:#13131f;border-top:2px solid #e94560">
+<div style="display:flex;align-items:center;gap:8px;padding:8px 16px;cursor:pointer" onclick="document.getElementById('__nexdb').classList.toggle('open')">
+<span style="font-weight:700;color:#e94560">▣ Bunigniter</span>
+<span style="background:#e94560;color:#fff;padding:1px 7px;border-radius:3px;font-size:11px;font-weight:600">${data.method}</span>
+<span style="flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:#aaa;font-size:12px">${data.path}</span>
+<span style="background:#2d2d5e;color:#fff;padding:1px 7px;border-radius:3px;font-size:11px"><b>${data.status}</b></span>
+<span style="background:rgba(248,165,194,0.15);color:#f8a5c2;padding:1px 7px;border-radius:3px;font-size:11px">${data.duration}ms</span>
+<span style="background:rgba(123,237,159,0.15);color:#7bed9f;padding:1px 7px;border-radius:3px;font-size:11px">📊 <b>${data.queries.length}</b> ${qtext}${warn}</span>
+<span style="background:rgba(112,161,255,0.15);color:#70a1ff;padding:1px 7px;border-radius:3px;font-size:11px">💾 ${data.memory}</span>
+</div></div>`
+}
+
+function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array {
+	const total = arrays.reduce((s, a) => s + a.length, 0)
+	const result = new Uint8Array(total)
+	let offset = 0
+	for (const a of arrays) { result.set(a, offset); offset += a.length }
+	return result
+}

package/dist/helpers/env.ts

@@ -0,0 +1,147 @@
+/**
+ * Environment variable helper — CodeIgniter-style env().
+ *
+ * Reads from `.env` file and `process.env`. Values in `.env` override
+ * system environment variables for development convenience.
+ *
+ * @example
+ * ```ts
+ * const port = env('PORT', 3000)
+ * const dbUrl = env('DATABASE_URL')
+ * const debug = env('DEBUG', false)
+ * ```
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Parsed `.env` cache. */
+let envCache: Record<string, string> | null = null
+
+/** CWD for `.env` resolution. */
+let envDir: string = process.cwd()
+
+/**
+ * Set the working directory for `.env` file lookup.
+ * Called automatically; override for testing.
+ */
+export function setEnvDir(dir: string): void {
+	envDir = dir
+	envCache = null
+}
+
+/**
+ * Parse `.env` file content string.
+ * Supports:
+ *   KEY=value
+ *   KEY="quoted value"
+ *   # comments
+ *   export KEY=value
+ */
+function parseEnv(content: string): Record<string, string> {
+	const result: Record<string, string> = {}
+	for (const line of content.split('\n')) {
+		const trimmed = line.trim()
+		if (!trimmed || trimmed.startsWith('#')) continue
+		const match = trimmed.match(/^(?:export\s+)?([\w._-]+)\s*=\s*(.*)$/)
+		if (!match) continue
+		const key = match[1]
+		let value = match[2].trim()
+
+		// Strip quotes
+		if ((value.startsWith('"') && value.endsWith('"')) ||
+		    (value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1)
+		}
+		result[key] = value
+	}
+	return result
+}
+
+/**
+ * Load `.env` file from CWD (or configured envDir).
+ * Supports `.env`, `.env.local`, `.env.{NODE_ENV}`, `.env.{NODE_ENV}.local`
+ * — loaded in order, later files override earlier ones.
+ */
+export function loadEnv(): Record<string, string> {
+	if (envCache) return envCache
+
+	const env: Record<string, string> = { ...process.env } as Record<string, string>
+	const nodeEnv = process.env.NODE_ENV ?? 'development'
+
+	// Load priority: .env.<environment>.local > .env.local > .env.<environment> > .env
+	const files = [
+		'.env',
+		`.env.${nodeEnv}`,
+		'.env.local',
+		`.env.${nodeEnv}.local`,
+	]
+
+	for (const file of files) {
+		const path = join(envDir, file)
+		if (existsSync(path)) {
+			const parsed = parseEnv(readFileSync(path, 'utf-8'))
+			Object.assign(env, parsed)
+		}
+	}
+
+	envCache = env
+	return env
+}
+
+/**
+ * Read an environment variable with optional default.
+ *
+ * @param key - Environment variable name
+ * @param defaultValue - Value to return if not set
+ * @returns The value cast to the type of defaultValue, or string
+ *
+ * @example
+ * ```ts
+ * const port = env('PORT', 3000)        // number
+ * const name = env('APP_NAME', 'MyApp') // string
+ * const debug = env('DEBUG', false)     // boolean
+ * const required = env('DATABASE_URL')  // string | undefined
+ * ```
+ */
+function castValue<T>(value: string, defaultValue?: T): T {
+	if (typeof defaultValue === 'boolean') {
+		return (value === 'true' || value === '1' || value === 'yes') as unknown as T
+	}
+	if (typeof defaultValue === 'number') {
+		return Number(value) as unknown as T
+	}
+	return value as unknown as T
+}
+
+export function env<T extends string | number | boolean>(
+	key: string,
+	defaultValue?: T
+): T {
+	// Check actual process.env FIRST (it takes priority over .env files)
+	const processValue = (process.env as Record<string, string>)[key]
+	if (processValue !== undefined && processValue !== '') {
+		return castValue(processValue, defaultValue)
+	}
+
+	// Then check .env file values
+	const all = loadEnv()
+	const value = all[key]
+
+	if (value === undefined || value === '') {
+		return defaultValue as T
+	}
+
+	return castValue(value, defaultValue)
+}
+
+/**
+ * Require an environment variable. Throws if not set.
+ */
+export function envOrFail(key: string): string {
+	const all = loadEnv()
+	const value = all[key]
+	if (value === undefined || value === '') {
+		throw new Error(`Required environment variable "${key}" is not set.`)
+	}
+	return value
+}

package/dist/helpers/handler.ts

@@ -0,0 +1,158 @@
+/**
+ * defineHandler — Void-style route handler with optional validation.
+ *
+ * Provides the same API as Void's `defineHandler` + `withValidator`.
+ *
+ * @example
+ * ```ts
+ * // routes/api/users.ts
+ * import { defineHandler } from 'nexusts'
+ * import { db } from 'nexusts/db'
+ *
+ * export const GET = defineHandler(async (c) => {
+ *   return db.select().from(users)
+ * })
+ *
+ * export const POST = defineHandler.withValidator({
+ *   body: z.object({ name: z.string(), email: z.string().email() })
+ * })(async (c, { body }) => {
+ *   return db.insert(users).values(body).returning()
+ * })
+ * ```
+ */
+import type { Context } from 'elysia'
+import type { z } from 'zod'
+import { validateZod, type ValidationErrors } from './validator'
+
+/** Handler function type. */
+export type HandlerFn<T = any> = (c: Context, args?: T) => any
+
+/** Validator config matching defineHandler.withValidator({ body, query, params }). */
+export interface HandlerValidatorConfig {
+	body?: z.ZodSchema
+	query?: z.ZodSchema
+	params?: z.ZodSchema
+}
+
+/** Wrapped handler with validated args. */
+export type ValidatedHandler<T> = (c: Context, args: T) => any
+
+/**
+ * createHandler — wraps a function as a route handler.
+ * Auto-converts return values to Response objects.
+ */
+function toResponse(result: any, c?: Context): Response {
+	if (result instanceof Response) return result
+	if (result === null || result === undefined) return new Response(null, { status: 204 })
+	if (typeof result === 'string') {
+		return new Response(result, {
+			headers: { 'content-type': 'text/html; charset=utf-8' },
+		})
+	}
+	// object / array / number / boolean → JSON
+	return new Response(JSON.stringify(result), {
+		headers: { 'content-type': 'application/json' },
+		...(c ? { status: (c as any).set?.status ?? 200 } : {}),
+	})
+}
+
+/**
+ * defineHandler — Void-style route handler factory.
+ *
+ * Usage:
+ * ```ts
+ * export const GET = defineHandler(async (c) => {
+ *   return { users: await db.select().from(users) }
+ * })
+ * ```
+ */
+export function defineHandler<T extends HandlerFn>(fn: T): T {
+	return ((c: Context) => {
+		const result = fn(c)
+		if (result instanceof Promise) {
+			return result.then((r: any) => toResponse(r, c))
+		}
+		return toResponse(result, c)
+	}) as unknown as T
+}
+
+/**
+ * defineHandler.withValidator — handler with input validation.
+ *
+ * Usage:
+ * ```ts
+ * export const POST = defineHandler.withValidator({
+ *   body: z.object({ name: z.string(), email: z.string().email() })
+ * })(async (c, { body }) => {
+ *   return db.insert(users).values(body).returning()
+ * })
+ * ```
+ */
+defineHandler.withValidator = function <T extends ValidatedHandler<any>>(
+	validators: HandlerValidatorConfig
+) {
+	return function (fn: T): HandlerFn {
+		return async (c: Context) => {
+			const errors: Record<string, ValidationErrors> = {}
+
+			// Validate body (Elysia v2 puts parsed body on c.body)
+			if (validators.body) {
+				const body = (c as any).body ?? {}
+				const result = validators.body.safeParse(body)
+				if (!result.success) {
+					errors.body = mapZodErrors(result.error)
+				} else {
+					(c as any)._validatedBody = result.data
+				}
+			}
+
+			// Validate query
+			if (validators.query) {
+				const query = Object.fromEntries(
+					new URL(c.request.url).searchParams.entries()
+				)
+				const result = validators.query.safeParse(query)
+				if (!result.success) {
+					errors.query = mapZodErrors(result.error)
+				} else {
+					(c as any)._validatedQuery = result.data
+				}
+			}
+
+			// Validate params
+			if (validators.params) {
+				const result = validators.params.safeParse((c as any).params ?? {})
+				if (!result.success) {
+					errors.params = mapZodErrors(result.error)
+				}
+			}
+
+			if (Object.keys(errors).length > 0) {
+				return new Response(JSON.stringify({
+					error: 'Validation failed',
+					issues: errors,
+				}), {
+					status: 400,
+					headers: { 'content-type': 'application/json' },
+				})
+			}
+
+			const result = await fn(c, {
+				body: (c as any)._validatedBody,
+				query: (c as any)._validatedQuery,
+				params: (c as any).params,
+			})
+			return toResponse(result, c)
+		}
+	}
+}
+
+/** Map Zod errors to our format. */
+function mapZodErrors(error: any): ValidationErrors {
+	const errors: ValidationErrors = {}
+	for (const issue of error.issues ?? []) {
+		const path = issue.path.join('.')
+		;(errors[path] ??= []).push(issue.message)
+	}
+	return errors
+}