jskelet 0.1.1 → 0.1.3

package/src/config/index.js

@@ -15,21 +15,28 @@
  *   headers()   → [{ source, headers: [{ key, value }] }]
  *   redirects() → [{ source, destination, permanent?, statusCode? }]
  *   rewrites()  → [{ source, destination }] | { beforeFiles?, afterFiles? }
- *   cache()     → { html?: { [source]: saniye }, prewarm?: {...} }
+ *   cache()     → { html?: { [source]: saniye }, maxEntries?: number,
+ *                   data?: {...}, prewarm?: {...} }
+ *
+ * Fonksiyon olmayan bölümler (`brand`, `security`, `static`, `navigation`…)
+ * düz nesne olarak okunur.
  */
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
-import { compilePattern } from "./pattern.js";
+import { compilePattern, matchPattern } from "./pattern.js";
 import {
   DEFAULT_BRAND,
+  DEFAULT_DATA_CACHE,
   DEFAULT_DEV_GATE_BYPASS,
   DEFAULT_DIRS,
+  DEFAULT_HTML_CACHE_MAX_ENTRIES,
   DEFAULT_NAVIGATION,
   DEFAULT_NAVIGATION_EXCLUDE,
   DEFAULT_PREWARM,
   DEFAULT_PREWARM_SKIP,
+  DEFAULT_SECURITY,
   DEFAULT_STATIC,
 } from "./defaults.js";
 
@@ -59,7 +66,10 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ pattern: CompiledPattern, destination: string, statusCode: number }[]} redirects
  * @property {{ phase: "beforeFiles" | "afterFiles", pattern: CompiledPattern, destination: string }[]} rewrites
  * @property {{ pattern: CompiledPattern, seconds: number }[]} html
+ * @property {number} htmlMaxEntries HTML önbelleğinin girdi sınırı.
+ * @property {Record<string, unknown>} data Upstream veri önbelleği ayarları.
  * @property {Record<string, unknown>} prewarm
+ * @property {{ source: string, test: (pathname: string) => boolean }[]} prewarmPriority
  * @property {Record<string, unknown>} brand
  * @property {Record<string, Function>} hooks
  * @property {string} layout Layout `.ejs` dosyasının mutlak yolu.
@@ -68,6 +78,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {string[]} devGateBypass
  * @property {string[]} preconnect
  * @property {NavigationConfig} navigation
+ * @property {SecurityConfig} security
  * @property {string[]} prewarmSkip
  * @property {string[]} watch Dev sunucusunun izlediği ek dizinler.
  * @property {{ family: string, slug?: string, weights: number[] }[]} fonts
@@ -87,7 +98,7 @@ let config = null;
 function asArray(value, label) {
   if (value == null) return [];
   if (Array.isArray(value)) return value;
-  console.warn(`[config] ${label} bir dizi döndürmeli, yok sayıldı`);
+  console.warn(`[config] ${label} must return an array, ignoring it`);
   return [];
 }
 
@@ -162,9 +173,41 @@ function normalizeRewrites(raw) {
   return out;
 }
 
