jskelet 0.2.5 → 0.3.0

package/src/server/middleware/csrf.js

@@ -1,134 +1,134 @@
-/**
- * CSRF koruması.
- *
- * Bu yüzey framework'e ait, çünkü gövdeyi ayrıştıran o: `create-app.js`
- * `express.urlencoded` ve `express.json` kuruyor, yani state değiştiren
- * istekleri kabul eden katman framework. Cookie ile kimlik doğrulayan bir
- * uygulama bu koruma olmadan açık.
- *
- * İki katman:
- *
- * 1. **Origin kontrolü** (varsayılan açık). `Origin` ya da
- *    `Sec-Fetch-Site` başlığı çapraz site olduğunu gösteriyorsa istek
- *    reddedilir. Başlıkların **hiçbiri yoksa geçer**: tarayıcılar çapraz
- *    origin bir POST'ta `Origin`'i her zaman gönderir, buna karşılık
- *    webhook'lar ve sunucudan sunucuya çağrılar hiç göndermez. Bu ayrım,
- *    korumayı açık bırakırken entegrasyonları bozmamayı sağlıyor.
- *
- * 2. **Çift gönderim token'ı** (`security.csrf.token` ile açılır). Cookie'deki
- *    imzalı token ile form alanı/başlıktaki değer karşılaştırılır. `Origin`
- *    göndermeyen eski tarayıcılar için ikinci katman; formlara `csrfField()`
- *    eklenmesini gerektirdiği için varsayılan kapalı.
- *
- * Token'ı bu middleware **üretmez**, yalnızca doğrular. Üretim `csrfField()`
- * içinde, yani gerçekten bir forma basıldığı anda olur. Sebebi somut: token
- * her yanıtta yazılsaydı public ve cache'lenebilir bir sayfa da `Set-Cookie`
- * taşırdı, bir CDN o yanıtı saklardı ve tüm ziyaretçiler aynı token'ı
- * paylaşırdı — çift gönderim kontrolü tam olarak o noktada anlamını yitirir.
- */
-import { getConfig } from "../../config/index.js";
-import { matchPattern } from "../../config/pattern.js";
-import { getSignedCookie, safeEqual } from "../../http/cookies.js";
-
-/** Gövdesi olmayan, yan etkisi beklenmeyen metotlar. */
-const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
-
-/**
- * İsteğin geldiği origin'in kendi origin'imiz olup olmadığını söyler.
- *
- * `trust proxy` kapalıysa `req.protocol` her zaman `http` döner ve HTTPS
- * arkasında her istek çapraz site sanılır; bu yüzden karşılaştırma yalnızca
- * host üzerinden yapılır, protokol değil.
- *
- * @param {import('express').Request} req
- * @param {string[]} allowedOrigins
- * @returns {boolean}
- */
-function isSameOrigin(req, allowedOrigins) {
-  const origin = req.headers.origin;
-  if (!origin || origin === "null") return false;
-
-  if (allowedOrigins.includes(origin)) return true;
-
-  try {
-    const host = req.headers.host;
-    return Boolean(host) && new URL(origin).host === host;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * @returns {import('express').RequestHandler}
- */
-export function csrf() {
-  const { security } = getConfig();
-  const { csrf: options } = security;
-
-  return (req, res, next) => {
-    if (!options.enabled) {
-      next();
-      return;
-    }
-
-    const pathname = req.path ?? "";
-    if (options.exclude.some((pattern) => matchPattern(pattern, pathname))) {
-      next();
-      return;
-    }
-
-    if (SAFE_METHODS.has(req.method)) {
-      next();
-      return;
-    }
-
-    const site = String(req.headers["sec-fetch-site"] ?? "");
-    const hasOrigin = Boolean(req.headers.origin);
-
-    // Yalnızca çapraz site olduğu **belli** olan istekler reddedilir.
-    if (site === "cross-site" || (hasOrigin && !isSameOrigin(req, options.allowedOrigins))) {
-      reject(req, res, "origin mismatch");
-      return;
-    }
-
-    if (options.token) {
-      // Cookie yoksa istek zaten token basan bir formdan gelmiyor.
-      const expected = getSignedCookie(req, options.cookieName);
-      const provided =
-        firstString(/** @type {any} */ (req.body)?.[options.fieldName]) ??
-        firstString(req.headers[options.headerName]);
-
-      if (!expected || !provided || !safeEqual(provided, expected)) {
-        reject(req, res, "token mismatch");
-        return;
-      }
-    }
-
-    next();
-  };
-}
-
-/**
- * @param {unknown} value
- * @returns {string | null}
- */
-function firstString(value) {
-  if (typeof value === "string" && value) return value;
-  if (Array.isArray(value)) return firstString(value[0]);
-  return null;
-}
-
-/**
- * Reddedilen istek HTML sayfası değil düz metin döner: bu bir kullanıcı
- * hatası değil, ya bir saldırı ya da bir programlama hatası — ve fragment
- * takasında bir hata sayfasının içine düşmemeli.
- *
- * @param {import('express').Request} req
- * @param {import('express').Response} res
- * @param {string} reason
- */
-function reject(req, res, reason) {
-  console.warn(`[csrf] ${req.method} ${req.originalUrl} rejected — ${reason}`);
-  res.status(403).setHeader("Cache-Control", "no-store");
-  res.type("text/plain").send("Forbidden");
-}
+/**
+ * CSRF koruması.
+ *
+ * Bu yüzey framework'e ait, çünkü gövdeyi ayrıştıran o: `create-app.js`
+ * `express.urlencoded` ve `express.json` kuruyor, yani state değiştiren
+ * istekleri kabul eden katman framework. Cookie ile kimlik doğrulayan bir
+ * uygulama bu koruma olmadan açık.
+ *
+ * İki katman:
+ *
+ * 1. **Origin kontrolü** (varsayılan açık). `Origin` ya da
+ *    `Sec-Fetch-Site` başlığı çapraz site olduğunu gösteriyorsa istek
+ *    reddedilir. Başlıkların **hiçbiri yoksa geçer**: tarayıcılar çapraz
+ *    origin bir POST'ta `Origin`'i her zaman gönderir, buna karşılık
+ *    webhook'lar ve sunucudan sunucuya çağrılar hiç göndermez. Bu ayrım,
+ *    korumayı açık bırakırken entegrasyonları bozmamayı sağlıyor.
+ *
+ * 2. **Çift gönderim token'ı** (`security.csrf.token` ile açılır). Cookie'deki
+ *    imzalı token ile form alanı/başlıktaki değer karşılaştırılır. `Origin`
+ *    göndermeyen eski tarayıcılar için ikinci katman; formlara `csrfField()`
+ *    eklenmesini gerektirdiği için varsayılan kapalı.
+ *
+ * Token'ı bu middleware **üretmez**, yalnızca doğrular. Üretim `csrfField()`
+ * içinde, yani gerçekten bir forma basıldığı anda olur. Sebebi somut: token
+ * her yanıtta yazılsaydı public ve cache'lenebilir bir sayfa da `Set-Cookie`
+ * taşırdı, bir CDN o yanıtı saklardı ve tüm ziyaretçiler aynı token'ı
+ * paylaşırdı — çift gönderim kontrolü tam olarak o noktada anlamını yitirir.
+ */
+import { getConfig } from "../../config/index.js";
+import { matchPattern } from "../../config/pattern.js";
+import { getSignedCookie, safeEqual } from "../../http/cookies.js";
+
+/** Gövdesi olmayan, yan etkisi beklenmeyen metotlar. */
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * İsteğin geldiği origin'in kendi origin'imiz olup olmadığını söyler.
+ *
+ * `trust proxy` kapalıysa `req.protocol` her zaman `http` döner ve HTTPS
+ * arkasında her istek çapraz site sanılır; bu yüzden karşılaştırma yalnızca
+ * host üzerinden yapılır, protokol değil.
+ *
+ * @param {import('express').Request} req
+ * @param {string[]} allowedOrigins
+ * @returns {boolean}
+ */
+function isSameOrigin(req, allowedOrigins) {
+  const origin = req.headers.origin;
+  if (!origin || origin === "null") return false;
+
+  if (allowedOrigins.includes(origin)) return true;
+
+  try {
+    const host = req.headers.host;
+    return Boolean(host) && new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @returns {import('express').RequestHandler}
+ */
+export function csrf() {
+  const { security } = getConfig();
+  const { csrf: options } = security;
+
+  return (req, res, next) => {
+    if (!options.enabled) {
+      next();
+      return;
+    }
+
+    const pathname = req.path ?? "";
+    if (options.exclude.some((pattern) => matchPattern(pattern, pathname))) {
+      next();
+      return;
+    }
+
+    if (SAFE_METHODS.has(req.method)) {
+      next();
+      return;
+    }
+
+    const site = String(req.headers["sec-fetch-site"] ?? "");
+    const hasOrigin = Boolean(req.headers.origin);
+
+    // Yalnızca çapraz site olduğu **belli** olan istekler reddedilir.
+    if (site === "cross-site" || (hasOrigin && !isSameOrigin(req, options.allowedOrigins))) {
+      reject(req, res, "origin mismatch");
+      return;
+    }
+
+    if (options.token) {
+      // Cookie yoksa istek zaten token basan bir formdan gelmiyor.
+      const expected = getSignedCookie(req, options.cookieName);
+      const provided =
+        firstString(/** @type {any} */ (req.body)?.[options.fieldName]) ??
+        firstString(req.headers[options.headerName]);
+
+      if (!expected || !provided || !safeEqual(provided, expected)) {
+        reject(req, res, "token mismatch");
+        return;
+      }
+    }
+
+    next();
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function firstString(value) {
+  if (typeof value === "string" && value) return value;
+  if (Array.isArray(value)) return firstString(value[0]);
+  return null;
+}
+
+/**
+ * Reddedilen istek HTML sayfası değil düz metin döner: bu bir kullanıcı
+ * hatası değil, ya bir saldırı ya da bir programlama hatası — ve fragment
+ * takasında bir hata sayfasının içine düşmemeli.
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {string} reason
+ */
+function reject(req, res, reason) {
+  console.warn(`[csrf] ${req.method} ${req.originalUrl} rejected — ${reason}`);
+  res.status(403).setHeader("Cache-Control", "no-store");
+  res.type("text/plain").send("Forbidden");
+}

package/src/server/middleware/dev-gate.js

@@ -1,62 +1,62 @@
-/**
- * Yayına açılmamış bir ortamı gizler: `DEV_TOKEN` ayarlıyken token taşımayan
- * her isteğe 404 döner. 403 değil 404 — 403 ortamın var olduğunu doğrular,
- * 404 hiç yokmuş gibi davranır.
- *
- * Token bir kez `?dev_token=…` ile gelirse çereze yazılır, böylece link
- * paylaşımı yeterli olur. `DEV_TOKEN` yoksa middleware tamamen devre dışıdır
- * ve üretimde hiçbir maliyeti olmaz.
- */
-import process from "node:process";
-import { getConfig } from "../../config/index.js";
-
-const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 14;
-
-/**
- * @param {import('http').IncomingMessage} req
- * @param {string} name
- * @returns {string | undefined}
- */
-function readCookie(req, name) {
-  const header = req.headers.cookie;
-  if (!header) return undefined;
-
-  for (const part of header.split(";")) {
-    const eq = part.indexOf("=");
-    if (eq === -1) continue;
-    if (part.slice(0, eq).trim() !== name) continue;
-    return decodeURIComponent(part.slice(eq + 1).trim());
-  }
-  return undefined;
-}
-
-/** @returns {import('express').RequestHandler} */
-export function devGate() {
-  const { devGateBypass, brand } = getConfig();
-  const bypass = new Set(devGateBypass);
-  const cookieName = brand.devTokenCookie;
-
-  return (req, res, next) => {
-    const devToken = process.env.DEV_TOKEN;
-    if (!devToken) return next();
-    if (bypass.has(req.path)) return next();
-
-    const fromQuery = req.query?.[cookieName];
-    const tokenFromQuery = Array.isArray(fromQuery) ? fromQuery[0] : fromQuery;
-    const tokenFromCookie = readCookie(req, cookieName);
-
-    if (tokenFromQuery !== devToken && tokenFromCookie !== devToken) {
-      res.status(404).type("text/plain").send("Not Found");
-      return;
-    }
-
-    if (tokenFromQuery === devToken) {
-      res.setHeader(
-        "Set-Cookie",
-        `${cookieName}=${encodeURIComponent(devToken)}; Max-Age=${COOKIE_MAX_AGE_SECONDS}; Path=/; SameSite=Lax`,
-      );
-    }
-
-    next();
-  };
-}
+/**
+ * Yayına açılmamış bir ortamı gizler: `DEV_TOKEN` ayarlıyken token taşımayan
+ * her isteğe 404 döner. 403 değil 404 — 403 ortamın var olduğunu doğrular,
+ * 404 hiç yokmuş gibi davranır.
+ *
+ * Token bir kez `?dev_token=…` ile gelirse çereze yazılır, böylece link
+ * paylaşımı yeterli olur. `DEV_TOKEN` yoksa middleware tamamen devre dışıdır
+ * ve üretimde hiçbir maliyeti olmaz.
+ */
+import process from "node:process";
+import { getConfig } from "../../config/index.js";
+
+const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 14;
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+function readCookie(req, name) {
+  const header = req.headers.cookie;
+  if (!header) return undefined;
+
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() !== name) continue;
+    return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return undefined;
+}
+
+/** @returns {import('express').RequestHandler} */
+export function devGate() {
+  const { devGateBypass, brand } = getConfig();
+  const bypass = new Set(devGateBypass);
+  const cookieName = brand.devTokenCookie;
+
+  return (req, res, next) => {
+    const devToken = process.env.DEV_TOKEN;
+    if (!devToken) return next();
+    if (bypass.has(req.path)) return next();
+
+    const fromQuery = req.query?.[cookieName];
+    const tokenFromQuery = Array.isArray(fromQuery) ? fromQuery[0] : fromQuery;
+    const tokenFromCookie = readCookie(req, cookieName);
+
+    if (tokenFromQuery !== devToken && tokenFromCookie !== devToken) {
+      res.status(404).type("text/plain").send("Not Found");
+      return;
+    }
+
+    if (tokenFromQuery === devToken) {
+      res.setHeader(
+        "Set-Cookie",
+        `${cookieName}=${encodeURIComponent(devToken)}; Max-Age=${COOKIE_MAX_AGE_SECONDS}; Path=/; SameSite=Lax`,
+      );
+    }
+
+    next();
+  };
+}

package/src/server/middleware/headers.js

@@ -1,37 +1,37 @@
-/**
- * `jskelet.config.mjs` → `headers()` uygulayıcısı.
- *
- * İki katman var. Framework yalnızca statik dosyalara uzun ömürlü cache
- * yazar — bu, hash'li çıktı için her projede doğru olan tek varsayılan.
- * Bunun dışındaki her başlık (CSP, COOP, HSTS, X-Frame-Options…) config'ten
- * gelir ve varsayılanların üstüne biner: aynı başlığı yeniden tanımlarsan
- * config kazanır.
- */
-import { getConfig } from "../../config/index.js";
-import { matchPattern } from "../../config/pattern.js";
-import { IMMUTABLE_CACHE } from "../../config/defaults.js";
-
-/** @returns {import('express').RequestHandler} */
-export function headersMiddleware() {
-  const { static: staticRules, headers: rules } = getConfig();
-
-  return (req, res, next) => {
-    const pathname = req.path ?? "";
-    const dot = pathname.lastIndexOf(".");
-    const ext = dot === -1 ? "" : pathname.slice(dot).toLowerCase();
-
-    if (
-      staticRules.extensions.has(ext) ||
-      staticRules.prefixes.some((prefix) => pathname.startsWith(prefix))
-    ) {
-      res.setHeader("Cache-Control", IMMUTABLE_CACHE);
-    }
-
-    for (const rule of rules) {
-      if (!matchPattern(rule.pattern, pathname)) continue;
-      for (const { key, value } of rule.headers) res.setHeader(key, value);
-    }
-
-    next();
-  };
-}
+/**
+ * `jskelet.config.mjs` → `headers()` uygulayıcısı.
+ *
+ * İki katman var. Framework yalnızca statik dosyalara uzun ömürlü cache
+ * yazar — bu, hash'li çıktı için her projede doğru olan tek varsayılan.
+ * Bunun dışındaki her başlık (CSP, COOP, HSTS, X-Frame-Options…) config'ten
+ * gelir ve varsayılanların üstüne biner: aynı başlığı yeniden tanımlarsan
+ * config kazanır.
+ */
+import { getConfig } from "../../config/index.js";
+import { matchPattern } from "../../config/pattern.js";
+import { IMMUTABLE_CACHE } from "../../config/defaults.js";
+
+/** @returns {import('express').RequestHandler} */
+export function headersMiddleware() {
+  const { static: staticRules, headers: rules } = getConfig();
+
+  return (req, res, next) => {
+    const pathname = req.path ?? "";
+    const dot = pathname.lastIndexOf(".");
+    const ext = dot === -1 ? "" : pathname.slice(dot).toLowerCase();
+
+    if (
+      staticRules.extensions.has(ext) ||
+      staticRules.prefixes.some((prefix) => pathname.startsWith(prefix))
+    ) {
+      res.setHeader("Cache-Control", IMMUTABLE_CACHE);
+    }
+
+    for (const rule of rules) {
+      if (!matchPattern(rule.pattern, pathname)) continue;
+      for (const { key, value } of rule.headers) res.setHeader(key, value);
+    }
+
+    next();
+  };
+}

package/src/server/middleware/redirects.js

@@ -1,32 +1,32 @@
-/**
- * `jskelet.config.mjs` → `redirects()` uygulayıcısı.
- *
- * İlk eşleşen kural kazanır, sonrası denenmez — sıralama config'teki yazım
- * sırasıdır. Query string korunur: `/eski?utm=x` → `/yeni?utm=x`, çünkü
- * yönlendirme kampanya parametrelerini düşürürse trafik kaynağı kaybolur.
- */
-import { getConfig } from "../../config/index.js";
-import { fillDestination, matchPattern } from "../../config/pattern.js";
-
-/** @returns {import('express').RequestHandler} */
-export function redirects() {
-  const rules = getConfig().redirects;
-  if (!rules.length) return (req, res, next) => next();
-
-  return (req, res, next) => {
-    const query = req.originalUrl.slice(req.path.length);
-
-    for (const rule of rules) {
-      const params = matchPattern(rule.pattern, req.path);
-      if (!params) continue;
-
-      res.redirect(
-        rule.statusCode,
-        `${fillDestination(rule.destination, params)}${query}`,
-      );
-      return;
-    }
-
-    next();
-  };
-}
+/**
+ * `jskelet.config.mjs` → `redirects()` uygulayıcısı.
+ *
+ * İlk eşleşen kural kazanır, sonrası denenmez — sıralama config'teki yazım
+ * sırasıdır. Query string korunur: `/eski?utm=x` → `/yeni?utm=x`, çünkü
+ * yönlendirme kampanya parametrelerini düşürürse trafik kaynağı kaybolur.
+ */
+import { getConfig } from "../../config/index.js";
+import { fillDestination, matchPattern } from "../../config/pattern.js";
+
+/** @returns {import('express').RequestHandler} */
+export function redirects() {
+  const rules = getConfig().redirects;
+  if (!rules.length) return (req, res, next) => next();
+
+  return (req, res, next) => {
+    const query = req.originalUrl.slice(req.path.length);
+
+    for (const rule of rules) {
+      const params = matchPattern(rule.pattern, req.path);
+      if (!params) continue;
+
+      res.redirect(
+        rule.statusCode,
+        `${fillDestination(rule.destination, params)}${query}`,
+      );
+      return;
+    }
+
+    next();
+  };
+}