jskelet 0.1.1 → 0.1.3

package/src/http/request-context.js

@@ -0,0 +1,162 @@
+/**
+ * İstek başına yaşayan bağlam.
+ *
+ * `request-cache.js` ile aynı desen: `AsyncLocalStorage`, bağlam yoksa her şey
+ * sessizce devre dışı. Ayrı bir modül olmasının sebebi, taşıdığı bilginin
+ * memoizasyondan farklı olması — burada tutulanlar bir isteğin **cache'lenip
+ * cache'lenemeyeceğine** dair kararlar:
+ *
+ *   private  → route açıkça "bu sayfa kişiye özel" dedi
+ *   tainted  → controller cookie/Authorization okudu, yani çıktı kullanıcıya
+ *              bağlı olabilir; HTML cache'e yazmak sızıntı olur
+ *   csrfToken → bu istek için üretilmiş token; `csrfField()` şablonda basar
+ *   res      → token cookie'sini yazabilmek için; başka hiçbir şey için
+ *              kullanılmaz, şablonlara yanıt nesnesi sızmaz
+ *
+ * `tainted` bir tahmin değil, gözlem: `markTainted()` yalnızca gerçekten
+ * kimliğe dokunan bir erişimden sonra çağrılır (bkz. `guardRequest`).
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * @typedef {object} RequestContext
+ * @property {boolean} private Route `private: true` ile mi kaydedildi.
+ * @property {boolean} tainted Kimliğe bağlı bir veri okundu mu.
+ * @property {string[]} taintReasons Hangi erişimler işaretledi (teşhis için).
+ * @property {string | null} csrfToken
+ * @property {import('express').Response | null} res
+ */
+
+/** @type {AsyncLocalStorage<RequestContext>} */
+const storage = new AsyncLocalStorage();
+
+/**
+ * @param {{ private?: boolean, res?: import('express').Response }} [initial]
+ * @returns {RequestContext}
+ */
+export function createRequestContext(initial = {}) {
+  return {
+    private: initial.private === true,
+    tainted: false,
+    taintReasons: [],
+    csrfToken: null,
+    res: initial.res ?? null,
+  };
+}
+
+/**
+ * İsteği verilen bağlam içinde çalıştırır.
+ *
+ * @template T
+ * @param {RequestContext} context
+ * @param {() => T} run
+ * @returns {T}
+ */
+export function withRequestContext(context, run) {
+  return storage.run(context, run);
+}
+
+/**
+ * @returns {RequestContext | undefined}
+ */
+export function getRequestContext() {
+  return storage.getStore();
+}
+
+/**
+ * Çıktının kullanıcıya bağlı olduğunu bildirir. Bağlam yoksa (script, build,
+ * fragment dışı kullanım) sessizce yok sayılır.
+ *
+ * @param {string} reason Teşhis mesajında görünecek erişim adı.
+ */
+export function markTainted(reason) {
+  const context = storage.getStore();
+  if (!context) return;
+
+  context.tainted = true;
+  if (!context.taintReasons.includes(reason)) {
+    context.taintReasons.push(reason);
+  }
+}
+
+
+/** Okunması çıktıyı kullanıcıya bağlayan başlıklar. */
+const SENSITIVE_HEADERS = new Set([
+  "cookie",
+  "authorization",
+  "proxy-authorization",
+]);
+
+/** Okunması çıktıyı kullanıcıya bağlayan `req` alanları. */
+const SENSITIVE_PROPS = new Set(["cookies", "signedCookies", "session", "user"]);
+
+/**
+ * @param {Record<string, unknown>} headers
+ * @returns {Record<string, unknown>}
+ */
+function guardHeaders(headers) {
+  return new Proxy(headers, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && SENSITIVE_HEADERS.has(prop.toLowerCase())) {
+        markTainted(`req.headers.${prop}`);
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}
+
+/**
+ * Controller'a giden `req`'i kimliğe dokunan erişimleri işaretleyen bir Proxy
+ * ile sarar.
+ *
+ * Neden gerekli: HTML cache anahtarı yalnızca yol + query. Cookie okuyan bir
+ * controller cache'lenebilir bir route'a bağlanmışsa bir kullanıcının HTML'i
+ * bir başkasına servis edilir ve bu hiçbir yerde hata olarak görünmez.
+ * İşaretleme, sessiz sızıntıyı gürültülü bir uyarıya çeviriyor.
+ *
+ * Kapsam bilinçli olarak dar: yalnızca *okuma* yakalanır, yazma ve metot
+ * çağrıları hedefe dokunulmadan geçer. Proxy'nin prototipi korunduğu için
+ * `req instanceof IncomingMessage` gibi kontroller etkilenmez.
+ *
+ * @param {import('express').Request} req
+ * @returns {import('express').Request}
+ */
+export function guardRequest(req) {
+  /** @type {Record<string, unknown> | null} */
+  let headersProxy = null;
+
+  return new Proxy(req, {
+    get(target, prop, receiver) {
+      if (prop === "headers" || prop === "headersDistinct") {
+        const raw = Reflect.get(target, prop, receiver);
+        if (!raw || typeof raw !== "object") return raw;
+        if (prop === "headers") {
+          headersProxy ??= guardHeaders(/** @type {Record<string, unknown>} */ (raw));
+          return headersProxy;
+        }
+        return guardHeaders(/** @type {Record<string, unknown>} */ (raw));
+      }
+
+      if (prop === "get" || prop === "header") {
+        const original = Reflect.get(target, prop, receiver);
+        if (typeof original !== "function") return original;
+        return function guardedHeaderLookup(/** @type {string} */ name) {
+          if (typeof name === "string" && SENSITIVE_HEADERS.has(name.toLowerCase())) {
+            markTainted(`req.get("${name}")`);
+          }
+          return original.call(target, name);
+        };
+      }
+
+      if (typeof prop === "string" && SENSITIVE_PROPS.has(prop)) {
+        markTainted(`req.${prop}`);
+      }
+
+      const value = Reflect.get(target, prop, receiver);
+      // Express metotları kendi iç alanlarına `this` üzerinden erişiyor;
+      // proxy'yi receiver olarak bırakmak bu erişimleri de yakalayıp
+      // gereksiz işaretlemeye yol açar.
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}

package/src/index.js

@@ -5,19 +5,36 @@
  * controller'lar bu yüzeyi kullanır. Alt yollardan (`jskelet/server`)
  * ithal etmek de mümkün; buradaki liste "kararlı" sayılan yüzeydir.
  */
-export { route, renderPage, renderView, renderNotFound } from "./server/render.js";
+export {
+  route,
+  fragment,
+  renderPage,
+  renderView,
+  renderNotFound,
+} from "./server/render.js";
 export { renderStatusPage, statusFromError } from "./server/status-page.js";
 export { createApp, startServer } from "./server/create-app.js";
 export {
   notFound,
   redirect,
   permanentRedirect,
+  seeOther,
   isNotFoundError,
   isRedirectError,
   NotFoundError,
   RedirectError,
 } from "./http/control-flow.js";
 export { cache, withRequestCache } from "./http/request-cache.js";
+export {
+  clearCookie,
+  getSignedCookie,
+  parseCookies,
+  randomToken,
+  safeEqual,
+  serializeCookie,
+  setCookie,
+  setSignedCookie,
+} from "./http/cookies.js";
 export { reportUpstreamFailure } from "./server/upstream-tracking.js";
 export { asset, hasAsset, optimizedImage, getSpriteIds } from "./server/assets.js";
 export { headHints } from "./server/head-hints.js";
@@ -28,8 +45,15 @@ export {
   getHtmlCacheSize,
   withHtmlCache,
 } from "./server/html-cache.js";
+export {
+  clearDataCache,
+  dataCache,
+  getDataCacheEntries,
+  getDataCacheSize,
+  withDataCache,
+} from "./server/data-cache.js";
 export { prewarm, prewarmProgress } from "./server/prewarm.js";
 export { createProxy } from "./server/middleware/upstream-proxy.js";
 export { getConfig, loadConfig } from "./config/index.js";
 export { attrs, cn, cx, esc, jsonScript } from "./views/helpers/html.js";
-export { icon, image, link, preloadImage } from "./views/helpers/tags.js";
+export { csrfField, icon, image, link, preloadImage } from "./views/helpers/tags.js";

package/src/init.mjs

@@ -12,43 +12,43 @@ import * as log from "./log.mjs";
 /** @type {Record<string, string>} */
 const FILES = {
   "jskelet.config.mjs": `/**
- * JSkelet yapılandırması. Tüm alanlar opsiyoneldir; bu dosyayı silseniz de
- * uygulama varsayılanlarla çalışır.
+ * JSkelet configuration. Every field is optional; the app still runs on
+ * defaults if you delete this file.
  *
- * Ayrıntılar: node_modules/jskelet/docs/07-yapilandirma.md
+ * Details: node_modules/jskelet/docs/en/07-configuration.md
  */
 export default {
-  brand: { lang: "tr" },
+  brand: { lang: "en" },
 
-  /** Üçüncü taraf kaynaklar; \`<head>\`e preconnect olarak basılır. */
+  /** Third-party origins; emitted as preconnect in \`<head>\`. */
   preconnect: [],
 
   async cache() {
     return {
-      /** Sayfa HTML'inin önbellekte kalma süresi (saniye). */
+      /** How long a page's HTML stays in the cache (seconds). */
       html: { "/": 60 },
     };
   },
 
   hooks: {
-    /** Her sayfanın metadata varsayılanı. */
+    /** Metadata defaults for every page. */
     metadata() {
       return {
         titleTemplate: "%s | JSkelet",
-        description: "JSkelet ile kurulmuş bir site.",
+        description: "A site built with JSkelet.",
       };
     },
 
-    /** Layout'a her render'da eklenen local'ler. */
+    /** Locals added to the layout on every render. */
     layoutContext() {
       return { bodyClass: "min-h-full" };
     },
 
-    /** 404 sayfası. */
+    /** 404 page. */
     notFound() {
       return {
         view: "pages/not-found",
-        metadata: { title: "Sayfa bulunamadı", robots: { index: false } },
+        metadata: { title: "Page not found", robots: { index: false } },
       };
     },
   },
@@ -56,11 +56,12 @@ export default {
 `,
 
   "routes/10-pages.mjs": `/**
- * Route modülü. Default export \`(app, api)\` alır; \`api.route()\` controller'ı
- * HTML cache'i, notFound/redirect akışı ve sıkıştırmayla sarar.
+ * Route module. The default export receives \`(app, api)\`; \`api.route()\` wraps
+ * the controller with the HTML cache, the notFound/redirect flow and
+ * compression.
  *
- * Dosya adındaki sayısal önek yükleme sırasını belirler: yakalayıcı
- * ("/:slug" gibi) route'lar daha yüksek numarada olmalı.
+ * The numeric prefix in the file name sets load order: catch-all routes
+ * (like "/:slug") belong to a higher number.
  */
 export default function register(app, { route }) {
   app.get(
@@ -68,8 +69,8 @@ export default function register(app, { route }) {
     route(
       async () => ({
         view: "pages/home",
-        metadata: { title: "Ana sayfa" },
-        data: { message: "JSkelet çalışıyor." },
+        metadata: { title: "Home" },
+        data: { message: "JSkelet is running." },
       }),
       { revalidate: 60 },
     ),
@@ -86,16 +87,16 @@ export default function register(app, { route }) {
 
   "views/pages/not-found.ejs": `<section class="wrapper">
   <h1>404</h1>
-  <p>Aradığınız sayfa bulunamadı.</p>
-  <p><a href="/">Ana sayfaya dön</a></p>
+  <p>The page you are looking for was not found.</p>
+  <p><a href="/">Back to home</a></p>
 </section>
 `,
 
   "views/components/button.js": `import { attrs, esc } from "jskelet/html";
 
 /**
- * \`views/components/**\` altındaki her named export şablonlarda doğrudan
- * kullanılabilir: \`<%- button({ text: "Kaydet" }) %>\`. Import gerekmez.
+ * Every named export under \`views/components/**\` is usable directly in
+ * templates: \`<%- button({ text: "Save" }) %>\`. No import needed.
  *
  * @param {{ text: string, href?: string, class?: string }} props
  * @returns {string}
@@ -109,8 +110,8 @@ export function button({ text, href, class: className }) {
   "client/entries/main.js": `import { registerAll, start } from "jskelet/client";
 
 /**
- * Island kaydı. Değerler dinamik import: modül yalnızca sayfada o island
- * gerçekten varsa ve görünür olduğunda indirilir.
+ * Island registry. Values are dynamic imports: a module is downloaded only if
+ * that island is actually on the page and becomes visible.
  */
 registerAll({
   counter: () => import("../islands/counter.js"),
@@ -120,8 +121,8 @@ start();
 `,
 
   "client/islands/counter.js": `/**
- * Island sözleşmesi: \`mount(element, props)\` adlı named export.
- * Dönen fonksiyon (varsa) temizlik için ayrılmıştır.
+ * Island contract: a named export called \`mount(element, props)\`.
+ * The returned function, if any, is reserved for cleanup.
  *
  * @param {HTMLElement} element
  * @param {{ start?: number }} props
@@ -133,7 +134,7 @@ export function mount(element, props) {
   button.type = "button";
 
   const paint = () => {
-    button.textContent = \`Tıklama: \${value}\`;
+    button.textContent = \`Clicks: \${value}\`;
   };
 
   button.addEventListener("click", () => {
@@ -149,9 +150,9 @@ export function mount(element, props) {
   "styles/globals.css": `@import "tailwindcss" source(none);
 
 /**
- * Tailwind'in sınıf taraması bu direktiflere bağlıdır. Otomatik tespit
- * yalnızca bu dosyanın bulunduğu dizini tarar; şablonlarda geçen varyantlar
- * (data-[active=false]:… gibi) aksi hâlde sessizce düşer.
+ * Tailwind's class scanning depends on these directives. Automatic detection
+ * only scans the directory holding this file; variants used in templates
+ * (like data-[active=false]:…) would otherwise be dropped silently.
  */
 @source "../views";
 @source "../client";
@@ -213,8 +214,8 @@ export async function init(root) {
   }
 
   for (const file of created) log.line(`+ ${file}`);
-  if (skipped.length) log.warn(`${skipped.length} dosya zaten vardı, atlandı`);
+  if (skipped.length) log.warn(`${skipped.length} files already existed, skipped`);
 
   log.line("");
-  log.line("sıradaki adım:  npx jskelet dev");
+  log.line("next step:  npx jskelet dev");
 }

package/src/log.mjs

@@ -75,9 +75,15 @@ function clearLine() {
   if (isTTY) write("\r\u001b[2K");
 }
 
-/** @returns {string} `01:49:02` */
+/**
+ * Saat, yerelden bağımsız olarak 24 saatlik biçimde. Dil etiketi vermek
+ * sunucunun bulunduğu makinenin diline göre `ÖÖ/ÖS` ya da `AM/PM` basılmasına
+ * yol açıyordu; log satırının genişliği sabit kalmalı.
+ *
+ * @returns {string} `01:49:02`
+ */
 export function clock() {
-  return new Date().toLocaleTimeString("tr-TR", { hour12: false });
+  return new Date().toLocaleTimeString("en-GB", { hour12: false });
 }
 
 /**

package/src/runtime/alias-hooks.mjs

@@ -56,7 +56,7 @@ function readAliases() {
       // Uzun önek önce: `@flags/` `@/`den önce denenmeli, yoksa `@/` yakalar.
       return aliases.sort((a, b) => b.prefix.length - a.prefix.length);
     } catch (error) {
-      console.warn(`[alias] ${name} okunamadı, alias'lar devre dışı`, error);
+      console.warn(`[alias] could not read ${name}, aliases disabled`, error);
       return [];
     }
   }

package/src/server/assets.js

@@ -30,7 +30,7 @@ function load() {
   } catch {
     if (!warned) {
       warned = true;
-      console.warn("[assets] manifest yok — `jskelet build` çalıştırın.");
+      console.warn("[assets] no manifest — run `jskelet build`.");
     }
   }
 

package/src/server/create-app.js

@@ -13,14 +13,17 @@
  *      static'e düşer ve middleware anında sıkıştırır (kalite 5).
  *   5. body parser'lar — statikten sonra: görsel isteklerinde gövde ayrıştırma
  *      maliyeti ödenmesin.
- *   6. rewrites(afterFiles) — statik denendikten sonra, sayfalardan önce.
- *   7. route'lar → 404 → hata yönetimi.
+ *   6. csrf — body parser'lardan sonra olmalı: token form alanından okunuyor.
+ *      Rewrite'lardan önce, çünkü kontrol istemcinin gördüğü yola bakar.
+ *   7. rewrites(afterFiles) — statik denendikten sonra, sayfalardan önce.
+ *   8. route'lar → 404 → hata yönetimi.
  */
 import path from "node:path";
 import process from "node:process";
 import express from "express";
 import { compression } from "./middleware/compression.js";
 import { headersMiddleware } from "./middleware/headers.js";
+import { csrf } from "./middleware/csrf.js";
 import { staticPrecompressed } from "./middleware/static-precompressed.js";
 import { devGate } from "./middleware/dev-gate.js";
 import { redirects } from "./middleware/redirects.js";
@@ -51,8 +54,11 @@ export async function createApp(options = {}) {
   });
 
   app.set("etag", "strong");
-  // Ters proxy arkasında doğru protokol ve istemci IP'si için.
-  app.set("trust proxy", true);
+  // Ters proxy arkasında doğru protokol ve istemci IP'si için. Doğrudan
+  // internete açık bir sunucuda kapatılmalı: açıkken istemci kendi
+  // `X-Forwarded-For` başlığını uydurabilir ve rate limit ile audit log
+  // yanlış IP görür.
+  app.set("trust proxy", config.security.trustProxy);
 
   app.use(configRewrites("beforeFiles"));
   app.use(compression());
@@ -87,6 +93,8 @@ export async function createApp(options = {}) {
   app.use(express.urlencoded({ extended: false, limit: "64kb" }));
   app.use(express.json({ limit: "256kb" }));
 
+  app.use(csrf());
+
   app.use(configRewrites("afterFiles"));
 
   await registerRoutes(app);