alabjs 0.1.0

package/src/server/cache.ts

@@ -0,0 +1,195 @@
+/**
+ * Alab in-process cache for server functions.
+ *
+ * Nothing is cached unless you explicitly opt in — no implicit layers.
+ * You own the key, the TTL, and the invalidation.
+ *
+ * @example
+ * ```ts
+ * // app/posts/[id]/page.server.ts
+ * export const getPost = defineServerFn(
+ *   async ({ params }) => db.posts.findById(params.id),
+ *   { cache: { ttl: 60, tags: ["posts", `post:${params.id}`] } },
+ * );
+ *
+ * // Invalidate from another server function or API route
+ * import { invalidateCache } from "alabjs/cache";
+ * await invalidateCache({ tags: ["posts"] });
+ * ```
+ */
+
+interface CacheEntry {
+  data: unknown;
+  /** Absolute expiry timestamp (ms since epoch). */
+  expires: number;
+  tags: string[];
+}
+
+/** Sentinel value returned when a cache key has no valid entry. */
+const CACHE_MISS: unique symbol = Symbol("alab:cache_miss");
+
+/** Global in-process LRU-style cache. Shared across all server function calls. */
+const _store = new Map<string, CacheEntry>();
+
+export { CACHE_MISS };
+
+/** Retrieve a cached value. Returns `CACHE_MISS` if absent or expired. */
+export function getCached(key: string): unknown | typeof CACHE_MISS {
+  const entry = _store.get(key);
+  if (!entry) return CACHE_MISS;
+  if (Date.now() > entry.expires) {
+    _store.delete(key);
+    return CACHE_MISS;
+  }
+  return entry.data;
+}
+
+/** Store a value in the cache with a TTL (seconds) and optional tags. */
+export function setCache(
+  key: string,
+  data: unknown,
+  opts: { ttl: number; tags?: string[] },
+): void {
+  _store.set(key, {
+    data,
+    expires: Date.now() + opts.ttl * 1_000,
+    tags: opts.tags ?? [],
+  });
+}
+
+/**
+ * Invalidate all cache entries that carry at least one of the given tags.
+ *
+ * @example
+ * ```ts
+ * import { invalidateCache } from "alabjs/cache";
+ * await invalidateCache({ tags: ["posts"] });
+ * ```
+ */
+export function invalidateCache(opts: { tags: string[] }): void {
+  for (const [key, entry] of _store) {
+    if (opts.tags.some((t) => entry.tags.includes(t))) {
+      _store.delete(key);
+    }
+  }
+}
+
+/**
+ * Invalidate a specific cache entry by its exact key.
+ * Prefer `invalidateCache({ tags })` for logical invalidation.
+ */
+export function invalidateCacheKey(key: string): void {
+  _store.delete(key);
+}
+
+// ─── Page-level HTML cache (ISR) ─────────────────────────────────────────────
+
+interface PageCacheEntry {
+  html: string;
+  expires: number;
+  /** Whether a background revalidation is already in flight. */
+  revalidating: boolean;
+  /** Tags for on-demand invalidation via `revalidateTag`. */
+  tags: string[];
+}
+
+const _pageStore = new Map<string, PageCacheEntry>();
+
+/**
+ * Retrieve a cached HTML page. Returns `null` if absent or fully expired
+ * (more than 2× TTL past — serves stale-while-revalidate window).
+ */
+export function getCachedPage(pathname: string): { html: string; stale: boolean } | null {
+  const entry = _pageStore.get(pathname);
+  if (!entry) return null;
+  const now = Date.now();
+  // Still fresh
+  if (now <= entry.expires) return { html: entry.html, stale: false };
+  // Stale-while-revalidate: serve stale for up to 2× TTL, trigger background regen
+  const ttl = entry.expires - (entry.expires - now); // rough TTL from stored data
+  if (now <= entry.expires + Math.max(ttl * 2, 60_000)) {
+    return { html: entry.html, stale: true };
+  }
+  _pageStore.delete(pathname);
+  return null;
+}
+
+/** Store a rendered HTML page with a TTL (seconds). */
+export function setCachedPage(pathname: string, html: string, ttl: number, tags: string[] = []): void {
+  _pageStore.set(pathname, { html, expires: Date.now() + ttl * 1_000, revalidating: false, tags });
+}
+
+/** Mark a page as currently being revalidated to prevent concurrent regen. */
+export function markPageRevalidating(pathname: string): void {
+  const entry = _pageStore.get(pathname);
+  if (entry) entry.revalidating = true;
+}
+
+/** Check if a page is currently being revalidated in the background. */
+export function isPageRevalidating(pathname: string): boolean {
+  return _pageStore.get(pathname)?.revalidating ?? false;
+}
+
+/**
+ * Purge a specific page's cached HTML, forcing a fresh render on the next request.
+ *
+ * @example
+ * ```ts
+ * import { revalidatePath } from "alabjs/cache";
+ * await revalidatePath("/posts/1"); // next request regenerates the page
+ * ```
+ */
+export function revalidatePath(pathname: string): void {
+  _pageStore.delete(pathname);
+}
+
+/**
+ * Purge all cached pages whose pathname starts with the given prefix.
+ *
+ * @example
+ * ```ts
+ * await revalidatePath("/posts"); // clears /posts, /posts/1, /posts/2, ...
+ * ```
+ */
+export function revalidatePathPrefix(prefix: string): void {
+  for (const key of _pageStore.keys()) {
+    if (key.startsWith(prefix)) _pageStore.delete(key);
+  }
+}
+
+/**
+ * Purge all server-function cache entries AND page HTML cache entries
+ * that carry at least one of the given tags.
+ *
+ * @example
+ * ```ts
+ * import { revalidateTag } from "alabjs/cache";
+ * revalidateTag({ tags: ["posts"] }); // clears both data and page caches
+ * ```
+ */
+export function revalidateTag(opts: { tags: string[] }): void {
+  // Server-function data cache
+  invalidateCache(opts);
+  // Page HTML cache (ISR)
+  for (const [path, entry] of _pageStore) {
+    if (opts.tags.some((t) => entry.tags.includes(t))) {
+      _pageStore.delete(path);
+    }
+  }
+}
+
+/** Return a snapshot of all live cache entries (for the dev Cache Inspector). */
+export function inspectCache(): Array<{
+  key: string;
+  tags: string[];
+  expiresIn: number;
+}> {
+  const now = Date.now();
+  const result: Array<{ key: string; tags: string[]; expiresIn: number }> = [];
+  for (const [key, entry] of _store) {
+    const expiresIn = entry.expires - now;
+    if (expiresIn > 0) result.push({ key, tags: entry.tags, expiresIn: Math.ceil(expiresIn / 1000) });
+    else _store.delete(key);
+  }
+  return result;
+}

