jskelet 0.2.4 → 0.3.0

package/src/server/admin/actions.js

@@ -0,0 +1,229 @@
+/**
+ * Admin paneli mutasyonları. Cevap metin değil `{ ok, code, params }` —
+ * i18n client'ta.
+ */
+import {
+  clearHtmlCache,
+  dropHtmlCacheKey,
+  getHtmlCacheSize,
+  invalidateHtmlCache,
+} from "../html-cache.js";
+import {
+  clearDataCache,
+  dropDataCacheKey,
+} from "../data-cache.js";
+import {
+  getRedisStatus,
+  inspectRedis,
+  redisDropMatching,
+} from "../redis.js";
+import {
+  clearCloudflareCacheReserve,
+  purgeCloudflare,
+  setCloudflareFeature,
+  setCloudflareSetting,
+  toCloudflareUrls,
+} from "../cloudflare.js";
+import { prewarm, prewarmProgress } from "../prewarm.js";
+
+/**
+ * @param {Record<string, any>} body
+ * @param {import('express').Request} req
+ * @returns {Promise<{ ok: boolean, code?: string,
+ *   params?: Record<string, string | number>,
+ *   parts?: ({ code: string, params?: Record<string, string | number> } | null)[] }>}
+ */
+export async function runAction(body, req) {
+  const type = String(body?.type ?? "");
+
+  switch (type) {
+    case "html:clear": {
+      const size = getHtmlCacheSize();
+      clearHtmlCache();
+      return { ok: true, code: "html.cleared", params: { count: size } };
+    }
+
+    case "data:clear": {
+      const prefix = typeof body.prefix === "string" && body.prefix ? body.prefix : undefined;
+      const removed = clearDataCache(prefix);
+      return prefix
+        ? { ok: true, code: "data.clearedPrefix", params: { count: removed, prefix } }
+        : { ok: true, code: "data.cleared", params: { count: removed } };
+    }
+
+    case "html:invalidate": {
+      const target = String(body.target ?? "");
+      if (!target.startsWith("/")) {
+        return { ok: false, code: "target.invalid" };
+      }
+
+      const hard = body.hard === true;
+      const count = invalidateHtmlCache(target, { hard });
+      return {
+        ok: true,
+        code: hard ? "html.dropped" : "html.marked",
+        params: { count, target },
+      };
+    }
+
+    case "html:drop": {
+      const key = String(body.key ?? "");
+      if (!key) return { ok: false, code: "key.missing" };
+      const existed = dropHtmlCacheKey(key);
+      return { ok: true, code: existed ? "entry.dropped" : "entry.absent", params: { key } };
+    }
+
+    case "data:drop": {
+      const key = String(body.key ?? "");
+      if (!key) return { ok: false, code: "key.missing" };
+      const existed = dropDataCacheKey(key);
+      return { ok: true, code: existed ? "entry.dropped" : "entry.absent", params: { key } };
+    }
+
+    case "redis:inspect": {
+      const result = await inspectRedis();
+      if (!result.ok) return { ok: false, code: "redis.unreachable" };
+
+      return {
+        ok: true,
+        parts: [
+          { code: "redis.htmlKeys", params: { count: result.html } },
+          { code: "redis.dataKeys", params: { count: result.data } },
+          result.totalKeys !== null
+            ? { code: "redis.dbKeys", params: { count: result.totalKeys } }
+            : null,
+          result.usedMemory ? { code: "redis.memory", params: { value: result.usedMemory } } : null,
+        ].filter(Boolean),
+      };
+    }
+
+    case "redis:drop": {
+      const kind = body.kind === "data" ? "data" : "html";
+      const status = getRedisStatus();
+      if (!status.connected) {
+        return { ok: false, code: "redis.notConnected" };
+      }
+
+      const dropped = await redisDropMatching(kind);
+      return {
+        ok: true,
+        code: kind === "data" ? "redis.droppedData" : "redis.droppedHtml",
+        params: { count: dropped },
+      };
+    }
+
+    case "cf:purge-everything": {
+      const result = await purgeCloudflare({ everything: true });
+      return result.ok
+        ? { ok: true, code: "cf.purgedEverything" }
+        : cloudflareFailure(result.error);
+    }
+
+    case "cf:purge-urls": {
+      const paths = Array.isArray(body.paths) ? body.paths.map(String) : [];
+      if (!paths.length) return { ok: false, code: "cf.noPaths" };
+
+      const urls = toCloudflareUrls(paths, originOf(req));
+      if (!urls.length) return { ok: false, code: "cf.noHostname" };
+
+      const result = await purgeCloudflare({ files: urls });
+      return result.ok
+        ? {
+            ok: true,
+            code: "cf.purgedUrls",
+            params: { count: result.purged, batches: result.batches },
+          }
+        : cloudflareFailure(result.error);
+    }
+
+    case "cf:purge-keys": {
+      /** @type {"prefixes" | "hosts" | "tags"} */
+      const kind =
+        body.kind === "hosts" ? "hosts" : body.kind === "tags" ? "tags" : "prefixes";
+
+      const values = String(body.values ?? "")
+        .split(/[\s,]+/)
+        .filter(Boolean);
+
+      if (!values.length) return { ok: false, code: "cf.nothingToPurge" };
+
+      const result = await purgeCloudflare({ [kind]: values });
+      return result.ok
+        ? { ok: true, code: "cf.purgedKeys", params: { count: result.purged, kind } }
+        : cloudflareFailure(result.error);
+    }
+
+    case "cf:setting": {
+      const result = await setCloudflareSetting(body.id, body.value);
+      return result.ok
+        ? {
+            ok: true,
+            code: "cf.settingChanged",
+            params: { id: String(body.id), value: String(result.value) },
+          }
+        : cloudflareFailure(result.error);
+    }
+
+    case "cf:feature": {
+      const value = body.value === "on" ? "on" : "off";
+      const result = await setCloudflareFeature(body.feature, value);
+      return result.ok
+        ? {
+            ok: true,
+            code: "cf.featureChanged",
+            params: { feature: String(body.feature), value },
+          }
+        : cloudflareFailure(result.error);
+    }
+
+    case "cf:clear-reserve": {
+      const result = await clearCloudflareCacheReserve();
+      return result.ok
+        ? { ok: true, code: "cf.reserveClearing" }
+        : cloudflareFailure(result.error);
+    }
+
+    case "prewarm": {
+      if (prewarmProgress.active) {
+        return { ok: false, code: "prewarm.busy" };
+      }
+
+      const requested = Array.isArray(body.paths) ? body.paths : [];
+      const paths = requested.filter(
+        (/** @type {unknown} */ value) =>
+          typeof value === "string" && value.startsWith("/"),
+      );
+
+      prewarm({
+        origin: `${req.protocol}://${req.get("host")}`,
+        paths: paths.length ? paths : undefined,
+      }).catch((error) => {
+        console.error("[admin] prewarm failed", error);
+      });
+
+      return paths.length
+        ? { ok: true, code: "prewarm.paths", params: { count: paths.length } }
+        : { ok: true, code: "prewarm.all" };
+    }
+
+    default:
+      return { ok: false, code: "action.unknown", params: { type } };
+  }
+}
+
+/**
+ * @param {string | undefined} error
+ * @returns {{ ok: false, code: string, params: { error: string } }}
+ */
+function cloudflareFailure(error) {
+  return { ok: false, code: "cf.failed", params: { error: error ?? "unknown error" } };
+}
+
+/**
+ * @param {import('express').Request} req
+ * @returns {string | undefined}
+ */
+function originOf(req) {
+  const host = req.get("host");
+  return host ? `${req.protocol}://${host}` : undefined;
+}

