@naulon/sdk 0.1.0

package/dist/crawl/fetcher.js

@@ -0,0 +1,106 @@
+/**
+ * crawl/fetcher.ts — the guarded `Fetcher` the crawl orchestrator hands every adapter.
+ *
+ * It enforces three things before a byte is sent, so an adapter that derives a URL can only
+ * ever reach the one host the publisher owns:
+ *   1. VERIFIED-ORIGIN-ONLY — the request host must equal the configured origin host.
+ *   2. SSRF CIDR block — the resolved IP must not be private/loopback/link-local (`net.ts`).
+ *   3. ANTI-DNS-REBIND — the socket connects to the IP the guard validated, via the connect-
+ *      time `guardedLookup` (no TOCTOU between the check and the connect).
+ *
+ * A `fetchImpl` is injectable for tests (the stub path skips the node-http machinery — moot for
+ * a fake — but STILL enforces origin + https).
+ */
+import http from "node:http";
+import https from "node:https";
+import { guardedLookup, isBlockedTarget } from "./net.js";
+/** Cap on a fetched body — feeds/sitemaps are text, but a hostile origin must not OOM us. */
+const MAX_BODY = 8 * 1024 * 1024; // 8 MiB
+/** Build the guarded fetcher bound to one origin. */
+export function makeGuardedFetcher(opts) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    const allowPrivate = opts.allowPrivate ?? false;
+    let originHost;
+    try {
+        originHost = new URL(opts.origin).host; // host = hostname[:port]
+    }
+    catch {
+        throw new Error(`crawl fetcher: invalid origin ${opts.origin}`);
+    }
+    return async (url, init) => {
+        let u;
+        try {
+            u = new URL(url);
+        }
+        catch {
+            throw new Error(`crawl fetcher: invalid url ${url}`);
+        }
+        // (1) verified-origin-only — the host must match the proven origin exactly.
+        if (u.host !== originHost) {
+            throw new Error(`crawl fetcher: off-origin host blocked (${u.host} ≠ ${originHost})`);
+        }
+        // https only, unless the dev escape hatch is on (local http fixtures).
+        if (u.protocol !== "https:" && !(allowPrivate && u.protocol === "http:")) {
+            throw new Error(`crawl fetcher: url must be https (${u.protocol})`);
+        }
+        const headers = {
+            "user-agent": "naulon-crawl/1 (+catalog-draft)",
+            accept: "application/json, application/rss+xml, application/atom+xml, application/xml, text/xml;q=0.9, */*;q=0.5",
+            ...init?.headers,
+        };
+        // Injected fetch (tests) — origin + https already enforced; TOCTOU is moot for a fake.
+        if (opts.fetchImpl) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await opts.fetchImpl(url, { method: "GET", headers, redirect: "manual", signal: controller.signal });
+                return wrapResponse(res.status, res.ok, await res.text().catch(() => ""));
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        // Real path — node http(s) with the connect-time guarded lookup (no rebind window).
+        const raw = await getViaNode(url, headers, timeoutMs, allowPrivate, u.protocol);
+        return wrapResponse(raw.status, raw.status >= 200 && raw.status < 300, raw.body);
+    };
+}
+/** A `FetchResult` over a buffered body. `json()` throws on non-JSON (the adapter narrows). */
+function wrapResponse(status, ok, body) {
+    return {
+        ok,
+        status,
+        async text() {
+            return body;
+        },
+        async json() {
+            return JSON.parse(body);
+        },
+    };
+}
+/** GET via node http(s) with the guarded lookup — the TOCTOU-safe real path. node never
+ *  auto-follows redirects, so a 3xx is returned (not chased to an off-origin location). */
+function getViaNode(urlStr, headers, timeoutMs, allowPrivate, protocol) {
+    return new Promise((resolve, reject) => {
+        const transport = protocol === "http:" ? http : https;
+        const req = transport.request(urlStr, { method: "GET", headers, lookup: guardedLookup(allowPrivate) }, (res) => {
+            // A private-IP literal in the URL is caught here too (lookup only runs for DNS names).
+            const ip = res.socket.remoteAddress;
+            if (ip && !allowPrivate && isBlockedTarget(ip)) {
+                res.destroy();
+                return reject(new Error(`crawl fetcher: connected IP is private/loopback (${ip})`));
+            }
+            let data = "";
+            res.setEncoding("utf8");
+            res.on("data", (c) => {
+                if (data.length < MAX_BODY)
+                    data += c;
+            });
+            res.on("end", () => resolve({ status: res.statusCode ?? 0, body: data.slice(0, MAX_BODY) }));
+        });
+        req.setTimeout(timeoutMs, () => req.destroy(new Error(`crawl fetcher: timeout after ${timeoutMs}ms`)));
+        req.on("error", reject);
+        req.end();
+    });
+}
+//# sourceMappingURL=fetcher.js.map