+/**
+ * Isıtma sırası desenleri. İki biçim kabul edilir: config'in her yerinde
+ * geçerli olan `/haber/:slug` sözdizimi ve doğrudan `RegExp` — ikincisi
+ * "sonu `-yorumlar` ile bitenler" gibi desen sözdiziminin karşılamadığı
+ * kuralları yazabilmek için.
+ *
+ * @param {unknown} raw
+ * @returns {ResolvedConfig["prewarmPriority"]}
+ */
+function normalizePriority(raw) {
+  /** @type {ResolvedConfig["prewarmPriority"]} */
+  const out = [];
+
+  for (const entry of asArray(raw, "cache().prewarm.priority")) {
+    if (entry instanceof RegExp) {
+      out.push({ source: String(entry), test: (pathname) => entry.test(pathname) });
+      continue;
+    }
+
+    const pattern = compilePattern(entry);
+    if (!pattern) continue;
+    out.push({
+      source: pattern.source,
+      test: (pathname) => matchPattern(pattern, pathname) !== null,
+    });
+  }
+
+  return out;
+}
+
 /**
  * @param {unknown} raw
- * @returns {{ html: ResolvedConfig["html"], prewarm: Record<string, unknown> }}
+ * @returns {{ html: ResolvedConfig["html"], htmlMaxEntries: number,
+ *   data: Record<string, unknown>, prewarm: Record<string, unknown>,
+ *   prewarmPriority: ResolvedConfig["prewarmPriority"] }}
  */
 function normalizeCache(raw) {
   /** @type {ResolvedConfig["html"]} */
@@ -177,7 +220,21 @@ function normalizeCache(raw) {
     html.push({ pattern, seconds: value });
   }
 
-  return { html, prewarm: { ...DEFAULT_PREWARM, ...(raw?.prewarm ?? {}) } };
+  const prewarm = { ...DEFAULT_PREWARM, ...(raw?.prewarm ?? {}) };
+  const maxEntries = Number(raw?.maxEntries);
+
+  return {
+    html,
+    htmlMaxEntries:
+      Number.isFinite(maxEntries) && maxEntries > 0
+        ? Math.floor(maxEntries)
+        : DEFAULT_HTML_CACHE_MAX_ENTRIES,
+    data: { ...DEFAULT_DATA_CACHE, ...(raw?.data ?? {}) },
+    // Desenler derlenmiş hâlde ayrı alanda tutulur: `prewarm` sayısal
+    // ayarların düz torbası olarak kalsın, her turda yeniden derlenmesin.
+    prewarm,
+    prewarmPriority: normalizePriority(prewarm.priority),
+  };
 }
 
 /** Speculation Rules'un tanıdığı eagerness değerleri. */
@@ -201,7 +258,7 @@ function normalizeEagerness(value, fallback, label) {
   }
 
   console.warn(
-    `[config] navigation.${label} geçersiz (${String(value)}), varsayılana dönüldü`,
+    `[config] navigation.${label} is invalid (${String(value)}), falling back to the default`,
   );
   return fallback;
 }
@@ -240,6 +297,50 @@ function normalizeNavigation(raw, brand) {
   };
 }
 
