@etus/bhono-app 0.1.1

package/templates/base/src/server/env.ts

@@ -0,0 +1,78 @@
+// src/server/env.ts
+export interface Env {
+  // D1 Database (may be undefined in test environments)
+  DB?: D1Database
+
+  // KV Sessions (may be undefined in test environments)
+  SESSIONS?: KVNamespace
+
+  // Static Assets (may be undefined in test environments)
+  ASSETS?: Fetcher
+
+  // R2 Storage (may be undefined in test environments)
+  R2_BUCKET?: R2Bucket
+  R2_PUBLIC_URL?: string
+
+  // Environment
+  ENVIRONMENT: string
+
+  // App URL
+  APP_URL: string
+
+  // JWT
+  JWT_SECRET: string
+  JWT_EXPIRY_MINUTES: string
+
+  // Google OAuth
+  GOOGLE_CLIENT_ID: string
+  GOOGLE_CLIENT_SECRET: string
+  GOOGLE_REDIRECT_URI: string
+
+  // Refresh Token
+  REFRESH_TOKEN_EXPIRY_DAYS: string
+
+  // SendGrid
+  SENDGRID_API_KEY: string
+  SENDGRID_FROM_EMAIL: string
+
+  // CORS
+  CORS_ORIGINS?: string
+
+  // Super Admin emails (comma-separated)
+  SUPER_ADMIN_EMAILS?: string
+}
+
+// Helper to get env with defaults
+export function getEnv(env: Env) {
+  return {
+    ...env,
+    JWT_EXPIRY_MINUTES: Number.parseInt(env.JWT_EXPIRY_MINUTES || '15', 10),
+    REFRESH_TOKEN_EXPIRY_DAYS: Number.parseInt(env.REFRESH_TOKEN_EXPIRY_DAYS || '30', 10),
+    CORS_ORIGINS_LIST: env.CORS_ORIGINS
+      ? env.CORS_ORIGINS.split(',').map((o) => o.trim())
+      : [],
+    SUPER_ADMIN_EMAILS_LIST: env.SUPER_ADMIN_EMAILS
+      ? env.SUPER_ADMIN_EMAILS.split(',').map((e) => e.trim().toLowerCase())
+      : [],
+  }
+}
+
+// Check if email is a super admin
+export function isSuperAdminEmail(env: Env, email: string): boolean {
+  const { SUPER_ADMIN_EMAILS_LIST } = getEnv(env)
+  return SUPER_ADMIN_EMAILS_LIST.includes(email.toLowerCase())
+}
+
+// Minimum required length for JWT_SECRET (security requirement)
+export const JWT_SECRET_MIN_LENGTH = 32
+
+/**
+ * Validate environment variables at startup
+ * Throws an error if validation fails
+ */
+export function validateEnv(env: Env): void {
+  // JWT_SECRET must be at least 32 characters for security
+  if (!env.JWT_SECRET || env.JWT_SECRET.length < JWT_SECRET_MIN_LENGTH) {
+    throw new Error(`JWT_SECRET must be at least ${String(JWT_SECRET_MIN_LENGTH)} characters`)
+  }
+}

package/templates/base/src/server/index.ts

@@ -0,0 +1,82 @@
+// src/server/index.ts
+import { Hono } from 'hono'
+import { secureHeaders } from 'hono/secure-headers'
+import type { HonoEnv } from './types'
+import { createDb } from './db/client'
+import { auth } from './routes/auth'
+import { api } from './routes'
+import { health } from './routes/health'
+import {
+  errorHandler,
+  requestLogger,
+  configurableCors,
+  requestContext,
+  rateLimit,
+  authRateLimit,
+} from './middleware'
+import { sessionMiddleware } from './lib/session'
+import { validateEnv } from './env'
+
+// Hono app with bindings and variables
+const app = new Hono<HonoEnv>()
+
+// 1. Global error handler
+app.onError(errorHandler)
+
+// 2. Request context (transactionId, IP, userAgent) - must be first for logging
+app.use('*', requestContext)
+
+// 3. Environment validation - fail fast if misconfigured
+app.use('*', async (c, next) => {
+  validateEnv(c.env)
+  await next()
+})
+
+// 4. Request logger (uses transactionId from context)
+app.use('*', requestLogger())
+
+// 5. Configurable CORS
+app.use('*', async (c, next) => {
+  const env = c.env
+  const corsOrigins = env.CORS_ORIGINS
+    ? env.CORS_ORIGINS.split(',').map((o) => o.trim())
+    : []
+  return configurableCors({
+    corsOrigins,
+    appUrl: env.APP_URL,
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- Hono wildcard route typing
+  })(c, next)
+})
+
+// 6. Security headers
+app.use('*', secureHeaders())
+
+// 7. Rate limiting - global limit of 100 requests per minute
+app.use('*', rateLimit())
+
+// 8. Stricter rate limiting for auth endpoints (10 requests per minute)
+app.use('/auth/*', authRateLimit())
+
+// 9. Database middleware - create db instance per request
+app.use('*', async (c, next) => {
+  if (c.env.DB) {
+    const db = createDb(c.env.DB)
+    c.set('db', db)
+  }
+  await next()
+})
+
+// 10. Session middleware - read session from KV
+app.use('*', sessionMiddleware())
+
+// Mount routes
+// Health checks (no auth required) - must be before /api
+app.route('/health', health)
+
+// Auth routes
+app.route('/auth', auth)
+
+// API routes (with auth)
+app.route('/api', api)
+
+export default app

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

