fastscript 0.1.1 → 2.0.0

package/src/security.mjs

@@ -1,50 +1,228 @@
-import { createHash } from "node:crypto";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { generateCspPolicy } from "./csp.mjs";
 
-const rateState = new Map();
+function nowMs() {
+  return Date.now();
+}
+
+function parseBool(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (value === true || value === "true" || value === "1") return true;
+  if (value === false || value === "false" || value === "0") return false;
+  return fallback;
+}
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, value) {
+  writeFileSync(path, JSON.stringify(value, null, 2), "utf8");
+}
+
+export function createMemoryWindowStore() {
+  const rows = new Map();
+  return {
+    async increment(key, windowMs) {
+      const now = nowMs();
+      const row = rows.get(key) || { count: 0, resetAt: now + windowMs };
+      if (now > row.resetAt) {
+        row.count = 0;
+        row.resetAt = now + windowMs;
+      }
+      row.count += 1;
+      rows.set(key, row);
+      return { count: row.count, resetAt: row.resetAt };
+    },
+  };
+}
+
+export function createFileWindowStore({ dir = ".fastscript/security", name = "rate-limit" } = {}) {
+  const root = resolve(dir);
+  mkdirSync(root, { recursive: true });
+  const file = join(root, `${name}.json`);
+  const state = readJson(file, { rows: {} });
 
-export function securityHeaders({ csp = "default-src 'self'", hsts = "max-age=31536000; includeSubDomains" } = {}) {
+  function persist() {
+    writeJson(file, state);
+  }
+
+  return {
+    async increment(key, windowMs) {
+      const now = nowMs();
+      const row = state.rows[key] || { count: 0, resetAt: now + windowMs };
+      if (now > row.resetAt) {
+        row.count = 0;
+        row.resetAt = now + windowMs;
+      }
+      row.count += 1;
+      state.rows[key] = row;
+      persist();
+      return { count: row.count, resetAt: row.resetAt };
+    },
+  };
+}
+
+export async function createRedisWindowStore({ url = process.env.REDIS_URL, prefix = "fastscript:rate" } = {}) {
+  const mod = await import("redis");
+  const client = mod.createClient({ url });
+  await client.connect();
+  return {
+    async increment(key, windowMs) {
+      const rowKey = `${prefix}:${key}`;
+      const count = Number(await client.incr(rowKey));
+      if (count === 1) await client.pExpire(rowKey, windowMs);
+      const ttl = Number(await client.pTTL(rowKey));
+      return { count, resetAt: nowMs() + Math.max(0, ttl) };
+    },
+    async close() {
+      await client.quit();
+    },
+  };
+}
+
+export async function createWindowStore({ driver = process.env.RATE_LIMIT_DRIVER || "memory", ...opts } = {}) {
+  const mode = String(driver || "memory").toLowerCase();
+  if (mode === "redis") {
+    try {
+      return await createRedisWindowStore(opts);
+    } catch {
+      return createMemoryWindowStore();
+    }
+  }
+  if (mode === "file") return createFileWindowStore(opts);
+  return createMemoryWindowStore();
+}
+
+export function securityHeaders({
+  csp,
+  target = process.env.DEPLOY_TARGET || "node",
+  hsts = "max-age=31536000; includeSubDomains",
+} = {}) {
   return async function securityHeadersMiddleware(ctx, next) {
+    const mode = process.env.NODE_ENV || "development";
+    const cspPolicy = csp || generateCspPolicy({ target, mode });
     ctx.res.setHeader("x-content-type-options", "nosniff");
     ctx.res.setHeader("x-frame-options", "DENY");
     ctx.res.setHeader("referrer-policy", "strict-origin-when-cross-origin");
     ctx.res.setHeader("permissions-policy", "geolocation=(), microphone=(), camera=()");
-    ctx.res.setHeader("content-security-policy", csp);
-    if ((process.env.NODE_ENV || "development") === "production") {
+    ctx.res.setHeader("content-security-policy", cspPolicy);
+    if (mode === "production") {
       ctx.res.setHeader("strict-transport-security", hsts);
     }
     return next();
   };
 }
 
-export function rateLimit({ windowMs = 60_000, max = 120, key = (ctx) => ctx.req.socket.remoteAddress || "anon" } = {}) {
+export function rateLimit({
+  windowMs = Number(process.env.RATE_LIMIT_WINDOW_MS || 60_000),
+  max = Number(process.env.RATE_LIMIT_MAX || 120),
+  key = (ctx) => ctx.req.socket.remoteAddress || "anon",
+  store,
+} = {}) {
+  const lazy = { store: store || null, pending: null };
+  async function getStore() {
+    if (lazy.store) return lazy.store;
+    if (!lazy.pending) lazy.pending = createWindowStore({ name: "rate-limit" }).then((s) => { lazy.store = s; return s; });
+    return lazy.pending;
+  }
   return async function rateLimitMiddleware(ctx, next) {
-    const k = key(ctx);
-    const now = Date.now();
-    const row = rateState.get(k) || { count: 0, resetAt: now + windowMs };
-    if (now > row.resetAt) {
-      row.count = 0;
-      row.resetAt = now + windowMs;
-    }
-    row.count += 1;
-    rateState.set(k, row);
+    const s = await getStore();
+    const row = await s.increment(String(key(ctx)), windowMs);
     ctx.res.setHeader("x-ratelimit-limit", String(max));
     ctx.res.setHeader("x-ratelimit-remaining", String(Math.max(0, max - row.count)));
     if (row.count > max) {
-      return { status: 429, json: { ok: false, error: "rate_limited" }, headers: { "retry-after": String(Math.ceil((row.resetAt - now) / 1000)) } };
+      return {
+        status: 429,
+        json: { ok: false, error: "rate_limited" },
+        headers: { "retry-after": String(Math.ceil((row.resetAt - nowMs()) / 1000)) },
+      };
     }
     return next();
   };
 }
 
+export function requestQuota({
+  windowMs = Number(process.env.QUOTA_WINDOW_MS || 60_000),
+  max = Number(process.env.QUOTA_MAX || 600),
+  store,
+} = {}) {
+  const lazy = { store: store || null, pending: null };
+  async function getStore() {
+    if (lazy.store) return lazy.store;
+    if (!lazy.pending) lazy.pending = createWindowStore({ name: "request-quotas" }).then((s) => { lazy.store = s; return s; });
+    return lazy.pending;
+  }
+  return async function requestQuotaMiddleware(ctx, next) {
+    const principal = ctx.user?.id || ctx.req.socket.remoteAddress || "anon";
+    const route = (ctx.pathname || "/").split("/").slice(0, 2).join("/") || "/";
+    const key = `${principal}:${route}`;
+    const s = await getStore();
+    const row = await s.increment(key, windowMs);
+    if (row.count > max) {
+      return {
+        status: 429,
+        json: { ok: false, error: "quota_exceeded", route, principal },
+      };
+    }
+    return next();
+  };
+}
+
+export function abuseGuard({
+  scoreWindowMs = Number(process.env.ABUSE_WINDOW_MS || 120_000),
+  threshold = Number(process.env.ABUSE_THRESHOLD || 80),
+  blockMs = Number(process.env.ABUSE_BLOCK_MS || 300_000),
+} = {}) {
+  const score = new Map();
+  const blocked = new Map();
+  return async function abuseGuardMiddleware(ctx, next) {
+    const key = ctx.req.socket.remoteAddress || "anon";
+    const now = nowMs();
+    const blockUntil = blocked.get(key) || 0;
+    if (blockUntil > now) {
+      return { status: 429, json: { ok: false, error: "abuse_blocked", retryAt: blockUntil } };
+    }
+
+    const row = score.get(key) || { value: 0, resetAt: now + scoreWindowMs };
+    if (now > row.resetAt) {
+      row.value = 0;
+      row.resetAt = now + scoreWindowMs;
+    }
+    const method = (ctx.method || "GET").toUpperCase();
+    row.value += ["POST", "PUT", "PATCH", "DELETE"].includes(method) ? 3 : 1;
+    if ((ctx.pathname || "").startsWith("/api/")) row.value += 1;
+    score.set(key, row);
+
+    if (row.value >= threshold) {
+      blocked.set(key, now + blockMs);
+      return { status: 429, json: { ok: false, error: "abuse_detected", blockedForMs: blockMs } };
+    }
+
+    return next();
+  };
+}
+
 export function csrf({ cookieName = "fs_csrf", headerName = "x-csrf-token" } = {}) {
   return async function csrfMiddleware(ctx, next) {
     const method = ctx.method || "GET";
     if (["GET", "HEAD", "OPTIONS"].includes(method)) {
-      const token = ctx.cookies[cookieName] || createHash("sha256").update(`${Date.now()}-${Math.random()}`).digest("hex");
-      ctx.helpers.setCookie(cookieName, token, { path: "/", sameSite: "Lax" });
+      const token = ctx.cookies[cookieName] || createHash("sha256").update(`${nowMs()}-${Math.random()}`).digest("hex");
+      ctx.helpers.setCookie(cookieName, token, { path: "/", sameSite: "Lax", secure: parseBool(process.env.SESSION_COOKIE_SECURE, false) });
       return next();
     }
     const cookie = ctx.cookies[cookieName];
+    const hasCookieHeader = Boolean(ctx.req.headers.cookie);
+    if (!cookie && !hasCookieHeader) {
+      return next();
+    }
     const header = ctx.req.headers[headerName];
     const token = Array.isArray(header) ? header[0] : header;
     if (!cookie || !token || cookie !== token) {
@@ -52,4 +230,4 @@ export function csrf({ cookieName = "fs_csrf", headerName = "x-csrf-token" } = {
     }
     return next();
   };
-}
+}

package/src/server-runtime.mjs

@@ -1,339 +1 @@
-import { createServer } from "node:http";
-import { existsSync, readFileSync, statSync, watch } from "node:fs";
-import { extname, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { runBuild } from "./build.mjs";
-import { parseCookies, serializeCookie, createSessionManager, requireUser } from "./auth.mjs";
-import { createFileDatabase } from "./db.mjs";
-import { composeMiddleware } from "./middleware.mjs";
-import { readJsonBody, validateShape } from "./validation.mjs";
-import { loadEnv, validateAppEnv } from "./env.mjs";
-import { createLogger } from "./logger.mjs";
-import { createJobQueue } from "./jobs.mjs";
-import { securityHeaders, rateLimit, csrf } from "./security.mjs";
-import { createFileCache } from "./cache.mjs";
-import { createTracer } from "./observability.mjs";
-import { createLocalStorage } from "./storage.mjs";
-
-const DIST_DIR = resolve("dist");
-const DB_DIR = resolve(".fastscript");
-
-function contentType(path) {
-  const ext = extname(path);
-  if (ext === ".html") return "text/html; charset=utf-8";
-  if (ext === ".js") return "application/javascript; charset=utf-8";
-  if (ext === ".css") return "text/css; charset=utf-8";
-  if (ext === ".json") return "application/json; charset=utf-8";
-  if (ext === ".map") return "application/json; charset=utf-8";
-  return "text/plain; charset=utf-8";
-}
-
-function readManifest() {
-  const path = join(DIST_DIR, "fastscript-manifest.json");
-  return JSON.parse(readFileSync(path, "utf8"));
-}
-
-function match(routePath, pathname) {
-  const a = routePath.split("/").filter(Boolean);
-  const b = pathname.split("/").filter(Boolean);
-  if (a.length !== b.length) return null;
-  const params = {};
-  for (let i = 0; i < a.length; i += 1) {
-    if (a[i].startsWith(":")) params[a[i].slice(1)] = b[i];
-    else if (a[i] !== b[i]) return null;
-  }
-  return params;
-}
-
-function resolveRoute(routes, pathname) {
-  for (const route of routes) {
-    const params = match(route.path, pathname);
-    if (params) return { route, params };
-  }
-  return null;
-}
-
-async function importDist(modulePath) {
-  const abs = join(DIST_DIR, modulePath.replace(/^\.\//, ""));
-  const url = `${pathToFileURL(abs).href}?t=${Date.now()}`;
-  return import(url);
-}
-
-function createHelpers(res) {
-  return {
-    json(body, status = 200, headers = {}) {
-      return { status, json: body, headers };
-    },
-    text(body, status = 200, headers = {}) {
-      return { status, body, headers };
-    },
-    redirect(location, status = 302) {
-      return { status, headers: { location } };
-    },
-    setCookie(name, value, opts = {}) {
-      const current = res.getHeader("set-cookie");
-      const next = serializeCookie(name, value, opts);
-      if (!current) res.setHeader("set-cookie", [next]);
-      else res.setHeader("set-cookie", Array.isArray(current) ? [...current, next] : [String(current), next]);
-    },
-  };
-}
-
-function writeResponse(res, payload) {
-  if (!payload) {
-    res.writeHead(204);
-    res.end();
-    return;
-  }
-  const status = payload.status ?? 200;
-  const headers = payload.headers ?? {};
-  if (payload.cookies && payload.cookies.length) headers["set-cookie"] = payload.cookies;
-  if (payload.json !== undefined) {
-    res.writeHead(status, { "content-type": "application/json; charset=utf-8", ...headers });
-    res.end(JSON.stringify(payload.json));
-    return;
-  }
-  res.writeHead(status, { "content-type": "text/plain; charset=utf-8", ...headers });
-  res.end(payload.body ?? "");
-}
-
-function htmlDoc(content, ssrData, hasStyles) {
-  const safe = JSON.stringify(ssrData ?? {}).replace(/</g, "\\u003c");
-  return `<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>FastScript</title>
-    ${hasStyles ? '<link rel="stylesheet" href="/styles.css" />' : ""}
-  </head>
-  <body>
-    <div id="app">${content}</div>
-    <script>window.__FASTSCRIPT_SSR=${safe}</script>
-    <script type="module" src="/router.js"></script>
-  </body>
-</html>`;
-}
-
-export async function runServer({ mode = "development", watchMode = false, buildOnStart = true, port = 4173 } = {}) {
-  loadEnv({ mode });
-  await validateAppEnv();
-
-  const logger = createLogger({ service: "fastscript-server" });
-  const tracer = createTracer({ service: "fastscript-server" });
-  if (buildOnStart) await runBuild();
-
-  const sessions = createSessionManager({ dir: DB_DIR, cookieName: "fs_session", secret: process.env.SESSION_SECRET || "fastscript-dev-secret" });
-  const db = createFileDatabase({ dir: DB_DIR, name: "appdb" });
-  const queue = createJobQueue({ dir: DB_DIR });
-  const cache = createFileCache({ dir: join(DB_DIR, "cache") });
-  const storage = createLocalStorage({ dir: join(DB_DIR, "storage") });
-
-  if (watchMode) {
-    let timer = null;
-    watch(resolve("app"), { recursive: true }, () => {
-      clearTimeout(timer);
-      timer = setTimeout(async () => {
-        try {
-          await runBuild();
-          logger.info("rebuild complete");
-        } catch (error) {
-          logger.error("rebuild failed", { error: error.message });
-        }
-      }, 120);
-    });
-  }
-
-  const server = createServer(async (req, res) => {
-    const requestId = logger.requestId();
-    const start = Date.now();
-    const span = tracer.span("request", { requestId, path: req.url, method: req.method });
-    res.setHeader("x-request-id", requestId);
-
-    try {
-      const url = new URL(req.url || "/", "http://localhost");
-      const pathname = url.pathname;
-      const manifest = readManifest();
-      const helpers = createHelpers(res);
-      const cookies = parseCookies(req.headers.cookie || "");
-      const session = sessions.read(cookies[sessions.cookieName]);
-      sessions.sweepExpired();
-
-      const ctx = {
-        req,
-        res,
-        requestId,
-        pathname,
-        method: (req.method || "GET").toUpperCase(),
-        params: {},
-        query: Object.fromEntries(url.searchParams.entries()),
-        cookies,
-        user: session?.user ?? null,
-        db,
-        queue,
-        cache,
-        storage,
-        auth: {
-          login: (user, opts = {}) => {
-            const token = sessions.create(user, opts.maxAge ?? 60 * 60 * 24 * 7);
-            helpers.setCookie(sessions.cookieName, token, { path: "/", httpOnly: true, maxAge: opts.maxAge ?? 60 * 60 * 24 * 7 });
-            return token;
-          },
-          logout: () => {
-            sessions.delete(cookies[sessions.cookieName]);
-            helpers.setCookie(sessions.cookieName, "", { path: "/", httpOnly: true, maxAge: 0 });
-          },
-          requireUser: () => requireUser(session?.user ?? null),
-          rotate: (opts = {}) => {
-            const token = sessions.rotate(cookies[sessions.cookieName], opts.maxAge ?? 60 * 60 * 24 * 7);
-            if (token) helpers.setCookie(sessions.cookieName, token, { path: "/", httpOnly: true, maxAge: opts.maxAge ?? 60 * 60 * 24 * 7 });
-            return token;
-          },
-        },
-        input: {
-          body: null,
-          query: Object.fromEntries(url.searchParams.entries()),
-          async readJson() {
-            if (ctx.input.body !== null) return ctx.input.body;
-            ctx.input.body = await readJsonBody(req);
-            return ctx.input.body;
-          },
-          validateQuery(schema) {
-            return validateShape(schema, ctx.query, "query").value;
-          },
-          async validateBody(schema) {
-            const body = await ctx.input.readJson();
-            return validateShape(schema, body, "body").value;
-          },
-        },
-        helpers,
-      };
-
-      const isBodyMethod = !["GET", "HEAD"].includes(ctx.method);
-      const contentTypeHeader = String(req.headers["content-type"] || "");
-      if (isBodyMethod && contentTypeHeader.includes("application/json")) {
-        ctx.input.body = await ctx.input.readJson();
-      }
-
-      const target = join(DIST_DIR, pathname === "/" ? "index.html" : pathname.slice(1));
-      if (pathname.startsWith("/__storage/")) {
-        const key = pathname.slice("/__storage/".length);
-        const file = storage.get(key);
-        if (!file) {
-          writeResponse(res, { status: 404, body: "Not found" });
-          span.end({ status: 404, kind: "storage" });
-          return;
-        }
-        res.writeHead(200, { "content-type": "application/octet-stream" });
-        res.end(file);
-        span.end({ status: 200, kind: "storage" });
-        return;
-      }
-      if (existsSync(target) && statSync(target).isFile() && !pathname.endsWith(".html")) {
-        const body = readFileSync(target);
-        res.writeHead(200, { "content-type": contentType(target) });
-        res.end(body);
-        logger.info("static", { requestId, path: pathname, status: 200, ms: Date.now() - start });
-        span.end({ status: 200, kind: "static" });
-        return;
-      }
-
-      const middlewareList = [];
-      middlewareList.push(securityHeaders(), rateLimit());
-      if (process.env.CSRF_PROTECT === "1") middlewareList.push(csrf());
-      if (manifest.middleware) {
-        const mm = await importDist(manifest.middleware);
-        if (Array.isArray(mm.middlewares)) middlewareList.push(...mm.middlewares);
-        else if (typeof mm.middleware === "function") middlewareList.push(mm.middleware);
-        else if (typeof mm.default === "function") middlewareList.push(mm.default);
-      }
-      const runWithMiddleware = composeMiddleware(middlewareList);
-
-      const out = await runWithMiddleware(ctx, async () => {
-        if (pathname.startsWith("/api/")) {
-          const apiHit = resolveRoute(manifest.apiRoutes, pathname);
-          if (!apiHit) return { status: 404, body: "API route not found" };
-          ctx.params = apiHit.params;
-          const mod = await importDist(apiHit.route.module);
-          const handler = mod[ctx.method];
-          if (typeof handler !== "function") return { status: 405, body: `Method ${ctx.method} not allowed` };
-          if (mod.schemas?.[ctx.method]) {
-            ctx.input.body = await ctx.input.readJson();
-            validateShape(mod.schemas[ctx.method], ctx.input.body, "body");
-          }
-          return handler(ctx, helpers);
-        }
-
-        const hit = resolveRoute(manifest.routes, pathname);
-        if (!hit) {
-          if (manifest.notFound) {
-            const nfMod = await importDist(manifest.notFound);
-            const body = nfMod.default ? nfMod.default({ pathname }) : "<h1>404</h1>";
-            return { status: 404, html: body, data: null };
-          }
-          return { status: 404, body: "Not found" };
-        }
-
-        ctx.params = hit.params;
-        const mod = await importDist(hit.route.module);
-
-        if (!["GET", "HEAD"].includes(ctx.method) && typeof mod[ctx.method] === "function") {
-          if (mod.schemas?.[ctx.method]) {
-            ctx.input.body = await ctx.input.readJson();
-            validateShape(mod.schemas[ctx.method], ctx.input.body, "body");
-          }
-          return mod[ctx.method](ctx, helpers);
-        }
-
-        let data = {};
-        if (typeof mod.load === "function") data = (await mod.load({ ...ctx, params: hit.params, pathname })) || {};
-        let html = mod.default ? mod.default({ ...data, params: hit.params, pathname, user: ctx.user }) : "";
-
-        if (manifest.layout) {
-          const layout = await importDist(manifest.layout);
-          html = layout.default ? layout.default({ content: html, pathname, user: ctx.user }) : html;
-        }
-
-        return { status: 200, html, data };
-      });
-
-      if (out?.html !== undefined) {
-        const hasStyles = existsSync(join(DIST_DIR, "styles.css"));
-        const payload = { pathname, data: out.data ?? null };
-        res.writeHead(out.status ?? 200, { "content-type": "text/html; charset=utf-8" });
-        res.end(htmlDoc(out.html, payload, hasStyles));
-        logger.info("ssr", { requestId, path: pathname, status: out.status ?? 200, ms: Date.now() - start });
-        span.end({ status: out.status ?? 200, kind: "ssr" });
-        return;
-      }
-
-      writeResponse(res, out);
-      logger.info("response", { requestId, path: pathname, status: out?.status ?? 200, ms: Date.now() - start });
-      span.end({ status: out?.status ?? 200, kind: "response" });
-    } catch (error) {
-      const status = error?.status && Number.isInteger(error.status) ? error.status : 500;
-      const payload = {
-        ok: false,
-        error: {
-          message: error?.message || "Unknown error",
-          status,
-          details: error?.details || null,
-        },
-      };
-      const wantsJson = (req.headers.accept || "").includes("application/json") || (req.url || "").startsWith("/api/");
-      if (wantsJson) {
-        res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
-        res.end(JSON.stringify(payload));
-      } else {
-        res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
-        res.end(`<!doctype html><html><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Error</title><style>body{background:#050505;color:#fff;font:16px/1.6 ui-sans-serif,system-ui;padding:40px}code{color:#9f92ff}</style></head><body><h1>Something went wrong</h1><p>Please retry or roll back to the previous deploy.</p><p>Request ID: <code>${requestId}</code></p></body></html>`);
-      }
-      logger.error("request_error", { requestId, status, path: req.url, error: payload.error.message });
-      span.end({ status, error: payload.error.message, kind: "error" });
-    }
-  });
-
-  server.listen(port, () => {
-    logger.info("server_started", { mode, port, watchMode });
-  });
-}
+export * from "@fastscript/core-private/server-runtime";

package/src/serverless-handler.mjs

@@ -0,0 +1,20 @@
+import { runServer } from "./server-runtime.mjs";
+
+let serverPromise = null;
+
+async function getServer() {
+  if (!serverPromise) {
+    serverPromise = runServer({
+      mode: process.env.NODE_ENV || "production",
+      watchMode: false,
+      buildOnStart: false,
+      listen: false,
+    });
+  }
+  return serverPromise;
+}
+
+export default async function handler(req, res) {
+  const server = await getServer();
+  server.emit("request", req, res);
+}

package/src/session-policy.mjs

@@ -0,0 +1,38 @@
+function parseBool(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (value === true || value === "true" || value === "1") return true;
+  if (value === false || value === "false" || value === "0") return false;
+  return fallback;
+}
+
+export function resolveSessionPolicy({ env = process.env, mode = env.NODE_ENV || "development" } = {}) {
+  const production = mode === "production";
+  const secret = String(env.SESSION_SECRET || "");
+  const cookieName = String(env.SESSION_COOKIE_NAME || "fs_session");
+  const secure = parseBool(env.SESSION_COOKIE_SECURE, production);
+  const sameSite = String(env.SESSION_COOKIE_SAMESITE || "Lax");
+  const maxAgeSec = Number(env.SESSION_MAX_AGE_SEC || 60 * 60 * 24 * 7);
+  const rotateOnRead = parseBool(env.SESSION_ROTATE_ON_READ, production);
+
+  if (production) {
+    if (!secret) throw new Error("SESSION_SECRET is required in production.");
+    if (secret.length < 32) throw new Error("SESSION_SECRET must be at least 32 characters in production.");
+    if (!secure) throw new Error("SESSION_COOKIE_SECURE must be enabled in production.");
+    if (!["Lax", "Strict", "None"].includes(sameSite)) {
+      throw new Error("SESSION_COOKIE_SAMESITE must be one of: Lax, Strict, None.");
+    }
+  }
+
+  return {
+    secret: secret || "fastscript-dev-secret",
+    cookie: {
+      name: cookieName,
+      secure,
+      sameSite,
+      maxAgeSec: Number.isFinite(maxAgeSec) && maxAgeSec > 0 ? maxAgeSec : 60 * 60 * 24 * 7,
+      httpOnly: true,
+      path: "/",
+    },
+    rotateOnRead,
+  };
+}