+/**
+ * @typedef {object} SecurityConfig
+ * @property {boolean} trustProxy
+ * @property {string | null} cookieSecret
+ * @property {{ enabled: boolean, token: boolean, allowedOrigins: string[],
+ *   exclude: CompiledPattern[], cookieName: string, fieldName: string,
+ *   headerName: string }} csrf
+ */
+
+/**
+ * Güvenlik bölümü. `csrf.exclude` desenleri burada derlenir: her istekte
+ * yeniden derlemek gereksiz, ve bozuk bir desen sunucuyu düşürmemeli.
+ *
+ * @param {unknown} raw
+ * @returns {SecurityConfig}
+ */
+function normalizeSecurity(raw) {
+  const source = /** @type {Record<string, any>} */ (raw ?? {});
+  const csrf = { ...DEFAULT_SECURITY.csrf, ...(source.csrf ?? {}) };
+
+  const exclude = asArray(csrf.exclude, "security.csrf.exclude")
+    .map((entry) => compilePattern(entry))
+    .filter((pattern) => pattern !== null);
+
+  return {
+    trustProxy: source.trustProxy !== false,
+    cookieSecret:
+      typeof source.cookieSecret === "string" && source.cookieSecret
+        ? source.cookieSecret
+        : null,
+    csrf: {
+      enabled: csrf.enabled !== false,
+      token: csrf.token === true,
+      allowedOrigins: asArray(csrf.allowedOrigins, "security.csrf.allowedOrigins")
+        .filter((entry) => typeof entry === "string")
+        .map(String),
+      exclude: /** @type {CompiledPattern[]} */ (exclude),
+      cookieName: String(csrf.cookieName ?? DEFAULT_SECURITY.csrf.cookieName),
+      fieldName: String(csrf.fieldName ?? DEFAULT_SECURITY.csrf.fieldName),
+      headerName: String(csrf.headerName ?? DEFAULT_SECURITY.csrf.headerName).toLowerCase(),
+    },
+  };
+}
+
 /**
  * Dizin adlarını mutlak yola çevirir. `styles` bir dosya yolu olduğu için
  * de aynı çözümlemeden geçer; ayrı bir alan tutmaya değmez.
@@ -307,7 +408,7 @@ export async function loadConfig(options = {}) {
 
   if (!fs.existsSync(configPath)) {
     console.warn(
-      `[config] ${configFile} bulunamadı — yerleşik varsayılanlarla devam ediliyor.`,
+      `[config] ${configFile} not found — continuing with built-in defaults.`,
     );
   } else {
     try {
@@ -316,7 +417,7 @@ export async function loadConfig(options = {}) {
       source = module.default ?? module;
       loaded = true;
     } catch (error) {
-      console.warn(`[config] ${configFile} yüklenemedi, yok sayıldı`, error);
+      console.warn(`[config] ${configFile} failed to load, ignoring it`, error);
     }
   }
 
@@ -327,7 +428,7 @@ export async function loadConfig(options = {}) {
     try {
       return typeof value === "function" ? await value.call(source) : value;
     } catch (error) {
-      console.warn(`[config] ${name}() hata verdi, yok sayıldı`, error);
+      console.warn(`[config] ${name}() threw, ignoring it`, error);
       return null;
     }
   };
@@ -339,7 +440,8 @@ export async function loadConfig(options = {}) {
     section("cache"),
   ]);
 
-  const { html, prewarm } = normalizeCache(cache);
+  const { html, htmlMaxEntries, data, prewarm, prewarmPriority } =
+    normalizeCache(cache);
   const dirs = resolveDirs(root, source.paths);
   const brand = { ...DEFAULT_BRAND, ...(source.brand ?? {}) };
 
@@ -351,7 +453,10 @@ export async function loadConfig(options = {}) {
     redirects: normalizeRedirects(redirects),
     rewrites: normalizeRewrites(rewrites),
     html,
+    htmlMaxEntries,
+    data,
     prewarm,
+    prewarmPriority,
     brand,
     hooks: source.hooks ?? {},
     layout: resolveLayout(dirs, source.layout),
@@ -363,6 +468,7 @@ export async function loadConfig(options = {}) {
     devGateBypass: source.devGateBypass ?? DEFAULT_DEV_GATE_BYPASS,
     preconnect: source.preconnect ?? [],
     navigation: normalizeNavigation(source.navigation, brand),
+    security: normalizeSecurity(source.security),
     prewarmSkip: source.prewarmSkip ?? DEFAULT_PREWARM_SKIP,
     // `routes`, `views` ve `lib` zaten izlenir; buraya yalnızca ek dizinler.
     watch: source.watch ?? [],
@@ -377,15 +483,20 @@ export async function loadConfig(options = {}) {
   // Dev'de build ve sunucu ayrı alt süreçler; üçü de aynı özeti basınca satır
   // banner'ın ve build bloğunun arasına üç kez giriyor. Özeti dış süreç basar.
   if (loaded && !process.env.JSKELET_CHILD) {
+    /** @param {number} count @param {string} singular @param {string} plural */
+    const label = (count, singular, plural) =>
+      `${count} ${count === 1 ? singular : plural}`;
+
     const counts = [
-      config.headers.length && `${config.headers.length} header`,
-      config.redirects.length && `${config.redirects.length} redirect`,
-      config.rewrites.length && `${config.rewrites.length} rewrite`,
-      config.html.length && `${config.html.length} cache kuralı`,
+      config.headers.length && label(config.headers.length, "header", "headers"),
+      config.redirects.length &&
+        label(config.redirects.length, "redirect", "redirects"),
+      config.rewrites.length && label(config.rewrites.length, "rewrite", "rewrites"),
+      config.html.length && label(config.html.length, "cache rule", "cache rules"),
     ].filter(Boolean);
 
     if (counts.length) {
-      console.log(`[config] ${configFile} yüklendi — ${counts.join(", ")}`);
+      console.log(`[config] ${configFile} loaded — ${counts.join(", ")}`);
     }
   }
 
