@beechcms/api 0.4.0-preview.1

package/src/index.ts

@@ -0,0 +1,344 @@
+/// <reference types="@cloudflare/workers-types" />
+import { Hono } from 'hono'
+import type { Context } from 'hono'
+import { getCookie, setCookie, deleteCookie } from 'hono/cookie'
+import { createBeechApp } from './factory'
+import { SEED_REGISTRY } from '@beechcms/core'
+import { AUTH_ERRORS } from './auth/constants'
+import {
+  parseLoginBody,
+  validateLoginInput,
+  findUserByEmail,
+  verifyPassword,
+  DUMMY_PASSWORD_HASH,
+} from './auth/login'
+import {
+  generateRefreshToken,
+  saveRefreshToken,
+  generateAccessToken,
+  validateRefreshToken,
+  revokeRefreshToken,
+} from './auth/refresh'
+import { authMiddleware } from './middleware'
+import { contentRoutes } from './content'
+import { widgetApp } from './widget'
+// TODO: refactor — rotate-field è una VSA slice. Il resto di index.ts (auth inline, content monolith)
+// va migrato a slices dedicati sotto src/features/ seguendo lo stesso pattern.
+import { rotateFieldApp } from './features/rotate-field'
+import { passwordResetApp } from './features/password-reset'
+import { setupApp } from './features/setup'
+import { draftApp } from './features/draft'
+import { settingsApp } from './features/settings/settings.handler'
+import { notificationsApp } from './features/notifications'
+import { statsApp } from './features/stats'
+import { uploadRoutes, serveMediaHandler } from './upload'
+import { publicRoutes, apiKeyMiddleware, publicRateLimitMiddleware } from './public'
+import { searchRouter } from "./search"
+import type { Env, Variables } from './types'
+
+// --- Costanti e helper ---
+
+/** Giorni di validità del refresh token */
+const REFRESH_TOKEN_EXPIRY_DAYS = 7
+
+/** Secondi in un giorno (per maxAge cookie) */
+const SECONDS_PER_DAY = 24 * 60 * 60
+
+/** Restituisce true se la richiesta è su HTTPS */
+function isRequestSecure(url: string): boolean {
+  return new URL(url).protocol === 'https:'
+}
+
+/** Estrae l'IP del client (header Cloudflare) o 'unknown' se non disponibile */
+function getClientIp(headers: Headers): string {
+  return headers.get('cf-connecting-ip') ?? 'unknown'
+}
+
+/** Opzioni comuni per il cookie refresh_token */
+function getRefreshTokenCookieOptions(secure: boolean) {
+  return {
+    httpOnly: true,
+    secure,
+    sameSite: 'Strict' as const,
+    maxAge: REFRESH_TOKEN_EXPIRY_DAYS * SECONDS_PER_DAY,
+    path: '/auth',
+  }
+}
+
+function getRefreshTokenDeleteCookieOptions(secure: boolean) {
+  return {
+    httpOnly: true,
+    secure,
+    sameSite: 'Strict' as const,
+    path: '/auth',
+  }
+}
+
+/** Logga l'errore solo in sviluppo e restituisce risposta 500 generica */
+function handleAuthError(
+  c: Context<{ Bindings: Env; Variables: Variables }>,
+  err: unknown,
+  operationName: string
+): Response {
+  if (c.env.ENV !== 'production') {
+    console.error(`${operationName} error:`, err)
+  }
+  return c.json({ error: AUTH_ERRORS.GENERIC_ERROR }, 500)
+}
+
+// --- App ---
+
+const app = createBeechApp({ seeds: Object.values(SEED_REGISTRY) })
+
+// Rota root di test
+app.get('/', (c) => c.text('Beech API is running!'))
+
+/** Estrae il seed slug dalle route pubbliche (/api/v1/public/:seed).
+ *  Restituisce '' per tutte le altre route (metrica globale). */
+function extractPublicSeed(path: string): string {
+  const match = path.match(/^\/api\/v1\/public\/([^/?]+)/)
+  return match ? match[1] : ''
+}
+
+// Middleware Analytics: traccia le richieste per la dashboard (Cloudflare-style metrics)
+app.use('/api/*', async (c, next) => {
+  await next()
+  
+  // Tracciamo solo richieste andate a buon fine (2xx) e non OPTIONS
+  if (c.req.method !== 'OPTIONS' && c.res.status >= 200 && c.res.status < 300) {
+    const db = c.env.DB
+    // Protezione per ambienti (es. test) dove executionCtx non è definito
+    let executionCtx: { waitUntil: (p: Promise<any>) => void } | undefined
+    try {
+      executionCtx = c.executionCtx
+    } catch {
+      // In ambiente di test Hono lancia se non presente
+    }
+
+    if (db && executionCtx) {
+      // Usa waitUntil per non bloccare la risposta al client
+      const seed = extractPublicSeed(c.req.path)
+      executionCtx.waitUntil((async () => {
+        try {
+          const today = Math.floor(new Date().setHours(0, 0, 0, 0) / 1000)
+
+          // Incrementa contatore richieste: seed='' per route interne, seed='articoli' per public API
+          await db.prepare(
+            `INSERT INTO analytics (day_ts, metric, seed, value)
+             VALUES (?, 'requests', ?, 1)
+             ON CONFLICT(day_ts, metric, seed) DO UPDATE SET value = value + 1`
+          ).bind(today, seed).run()
+        } catch (err) {
+          console.error('Analytics middleware error:', err)
+        }
+      })())
+    }
+  }
+})
+
+// POST /auth/login: autenticazione con email e password + refresh token
+app.post('/auth/login', async (c) => {
+  try {
+    let body: unknown
+    try {
+      body = await c.req.json()
+    } catch {
+      return c.json({ error: AUTH_ERRORS.INVALID_REQUEST }, 400)
+    }
+
+    const credentials = parseLoginBody(body)
+    if (!credentials) {
+      return c.json({ error: AUTH_ERRORS.INVALID_REQUEST }, 400)
+    }
+
+    const { email, password } = credentials
+    if (!validateLoginInput(email, password)) {
+      return c.json({ error: AUTH_ERRORS.INVALID_REQUEST }, 400)
+    }
+
+    // Rate limiting: 5 tentativi per IP+email ogni 60 secondi
+    const loginLimiter = c.env.LOGIN_RATE_LIMITER
+    if (loginLimiter) {
+      const clientIp = getClientIp(c.req.raw.headers)
+      const { success } = await loginLimiter.limit({ key: `${clientIp}:${email}` })
+      if (!success) {
+        return c.json({ error: AUTH_ERRORS.RATE_LIMIT_EXCEEDED }, 429)
+      }
+    }
+
+    const { DB, JWT_SECRET } = c.env
+    const user = await findUserByEmail(DB, email)
+    // Sempre verifyPassword per evitare timing attack (utente non trovato vs password errata)
+    const hashToCompare = user?.password_hash ?? DUMMY_PASSWORD_HASH
+    const isValid = await verifyPassword(password, hashToCompare)
+
+    if (!user || !isValid) {
+      return c.json({ error: AUTH_ERRORS.INVALID_CREDENTIALS }, 401)
+    }
+
+    // Recupera name per includerlo nel JWT
+    const userProfile = await DB.prepare('SELECT name FROM users WHERE id = ? LIMIT 1').bind(user.id).first<{ name: string | null }>()
+
+    // Genera access token (15min) e refresh token (7 giorni)
+    const accessToken = await generateAccessToken(user.id, user.email, JWT_SECRET, {
+      issuer: c.env.JWT_ISSUER,
+      audience: c.env.JWT_AUDIENCE,
+    }, userProfile?.name ?? undefined)
+    const refreshToken = generateRefreshToken()
+
+    // Salva refresh token in DB (hashed)
+    await saveRefreshToken(DB, user.id, refreshToken, REFRESH_TOKEN_EXPIRY_DAYS)
+
+    setCookie(c, 'refresh_token', refreshToken, {
+      ...getRefreshTokenCookieOptions(isRequestSecure(c.req.url)),
+    })
+
+    // Restituisci solo access token nel body
+    return c.json({ token: accessToken, expiresIn: '15m' }, 200)
+  } catch (err) {
+    return handleAuthError(c, err, 'Login')
+  }
+})
+
+// POST /auth/refresh: ottieni nuovo access token usando refresh token
+app.post('/auth/refresh', async (c) => {
+  try {
+    // Rate limiting: 20 richieste per IP ogni 60 secondi
+    const refreshLimiter = c.env.REFRESH_RATE_LIMITER
+    if (refreshLimiter) {
+      const clientIp = getClientIp(c.req.raw.headers)
+      const { success } = await refreshLimiter.limit({ key: clientIp })
+      if (!success) {
+        return c.json({ error: AUTH_ERRORS.RATE_LIMIT_EXCEEDED }, 429)
+      }
+    }
+
+    // Leggi refresh token dal cookie usando helper Hono
+    const refreshToken = getCookie(c, 'refresh_token')
+
+    if (!refreshToken) {
+      return c.json({ error: 'Refresh token missing' }, 401)
+    }
+
+    const { DB, JWT_SECRET } = c.env
+
+    // Valida refresh token
+    const validation = await validateRefreshToken(DB, refreshToken)
+    if (!validation.valid || !validation.userId) {
+      return c.json({ error: 'Invalid refresh token' }, 401)
+    }
+
+    // Ottieni info utente per generare nuovo access token
+    const user = await DB.prepare(
+      'SELECT id, email, name FROM users WHERE id = ? LIMIT 1'
+    ).bind(validation.userId).first<{ id: string; email: string; name: string | null }>()
+
+    if (!user) {
+      return c.json({ error: 'User not found' }, 401)
+    }
+
+    // ROTAZIONE: Invalida vecchio refresh token
+    const revoked = await revokeRefreshToken(DB, refreshToken)
+    if (!revoked) {
+      // Token già consumato/revocato (race) o appena scaduto: tratta come invalido.
+      return c.json({ error: 'Invalid refresh token' }, 401)
+    }
+
+    // Genera NUOVO access token e NUOVO refresh token
+    const newAccessToken = await generateAccessToken(user.id, user.email, JWT_SECRET, {
+      issuer: c.env.JWT_ISSUER,
+      audience: c.env.JWT_AUDIENCE,
+    }, user.name ?? undefined)
+    const newRefreshToken = generateRefreshToken()
+
+    // Salva nuovo refresh token in DB
+    await saveRefreshToken(DB, user.id, newRefreshToken, REFRESH_TOKEN_EXPIRY_DAYS)
+
+    setCookie(c, 'refresh_token', newRefreshToken, {
+      ...getRefreshTokenCookieOptions(isRequestSecure(c.req.url)),
+    })
+
+    // Restituisci nuovo access token
+    return c.json({ token: newAccessToken, expiresIn: '15m' }, 200)
+  } catch (err) {
+    return handleAuthError(c, err, 'Refresh')
+  }
+})
+
+// POST /auth/logout: invalida refresh token e cancella cookie
+app.post('/auth/logout', async (c) => {
+  try {
+    // Leggi refresh token dal cookie usando helper Hono
+    const refreshToken = getCookie(c, 'refresh_token')
+
+    if (refreshToken) {
+      await revokeRefreshToken(c.env.DB, refreshToken)
+    }
+
+    deleteCookie(c, 'refresh_token', {
+      ...getRefreshTokenDeleteCookieOptions(isRequestSecure(c.req.url)),
+    })
+
+    return c.json({ message: 'Logged out' }, 200)
+  } catch (err) {
+    return handleAuthError(c, err, 'Logout')
+  }
+})
+
+// First-run setup: GET /auth/setup, POST /auth/setup (pubblici, bloccati dopo il primo utente)
+app.route('/', setupApp)
+
+// Password reset: GET /auth/features, POST /auth/forgot-password, POST /auth/reset-password (pubblici)
+app.route('/', passwordResetApp)
+
+// API Settings: gestione profilo e preferenze utente, protetto da JWT
+const apiSettings = new Hono<{ Bindings: Env; Variables: Variables }>()
+apiSettings.use('*', async (c, next) => {
+  await authMiddleware(c.env.JWT_SECRET, {
+    issuer: c.env.JWT_ISSUER,
+    audience: c.env.JWT_AUDIENCE,
+  })(c, next)
+})
+apiSettings.route('/', settingsApp)
+app.route('/api/settings', apiSettings)
+
+// API Content: CRUD universale protetto da JWT
+const apiContent = new Hono<{ Bindings: Env; Variables: Variables }>()
+apiContent.use('*', async (c, next) => {
+  await authMiddleware(c.env.JWT_SECRET, {
+    issuer: c.env.JWT_ISSUER,
+    audience: c.env.JWT_AUDIENCE,
+  })(c, next)
+})
+// Specific routes before wildcard content routes to avoid pattern conflicts
+apiContent.route('/', notificationsApp)
+apiContent.route('/', statsApp)
+apiContent.route('/', rotateFieldApp)
+apiContent.route('/', draftApp)
+apiContent.route('/', contentRoutes)
+app.route('/api/content', apiContent)
+app.route('/api/search', searchRouter)
+
+// API Widget: endpoint aggregati per i widget della dashboard, protetti da JWT
+const apiWidget = new Hono<{ Bindings: Env; Variables: Variables }>()
+apiWidget.use('*', async (c, next) => {
+  await authMiddleware(c.env.JWT_SECRET, {
+    issuer: c.env.JWT_ISSUER,
+    audience: c.env.JWT_AUDIENCE,
+  })(c, next)
+})
+apiWidget.route('/', widgetApp)
+app.route('/api/widget', apiWidget)
+
+// API Upload: POST /api/upload (JWT) + GET /api/media/:key (pubblico)
+app.route('/api', uploadRoutes)
+app.get('/api/media/:key', (c) => serveMediaHandler(c))
+
+// API Pubblica: endpoint per consumatori esterni, protetti da API Key
+const apiPublic = new Hono<{ Bindings: Env; Variables: Variables }>()
+apiPublic.use('*', publicRateLimitMiddleware())
+apiPublic.use('*', apiKeyMiddleware())
+apiPublic.route('/', publicRoutes)
+app.route('/api/v1/public', apiPublic)
+
+export default app

