@etus/bhono-app 0.1.1

package/templates/base/src/server/lib/session.ts

@@ -0,0 +1,267 @@
+// src/server/lib/session.ts
+import type { Context, MiddlewareHandler } from 'hono'
+import { getCookie } from 'hono/cookie'
+import { getConnInfo } from 'hono/cloudflare-workers'
+import { serialize as serializeCookie } from 'hono/utils/cookie'
+import type { Env } from '../env'
+
+/**
+ * Session data stored in KV
+ */
+export interface SessionData {
+  userId: string
+  email: string
+  name: string
+  avatarUrl?: string | null
+  isSuperAdmin: boolean
+  fingerprint?: {
+    ip?: string
+    userAgent?: string
+  }
+}
+
+/**
+ * Session variables added to Hono context
+ */
+export interface SessionVars {
+  sessionId?: string
+  sessionData?: SessionData
+  sessionCookies?: string[]
+}
+
+/**
+ * Session configuration options
+ */
+export interface SessionOptions {
+  cookieName?: string
+  ttlSeconds?: number
+  sliding?: boolean
+  keyPrefix?: string
+  cookie?: {
+    path?: string
+    domain?: string
+    secure?: boolean
+    httpOnly?: boolean
+    sameSite?: 'lax' | 'strict' | 'none'
+  }
+}
+
+/**
+ * Generate a cryptographically secure random session ID
+ */
+function generateSessionId(): string {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return btoa(String.fromCharCode(...bytes))
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replaceAll('=', '')
+}
+
+/**
+ * Extract fingerprint data from request for session binding
+ */
+function extractFingerprint(c: Context): { ip?: string; userAgent?: string } {
+  let ip: string | undefined
+
+  try {
+    const connInfo = getConnInfo(c)
+    ip = connInfo.remote.address
+  } catch {
+    // Ignore connection info errors in test/mocked contexts
+  }
+
+  const userAgent = c.req.header('user-agent') ?? undefined
+
+  return { ip, userAgent }
+}
+
+/**
+ * Validate session fingerprint to detect potential session hijacking
+ */
+function isFingerprintValid(
+  stored?: { ip?: string; userAgent?: string },
+  current?: { ip?: string; userAgent?: string }
+): boolean {
+  if (!stored || !current) return true
+
+  // User-Agent should never change for the same session
+  if (stored.userAgent && current.userAgent && stored.userAgent !== current.userAgent) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Session middleware: reads session from KV, sets context variables
+ */
+export function sessionMiddleware(opts?: SessionOptions): MiddlewareHandler {
+  return async (c, next) => {
+    const isSecure = new URL(c.req.url).protocol === 'https:'
+
+    const {
+      cookieName = isSecure ? '__Host-sid' : 'sid',
+      ttlSeconds = 60 * 60 * 24, // 24 hours
+      sliding = true,
+      keyPrefix = 'sid:',
+    } = opts ?? {}
+
+    // Try to read session cookie
+    const sid = getCookie(c, cookieName) ?? getCookie(c, isSecure ? 'sid' : '__Host-sid')
+    const store = (c.env as Env).SESSIONS
+
+    if (sid && store) {
+      const key = `${keyPrefix}${sid}`
+      const raw = await store.get(key)
+
+      if (raw) {
+        try {
+          const data = JSON.parse(raw) as SessionData
+
+          // Validate fingerprint
+          const currentFingerprint = extractFingerprint(c)
+          if (!isFingerprintValid(data.fingerprint, currentFingerprint)) {
+            console.warn('[SECURITY] Session fingerprint mismatch', { sessionId: sid })
+            await store.delete(key)
+            // Clear cookie
+            const serializedCookie = serializeCookie(cookieName, '', {
+              path: '/',
+              secure: isSecure,
+              httpOnly: true,
+              expires: new Date(0),
+              sameSite: 'lax',
+            })
+            c.header('Set-Cookie', serializedCookie)
+            await next()
+            return
+          }
+
+          c.set('sessionId', sid)
+          c.set('sessionData', data)
+
+          // Sliding expiration
+          if (sliding) {
+            await store.put(key, raw, { expirationTtl: ttlSeconds })
+          }
+        } catch {
+          // Invalid JSON in KV - ignore
+        }
+      }
+    }
+
+    c.set('sessionCookies', c.get('sessionCookies') ?? [])
+    await next()
+
+    // Apply any cookies set during request
+    const cookieJar = c.get('sessionCookies') as string[] | undefined
+    if (cookieJar?.length) {
+      for (const cookie of cookieJar) {
+        c.header('Set-Cookie', cookie, { append: true })
+      }
+    }
+  }
+}
+
+/**
+ * Create a new session: generates SID, stores in KV, sets cookie
+ */
+export async function createSession(
+  c: Context,
+  data: Omit<SessionData, 'fingerprint'>,
+  opts?: SessionOptions
+): Promise<string> {
+  const isSecure = new URL(c.req.url).protocol === 'https:'
+
+  const {
+    cookieName = isSecure ? '__Host-sid' : 'sid',
+    ttlSeconds = 60 * 60 * 24,
+    keyPrefix = 'sid:',
+    cookie = {},
+  } = opts ?? {}
+
+  const sid = generateSessionId()
+  const store = (c.env as Env).SESSIONS
+
+  // Add fingerprint to session data
+  const fingerprint = extractFingerprint(c)
+  const dataWithFingerprint: SessionData = { ...data, fingerprint }
+
+  if (store) {
+    const key = `${keyPrefix}${sid}`
+    await store.put(key, JSON.stringify(dataWithFingerprint), {
+      expirationTtl: ttlSeconds,
+    })
+  }
+
+  // Serialize and set cookie
+  const useHostPrefix = cookieName.startsWith('__Host-')
+  const serializedCookie = serializeCookie(cookieName, sid, {
+    path: '/',
+    domain: useHostPrefix ? undefined : cookie.domain,
+    secure: useHostPrefix ? true : isSecure,
+    httpOnly: cookie.httpOnly ?? true,
+    sameSite: (cookie.sameSite ?? 'lax'),
+  })
+
+  const cookieJar = (c.get('sessionCookies') as string[] | undefined) ?? []
+  cookieJar.push(serializedCookie)
+  c.set('sessionCookies', cookieJar)
+
+  c.set('sessionId', sid)
+  c.set('sessionData', dataWithFingerprint)
+
+  return sid
+}
+
+/**
+ * Destroy session: removes from KV and clears cookie
+ */
+export async function destroySession(c: Context, opts?: SessionOptions): Promise<void> {
+  const isSecure = new URL(c.req.url).protocol === 'https:'
+
+  const {
+    cookieName = isSecure ? '__Host-sid' : 'sid',
+    keyPrefix = 'sid:',
+    cookie = {},
+  } = opts ?? {}
+
+  const sid = (c.get('sessionId') as string | undefined) ?? getCookie(c, cookieName)
+  const store = (c.env as Env).SESSIONS
+
+  if (sid && store) {
+    await store.delete(`${keyPrefix}${sid}`)
+  }
+
+  // Clear cookie
+  const useHostPrefix = cookieName.startsWith('__Host-')
+  const serializedCookie = serializeCookie(cookieName, '', {
+    path: '/',
+    domain: useHostPrefix ? undefined : cookie.domain,
+    secure: useHostPrefix ? true : isSecure,
+    httpOnly: cookie.httpOnly ?? true,
+    expires: new Date(0),
+    sameSite: (cookie.sameSite ?? 'lax'),
+  })
+
+  const cookieJar = (c.get('sessionCookies') as string[] | undefined) ?? []
+  cookieJar.push(serializedCookie)
+  c.set('sessionCookies', cookieJar)
+
+  c.set('sessionId', undefined)
+  c.set('sessionData', undefined)
+}
+
+/**
+ * Get current session data from context
+ */
+export function getSession(c: Context): SessionData | null {
+  return (c.get('sessionData') as SessionData | undefined) ?? null
+}
+
+/**
+ * Check if user is authenticated (has valid session)
+ */
+export function isAuthenticated(c: Context): boolean {
+  return !!c.get('sessionData')
+}

package/templates/base/src/server/lib/tokens.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  createAccessToken,
+  generateRefreshToken,
+  hashToken,
+  verifyToken,
+  getRefreshTokenExpiry,
+  setCookieOptions,
+  setOAuthStateCookieOptions,
+} from './tokens'
+
+const mockEnv = {
+  JWT_SECRET: 'test-secret-key',
+  JWT_EXPIRY_MINUTES: '15',
+  REFRESH_TOKEN_EXPIRY_DAYS: '30',
+} as any
+
+describe('tokens', () => {
+  describe('createAccessToken', () => {
+    it('should create valid JWT token', async () => {
+      const token = await createAccessToken(mockEnv, 'user-123', 'test@example.com')
+
+      expect(token).toBeDefined()
+      expect(typeof token).toBe('string')
+      // JWT tokens have 3 parts separated by dots
+      const parts = token.split('.')
+      expect(parts).toHaveLength(3)
+    })
+
+    it('should include userId and email in payload', async () => {
+      const userId = 'user-123'
+      const email = 'test@example.com'
+      const token = await createAccessToken(mockEnv, userId, email)
+
+      // Decode the payload (second part of JWT)
+      const payloadBase64 = token.split('.')[1]
+      const payload = JSON.parse(atob(payloadBase64))
+
+      expect(payload.sub).toBe(userId)
+      expect(payload.email).toBe(email)
+      expect(payload.iat).toBeDefined()
+      expect(payload.exp).toBeDefined()
+      // Expiry should be 15 minutes (900 seconds) after iat
+      expect(payload.exp - payload.iat).toBe(15 * 60)
+    })
+  })
+
+  describe('generateRefreshToken', () => {
+    it('should generate 64-character hex string', () => {
+      const token = generateRefreshToken()
+
+      expect(token).toHaveLength(64)
+      // Should be valid hexadecimal
+      expect(token).toMatch(/^[0-9a-f]{64}$/)
+    })
+
+    it('should generate unique tokens', () => {
+      const tokens = new Set<string>()
+      const iterations = 100
+
+      for (let i = 0; i < iterations; i++) {
+        tokens.add(generateRefreshToken())
+      }
+
+      // All tokens should be unique
+      expect(tokens.size).toBe(iterations)
+    })
+  })
+
+  describe('hashToken', () => {
+    it('should hash token using SHA-256', async () => {
+      const token = 'test-token-123'
+      const hash = await hashToken(token)
+
+      // SHA-256 produces 64-character hex string (256 bits = 32 bytes = 64 hex chars)
+      expect(hash).toHaveLength(64)
+      expect(hash).toMatch(/^[0-9a-f]{64}$/)
+    })
+
+    it('should produce consistent hash for same input', async () => {
+      const token = 'consistent-token'
+
+      const hash1 = await hashToken(token)
+      const hash2 = await hashToken(token)
+
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should produce different hashes for different inputs', async () => {
+      const token1 = 'token-one'
+      const token2 = 'token-two'
+
+      const hash1 = await hashToken(token1)
+      const hash2 = await hashToken(token2)
+
+      expect(hash1).not.toBe(hash2)
+    })
+  })
+
+  describe('verifyToken', () => {
+    it('should return true for matching token and hash', async () => {
+      const originalToken = 'my-secret-token'
+      const hashedToken = await hashToken(originalToken)
+
+      const isValid = await verifyToken(originalToken, hashedToken)
+
+      expect(isValid).toBe(true)
+    })
+
+    it('should return false for non-matching token', async () => {
+      const originalToken = 'my-secret-token'
+      const hashedToken = await hashToken(originalToken)
+
+      const isValid = await verifyToken('wrong-token', hashedToken)
+
+      expect(isValid).toBe(false)
+    })
+
+    it('should be case-sensitive', async () => {
+      const token = 'CaseSensitiveToken'
+      const hash = await hashToken(token)
+
+      expect(await verifyToken('CaseSensitiveToken', hash)).toBe(true)
+      expect(await verifyToken('casesensitivetoken', hash)).toBe(false)
+    })
+  })
+
+  describe('getRefreshTokenExpiry', () => {
+    it('should return date 30 days in future (default)', () => {
+      const now = new Date()
+      const expiry = getRefreshTokenExpiry(mockEnv)
+
+      // Calculate expected date (30 days from now)
+      const expectedDate = new Date(now)
+      expectedDate.setDate(expectedDate.getDate() + 30)
+
+      // Allow 1 second tolerance for test execution time
+      const diffMs = Math.abs(expiry.getTime() - expectedDate.getTime())
+      expect(diffMs).toBeLessThan(1000)
+    })
+
+    it('should respect custom expiry days from env', () => {
+      const customEnv = { ...mockEnv, REFRESH_TOKEN_EXPIRY_DAYS: '7' }
+      const now = new Date()
+      const expiry = getRefreshTokenExpiry(customEnv)
+
+      const expectedDate = new Date(now)
+      expectedDate.setDate(expectedDate.getDate() + 7)
+
+      const diffMs = Math.abs(expiry.getTime() - expectedDate.getTime())
+      expect(diffMs).toBeLessThan(1000)
+    })
+  })
+
+  describe('setCookieOptions', () => {
+    it('should return httpOnly and secure options', () => {
+      const options = setCookieOptions(mockEnv, true)
+
+      expect(options.httpOnly).toBe(true)
+      expect(options.secure).toBe(true)
+      expect(options.sameSite).toBe('Lax')
+      expect(options.path).toBe('/')
+      expect(options.maxAge).toBeDefined()
+    })
+
+    it('should set secure based on isProduction', () => {
+      const prodOptions = setCookieOptions(mockEnv, true)
+      const devOptions = setCookieOptions(mockEnv, false)
+
+      expect(prodOptions.secure).toBe(true)
+      expect(devOptions.secure).toBe(false)
+    })
+
+    it('should set maxAge based on REFRESH_TOKEN_EXPIRY_DAYS', () => {
+      const options = setCookieOptions(mockEnv, true)
+
+      // 30 days in seconds
+      const expectedMaxAge = 30 * 24 * 60 * 60
+      expect(options.maxAge).toBe(expectedMaxAge)
+    })
+  })
+
+  describe('setOAuthStateCookieOptions', () => {
+    it('should set 10 minute maxAge', () => {
+      const options = setOAuthStateCookieOptions(true)
+
+      // 10 minutes in seconds
+      expect(options.maxAge).toBe(10 * 60)
+    })
+
+    it('should return standard cookie options', () => {
+      const options = setOAuthStateCookieOptions(true)
+
+      expect(options.httpOnly).toBe(true)
+      expect(options.secure).toBe(true)
+      expect(options.sameSite).toBe('Lax')
+      expect(options.path).toBe('/')
+    })
+
+    it('should set secure based on isProduction', () => {
+      const prodOptions = setOAuthStateCookieOptions(true)
+      const devOptions = setOAuthStateCookieOptions(false)
+
+      expect(prodOptions.secure).toBe(true)
+      expect(devOptions.secure).toBe(false)
+    })
+  })
+})

