@warlock.js/ai 4.4.0 → 4.6.0

package/esm/rag/transforms/multi-query.d.mts

@@ -0,0 +1,27 @@
+import { ModelContract } from "../../contracts/model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/rag/transforms/multi-query.d.ts
+/** Options for {@link multiQuery}. */
+type MultiQueryOptions = {
+  /** How many alternative phrasings to request. Default 3. */n?: number; /** Include the original query in the returned list. Default true. */
+  includeOriginal?: boolean;
+};
+/**
+ * Multi-query expansion (A4) — ask a model for several alternative
+ * phrasings of `query`, so retrieval covers vocabulary the original
+ * wording missed (synonyms, specificity, rephrasings). Pair the variants
+ * with {@link hybridRank} / a vector search and fuse the per-variant hits.
+ *
+ * Deterministic, dependency-light parsing: the model is asked for one
+ * query per line; bullets / numbering are stripped, blanks dropped, and
+ * the set is de-duplicated. Returns the original (unless opted out) plus
+ * up to `n` variants.
+ *
+ * @example
+ * const queries = await multiQuery(model, "how do I cancel?", { n: 3 });
+ * // → ["how do I cancel?", "cancel my subscription", "end my plan", ...]
+ */
+declare function multiQuery(model: ModelContract, query: string, options?: MultiQueryOptions): Promise<string[]>;
+//#endregion
+export { MultiQueryOptions, multiQuery };
+//# sourceMappingURL=multi-query.d.mts.map

package/esm/rag/transforms/multi-query.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-query.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/transforms/multi-query.ts"],"mappings":";;;;KAGY,iBAAA;EAAA,4DAEV,CAAA;EAEA,eAAe;AAAA;AAkBjB;;;;;;;;;;;;;;;AAAA,iBAAsB,UAAA,CACpB,KAAA,EAAO,aAAA,EACP,KAAA,UACA,OAAA,GAAS,iBAAA,GACR,OAAA"}

package/esm/rag/transforms/multi-query.mjs

@@ -0,0 +1,41 @@
+//#region ../@warlock.js/ai/src/rag/transforms/multi-query.ts
+/**
+* Multi-query expansion (A4) — ask a model for several alternative
+* phrasings of `query`, so retrieval covers vocabulary the original
+* wording missed (synonyms, specificity, rephrasings). Pair the variants
+* with {@link hybridRank} / a vector search and fuse the per-variant hits.
+*
+* Deterministic, dependency-light parsing: the model is asked for one
+* query per line; bullets / numbering are stripped, blanks dropped, and
+* the set is de-duplicated. Returns the original (unless opted out) plus
+* up to `n` variants.
+*
+* @example
+* const queries = await multiQuery(model, "how do I cancel?", { n: 3 });
+* // → ["how do I cancel?", "cancel my subscription", "end my plan", ...]
+*/
+async function multiQuery(model, query, options = {}) {
+	const n = options.n ?? 3;
+	const includeOriginal = options.includeOriginal ?? true;
+	const prompt = `Rewrite the following search query into ${n} alternative phrasings that would retrieve relevant documents. Output ONE query per line, no numbering or commentary.\n\nQuery: ${query}`;
+	const variants = (await model.complete([{
+		role: "user",
+		content: prompt
+	}])).content.split("\n").map((line) => line.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, "").trim()).filter(Boolean);
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	const add = (q) => {
+		const key = q.toLowerCase();
+		if (!seen.has(key)) {
+			seen.add(key);
+			out.push(q);
+		}
+	};
+	if (includeOriginal) add(query);
+	for (const variant of variants.slice(0, n)) add(variant);
+	return out;
+}
+
+//#endregion
+export { multiQuery };
+//# sourceMappingURL=multi-query.mjs.map

package/esm/rag/transforms/multi-query.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-query.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/transforms/multi-query.ts"],"sourcesContent":["import type { ModelContract } from \"../../contracts/model.contract\";\n\n/** Options for {@link multiQuery}. */\nexport type MultiQueryOptions = {\n  /** How many alternative phrasings to request. Default 3. */\n  n?: number;\n  /** Include the original query in the returned list. Default true. */\n  includeOriginal?: boolean;\n};\n\n/**\n * Multi-query expansion (A4) — ask a model for several alternative\n * phrasings of `query`, so retrieval covers vocabulary the original\n * wording missed (synonyms, specificity, rephrasings). Pair the variants\n * with {@link hybridRank} / a vector search and fuse the per-variant hits.\n *\n * Deterministic, dependency-light parsing: the model is asked for one\n * query per line; bullets / numbering are stripped, blanks dropped, and\n * the set is de-duplicated. Returns the original (unless opted out) plus\n * up to `n` variants.\n *\n * @example\n * const queries = await multiQuery(model, \"how do I cancel?\", { n: 3 });\n * // → [\"how do I cancel?\", \"cancel my subscription\", \"end my plan\", ...]\n */\nexport async function multiQuery(\n  model: ModelContract,\n  query: string,\n  options: MultiQueryOptions = {},\n): Promise<string[]> {\n  const n = options.n ?? 3;\n  const includeOriginal = options.includeOriginal ?? true;\n\n  const prompt =\n    `Rewrite the following search query into ${n} alternative phrasings that would ` +\n    `retrieve relevant documents. Output ONE query per line, no numbering or commentary.\\n\\n` +\n    `Query: ${query}`;\n\n  const response = await model.complete([{ role: \"user\", content: prompt }]);\n\n  const variants = response.content\n    .split(\"\\n\")\n    .map(line => line.replace(/^\\s*(?:[-*•]|\\d+[.)])\\s*/, \"\").trim())\n    .filter(Boolean);\n\n  const seen = new Set<string>();\n  const out: string[] = [];\n\n  const add = (q: string) => {\n    const key = q.toLowerCase();\n    if (!seen.has(key)) {\n      seen.add(key);\n      out.push(q);\n    }\n  };\n\n  if (includeOriginal) add(query);\n  for (const variant of variants.slice(0, n)) add(variant);\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,eAAsB,WACpB,OACA,OACA,UAA6B,CAAC,GACX;CACnB,MAAM,IAAI,QAAQ,KAAK;CACvB,MAAM,kBAAkB,QAAQ,mBAAmB;CAEnD,MAAM,SACJ,2CAA2C,EAAE,kIAEnC;CAIZ,MAAM,YAAW,MAFM,MAAM,SAAS,CAAC;EAAE,MAAM;EAAQ,SAAS;CAAO,CAAC,CAAC,EAEhD,CAAC,QACvB,MAAM,IAAI,CAAC,CACX,KAAI,SAAQ,KAAK,QAAQ,4BAA4B,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAChE,OAAO,OAAO;CAEjB,MAAM,uBAAO,IAAI,IAAY;CAC7B,MAAM,MAAgB,CAAC;CAEvB,MAAM,OAAO,MAAc;EACzB,MAAM,MAAM,EAAE,YAAY;EAC1B,IAAI,CAAC,KAAK,IAAI,GAAG,GAAG;GAClB,KAAK,IAAI,GAAG;GACZ,IAAI,KAAK,CAAC;EACZ;CACF;CAEA,IAAI,iBAAiB,IAAI,KAAK;CAC9B,KAAK,MAAM,WAAW,SAAS,MAAM,GAAG,CAAC,GAAG,IAAI,OAAO;CAEvD,OAAO;AACT"}