@@ -402,8 +513,8 @@ export async function loadConfig(options = {}) {
 export function getConfig() {
   if (!config) {
     throw new Error(
-      "[config] loadConfig() çağrılmadan getConfig() kullanıldı. " +
-        "Sunucuyu `jskelet` CLI ile ya da createApp() üzerinden başlatın.",
+      "[config] getConfig() was used before loadConfig(). " +
+        "Start the server with the `jskelet` CLI or through createApp().",
     );
   }
   return config;
@@ -427,7 +538,7 @@ export async function hook(name, fallback, ...args) {
   try {
     return await fn(...args);
   } catch (error) {
-    console.warn(`[config] hooks.${name}() hata verdi, varsayılan kullanıldı`, error);
+    console.warn(`[config] hooks.${name}() threw, using the default`, error);
     return fallback;
   }
 }

package/src/config/pattern.js

@@ -28,7 +28,7 @@ function escapeLiteral(text) {
  */
 export function compilePattern(source) {
   if (typeof source !== "string" || !source.startsWith("/")) {
-    console.warn(`[config] geçersiz source (\`/\` ile başlamalı): ${source}`);
+    console.warn(`[config] invalid source (must start with \`/\`): ${source}`);
     return null;
   }
 

package/src/dev-server.mjs

@@ -350,7 +350,7 @@ function watchSources() {
       });
     } catch {
       log.warn(
-        `${path.relative(ROOT, target)} izlenemedi; bu dizinde otomatik restart olmayacak.`,
+        `could not watch ${path.relative(ROOT, target)}; no auto restart for this directory.`,
       );
     }
   }

package/src/http/control-flow.js

@@ -14,7 +14,7 @@ export class NotFoundError extends Error {
 export class RedirectError extends Error {
   /**
    * @param {string} location
-   * @param {301 | 302 | 307 | 308} [statusCode]
+   * @param {301 | 302 | 303 | 307 | 308} [statusCode]
    */
   constructor(location, statusCode = 307) {
     super(`Redirect to ${location}`);
@@ -45,6 +45,21 @@ export function redirect(location) {
   throw new RedirectError(location, 307);
 }
 
+/**
+ * POST sonrası yönlendirme (303 See Other).
+ *
+ * `redirect()` 307 kullanır ve 307 **metodu korur**: bir POST handler'ından
+ * çağrıldığında tarayıcı hedefe yeniden POST eder. Form gönderiminden sonra
+ * sayfayı GET olarak açmak — yani geri tuşunun formu yeniden göndermediği
+ * klasik "post/redirect/get" akışı — 303 gerektiriyor.
+ *
+ * @param {string} location
+ * @returns {never}
+ */
+export function seeOther(location) {
+  throw new RedirectError(location, 303);
+}
+
 /** @param {unknown} error */
 export function isNotFoundError(error) {
   return error instanceof NotFoundError;

package/src/http/cookies.js

@@ -0,0 +1,257 @@
+/**
+ * Cookie okuma/yazma ve HMAC ile imzalama.
+ *
+ * Neden framework'te: kişiye özel her sayfa bir oturum cookie'sine dayanıyor
+ * ve bunu elle yazan her proje aynı üç hatayı tekrar ediyor — `HttpOnly`
+ * unutmak, imzasız değere güvenmek, karşılaştırmayı `===` ile yapmak.
+ * Burada varsayılanlar güvenli tarafta ve imza doğrulaması sabit zamanlı.
+ *
+ * Framework **kimlik sağlamaz**: oturumun içinde ne olduğu, ne kadar
+ * yaşadığı ve kimin verdiği uygulamanın kararı. Buradaki yüzey yalnızca
+ * "bu değeri ben yazdım, kurcalanmamış" garantisini veriyor.
+ *
+ * Bağımlılık eklenmez; `node:crypto` yeterli.
+ */
+import crypto from "node:crypto";
+import process from "node:process";
+import { getConfig } from "../config/index.js";
+import { markTainted } from "./request-context.js";
+
+/** Ayrıştırılmış cookie'ler istek başına bir kez hesaplanır. */
+const PARSED = Symbol("jskelet.cookies");
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function base64url(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+
+/**
+ * @param {string} value
+ * @returns {string | null}
+ */
+function fromBase64url(value) {
+  try {
+    return Buffer.from(value, "base64url").toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * İmza sırrı. `security.cookieSecret` ya da `JSKELET_SECRET`.
+ *
+ * Yokluğunda imzasız cookie yazmak en kötü sonuç olurdu: uygulama kendini
+ * güvende sanar, değer kurcalanabilir. Bu yüzden imzalı API sır olmadan
+ * hata verir — config hatasının siteyi düşürmemesi kuralı burada geçmez,
+ * çünkü sessiz alternatif bir güvenlik açığı.
+ *
+ * @returns {string}
+ */
+function getSecret() {
+  /** @type {string | null} */
+  let configured = null;
+
+  try {
+    configured = getConfig().security.cookieSecret;
+  } catch {
+    // Config yüklenmemiş olabilir (script, test); env yine de geçerli.
+    configured = null;
+  }
+
+  const secret = configured ?? process.env.JSKELET_SECRET ?? null;
+
+  if (!secret) {
+    throw new Error(
+      "[cookies] a secret is required for signed cookies. Set " +
+        "`security.cookieSecret` in `jskelet.config.mjs` or the JSKELET_SECRET environment variable.",
+    );
+  }
+
+  return secret;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function sign(value) {
+  return crypto.createHmac("sha256", getSecret()).update(value).digest("base64url");
+}
+
+/**
+ * Sabit zamanlı karşılaştırma: imza doğrulamasında erken çıkış, saldırganın
+ * baytları tek tek tahmin etmesine kapı aralar.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function safeEqual(a, b) {
+  const left = Buffer.from(String(a));
+  const right = Buffer.from(String(b));
+  if (left.length !== right.length) return false;
+  return crypto.timingSafeEqual(left, right);
+}
+
+/**
+ * `Cookie` başlığını ayrıştırır.
+ *
+ * Okuma çıktının kullanıcıya bağlı olduğunu bildirir: bu sayfa artık public
+ * HTML cache'ine yazılamaz.
+ *
+ * @param {import('http').IncomingMessage} req
+ * @returns {Record<string, string>}
+ */
+export function parseCookies(req) {
+  markTainted("parseCookies(req)");
+
+  const cached = /** @type {any} */ (req)[PARSED];
+  if (cached) return cached;
+
+  /** @type {Record<string, string>} */
+  const out = {};
+  const header = req.headers?.cookie;
+
+  if (header) {
+    for (const part of header.split(";")) {
+      const index = part.indexOf("=");
+      if (index === -1) continue;
+
+      const name = part.slice(0, index).trim();
+      if (!name) continue;
+
+      try {
+        out[name] = decodeURIComponent(part.slice(index + 1).trim());
+      } catch {
+        // Bozuk yüzde kodlaması tüm başlığı çöpe atmamalı.
+        out[name] = part.slice(index + 1).trim();
+      }
+    }
+  }
+
+  /** @type {any} */ (req)[PARSED] = out;
+  return out;
+}
+
+/**
+ * @typedef {object} CookieOptions
+ * @property {string} [path] Varsayılan `/`.
+ * @property {string} [domain]
+ * @property {number} [maxAge] Saniye.
+ * @property {Date} [expires]
+ * @property {boolean} [httpOnly] Varsayılan `true`.
+ * @property {boolean} [secure] Varsayılan: development dışında `true`.
+ * @property {"Strict" | "Lax" | "None"} [sameSite] Varsayılan `Lax`.
+ */
+
+/**
+ * Varsayılanlar bilinçli olarak kısıtlayıcı: `HttpOnly` ile JS okuyamaz,
+ * `SameSite=Lax` ile çapraz site POST'larında gönderilmez (CSRF'nin büyük
+ * kısmını kapatan tek satır), `Secure` üretimde açık.
+ *
+ * @param {string} name
+ * @param {string} value
+ * @param {CookieOptions} [options]
+ * @returns {string}
+ */
+export function serializeCookie(name, value, options = {}) {
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+
+  parts.push(`Path=${options.path ?? "/"}`);
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (options.maxAge !== undefined) parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
+  if (options.httpOnly !== false) parts.push("HttpOnly");
+  if (options.secure ?? process.env.NODE_ENV !== "development") parts.push("Secure");
+  parts.push(`SameSite=${options.sameSite ?? "Lax"}`);
+
+  return parts.join("; ");
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {string} name
+ * @param {string} value
+ * @param {CookieOptions} [options]
+ */
+export function setCookie(res, name, value, options = {}) {
+  const existing = res.getHeader("Set-Cookie");
+  const serialized = serializeCookie(name, value, options);
+
+  /** @type {string[]} */
+  const all = existing
+    ? Array.isArray(existing)
+      ? [...existing.map(String)]
+      : [String(existing)]
+    : [];
+
+  all.push(serialized);
+  res.setHeader("Set-Cookie", all);
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {string} name
+ * @param {CookieOptions} [options]
+ */
+export function clearCookie(res, name, options = {}) {
+  setCookie(res, name, "", { ...options, maxAge: 0, expires: new Date(0) });
+}
+
+/**
+ * İmzalı cookie yazar. Değer okunabilir kalır (şifreleme değil, imza);
+ * gizli kalması gereken veriyi cookie'ye koymayın, kimliğini koyun.
+ *
+ * @param {import('http').ServerResponse} res
+ * @param {string} name
+ * @param {string} value
+ * @param {CookieOptions} [options]
+ */
+export function setSignedCookie(res, name, value, options = {}) {
+  const encoded = base64url(value);
+  setCookie(res, name, `${encoded}.${sign(encoded)}`, options);
+}
+
+/**
+ * İmzalı cookie okur. İmza uymuyorsa `null` — bozuk imza, yok sayılmalı,
+ * "belki geçerlidir" diye kullanılmamalı.
+ *
+ * @param {import('http').IncomingMessage} req
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function getSignedCookie(req, name) {
+  const raw = parseCookies(req)[name];
+  if (!raw) return null;
+
+  const index = raw.lastIndexOf(".");
+  if (index <= 0) return null;
+
+  const encoded = raw.slice(0, index);
+  const signature = raw.slice(index + 1);
+
+  let expected;
+  try {
+    expected = sign(encoded);
+  } catch {
+    // Sır yoksa imzalı okuma sessizce başarısız olur: sunucu ayakta kalır
+    // ama hiçbir oturum geçerli sayılmaz.
+    return null;
+  }
+
+  if (!safeEqual(signature, expected)) return null;
+  return fromBase64url(encoded);
+}
+
+/**
+ * Kriptografik rastgele token. CSRF token'ı ve oturum kimliği için.
+ *
+ * @param {number} [bytes]
+ * @returns {string}
+ */
+export function randomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString("base64url");
+}