jskelet 0.2.5 → 0.3.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();
+  };
+}

package/src/server/admin/inventory.js

@@ -0,0 +1,188 @@
+/**
+ * Route ve view envanteri — admin paneline salt okunur döküm.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getConfig } from "../../config/index.js";
+import { list as listLogs } from "./event-log.js";
+
+/**
+ * Express router stack'ini dolaşır. İç API kırılgan; yalnızca gözlem için.
+ *
+ * @param {import('express').Express} app
+ * @returns {{ method: string, path: string }[]}
+ */
+export function listExpressRoutes(app) {
+  /** @type {{ method: string, path: string }[]} */
+  const out = [];
+  const stack = /** @type {any} */ (app)?._router?.stack;
+  if (!Array.isArray(stack)) return out;
+
+  /**
+   * @param {any[]} layers
+   * @param {string} prefix
+   */
+  function walk(layers, prefix) {
+    for (const layer of layers) {
+      if (layer.route) {
+        const routePath = joinPath(prefix, layer.route.path);
+        const methods = Object.keys(layer.route.methods || {}).filter(
+          (name) => layer.route.methods[name],
+        );
+        for (const method of methods) {
+          out.push({ method: method.toUpperCase(), path: routePath });
+        }
+        continue;
+      }
+
+      if (layer.name === "router" && layer.handle?.stack) {
+        const mount = layer.regexp ? regexpToPrefix(layer.regexp) : "";
+        walk(layer.handle.stack, joinPath(prefix, mount));
+      }
+    }
+  }
+
+  walk(stack, "");
+  return out.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {string}
+ */
+function joinPath(a, b) {
+  if (!a) return b || "/";
+  if (!b || b === "/") return a || "/";
+  return `${a.replace(/\/+$/, "")}/${String(b).replace(/^\/+/, "")}`;
+}
+
+/**
+ * Express mount regexp → okunabilir önek. Tam doğruluk şart değil.
+ *
+ * @param {RegExp} regexp
+ * @returns {string}
+ */
+function regexpToPrefix(regexp) {
+  const source = regexp.source
+    .replace("^\\/", "/")
+    .replace("\\/?(?=\\/|$)", "")
+    .replace(/\$$/, "")
+    .replace(/\\\//g, "/")
+    .replace(/\(\?:\(\?=.*$/, "");
+  if (!source.startsWith("/")) return "";
+  const cleaned = source.replace(/[^a-zA-Z0-9/_\-.:*]/g, "");
+  return cleaned || "";
+}
+
+/**
+ * `routes/` altındaki (veya config.routes listesindeki) modül dosyaları.
+ *
+ * @returns {{ file: string, relative: string }[]}
+ */
+export function listRouteModules() {
+  const config = getConfig();
+  const root = config.root;
+
+  const files = config.routes
+    ? config.routes.map((entry) => path.resolve(root, entry))
+    : discover(config.dirs.routes);
+
+  return files.map((file) => ({
+    file,
+    relative: path.relative(root, file).replaceAll("\\", "/"),
+  }));
+}
+
+/**
+ * @param {string} dir
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+function discover(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+
+  const entries = fs
+    .readdirSync(dir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      discover(full, out);
+      continue;
+    }
+    if (!/\.(js|mjs)$/.test(entry.name)) continue;
+    if (entry.name.startsWith("_")) continue;
+    out.push(full);
+  }
+
+  return out;
+}
+
+/**
+ * `views/` altındaki şablon ve bileşen dosyaları.
+ *
+ * @returns {{ relative: string, kind: "ejs" | "js" | "other" }[]}
+ */
+export function listViews() {
+  const config = getConfig();
+  const root = config.dirs.views;
+  /** @type {{ relative: string, kind: "ejs" | "js" | "other" }[]} */
+  const out = [];
+
+  /**
+   * @param {string} dir
+   */
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      const relative = path.relative(root, full).replaceAll("\\", "/");
+      const kind = entry.name.endsWith(".ejs")
+        ? "ejs"
+        : /\.(js|mjs)$/.test(entry.name)
+          ? "js"
+          : "other";
+      out.push({ relative, kind });
+    }
+  }
+
+  walk(root);
+  return out;
+}
+
+/**
+ * Son HTTP log'larından path başına özet.
+ *
+ * @returns {Record<string, { status: number, ms: number, cache: string | null, at: number, count: number }>}
+ */
+export function routeActivity() {
+  /** @type {Record<string, { status: number, ms: number, cache: string | null, at: number, count: number }>} */
+  const byPath = {};
+
+  for (const entry of listLogs(0, 500)) {
+    if (entry.kind !== "http") continue;
+    const key = typeof entry.route === "string" && entry.route
+      ? entry.route
+      : String(entry.path ?? entry.url ?? "");
+    if (!key) continue;
+
+    const prev = byPath[key];
+    byPath[key] = {
+      status: Number(entry.status) || 0,
+      ms: Number(entry.ms) || 0,
+      cache: /** @type {string | null} */ (entry.cache ?? null),
+      at: entry.at,
+      count: (prev?.count ?? 0) + 1,
+    };
+  }
+
+  return byPath;
+}

package/src/server/admin/mount.js

@@ -0,0 +1,56 @@
+/**
+ * Framework yönetim paneli (`/_jskelet/admin`).
+ *
+ * Dev overlay'den ayrı: `NODE_ENV`'e bakmaz, yalnızca `admin().enabled` /
+ * `JSKELET_ADMIN` ile açılır. Kapalıyken modül yüklenmez ve yol yoktur.
+ *
+ * Şifre süreç başlangıcında üretilir ve log kutusunda bir kez basılır.
+ */
+import process from "node:process";
+import * as log from "../../log.mjs";
+import { getConfig } from "../../config/index.js";
+import { PASSWORD } from "./auth.js";
+import { createAdminRouter } from "./router.js";
+import { configureEventLog, requestLogMiddleware } from "./event-log.js";
+
+/** @type {typeof import('../../config/defaults.js').DEFAULT_ADMIN} */
+let settings;
+
+/**
+ * @returns {typeof import('../../config/defaults.js').DEFAULT_ADMIN}
+ */
+function getSettings() {
+  return settings;
+}
+
+/**
+ * Paneli uygulamaya bağlar, istek log middleware'ini kurar ve şifreyi loglar.
+ *
+ * @param {import('express').Express} app
+ */
+export function mountAdmin(app) {
+  settings = getConfig().admin;
+
+  configureEventLog({
+    basePath: settings.basePath,
+    logSize: settings.logSize,
+    prewarmUserAgent: String(getConfig().brand.prewarmUserAgent ?? ""),
+  });
+
+  app.use(settings.basePath, createAdminRouter(getSettings, app));
+  // Route'lardan önce mount edilir; `finish` anında Express `req.route`
+  // doldurmuş olur. Admin yolları ring'e yazılmaz.
+  app.use(requestLogMiddleware());
+
+  const port = process.env.PORT ?? 3000;
+  log.box({
+    title: "ADMIN",
+    lines: [
+      `http://localhost:${port}${settings.basePath}`,
+      "",
+      `password  ${PASSWORD}`,
+      "",
+      "Valid until this process restarts.",
+    ],
+  });
+}