@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/converters/ncm/fix/styleClosers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bare `%%` style closers → `/%` (#1346).
+ *
+ * JSPWiki closes a `%%` style block with `/%` or with a bare `%%`. NCM writes
+ * only `/%` (operator decision, 2026-09-12); the renderer still tolerates a
+ * bare `%%`, so this changes the text, not what the page shows. A `%%` is a
+ * closer under Apache's rule (`JSPWikiMarkupParser.handleDiv`): not followed
+ * by a letter or `(`, with a block open. That covers a line that is only
+ * `%%` and the inline form `%%sub text%%`.
+ *
+ * Openers are counted to know whether a block is open: `%%` followed by a
+ * letter or `(` opens one, `/%` or a bare `%%` closes the innermost. An
+ * inline opener (text after it on the line) that is never closed ends with
+ * its paragraph, as in Apache, so a blank line drops the inline ones still
+ * open; a block-form opener (alone on its line) stays open until closed.
+ *
+ * Deliberately narrow:
+ *   - a `%%` with no block open is left alone, for review; Apache drops it;
+ *   - never a line the renderer treats as code or HTML, and never inside an
+ *     inline code span.
+ *
+ * @module converters/ncm/fix/styleClosers
+ */
+import type { FixStep } from './types.js';
+export declare const styleClosers: FixStep;

package/lib/src/converters/ncm/fix/tightenLists.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Remove empty lines between list items, so the list renders "tight" (#1271).
+ *
+ * In CommonMark one empty line anywhere between the items of a list makes the
+ * whole list "loose": every item's text is wrapped in a paragraph and the list
+ * is spread out. Authors often leave an empty line only to group items in the
+ * source — "Antibiotics:" and its sub-items, an empty line, "Antitoxin
+ * therapy:" — and get a spaced-out list they did not ask for. An empty line
+ * between two items of one list never ends the list, so removing it changes
+ * the spacing and nothing else.
+ *
+ * Works on each top-level list together with the lists nested in it, and
+ * deliberately narrow:
+ *   - only an empty line whose next non-empty line starts an item of the same
+ *     top-level list;
+ *   - the list is skipped when any item has a real second block after an
+ *     empty line (a second paragraph, a code block): there the empty line is
+ *     meaning, and the list stays loose whatever else is removed;
+ *   - the list is also skipped when an item's text runs onto a second line.
+ *     showdown turns that line into a `<br>` only in a loose list and joins it
+ *     into one line in a tight one, so tightening would lose the break until
+ *     the converter swap (#1273). markdown-it keeps it either way.
+ *
+ * The result is parsed again; if the list items are not exactly the ones
+ * before, nothing is changed.
+ *
+ * @module converters/ncm/fix/tightenLists
+ */
+import type { FixStep } from './types.js';
+export declare const tightenLists: FixStep;

package/lib/src/converters/ncm/fix/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Types for the Markdown fix module (#1332).
+ *
+ * @module converters/ncm/fix/types
+ */
+/** What one step changed. Empty `lines` means nothing changed. */
+export interface FixStepResult {
+    content: string;
+    /** 1-based line numbers, in the step's input, that were rewritten or removed. */
+    lines: number[];
+}
+/**
+ * One conversion step: small, pure and idempotent — running it on its own
+ * output changes nothing.
+ */
+export interface FixStep {
+    /** Stable id, used in reports and to pick steps by name. */
+    id: string;
+    /** Plain-language summary for the author, e.g. "JSPWiki ** bullets became nested - bullets". */
+    summary: string;
+    apply(body: string): FixStepResult;
+}
+/** One step's entry in a {@link FixResult}. */
+export interface FixChange {
+    step: string;
+    summary: string;
+    lines: number[];
+}
+export interface FixResult {
+    content: string;
+    /** Only the steps that changed something, in the order they ran. */
+    changes: FixChange[];
+}

package/lib/src/converters/ncm/footnotes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * NCM footnote capture (#1125) — the pure half.
+ *
+ * GFM and NCM share the `[^id]` / `[^id]: text` syntax, and the render
+ * pipeline already links refs inline. What the sidecar footnote list
+ * (FootnoteManager + FootnotesPlugin, the one with the CRUD UI) needs is the
+ * DEFINITIONS as structured records. This module extracts them and rewrites
+ * the body; it is deliberately side-effect free so §3.1 determinism holds —
+ * the sidecar write belongs to the caller (the convert route), exactly as
+ * image localization splits pure rewrite from attachment persistence.
+ *
+ * Ids are preserved verbatim — the body's `[^note-1]` refs must keep
+ * resolving to `#footnote-note-1` in the rendered list, so renumbering would
+ * break every ref it touched.
+ */
+export interface ExtractedFootnoteDef {
+    id: string;
+    display: string;
+    url: string;
+    note: string;
+}
+export interface FootnoteExtraction {
+    defs: ExtractedFootnoteDef[];
+    /** Body with the definition lines removed. Byte-identical input when there are none. */
+    content: string;
+}
+/**
+ * Pull every footnote definition (single-line and GFM multi-paragraph) out of
+ * the body. Continuation lines — indented by 4+ spaces or a tab, with blank
+ * lines allowed between paragraphs of the same definition — join the note
+ * with newlines.
+ */
+export declare function extractFootnoteDefs(content: string): FootnoteExtraction;
+/**
+ * Append a footnote-list section when the page has none, so transferred
+ * definitions stay visible. Idempotent: an existing invocation — with or
+ * without parameters — is left untouched.
+ */
+export declare function ensureFootnotesPlugin(content: string): string;

package/lib/src/converters/ncm/images.d.ts

@@ -0,0 +1,49 @@
+/**
+ * NCM embedded-image → attachment rule (#728 spec §2.2, Phase 2 Slice 4)
+ *
+ * `normalizeToNcm` stays synchronous and dependency-free; image localization
+ * is inherently async (outbound fetch) and engine-coupled (AttachmentManager,
+ * a target page), so it is a **separate post-pass** with **injected I/O**.
+ * That keeps S1/S2 pure and this slice unit-testable with fakes; S5 wires the
+ * real fetch (`ngdpbase.fetch-timeout-ms`) + `AttachmentManager.uploadAttachment`.
+ *
+ * For every `![alt](src)` whose `src` is a remote `http(s)` URL or a `data:`
+ * URI:
+ *  - host on the ad/tracker deny-list  → drop  (`img-rejected: adhost`)
+ *  - fetch fails / times out           → drop  (`img-rejected: fetch`)
+ *  - magic-byte sniff not in the strict raster allowlist (jpeg/png/gif/webp;
+ *    **SVG/RAW excluded — never trust the extension or `Content-Type`**)
+ *                                      → drop  (`img-rejected: type`)
+ *  - decoded bytes exceed the size cap → drop  (`img-rejected: size`)
+ *  - otherwise → store + rewrite to the local ref (`img-attached`)
+ * Every drop also leaves a deterministic §3.3 placeholder. Local/relative
+ * srcs are left untouched, so the pass is idempotent.
+ *
+ * @module converters/ncm/images
+ */
+import { NcmWarning } from './types.js';
+/** Config for the image rule (size cap reuses ngdpbase.attachment.maxsize). */
+export interface NcmImageConfig {
+    maxBytes: number;
+    adDenyList: string[];
+    fetchTimeoutMs: number;
+}
+/** Injected I/O so the rule is pure-testable; S5 supplies the real impls. */
+export interface NcmImageDeps {
+    /** Fetch raw bytes with the given timeout. Reject/throw or return error. */
+    fetchBytes(url: string, timeoutMs: number): Promise<Buffer>;
+    /** Persist the image; return the local reference to put in `![alt](ref)`. */
+    storeAttachment(input: {
+        bytes: Buffer;
+        mime: string;
+        sourceUrl: string;
+    }): Promise<string>;
+}
+/**
+ * Localize embedded remote/data images in an NCM document.
+ * Pure aside from the injected `deps`; idempotent.
+ */
+export declare function localizeNcmImages(ncm: string, cfg: NcmImageConfig, deps: NcmImageDeps): Promise<{
+    content: string;
+    warnings: NcmWarning[];
+}>;

package/lib/src/converters/ncm/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ngdp Compatible Markdown (NCM) — module barrel (#728)
+ *
+ * Spec: docs/NGDP-Compatible-Markdown.md
+ * Phase 2: S1 core types + idempotent normalizer + placeholder;
+ * S2 HTML/JSPWiki→NCM conversion + §2.4 link normalization.
+ *
+ * @module converters/ncm
+ */
+export * from './types.js';
+export { formatDroppedPlaceholder, isDroppedPlaceholderLine } from './placeholder.js';
+export { normalizeLinks } from './links.js';
+export { upconvertPipeTables, DEFAULT_TABLE_CLASSES } from './tables.js';
+export { localizeNcmImages } from './images.js';
+export type { NcmImageConfig, NcmImageDeps } from './images.js';
+export { normalizeToNcm } from './normalize.js';
+export { ncmToConversionResult } from './bridge.js';
+export { normalizeExistingPageToNcm } from './existing.js';
+export { extractFootnoteDefs, ensureFootnotesPlugin } from './footnotes.js';
+export type { ExtractedFootnoteDef, FootnoteExtraction } from './footnotes.js';

package/lib/src/converters/ncm/links.d.ts

@@ -0,0 +1,21 @@
+/**
+ * NCM link normalization (#728 spec §2.4, Phase 2 Slice 2)
+ *
+ * The upstream converters (`HtmlConverter` via turndown, `JSPWikiConverter`)
+ * emit CommonMark `[text](url)` for external links. NCM does **not** use
+ * CommonMark link syntax — it uses the `LinkParserHandler` JSPWiki forms:
+ *
+ * - external (absolute http/https) → `[text|url|target="_blank"]`
+ *   (the renderer adds `rel="noopener noreferrer"`)
+ * - internal / relative          → `[text|target]`
+ * - other schemes (mailto:, ftp:) → left as-is (conservative; not NCM-ified)
+ *
+ * Idempotent by construction: it only matches CommonMark `](…)` which it
+ * eliminates, so a second pass is a no-op. Images (`![alt](src)`) are left
+ * untouched — image→attachment is the §2.2 rule (#728 S4), not a link concern.
+ *
+ * @module converters/ncm/links
+ */
+import { NcmWarning } from './types.js';
+/** Rewrite CommonMark links in `md` to NCM forms, recording externalizations. */
+export declare function normalizeLinks(md: string, warnings: NcmWarning[]): string;

package/lib/src/converters/ncm/normalize.d.ts

@@ -0,0 +1,39 @@
+/**
+ * NCM normalizer — Phase 2 Slice 1 (#728)
+ *
+ * - `ncm` / `markdown` (S1): parse frontmatter, stamp `ncmVersion` if absent
+ *   (preserve an existing value — migration is a separate explicit step,
+ *   never silent rewrite-on-read), re-emit with deterministic (sorted)
+ *   frontmatter key order; body passed through unchanged. Placeholder lines
+ *   therefore round-trip byte-identical.
+ * - `html` / `jspwiki` (S2): delegate to the existing `HtmlConverter` /
+ *   `JSPWikiConverter` registry (the spec says NCM *extends* the registry,
+ *   not reinvents it), map their `string[]` warnings to structured
+ *   `NcmWarning`, normalize CommonMark links to NCM §2.4 forms, then run the
+ *   assembled doc through the S1 fixed point so determinism/version/order
+ *   live in exactly one place.
+ *
+ * The guarantee S1 establishes (painful to retrofit):
+ * `normalize(normalize(x)) === normalize(x)` byte-identical, and an existing
+ * `ncmVersion` is never silently changed.
+ *
+ * @module converters/ncm/normalize
+ */
+import { NcmResult, NcmSourceFormat } from './types.js';
+/** Options controlling normalization behaviour. */
+export interface NcmNormalizeOptions {
+    /**
+     * Style classes to wrap up-converted tables in (§2.1, NCM v2). Defaults to
+     * {@link DEFAULT_TABLE_CLASSES}. ImportManager resolves this from
+     * `ngdpbase.markdown.ncm.table.default-classes`. Pass `[]` to up-convert the
+     * table syntax without a style wrapper.
+     */
+    tableClasses?: string[];
+}
+/**
+ * Normalize input to NCM. See module docs for the Slice-1 scope.
+ *
+ * @param input        Raw source content (may include YAML frontmatter)
+ * @param sourceFormat One of {@link NcmSourceFormat}
+ */
+export declare function normalizeToNcm(input: string, sourceFormat: NcmSourceFormat, options?: NcmNormalizeOptions): NcmResult;

package/lib/src/converters/ncm/placeholder.d.ts

@@ -0,0 +1,25 @@
+/**
+ * NCM dropped-content placeholder (#728 spec §3.3, Phase 2 Slice 1)
+ *
+ * When the normalizer drops content (stripped HTML, rejected image, …) it
+ * leaves a deterministic, NCM-valid blockquote so a reader later sees *that*
+ * and *why* something was removed — never a silent gap. This is the durable
+ * signal where there is no preview (bulk import, #685, MCP).
+ *
+ * HARD RULE (idempotence, ties to spec §3.1): the normalizer must recognise
+ * its own placeholder and pass it through byte-identical on re-run, so
+ * convert-existing-page / #685 re-runs never re-wrap or duplicate it.
+ *
+ * Single-line blockquote on purpose (not an HTML comment — that would be
+ * stripped and invisible; not a plugin — that would add a render path).
+ *
+ * @module converters/ncm/placeholder
+ */
+/**
+ * Build the placeholder line for dropped content.
+ * `tag`/`reason` are flattened to a single line so the placeholder stays one
+ * deterministic line that round-trips.
+ */
+export declare function formatDroppedPlaceholder(tag: string, reason: string): string;
+/** True if `line` is an NCM dropped-content placeholder (trailing space tolerant). */
+export declare function isDroppedPlaceholderLine(line: string): boolean;

package/lib/src/converters/ncm/tables.d.ts

@@ -0,0 +1,36 @@
+/**
+ * NCM table up-conversion — GFM pipe tables → JSPWiki styled tables (#728, NCM v2)
+ *
+ * NCM v1 left tables as passthrough (both GFM pipe tables and JSPWiki `||`/`|`
+ * tables rendered independently). NCM v2 makes the rich JSPWiki form the single
+ * canonical table: every GFM pipe table found in a normalized body is rewritten
+ * to a `||header||` / `|cell|` table wrapped in the configured style blocks
+ * (default `%%table-fit %%table-bordered %%table-striped %%table-hover
+ * %%sortable`). This gives imported markdown tables fit/border/zebra/hover and
+ * client-side sorting for free, via the existing `JSPWikiPreprocessor`.
+ *
+ * Two invariants the rest of NCM relies on:
+ * - **Idempotent.** The output has no GFM separator row (`|---|`), and detection
+ *   requires a separator row, so a second pass converts nothing — the body is a
+ *   fixed point. JSPWiki tables already in the body are likewise never matched.
+ * - **Delimiter shape.** `JSPWikiPreprocessor.parseTableRow` slices off the
+ *   first and last cell (the empties around the outer delimiters), so rows MUST
+ *   lead AND trail with their delimiter: `||a||b||c||` for headers, `|a|b|c|`
+ *   for data. Omitting the trailing delimiter silently drops the last column.
+ *
+ * @module converters/ncm/tables
+ */
+/** The five style classes NCM wraps an up-converted table in by default. */
+export declare const DEFAULT_TABLE_CLASSES: string[];
+/**
+ * Up-convert every GFM pipe table in a Markdown body to the JSPWiki styled form.
+ *
+ * @param body    Markdown body (no frontmatter)
+ * @param classes Style classes to wrap each table in (default {@link DEFAULT_TABLE_CLASSES}).
+ *                Pass `[]` to convert the table syntax without any style wrapper.
+ * @returns The rewritten body and the count of tables converted.
+ */
+export declare function upconvertPipeTables(body: string, classes?: string[]): {
+    body: string;
+    converted: number;
+};

package/lib/src/converters/ncm/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ngdp Compatible Markdown (NCM) — core types (#728, Phase 2 Slice 1)
+ *
+ * Spec: docs/NGDP-Compatible-Markdown.md
+ *
+ * These are NCM-local types. The shared `ConversionResult.warnings`
+ * (string[]) used by ImportManager/ValidationManager/the converters is NOT
+ * changed here — migrating that to structured warnings is a separate, broad
+ * slice (#728 S3). NCM functions return their own {@link NcmResult} so this
+ * slice has zero blast radius on existing consumers.
+ *
+ * @module converters/ncm/types
+ */
+/** Current NCM profile version. Bumped only when the profile changes; pages
+ *  are re-normalized to a new version ONLY via an explicit migration, never
+ *  silently on read (spec §3, Q4).
+ *
+ *  v2 (#728 table profile): GFM pipe tables are up-converted to the JSPWiki
+ *  styled form (`%%table-*` wrapped `||header||`/`|cell|`) — v1 left tables as
+ *  passthrough. See docs/NGDP-Compatible-Markdown.md §2.1. */
+export declare const NCM_VERSION = 2;
+/** Source content formats the normalizer accepts. */
+export type NcmSourceFormat = 'ncm' | 'markdown' | 'html' | 'jspwiki';
+/**
+ * Stable warning/error code. Free text alone is not aggregatable — the code
+ * is the prerequisite for the conversion-metrics work (#738) and tightens
+ * determinism (enum > prose). Detail strings carry the specifics.
+ */
+export type NcmWarningKind = 'html-dropped' | 'img-attached' | 'img-rejected' | 'link-externalized' | 'placeholder-inserted' | 'converter-note' | 'source-unsupported';
+export interface NcmWarning {
+    kind: NcmWarningKind;
+    detail: string;
+}
+/** Result of normalizing arbitrary input to NCM. */
+export interface NcmResult {
+    /** Full NCM document including frontmatter. */
+    content: string;
+    /** Structured warnings (see {@link NcmWarningKind}). */
+    warnings: NcmWarning[];
+    /** The `ncmVersion` stamped on / read from the document. */
+    ncmVersion: number;
+}

package/lib/src/http/egressPolicy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration to policy (#1133).
+ *
+ * The operator sets two CIDR lists; this turns them into the `EgressPolicy`
+ * the guard enforces, and reconciles them at BOOT so a contradiction is a
+ * startup message rather than one dropped image months later — which would
+ * surface as a `fetch` warning indistinguishable from the remote host being
+ * down.
+ *
+ * Contradictions resolve by FIREWALL CONVENTION and none of them stops the
+ * boot (#1144, D8). #1133 chose longest-prefix match — the routing rule,
+ * because the values are routes — so a general overlap is not a conflict at
+ * all. The cases longest prefix cannot decide are settled here: an allow entry
+ * reaching the mechanism is unsatisfiable and dropped, and a range in both
+ * lists is a prefix-length tie the DENY wins.
+ *
+ * `ngdpbase.security.profile` used to decide whether a contradiction stopped
+ * the boot. That was the profile looking for a job: `iptables` rejects a bad
+ * rule and keeps the chain, and the Kubernetes API server rejects an invalid
+ * NetworkPolicy while the others keep applying. Neither takes the workload
+ * down. The one case with no safe silent resolution — a malformed range, where
+ * dropping a DENY fails open — is reported separately for #1152.
+ */
+import { type EgressPolicy } from './ssrf.js';
+/** The shape of `ConfigurationManager.getProperty`. */
+export type ConfigReader = (key: string, fallback?: unknown) => unknown;
+export declare const DENIED_RANGES_KEY = "ngdpbase.security.egress.denied-ranges";
+export declare const ALLOWED_RANGES_KEY = "ngdpbase.security.egress.allowed-ranges";
+export interface ResolvedEgressPolicy {
+    policy: EgressPolicy;
+    /** Human-readable contradictions, empty when the configuration is coherent. */
+    conflicts: string[];
+    /**
+     * Ranges that do not parse as CIDR.
+     *
+     * Separate from `conflicts` because it is the only case without a safe
+     * silent resolution: dropping a malformed ALLOW fails closed and is
+     * harmless, while dropping a malformed DENY fails open — the operator wrote
+     * a restriction, it did not apply, and nothing looks wrong. #1152 turns this
+     * into a maintenance boot with a route to the fix.
+     */
+    malformed: string[];
+}
+/**
+ * Read the configured ranges, reconcile them, and report what could not be
+ * resolved.
+ *
+ * A contradiction never widens access. Where the two lists disagree the
+ * stricter reading wins, which is the only direction a security control should
+ * fail when nobody can be asked.
+ */
+export declare function resolveEgressPolicy(read: ConfigReader): ResolvedEgressPolicy;

package/lib/src/http/guardedFetch.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The outbound client (#1133).
+ *
+ * Node's built-in `fetch` is not used here, and that is the point rather than
+ * an inconvenience. It is undici, which ignores `http.Agent` and so ignores
+ * the guarded lookup in ./guardedLookup.ts that is the actual control — a
+ * guard installed on an Agent and then bypassed by `fetch()` looks correct in
+ * review and does nothing. `fetch` also follows redirects internally, which is
+ * exactly the step that has to be inspected rather than delegated.
+ *
+ * So requests go through node:http / node:https with the guarded agents, and
+ * redirects are followed by hand. Every hop is a fresh guarded request: the
+ * validated first URL is public and the server answers
+ * `302 http://169.254.169.254/…`, which no amount of checking the original URL
+ * would catch.
+ *
+ * Forbidding `fetch` outside this module is also what makes the boundary
+ * enforceable rather than merely present — "calling fetch is fine provided a
+ * dispatcher was installed first" is not something a CI check can see. That
+ * check is #1139.
+ *
+ * Adapted from `src/http/guarded-fetch.ts` in jwilleke/yourphr, sole-authored
+ * by the copyright holder and contributed here under this repository's
+ * Apache-2.0 licence.
+ */
+import { Agent as HttpAgent } from 'node:http';
+import { Agent as HttpsAgent } from 'node:https';
+import { type EgressPolicy } from './ssrf.js';
+import { type Resolver } from './guardedLookup.js';
+export interface TransportResponse {
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+    /** Chunks, so the byte cap can stop a large body instead of buffering it. */
+    body: AsyncIterable<Buffer>;
+}
+export interface TransportInit {
+    method: string;
+    headers: Record<string, string>;
+    agent: HttpAgent | HttpsAgent;
+    timeoutMs: number;
+    /** A request body (a POST's form), sent as given. */
+    body?: Buffer;
+}
+/**
+ * One request, one response, no redirect handling.
+ *
+ * Injected so the redirect and limit logic can be tested without a socket.
+ * Tier 1 in ./ssrf.ts is absolute, so a test cannot open loopback to reach a
+ * fixture server — and a production flag that could is precisely the switch
+ * that gets left on. The seam is a parameter a caller supplies, never a mode
+ * the shipped module can be put into.
+ */
+export type Transport = (url: URL, init: TransportInit) => Promise<TransportResponse>;
+export interface GuardedFetchOptions {
+    policy: EgressPolicy;
+    maxRedirects?: number;
+    maxBytes?: number;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+    method?: 'GET' | 'HEAD' | 'POST';
+    /**
+     * A POST body (#1743: an OpenID Connect token request). A request that
+     * carries one is never redirected: a redirect answer is returned as it is,
+     * so a body (a code, a client secret) is never re-sent to a host the caller
+     * did not name.
+     */
+    body?: string | Buffer;
+    /** Test seam — see `Transport`. */
+    transport?: Transport;
+    /** Test seam — see `Resolver`. */
+    resolver?: Resolver;
+}
+export interface GuardedResponse {
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: Buffer;
+    /** Where the response actually came from, after redirects. */
+    finalUrl: string;
+    /** Every URL in the chain. A redirect is a disclosure of where you went. */
+    chain: string[];
+}
+/**
+ * Fetch `target`, refusing at every hop to connect anywhere the policy does
+ * not permit.
+ *
+ * Each hop is validated as a URL first (a courtesy, and it catches a scheme
+ * change) and then at connect time by the guarded lookup, which is the control.
+ */
+export declare function guardedFetch(target: string, options: GuardedFetchOptions): Promise<GuardedResponse>;

package/lib/src/http/guardedFetch.js

@@ -0,0 +1,113 @@
+/**
+ * The outbound client (#1133).
+ *
+ * Node's built-in `fetch` is not used here, and that is the point rather than
+ * an inconvenience. It is undici, which ignores `http.Agent` and so ignores
+ * the guarded lookup in ./guardedLookup.ts that is the actual control — a
+ * guard installed on an Agent and then bypassed by `fetch()` looks correct in
+ * review and does nothing. `fetch` also follows redirects internally, which is
+ * exactly the step that has to be inspected rather than delegated.
+ *
+ * So requests go through node:http / node:https with the guarded agents, and
+ * redirects are followed by hand. Every hop is a fresh guarded request: the
+ * validated first URL is public and the server answers
+ * `302 http://169.254.169.254/…`, which no amount of checking the original URL
+ * would catch.
+ *
+ * Forbidding `fetch` outside this module is also what makes the boundary
+ * enforceable rather than merely present — "calling fetch is fine provided a
+ * dispatcher was installed first" is not something a CI check can see. That
+ * check is #1139.
+ *
+ * Adapted from `src/http/guarded-fetch.ts` in jwilleke/yourphr, sole-authored
+ * by the copyright holder and contributed here under this repository's
+ * Apache-2.0 licence.
+ */
+import { Agent as HttpAgent, request as httpRequest } from 'node:http';
+import { Agent as HttpsAgent, request as httpsRequest } from 'node:https';
+import { validateUrl } from './ssrf.js';
+import { guardedLookup } from './guardedLookup.js';
+const DEFAULTS = { maxRedirects: 5, maxBytes: 8 * 1024 * 1024, timeoutMs: 30_000 };
+/** Statuses that carry a `Location` worth following. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** The real transport: node:http / node:https, whose agents carry the guarded lookup. */
+const nodeTransport = (url, init) => new Promise((resolve, reject) => {
+    const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    const req = send(url, { method: init.method, headers: init.headers, agent: init.agent, timeout: init.timeoutMs }, (res) => {
+        resolve({
+            status: res.statusCode ?? 0,
+            headers: res.headers,
+            body: res
+        });
+    });
+    req.on('timeout', () => req.destroy(new Error(`timed out after ${init.timeoutMs}ms`)));
+    req.on('error', reject);
+    req.end(init.body);
+});
+/** Read chunks up to `maxBytes`, refusing — and stopping — rather than buffering past it. */
+async function readCapped(body, maxBytes) {
+    const parts = [];
+    let total = 0;
+    for await (const chunk of body) {
+        total += chunk.length;
+        if (total > maxBytes) {
+            throw new Error(`response body too large: exceeded maxBytes ${maxBytes}`);
+        }
+        parts.push(chunk);
+    }
+    return Buffer.concat(parts);
+}
+/** The first header value, since node presents repeated headers as an array. */
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * Fetch `target`, refusing at every hop to connect anywhere the policy does
+ * not permit.
+ *
+ * Each hop is validated as a URL first (a courtesy, and it catches a scheme
+ * change) and then at connect time by the guarded lookup, which is the control.
+ */
+export async function guardedFetch(target, options) {
+    const maxRedirects = options.maxRedirects ?? DEFAULTS.maxRedirects;
+    const maxBytes = options.maxBytes ?? DEFAULTS.maxBytes;
+    const timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs;
+    const transport = options.transport ?? nodeTransport;
+    const body = options.body === undefined ? undefined : Buffer.from(options.body);
+    // keepAlive: false is load-bearing. A pooled connection skips resolution on
+    // reuse, so the guard would run for the first request to a host and never
+    // again — every later request riding a connection validated once, long ago.
+    const agentOptions = { lookup: guardedLookup(options.policy, options.resolver), keepAlive: false };
+    const agents = { http: new HttpAgent(agentOptions), https: new HttpsAgent(agentOptions) };
+    const chain = [];
+    let current = target;
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+        const checked = validateUrl(current, options.policy);
+        if (!checked.ok) {
+            throw new Error(checked.reason);
+        }
+        const url = checked.url;
+        chain.push(url.toString());
+        const res = await transport(url, {
+            method: options.method ?? 'GET',
+            headers: body ? { ...options.headers, 'Content-Length': String(body.length) } : (options.headers ?? {}),
+            agent: url.protocol === 'https:' ? agents.https : agents.http,
+            timeoutMs,
+            ...(body ? { body } : {})
+        });
+        const location = headerValue(res.headers['location']);
+        if (!REDIRECT_STATUSES.has(res.status) || !location || body) {
+            return {
+                status: res.status,
+                headers: res.headers,
+                body: await readCapped(res.body, maxBytes),
+                finalUrl: url.toString(),
+                chain
+            };
+        }
+        // Relative Locations are legal and common; resolve against the hop that
+        // issued them, then validate the result like any other target.
+        current = new URL(location, url).toString();
+    }
+    throw new Error(`too many redirects: stopped after ${maxRedirects} (${chain.join(' -> ')})`);
+}