package/src/server/admin/auth.js

@@ -0,0 +1,125 @@
+/**
+ * Admin paneli oturum ve şifre yönetimi.
+ *
+ * Şifre süreç ömrü kadar; kalıcı sır yok. Cookie parse framework'ün
+ * `parseCookies()` yolunu kullanmaz — o yol isteği "kişiselleştirilmiş"
+ * işaretler.
+ */
+import crypto from "node:crypto";
+import process from "node:process";
+import { safeEqual } from "../../http/cookies.js";
+
+export const COOKIE_NAME = "jskelet_admin_sid";
+
+/**
+ * Aksiyon isteklerinde beklenen başlık. Tarayıcı bu başlığı çapraz site bir
+ * formla gönderemez (preflight gerekir), yani panelin kendi CSRF freni.
+ */
+export const ACTION_HEADER = "x-jskelet-admin";
+
+/** 32 haneli, süreç ömrü kadar geçerli şifre. */
+export const PASSWORD = crypto.randomBytes(16).toString("hex");
+
+/** @type {Map<string, number>} token → son kullanma zamanı. */
+const sessions = new Map();
+
+/**
+ * @param {import('express').Request} req
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function readCookie(req, name) {
+  const header = req.headers.cookie;
+  if (!header) return null;
+
+  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 null;
+}
+
+/**
+ * Süresi geçmiş oturumları eler.
+ */
+export function pruneSessions() {
+  const now = Date.now();
+  for (const [token, expiresAt] of sessions) {
+    if (now >= expiresAt) sessions.delete(token);
+  }
+}
+
+/**
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+export function authenticated(req) {
+  const token = readCookie(req, COOKIE_NAME);
+  if (!token) return false;
+
+  const expiresAt = sessions.get(token);
+  if (expiresAt === undefined) return false;
+
+  if (Date.now() >= expiresAt) {
+    sessions.delete(token);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * @param {string} password
+ * @returns {boolean}
+ */
+export function passwordMatches(password) {
+  return Boolean(password) && safeEqual(password, PASSWORD);
+}
+
+/**
+ * @param {number} sessionHours
+ * @returns {{ token: string, maxAge: number }}
+ */
+export function createSession(sessionHours) {
+  pruneSessions();
+  const token = crypto.randomBytes(32).toString("base64url");
+  const maxAge = Math.round(sessionHours * 3600);
+  sessions.set(token, Date.now() + maxAge * 1000);
+  return { token, maxAge };
+}
+
+/**
+ * @param {import('express').Request} req
+ */
+export function destroySession(req) {
+  const token = readCookie(req, COOKIE_NAME);
+  if (token) sessions.delete(token);
+}
+
+/**
+ * @param {string} basePath
+ * @param {string} token
+ * @param {number} maxAge
+ * @returns {string}
+ */
+export function sessionCookie(basePath, token, maxAge) {
+  return [
+    `${COOKIE_NAME}=${token}`,
+    `Path=${basePath}`,
+    `Max-Age=${maxAge}`,
+    "HttpOnly",
+    "SameSite=Strict",
+    ...(process.env.NODE_ENV === "development" ? [] : ["Secure"]),
+  ].join("; ");
+}
+
+/**
+ * @param {string} basePath
+ * @returns {string}
+ */
+export function clearSessionCookie(basePath) {
+  return `${COOKIE_NAME}=; Path=${basePath}; Max-Age=0`;
+}

