@takosjp/yurucommu-core 3.0.0

package/src/backend/middleware/cache.ts

@@ -0,0 +1,429 @@
+/**
+ * Caching Middleware for Yurucommu Backend
+ *
+ * Supports multiple runtimes:
+ * - Cloudflare Workers: Uses Cache API
+ * - Node.js/Bun: Uses in-memory LRU cache
+ *
+ * Features:
+ * - TTL-based caching
+ * - ETag and Last-Modified headers
+ * - Conditional requests
+ * - Cache invalidation
+ */
+
+import type { Context, MiddlewareHandler, Next } from "hono";
+import type { Env, Variables } from "../types.ts";
+import { logger } from "../lib/logger.ts";
+import { bytesToHex } from "../lib/hex.ts";
+
+const log = logger.child({ component: "middleware.cache" });
+
+declare global {
+  interface CacheStorage {
+    default: Cache;
+  }
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+type HonoContext = Context<{ Bindings: Env; Variables: Variables }>;
+type HonoMiddleware = MiddlewareHandler<{
+  Bindings: Env;
+  Variables: Variables;
+}>;
+
+interface CacheConfig {
+  /** Time-to-live in seconds */
+  ttl: number;
+  /** Whether to include query params in cache key (default: true) */
+  includeQueryParams?: boolean;
+  /** Specific query params to include (if not specified, all are included) */
+  queryParamsToInclude?: string[];
+  /** Cache tag for invalidation grouping */
+  cacheTag?: string;
+  /** Whether to add stale-while-revalidate (default: false) */
+  staleWhileRevalidate?: number;
+  /** Whether to vary cache by authenticated actor */
+  varyByActor?: boolean;
+  /** Custom cache key generator */
+  cacheKeyGenerator?: (c: HonoContext) => string;
+}
+
+export const CacheTTL = {
+  /** Public timeline (2 minutes) - frequently updated */
+  PUBLIC_TIMELINE: 120,
+  /** Actor profile data (5 minutes) */
+  ACTOR_PROFILE: 300,
+  /** ActivityPub actor JSON (10 minutes) */
+  ACTIVITYPUB_ACTOR: 600,
+  /** WebFinger response (1 hour) */
+  WEBFINGER: 3600,
+  /** Community info (5 minutes) */
+  COMMUNITY: 300,
+  /** Search results (1 minute) */
+  SEARCH: 60,
+} as const;
+
+export const CacheTags = {
+  TIMELINE: "timeline",
+  ACTOR: "actor",
+  COMMUNITY: "community",
+  WEBFINGER: "webfinger",
+} as const;
+
+// ============================================================================
+// In-Memory LRU Cache (for non-Cloudflare runtimes)
+// ============================================================================
+
+interface CacheEntry {
+  body: string;
+  headers: Record<string, string>;
+  status: number;
+  expiresAt: number;
+  etag: string;
+  lastModified: string;
+  tag?: string;
+}
+
+class LRUCache {
+  private cache: Map<string, CacheEntry> = new Map();
+  private maxSize: number;
+
+  constructor(maxSize: number = 1000) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: string): CacheEntry | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    return entry;
+  }
+
+  set(key: string, entry: CacheEntry): void {
+    while (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    this.cache.set(key, entry);
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.cache) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+      }
+    }
+  }
+}
+
+const memoryCache = new LRUCache(1000);
+
+const CLEANUP_INTERVAL = 5 * 60 * 1000;
+let lastCleanup = Date.now();
+
+function maybeCleanup(): void {
+  const now = Date.now();
+  if (now - lastCleanup >= CLEANUP_INTERVAL) {
+    lastCleanup = now;
+    memoryCache.cleanup();
+  }
+}
+
+// ============================================================================
+// Shared Helpers
+// ============================================================================
+
+// Exported for tests: the per-viewer (varyByActor) dimension MUST land in the
+// query string, never a URL fragment — Cloudflare's Cache API strips fragments,
+// which would collapse all viewers onto one key (see the comment below).
+export function generateCacheKey(c: HonoContext, config: CacheConfig): string {
+  if (config.cacheKeyGenerator) {
+    return config.cacheKeyGenerator(c);
+  }
+
+  const url = new URL(c.req.url);
+  let cacheKey = url.pathname;
+
+  if (config.includeQueryParams !== false) {
+    const params = new URLSearchParams();
+
+    if (config.queryParamsToInclude) {
+      for (const key of config.queryParamsToInclude) {
+        const value = url.searchParams.get(key);
+        if (value !== null) {
+          params.set(key, value);
+        }
+      }
+    } else {
+      const sortedKeys = Array.from(url.searchParams.keys()).sort();
+      for (const key of sortedKeys) {
+        params.set(key, url.searchParams.get(key)!);
+      }
+    }
+
+    const queryString = params.toString();
+    if (queryString) {
+      cacheKey += `?${queryString}`;
+    }
+  }
+
+  if (config.varyByActor) {
+    const actor = c.get("actor");
+    const actorVal = actor ? actor.ap_id : "anonymous";
+    // Fold the per-viewer dimension into the QUERY STRING, NOT a URL fragment.
+    // On Cloudflare the Cache API strips the fragment during match()/put(), so a
+    // `#actor:` suffix collapsed ALL viewers onto one key and served viewer A's
+    // private (authenticated, per-viewer) response to viewer B for the TTL. A
+    // query param is part of the real cache key on both the CF and memory paths.
+    cacheKey += `${cacheKey.includes("?") ? "&" : "?"}__actor=${encodeURIComponent(
+      actorVal,
+    )}`;
+  }
+
+  return cacheKey;
+}
+
+async function generateETag(body: string): Promise<string> {
+  const data = new TextEncoder().encode(body);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashHex = bytesToHex(new Uint8Array(hashBuffer));
+  return `"${hashHex.substring(0, 16)}"`;
+}
+
+function buildCacheControl(config: CacheConfig): string {
+  let value = `public, max-age=${config.ttl}`;
+  if (config.staleWhileRevalidate) {
+    value += `, stale-while-revalidate=${config.staleWhileRevalidate}`;
+  }
+  return value;
+}
+
+/**
+ * Check If-None-Match and If-Modified-Since conditional request headers.
+ * Returns true if the client's cached copy is still fresh (caller should respond 304).
+ */
+function isConditionalHit(
+  c: HonoContext,
+  etag: string | null,
+  lastModified: string | null,
+): boolean {
+  const ifNoneMatch = c.req.header("If-None-Match");
+  if (ifNoneMatch && etag && ifNoneMatch === etag) {
+    return true;
+  }
+
+  const ifModifiedSince = c.req.header("If-Modified-Since");
+  if (ifModifiedSince && lastModified) {
+    if (new Date(ifModifiedSince) >= new Date(lastModified)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Apply standard cache headers to a Headers object.
+ * Mutates `headers` in place and returns it for chaining convenience.
+ */
+function applyCacheHeaders(
+  headers: Headers,
+  config: CacheConfig,
+  etag: string,
+  lastModified: string,
+  cacheStatus: "HIT" | "MISS",
+): Headers {
+  headers.set("Cache-Control", buildCacheControl(config));
+  headers.set("ETag", etag);
+  headers.set("Last-Modified", lastModified);
+  headers.set("X-Cache", cacheStatus);
+  if (config.cacheTag) {
+    // Emits a Cache-Tag header for OPTIONAL operator-side purging (Cloudflare
+    // Enterprise Cache-Tag purge API). NOTE: there is NO in-app, mutation-
+    // triggered invalidation — cached reads expire by TTL ONLY, so a deleted/
+    // edited/now-private object can be served stale until its TTL lapses (worst
+    // case ~1h for webfinger, 2-5min for feeds/actor). TTLs are deliberately
+    // short and varyByActor/authed-bypass prevent cross-audience leaks, so the
+    // staleness window is the accepted tradeoff rather than a correctness bug.
+    headers.set("Cache-Tag", config.cacheTag);
+  }
+  return headers;
+}
+
+function isCloudflareWorkers(): boolean {
+  return typeof caches !== "undefined" && "default" in caches;
+}
+
+// ============================================================================
+// Caching Middleware
+// ============================================================================
+
+/**
+ * Create a caching middleware
+ *
+ * @example
+ * // Cache public timeline for 2 minutes
+ * timeline.get('/', withCache({ ttl: CacheTTL.PUBLIC_TIMELINE }), handler);
+ *
+ * // Cache actor profile with tag for invalidation
+ * actors.get('/:username', withCache({
+ *   ttl: CacheTTL.ACTOR_PROFILE,
+ *   cacheTag: CacheTags.ACTOR,
+ * }), handler);
+ */
+export function withCache(config: CacheConfig): HonoMiddleware {
+  return async (c, next) => {
+    if (c.req.method !== "GET") {
+      await next();
+      return;
+    }
+
+    if (!config.varyByActor && c.get("actor")) {
+      await next();
+      return;
+    }
+
+    const cacheKey = generateCacheKey(c, config);
+
+    if (isCloudflareWorkers()) {
+      return handleCloudflareCache(c, next, cacheKey, config);
+    }
+    return handleMemoryCache(c, next, cacheKey, config);
+  };
+}
+
+async function handleCloudflareCache(
+  c: HonoContext,
+  next: Next,
+  cacheKey: string,
+  config: CacheConfig,
+): Promise<Response | void> {
+  const cache = caches.default;
+  const url = new URL(c.req.url);
+  const fullCacheKey = new Request(`${url.origin}/_cache${cacheKey}`);
+
+  const cachedResponse = await cache.match(fullCacheKey);
+
+  if (cachedResponse) {
+    const etag = cachedResponse.headers.get("ETag");
+    const lastModified = cachedResponse.headers.get("Last-Modified");
+
+    if (isConditionalHit(c, etag, lastModified)) {
+      return c.body(null, 304);
+    }
+
+    const headers = new Headers(cachedResponse.headers);
+    headers.set("X-Cache", "HIT");
+    return new Response(cachedResponse.body, {
+      status: cachedResponse.status,
+      headers,
+    });
+  }
+
+  await next();
+
+  if (c.res.status !== 200) {
+    return;
+  }
+
+  const responseBody = await c.res.text();
+  const etag = await generateETag(responseBody);
+  const lastModified = new Date().toUTCString();
+
+  const headers = new Headers(c.res.headers);
+  applyCacheHeaders(headers, config, etag, lastModified, "MISS");
+
+  const responseToCache = new Response(responseBody, {
+    status: 200,
+    headers,
+  });
+
+  const ctx = c.executionCtx;
+  if (ctx && typeof ctx.waitUntil === "function") {
+    ctx.waitUntil(
+      cache.put(fullCacheKey, responseToCache.clone()).catch((err) => {
+        log.error("Failed to store response in cache", {
+          event: "cache.put.failed",
+          cacheKey: fullCacheKey,
+          error: err,
+        });
+      }),
+    );
+  }
+
+  c.res = responseToCache;
+}
+
+async function handleMemoryCache(
+  c: HonoContext,
+  next: Next,
+  cacheKey: string,
+  config: CacheConfig,
+): Promise<Response | void> {
+  maybeCleanup();
+
+  const cached = memoryCache.get(cacheKey);
+
+  if (cached) {
+    if (isConditionalHit(c, cached.etag, cached.lastModified)) {
+      return c.body(null, 304);
+    }
+
+    const headers = new Headers(cached.headers);
+    headers.set("X-Cache", "HIT");
+    return new Response(cached.body, {
+      status: cached.status,
+      headers,
+    });
+  }
+
+  await next();
+
+  if (c.res.status !== 200) {
+    return;
+  }
+
+  const responseBody = await c.res.text();
+  const etag = await generateETag(responseBody);
+  const lastModified = new Date().toUTCString();
+
+  const headers = new Headers(c.res.headers);
+  applyCacheHeaders(headers, config, etag, lastModified, "MISS");
+
+  const headersObj: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    headersObj[key] = value;
+  });
+
+  memoryCache.set(cacheKey, {
+    body: responseBody,
+    headers: headersObj,
+    status: 200,
+    expiresAt: Date.now() + config.ttl * 1000,
+    etag,
+    lastModified,
+    tag: config.cacheTag,
+  });
+
+  c.res = new Response(responseBody, {
+    status: 200,
+    headers,
+  });
+}

package/src/backend/middleware/csrf.ts

@@ -0,0 +1,130 @@
+import type { Context, Next } from "hono";
+
+import type { Env, Variables } from "../types.ts";
+import { logger } from "../lib/logger.ts";
+
+const log = logger.child({ component: "middleware.csrf" });
+
+const STATE_CHANGING_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
+
+function getOrigin(url: string | null): string | null {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url);
+    return `${parsed.protocol}//${parsed.host}`;
+  } catch {
+    return null;
+  }
+}
+
+function isActivityPubInbox(path: string): boolean {
+  return path.includes("/inbox") && path.includes("/ap/");
+}
+
+function isDevLocalhost(appUrl: string | undefined): boolean {
+  return (
+    !!appUrl && (appUrl.includes("localhost") || appUrl.includes("127.0.0.1"))
+  );
+}
+
+/**
+ * Build the set of allowed origins for CSRF Origin / Referer check.
+ *
+ * Sources (= union):
+ * - `APP_URL` env (= 既存 production-equivalent origin)
+ * - `CSRF_ALLOWED_ORIGINS` env (= comma-separated 追加 origin、 dev hostname
+ *   を register するための env、 default 未設定で backward compat)
+ *
+ * 未正規化 / 空文字 / 構文不正な URL は skip。 trailing slash は正規化される
+ * (= `getOrigin` が `protocol//host` 形式に戻すため)。
+ */
+function buildAllowedOrigins(env: {
+  APP_URL?: string;
+  CSRF_ALLOWED_ORIGINS?: string;
+}): Set<string> {
+  const origins = new Set<string>();
+  const appOrigin = getOrigin(env.APP_URL ?? null);
+  if (appOrigin) origins.add(appOrigin);
+
+  const extra =
+    env.CSRF_ALLOWED_ORIGINS?.split(",")
+      .map((s) => s.trim())
+      .filter(Boolean) ?? [];
+  for (const raw of extra) {
+    const normalized = getOrigin(raw);
+    if (normalized) origins.add(normalized);
+  }
+  return origins;
+}
+
+function isBearerApiRequest(
+  c: Context<{ Bindings: Env; Variables: Variables }>,
+) {
+  const auth = c.req.header("Authorization");
+  if (!auth?.startsWith("Bearer ")) return false;
+
+  // Browser session requests must still satisfy CSRF checks even if a script
+  // adds an Authorization header. Server-to-server bearer calls should not
+  // carry cookies.
+  return !c.req.header("Cookie");
+}
+
+/**
+ * CSRF protection middleware.
+ * Validates Origin/Referer for state-changing requests as defense-in-depth
+ * alongside SameSite=Lax cookies.
+ */
+export function csrfProtection() {
+  return async (
+    c: Context<{ Bindings: Env; Variables: Variables }>,
+    next: Next,
+  ) => {
+    if (!STATE_CHANGING_METHODS.has(c.req.method.toUpperCase())) return next();
+    if (isActivityPubInbox(c.req.path)) return next();
+    if (isBearerApiRequest(c)) return next();
+
+    const appUrl = c.env.APP_URL;
+    const allowedOrigins = buildAllowedOrigins(c.env);
+
+    const requestOrigin =
+      c.req.header("Origin") || getOrigin(c.req.header("Referer") ?? null);
+    if (!requestOrigin) {
+      log.warn("CSRF check failed: missing origin", {
+        event: "csrf.check.missing_origin",
+        method: c.req.method,
+        path: c.req.path,
+      });
+      return c.json(
+        { error: "CSRF validation failed: missing Origin header" },
+        403,
+      );
+    }
+
+    if (!allowedOrigins.has(requestOrigin)) {
+      const ro = (() => {
+        try {
+          return new URL(requestOrigin).hostname;
+        } catch {
+          return null;
+        }
+      })();
+      if (
+        isDevLocalhost(appUrl) &&
+        ro &&
+        (ro === "localhost" || ro === "127.0.0.1" || ro === "[::1]")
+      ) {
+        return next();
+      }
+      log.warn("CSRF check failed: origin mismatch", {
+        event: "csrf.check.origin_mismatch",
+        method: c.req.method,
+        path: c.req.path,
+        allowedOrigins: [...allowedOrigins],
+        requestOrigin,
+      });
+      return c.json({ error: "CSRF validation failed" }, 403);
+    }
+
+    return next();
+  };
+}