package/dist/crawl/fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.js","sourceRoot":"","sources":["../../src/crawl/fetcher.ts"],"names":[],"mappings":"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"}

package/dist/crawl/glob.d.ts

@@ -0,0 +1,19 @@
+/**
+ * crawl/glob.ts — include/exclude URL-path glob matching for article filtering.
+ *
+ * A sitemap lists every URL on a site, not just articles, so the sitemap adapter filters
+ * with these globs. Deterministic, no model. Supported syntax, deliberately small:
+ *   `*`  — any run of chars except `/`
+ *   `**` — any run of chars including `/`
+ *   `?`  — a single char except `/`
+ * A path passes when it matches at least one include glob (or include is empty → all pass)
+ * AND matches no exclude glob (exclude wins — it is the safety lever).
+ */
+/** True if `path` (a URL pathname) matches `glob`. */
+export declare function matchGlob(path: string, glob: string): boolean;
+/**
+ * Article gate: passes an include (empty include ⇒ everything is in) and survives every
+ * exclude. Exclude takes precedence — it is how an owner carves `/essays/drafts/**` out.
+ */
+export declare function passesGlobs(path: string, include: string[], exclude: string[]): boolean;
+//# sourceMappingURL=glob.d.ts.map

package/dist/crawl/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/crawl/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiCH,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAIvF"}

package/dist/crawl/glob.js

