@k2b/cloud 0.6.0-rc.0

package/src/server/middleware/rate-limit.ts

@@ -0,0 +1,125 @@
+import type { Context, MiddlewareHandler } from "hono";
+import { createMiddleware } from "hono/factory";
+import type { MessageResponse } from "../../contracts/shared";
+import * as settings from "../../services/settings";
+import { ratelimit } from "../ratelimit";
+import { type AuthContext, auth } from "./auth";
+
+export type RateLimitRouteOverride = {
+  method?: string;
+  path: string | RegExp;
+  limitPerSecond?: number;
+  disabled?: boolean;
+};
+
+export type RateLimitConfig = {
+  limitPerSecond?: number;
+  windowSecs?: number;
+  keyBy?: "auto" | "ip" | "user";
+  routes?: RateLimitRouteOverride[];
+};
+
+type ResolvedRateLimit = {
+  disabled: boolean;
+  limitPerSecond: number;
+  windowSecs: number;
+};
+
+const DEFAULT_WINDOW_SECS = 1;
+const LIMITER_PREFIX = "cloud:rate-limit";
+const limiterCache = new Map<string, ReturnType<typeof ratelimit>>();
+
+const getClientIp = (c: Context): string =>
+  c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.req.header("x-real-ip") ?? "unknown";
+
+const pathMatches = (requestPath: string, matcher: string | RegExp): boolean => {
+  if (matcher instanceof RegExp) return matcher.test(requestPath);
+  return requestPath === matcher || requestPath.startsWith(`${matcher}/`);
+};
+
+const resolveRouteOverride = (c: Context, overrides: RateLimitRouteOverride[] | undefined): RateLimitRouteOverride | undefined => {
+  if (!overrides || overrides.length === 0) return undefined;
+  return overrides.find((override) => {
+    if (override.method && override.method.toUpperCase() !== c.req.method.toUpperCase()) {
+      return false;
+    }
+    return pathMatches(c.req.path, override.path);
+  });
+};
+
+const resolveConfig = async (c: Context, config: RateLimitConfig): Promise<ResolvedRateLimit> => {
+  const override = resolveRouteOverride(c, config.routes);
+  if (override?.disabled) {
+    return {
+      disabled: true,
+      limitPerSecond: 0,
+      windowSecs: config.windowSecs ?? DEFAULT_WINDOW_SECS,
+    };
+  }
+
+  const configuredLimit = override?.limitPerSecond ?? config.limitPerSecond ?? null;
+  const limitPerSecond = configuredLimit ?? (await settings.get<number>("security.rate_limit_per_second"));
+
+  return {
+    disabled: false,
+    limitPerSecond: Math.max(1, Math.floor(limitPerSecond)),
+    windowSecs: Math.max(1, Math.floor(config.windowSecs ?? DEFAULT_WINDOW_SECS)),
+  };
+};
+
+const getLimiter = (limitPerSecond: number, windowSecs: number) => {
+  const cacheKey = `${limitPerSecond}:${windowSecs}`;
+  const cached = limiterCache.get(cacheKey);
+  if (cached) return cached;
+
+  const limiter = ratelimit({
+    id: cacheKey,
+    limit: limitPerSecond,
+    windowSecs,
+    prefix: LIMITER_PREFIX,
+  });
+  limiterCache.set(cacheKey, limiter);
+  return limiter;
+};
+
+const resolveIdentifier = async (c: Context<AuthContext>, keyBy: RateLimitConfig["keyBy"]): Promise<string> => {
+  if (keyBy === "ip") return `ip:${getClientIp(c)}`;
+
+  const token = auth.session.getToken(c);
+  if (!token) return `ip:${getClientIp(c)}`;
+
+  const userId = await auth.session.getRequestSubject(c, token);
+  if (!userId) return `ip:${getClientIp(c)}`;
+
+  return `user:${userId}`;
+};
+
+/**
+ * Stateless per-route rate limiting middleware backed by the Cloud Redis.
+ * Keying defaults to user ID (when session exists), otherwise client IP.
+ */
+export const rateLimit = (config: RateLimitConfig = {}): MiddlewareHandler<AuthContext> =>
+  createMiddleware<AuthContext>(async (c, next) => {
+    const resolved = await resolveConfig(c, config);
+    if (resolved.disabled) {
+      await next();
+      return;
+    }
+
+    const keyBy = config.keyBy ?? "auto";
+    const identifier = await resolveIdentifier(c, keyBy);
+    const limiter = getLimiter(resolved.limitPerSecond, resolved.windowSecs);
+    const result = await limiter.check(identifier);
+    const resetInSeconds = Math.max(1, Math.ceil(result.resetIn / 1000));
+
+    c.header("X-RateLimit-Limit", String(resolved.limitPerSecond));
+    c.header("X-RateLimit-Remaining", String(result.remaining));
+    c.header("X-RateLimit-Reset", String(resetInSeconds));
+
+    if (result.limited) {
+      c.header("Retry-After", String(resetInSeconds));
+      return c.json({ message: "Rate limit exceeded" } as MessageResponse, 429);
+    }
+
+    await next();
+  });