package/src/backend/middleware/error-handler.ts

@@ -0,0 +1,77 @@
+import type { Context } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+import {
+  AppError,
+  BadRequestError,
+  InternalError,
+  isAppError,
+  logError,
+} from "../lib/errors.ts";
+
+interface ErrorMiddlewareOptions {
+  /** Custom error logger */
+  logger?: (error: unknown, context?: Record<string, unknown>) => void;
+}
+
+function getCorrelationId(c: Context): string {
+  return (
+    c.req.header("x-request-id") ??
+    c.req.header("CF-Ray") ??
+    crypto.randomUUID()
+  );
+}
+
+/**
+ * Resolve the incoming error to an AppError, logging unknown errors.
+ */
+function resolveAppError(
+  err: Error,
+  c: Context,
+  correlationId: string,
+  logger: ErrorMiddlewareOptions["logger"],
+): AppError {
+  if (isAppError(err)) return err;
+
+  // Client-input parse failures that reach the top-level handler are 400s, not
+  // 500s, and are not logged as faults (they're expected client behavior):
+  //  - SyntaxError: a malformed/empty JSON request body from `c.req.json()`
+  //    (internal JSON parsing uses safeJsonParse, which never throws).
+  //  - URIError: malformed percent-encoding in a route/query param decoded with
+  //    decodeURIComponent (e.g. a bad `:encodedApId`).
+  // TypeError/RangeError are deliberately NOT mapped here: they usually signal
+  // an internal bug and must be fixed at the call site, not masked as 400.
+  if (err instanceof SyntaxError) {
+    return new BadRequestError("Invalid or malformed JSON request body");
+  }
+  if (err instanceof URIError) {
+    return new BadRequestError("Malformed URL encoding in request");
+  }
+
+  logger?.(err, {
+    correlationId,
+    path: c.req.path,
+    method: c.req.method,
+    requestId: c.req.header("x-request-id"),
+  });
+  return new InternalError("An unexpected error occurred");
+}
+
+/**
+ * Create Hono error middleware
+ */
+export function createErrorMiddleware(
+  options: ErrorMiddlewareOptions = {},
+): (err: Error, c: Context) => Response {
+  const { logger = logError } = options;
+
+  return (err: Error, c: Context): Response => {
+    const correlationId = getCorrelationId(c);
+    const appError = resolveAppError(err, c, correlationId, logger);
+
+    const response = appError.toResponse();
+    response.correlation_id = correlationId;
+
+    return c.json(response, appError.statusCode as ContentfulStatusCode);
+  };
+}