@@ -0,0 +1,59 @@
+/**
+ * crawl/glob.ts — include/exclude URL-path glob matching for article filtering.
+ *
+ * A sitemap lists every URL on a site, not just articles, so the sitemap adapter filters
+ * with these globs. Deterministic, no model. Supported syntax, deliberately small:
+ *   `*`  — any run of chars except `/`
+ *   `**` — any run of chars including `/`
+ *   `?`  — a single char except `/`
+ * A path passes when it matches at least one include glob (or include is empty → all pass)
+ * AND matches no exclude glob (exclude wins — it is the safety lever).
+ */
+/** Compile one glob to an anchored RegExp. Literals are escaped; only `*`/`?` are special. */
+function globToRe(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*"; // `**` → across segments
+                i++;
+            }
+            else {
+                re += "[^/]*"; // `*` → within a segment
+            }
+        }
+        else if (ch === "?") {
+            re += "[^/]";
+        }
+        else {
+            re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+const cache = new Map();
+function compiled(glob) {
+    let re = cache.get(glob);
+    if (!re) {
+        re = globToRe(glob);
+        cache.set(glob, re);
+    }
+    return re;
+}
+/** True if `path` (a URL pathname) matches `glob`. */
+export function matchGlob(path, glob) {
+    return compiled(glob).test(path);
+}
+/**
+ * Article gate: passes an include (empty include ⇒ everything is in) and survives every
+ * exclude. Exclude takes precedence — it is how an owner carves `/essays/drafts/**` out.
+ */
+export function passesGlobs(path, include, exclude) {
+    if (exclude.some((g) => matchGlob(path, g)))
+        return false;
+    if (include.length === 0)
+        return true;
+    return include.some((g) => matchGlob(path, g));
+}
+//# sourceMappingURL=glob.js.map

package/dist/crawl/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/crawl/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,8FAA8F;AAC9F,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACpB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACxB,EAAE,IAAI,IAAI,CAAC,CAAC,yBAAyB;gBACrC,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,EAAE,IAAI,OAAO,CAAC,CAAC,yBAAyB;YAC1C,CAAC;QACH,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACtB,EAAE,IAAI,MAAM,CAAC;QACf,CAAC;aAAM,CAAC;YACN,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;AACxC,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpB,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY;IAClD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,OAAiB,EAAE,OAAiB;IAC5E,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/crawl/net.d.ts

@@ -0,0 +1,12 @@
+import type { LookupFunction } from "node:net";
+/** True if `host` is a literal IP in a blocked range. A DNS name is NOT blocked here —
+ *  it has no literal to check; `guardedLookup` validates the resolved IP at connect time. */
+export declare function isBlockedTarget(host: string): boolean;
+/**
+ * A `lookup` implementation for `http(s).request` that rejects any resolved address in a
+ * blocked range. Passing this as the request's `lookup` closes the check/connect rebind
+ * window: the IP the socket connects to is the one that passed the guard. `allowPrivate`
+ * (a dev-only knob for local fixture origins) relaxes it.
+ */
+export declare function guardedLookup(allowPrivate: boolean): LookupFunction;
+//# sourceMappingURL=net.d.ts.map

package/dist/crawl/net.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../../src/crawl/net.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA2C/C;6FAC6F;AAC7F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKrD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,OAAO,GAAG,cAAc,CAenE"}

package/dist/crawl/net.js

@@ -0,0 +1,93 @@
+/**
+ * crawl/net.ts — the SSRF guard for the crawler's network seam.
+ *
+ * `naulon crawl` fetches whatever URL an adapter derives from a publisher's origin
+ * (feed paths, `/wp-json`, sitemap `<loc>`s). Without a guard that is a pointable-at-
+ * anything footgun: a hostile or misconfigured feed could name `http://169.254.169.254`
+ * (cloud metadata) or `http://10.0.0.5` (an internal service) and the crawler would
+ * happily fetch it. So every connection is CIDR-checked against the private/loopback/
+ * link-local ranges, and — because a plain check-then-connect leaves a DNS-rebind window
+ * — the socket connects through `guardedLookup`, which validates the ACTUAL resolved IP.
+ *
+ * This is a standalone port of the cloud webhook sender's SSRF machinery, with no cloud
+ * dependencies, so the open-source gate carries the same threat model as the hosted one.
+ */
+import { lookup as dnsLookupCb } from "node:dns";
+/** Parse a dotted-quad IPv4 literal to its 32-bit int, or null if it isn't one. */
+function ipToInt(ip) {
+    const m = ip.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m)
+        return null;
+    const octets = m.slice(1).map(Number);
+    if (octets.some((o) => o > 255))
+        return null;
+    return ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+}
+// [networkInt, maskBits] — the private/loopback/link-local v4 ranges.
+const PRIVATE_V4 = [
+    [ipToInt("127.0.0.0"), 8], // loopback
+    [ipToInt("10.0.0.0"), 8], // private
+    [ipToInt("172.16.0.0"), 12], // private
+    [ipToInt("192.168.0.0"), 16], // private
+    [ipToInt("169.254.0.0"), 16], // link-local (incl. 169.254.169.254 cloud metadata)
+    [ipToInt("0.0.0.0"), 8], // "this" network
+    [ipToInt("100.64.0.0"), 10], // CGNAT
+];
+function isPrivateV4(ipInt) {
+    return PRIVATE_V4.some(([net, bits]) => {
+        const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+        return (ipInt & mask) === (net & mask);
+    });
+}
+function isBlockedV6(ip) {
+    const h = ip.toLowerCase();
+    if (h === "::1" || h === "::")
+        return true; // loopback / unspecified
+    if (h.startsWith("fe80"))
+        return true; // link-local
+    if (h.startsWith("fc") || h.startsWith("fd"))
+        return true; // unique-local fc00::/7
+    // IPv4-mapped (::ffff:a.b.c.d) — unwrap and check as v4.
+    const mapped = h.match(/::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (mapped) {
+        const v4 = ipToInt(mapped[1]);
+        return v4 !== null && isPrivateV4(v4);
+    }
+    return false;
+}
+/** True if `host` is a literal IP in a blocked range. A DNS name is NOT blocked here —
+ *  it has no literal to check; `guardedLookup` validates the resolved IP at connect time. */
+export function isBlockedTarget(host) {
+    const v4 = ipToInt(host);
+    if (v4 !== null)
+        return isPrivateV4(v4);
+    if (host.includes(":"))
+        return isBlockedV6(host);
+    return false;
+}
+/**
+ * A `lookup` implementation for `http(s).request` that rejects any resolved address in a
+ * blocked range. Passing this as the request's `lookup` closes the check/connect rebind
+ * window: the IP the socket connects to is the one that passed the guard. `allowPrivate`
+ * (a dev-only knob for local fixture origins) relaxes it.
+ */
+export function guardedLookup(allowPrivate) {
+    return (hostname, options, callback) => {
+        dnsLookupCb(hostname, { all: true, family: options.family ?? 0 }, (err, addresses) => {
+            if (err)
+                return callback(err, "", 0);
+            for (const a of addresses) {
+                if (!allowPrivate && isBlockedTarget(a.address)) {
+                    return callback(new Error(`blocked target (private/loopback): ${a.address}`), "", 0);
+                }
+            }
+            if (options.all)
+                return callback(null, addresses);
+            const first = addresses[0];
+            if (!first)
+                return callback(new Error("dns resolution returned no address"), "", 0);
+            callback(null, first.address, first.family);
+        });
+    };
+}
+//# sourceMappingURL=net.js.map

package/dist/crawl/net.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.js","sourceRoot":"","sources":["../../src/crawl/net.ts"],"names":[],"mappings":"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"}

package/dist/crawl/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * crawl/registry.ts — the adapter registry + auto-detect.
+ *
+ * `naulon crawl` doesn't make the operator name their platform. It probes every on-origin,
+ * no-secret adapter and picks the richest one that detects — WordPress (real author objects)
+ * over RSS (free-text authors) over sitemap (URLs only). Ties break by `rank`, highest wins.
+ * The two feed fallbacks (rss/sitemap) mean nearly any site yields at least a slug catalog.
+ */
+import type { AdapterContext, SourceAdapter } from "./types.ts";
+/** All public on-origin adapters, richest first. */
+export declare const ADAPTERS: readonly SourceAdapter[];
+/** The adapter to force by id, or undefined for auto-detect. */
+export declare function adapterById(id: string): SourceAdapter | undefined;
+/** Probe origin with every adapter (highest rank first) and return the first that detects,
+ *  or null when none do. Each `detect` uses only the guarded fetch and never throws on "no". */
+export declare function selectAdapter(ctx: AdapterContext): Promise<SourceAdapter | null>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/crawl/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/crawl/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhE,oDAAoD;AACpD,eAAO,MAAM,QAAQ,EAAE,SAAS,aAAa,EAAmD,CAAC;AAEjG,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEjE;AAED;gGACgG;AAChG,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAKtF"}

package/dist/crawl/registry.js

@@ -0,0 +1,19 @@
+import { rssAdapter } from "./adapters/rss.js";
+import { sitemapAdapter } from "./adapters/sitemap.js";
+import { wordpressAdapter } from "./adapters/wordpress.js";
+/** All public on-origin adapters, richest first. */
+export const ADAPTERS = [wordpressAdapter, rssAdapter, sitemapAdapter];
+/** The adapter to force by id, or undefined for auto-detect. */
+export function adapterById(id) {
+    return ADAPTERS.find((a) => a.id === id);
+}
+/** Probe origin with every adapter (highest rank first) and return the first that detects,
+ *  or null when none do. Each `detect` uses only the guarded fetch and never throws on "no". */
+export async function selectAdapter(ctx) {
+    for (const adapter of [...ADAPTERS].sort((a, b) => b.rank - a.rank)) {
+        if (await adapter.detect(ctx))
+            return adapter;
+    }
+    return null;
+}
+//# sourceMappingURL=registry.js.map

package/dist/crawl/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/crawl/registry.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,oDAAoD;AACpD,MAAM,CAAC,MAAM,QAAQ,GAA6B,CAAC,gBAAgB,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;AAEjG,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED;gGACgG;AAChG,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAmB;IACrD,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACpE,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,OAAO,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/crawl/slug.d.ts

@@ -0,0 +1,15 @@
+/**
+ * crawl/slug.ts — credits-key slug derivation, mirroring the gate exactly.
+ *
+ * The crawler writes `credits.json[slug]`; the gate looks that exact key up via its own
+ * `slugFromPath`: the first path segment AFTER a configured article prefix,
+ * `^/(?:<prefixes>)/([^/?#]+)`. A slug derived any other way is an article the gate can
+ * never find → it would never toll. So this is a faithful re-impl of that one function.
+ */
+/**
+ * Article slug from a URL, using the publisher's prefixes. Returns the decoded slug, or
+ * `null` when the path is not a gateable article (no prefix matches, or it is a gate
+ * control route, or the URL is malformed). Matches the gate exactly.
+ */
+export declare function deriveSlug(url: string, prefixes: string[]): string | null;
+//# sourceMappingURL=slug.d.ts.map

package/dist/crawl/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../../src/crawl/slug.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAkBzE"}

package/dist/crawl/slug.js

@@ -0,0 +1,42 @@
+/**
+ * crawl/slug.ts — credits-key slug derivation, mirroring the gate exactly.
+ *
+ * The crawler writes `credits.json[slug]`; the gate looks that exact key up via its own
+ * `slugFromPath`: the first path segment AFTER a configured article prefix,
+ * `^/(?:<prefixes>)/([^/?#]+)`. A slug derived any other way is an article the gate can
+ * never find → it would never toll. So this is a faithful re-impl of that one function.
+ */
+/** Escape a string for use as a literal inside a RegExp. */
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Article slug from a URL, using the publisher's prefixes. Returns the decoded slug, or
+ * `null` when the path is not a gateable article (no prefix matches, or it is a gate
+ * control route, or the URL is malformed). Matches the gate exactly.
+ */
+export function deriveSlug(url, prefixes) {
+    let path;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        return null;
+    }
+    // Never treat the gate's own control routes as articles, whatever the prefixes are.
+    if (path.startsWith("/.well-known/") || path.startsWith("/licenses/"))
+        return null;
+    const clean = prefixes.filter(Boolean);
+    if (clean.length === 0)
+        return null;
+    const m = path.match(new RegExp(`^/(?:${clean.map(escapeRe).join("|")})/([^/?#]+)`));
+    if (!m)
+        return null;
+    try {
+        return decodeURIComponent(m[1]);
+    }
+    catch {
+        return m[1];
+    }
+}
+//# sourceMappingURL=slug.js.map