package/src/server/middleware/request-logger.ts

@@ -0,0 +1,41 @@
+import { createMiddleware } from "hono/factory";
+import { logger } from "../../services/logging";
+import type { AuthContext } from "./auth";
+
+const log = logger("http");
+
+const SKIP_PREFIXES = ["/public/", "/_ssr/", "/favicon", "/branding/"];
+
+/**
+ * HTTP request logging middleware.
+ * Logs to DB based on response status:
+ * - 5xx → error (server errors)
+ * - 429 → warn (rate limiting)
+ * - 401/403 → info (auth flows)
+ * - Everything else (2xx, 3xx, 400, 404) → not logged (too noisy)
+ */
+export const requestLogger = createMiddleware<AuthContext>(async (c, next) => {
+  const path = c.req.path;
+  if (SKIP_PREFIXES.some((p) => path.startsWith(p))) return next();
+
+  const start = Date.now();
+  await next();
+  const status = c.res.status;
+  const duration = Date.now() - start;
+
+  const meta = {
+    method: c.req.method,
+    path,
+    status,
+    duration,
+    userId: c.get("user")?.id ?? null,
+  };
+
+  if (status >= 500) {
+    log.error(`${c.req.method} ${path} ${status}`, meta);
+  } else if (status === 429) {
+    log.warn(`${c.req.method} ${path} 429 rate-limited`, meta);
+  } else if (status === 401 || status === 403) {
+    log.info(`${c.req.method} ${path} ${status}`, meta);
+  }
+});

package/src/server/middleware/route-template.ts

@@ -0,0 +1,46 @@
+/**
+ * Publishes the app's matched Hono route template to the gateway.
+ *
+ * Gateway telemetry only knows the registry prefix it routed on
+ * (`/api/mail`), so every endpoint of an app collapses into one bucket —
+ * enough to see that an app is failing, never enough to see which
+ * endpoint. The app itself already knows the exact answer: after the
+ * handler ran, `routePath(c)` resolves to the registered pattern
+ * (`/api/mail/mailboxes/:mailboxId`).
+ *
+ * We hand it to the gateway in a response header. The gateway reads it
+ * off the upstream response next to status and duration — which it
+ * already sources the same way — and strips it before the client sees
+ * it. No second telemetry pipeline, no path guessing.
+ *
+ * Templates only: the request path itself never leaves the app, so ids
+ * and query strings stay out of telemetry by construction.
+ */
+import { createMiddleware } from "hono/factory";
+import { routePath } from "hono/route";
+import { ROUTE_TEMPLATE_HEADER } from "../../services/gateway";
+
+/** Hono's placeholder when nothing matched (404) — carries no information. */
+const UNMATCHED = "/*";
+
+const MAX_TEMPLATE_LENGTH = 200;
+
+/**
+ * Hono allows a regex constraint on a param (`:filename{.+\.js$}`). It is part
+ * of the pattern but noise in an ops table, and it can carry characters that
+ * are awkward in a header value, so only the param name is reported.
+ */
+const stripParamConstraints = (template: string): string => template.replace(/\{[^}]*\}/g, "");
+
+export const routeTemplate = createMiddleware(async (c, next) => {
+  await next();
+
+  // Best-effort: telemetry enrichment must never break a response.
+  try {
+    const template = routePath(c);
+    if (!template || template === UNMATCHED) return;
+    c.res.headers.set(ROUTE_TEMPLATE_HEADER, stripParamConstraints(template).slice(0, MAX_TEMPLATE_LENGTH));
+  } catch {
+    // Immutable response headers or an unrouted context — nothing to report.
+  }
+});