package/src/server/admin/event-log.js

@@ -0,0 +1,151 @@
+/**
+ * Admin paneli için süreç içi olay kuyruğu.
+ *
+ * Kaynaklar: HTTP `finish` middleware'i ve `log.mjs` aboneliği. Gövde yok —
+ * yalnızca meta. Admin kapalıyken bu modül yüklenmez.
+ */
+import * as log from "../../log.mjs";
+import { getConfig } from "../../config/index.js";
+
+/** @typedef {{ kind: string, id: number, at: number, [key: string]: unknown }} LogEntry */
+
+/** @type {LogEntry[]} */
+const ring = [];
+
+/** @type {Set<(entry: LogEntry) => void>} */
+const live = new Set();
+
+let nextId = 1;
+/** @type {(() => void) | null} */
+let unsubscribeLog = null;
+/** @type {string} */
+let basePath = "/_jskelet/admin";
+/** @type {string} */
+let prewarmUa = "jskelet-prewarm";
+let maxSize = 500;
+
+/**
+ * @param {{ basePath: string, logSize: number, prewarmUserAgent?: string }} options
+ */
+export function configureEventLog(options) {
+  basePath = options.basePath;
+  maxSize = options.logSize;
+  if (options.prewarmUserAgent) prewarmUa = options.prewarmUserAgent;
+
+  if (!unsubscribeLog) {
+    unsubscribeLog = log.subscribe((raw) => {
+      // HTTP finish middleware zaten kendi kaydını yazıyor; log.http
+      // çift kayıt üretmesin.
+      if (raw.kind === "http") return;
+      push({
+        kind: typeof raw.kind === "string" ? raw.kind : "event",
+        scope: raw.scope ?? null,
+        message: raw.message ?? "",
+        note: raw.note ?? null,
+        ms: raw.ms ?? null,
+      });
+    });
+  }
+}
+
+/**
+ * @param {Omit<LogEntry, "id" | "at"> & { kind: string }} partial
+ * @returns {LogEntry}
+ */
+export function push(partial) {
+  /** @type {LogEntry} */
+  const entry = {
+    ...partial,
+    id: nextId++,
+    at: Date.now(),
+  };
+
+  ring.push(entry);
+  while (ring.length > maxSize) ring.shift();
+
+  for (const listener of live) {
+    try {
+      listener(entry);
+    } catch {
+      // SSE dinleyicisi paneli düşürmesin.
+    }
+  }
+
+  return entry;
+}
+
+/**
+ * @param {number} [afterId]
+ * @param {number} [limit]
+ * @returns {LogEntry[]}
+ */
+export function list(afterId = 0, limit = 200) {
+  const capped = Math.min(Math.max(1, limit), maxSize);
+  const filtered = afterId > 0 ? ring.filter((entry) => entry.id > afterId) : ring;
+  return filtered.slice(-capped);
+}
+
+/**
+ * @param {(entry: LogEntry) => void} listener
+ * @returns {() => void}
+ */
+export function subscribeLive(listener) {
+  live.add(listener);
+  return () => live.delete(listener);
+}
+
+/**
+ * HTTP yanıt bitiminde ring'e yazar. Admin yolları ve prewarm UA atlanır.
+ *
+ * @returns {import('express').RequestHandler}
+ */
+export function requestLogMiddleware() {
+  const brand = getConfig().brand;
+
+  /** @type {import('express').RequestHandler} */
+  return (req, res, next) => {
+    const pathname = req.path || "";
+    if (pathname === basePath || pathname.startsWith(`${basePath}/`)) {
+      return next();
+    }
+
+    if (req.headers["user-agent"] === (brand.prewarmUserAgent || prewarmUa)) {
+      return next();
+    }
+
+    const started = process.hrtime.bigint();
+
+    res.on("finish", () => {
+      const routePath = matchedRoute(req);
+      push({
+        kind: "http",
+        method: req.method,
+        url: req.originalUrl,
+        path: req.path,
+        route: routePath,
+        status: res.statusCode,
+        ms: Number(process.hrtime.bigint() - started) / 1e6,
+        cache: /** @type {string | null} */ (
+          res.getHeader(brand.cacheHeader) ?? null
+        ),
+      });
+    });
+
+    next();
+  };
+}
+
+/**
+ * Express'in eşleştirdiği route deseni (mount + path). Yoksa null.
+ *
+ * @param {import('express').Request} req
+ * @returns {string | null}
+ */
+function matchedRoute(req) {
+  const layer = /** @type {any} */ (req).route;
+  if (!layer || typeof layer.path !== "string") return null;
+
+  const base = /** @type {any} */ (req).baseUrl || "";
+  const pattern = layer.path === "/" ? base || "/" : `${base}${layer.path}`;
+  return pattern || null;
+}