package/dist/crawl/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../../src/crawl/slug.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4DAA4D;AAC5D,SAAS,QAAQ,CAAC,CAAS;IACzB,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,QAAkB;IACxD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,oFAAoF;IACpF,IAAI,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IACnF,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IACrF,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC,CAAC,CAAE,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/crawl/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * crawl/types.ts — the ports for the open-source publisher crawler.
+ *
+ * `naulon crawl` is a ONE-SHOT drafting aid: it reads a publisher's own origin
+ * (no API key) and drafts a `credits.json` so a self-hoster doesn't hand-author
+ * one article at a time. It is deliberately the *primitive* form of discovery —
+ * the hosted product's continuous, enriched, reviewed, multi-tenant pipeline is a
+ * separate thing and stays there. This file is the seam; concrete adapters live
+ * beside it and reach the network ONLY through the guarded `Fetcher`.
+ *
+ * The load-bearing invariant, identical to the hosted crawler: the crawler auto-
+ * configs the CATALOG plane only (slugs, titles, author strings). MONEY IS NEVER
+ * INFERRED — a `DiscoveredArticle` carries the feed's author STRING, never a wallet.
+ * The human-supplied `authorWalletMap` / `defaultWallet` map that string to a payTo;
+ * an unmapped author is reported to the operator, never written to a guessed address.
+ *
+ * On-origin, no-secret adapters ONLY (`rss`, `sitemap`, `wordpress`). Keyed adapters
+ * (Ghost/Blogger), LLM enrichment, and a review queue are the operated pipeline — not here.
+ */
+/** The minimal response an adapter consumes — a subset of the DOM `Response`, so the real
+ *  node-http path and a plain test fake both satisfy it. */
+export interface FetchResult {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}
+/** The ONLY way an adapter reaches the network. The crawl orchestrator injects an impl that
+ *  enforces verified-origin-only + SSRF CIDR block + anti-DNS-rebind (`makeGuardedFetcher`).
+ *  Adapters never import `fetch`/`node:http` — that keeps the SSRF guard un-bypassable and the
+ *  whole module network-testable with a plain fake. */
+export interface Fetcher {
+    (url: string, init?: {
+        headers?: Record<string, string>;
+    }): Promise<FetchResult>;
+}
+/** One author exactly as the feed/API states it. `name` is the raw string used as the
+ *  `authorWalletMap` key — catalog data, NEVER a wallet (money is never inferred). */
+export interface DiscoveredAuthor {
+    name: string;
+    /** Platform-native id when exposed (WP author id/slug) — aids stable mapping. */
+    externalId?: string;
+}
+/** One article an adapter found on the verified origin. Catalog plane only — no money here. */
+export interface DiscoveredArticle {
+    /** The gate's credits key — the URL path slug, derived per `articlePrefixes`. */
+    slug: string;
+    /** Canonical article URL on the verified origin. */
+    url: string;
+    title: string;
+    /** Feed-stated authors (may be empty — then resolution falls to `defaultWallet`). */
+    authors: DiscoveredAuthor[];
+    /** ISO-8601 publish timestamp the source states, when present. */
+    publishedAt?: string;
+}
+/** The human-authored crawl policy the adapters read. A subset of the hosted `CrawlConfig`:
+ *  no API keys (keyed adapters are hosted-only), no continuous-sweep knobs. */
+export interface CrawlConfig {
+    /** Explicit feed/sitemap URL, overriding the conventional-path probe. */
+    feedUrl?: string;
+    /** URL-path globs deciding which discovered URLs are articles (sitemap adapter). */
+    includeGlobs: string[];
+    excludeGlobs: string[];
+    /** author STRING → payTo, human-supplied. Never inferred. */
+    authorWalletMap: Record<string, string>;
+    /** Fallback payTo when an author is unmapped or the source stated none. Optional —
+     *  absent means an unmapped article is reported, not written. */
+    defaultWallet?: string;
+}
+/** Everything an adapter may touch: the verified origin, the human policy, the guarded fetch.
+ *  An adapter that reaches outside `ctx.fetch` breaks the SSRF guarantee. */
+export interface AdapterContext {
+    /** The verified origin `scheme://host[:port]` — the ONLY host `ctx.fetch` connects to. */
+    origin: string;
+    /** Gateable path prefixes (no leading slash). A slug MUST be derived from these (via
+     *  `deriveSlug`) so it matches the gate's credits key exactly. */
+    articlePrefixes: string[];
+    config: CrawlConfig;
+    fetch: Fetcher;
+}
+/** The public adapter ids — on-origin, no-secret sources only. */
+export type SourceAdapterId = "rss" | "sitemap" | "wordpress";
+/** A source connector: one file per platform. The registry picks the richest adapter whose
+ *  `detect` returns true; `rss`/`sitemap` are the always-available fallbacks (lowest rank). */
+export interface SourceAdapter {
+    readonly id: SourceAdapterId;
+    /** Richness rank — the registry prefers the highest detected. Real author objects (WordPress)
+     *  outrank feed parsing (rss), which outranks pure URL discovery (sitemap). */
+    readonly rank: number;
+    /** Cheap probe: could this adapter discover THIS origin? MUST use only `ctx.fetch`. Never
+     *  throws on a normal "no" — returns false. */
+    detect(ctx: AdapterContext): Promise<boolean>;
+    /** Discover the catalog. MUST hit only the verified origin via `ctx.fetch`. */
+    discover(ctx: AdapterContext): Promise<DiscoveredArticle[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/crawl/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/crawl/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;4DAC4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;uDAGuD;AACvD,MAAM,WAAW,OAAO;IACtB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAClF;AAID;sFACsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+FAA+F;AAC/F,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;+EAC+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC;qEACiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;6EAC6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;IACf;sEACkE;IAClE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,CAAC;AAE9D;+FAC+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;IAC7B;mFAC+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;mDAC+C;IAC/C,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC7D"}

package/dist/crawl/types.js

@@ -0,0 +1,21 @@
+/**
+ * crawl/types.ts — the ports for the open-source publisher crawler.
+ *
+ * `naulon crawl` is a ONE-SHOT drafting aid: it reads a publisher's own origin
+ * (no API key) and drafts a `credits.json` so a self-hoster doesn't hand-author
+ * one article at a time. It is deliberately the *primitive* form of discovery —
+ * the hosted product's continuous, enriched, reviewed, multi-tenant pipeline is a
+ * separate thing and stays there. This file is the seam; concrete adapters live
+ * beside it and reach the network ONLY through the guarded `Fetcher`.
+ *
+ * The load-bearing invariant, identical to the hosted crawler: the crawler auto-
+ * configs the CATALOG plane only (slugs, titles, author strings). MONEY IS NEVER
+ * INFERRED — a `DiscoveredArticle` carries the feed's author STRING, never a wallet.
+ * The human-supplied `authorWalletMap` / `defaultWallet` map that string to a payTo;
+ * an unmapped author is reported to the operator, never written to a guessed address.
+ *
+ * On-origin, no-secret adapters ONLY (`rss`, `sitemap`, `wordpress`). Keyed adapters
+ * (Ghost/Blogger), LLM enrichment, and a review queue are the operated pipeline — not here.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/crawl/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/crawl/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/crawl/xml.d.ts

@@ -0,0 +1,9 @@
+/** Parse an XML document. Throws on malformed input (an adapter treats a throw as "no feed"). */
+export declare function parseXml(xml: string): Record<string, unknown>;
+/** fast-xml-parser yields a single object for one child and an array for many. Normalize to an
+ *  array so adapters iterate uniformly (`<item>`×1 and ×N look the same). */
+export declare function toArray<T>(x: T | T[] | undefined | null): T[];
+/** Read a node's text whether it is a bare string, a `{ "#text" }` object (mixed content), or a
+ *  CDATA `{ __cdata }`. Returns "" for anything else. */
+export declare function textOf(node: unknown): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/crawl/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../src/crawl/xml.ts"],"names":[],"mappings":"AAoBA,iGAAiG;AACjG,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE7D;AAED;6EAC6E;AAC7E,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,EAAE,CAG7D;AAED;yDACyD;AACzD,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAQ5C"}

package/dist/crawl/xml.js

@@ -0,0 +1,44 @@
+/**
+ * crawl/xml.ts — the one XML parse wrapper (fast-xml-parser).
+ *
+ * RSS/Atom/sitemap are all XML; this is the only place the parser is configured, so every
+ * adapter reads feeds the same way. Text values stay strings (a slug like `2026` must not
+ * become the number 2026), attributes surface under `@_` so `<link href=…>` (Atom) is
+ * reachable, and namespaced tags (`dc:creator`) keep their prefix.
+ */
+import { XMLParser } from "fast-xml-parser";
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    parseTagValue: false, // keep `<guid>2026</guid>` a string, not the number 2026
+    parseAttributeValue: false,
+    trimValues: true,
+    cdataPropName: "__cdata", // CDATA (common in RSS) folds into the tag's text value
+    processEntities: true,
+});
+/** Parse an XML document. Throws on malformed input (an adapter treats a throw as "no feed"). */
+export function parseXml(xml) {
+    return parser.parse(xml);
+}
+/** fast-xml-parser yields a single object for one child and an array for many. Normalize to an
+ *  array so adapters iterate uniformly (`<item>`×1 and ×N look the same). */
+export function toArray(x) {
+    if (x === undefined || x === null)
+        return [];
+    return Array.isArray(x) ? x : [x];
+}
+/** Read a node's text whether it is a bare string, a `{ "#text" }` object (mixed content), or a
+ *  CDATA `{ __cdata }`. Returns "" for anything else. */
+export function textOf(node) {
+    if (typeof node === "string")
+        return node;
+    if (node && typeof node === "object") {
+        const o = node;
+        if (typeof o["__cdata"] === "string")
+            return o["__cdata"];
+        if (typeof o["#text"] === "string")
+            return o["#text"];
+    }
+    return "";
+}
+//# sourceMappingURL=xml.js.map

package/dist/crawl/xml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.js","sourceRoot":"","sources":["../../src/crawl/xml.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,gBAAgB,EAAE,KAAK;IACvB,mBAAmB,EAAE,IAAI;IACzB,aAAa,EAAE,KAAK,EAAE,yDAAyD;IAC/E,mBAAmB,EAAE,KAAK;IAC1B,UAAU,EAAE,IAAI;IAChB,aAAa,EAAE,SAAS,EAAE,wDAAwD;IAClF,eAAe,EAAE,IAAI;CACtB,CAAC,CAAC;AAEH,iGAAiG;AACjG,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;AACtD,CAAC;AAED;6EAC6E;AAC7E,MAAM,UAAU,OAAO,CAAI,CAA6B;IACtD,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;yDACyD;AACzD,MAAM,UAAU,MAAM,CAAC,IAAa;IAClC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC;QAC1D,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}