package/esm/security/index.mjs

@@ -0,0 +1,5 @@
+import { isPrivateOrReservedIp } from "./private-ip.mjs";
+import { assertUrlAllowed, fetchTextWithPolicy, guardedFetch, readTextCapped, resolveOutboundPolicy } from "./outbound-policy.mjs";
+import { DEFAULT_SENSITIVE_KEYS, SENSITIVE_HEADERS, redact, redactError, redactHeaders, scrubSecrets } from "./redact.mjs";
+
+export {  };

package/esm/security/outbound-policy.d.mts

@@ -0,0 +1,46 @@
+import { OutboundPolicy, ResolvedOutboundPolicy } from "./outbound-policy.type.mjs";
+
+//#region ../@warlock.js/ai/src/security/outbound-policy.d.ts
+/**
+ * Fill an {@link OutboundPolicy} with strict defaults: https-only,
+ * private-IP deny on, 10s timeout, 5 MiB cap, global `fetch`. Idempotent
+ * — resolving an already-resolved policy yields the same shape.
+ */
+declare function resolveOutboundPolicy(policy?: OutboundPolicy): ResolvedOutboundPolicy;
+/**
+ * Validate a URL against the policy BEFORE any network call: scheme
+ * allowlist, host allowlist, and (when enabled) a DNS resolution that
+ * rejects private / loopback / link-local / metadata addresses — the SSRF
+ * guard. Returns the parsed `URL` on success; throws
+ * {@link OutboundPolicyError} otherwise.
+ */
+declare function assertUrlAllowed(rawUrl: string, policy: ResolvedOutboundPolicy): Promise<URL>;
+/**
+ * Policy-guarded `fetch`: validates the URL ({@link assertUrlAllowed}),
+ * then performs the request with the policy's timeout and (optional)
+ * caller signal merged. Returns the raw `Response` — read its body via
+ * {@link readTextCapped} to enforce `maxBytes`. Throws
+ * {@link OutboundPolicyError} on a policy violation or timeout.
+ */
+declare function guardedFetch(rawUrl: string, policyInput: OutboundPolicy, init?: RequestInit): Promise<Response>;
+/**
+ * Read a response body as UTF-8 text with a hard byte cap. A declared
+ * `content-length` over the cap fails fast; otherwise the stream is read
+ * chunk-by-chunk and aborted the moment the running total exceeds
+ * `maxBytes`. Throws {@link OutboundPolicyError} on overflow.
+ */
+declare function readTextCapped(response: Response, maxBytes: number): Promise<string>;
+/**
+ * Convenience: {@link guardedFetch} + {@link readTextCapped}. Returns the
+ * response status alongside the (capped) body text so callers can shape
+ * their own not-OK error. The body is only read when the response is OK.
+ */
+declare function fetchTextWithPolicy(rawUrl: string, policyInput: OutboundPolicy, init?: RequestInit): Promise<{
+  ok: boolean;
+  status: number;
+  statusText: string;
+  text: string;
+}>;
+//#endregion
+export { assertUrlAllowed, fetchTextWithPolicy, guardedFetch, readTextCapped, resolveOutboundPolicy };
+//# sourceMappingURL=outbound-policy.d.mts.map

package/esm/security/outbound-policy.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-policy.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/security/outbound-policy.ts"],"mappings":";;;;;AAmBA;;;iBAAgB,qBAAA,CACd,MAAA,GAAQ,cAAA,GACP,sBAAsB;;;;;AAAA;AAiCzB;;iBAAsB,gBAAA,CACpB,MAAA,UACA,MAAA,EAAQ,sBAAA,GACP,OAAA,CAAQ,GAAA;;;;;;;;iBAiGW,YAAA,CACpB,MAAA,UACA,WAAA,EAAa,cAAA,EACb,IAAA,GAAO,WAAA,GACN,OAAA,CAAQ,QAAA;;;;AArGG;AAiGd;;iBAkCsB,cAAA,CACpB,QAAA,EAAU,QAAA,EACV,QAAA,WACC,OAAO;;;;;;iBAgDY,mBAAA,CACpB,MAAA,UACA,WAAA,EAAa,cAAA,EACb,IAAA,GAAO,WAAA,GACN,OAAA;EAAU,EAAA;EAAa,MAAA;EAAgB,UAAA;EAAoB,IAAA;AAAA"}

package/esm/security/outbound-policy.mjs