package/src/server/csrf.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { createApp, defineEventHandler, toWebHandler } from "h3";
+import { csrfMiddleware, setCsrfCookie, csrfMetaTag, CSRF_COOKIE, CSRF_HEADER } from "./csrf.js";
+
+// ─── csrfMetaTag ─────────────────────────────────────────────────────────────
+
+describe("csrfMetaTag", () => {
+  it("generates a meta tag with the token", () => {
+    const html = csrfMetaTag("abc-123");
+    expect(html).toBe('<meta name="csrf-token" content="abc-123" />');
+  });
+
+  it("escapes double quotes in the token", () => {
+    const html = csrfMetaTag('token"with"quotes');
+    expect(html).toContain("&quot;");
+    expect(html).not.toContain('content="token"');
+  });
+
+  it("handles empty token", () => {
+    const html = csrfMetaTag("");
+    expect(html).toBe('<meta name="csrf-token" content="" />');
+  });
+
+  it("handles UUID-style tokens", () => {
+    const html = csrfMetaTag("550e8400-e29b-41d4-a716-446655440000");
+    expect(html).toContain("550e8400-e29b-41d4-a716-446655440000");
+  });
+});
+
+// ─── csrfMiddleware ───────────────────────────────────────────────────────────
+
+describe("csrfMiddleware", () => {
+  const savedEnv = process.env["NODE_ENV"];
+
+  afterEach(() => {
+    process.env["NODE_ENV"] = savedEnv;
+  });
+
+  function makeHandler() {
+    const app = createApp();
+    app.use(csrfMiddleware());
+    app.use(defineEventHandler(() => "ok"));
+    return toWebHandler(app);
+  }
+
+  const TOKEN = "550e8400-e29b-41d4-a716-446655440000";
+
+  // Safe methods pass without any token
+
+  it("allows GET without token in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(new Request("http://localhost/"));
+    expect(res.status).toBe(200);
+  });
+
+  it("allows HEAD without token in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(new Request("http://localhost/", { method: "HEAD" }));
+    expect(res.status).toBe(200);
+  });
+
+  it("allows OPTIONS without token in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(new Request("http://localhost/", { method: "OPTIONS" }));
+    expect(res.status).toBe(200);
+  });
+
+  // Valid POST
+
+  it("allows POST with matching cookie and header in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(
+      new Request("http://localhost/", {
+        method: "POST",
+        headers: {
+          cookie: `${CSRF_COOKIE}=${TOKEN}`,
+          [CSRF_HEADER]: TOKEN,
+        },
+      }),
+    );
+    expect(res.status).toBe(200);
+  });
+
+  // Missing token cases → 403
+
+  it("rejects POST with no cookie and no header in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(new Request("http://localhost/", { method: "POST" }));
+    expect(res.status).toBe(403);
+  });
+
+  it("rejects POST with cookie but no header in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(
+      new Request("http://localhost/", {
+        method: "POST",
+        headers: { cookie: `${CSRF_COOKIE}=${TOKEN}` },
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it("rejects POST with header but no cookie in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(
+      new Request("http://localhost/", {
+        method: "POST",
+        headers: { [CSRF_HEADER]: TOKEN },
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it("rejects POST with mismatched cookie and header in production", async () => {
+    process.env["NODE_ENV"] = "production";
+    const res = await makeHandler()(
+      new Request("http://localhost/", {
+        method: "POST",
+        headers: {
+          cookie: `${CSRF_COOKIE}=token-a`,
+          [CSRF_HEADER]: "token-b",
+        },
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  // Non-production bypasses CSRF check
+
+  it("allows POST without token in development mode", async () => {
+    process.env["NODE_ENV"] = "development";
+    const res = await makeHandler()(new Request("http://localhost/", { method: "POST" }));
+    expect(res.status).toBe(200);
+  });
+
+  it("allows POST without token when NODE_ENV is unset", async () => {
+    delete process.env["NODE_ENV"];
+    const res = await makeHandler()(new Request("http://localhost/", { method: "POST" }));
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── setCsrfCookie ────────────────────────────────────────────────────────────
+
+describe("setCsrfCookie", () => {
+  function makeSetCookieHandler() {
+    const app = createApp();
+    app.use(
+      defineEventHandler((event) => {
+        const token = setCsrfCookie(event);
+        return { token };
+      }),
+    );
+    return toWebHandler(app);
+  }
+
+  it("sets a UUID token in the Set-Cookie header", async () => {
+    const res = await makeSetCookieHandler()(new Request("http://localhost/"));
+    const setCookieHeader = res.headers.get("set-cookie") ?? "";
+    expect(setCookieHeader).toMatch(/alab-csrf=[0-9a-f-]{36}/);
+  });
+
+  it("returns the generated token in the response", async () => {
+    const res = await makeSetCookieHandler()(new Request("http://localhost/"));
+    const body = (await res.json()) as { token: string };
+    expect(body.token).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it("reuses an existing cookie token instead of generating a new one", async () => {
+    const existingToken = "existing-csrf-token-value";
+    const res = await makeSetCookieHandler()(
+      new Request("http://localhost/", {
+        headers: { cookie: `${CSRF_COOKIE}=${existingToken}` },
+      }),
+    );
+    const body = (await res.json()) as { token: string };
+    expect(body.token).toBe(existingToken);
+  });
+
+  it("does not set HttpOnly on the cookie (must be readable by JS)", async () => {
+    const res = await makeSetCookieHandler()(new Request("http://localhost/"));
+    const setCookieHeader = (res.headers.get("set-cookie") ?? "").toLowerCase();
+    expect(setCookieHeader).not.toContain("httponly");
+  });
+
+  it("sets SameSite=Strict on the cookie", async () => {
+    const res = await makeSetCookieHandler()(new Request("http://localhost/"));
+    const setCookieHeader = (res.headers.get("set-cookie") ?? "").toLowerCase();
+    expect(setCookieHeader).toContain("samesite=strict");
+  });
+
+  it("sets path=/ on the cookie", async () => {
+    const res = await makeSetCookieHandler()(new Request("http://localhost/"));
+    const setCookieHeader = (res.headers.get("set-cookie") ?? "").toLowerCase();
+    expect(setCookieHeader).toContain("path=/");
+  });
+});

package/src/server/csrf.ts

@@ -0,0 +1,80 @@
+import { timingSafeEqual } from "node:crypto";
+import {
+  defineEventHandler,
+  getCookie,
+  getHeader,
+  setCookie,
+  createError,
+  type H3Event,
+} from "h3";
+
+export const CSRF_COOKIE = "alab-csrf";
+export const CSRF_HEADER = "x-csrf-token";
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * CSRF protection middleware using the Double Submit Cookie pattern.
+ *
+ * - Safe methods (GET, HEAD, OPTIONS) are always allowed.
+ * - Mutating requests must include an `x-csrf-token` header whose value
+ *   matches the `alab-csrf` cookie set by `setCsrfCookie()`.
+ * - The cookie is `SameSite=Strict` (first line of defence). The header
+ *   check is a second layer that prevents attacks from subdomains.
+ * - Disabled in development (NODE_ENV !== "production") for DX.
+ */
+export function csrfMiddleware() {
+  return defineEventHandler((event) => {
+    // Skip in development — avoid friction during local iteration.
+    if (process.env["NODE_ENV"] !== "production") return;
+
+    const method = event.method.toUpperCase();
+    if (SAFE_METHODS.has(method)) return;
+
+    const cookieToken = getCookie(event, CSRF_COOKIE);
+    const headerToken = getHeader(event, CSRF_HEADER);
+
+    const tokensMatch =
+      !!cookieToken &&
+      !!headerToken &&
+      cookieToken.length === headerToken.length &&
+      timingSafeEqual(Buffer.from(cookieToken), Buffer.from(headerToken));
+
+    if (!tokensMatch) {
+      throw createError({
+        statusCode: 403,
+        message: "CSRF token mismatch. Include the x-csrf-token header.",
+      });
+    }
+  });
+}
+
+/**
+ * Set a CSRF cookie on the response and return the generated token.
+ * Call this on every GET page response so the client always has a fresh token.
+ *
+ * The cookie is intentionally NOT HttpOnly so JavaScript can read and send
+ * it as the `x-csrf-token` request header.
+ */
+export function setCsrfCookie(event: H3Event): string {
+  const existing = getCookie(event, CSRF_COOKIE);
+  if (existing) return existing;
+
+  const token = crypto.randomUUID();
+  setCookie(event, CSRF_COOKIE, token, {
+    httpOnly: false,
+    sameSite: "strict",
+    secure: process.env["NODE_ENV"] === "production",
+    path: "/",
+    maxAge: 60 * 60 * 24, // 24 hours
+  });
+  return token;
+}
+
+/**
+ * Inject the CSRF token as a `<meta name="csrf-token">` tag into
+ * the HTML shell so client code can read it without a separate request.
+ */
+export function csrfMetaTag(token: string): string {
+  return `<meta name="csrf-token" content="${token.replace(/"/g, "&quot;")}" />`;
+}

package/src/server/image.ts

@@ -0,0 +1,112 @@
+import { readFile, access } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AlabNapi } from "../types/napi.js";
+
+/**
+ * Handle `/_alabjs/image` requests using the Rust image optimiser (alab-napi).
+ *
+ * Node.js reads the source file from `public/` then passes the raw bytes to
+ * Rust — same pattern as snapbolt-cli. Rust decodes, resizes, and encodes to
+ * WebP (libwebp-sys with `native` feature, or pure-Rust fallback).
+ *
+ * Query params:
+ *   src    — path relative to the project's `public/` directory (required)
+ *   w      — target width in pixels (required)
+ *   q      — quality 1–100 (default: 80)
+ *   fmt    — "webp" (default) | "jpeg" | "png"
+ *
+ * Cache-Control is set to 1 year / immutable for optimised responses.
+ */
+export async function handleImageRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  publicDir: string,
+): Promise<void> {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const src = url.searchParams.get("src");
+  const wParam = url.searchParams.get("w");
+  const quality = Math.max(1, Math.min(100, parseInt(url.searchParams.get("q") ?? "80", 10)));
+  const fmt = url.searchParams.get("fmt") ?? "webp";
+
+  if (!src || !wParam) {
+    res.statusCode = 400;
+    res.end("[alabjs] Missing src or w parameter");
+    return;
+  }
+
+  const width = parseInt(wParam, 10);
+  if (!Number.isFinite(width) || width < 1 || width > 4096) {
+    res.statusCode = 400;
+    res.end("[alabjs] Invalid width — must be 1–4096");
+    return;
+  }
+
+  // Prevent path traversal
+  const safeSrc = src.replace(/\.\./g, "").replace(/^\/+/, "");
+  const filePath = resolve(publicDir, safeSrc);
+  if (!filePath.startsWith(publicDir)) {
+    res.statusCode = 403;
+    res.end("[alabjs] Forbidden");
+    return;
+  }
+
+  try {
+    await access(filePath);
+  } catch {
+    res.statusCode = 404;
+    res.end("[alabjs] Image not found");
+    return;
+  }
+
+  const input = await readFile(filePath);
+
+  // Load napi binding (built by `cargo build --release -p alab-napi`).
+  // Fall back to serving the raw file when the binary isn't available so that
+  // images still load during development without the Rust toolchain.
+  let napi: AlabNapi | null = null;
+  try {
+    const mod = await import("@alabjs/compiler") as { default?: AlabNapi } & AlabNapi;
+    napi = (mod.default ?? mod) as AlabNapi;
+  } catch {
+    // napi not built — will serve raw file below.
+  }
+
+  if (!napi) {
+    const ext = safeSrc.split(".").pop()?.toLowerCase() ?? "";
+    const mime =
+      ext === "jpg" || ext === "jpeg" ? "image/jpeg"
+      : ext === "png"                  ? "image/png"
+      : ext === "gif"                  ? "image/gif"
+      : ext === "webp"                 ? "image/webp"
+      : ext === "avif"                 ? "image/avif"
+      :                                  "application/octet-stream";
+    res.statusCode = 200;
+    res.setHeader("content-type", mime);
+    res.setHeader("cache-control", "no-store");
+    res.setHeader("content-length", input.length);
+    res.end(input);
+    return;
+  }
+
+  try {
+    // Pass raw bytes to Rust — decode + resize + encode on a blocking thread pool.
+    const optimised = await napi.optimizeImage(input, quality, width, undefined, fmt);
+
+    const mime =
+      fmt === "jpeg" || fmt === "jpg" ? "image/jpeg"
+      : fmt === "png"                 ? "image/png"
+      :                                 "image/webp";
+
+    res.statusCode = 200;
+    res.setHeader("content-type", mime);
+    res.setHeader("cache-control", "public, max-age=31536000, immutable");
+    res.setHeader("content-length", optimised.length);
+    res.end(optimised);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[alabjs] image optimisation failed — src=${safeSrc} w=${width} fmt=${fmt}: ${msg}`);
+    res.statusCode = 500;
+    res.end("[alabjs] Image optimisation failed — check server logs");
+  }
+}