kreftjs 0.0.21-beta → 0.0.22-beta

package/bin/backend/shield.js

@@ -0,0 +1,266 @@
+/*
+ * Kreft Shield: automatic protection against floods and abuse from a single address.
+ *
+ *   SHIELD=true          in .env turns it on (off by default). Changes to .env apply without a restart.
+ *
+ * What it does, per visitor address (the same req.ip() that throttle uses, so TRUSTED_PROXIES applies):
+ *   1. Rate limit: more than SHIELD_MAX_REQUESTS (300) in SHIELD_WINDOW_SEC (10) seconds → 429 + Retry-After.
+ *      Responses that look like probing (401, 403, 404, 405) count SHIELD_ERROR_WEIGHT (5) times, so scanners
+ *      and password guessers hit the limit sooner than normal visitors.
+ *   2. Concurrency: more than SHIELD_MAX_CONCURRENT (60) requests of one address in flight at once → 429.
+ *   3. Ban: SHIELD_STRIKES (3) rate-limit hits within SHIELD_STRIKE_WINDOW_MIN (10) minutes → the address is
+ *      refused for SHIELD_BAN_MINUTES (15), doubling at every repeat (up to 24 hours). Banned requests are
+ *      answered with a bare 429 before any work is done.
+ *   4. Connections: more than SHIELD_MAX_CONNECTIONS (100) open sockets from one address are closed at once, which
+ *      stops slow-connection floods (slowloris) that never finish a request. Needs Shield.watch(server) (kreft does it).
+ *   5. Overload: when the event loop lags by more than SHIELD_MAX_LAG_MS (300), limits shrink to a quarter
+ *      so the server keeps answering instead of falling over.
+ *
+ * Never limited: SHIELD_ALLOW="1.2.3.4,5.6.7.8" and, unless SHIELD_LOCAL=true, this computer (127.0.0.1, ::1).
+ * Bans live in memory: a restart clears them. For a flood bigger than one process can absorb, put a firewall
+ * or CDN in front; the Shield protects the application, it does not replace network-level DDoS protection.
+ *
+ *   const { Shield } = require('kreftjs/server')
+ *   Shield.bans()  Shield.unban('1.2.3.4')  Shield.ban('1.2.3.4', 60)  Shield.status()  Shield.on('ban', fn)
+ */
+const { EventEmitter } = require('events');
+
+const events = new EventEmitter();
+const ips = new Map(); // address → { windowStart, count, struck, strikes: [ms], level, lastBanAt, bannedUntil, inflight, last }
+const MAX_ENTRIES = 100000;
+const DAY = 86400000;
+
+let cfgAt = 0;
+let cfg = null;
+let lagMonitor = null;
+let lagMs = 0;
+let timers = [];
+let warnedProxy = false;
+const conns = new Map(); // direct socket address → open connections
+const stats = { blocked: 0, limited: 0, bans: 0 };
+
+const num = (v, d) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : d);
+const flag = (v) => ['true', '1', 'on', 'yes'].includes(String(v || '').trim().toLowerCase());
+
+function config() {
+  const now = Date.now();
+  if (cfg && now - cfgAt < 2000) return cfg;
+  const e = process.env;
+  cfg = {
+    enabled: flag(e.SHIELD),
+    maxRequests: num(e.SHIELD_MAX_REQUESTS, 300),
+    windowMs: num(e.SHIELD_WINDOW_SEC, 10) * 1000,
+    errorWeight: num(e.SHIELD_ERROR_WEIGHT, 5),
+    maxConcurrent: num(e.SHIELD_MAX_CONCURRENT, 60),
+    maxConnections: num(e.SHIELD_MAX_CONNECTIONS, 100),
+    strikes: num(e.SHIELD_STRIKES, 3),
+    strikeWindowMs: num(e.SHIELD_STRIKE_WINDOW_MIN, 10) * 60000,
+    banMs: num(e.SHIELD_BAN_MINUTES, 15) * 60000,
+    maxLagMs: num(e.SHIELD_MAX_LAG_MS, 300),
+    local: flag(e.SHIELD_LOCAL),
+    allow: new Set(String(e.SHIELD_ALLOW || '').split(',').map((x) => x.trim().replace(/^::ffff:/, '')).filter(Boolean)),
+  };
+  cfgAt = now;
+  return cfg;
+}
+
+const isLoopback = (ip) => ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+const normalize = (ip) => String(ip || '').replace(/^::ffff:/, '');
+
+// One IPv6 customer owns a whole /64 (billions of addresses): counting single addresses would let an attacker
+// rotate through them and never be limited. IPv6 visitors are counted by their /64 prefix, IPv4 by address.
+function keyOf(ip) {
+  if (!ip.includes(':')) return ip;
+  const s = ip.split('%')[0];
+  if (s.includes('.')) return ip; // an embedded IPv4 form: leave as is
+  const dbl = s.includes('::');
+  const [h, t] = s.split('::');
+  const head = h ? h.split(':') : [];
+  const tail = dbl && t ? t.split(':') : [];
+  const fill = dbl ? 8 - head.length - tail.length : 0;
+  if (fill < 0 || (!dbl && head.length !== 8)) return ip;
+  const groups = [...head, ...Array(fill).fill('0'), ...tail].map((x) => parseInt(x, 16));
+  if (groups.length !== 8 || groups.some((x) => Number.isNaN(x))) return ip;
+  return groups.slice(0, 4).map((x) => x.toString(16)).join(':') + '::/64';
+}
+
+function entry(ip, now) {
+  let e = ips.get(ip);
+  if (!e) {
+    if (ips.size >= MAX_ENTRIES) prune(true);
+    e = { windowStart: now, count: 0, struck: false, strikes: [], level: 0, lastBanAt: 0, bannedUntil: 0, inflight: 0, last: now };
+    ips.set(ip, e);
+  }
+  e.last = now;
+  return e;
+}
+
+// Drops addresses that are idle and not banned. `hard` also drops the oldest when the table is full.
+function prune(hard = false) {
+  const now = Date.now();
+  for (const [ip, e] of ips) {
+    if (e.bannedUntil > now || e.inflight > 0) continue;
+    if (now - e.last > 10 * 60000 && (!e.lastBanAt || now - e.lastBanAt > DAY)) ips.delete(ip);
+  }
+  if (hard && ips.size >= MAX_ENTRIES) {
+    for (const [ip, e] of ips) { if (e.bannedUntil <= now && e.inflight === 0) { ips.delete(ip); if (ips.size < MAX_ENTRIES * 0.9) break; } }
+  }
+}
+
+function ensureRunning() {
+  if (timers.length) return;
+  try {
+    const { monitorEventLoopDelay } = require('perf_hooks');
+    lagMonitor = monitorEventLoopDelay({ resolution: 20 });
+    lagMonitor.enable();
+  } catch (_) { lagMonitor = null; }
+  const t1 = setInterval(() => {
+    if (lagMonitor) { lagMs = lagMonitor.percentile(99) / 1e6; lagMonitor.reset(); }
+    const c = config();
+    if (c.enabled && lagMs > c.maxLagMs && !ensureRunning.warned) {
+      ensureRunning.warned = true;
+      console.warn(`  [Kreft Shield] The server is overloaded (event loop lag ${Math.round(lagMs)} ms): per-address limits are cut to a quarter.`);
+    } else if (lagMs <= c.maxLagMs) ensureRunning.warned = false;
+  }, 5000);
+  const t2 = setInterval(() => prune(), 60000);
+  timers = [t1, t2];
+  timers.forEach((t) => t.unref && t.unref());
+  try { require('./gc.js').onMemoryPressure('shield', () => { const before = ips.size; prune(true); return before - ips.size; }); } catch (_) {}
+}
+
+function banEntry(ip, e, ms, reason) {
+  const now = Date.now();
+  e.bannedUntil = now + ms;
+  e.lastBanAt = now;
+  e.level++;
+  e.strikes = [];
+  stats.bans++;
+  const info = { ip, minutes: Math.round(ms / 60000), reason, until: new Date(e.bannedUntil).toISOString(), level: e.level };
+  console.warn(`  [Kreft Shield] Banned ${ip} for ${info.minutes} min (${reason}).`);
+  events.emit('ban', info);
+  return info;
+}
+
+function refuse(res, seconds, why) {
+  stats.blocked++;
+  try {
+    res.writeHead(429, { 'Retry-After': String(Math.max(1, Math.ceil(seconds))), 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store', Connection: 'close' });
+    res.end(why);
+  } catch (_) { try { res.destroy(); } catch (__) {} }
+  return true;
+}
+
+/**
+ * Call first for every request. Returns true when it already answered (the request must stop there).
+ */
+function guard(req, res) {
+  const c = config();
+  if (!c.enabled) return false;
+  ensureRunning();
+  let ip;
+  try { ip = normalize(require('./http.js').Request.prototype.ip.call({ raw: req })); } catch (_) { ip = normalize(req.socket && req.socket.remoteAddress); }
+  if (!ip) return false;
+  // Behind a proxy that is not in TRUSTED_PROXIES every visitor looks like the proxy: one address (all users would
+  // share one limit and one ban) or, for a proxy on this computer, loopback (which is never limited). Say so once.
+  if (!warnedProxy && req.headers['x-forwarded-for'] && ip === normalize(req.socket && req.socket.remoteAddress)) {
+    warnedProxy = true;
+    console.warn(`  [Kreft Shield] Requests carry X-Forwarded-For, but ${ip} is not in TRUSTED_PROXIES, so the real visitor address is unknown and the Shield cannot tell visitors apart. Behind nginx, Caddy or a CDN, set TRUSTED_PROXIES in .env.`);
+  }
+  if (c.allow.has(ip) || (isLoopback(ip) && !c.local)) return false;
+
+  const now = Date.now();
+  const key = keyOf(ip);
+  const e = entry(key, now);
+
+  if (e.bannedUntil > now) return refuse(res, (e.bannedUntil - now) / 1000, 'Too many requests. Try again later.');
+  if (e.bannedUntil && e.bannedUntil <= now) e.bannedUntil = 0;
+  if (e.level && e.lastBanAt && now - e.lastBanAt > DAY) e.level = 0;
+
+  if (now - e.windowStart >= c.windowMs) { e.windowStart = now; e.count = 0; e.struck = false; }
+  e.strikes = e.strikes.filter((t) => now - t < c.strikeWindowMs);
+
+  const overloaded = lagMs > c.maxLagMs;
+  const limit = Math.max(5, Math.floor(c.maxRequests / (overloaded ? 4 : 1)));
+  const concurrent = Math.max(3, Math.floor(c.maxConcurrent / (overloaded ? 4 : 1)));
+  e.count++;
+
+  const overRate = e.count > limit;
+  const overConc = e.inflight >= concurrent;
+  if (overRate || overConc) {
+    stats.limited++;
+    if (!e.struck) {
+      e.struck = true;
+      e.strikes.push(now);
+      if (e.strikes.length >= c.strikes) {
+        const ms = Math.min(DAY, c.banMs * 2 ** e.level);
+        banEntry(key, e, ms, `${e.strikes.length} rate-limit hits in ${Math.round(c.strikeWindowMs / 60000)} min`);
+        return refuse(res, ms / 1000, 'Too many requests. Try again later.');
+      }
+    }
+    return refuse(res, (e.windowStart + c.windowMs - now) / 1000, 'Too many requests. Slow down.');
+  }
+
+  e.inflight++;
+  let done = false;
+  const finish = () => { if (done) return; done = true; e.inflight = Math.max(0, e.inflight - 1); };
+  res.once('close', finish);
+  res.once('finish', () => {
+    // probing (wrong login, missing pages, forbidden) costs more, so scanners trip the limit early
+    const s = res.statusCode;
+    if (s === 401 || s === 403 || s === 404 || s === 405) e.count += c.errorWeight - 1;
+    finish();
+  });
+  return false;
+}
+
+const Shield = {
+  guard,
+  enabled: () => config().enabled,
+  on: (event, fn) => { events.on(event, fn); return Shield; },
+  off: (event, fn) => { events.off(event, fn); return Shield; },
+  /**
+   * Caps open connections per direct address (call once on the http.Server). Connections from this computer or from a
+   * proxy in TRUSTED_PROXIES are not capped here: they carry many visitors, and the request limits tell those apart.
+   */
+  watch(server) {
+    server.on('connection', (sock) => {
+      const c = config();
+      if (!c.enabled) return;
+      const ip = normalize(sock.remoteAddress);
+      const trusted = String(process.env.TRUSTED_PROXIES || '').split(',').map((x) => normalize(x.trim())).filter(Boolean);
+      if (!ip || c.allow.has(ip) || (isLoopback(ip) && !c.local) || trusted.includes('*') || trusted.includes(ip)) return;
+      const key = keyOf(ip);
+      const n = (conns.get(key) || 0) + 1;
+      if (n > c.maxConnections) { stats.blocked++; sock.destroy(); return; }
+      conns.set(key, n);
+      sock.once('close', () => { const m = (conns.get(key) || 1) - 1; if (m <= 0) conns.delete(key); else conns.set(key, m); });
+    });
+    return Shield;
+  },
+  /** Currently banned addresses. */
+  bans() {
+    const now = Date.now();
+    const out = [];
+    for (const [ip, e] of ips) if (e.bannedUntil > now) out.push({ ip, until: new Date(e.bannedUntil).toISOString(), level: e.level, secondsLeft: Math.ceil((e.bannedUntil - now) / 1000) });
+    return out;
+  },
+  ban(ip, minutes = 60, reason = 'manual') { const a = keyOf(normalize(ip)); return banEntry(a, entry(a, Date.now()), minutes * 60000, reason); },
+  unban(ip) {
+    const e = ips.get(keyOf(normalize(ip)));
+    if (!e) return false;
+    e.bannedUntil = 0; e.level = 0; e.strikes = []; e.count = 0; e.struck = false;
+    return true;
+  },
+  status() {
+    const c = config();
+    return { enabled: c.enabled, tracked: ips.size, banned: Shield.bans().length, ...stats, eventLoopLagMs: Math.round(lagMs), overloaded: lagMs > c.maxLagMs, limits: { maxRequests: c.maxRequests, windowSec: c.windowMs / 1000, maxConcurrent: c.maxConcurrent, strikes: c.strikes, banMinutes: c.banMs / 60000 } };
+  },
+  /** For tests: forget everything and stop the timers. */
+  reset() {
+    ips.clear(); conns.clear(); warnedProxy = false; cfg = null; lagMs = 0; stats.blocked = stats.limited = stats.bans = 0;
+    timers.forEach(clearInterval); timers = [];
+    if (lagMonitor) { try { lagMonitor.disable(); } catch (_) {} lagMonitor = null; }
+  },
+};
+
+module.exports = { Shield, _keyOf: keyOf };

package/bin/db-api.js

@@ -16,10 +16,14 @@
  * Which tables, and what each allows, comes from `tables` (kreftjs.config.json):
  *   { "posts": true, "users": { "write": false, "hidden": ["password"] }, "logs": false }
  * `kreft dev` shows every table unless you list them; `kreft serve` shows only the tables you list.
+ * Credential-looking columns (password, token, secret, hash, …) are hidden by default ("show": ["token"] opens one), and
+ * tables of sessions, tokens and jobs are only opened when named in the list.
  */
 const { validate } = require('../kreftjs.js'); // the same rules as Kreftjs.validate in the browser
 const MAX_BODY = 1024 * 1024;
 const MAX_ROWS = 1000;
+const SECRET_COL_RE = /(password|passwd|secret|token|api_?key|private_?key|recovery_?code|remember|two_factor|salt|hash)/i;
+const SECRET_TABLE_RE = /^(personal_access_tokens|password_reset_tokens|password_resets|sessions|failed_jobs|jobs|job_batches|cache|cache_locks)$/i;
 
 function createDbApi(db, { tables: allow = null, production = false, prefix = '/api', log = console } = {}) {
   const isProd = Boolean(production || process.env.APP_ENV === 'production' || process.env.NODE_ENV === 'production');
@@ -29,13 +33,17 @@ function createDbApi(db, { tables: allow = null, production = false, prefix = '/
     const out = new Map();
     for (const t of all) {
       if (t.name === 'kreft_migrations') continue;
+      // tables that hold logins, tokens or queued payloads are never shown by default, even by `kreft dev` with no list:
+      // only a table named in kreftjs.config.json is opened
+      if (SECRET_TABLE_RE.test(t.name) && !(allow && allow[t.name] != null && allow[t.name] !== false)) continue;
       let rules = allow ? allow[t.name] : true;
       if (rules == null || rules === false) continue;
       if (rules === true) rules = {};
       const write = rules.write === undefined ? true : rules.write;
       out.set(t.name, {
         ...t,
-        hidden: new Set(rules.hidden || []),
+        // columns that look like credentials are hidden unless "show": ["token"] lists them (a "hidden" list adds to them)
+        hidden: new Set([...t.columns.map((c) => c.name).filter((n) => SECRET_COL_RE.test(n) && !(rules.show || []).includes(n)), ...(rules.hidden || [])]),
         rules: rules.rules || null, // { "title": "required|min:3", "email": "required|email" }
         can: {
           read: rules.read !== false,

package/bin/kreftjs.js

@@ -640,7 +640,7 @@ function installVscode() {
 /* ------------------------------------------------------------------ kreft dev */
 async function devServer(args, { production = false } = {}) {
   const isProd = Boolean(production || process.env.APP_ENV === 'production' || process.env.NODE_ENV === 'production');
-  let port = production ? Number(process.env.PORT) || 8000 : 8000, folder = production ? 'dist' : '.', apiFile = null, delay = 0, saveApi = true, hot = !production, dbUrl = null, migrations = null, serverFolder = null, backendFolder = null, seedNew = false;
+  let port = production ? Number(process.env.PORT) || 8000 : 8000, folder = production ? 'dist' : '.', apiFile = null, delay = 0, saveApi = true, hot = !production, dbUrl = null, migrations = null, serverFolder = null, backendFolder = null, seedNew = false, force = false;
   // kreft dev only answers this computer; --host 0.0.0.0 shares it on your network.
   // kreft serve answers everyone (HOST in the environment can narrow it).
   let host = production ? process.env.HOST || '0.0.0.0' : '127.0.0.1';
@@ -655,6 +655,7 @@ async function devServer(args, { production = false } = {}) {
     else if (args[i] === '--server') serverFolder = path.resolve(args[++i]);
     else if (args[i] === '--backend') backendFolder = path.resolve(args[++i]);
     else if (args[i] === '--seed') seedNew = true;
+    else if (args[i] === '--force') force = true;
     else if (args[i] === '--host') host = args[++i];
     else if (/^\d+$/.test(args[i])) port = Number(args[i]);
     else folder = args[i];
@@ -680,6 +681,16 @@ async function devServer(args, { production = false } = {}) {
   const backendDir = backendFolder || (lay.split ? lay.backend : envDir);
   const apiRoutesFile = require('./backend/typescript.js').findFile(path.join(backendDir, 'routes', 'api')); // api.js or api.ts
   const hasBackend = Boolean(apiRoutesFile);
+  // Not a Kreft project and nothing to show: do not start a server on whatever folder this happens to be (an empty
+  // one, or your home folder). --force serves it anyway.
+  if (!force && !dbUrl && !apiFile && !serverFolder && !hasBackend && !lay.split) {
+    const names = (() => { try { return fs.readdirSync(root); } catch (_) { return []; } })();
+    const isSite = names.includes('index.html') || names.some((n) => /\.kreft$/.test(n)) || fs.existsSync(path.join(root, 'demo', 'index.html')) || fs.existsSync(path.join(config.dir || root, 'kreftjs.config.json'));
+    if (!isSite) {
+      console.error(`  ${path.resolve(root)} is not a Kreft project: there is no index.html, no frontend/ folder and no .kreft pages.\n\n  Make one:                  kreft new my-app   (then: cd my-app, kreft dev)\n  Or go into your project:   cd path/to/your-app\n  To serve this folder anyway: kreft ${production ? 'serve' : 'dev'} ${folder === '.' ? '' : folder + ' '}--force`);
+      process.exit(1);
+    }
+  }
   // kreftjs serve: the backend must not sit inside the folder that is served, or its files could be downloaded
   if (production && hasBackend && (backendDir === root || backendDir.startsWith(root + path.sep))) {
     console.error(`  The backend (${backendDir}) is inside the folder being served (${root}).\n  Serve the built site instead: kreft build, then kreft serve dist`);
@@ -1060,6 +1071,8 @@ async function devServer(args, { production = false } = {}) {
 
   const server = http.createServer(async (req, res) => {
     try {
+      // SHIELD=true in .env: rate limits, bans and load shedding per visitor address (see backend/shield.js)
+      if (require('./backend/shield.js').Shield.guard(req, res)) return;
       if (loopbackBind && !isLocalName(hostOnly(req.headers.host)) && !allowedHosts.has(hostOnly(req.headers.host))) {
         res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
         return res.end(`Blocked: this server only answers localhost. To reach it by the name "${hostOnly(req.headers.host)}", start it with KREFT_ALLOWED_HOSTS=${hostOnly(req.headers.host)} (or --host 0.0.0.0 to share it on your network).`);
@@ -1177,6 +1190,7 @@ async function devServer(args, { production = false } = {}) {
 
   // if the port is taken (another server is still running), try the next one
   let tries = 0;
+  require('./backend/shield.js').Shield.watch(server); // SHIELD=true: caps open connections per address
   server.on('error', (err) => {
     if (err.code === 'EADDRINUSE' && tries < 20) {
       console.log(`  Port ${port + tries} is already in use by another program, trying ${port + tries + 1}…`);

package/docs/README.md

@@ -82,7 +82,7 @@ npx kreftjs@latest new my-app
 ### Check that it works
 
 ```bash
-kreft --version     # for example 0.0.21-beta
+kreft --version     # for example 0.0.22-beta
 kreft about         # Kreft and Node.js versions, this project's settings and drivers
 kreft list          # every command your version has
 ```
@@ -1291,10 +1291,36 @@ Generate one with `kreft make:controller PostController --api` (also `--model Po
 |---|---|
 | `req.input('name', default)`, `req.all()`, `req.only('a', 'b')`, `req.except(…)`, `req.has(…)`, `req.filled(…)` | Values from the body and the query. |
 | `req.boolean('x')`, `req.integer('page', 1)`, `req.string('q')` | A value in the right type. |
-| `await req.validate(rules)` | The same rules as `form()`, plus `unique:table,column` and `exists:table,column`. Returns only the checked fields, or answers `422`. |
+| `await req.validate(rules, messages, names)` | The same rules as `form()`, plus `unique:table,column` and `exists:table,column`. Returns only the checked fields, or answers `422`. `messages` are your own texts (`{ 'title.unique': 'That title is already used.' }`, or `{ unique: '…' }` for every field); `names` are nicer field names (`{ email: 'e-mail address' }`). |
 | `req.params`, `req.query`, `req.body`, `req.header('x')`, `req.bearerToken()`, `req.ip()`, `req.user` | The rest. |
 | `req.file('avatar').store('avatars')` | Saves an upload with a random name. |
 | `response(data, 201)`, `response(data).header('X', 'y')`, `abort(403, 'message')` | Answers. |
+| `response.stream('/path/video.mp4', { type, download, headers })` | Sends a file with byte ranges. See [Video and audio files](#video-and-audio-files). |
+
+### Video and audio files
+
+To serve a video or audio file, return `response.stream(path)` instead of reading the file yourself:
+
+```js
+const path = require('path')
+
+Route.get('/videos/:name', (req) =>
+  response.stream(path.join(__dirname, '../storage/videos', path.basename(req.params.name))))
+
+Route.get('/podcast/:id/download', (req) =>
+  response.stream('/var/media/episode.mp3', { download: true }))   // saved as a file instead of played
+```
+
+- **Seeking works.** The server answers `Range` requests with `206 Partial Content`, so a player can jump to any minute without downloading the rest, and Safari, which refuses to play video without ranges, plays it. A range that does not fit the file gets `416`.
+- **Only the needed bytes are read**, and reading stops when the viewer leaves or seeks elsewhere.
+- **Caching is built in.** The answer carries `ETag` and `Last-Modified`, so an unchanged file is answered with `304`. `HEAD` requests get the headers only.
+- **A missing file is a plain `404`**, not a crash.
+- Options: `type` (the media type; guessed from the extension for `mp4`, `webm`, `mov`, `mp3`, `m4a`, `ogg`, `wav`, `flac`, `m3u8`, `mpd`, `vtt` …), `download: true` (adds `Content-Disposition: attachment`), and `headers` (extra headers).
+
+> [!WARNING]
+> Never build the path straight from the request. Use `path.basename(...)` as above, or look the file up in your database, so nobody can ask for `../../.env`.
+
+`kreft dev` and `kreft serve` also send the static media files of your app (`.mp4`, `.webm`, `.mp3`, HLS playlists …) with ranges, so a `<video src="/intro.mp4" controls>` seeks without any code.
 
 ### Form requests, resources and policies
 
@@ -1350,6 +1376,8 @@ class Post extends Model {
 module.exports = Post
 ```
 
+**Always set `static fillable`.** Without it a model lets `create()` and `update()` set every column except `id`, so `Post.create(req.all())` would save `{ "is_admin": true }` from a visitor. The controllers made by `kreft make:controller --model` read only the `fillable` columns (`req.only(...Model.fillable)`) and stop with an error until you set it. Kreft prints a warning when a model without `fillable` is given a privilege-looking column (`is_admin`, `role`, `permissions` …).
+
 The table is the plural of the class name (`Post` is `posts`); set `static table = '…'` for another one.
 
 ### Querying
@@ -2263,10 +2291,80 @@ curl -H "Authorization: Bearer a-long-random-secret" -d '{"jsonrpc":"2.0","id":1
 > [!WARNING]
 > The MCP database tool can still read every other table. Use a database account with read-only access and no access to credentials, and keep the token out of version control.
 
+### Calling other MCP servers (client)
+
+Your app can also call tools on a remote MCP server over Streamable HTTP:
+
+```js
+const { Mcp } = require('kreftjs/server')
+
+const quran = await Mcp.connect('https://mcp.quran.ai')   // { headers: { Authorization: 'Bearer …' } } if needed
+const tools = await quran.tools()
+const verses = await quran.call('fetch_quran', { ayahs: '1:1-2' })
+await quran.close()
+```
+
+`call` returns the structured result (or the text, parsed as JSON when possible) and throws if the tool reports an error. Only `http(s)` URLs are accepted, redirects are refused, and a response over `maxBytes` (10 MB) is cut off. Never pass a URL a visitor typed: your server would fetch addresses of their choosing, including your internal network (SSRF). Use a fixed or allow-listed URL.
+
+## Running `kreft dev` outside a project
+
+`kreft dev` and `kreft serve` start only in a Kreft project: a folder with `index.html`, a `frontend/` folder, `.kreft` pages, a backend or a `kreftjs.config.json`. In any other folder (an empty one, your home folder) they stop and say so, instead of serving whatever is there. `kreft dev --force` serves the folder anyway. `kreft run dev` is not a command: inside a project use `kreft dev`, or `npm run dev`.
+
+## Kreft Shield
+
+Floods and scanners from one address can slow a server to a crawl. Turn on the Shield with one line in `.env` (changes apply without a restart):
+
+```
+SHIELD=true
+```
+
+For every visitor address (the same `req.ip()` that `throttle` uses, so set `TRUSTED_PROXIES` behind a proxy):
+
+| Protection | Default | Setting |
+|---|---|---|
+| Rate limit: over the limit answers `429` with `Retry-After` | 300 requests in 10 s | `SHIELD_MAX_REQUESTS`, `SHIELD_WINDOW_SEC` |
+| Probing counts more: `401`, `403`, `404` and `405` answers weigh 5 requests | 5 | `SHIELD_ERROR_WEIGHT` |
+| Concurrency: requests in flight at once from one address | 60 | `SHIELD_MAX_CONCURRENT` |
+| Ban: this many rate-limit hits within the strike window | 3 hits in 10 min | `SHIELD_STRIKES`, `SHIELD_STRIKE_WINDOW_MIN` |
+| Ban length, doubling at every repeat up to 24 h | 15 min | `SHIELD_BAN_MINUTES` |
+| Connections: open sockets from one address; extra ones are closed (stops slowloris floods that never finish a request) | 100 | `SHIELD_MAX_CONNECTIONS` |
+| Overload: when the event loop lags, limits shrink to a quarter | 300 ms lag | `SHIELD_MAX_LAG_MS` |
+
+IPv6 visitors are counted by their `/64` prefix, because one customer owns billions of addresses in it and could otherwise rotate through them.
+
+**Behind nginx, Caddy or a CDN, set `TRUSTED_PROXIES`.** Without it every visitor looks like the proxy: all users would share one limit and one ban, and a proxy on the same computer (`127.0.0.1`) is never limited at all. The Shield prints a warning when it sees `X-Forwarded-For` from an address that is not trusted.
+
+Never limited: addresses in `SHIELD_ALLOW="1.2.3.4,5.6.7.8"` and this computer (`127.0.0.1`, `::1`), unless `SHIELD_LOCAL=true` (use it to try the Shield on your own machine). A banned address is answered with a bare `429` before any work is done.
+
+```js
+const { Shield } = require('kreftjs/server')
+Shield.on('ban', (b) => Log.warning(`banned ${b.ip} for ${b.minutes} min: ${b.reason}`))
+Shield.bans()            // who is banned now
+Shield.unban('1.2.3.4')  // let an address back in
+Shield.ban('1.2.3.4', 60)
+Shield.status()          // counters, limits, event-loop lag
+```
+
+The MCP tool `shield_status` returns the same. Bans are kept in memory, so a restart clears them. The Shield protects the application; a flood that fills your network connection has to be stopped by a firewall or a CDN in front of the server.
+
 ## Memory watchdog
 
 Long-running servers can slowly collect memory. Start with `--gc` (or `AUTO_GC=1`) and Kreft samples the heap every 30 seconds (`AUTO_GC_INTERVAL_MS`). When it passes `AUTO_GC_THRESHOLD_MB`, Kreft clears its own caches and runs garbage collection. This is a safety net; find the leak if you see it often.
 
+The watchdog is a small memory manager:
+
+- **Adaptive.** A cleanup also runs when the heap keeps growing (more than `AUTO_GC_GROWTH_MB_PER_MIN`, default 20) while already above 60% of the threshold, not only after it passes the limit.
+- **Least-used first.** The in-memory cache (`CACHE_STORE=memory`) keeps at most `CACHE_MEMORY_MAX` entries (default 5000) and, under pressure, drops expired and least recently used entries instead of everything. Register your own cache with `onMemoryPressure('name', (fraction) => dropped)`.
+- **Leak hint.** After each real GC (needs `--gc`) Kreft records the heap that remains. If it keeps rising by `AUTO_GC_LEAK_RISE_MB` (default 20) over several collections, it reports a suspected leak. `writeHeapSnapshot()` saves a `.heapsnapshot` for Chrome DevTools to show what holds the memory.
+- **Alerts.** `onMemoryAlert((alert) => …)` is called when memory is still high after `AUTO_GC_ALERT_AFTER` cleanups in a row (default 3), or a leak is suspected, at most once per 10 minutes. Without a listener the alert is printed as a warning.
+- **Report.** `getMemoryReport()` returns the samples, trend, GC and eviction counts, leak state and alerts as JSON; the MCP tool `memory_report` returns the same.
+
+```js
+const { getMemoryReport, onMemoryAlert } = require('kreftjs/server')
+onMemoryAlert((a) => Log.warning(a.message))
+Route.get('/admin/memory', () => getMemoryReport()).middleware('auth')
+```
+
 # Security
 
 ## Security overview

package/editors/sublime/Comments.tmPreferences

@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
 	<key>scope</key>
@@ -10,12 +11,14 @@
 			<dict>
 				<key>name</key>
 				<string>TM_COMMENT_START</string>
-				<value><![CDATA[<!-- ]]></value>
+				<key>value</key>
+				<string>&lt;!-- </string>
 			</dict>
 			<dict>
 				<key>name</key>
 				<string>TM_COMMENT_END</string>
-				<value><![CDATA[ -->]]></value>
+				<key>value</key>
+				<string> --&gt;</string>
 			</dict>
 		</array>
 	</dict>

package/editors/sublime/Kreft.sublime-syntax

@@ -3,8 +3,37 @@
 name: Kreft
 scope: text.html.kreft
 version: 2
-extends: Packages/HTML/HTML.sublime-syntax
 file_extensions:
   - kreft
   - kreftjs
 first_line_match: ^\s*<view\b
+
+contexts:
+  main:
+    # <view>, <script> and <style> blocks are HTML (with JS and CSS inside)
+    - match: (?i)(?=<view\b)
+      embed: scope:text.html.basic
+      embed_scope: text.html.embedded.kreft
+      escape: (?i)(?<=</view>)
+    - match: (?i)(?=<script\b)
+      embed: scope:text.html.basic
+      embed_scope: text.html.embedded.kreft
+      escape: (?i)(?<=</script>)
+    - match: (?i)(?=<style\b)
+      embed: scope:text.html.basic
+      embed_scope: text.html.embedded.kreft
+      escape: (?i)(?<=</style>)
+    - match: <!--
+      scope: punctuation.definition.comment.begin.html
+      push: html-comment
+    # everything else at the top level is the component's JavaScript
+    - match: '^\s*(layout|prop|state|saved|derive|action|load|watch|when|on|event|use|share|receive)\b'
+      captures:
+        1: keyword.control.kreft storage.type.kreft
+    - include: scope:source.js
+
+  html-comment:
+    - meta_scope: comment.block.html
+    - match: -->
+      scope: punctuation.definition.comment.end.html
+      pop: true

package/editors/sublime/layout.sublime-snippet

@@ -4,5 +4,5 @@ layout ${1:app}
 ]]></content>
 	<tabTrigger>layout</tabTrigger>
 	<scope>text.html.kreft</scope>
-	<description>This page goes inside layouts/<name>.kreft (layout none: no layout)</description>
+	<description>This page goes inside layouts/&lt;name&gt;.kreft (layout none: no layout)</description>
 </snippet>

package/editors/sublime/section.sublime-snippet

@@ -6,5 +6,5 @@
 ]]></content>
 	<tabTrigger>kreft-section</tabTrigger>
 	<scope>text.html.kreft</scope>
-	<description>Content for the layout's <kreft-yield name></description>
+	<description>Content for the layout's &lt;kreft-yield name&gt;</description>
 </snippet>

package/editors/sublime/yield.sublime-snippet

@@ -4,5 +4,5 @@
 ]]></content>
 	<tabTrigger>kreft-yield</tabTrigger>
 	<scope>text.html.kreft</scope>
-	<description>In a layout: where a page's <kreft-section> goes</description>
+	<description>In a layout: where a page's &lt;kreft-section&gt; goes</description>
 </snippet>

package/kreftjs.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for Kreft 0.0.21-beta
+// Type definitions for Kreft 0.0.22-beta
 // Use from TypeScript or for editor hints in plain JavaScript (// @ts-check).
 
 export interface Signal<T> { value: T }

package/kreftjs.js

@@ -1,5 +1,5 @@
 /*!
- * Kreft v0.0.21-beta — reactive by nature
+ * Kreft v0.0.22-beta — reactive by nature
  * The .kreft component language (state · derive · action · when · watch · on),
  * { } views with k-if / k-each / k-model, components, slots, router, stores,
  * share / receive, event bus and a template engine.
@@ -5601,7 +5601,7 @@
     stores, storeLog, busLog,
   };
 
-  const VERSION = '0.0.21-beta';
+  const VERSION = '0.0.22-beta';
   const Kreftjs = {
     version: VERSION,
     // PUBLIC_ values from .env (kreft dev and kreft build put them here); never secrets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kreftjs",
-  "version": "0.0.21-beta",
+  "version": "0.0.22-beta",
   "description": "A tiny reactive framework with its own component language (.kreft files): router with nested routes, stores, saved data, animations, an API client, hot reload, DevTools and a template engine.",
   "license": "Elastic-2.0",
   "main": "kreftjs.js",
@@ -14,7 +14,7 @@
     "start": "node bin/kreftjs.js dev --api demo/db.json --db sqlite:demo/database/demo.db --migrations demo/database/migrations --server demo/server --backend demo --seed",
     "build": "node bin/kreftjs.js build demo --out dist/kreftjs-com --base / --include docs",
     "preview": "node bin/kreftjs.js dev dist --api demo/db.json --db sqlite:demo/database/demo.db --migrations demo/database/migrations --server demo/server --backend demo --seed",
-    "test": "node --test test/security.test.js test/prerender.test.js test/seo.test.js test/rebrand.test.js test/noauth.test.js test/winspawn.test.js test/htaccess.test.js test/cookie-secure.test.js test/password-rule.test.js test/headline.test.js test/menu.test.js test/electron-all.test.js test/build-minify.test.js test/stream.test.js test/syntax.test.js",
+    "test": "node --test test/security.test.js test/prerender.test.js test/seo.test.js test/rebrand.test.js test/noauth.test.js test/winspawn.test.js test/htaccess.test.js test/cookie-secure.test.js test/password-rule.test.js test/headline.test.js test/menu.test.js test/electron-all.test.js test/build-minify.test.js test/stream.test.js test/syntax.test.js test/memory.test.js test/shield.test.js test/mcp-client.test.js test/dbapi-secrets.test.js test/auth-csrf.test.js test/not-a-project.test.js",
     "electron": "kreftjs electron",
     "electron:dev": "kreftjs electron:dev",
     "electron:build": "kreftjs electron:build"
@@ -31,6 +31,7 @@
     "docs/",
     "book/",
     "assets/logo.png",
+    "!book/~$*",
     "README.md"
   ],
   "keywords": [