@@ -0,0 +1,187 @@
+import { OutboundPolicyError } from "../errors/outbound-policy-error.mjs";
+import "../errors/index.mjs";
+import { isPrivateOrReservedIp } from "./private-ip.mjs";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+//#region ../@warlock.js/ai/src/security/outbound-policy.ts
+/** 5 MiB — default cap on an outbound response body. */
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+/** 10s — default per-request timeout. */
+const DEFAULT_TIMEOUT_MS = 1e4;
+/**
+* Fill an {@link OutboundPolicy} with strict defaults: https-only,
+* private-IP deny on, 10s timeout, 5 MiB cap, global `fetch`. Idempotent
+* — resolving an already-resolved policy yields the same shape.
+*/
+function resolveOutboundPolicy(policy = {}) {
+	return {
+		allowedSchemes: policy.allowedSchemes ?? ["https"],
+		hostAllowlist: policy.hostAllowlist,
+		denyPrivateIPsAfterDNS: policy.denyPrivateIPsAfterDNS ?? true,
+		maxBytes: policy.maxBytes ?? DEFAULT_MAX_BYTES,
+		timeoutMs: policy.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		signal: policy.signal,
+		fetch: policy.fetch ?? globalThis.fetch
+	};
+}
+/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */
+function stripBrackets(host) {
+	return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+/** Whether `host` equals or is a subdomain of any allowlist entry. */
+function hostAllowed(host, allowlist) {
+	const lower = host.toLowerCase();
+	return allowlist.some((entry) => {
+		const e = entry.toLowerCase();
+		return lower === e || lower.endsWith(`.${e}`);
+	});
+}
+/**
+* Validate a URL against the policy BEFORE any network call: scheme
+* allowlist, host allowlist, and (when enabled) a DNS resolution that
+* rejects private / loopback / link-local / metadata addresses — the SSRF
+* guard. Returns the parsed `URL` on success; throws
+* {@link OutboundPolicyError} otherwise.
+*/
+async function assertUrlAllowed(rawUrl, policy) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		throw new OutboundPolicyError(`outbound request blocked — invalid URL: ${rawUrl}`, { context: { url: rawUrl } });
+	}
+	const scheme = url.protocol.replace(/:$/, "").toLowerCase();
+	if (!policy.allowedSchemes.some((s) => s.toLowerCase() === scheme)) throw new OutboundPolicyError(`outbound request blocked — scheme "${scheme}" is not allowed (allowed: ${policy.allowedSchemes.join(", ")})`, { context: {
+		url: rawUrl,
+		scheme
+	} });
+	const host = stripBrackets(url.hostname);
+	if (policy.hostAllowlist && !hostAllowed(host, policy.hostAllowlist)) throw new OutboundPolicyError(`outbound request blocked — host "${host}" is not in the allowlist`, { context: {
+		url: rawUrl,
+		host
+	} });
+	if (policy.denyPrivateIPsAfterDNS) await assertHostNotPrivate(host, rawUrl);
+	return url;
+}
+/**
+* Reject when `host` is — or resolves to — a private / reserved address.
+* IP literals are checked directly; hostnames are resolved via DNS and
+* every returned address is checked (a public name pointing inward is
+* caught). A resolution failure fails closed.
+*/
+async function assertHostNotPrivate(host, rawUrl) {
+	if (isIP(host) !== 0) {
+		if (isPrivateOrReservedIp(host)) throw new OutboundPolicyError(`outbound request blocked — "${host}" is a private/reserved address`, { context: {
+			url: rawUrl,
+			address: host
+		} });
+		return;
+	}
+	let addresses;
+	try {
+		addresses = await lookup(host, { all: true });
+	} catch (cause) {
+		throw new OutboundPolicyError(`outbound request blocked — could not resolve host "${host}" to verify it is public`, {
+			cause,
+			context: {
+				url: rawUrl,
+				host
+			}
+		});
+	}
+	for (const { address } of addresses) if (isPrivateOrReservedIp(address)) throw new OutboundPolicyError(`outbound request blocked — host "${host}" resolves to a private/reserved address (${address})`, { context: {
+		url: rawUrl,
+		host,
+		address
+	} });
+}
+/** Merge the internal timeout signal with an optional caller signal. */
+function mergeSignals(timeout, external) {
+	if (!external) return timeout;
+	const controller = new AbortController();
+	const abort = (from) => controller.abort(from.reason);
+	if (timeout.aborted) abort(timeout);
+	else timeout.addEventListener("abort", () => abort(timeout), { once: true });
+	if (external.aborted) abort(external);
+	else external.addEventListener("abort", () => abort(external), { once: true });
+	return controller.signal;
+}
+/**
+* Policy-guarded `fetch`: validates the URL ({@link assertUrlAllowed}),
+* then performs the request with the policy's timeout and (optional)
+* caller signal merged. Returns the raw `Response` — read its body via
+* {@link readTextCapped} to enforce `maxBytes`. Throws
+* {@link OutboundPolicyError} on a policy violation or timeout.
+*/
+async function guardedFetch(rawUrl, policyInput, init) {
+	const policy = resolveOutboundPolicy(policyInput);
+	const url = await assertUrlAllowed(rawUrl, policy);
+	const timeoutController = new AbortController();
+	const timer = setTimeout(() => {
+		timeoutController.abort(new OutboundPolicyError(`outbound request timed out after ${policy.timeoutMs}ms`, { context: {
+			url: rawUrl,
+			timeoutMs: policy.timeoutMs
+		} }));
+	}, policy.timeoutMs);
+	try {
+		return await policy.fetch(url, {
+			...init,
+			signal: mergeSignals(timeoutController.signal, policy.signal)
+		});
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Read a response body as UTF-8 text with a hard byte cap. A declared
+* `content-length` over the cap fails fast; otherwise the stream is read
+* chunk-by-chunk and aborted the moment the running total exceeds
+* `maxBytes`. Throws {@link OutboundPolicyError} on overflow.
+*/
+async function readTextCapped(response, maxBytes) {
+	const declared = Number(response.headers.get("content-length"));
+	if (Number.isFinite(declared) && declared > maxBytes) throw new OutboundPolicyError(`outbound response body too large — declared ${declared} bytes exceeds the ${maxBytes}-byte cap`, { context: {
+		declared,
+		maxBytes
+	} });
+	if (!response.body) {
+		const text = await response.text();
+		if (Buffer.byteLength(text) > maxBytes) throw new OutboundPolicyError(`outbound response body exceeded the ${maxBytes}-byte cap`, { context: { maxBytes } });
+		return text;
+	}
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (!value) continue;
+		total += value.byteLength;
+		if (total > maxBytes) {
+			await reader.cancel();
+			throw new OutboundPolicyError(`outbound response body exceeded the ${maxBytes}-byte cap`, { context: { maxBytes } });
+		}
+		chunks.push(value);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+/**
+* Convenience: {@link guardedFetch} + {@link readTextCapped}. Returns the
+* response status alongside the (capped) body text so callers can shape
+* their own not-OK error. The body is only read when the response is OK.
+*/
+async function fetchTextWithPolicy(rawUrl, policyInput, init) {
+	const policy = resolveOutboundPolicy(policyInput);
+	const response = await guardedFetch(rawUrl, policy, init);
+	return {
+		ok: response.ok,
+		status: response.status,
+		statusText: response.statusText,
+		text: response.ok ? await readTextCapped(response, policy.maxBytes) : ""
+	};
+}
+
+//#endregion
+export { assertUrlAllowed, fetchTextWithPolicy, guardedFetch, readTextCapped, resolveOutboundPolicy };
+//# sourceMappingURL=outbound-policy.mjs.map

package/esm/security/outbound-policy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-policy.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/security/outbound-policy.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"node:net\";\nimport { OutboundPolicyError } from \"../errors\";\nimport { isPrivateOrReservedIp } from \"./private-ip\";\nimport type {\n  OutboundPolicy,\n  ResolvedOutboundPolicy,\n} from \"./outbound-policy.type\";\n\n/** 5 MiB — default cap on an outbound response body. */\nconst DEFAULT_MAX_BYTES = 5 * 1024 * 1024;\n/** 10s — default per-request timeout. */\nconst DEFAULT_TIMEOUT_MS = 10_000;\n\n/**\n * Fill an {@link OutboundPolicy} with strict defaults: https-only,\n * private-IP deny on, 10s timeout, 5 MiB cap, global `fetch`. Idempotent\n * — resolving an already-resolved policy yields the same shape.\n */\nexport function resolveOutboundPolicy(\n  policy: OutboundPolicy = {},\n): ResolvedOutboundPolicy {\n  return {\n    allowedSchemes: policy.allowedSchemes ?? [\"https\"],\n    hostAllowlist: policy.hostAllowlist,\n    denyPrivateIPsAfterDNS: policy.denyPrivateIPsAfterDNS ?? true,\n    maxBytes: policy.maxBytes ?? DEFAULT_MAX_BYTES,\n    timeoutMs: policy.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    signal: policy.signal,\n    fetch: policy.fetch ?? globalThis.fetch,\n  };\n}\n\n/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */\nfunction stripBrackets(host: string): string {\n  return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/** Whether `host` equals or is a subdomain of any allowlist entry. */\nfunction hostAllowed(host: string, allowlist: string[]): boolean {\n  const lower = host.toLowerCase();\n  return allowlist.some(entry => {\n    const e = entry.toLowerCase();\n    return lower === e || lower.endsWith(`.${e}`);\n  });\n}\n\n/**\n * Validate a URL against the policy BEFORE any network call: scheme\n * allowlist, host allowlist, and (when enabled) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws\n * {@link OutboundPolicyError} otherwise.\n */\nexport async function assertUrlAllowed(\n  rawUrl: string,\n  policy: ResolvedOutboundPolicy,\n): Promise<URL> {\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    throw new OutboundPolicyError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n      context: { url: rawUrl },\n    });\n  }\n\n  const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n  if (!policy.allowedSchemes.some(s => s.toLowerCase() === scheme)) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n      { context: { url: rawUrl, scheme } },\n    );\n  }\n\n  const host = stripBrackets(url.hostname);\n\n  if (policy.hostAllowlist && !hostAllowed(host, policy.hostAllowlist)) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — host \"${host}\" is not in the allowlist`,\n      { context: { url: rawUrl, host } },\n    );\n  }\n\n  if (policy.denyPrivateIPsAfterDNS) {\n    await assertHostNotPrivate(host, rawUrl);\n  }\n\n  return url;\n}\n\n/**\n * Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and\n * every returned address is checked (a public name pointing inward is\n * caught). A resolution failure fails closed.\n */\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n  if (isIP(host) !== 0) {\n    if (isPrivateOrReservedIp(host)) {\n      throw new OutboundPolicyError(\n        `outbound request blocked — \"${host}\" is a private/reserved address`,\n        { context: { url: rawUrl, address: host } },\n      );\n    }\n    return;\n  }\n\n  let addresses: Array<{ address: string }>;\n  try {\n    addresses = await lookup(host, { all: true });\n  } catch (cause) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n      { cause, context: { url: rawUrl, host } },\n    );\n  }\n\n  for (const { address } of addresses) {\n    if (isPrivateOrReservedIp(address)) {\n      throw new OutboundPolicyError(\n        `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n        { context: { url: rawUrl, host, address } },\n      );\n    }\n  }\n}\n\n/** Merge the internal timeout signal with an optional caller signal. */\nfunction mergeSignals(\n  timeout: AbortSignal,\n  external?: AbortSignal,\n): AbortSignal {\n  if (!external) return timeout;\n\n  const controller = new AbortController();\n  const abort = (from: AbortSignal) => controller.abort(from.reason);\n\n  if (timeout.aborted) abort(timeout);\n  else timeout.addEventListener(\"abort\", () => abort(timeout), { once: true });\n\n  if (external.aborted) abort(external);\n  else external.addEventListener(\"abort\", () => abort(external), { once: true });\n\n  return controller.signal;\n}\n\n/**\n * Policy-guarded `fetch`: validates the URL ({@link assertUrlAllowed}),\n * then performs the request with the policy's timeout and (optional)\n * caller signal merged. Returns the raw `Response` — read its body via\n * {@link readTextCapped} to enforce `maxBytes`. Throws\n * {@link OutboundPolicyError} on a policy violation or timeout.\n */\nexport async function guardedFetch(\n  rawUrl: string,\n  policyInput: OutboundPolicy,\n  init?: RequestInit,\n): Promise<Response> {\n  const policy = resolveOutboundPolicy(policyInput);\n  const url = await assertUrlAllowed(rawUrl, policy);\n\n  const timeoutController = new AbortController();\n  const timer = setTimeout(() => {\n    timeoutController.abort(\n      new OutboundPolicyError(\n        `outbound request timed out after ${policy.timeoutMs}ms`,\n        { context: { url: rawUrl, timeoutMs: policy.timeoutMs } },\n      ),\n    );\n  }, policy.timeoutMs);\n\n  try {\n    return await policy.fetch(url, {\n      ...init,\n      signal: mergeSignals(timeoutController.signal, policy.signal),\n    });\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Read a response body as UTF-8 text with a hard byte cap. A declared\n * `content-length` over the cap fails fast; otherwise the stream is read\n * chunk-by-chunk and aborted the moment the running total exceeds\n * `maxBytes`. Throws {@link OutboundPolicyError} on overflow.\n */\nexport async function readTextCapped(\n  response: Response,\n  maxBytes: number,\n): Promise<string> {\n  const declared = Number(response.headers.get(\"content-length\"));\n  if (Number.isFinite(declared) && declared > maxBytes) {\n    throw new OutboundPolicyError(\n      `outbound response body too large — declared ${declared} bytes exceeds the ${maxBytes}-byte cap`,\n      { context: { declared, maxBytes } },\n    );\n  }\n\n  if (!response.body) {\n    const text = await response.text();\n    if (Buffer.byteLength(text) > maxBytes) {\n      throw new OutboundPolicyError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { maxBytes } },\n      );\n    }\n    return text;\n  }\n\n  const reader = response.body.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n    if (done) break;\n    if (!value) continue;\n\n    total += value.byteLength;\n    if (total > maxBytes) {\n      await reader.cancel();\n      throw new OutboundPolicyError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { maxBytes } },\n      );\n    }\n    chunks.push(value);\n  }\n\n  return Buffer.concat(chunks).toString(\"utf8\");\n}\n\n/**\n * Convenience: {@link guardedFetch} + {@link readTextCapped}. Returns the\n * response status alongside the (capped) body text so callers can shape\n * their own not-OK error. The body is only read when the response is OK.\n */\nexport async function fetchTextWithPolicy(\n  rawUrl: string,\n  policyInput: OutboundPolicy,\n  init?: RequestInit,\n): Promise<{ ok: boolean; status: number; statusText: string; text: string }> {\n  const policy = resolveOutboundPolicy(policyInput);\n  const response = await guardedFetch(rawUrl, policy, init);\n\n  return {\n    ok: response.ok,\n    status: response.status,\n    statusText: response.statusText,\n    text: response.ok ? await readTextCapped(response, policy.maxBytes) : \"\",\n  };\n}\n"],"mappings":";;;;;;;;AAUA,MAAM,oBAAoB,IAAI,OAAO;;AAErC,MAAM,qBAAqB;;;;;;AAO3B,SAAgB,sBACd,SAAyB,CAAC,GACF;CACxB,OAAO;EACL,gBAAgB,OAAO,kBAAkB,CAAC,OAAO;EACjD,eAAe,OAAO;EACtB,wBAAwB,OAAO,0BAA0B;EACzD,UAAU,OAAO,YAAY;EAC7B,WAAW,OAAO,aAAa;EAC/B,QAAQ,OAAO;EACf,OAAO,OAAO,SAAS,WAAW;CACpC;AACF;;AAGA,SAAS,cAAc,MAAsB;CAC3C,OAAO,KAAK,WAAW,GAAG,KAAK,KAAK,SAAS,GAAG,IAAI,KAAK,MAAM,GAAG,EAAE,IAAI;AAC1E;;AAGA,SAAS,YAAY,MAAc,WAA8B;CAC/D,MAAM,QAAQ,KAAK,YAAY;CAC/B,OAAO,UAAU,MAAK,UAAS;EAC7B,MAAM,IAAI,MAAM,YAAY;EAC5B,OAAO,UAAU,KAAK,MAAM,SAAS,IAAI,GAAG;CAC9C,CAAC;AACH;;;;;;;;AASA,eAAsB,iBACpB,QACA,QACc;CACd,IAAI;CACJ,IAAI;EACF,MAAM,IAAI,IAAI,MAAM;CACtB,QAAQ;EACN,MAAM,IAAI,oBAAoB,2CAA2C,UAAU,EACjF,SAAS,EAAE,KAAK,OAAO,EACzB,CAAC;CACH;CAEA,MAAM,SAAS,IAAI,SAAS,QAAQ,MAAM,EAAE,CAAC,CAAC,YAAY;CAC1D,IAAI,CAAC,OAAO,eAAe,MAAK,MAAK,EAAE,YAAY,MAAM,MAAM,GAC7D,MAAM,IAAI,oBACR,sCAAsC,OAAO,6BAA6B,OAAO,eAAe,KAAK,IAAI,EAAE,IAC3G,EAAE,SAAS;EAAE,KAAK;EAAQ;CAAO,EAAE,CACrC;CAGF,MAAM,OAAO,cAAc,IAAI,QAAQ;CAEvC,IAAI,OAAO,iBAAiB,CAAC,YAAY,MAAM,OAAO,aAAa,GACjE,MAAM,IAAI,oBACR,oCAAoC,KAAK,4BACzC,EAAE,SAAS;EAAE,KAAK;EAAQ;CAAK,EAAE,CACnC;CAGF,IAAI,OAAO,wBACT,MAAM,qBAAqB,MAAM,MAAM;CAGzC,OAAO;AACT;;;;;;;AAQA,eAAe,qBAAqB,MAAc,QAA+B;CAC/E,IAAI,KAAK,IAAI,MAAM,GAAG;EACpB,IAAI,sBAAsB,IAAI,GAC5B,MAAM,IAAI,oBACR,+BAA+B,KAAK,kCACpC,EAAE,SAAS;GAAE,KAAK;GAAQ,SAAS;EAAK,EAAE,CAC5C;EAEF;CACF;CAEA,IAAI;CACJ,IAAI;EACF,YAAY,MAAM,OAAO,MAAM,EAAE,KAAK,KAAK,CAAC;CAC9C,SAAS,OAAO;EACd,MAAM,IAAI,oBACR,sDAAsD,KAAK,2BAC3D;GAAE;GAAO,SAAS;IAAE,KAAK;IAAQ;GAAK;EAAE,CAC1C;CACF;CAEA,KAAK,MAAM,EAAE,aAAa,WACxB,IAAI,sBAAsB,OAAO,GAC/B,MAAM,IAAI,oBACR,oCAAoC,KAAK,4CAA4C,QAAQ,IAC7F,EAAE,SAAS;EAAE,KAAK;EAAQ;EAAM;CAAQ,EAAE,CAC5C;AAGN;;AAGA,SAAS,aACP,SACA,UACa;CACb,IAAI,CAAC,UAAU,OAAO;CAEtB,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,SAAS,SAAsB,WAAW,MAAM,KAAK,MAAM;CAEjE,IAAI,QAAQ,SAAS,MAAM,OAAO;MAC7B,QAAQ,iBAAiB,eAAe,MAAM,OAAO,GAAG,EAAE,MAAM,KAAK,CAAC;CAE3E,IAAI,SAAS,SAAS,MAAM,QAAQ;MAC/B,SAAS,iBAAiB,eAAe,MAAM,QAAQ,GAAG,EAAE,MAAM,KAAK,CAAC;CAE7E,OAAO,WAAW;AACpB;;;;;;;;AASA,eAAsB,aACpB,QACA,aACA,MACmB;CACnB,MAAM,SAAS,sBAAsB,WAAW;CAChD,MAAM,MAAM,MAAM,iBAAiB,QAAQ,MAAM;CAEjD,MAAM,oBAAoB,IAAI,gBAAgB;CAC9C,MAAM,QAAQ,iBAAiB;EAC7B,kBAAkB,MAChB,IAAI,oBACF,oCAAoC,OAAO,UAAU,KACrD,EAAE,SAAS;GAAE,KAAK;GAAQ,WAAW,OAAO;EAAU,EAAE,CAC1D,CACF;CACF,GAAG,OAAO,SAAS;CAEnB,IAAI;EACF,OAAO,MAAM,OAAO,MAAM,KAAK;GAC7B,GAAG;GACH,QAAQ,aAAa,kBAAkB,QAAQ,OAAO,MAAM;EAC9D,CAAC;CACH,UAAU;EACR,aAAa,KAAK;CACpB;AACF;;;;;;;AAQA,eAAsB,eACpB,UACA,UACiB;CACjB,MAAM,WAAW,OAAO,SAAS,QAAQ,IAAI,gBAAgB,CAAC;CAC9D,IAAI,OAAO,SAAS,QAAQ,KAAK,WAAW,UAC1C,MAAM,IAAI,oBACR,+CAA+C,SAAS,qBAAqB,SAAS,YACtF,EAAE,SAAS;EAAE;EAAU;CAAS,EAAE,CACpC;CAGF,IAAI,CAAC,SAAS,MAAM;EAClB,MAAM,OAAO,MAAM,SAAS,KAAK;EACjC,IAAI,OAAO,WAAW,IAAI,IAAI,UAC5B,MAAM,IAAI,oBACR,uCAAuC,SAAS,YAChD,EAAE,SAAS,EAAE,SAAS,EAAE,CAC1B;EAEF,OAAO;CACT;CAEA,MAAM,SAAS,SAAS,KAAK,UAAU;CACvC,MAAM,SAAuB,CAAC;CAC9B,IAAI,QAAQ;CAEZ,SAAS;EACP,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;EAC1C,IAAI,MAAM;EACV,IAAI,CAAC,OAAO;EAEZ,SAAS,MAAM;EACf,IAAI,QAAQ,UAAU;GACpB,MAAM,OAAO,OAAO;GACpB,MAAM,IAAI,oBACR,uCAAuC,SAAS,YAChD,EAAE,SAAS,EAAE,SAAS,EAAE,CAC1B;EACF;EACA,OAAO,KAAK,KAAK;CACnB;CAEA,OAAO,OAAO,OAAO,MAAM,CAAC,CAAC,SAAS,MAAM;AAC9C;;;;;;AAOA,eAAsB,oBACpB,QACA,aACA,MAC4E;CAC5E,MAAM,SAAS,sBAAsB,WAAW;CAChD,MAAM,WAAW,MAAM,aAAa,QAAQ,QAAQ,IAAI;CAExD,OAAO;EACL,IAAI,SAAS;EACb,QAAQ,SAAS;EACjB,YAAY,SAAS;EACrB,MAAM,SAAS,KAAK,MAAM,eAAe,UAAU,OAAO,QAAQ,IAAI;CACxE;AACF"}

package/esm/security/outbound-policy.type.d.mts

@@ -0,0 +1,74 @@
+//#region ../@warlock.js/ai/src/security/outbound-policy.type.d.ts
+/**
+ * One shared policy for every server-side outbound request the framework
+ * makes on a user's behalf — attachment fetches (S1), URL skill manifests
+ * (S3), RAG document loaders (A4), and any future HTTP helper. Centralizing
+ * the controls here means a single, audited SSRF / resource-exhaustion
+ * guard instead of six ad-hoc `fetch()` call sites.
+ *
+ * Every field is optional; {@link resolveOutboundPolicy} fills safe
+ * defaults. The defaults are deliberately strict (https-only, private-IP
+ * deny on, 10s timeout, 5 MiB cap) so a caller that opts into outbound
+ * fetch without tuning still gets a hardened request.
+ *
+ * @example
+ * const policy: OutboundPolicy = {
+ *   allowedSchemes: ["https"],
+ *   hostAllowlist: ["cdn.example.com"],
+ *   maxBytes: 1_000_000,
+ *   timeoutMs: 5_000,
+ * };
+ */
+type OutboundPolicy = {
+  /**
+   * URL schemes permitted for the request. Compared case-insensitively
+   * against the URL's protocol (without the trailing colon). Default
+   * `["https"]` — `http` must be opted in explicitly.
+   */
+  allowedSchemes?: string[];
+  /**
+   * Host allowlist. When set, the request host must equal one of these
+   * entries or be a subdomain of one (`cdn.example.com` allows
+   * `a.cdn.example.com`). When omitted, any host passes the allowlist
+   * check — but the private-IP guard below still applies.
+   */
+  hostAllowlist?: string[];
+  /**
+   * Resolve the host through DNS and reject when it maps to a private,
+   * loopback, link-local, unique-local, or cloud-metadata
+   * (`169.254.169.254`) address — the core SSRF guard. Catches a public
+   * hostname that resolves inward. Default `true`.
+   */
+  denyPrivateIPsAfterDNS?: boolean;
+  /**
+   * Maximum response body size in bytes. A declared `content-length`
+   * over this fails fast; otherwise the body is read with a running cap
+   * and aborted on overflow. Default `5_242_880` (5 MiB).
+   */
+  maxBytes?: number; /** Per-request timeout in milliseconds. Default `10_000`. */
+  timeoutMs?: number;
+  /**
+   * Caller `AbortSignal`, merged with the internal timeout — whichever
+   * fires first aborts the request.
+   */
+  signal?: AbortSignal;
+  /**
+   * Injected `fetch` implementation (for tests, proxies, or a wrapper
+   * that already enforces app-level SSRF rules). Defaults to the global
+   * `fetch`.
+   */
+  fetch?: typeof fetch;
+};
+/** {@link OutboundPolicy} with every default resolved — never partial. */
+type ResolvedOutboundPolicy = {
+  allowedSchemes: string[];
+  hostAllowlist?: string[];
+  denyPrivateIPsAfterDNS: boolean;
+  maxBytes: number;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  fetch: typeof fetch;
+};
+//#endregion
+export { OutboundPolicy, ResolvedOutboundPolicy };
+//# sourceMappingURL=outbound-policy.type.d.mts.map

package/esm/security/outbound-policy.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-policy.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/security/outbound-policy.type.ts"],"mappings":";;AAoBA;;;;;;;;;;;;;;AAuCsB;AAItB;;;;KA3CY,cAAA;EA6CV;;;;;EAvCA,cAAA;EA4CA;;;AAAmB;;;EArCnB,aAAA;;;;;;;EAOA,sBAAA;;;;;;EAMA,QAAA;EAEA,SAAA;;;;;EAKA,MAAA,GAAS,WAAA;;;;;;EAMT,KAAA,UAAe,KAAK;AAAA;;KAIV,sBAAA;EACV,cAAA;EACA,aAAA;EACA,sBAAA;EACA,QAAA;EACA,SAAA;EACA,MAAA,GAAS,WAAA;EACT,KAAA,SAAc,KAAK;AAAA"}

package/esm/security/private-ip.d.mts

@@ -0,0 +1,15 @@
+//#region ../@warlock.js/ai/src/security/private-ip.d.ts
+/**
+ * True when `ip` is a private, loopback, link-local, unique-local,
+ * carrier-grade-NAT, unspecified, or otherwise non-public address — the
+ * set an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including
+ * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns
+ * `false` (the caller resolves hostnames via DNS first).
+ *
+ * The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4
+ * link-local range `169.254.0.0/16`.
+ */
+declare function isPrivateOrReservedIp(ip: string): boolean;
+//#endregion
+export { isPrivateOrReservedIp };
+//# sourceMappingURL=private-ip.d.mts.map

package/esm/security/private-ip.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-ip.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/security/private-ip.ts"],"mappings":";;AAYA;;;;AAAgD;;;;;iBAAhC,qBAAA,CAAsB,EAAU"}

package/esm/security/private-ip.mjs

@@ -0,0 +1,48 @@
+import { isIP } from "node:net";
+
+//#region ../@warlock.js/ai/src/security/private-ip.ts
+/**
+* True when `ip` is a private, loopback, link-local, unique-local,
+* carrier-grade-NAT, unspecified, or otherwise non-public address — the
+* set an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including
+* IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns
+* `false` (the caller resolves hostnames via DNS first).
+*
+* The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4
+* link-local range `169.254.0.0/16`.
+*/
+function isPrivateOrReservedIp(ip) {
+	const family = isIP(ip);
+	if (family === 4) return isPrivateIpv4(ip);
+	if (family === 6) return isPrivateIpv6(ip);
+	return false;
+}
+/** Parse a dotted-quad into four octets, or `null` if malformed. */
+function parseIpv4(ip) {
+	const parts = ip.split(".");
+	if (parts.length !== 4) return null;
+	const octets = parts.map((part) => Number(part));
+	if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+	return octets;
+}
+function isPrivateIpv4(ip) {
+	const octets = parseIpv4(ip);
+	if (!octets) return true;
+	const [a, b] = octets;
+	return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 192 && b === 0 || a === 198 && (b === 18 || b === 19) || a === 198 && b === 51 || a === 203 && b === 0 || a >= 224;
+}
+function isPrivateIpv6(ip) {
+	const normalized = ip.toLowerCase().split("%")[0];
+	const v4 = normalized.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+	if (v4) return isPrivateIpv4(v4[1]);
+	if (normalized === "::1" || normalized === "::") return true;
+	const firstGroup = normalized.split(":")[0];
+	const head = firstGroup === "" ? 0 : Number.parseInt(firstGroup, 16);
+	if ((head & 65024) === 64512) return true;
+	if ((head & 65472) === 65152) return true;
+	return false;
+}
+
+//#endregion
+export { isPrivateOrReservedIp };
+//# sourceMappingURL=private-ip.mjs.map

package/esm/security/private-ip.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-ip.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/security/private-ip.ts"],"sourcesContent":["import { isIP } from \"node:net\";\n\n/**\n * True when `ip` is a private, loopback, link-local, unique-local,\n * carrier-grade-NAT, unspecified, or otherwise non-public address — the\n * set an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including\n * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns\n * `false` (the caller resolves hostnames via DNS first).\n *\n * The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4\n * link-local range `169.254.0.0/16`.\n */\nexport function isPrivateOrReservedIp(ip: string): boolean {\n  const family = isIP(ip);\n  if (family === 4) return isPrivateIpv4(ip);\n  if (family === 6) return isPrivateIpv6(ip);\n  return false;\n}\n\n/** Parse a dotted-quad into four octets, or `null` if malformed. */\nfunction parseIpv4(ip: string): [number, number, number, number] | null {\n  const parts = ip.split(\".\");\n  if (parts.length !== 4) return null;\n\n  const octets = parts.map(part => Number(part));\n  if (octets.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return null;\n\n  return octets as [number, number, number, number];\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n  const octets = parseIpv4(ip);\n  if (!octets) return true; // unparseable → refuse, fail closed\n\n  const [a, b] = octets;\n\n  return (\n    a === 0 || // 0.0.0.0/8 \"this network\"\n    a === 10 || // 10.0.0.0/8 private\n    a === 127 || // 127.0.0.0/8 loopback\n    (a === 100 && b >= 64 && b <= 127) || // 100.64.0.0/10 CGNAT\n    (a === 169 && b === 254) || // 169.254.0.0/16 link-local + metadata\n    (a === 172 && b >= 16 && b <= 31) || // 172.16.0.0/12 private\n    (a === 192 && b === 168) || // 192.168.0.0/16 private\n    (a === 192 && b === 0) || // 192.0.0.0/24 + 192.0.2.0/24 (IETF/test)\n    (a === 198 && (b === 18 || b === 19)) || // 198.18.0.0/15 benchmarking\n    (a === 198 && b === 51) || // 198.51.100.0/24 test-net-2\n    (a === 203 && b === 0) || // 203.0.113.0/24 test-net-3\n    a >= 224 // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255\n  );\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n  const normalized = ip.toLowerCase().split(\"%\")[0]; // drop zone id\n\n  // IPv4-mapped / -embedded (::ffff:a.b.c.d, ::a.b.c.d) — defer to the v4\n  // check on the trailing dotted-quad so an inward-mapped address is caught.\n  const v4 = normalized.match(/(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n  if (v4) {\n    return isPrivateIpv4(v4[1]);\n  }\n\n  if (normalized === \"::1\" || normalized === \"::\") {\n    return true; // loopback / unspecified\n  }\n\n  // Expand only the leading group enough to classify the reserved blocks.\n  const firstGroup = normalized.split(\":\")[0];\n  const head = firstGroup === \"\" ? 0 : Number.parseInt(firstGroup, 16);\n\n  // fc00::/7 unique-local (fc.. / fd..)\n  if ((head & 0xfe00) === 0xfc00) return true;\n  // fe80::/10 link-local\n  if ((head & 0xffc0) === 0xfe80) return true;\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,sBAAsB,IAAqB;CACzD,MAAM,SAAS,KAAK,EAAE;CACtB,IAAI,WAAW,GAAG,OAAO,cAAc,EAAE;CACzC,IAAI,WAAW,GAAG,OAAO,cAAc,EAAE;CACzC,OAAO;AACT;;AAGA,SAAS,UAAU,IAAqD;CACtE,MAAM,QAAQ,GAAG,MAAM,GAAG;CAC1B,IAAI,MAAM,WAAW,GAAG,OAAO;CAE/B,MAAM,SAAS,MAAM,KAAI,SAAQ,OAAO,IAAI,CAAC;CAC7C,IAAI,OAAO,MAAK,MAAK,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,GAAG,GAAG,OAAO;CAEvE,OAAO;AACT;AAEA,SAAS,cAAc,IAAqB;CAC1C,MAAM,SAAS,UAAU,EAAE;CAC3B,IAAI,CAAC,QAAQ,OAAO;CAEpB,MAAM,CAAC,GAAG,KAAK;CAEf,OACE,MAAM,KACN,MAAM,MACN,MAAM,OACL,MAAM,OAAO,KAAK,MAAM,KAAK,OAC7B,MAAM,OAAO,MAAM,OACnB,MAAM,OAAO,KAAK,MAAM,KAAK,MAC7B,MAAM,OAAO,MAAM,OACnB,MAAM,OAAO,MAAM,KACnB,MAAM,QAAQ,MAAM,MAAM,MAAM,OAChC,MAAM,OAAO,MAAM,MACnB,MAAM,OAAO,MAAM,KACpB,KAAK;AAET;AAEA,SAAS,cAAc,IAAqB;CAC1C,MAAM,aAAa,GAAG,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;CAI/C,MAAM,KAAK,WAAW,MAAM,uCAAuC;CACnE,IAAI,IACF,OAAO,cAAc,GAAG,EAAE;CAG5B,IAAI,eAAe,SAAS,eAAe,MACzC,OAAO;CAIT,MAAM,aAAa,WAAW,MAAM,GAAG,CAAC,CAAC;CACzC,MAAM,OAAO,eAAe,KAAK,IAAI,OAAO,SAAS,YAAY,EAAE;CAGnE,KAAK,OAAO,WAAY,OAAQ,OAAO;CAEvC,KAAK,OAAO,WAAY,OAAQ,OAAO;CAEvC,OAAO;AACT"}