@@ -0,0 +1,73 @@
+import type { Database } from '../db/client'
+import { auditLogs } from '../db/schema'
+import type { ServiceContext } from '../types'
+
+export type AuditAction = 'INSERT' | 'UPDATE' | 'DELETE' | 'LOGIN' | 'LOGOUT' | 'SIGNUP' | 'TOKEN_REFRESH' | 'LOGIN_FAILED'
+
+export async function logAudit(
+  db: Database,
+  ctx: ServiceContext,
+  entity: string,
+  entityId: string,
+  action: AuditAction,
+  changes: Record<string, unknown>
+): Promise<void> {
+  await db.insert(auditLogs).values({
+    transactionId: ctx.transactionId ?? crypto.randomUUID(),
+    accountId: ctx.accountId,
+    userId: ctx.user.id,
+    entity,
+    entityId,
+    action,
+    changes,
+    ipAddress: ctx.ip ?? null,
+    userAgent: ctx.userAgent ?? null,
+  })
+}
+
+export function createChangeDiff(
+  oldData: Record<string, unknown>,
+  newData: Record<string, unknown>
+): Record<string, { old: unknown; new: unknown }> {
+  const changes: Record<string, { old: unknown; new: unknown }> = {}
+
+  for (const key of Object.keys(newData)) {
+    if (oldData[key] !== newData[key]) {
+      changes[key] = {
+        old: oldData[key],
+        new: newData[key],
+      }
+    }
+  }
+
+  return changes
+}
+
+// Auth event context - doesn't require full ServiceContext
+export interface AuthEventContext {
+  transactionId?: string
+  ip?: string
+  userAgent?: string
+}
+
+export type AuthAction = 'LOGIN' | 'LOGOUT' | 'SIGNUP' | 'TOKEN_REFRESH' | 'LOGIN_FAILED'
+
+export async function logAuthEvent(
+  db: Database,
+  ctx: AuthEventContext,
+  action: AuthAction,
+  userId: string | null,
+  details: Record<string, unknown>
+): Promise<void> {
+  await db.insert(auditLogs).values({
+    transactionId: ctx.transactionId ?? crypto.randomUUID(),
+    accountId: null, // Auth events are account-agnostic
+    userId,
+    entity: 'Auth',
+    entityId: userId ?? 'anonymous',
+    action,
+    changes: details,
+    ipAddress: ctx.ip ?? null,
+    userAgent: ctx.userAgent ?? null,
+  })
+}

package/templates/base/src/server/lib/audited-db.test.ts