package/src/server/middleware/runtime.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-request middleware that exposes the live cluster registry on
+ * `c.get("runtime")`. The first call to this middleware kicks off the
+ * Redis registry watcher (idempotent); subsequent requests read from
+ * the in-memory snapshot.
+ *
+ * Required by anything that renders the framework's `<Layout>`,
+ * `<Sidebar>`, dashboard widget aggregator, or `Cmd+K` global search.
+ */
+import { createMiddleware } from "hono/factory";
+import { ensureRuntimeWatcher, getCurrentRuntime } from "../../_internal/runtime-watcher";
+import { routeTemplate } from "./route-template";
+
+export const runtime = () =>
+  createMiddleware(async (c, next) => {
+    await ensureRuntimeWatcher();
+    (c as unknown as { set: (k: string, v: unknown) => void }).set("runtime", getCurrentRuntime());
+    // Piggybacks on the middleware every proxied app already installs, so
+    // gateway telemetry gets per-endpoint route templates without any app
+    // having to opt in. See `middleware.observability()` for the rest.
+    await routeTemplate(c, next);
+  });

package/src/server/middleware/settings.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-request middleware that exposes a frozen settings snapshot on
+ * `c.get("settings")`. Backed by Redis cache-aside (5-minute TTL),
+ * so the per-request cost is a single Redis read at most.
+ *
+ * Required by anything that reads typed settings inside an HTTP
+ * handler via `c.get("settings").<key>`.
+ *
+ * `skipPrefixes` defaults to `["/public/", "/_ssr/", "/branding/", "/favicon"]`
+ * — those paths never read settings, so skipping the snapshot load
+ * keeps static-asset requests free. Apps that mount settings only on
+ * /api or /app can avoid the option entirely by scoping the
+ * `.use()` path instead.
+ */
+import { createMiddleware } from "hono/factory";
+import {
+  type ActiveAnnouncementsResponse,
+  type AnnouncementCookieState,
+  parseAnnouncementCookieHeader,
+} from "../../contracts/announcements";
+import { announcements } from "../../services/announcements";
+import { logger } from "../../services/logging";
+import { loadSnapshot } from "../../services/settings/snapshot";
+
+const DEFAULT_SKIP = ["/public/", "/_ssr/", "/branding/", "/favicon"] as const;
+const ANNOUNCEMENT_SKIP = ["/api/", "/public/", "/_ssr/", "/branding/", "/favicon"] as const;
+const log = logger("middleware:settings");
+
+export type LayoutAnnouncementsState = ActiveAnnouncementsResponse & {
+  cookieState: AnnouncementCookieState;
+};
+
+const shouldLoadAnnouncements = (path: string, cookieHeader: string | null): boolean =>
+  Boolean(cookieHeader?.match(/(?:^|;\s*)session_token=/)) && !ANNOUNCEMENT_SKIP.some((prefix) => path.startsWith(prefix));
+
+export const settings = (opts?: { skipPrefixes?: readonly string[] }) => {
+  const skip = opts?.skipPrefixes ?? DEFAULT_SKIP;
+  return createMiddleware(async (c, next) => {
+    const path = c.req.path;
+    if (!skip.some((p) => path.startsWith(p))) {
+      (c as unknown as { set: (k: string, v: unknown) => void }).set("settings", await loadSnapshot());
+    }
+    const cookieHeader = c.req.header("Cookie") ?? null;
+    if (shouldLoadAnnouncements(path, cookieHeader)) {
+      const cookieState = parseAnnouncementCookieHeader(cookieHeader);
+      try {
+        const active = await announcements.active.forState({ state: cookieState });
+        (c as unknown as { set: (k: string, v: unknown) => void }).set("announcements", { ...active, cookieState });
+      } catch (error) {
+        log.warn("Failed to preload announcements", { error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    await next();
+  });
+};

package/src/server/middleware/validator.ts

@@ -0,0 +1,49 @@
+import type { Context, ValidationTargets } from "hono";
+import { validator as honoValidator } from "hono-openapi";
+import type { ZodType } from "zod";
+
+export type ValidatorError = Readonly<{
+  code: string;
+  message: string;
+}>;
+
+export type ValidatorErrorResolver = (context: Context) => ValidatorError;
+
+/**
+ * Zod validator middleware with pretty error messages and OpenAPI support.
+ * Uses hono-openapi validator for automatic OpenAPI schema generation.
+ *
+ * @param target - Where to validate: "json", "query", "param", "header", "cookie", or "form"
+ * @param schema - Zod schema to validate against
+ * @param resolveError - Optional request-scoped application error resolver
+ * @returns Hono middleware that validates request data and returns 400 on failure
+ *
+ * @example
+ * ```ts
+ * app.post("/users", v("json", CreateUserSchema), async (c) => {
+ *   const data = c.req.valid("json"); // Fully typed!
+ *   // ...
+ * });
+ * ```
+ */
+export const validator = <Target extends keyof ValidationTargets, T extends ZodType>(
+  target: Target,
+  schema: T,
+  resolveError?: ValidatorErrorResolver,
+) =>
+  honoValidator(target, schema, (result, c: Context) => {
+    if (!result.success) {
+      if (resolveError) return c.json(resolveError(c), 400);
+
+      // Standard Schema returns issues array on failure
+      const errorMessage = result.error
+        ?.map((issue) => {
+          const path = issue.path?.map((p) => (typeof p === "object" && "key" in p ? String(p.key) : String(p))).join(".");
+          return path ? `${path}: ${issue.message}` : issue.message;
+        })
+        .join(", ");
+      return c.json({ message: errorMessage || "Validation failed" }, 400);
+    }
+  });
+
+export const v = validator;

package/src/server/middleware/workload.ts

@@ -0,0 +1,22 @@
+import type { Context, MiddlewareHandler } from "hono";
+import { createMiddleware } from "hono/factory";
+import { hasReservedWorkloadScope } from "../../services/identity/workload-auth";
+import type { AuthContext } from "./auth";
+
+/** Reserved app workload keys are valid only at their dedicated Core authority routes. */
+export const isReservedWorkloadCredential = (c: Context<AuthContext>): boolean => {
+  const actor = c.get("actor");
+  return (
+    c.get("credentialKind") === "api_key" &&
+    actor?.kind === "service_account" &&
+    actor.serviceAccount.kind === "resource_bound" &&
+    hasReservedWorkloadScope(c.get("credentialScopes") ?? [])
+  );
+};
+
+const reservedWorkloadResponse = (c: Context<AuthContext>): Response =>
+  c.json({ code: "FORBIDDEN", message: "App workload credentials require a dedicated Core authority route" }, 403);
+
+export const rejectReservedWorkloadCredential: MiddlewareHandler<AuthContext> = createMiddleware<AuthContext>(async (c, next) =>
+  isReservedWorkloadCredential(c) ? reservedWorkloadResponse(c) : await next(),
+);

package/src/server/ratelimit.ts

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+import { redis } from "bun";
+
+/**
+ * Sliding-window rate limiter on the Cloud Redis.
+ *
+ * Ported 1:1 from @k2b/sync v5 (which dropped it in v6): two fixed-window
+ * counters per identifier, the previous one weighted by the remaining share
+ * of the current window. Key layout and semantics are unchanged so existing
+ * counters keep working across the cutover.
+ */
+
+const DEFAULT_PREFIX = "cloud:ratelimit";
+const DEFAULT_WINDOW_SECS = 1;
+const MAX_IDENTIFIER_LENGTH = 128;
+
+const RATE_LIMIT_SCRIPT = `
+  local currentKey = KEYS[1]
+  local previousKey = KEYS[2]
+  local windowSecs = tonumber(ARGV[1])
+  local limit = tonumber(ARGV[2])
+  local elapsedRatio = tonumber(ARGV[3])
+
+  local previousCount = tonumber(redis.call("GET", previousKey) or "0")
+
+  local currentCount = redis.call("INCR", currentKey)
+  if currentCount == 1 then
+    redis.call("EXPIRE", currentKey, windowSecs * 2)
+  end
+
+  local weightedCount = previousCount * (1 - elapsedRatio) + currentCount
+
+  -- Redis converts Lua numbers returned directly to integers. Return the
+  -- weighted value as text so fractional carry-over is not truncated.
+  return {currentCount, previousCount, tostring(weightedCount)}
+`;
+
+const normalizeIdentifier = (identifier: string): string => {
+  if (identifier.length <= MAX_IDENTIFIER_LENGTH) return identifier;
+  const hash = createHash("sha256").update(identifier).digest("hex");
+  return `hash:${hash}`;
+};
+
+// ==========================
+// Types
+// ==========================
+
+export type RateLimitResult = {
+  limited: boolean;
+  remaining: number;
+  /** Milliseconds until the current window resets. */
+  resetIn: number;
+};
+
+export type RateLimiterConfig = {
+  id: string;
+  limit: number;
+  windowSecs?: number;
+  prefix?: string;
+};
+
+export type RateLimiter = {
+  id: string;
+  check(identifier: string): Promise<RateLimitResult>;
+  checkOrThrow(identifier: string): Promise<RateLimitResult>;
+};
+
+// ==========================
+// Rate Limit Error
+// ==========================
+
+export class RateLimitError extends Error {
+  readonly remaining: number;
+  readonly resetIn: number;
+
+  constructor(result: RateLimitResult) {
+    super("Rate limit exceeded");
+    this.name = "RateLimitError";
+    this.remaining = result.remaining;
+    this.resetIn = result.resetIn;
+  }
+}
+
+// ==========================
+// Rate Limiter Factory
+// ==========================
+
+export const ratelimit = (config: RateLimiterConfig): RateLimiter => {
+  // windowSecs: 0 — e.g. Number(process.env.RL_WINDOW) on an unset var — made
+  // both window keys Infinity and collapse to one, elapsedRatio NaN, and
+  // `EXPIRE key 0` delete the counter on every first increment, so the
+  // weighted count never exceeded the limit and the limiter allowed
+  // everything. A fractional windowSecs made EXPIRE reject exactly the first
+  // request of each window. Fail loudly at construction instead.
+  if (!Number.isFinite(config.limit) || config.limit <= 0) {
+    throw new Error("limit must be > 0");
+  }
+  if (
+    config.windowSecs !== undefined &&
+    (!Number.isSafeInteger(config.windowSecs) || config.windowSecs <= 0 || config.windowSecs > Math.floor(Number.MAX_SAFE_INTEGER / 2_000))
+  ) {
+    throw new Error("windowSecs must be a positive integer number of seconds");
+  }
+
+  const prefix = config.prefix ?? DEFAULT_PREFIX;
+  const windowSecs = config.windowSecs ?? DEFAULT_WINDOW_SECS;
+  const { limit } = config;
+
+  const check = async (identifier: string): Promise<RateLimitResult> => {
+    const safeIdentifier = normalizeIdentifier(identifier);
+    const now = Date.now();
+    const windowMs = windowSecs * 1000;
+    const currentWindow = Math.floor(now / windowMs);
+    const previousWindow = currentWindow - 1;
+    const elapsedInWindow = now % windowMs;
+    const elapsedRatio = elapsedInWindow / windowMs;
+
+    const currentKey = `${prefix}:${config.id}:${safeIdentifier}:${currentWindow}`;
+    const previousKey = `${prefix}:${config.id}:${safeIdentifier}:${previousWindow}`;
+
+    const result = (await redis.send("EVAL", [
+      RATE_LIMIT_SCRIPT,
+      "2",
+      currentKey,
+      previousKey,
+      windowSecs.toString(),
+      limit.toString(),
+      elapsedRatio.toString(),
+    ])) as [number, number, string];
+
+    const weightedCount = Number(result[2]);
+
+    // Fail closed on a non-comparable count: an abuse-control primitive must
+    // never allow everything because arithmetic went sideways.
+    const limited = !Number.isFinite(weightedCount) || weightedCount > limit;
+    const remaining = Math.max(0, Math.floor(limit - weightedCount));
+    const resetIn = windowMs - elapsedInWindow;
+
+    return { limited, remaining, resetIn };
+  };
+
+  const checkOrThrow = async (identifier: string): Promise<RateLimitResult> => {
+    const result = await check(identifier);
+    if (result.limited) {
+      throw new RateLimitError(result);
+    }
+    return result;
+  };
+
+  return { id: config.id, check, checkOrThrow };
+};

package/src/server/request-cookies.ts

@@ -0,0 +1,18 @@
+/** One cookie value from raw request headers, URL-decoded when possible. */
+export const readCookie = (headers: Headers, name: string): string | undefined => {
+  const cookie = headers.get("Cookie");
+  if (!cookie) return undefined;
+
+  for (const part of cookie.split(";")) {
+    const [rawName, ...rawValue] = part.trim().split("=");
+    if (rawName !== name) continue;
+    const value = rawValue.join("=");
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  }
+
+  return undefined;
+};