package/esm/security/redact.d.mts

@@ -0,0 +1,59 @@
+//#region ../@warlock.js/ai/src/security/redact.d.ts
+/**
+ * Default set of sensitive key fragments (matched case-insensitively as
+ * substrings of an object key). Covers the secrets that leak through
+ * recorded requests, error causes, and trace payloads: auth headers, API
+ * keys, cookies, tokens, passwords, and private keys.
+ */
+declare const DEFAULT_SENSITIVE_KEYS: readonly string[];
+/** HTTP header names always stripped from a serialized error/cause. */
+declare const SENSITIVE_HEADERS: readonly string[];
+type RedactOptions = {
+  /** Extra key fragments to redact, merged with {@link DEFAULT_SENSITIVE_KEYS}. */keys?: string[]; /** Replacement for a redacted value. Default `"[redacted]"`. */
+  placeholder?: string; /** Maximum recursion depth before bailing out. Default `8`. */
+  maxDepth?: number;
+};
+/**
+ * Deep-copy `value` with any property whose KEY matches a sensitive
+ * fragment replaced by the placeholder. Arrays are walked element-wise;
+ * circular references and over-deep trees collapse to the placeholder.
+ * Primitives pass through untouched (redaction is key-driven, not
+ * value-driven — it never guesses at a bare string being a secret).
+ *
+ * Shared by VCR cassettes (S2), Panoptic content capture, and the error /
+ * cause serializer (S4) so there is ONE redaction policy, not three.
+ */
+declare function redact<T>(value: T, options?: RedactOptions): T;
+/**
+ * Strip sensitive HTTP headers from a `Headers` instance or a plain
+ * header record, returning a redacted plain object. Header names are
+ * matched case-insensitively against {@link SENSITIVE_HEADERS}.
+ */
+declare function redactHeaders(headers: Headers | Record<string, unknown> | undefined, placeholder?: string): Record<string, unknown>;
+/**
+ * Scrub secrets that appear in free-form text — error messages, stack
+ * traces, exported log lines. Complements {@link redact} (which is key-
+ * driven and can't see a token embedded in a string). Used by the trace /
+ * error serializer (S4) before a message or stack is stored or exported.
+ */
+declare function scrubSecrets(text: string): string;
+/**
+ * Serialized, secret-free view of an error. `stack` is omitted by default
+ * (it can embed local paths, endpoints, and tokens); pass
+ * `includeStack: true` only for a trusted local sink. The retained
+ * `cause` is deep-redacted via {@link redact}, so a raw provider SDK error
+ * carrying `Authorization` / `x-api-key` on `cause.headers` is sanitized.
+ */
+type RedactedError = {
+  name: string;
+  message: string;
+  code?: string;
+  cause?: unknown;
+  stack?: string;
+};
+declare function redactError(error: unknown, options?: {
+  includeStack?: boolean;
+} & RedactOptions): RedactedError;
+//#endregion
+export { DEFAULT_SENSITIVE_KEYS, RedactOptions, RedactedError, SENSITIVE_HEADERS, redact, redactError, redactHeaders, scrubSecrets };
+//# sourceMappingURL=redact.d.mts.map

package/esm/security/redact.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/security/redact.ts"],"mappings":";;AAMA;;;;AAgBC;cAhBY,sBAAA;;cAmBA,iBAAA;AAAA,KASD,aAAA;EAFX,iFAIC,IAAA,aAFuB;EAIvB,WAAA,WAJuB;EAMvB,QAAA;AAAA;;;AAAQ;AAqBV;;;;;;;iBAAgB,MAAA,IAAU,KAAA,EAAO,CAAA,EAAG,OAAA,GAAS,aAAA,GAAqB,CAAA;;;;;;iBAsClD,aAAA,CACd,OAAA,EAAS,OAAA,GAAU,MAAA,+BACnB,WAAA,YACC,MAAA;;AAzCgE;AAsCnE;;;;iBAuCgB,YAAA,CAAa,IAAY;;;;;;;;KAe7B,aAAA;EACV,IAAA;EACA,OAAA;EACA,IAAA;EACA,KAAA;EACA,KAAA;AAAA;AAAA,iBAGc,WAAA,CACd,KAAA,WACA,OAAA;EAAW,YAAA;AAAA,IAA2B,aAAA,GACrC,aAAa"}