@@ -0,0 +1,107 @@
+// src/server/lib/audited-db.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { auditedInsert, auditedUpdate, auditedDelete } from './audited-db'
+import type { ServiceContext } from '../types'
+
+// Mock database and table
+const mockDb = {
+  insert: vi.fn(),
+  update: vi.fn(),
+  delete: vi.fn(),
+  select: vi.fn(),
+}
+
+const mockTable = {
+  _: { name: 'users' },
+} as any
+
+const mockCtx: ServiceContext = {
+  accountId: 'account-123',
+  user: {
+    id: 'user-123',
+    email: 'test@example.com',
+    name: 'Test User',
+    status: 'active',
+    providerIds: [],
+    isSuperAdmin: false,
+    createdAt: '2024-01-01',
+    updatedAt: '2024-01-01',
+    deletedAt: null,
+  },
+  transactionId: 'tx-123',
+  ip: '127.0.0.1',
+  userAgent: 'test-agent',
+}
+
+describe('audited-db', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('auditedInsert', () => {
+    it('should insert data and return result', async () => {
+      const insertedData = { id: 'new-123', name: 'Test' }
+      const mockReturning = vi.fn().mockResolvedValue([insertedData])
+      const mockValues = vi.fn().mockReturnValue({ returning: mockReturning })
+      mockDb.insert.mockReturnValue({ values: mockValues })
+
+      const result = await auditedInsert(mockDb as any, mockCtx, mockTable, { name: 'Test' })
+
+      expect(result).toEqual([insertedData])
+      expect(mockDb.insert).toHaveBeenCalledWith(mockTable)
+    })
+
+    it('should log audit after insert', async () => {
+      const insertedData = { id: 'new-123', name: 'Test' }
+      const mockReturning = vi.fn().mockResolvedValue([insertedData])
+      const mockValues = vi.fn().mockReturnValue({ returning: mockReturning })
+      mockDb.insert.mockReturnValue({ values: mockValues })
+
+      await auditedInsert(mockDb as any, mockCtx, mockTable, { name: 'Test' })
+
+      // Verify insert was called (audit logging happens internally)
+      expect(mockDb.insert).toHaveBeenCalled()
+    })
+  })
+
+  describe('auditedUpdate', () => {
+    it('should update data and return result', async () => {
+      const updatedData = { id: 'existing-123', name: 'Updated' }
+      const mockReturning = vi.fn().mockResolvedValue([updatedData])
+      const mockWhere = vi.fn().mockReturnValue({ returning: mockReturning })
+      const mockSet = vi.fn().mockReturnValue({ where: mockWhere })
+      mockDb.update.mockReturnValue({ set: mockSet })
+
+      // Mock select for getting old data
+      const mockLimit = vi.fn().mockResolvedValue([{ id: 'existing-123', name: 'Old' }])
+      const mockSelectWhere = vi.fn().mockReturnValue({ limit: mockLimit })
+      const mockFrom = vi.fn().mockReturnValue({ where: mockSelectWhere })
+      mockDb.select.mockReturnValue({ from: mockFrom })
+
+      const whereClause = {} as any
+      const result = await auditedUpdate(
+        mockDb as any,
+        mockCtx,
+        mockTable,
+        { name: 'Updated' },
+        whereClause
+      )
+
+      expect(result).toEqual([updatedData])
+    })
+  })
+
+  describe('auditedDelete', () => {
+    it('should soft delete and return void', async () => {
+      const mockReturning = vi.fn().mockResolvedValue([{ id: 'deleted-123' }])
+      const mockWhere = vi.fn().mockReturnValue({ returning: mockReturning })
+      const mockSet = vi.fn().mockReturnValue({ where: mockWhere })
+      mockDb.update.mockReturnValue({ set: mockSet })
+
+      const whereClause = {} as any
+      await auditedDelete(mockDb as any, mockCtx, mockTable, whereClause)
+
+      expect(mockDb.update).toHaveBeenCalledWith(mockTable)
+    })
+  })
+})

package/templates/base/src/server/lib/audited-db.ts

