@zvndev/darkmown 2.12.2 → 2.13.0

package/types/dev.d.ts

@@ -1,3 +1,31 @@
+/**
+ * The local dev/preview servers bind to loopback, but loopback alone does not
+ * keep a website you are visiting out. Two attacks reach it from a browser:
+ *
+ * - DNS rebinding: `evil.example` re-resolves to 127.0.0.1, after which the
+ *   page can READ every response (drafts, the dep map, the SSE stream, and
+ *   `api/*` handlers, which run with the full `process.env`). The browser still
+ *   sends `Host: evil.example`, so only hostnames that cannot be rebound pass:
+ *   `localhost`/`*.localhost`, IP literals (a rebinding needs a domain), the
+ *   bind address, and the `DARKMOWN_ALLOWED_HOSTS` list (a tunnel's domain).
+ * - Cross-site requests: any page can fire a simple POST at
+ *   `http://127.0.0.1:5173/api/x` without reading the reply, so the handler's
+ *   side effects run. `/api/*` therefore also refuses `Sec-Fetch-Site:
+ *   cross-site` and an `Origin` that is not loopback, the request's own host,
+ *   or allow-listed.
+ *
+ * `DARKMOWN_ALLOWED_HOSTS=*` turns the guard off.
+ * @param {{ url?: string, headers: Record<string, string | string[] | undefined> }} req
+ * @param {{ bindHost?: string, allowedHosts?: string }} [options]
+ * @returns {string | null} why the request is refused, or null to serve it
+ */
+export function refuseLocalRequest(req: {
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+}, { bindHost, allowedHosts }?: {
+    bindHost?: string;
+    allowedHosts?: string;
+}): string | null;
 /**
  * Serialize the dev server's rebuilds: at most ONE child build runs at a time.
  * Every build read-modify-writes the dependency map (`dist/.wd-dev-deps.json`),

package/types/feeds.d.ts

@@ -1,16 +1,9 @@
-/**
- * @typedef {import("./router.js").Route} Route
- */
-/**
- * A route paired with its source file's last-modified date (ISO yyyy-mm-dd),
- * ready for a sitemap `<lastmod>`.
- * @typedef {object} DatedRoute
- * @property {string} loc Absolute URL (`site_url` + route path).
- * @property {string} lastmod ISO date (`yyyy-mm-dd`).
- */
 /**
  * XML-escape a text value for use inside an element or attribute. Covers the
- * five predefined XML entities — the same set RSS/sitemap consumers expect.
+ * five predefined XML entities — the same set RSS/sitemap consumers expect —
+ * and drops the characters XML 1.0 cannot carry at all (C0 controls other than
+ * tab/LF/CR, U+FFFE/U+FFFF, lone surrogates): one in a single post title makes
+ * the whole feed malformed, and readers reject it outright.
  * @param {string} value
  * @returns {string}
  */
@@ -238,21 +231,6 @@ export const AI_CRAWLER_POLICIES: string[];
  * ({@link rssItemLimit}).
  */
 export const RSS_ITEM_LIMIT: 20;
-export type Route = import("./router.js").Route;
-/**
- * A route paired with its source file's last-modified date (ISO yyyy-mm-dd),
- * ready for a sitemap `<lastmod>`.
- */
-export type DatedRoute = {
-    /**
-     * Absolute URL (`site_url` + route path).
-     */
-    loc: string;
-    /**
-     * ISO date (`yyyy-mm-dd`).
-     */
-    lastmod: string;
-};
 /**
  * An RSS item — a dated post in feed order.
  */
@@ -268,3 +246,18 @@ export type RssItem = {
     pubDate: string;
     description: string;
 };
+export type Route = import("./router.js").Route;
+/**
+ * A route paired with its source file's last-modified date (ISO yyyy-mm-dd),
+ * ready for a sitemap `<lastmod>`.
+ */
+export type DatedRoute = {
+    /**
+     * Absolute URL (`site_url` + route path).
+     */
+    loc: string;
+    /**
+     * ISO date (`yyyy-mm-dd`).
+     */
+    lastmod: string;
+};

package/types/headers.d.ts

@@ -51,8 +51,13 @@ export const REACTIVE_CSP: string;
  */
 export const STATIC_CSP: string;
 /**
- * Baseline security headers applied to every HTML response, independent of the
+ * Baseline security headers applied to every response, independent of the
  * CSP. CSP is added per-route (static vs reactive) by the helpers below.
+ *
+ * HSTS is one year WITHOUT `includeSubDomains`/`preload`: those pin every
+ * sibling subdomain to HTTPS, which only the domain owner can safely decide.
+ * Browsers ignore the header over plain HTTP, so local `serve` is unaffected.
+ * Cloudflare custom domains send no HSTS unless the zone enables it.
  * @type {Record<string, string>}
  */
 export const BASE_SECURITY_HEADERS: Record<string, string>;