package/src/server/admin/gate.js

@@ -0,0 +1,209 @@
+/**
+ * Admin paneli erişim kapısı: IP allowlist, bot UA engeli, ban sayacı.
+ *
+ * Yasaklı / reddedilen her cevap 404: 401/403 panelin varlığını doğrular.
+ */
+import net from "node:net";
+
+/** Bilinen crawler / bot imzaları (küçük harf). */
+const BOT_MARKERS = [
+  "googlebot",
+  "bingbot",
+  "slurp",
+  "duckduckbot",
+  "baiduspider",
+  "yandexbot",
+  "sogou",
+  "exabot",
+  "facebot",
+  "facebookexternalhit",
+  "ia_archiver",
+  "applebot",
+  "semrushbot",
+  "ahrefsbot",
+  "mj12bot",
+  "dotbot",
+  "petalbot",
+  "bytespider",
+  "gptbot",
+  "claudebot",
+  "ccbot",
+  "amazonbot",
+  "twitterbot",
+  "linkedinbot",
+  "embedly",
+  "quora link preview",
+  "showyoubot",
+  "outbrain",
+  "pinterest",
+  "redditbot",
+  "whatsapp",
+  "telegrambot",
+  "discordbot",
+  "crawler",
+  "spider",
+  "bot/",
+  "bot;",
+];
+
+/** @type {Map<string, { fails: number, bannedUntil: number }>} */
+const offenders = new Map();
+
+/**
+ * @param {import('express').Request} req
+ * @returns {string}
+ */
+export function clientKey(req) {
+  // `trust proxy` ayarı `req.ip`e yansıyor; ters proxy arkasında doğru IP,
+  // doğrudan internete açık bir sunucuda soket adresi kullanılır.
+  return req.ip ?? req.socket.remoteAddress ?? "unknown";
+}
+
+/**
+ * @param {string} ua
+ * @returns {boolean}
+ */
+export function looksLikeBot(ua) {
+  if (!ua) return true;
+  const lower = ua.toLowerCase();
+  return BOT_MARKERS.some((marker) => lower.includes(marker));
+}
+
+/**
+ * Exact IP veya CIDR (`10.0.0.0/8`). IPv6 için yalnızca exact eşleşme.
+ *
+ * @param {string} ip
+ * @param {string[]} allowIps
+ * @returns {boolean}
+ */
+export function ipAllowed(ip, allowIps) {
+  if (!allowIps.length) return true;
+
+  const normalized = normalizeIp(ip);
+  if (!normalized) return false;
+
+  for (const entry of allowIps) {
+    if (entry.includes("/")) {
+      if (matchCidr(normalized, entry)) return true;
+      continue;
+    }
+    if (normalizeIp(entry) === normalized) return true;
+  }
+
+  return false;
+}
+
+/**
+ * @param {string} ip
+ * @returns {string | null}
+ */
+function normalizeIp(ip) {
+  if (!ip) return null;
+  // Express IPv4-mapped IPv6: `:ffff:127.0.0.1`
+  const mapped = ip.startsWith("::ffff:") ? ip.slice(7) : ip;
+  return mapped;
+}
+
+/**
+ * @param {string} ip
+ * @param {string} cidr
+ * @returns {boolean}
+ */
+function matchCidr(ip, cidr) {
+  const [network, bitsRaw] = cidr.split("/");
+  const bits = Number(bitsRaw);
+  if (!Number.isFinite(bits) || bits < 0 || bits > 32) return false;
+  if (net.isIPv4(ip) && net.isIPv4(network)) {
+    const ipNum = ipv4ToInt(ip);
+    const netNum = ipv4ToInt(network);
+    if (ipNum === null || netNum === null) return false;
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (ipNum & mask) === (netNum & mask);
+  }
+  return false;
+}
+
+/**
+ * @param {string} ip
+ * @returns {number | null}
+ */
+function ipv4ToInt(ip) {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n) || n < 0 || n > 255)) {
+    return null;
+  }
+  return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+
+/**
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+export function banned(req) {
+  const record = offenders.get(clientKey(req));
+  if (!record) return false;
+
+  if (record.bannedUntil && Date.now() >= record.bannedUntil) {
+    offenders.delete(clientKey(req));
+    return false;
+  }
+
+  return record.bannedUntil > 0;
+}
+
+/**
+ * @param {import('express').Request} req
+ * @param {string} reason
+ * @param {{ banAttempts: number, banHours: number }} settings
+ */
+export function noteFailure(req, reason, settings) {
+  const key = clientKey(req);
+  const record = offenders.get(key) ?? { fails: 0, bannedUntil: 0 };
+  record.fails += 1;
+
+  if (record.fails >= settings.banAttempts) {
+    record.bannedUntil = Date.now() + settings.banHours * 3600_000;
+    console.warn(
+      `[admin] ${key} banned for ${settings.banHours}h after ` +
+        `${record.fails} failed attempts (${reason})`,
+    );
+  }
+
+  offenders.set(key, record);
+}
+
+/**
+ * @param {import('express').Request} req
+ */
+export function clearOffender(req) {
+  offenders.delete(clientKey(req));
+}
+
+/**
+ * Kapı middleware'i: ban → IP → bot. Hepsi 404.
+ *
+ * @param {() => typeof import('../../config/defaults.js').DEFAULT_ADMIN} getSettings
+ * @returns {import('express').RequestHandler}
+ */
+export function gateMiddleware(getSettings) {
+  return (req, res, next) => {
+    if (banned(req)) {
+      res.status(404).type("text/plain").send("Not Found");
+      return;
+    }
+
+    const settings = getSettings();
+
+    if (!ipAllowed(clientKey(req), settings.allowIps)) {
+      res.status(404).type("text/plain").send("Not Found");
+      return;
+    }
+
+    if (settings.blockBots && looksLikeBot(String(req.headers["user-agent"] ?? ""))) {
+      res.status(404).type("text/plain").send("Not Found");
+      return;
+    }
+
+    next();
+  };
+}