package/src/media-utils.ts

@@ -0,0 +1,78 @@
+/**
+ * Media utils: estrazione chiavi R2 dal data di un'entry.
+ * Usato alla cancellazione entry per eliminare i file associati da R2.
+ *
+ * @see docs/media-engine.md
+ */
+import type { Seed } from '@beechcms/core'
+
+/** Pattern per estrarre la chiave R2 da URL in formato /api/media/KEY */
+const MEDIA_URL_PATTERN = /\/api\/media\/([^/?#]+)/
+
+/**
+ * Estrae la chiave R2 da un URL di media.
+ * Es: "https://x.com/api/media/1739123456-avatar.png" → "1739123456-avatar.png"
+ *
+ * @param mediaUrl - URL completo o path (es. /api/media/123-foto.png)
+ * @returns Chiave R2 o null se l'URL non è valido
+ */
+export function extractMediaKey(mediaUrl: string): string | null {
+  const match = MEDIA_URL_PATTERN.exec(String(mediaUrl))
+  return match ? decodeURIComponent(match[1]) : null
+}
+
+/**
+ * Attraversa ricorsivamente un valore (stringa, array, oggetto) e raccoglie
+ * tutte le chiavi R2 trovate in stringhe che matchano /api/media/KEY.
+ */
+function collectMediaKeysRecursive(value: unknown, collectedKeys: Set<string>): void {
+  if (typeof value === 'string') {
+    const r2Key = extractMediaKey(value)
+    if (r2Key) {
+      collectedKeys.add(r2Key)
+      return
+    }
+    // Legacy compat: campi json/file possono contenere JSON serializzato.
+    try {
+      const parsed = JSON.parse(value) as unknown
+      if (parsed !== value) {
+        collectMediaKeysRecursive(parsed, collectedKeys)
+      }
+    } catch {
+      // ignore
+    }
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectMediaKeysRecursive(item, collectedKeys)
+    return
+  }
+  if (value != null && typeof value === 'object') {
+    for (const nestedValue of Object.values(value)) {
+      collectMediaKeysRecursive(nestedValue, collectedKeys)
+    }
+  }
+}
+
+/**
+ * Estrae tutte le chiavi R2 dal data di un'entry.
+ * Cerca nei campi `file` (stringa URL) e `json` (array/oggetto con URL).
+ * Il data è in formato DB: chiavi = branch.id (es. art_03, prd_05).
+ *
+ * @param seed - Schema del tipo di contenuto
+ * @param entryData - Payload in formato DB (chiavi = branch ID)
+ * @returns Array di chiavi R2 uniche da eliminare
+ */
+export function extractMediaKeysFromData(
+  seed: Seed,
+  entryData: Record<string, unknown>
+): string[] {
+  const r2Keys = new Set<string>()
+  for (const branch of seed.branches) {
+    if (branch.type !== 'file' && branch.type !== 'json') continue
+    const fieldValue = entryData[branch.alias]
+    if (fieldValue == null) continue
+    collectMediaKeysRecursive(fieldValue, r2Keys)
+  }
+  return [...r2Keys]
+}

package/src/middleware.ts

@@ -0,0 +1,67 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { Context, Next } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { jwtVerify } from 'jose'
+
+/** Payload JWT decodificato (sub = userId, email opzionale, name opzionale) */
+export type JwtPayload = {
+  sub: string
+  email?: string
+  name?: string
+}
+
+/** Variabili iniettate nel context Hono dopo auth */
+export type AuthVariables = {
+  jwtPayload: JwtPayload
+}
+
+const UNAUTHORIZED_JSON = JSON.stringify({ error: 'Unauthorized' })
+
+function unauthorizedResponse() {
+  return new Response(UNAUTHORIZED_JSON, {
+    status: 401,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+export type JwtVerifyOptions = {
+  issuer?: string
+  audience?: string
+}
+
+/**
+ * Middleware di autenticazione JWT.
+ * Intercetta Authorization: Bearer <token>, verifica con jose e JWT_SECRET.
+ * Se valido: imposta jwtPayload nel context e chiama next().
+ * Se invalido/mancante: lancia HTTPException 401 (gestita dal framework).
+ */
+export function authMiddleware(secret: string, options: JwtVerifyOptions = {}) {
+  return async (c: Context, next: Next): Promise<Response | void> => {
+    const auth = c.req.header('Authorization')
+    if (!auth?.startsWith('Bearer ')) {
+      throw new HTTPException(401, { res: unauthorizedResponse() })
+    }
+
+    const token = auth.slice(7)
+    if (!token) {
+      throw new HTTPException(401, { res: unauthorizedResponse() })
+    }
+
+    try {
+      const secretBytes = new TextEncoder().encode(secret)
+      const { payload, protectedHeader } = await jwtVerify(token, secretBytes, {
+        algorithms: ['HS256'],
+        issuer: options.issuer,
+        audience: options.audience,
+      })
+      // Hardening: accetta solo token JWT standard (se presente il typ)
+      if (protectedHeader.typ && protectedHeader.typ !== 'JWT') {
+        throw new Error('Invalid typ header')
+      }
+      c.set('jwtPayload', payload as JwtPayload)
+      await next()
+    } catch {
+      throw new HTTPException(401, { res: unauthorizedResponse() })
+    }
+  }
+}

package/src/public/access-policy.ts

@@ -0,0 +1,23 @@
+import type { Seed } from '@beechcms/core'
+
+export type PublicOperation = 'read' | 'add' | 'edit'
+
+function isAllowed(seed: Seed, operation: PublicOperation): boolean {
+  if (operation === 'read') return seed.allowPublicRead === true
+  if (operation === 'add') return seed.allowPublicPost === true
+  return seed.allowPublicEdit === true
+}
+
+export function checkPublicOperation(seed: Seed, operation: PublicOperation) {
+  if (isAllowed(seed, operation)) {
+    return { ok: true } as const
+  }
+
+  return {
+    ok: false,
+    error: {
+      error: 'Forbidden',
+      message: `Public ${operation.toUpperCase()} is not allowed for content type '${seed.slug}'.`,
+    },
+  } as const
+}

package/src/public/api-key-middleware.ts

@@ -0,0 +1,53 @@
+import type { Context, Next } from 'hono'
+import { PUBLIC_ERRORS } from './public-errors'
+import { publicProblem } from './problem-details'
+
+type PublicBindings = {
+  PUBLIC_READ_API_KEY?: string
+  PUBLIC_WRITE_API_KEY?: string
+}
+
+function isReadMethod(method: string): boolean {
+  return method === 'GET' || method === 'HEAD' || method === 'OPTIONS'
+}
+
+function getConfiguredKey(env: PublicBindings, method: string): string | undefined {
+  if (isReadMethod(method)) {
+    return env.PUBLIC_READ_API_KEY
+  }
+  return env.PUBLIC_WRITE_API_KEY
+}
+
+/**
+ * API key auth middleware for Public API routes.
+ * Uses X-API-Key header only.
+ */
+export function apiKeyMiddleware() {
+  return async (c: Context, next: Next): Promise<Response | void> => {
+    const env = c.env as PublicBindings
+    const configuredKey = getConfiguredKey(env, c.req.method)
+
+    if (!configuredKey) {
+      return publicProblem(c, {
+        type: 'public-api-not-configured',
+        title: PUBLIC_ERRORS.API_KEY_FORBIDDEN.error,
+        status: 403,
+        detail: PUBLIC_ERRORS.API_KEY_FORBIDDEN.message,
+      })
+    }
+
+    const providedKey = c.req.header('X-API-Key')
+
+    if (!providedKey || providedKey !== configuredKey) {
+      return publicProblem(c, {
+        type: 'public-api-key-unauthorized',
+        title: PUBLIC_ERRORS.API_KEY_UNAUTHORIZED.error,
+        status: 401,
+        detail: PUBLIC_ERRORS.API_KEY_UNAUTHORIZED.message,
+      })
+    }
+
+    await next()
+  }
+}
+

package/src/public/index.ts

@@ -0,0 +1,12 @@
+export { apiKeyMiddleware } from './api-key-middleware'
+export { publicRateLimitMiddleware } from './rate-limit-middleware'
+export { publicRoutes } from './public-routes'
+export { PUBLIC_ERRORS } from './public-errors'
+export { sanitizePublicPayload } from './sanitize'
+export { generateEntrySlug, slugify } from './slug-utils'
+export { buildPublicListMeta, buildPublicSingleMeta } from './response-builder'
+export { parseLatestCount, parsePublicPagination } from './query-builder'
+export { publicReadHandler } from './public-read'
+export { publicAddHandler } from './public-add'
+export { publicEditHandler } from './public-edit'
+

package/src/public/problem-details.ts

@@ -0,0 +1,42 @@
+import type { Context } from 'hono'
+
+export interface PublicProblemDetailItem {
+  field: string
+  expected: string
+  received: string
+  message: string
+}
+
+type PublicProblemInput = {
+  type: string
+  title: string
+  status: 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 | 500 | 501
+  detail: string
+  errors?: PublicProblemDetailItem[]
+}
+
+function normalizeProblemType(type: string): string {
+  if (type.startsWith('http://') || type.startsWith('https://')) {
+    return type
+  }
+  return `https://beechcms.dev/problems/${type}`
+}
+
+/**
+ * Restituisce errori API in formato Problem Details (RFC 9457).
+ */
+export function publicProblem(c: Context, input: PublicProblemInput): Response {
+  const body: Record<string, unknown> = {
+    type: normalizeProblemType(input.type),
+    title: input.title,
+    status: input.status,
+    detail: input.detail,
+    instance: c.req.path,
+  }
+  if (input.errors && input.errors.length > 0) {
+    body.errors = input.errors
+  }
+  return c.json(body, input.status, {
+    'Content-Type': 'application/problem+json',
+  })
+}