package/templates/base/src/server/lib/tokens.ts

@@ -0,0 +1,65 @@
+// src/lib/tokens.ts
+import { sign } from 'hono/jwt'
+import type { Env } from '../env'
+
+export async function createAccessToken(env: Env, userId: string, email: string): Promise<string> {
+  const now = Math.floor(Date.now() / 1000)
+  const expiryMinutes = Number.parseInt(env.JWT_EXPIRY_MINUTES || '15', 10)
+  const payload = {
+    sub: userId,
+    email,
+    iat: now,
+    exp: now + expiryMinutes * 60,
+  }
+  return sign(payload, env.JWT_SECRET)
+}
+
+export function generateRefreshToken(): string {
+  const array = new Uint8Array(32)
+  crypto.getRandomValues(array)
+  return [...array]
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+export async function hashToken(token: string): Promise<string> {
+  const encoder = new TextEncoder()
+  const data = encoder.encode(token)
+  const hash = await crypto.subtle.digest('SHA-256', data)
+  return [...new Uint8Array(hash)]
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+export async function verifyToken(token: string, hash: string): Promise<boolean> {
+  const computedHash = await hashToken(token)
+  return computedHash === hash
+}
+
+export function getRefreshTokenExpiry(env: Env): Date {
+  const expiryDays = Number.parseInt(env.REFRESH_TOKEN_EXPIRY_DAYS || '30', 10)
+  const now = new Date()
+  now.setDate(now.getDate() + expiryDays)
+  return now
+}
+
+export function setCookieOptions(env: Env, isProduction: boolean) {
+  const expiryDays = Number.parseInt(env.REFRESH_TOKEN_EXPIRY_DAYS || '30', 10)
+  return {
+    httpOnly: true,
+    secure: isProduction,
+    sameSite: 'Lax' as const,
+    path: '/',
+    maxAge: expiryDays * 24 * 60 * 60,
+  }
+}
+
+export function setOAuthStateCookieOptions(isProduction: boolean) {
+  return {
+    httpOnly: true,
+    secure: isProduction,
+    sameSite: 'Lax' as const,
+    path: '/',
+    maxAge: 10 * 60, // 10 minutes
+  }
+}

package/templates/base/src/server/lib/transaction.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi } from 'vitest'
+import { withTransaction } from './transaction'
+
+describe('withTransaction', () => {
+  it('returns result from successful callback', async () => {
+    const mockTx = { insert: vi.fn(), update: vi.fn() }
+    const mockDb = {
+      transaction: vi.fn(async (cb) => cb(mockTx)),
+    }
+
+    const result = await withTransaction(mockDb as any, async (tx) => {
+      return { id: '123', name: 'Test' }
+    })
+
+    expect(result).toEqual({ id: '123', name: 'Test' })
+    expect(mockDb.transaction).toHaveBeenCalledTimes(1)
+  })
+
+  it('propagates errors from callback', async () => {
+    const mockDb = {
+      transaction: vi.fn(async (cb) => cb({})),
+    }
+
+    await expect(
+      withTransaction(mockDb as any, async () => {
+        throw new Error('Database error')
+      })
+    ).rejects.toThrow('Database error')
+  })
+
+  it('passes transaction to callback', async () => {
+    const mockTx = { insert: vi.fn(), update: vi.fn() }
+    const mockDb = {
+      transaction: vi.fn(async (cb) => cb(mockTx)),
+    }
+
+    let receivedTx: any
+    await withTransaction(mockDb as any, async (tx) => {
+      receivedTx = tx
+      return null
+    })
+
+    expect(receivedTx).toBe(mockTx)
+  })
+})

package/templates/base/src/server/lib/transaction.ts

@@ -0,0 +1,24 @@
+import type { Database } from '../db/client'
+
+type Transaction = Parameters<Parameters<Database['transaction']>[0]>[0]
+
+/**
+ * Execute a callback within a database transaction.
+ * - Callback succeeds → automatic commit
+ * - Callback throws → automatic rollback
+ *
+ * @example
+ * const result = await withTransaction(db, async (tx) => {
+ *   const [account] = await tx.insert(accounts).values({ name: 'Acme' }).returning()
+ *   const [user] = await tx.insert(users).values({ email: 'admin@acme.com' }).returning()
+ *   return { account, user }
+ * })
+ */
+export async function withTransaction<T>(
+  db: Database,
+  callback: (tx: Transaction) => Promise<T>
+): Promise<T> {
+  return db.transaction(callback)
+}
+
+export type { Transaction }