@@ -0,0 +1,154 @@
+// src/server/lib/audited-db.ts
+import { type SQL, getTableName as drizzleGetTableName, is, Table } from 'drizzle-orm'
+import type { SQLiteTable } from 'drizzle-orm/sqlite-core'
+import type { Database } from '../db/client'
+import type { ServiceContext } from '../types'
+import { logAudit, createChangeDiff } from './audit'
+
+/**
+ * Base interface for auditable records - requires an id field
+ */
+interface AuditableRecord {
+  id: string
+}
+
+/**
+ * Get the table name from a Drizzle table definition
+ */
+function getTableName(table: SQLiteTable): string {
+  if (is(table, Table)) {
+    return drizzleGetTableName(table)
+  }
+  return 'unknown'
+}
+
+/**
+ * Insert with automatic audit logging
+ * Returns the inserted records (same as .returning())
+ */
+export async function auditedInsert<TRecord extends AuditableRecord>(
+  db: Database,
+  ctx: ServiceContext,
+  table: SQLiteTable,
+  values: Record<string, unknown> | Record<string, unknown>[]
+): Promise<TRecord[]> {
+  const tableName = getTableName(table)
+  const valuesArray = Array.isArray(values) ? values : [values]
+
+  const results = await db
+    .insert(table)
+    .values(valuesArray)
+    .returning()
+
+  // Log audit for each inserted record
+  for (const record of results) {
+    const typedRecord = record as unknown as TRecord
+    await logAudit(
+      db,
+      ctx,
+      tableName,
+      typedRecord.id,
+      'INSERT',
+      record as Record<string, unknown>
+    )
+  }
+
+  return results as unknown as TRecord[]
+}
+
+/**
+ * Update with automatic audit logging (includes diff of changes)
+ * Returns the updated records (same as .returning())
+ */
+export async function auditedUpdate<TRecord extends AuditableRecord>(
+  db: Database,
+  ctx: ServiceContext,
+  table: SQLiteTable,
+  values: Record<string, unknown>,
+  where: SQL
+): Promise<TRecord[]> {
+  const tableName = getTableName(table)
+
+  // Get old data first for diff
+  const oldRecords = await db
+    .select()
+    .from(table)
+    .where(where)
+    .limit(100) // Safety limit
+
+  const results = await db
+    .update(table)
+    .set(values)
+    .where(where)
+    .returning()
+
+  // Log audit for each updated record with diff
+  for (let i = 0; i < results.length; i++) {
+    const oldData = (oldRecords[i] ?? {}) as Record<string, unknown>
+    const newData = results[i] as unknown as TRecord
+    const diff = createChangeDiff(
+      oldData,
+      newData as Record<string, unknown>
+    )
+
+    await logAudit(
+      db,
+      ctx,
+      tableName,
+      newData.id,
+      'UPDATE',
+      diff
+    )
+  }
+
+  return results as unknown as TRecord[]
+}
+
+/**
+ * Interface for soft-deletable tables with required audit fields
+ */
+interface SoftDeletableFields {
+  deletedAt: string | null
+  deletedById: string | null
+  updatedAt: string
+  updatedById: string | null
+}
+
+/**
+ * Soft delete with automatic audit logging
+ * Sets deletedAt and deletedById fields
+ */
+export async function auditedDelete(
+  db: Database,
+  ctx: ServiceContext,
+  table: SQLiteTable,
+  where: SQL
+): Promise<void> {
+  const tableName = getTableName(table)
+
+  const softDeleteValues: SoftDeletableFields = {
+    deletedAt: new Date().toISOString(),
+    deletedById: ctx.user.id,
+    updatedAt: new Date().toISOString(),
+    updatedById: ctx.user.id,
+  }
+
+  const results = await db
+    .update(table)
+    .set(softDeleteValues)
+    .where(where)
+    .returning()
+
+  // Log audit for each deleted record
+  for (const record of results) {
+    const typedRecord = record as unknown as AuditableRecord
+    await logAudit(
+      db,
+      ctx,
+      tableName,
+      typedRecord.id,
+      'DELETE',
+      { deleted: true }
+    )
+  }
+}

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

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { sendInvitationEmail } from './email'
+
+const mockFetch = vi.fn()
+vi.stubGlobal('fetch', mockFetch)
+
+const mockEnv = {
+  SENDGRID_API_KEY: 'test-api-key',
+  SENDGRID_FROM_EMAIL: 'noreply@test.com',
+} as any
+
+describe('email library', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('sendInvitationEmail', () => {
+    const testData = {
+      to: 'recipient@example.com',
+      inviterName: 'John Doe',
+      accountName: 'Acme Corp',
+      inviteUrl: 'https://example.com/invite/abc123',
+    }
+
+    it('should call SendGrid API with correct payload', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true })
+
+      await sendInvitationEmail(
+        mockEnv,
+        testData.to,
+        testData.inviterName,
+        testData.accountName,
+        testData.inviteUrl
+      )
+
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.sendgrid.com/v3/mail/send',
+        expect.objectContaining({
+          method: 'POST',
+          headers: {
+            'Authorization': 'Bearer test-api-key',
+            'Content-Type': 'application/json',
+          },
+        })
+      )
+
+      const callArgs = mockFetch.mock.calls[0]
+      const body = JSON.parse(callArgs[1].body)
+
+      expect(body.personalizations).toEqual([{ to: [{ email: testData.to }] }])
+      expect(body.from).toEqual({ email: 'noreply@test.com' })
+      expect(body.content).toHaveLength(2)
+      expect(body.content[0].type).toBe('text/plain')
+      expect(body.content[1].type).toBe('text/html')
+    })
+
+    it('should include correct subject with inviter and account name', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true })
+
+      await sendInvitationEmail(
+        mockEnv,
+        testData.to,
+        testData.inviterName,
+        testData.accountName,
+        testData.inviteUrl
+      )
+
+      const callArgs = mockFetch.mock.calls[0]
+      const body = JSON.parse(callArgs[1].body)
+
+      expect(body.subject).toBe(`${testData.inviterName} invited you to join "${testData.accountName}"`)
+    })
+
+    it('should include invite URL in email body', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true })
+
+      await sendInvitationEmail(
+        mockEnv,
+        testData.to,
+        testData.inviterName,
+        testData.accountName,
+        testData.inviteUrl
+      )
+
+      const callArgs = mockFetch.mock.calls[0]
+      const body = JSON.parse(callArgs[1].body)
+
+      // Check text content contains the invite URL
+      const textContent = body.content.find((c: any) => c.type === 'text/plain')
+      expect(textContent.value).toContain(testData.inviteUrl)
+
+      // Check HTML content contains the invite URL
+      const htmlContent = body.content.find((c: any) => c.type === 'text/html')
+      expect(htmlContent.value).toContain(testData.inviteUrl)
+      expect(htmlContent.value).toContain(`href="${testData.inviteUrl}"`)
+    })
+
+    it('should throw error when API call fails', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        text: () => Promise.resolve('Unauthorized'),
+      })
+
+      await expect(
+        sendInvitationEmail(
+          mockEnv,
+          testData.to,
+          testData.inviterName,
+          testData.accountName,
+          testData.inviteUrl
+        )
+      ).rejects.toThrow('Failed to send email: Unauthorized')
+    })
+  })
+})

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

@@ -0,0 +1,82 @@
+// src/lib/email.ts
+import type { Env } from '../env'
+
+interface SendEmailOptions {
+  to: string
+  subject: string
+  text: string
+  html: string
+}
+
+async function sendEmail(env: Env, options: SendEmailOptions): Promise<void> {
+  const response = await fetch('https://api.sendgrid.com/v3/mail/send', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${env.SENDGRID_API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      personalizations: [{ to: [{ email: options.to }] }],
+      from: { email: env.SENDGRID_FROM_EMAIL },
+      subject: options.subject,
+      content: [
+        { type: 'text/plain', value: options.text },
+        { type: 'text/html', value: options.html },
+      ],
+    }),
+  })
+
+  if (!response.ok) {
+    const error = await response.text()
+    throw new Error(`Failed to send email: ${error}`)
+  }
+}
+
+export async function sendInvitationEmail(
+  env: Env,
+  to: string,
+  inviterName: string,
+  accountName: string,
+  inviteUrl: string
+): Promise<void> {
+  const subject = `${inviterName} invited you to join "${accountName}"`
+
+  const text = `
+Hi,
+
+${inviterName} has invited you to join "${accountName}".
+
+Click the link below to accept the invitation:
+${inviteUrl}
+
+This invitation expires in 7 days.
+
+If you didn't expect this invitation, you can ignore this email.
+`.trim()
+
+  const html = `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.6; color: #333; }
+    .container { max-width: 600px; margin: 0 auto; padding: 20px; }
+    .button { display: inline-block; padding: 12px 24px; background-color: #0070f3; color: white; text-decoration: none; border-radius: 6px; margin: 20px 0; }
+    .footer { margin-top: 30px; font-size: 14px; color: #666; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <p>Hi,</p>
+    <p><strong>${inviterName}</strong> has invited you to join <strong>"${accountName}"</strong>.</p>
+    <a href="${inviteUrl}" class="button">Accept Invitation</a>
+    <p>Or copy this link: ${inviteUrl}</p>
+    <p class="footer">This invitation expires in 7 days.<br>If you didn't expect this invitation, you can ignore this email.</p>
+  </div>
+</body>
+</html>
+`.trim()
+
+  await sendEmail(env, { to, subject, text, html })
+}