@sweny-ai/core 0.1.102 → 0.1.104

package/dist/skills/custom-loader.js

@@ -20,6 +20,18 @@ import { builtinSkills, isSkillConfigured } from "./index.js";
  * side cannot disagree on what counts as a skill harness directory.
  */
 const SKILL_DIRS = SKILL_HARNESSES.map((h) => h.path);
+/**
+ * Opt-in env flag that allows discovered SKILL.md files to wire a local stdio
+ * `mcp.command`. Defaults OFF: an unvetted discovered stdio command is a code
+ * execution sink (the harness runs with `permissionMode: "bypassPermissions"`),
+ * and SKILL.md files can arrive via a PR or supply-chain path that the workflow
+ * author never reviewed per run.
+ */
+const STDIO_OPT_IN_ENV = "SWENY_ALLOW_SKILL_STDIO_COMMAND";
+function stdioCommandAllowed(env) {
+    const v = (env[STDIO_OPT_IN_ENV] ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
 /**
  * Discover custom skills and surface diagnostics for broken ones.
  *
@@ -27,9 +39,10 @@ const SKILL_DIRS = SKILL_HARNESSES.map((h) => h.path);
  * to users. `discoverSkills` stays as a backward-compatible wrapper for
  * callers that only want the happy-path skill list.
  */
-export function discoverSkillsWithDiagnostics(cwd = process.cwd()) {
+export function discoverSkillsWithDiagnostics(cwd = process.cwd(), env = process.env) {
     const skillMap = new Map();
     const warnings = [];
+    const allowStdio = stdioCommandAllowed(env);
     for (const relDir of SKILL_DIRS) {
         const skillsDir = join(cwd, relDir);
         if (!existsSync(skillsDir))
@@ -60,8 +73,10 @@ export function discoverSkillsWithDiagnostics(cwd = process.cwd()) {
                 });
                 continue;
             }
-            const parsed = parseSkillMd(content, skillFile);
+            const parsed = parseSkillMd(content, skillFile, allowStdio);
             if (parsed.kind === "ok") {
+                if (parsed.diagnostics)
+                    warnings.push(...parsed.diagnostics);
                 if (skillMap.has(parsed.skill.id)) {
                     warnings.push({
                         kind: "duplicate-id",
@@ -84,10 +99,10 @@ export function discoverSkillsWithDiagnostics(cwd = process.cwd()) {
  * Backwards-compatible wrapper that drops diagnostics. Use
  * `discoverSkillsWithDiagnostics` when you want to surface warnings.
  */
-export function discoverSkills(cwd = process.cwd()) {
-    return discoverSkillsWithDiagnostics(cwd).skills;
+export function discoverSkills(cwd = process.cwd(), env = process.env) {
+    return discoverSkillsWithDiagnostics(cwd, env).skills;
 }
-function parseSkillMd(content, path) {
+function parseSkillMd(content, path, allowStdio) {
     const raw = parseFrontmatter(content);
     if (raw === "invalid") {
         return {
@@ -118,18 +133,38 @@ function parseSkillMd(content, path) {
         };
     }
     const instruction = extractBody(content);
+    const diagnostics = [];
     let mcp;
     if (fm.mcp && typeof fm.mcp === "object") {
         const m = fm.mcp;
         if (m.command || m.url) {
-            mcp = {
-                type: m.type ?? (m.command ? "stdio" : "http"),
-                ...(m.command ? { command: m.command } : {}),
-                ...(m.args ? { args: m.args } : {}),
-                ...(m.url ? { url: m.url } : {}),
-                ...(m.headers ? { headers: m.headers } : {}),
-                ...(m.env ? { env: m.env } : {}),
-            };
+            const isStdio = (m.type ?? (m.command ? "stdio" : "http")) === "stdio";
+            // A discovered SKILL.md that declares a local stdio `command` is a code
+            // execution sink — the harness runs with bypassPermissions, so the
+            // command spawns with no interactive gate. Surface it loudly and, unless
+            // explicitly opted in via SWENY_ALLOW_SKILL_STDIO_COMMAND, do NOT wire it
+            // as a launchable server (drop the mcp config). HTTP-type skills and
+            // skills with no command are unaffected.
+            if (isStdio && m.command) {
+                diagnostics.push({
+                    kind: "stdio-command-declared",
+                    path,
+                    message: `Skill "${id}" declares a local stdio command (${String(m.command)}). ` +
+                        (allowStdio
+                            ? `Honoring it because ${STDIO_OPT_IN_ENV} is set — this spawns a local process with bypassPermissions.`
+                            : `Refusing to wire it as a launchable MCP server. Set ${STDIO_OPT_IN_ENV}=1 to opt in (the command runs with bypassPermissions).`),
+                });
+            }
+            if (!isStdio || !m.command || allowStdio) {
+                mcp = {
+                    type: m.type ?? (m.command ? "stdio" : "http"),
+                    ...(m.command ? { command: m.command } : {}),
+                    ...(m.args ? { args: m.args } : {}),
+                    ...(m.url ? { url: m.url } : {}),
+                    ...(m.headers ? { headers: m.headers } : {}),
+                    ...(m.env ? { env: m.env } : {}),
+                };
+            }
         }
     }
     // Parse config fields from frontmatter
@@ -158,6 +193,7 @@ function parseSkillMd(content, path) {
             instruction: instruction || undefined,
             mcp,
         },
+        diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
     };
 }
 /**
@@ -209,18 +245,24 @@ export function loadCustomSkills(cwd = process.cwd()) {
  */
 export function configuredSkillsWithDiagnostics(env = process.env, cwd) {
     const configured = builtinSkills.filter((s) => isSkillConfigured(s, env));
-    const { skills: custom, warnings } = discoverSkillsWithDiagnostics(cwd);
+    const { skills: custom, warnings } = discoverSkillsWithDiagnostics(cwd, env);
     // Custom skills can override built-in IDs. When overriding, merge:
     // keep the built-in's tools and config, add the custom instruction/mcp.
     const configuredMap = new Map(configured.map((s) => [s.id, s]));
+    // Resolve override targets against the FULL built-in set, not the
+    // env-filtered `configured` list. Otherwise a custom override of a built-in
+    // whose required env var happens to be unset falls through to the
+    // "net-new custom skill" branch and silently drops the built-in's tools.
+    // The tool surface of a built-in must not hinge on an unrelated env check.
+    const builtinById = new Map(builtinSkills.map((s) => [s.id, s]));
     for (const skill of custom) {
-        const existing = configuredMap.get(skill.id);
-        if (existing) {
+        const base = configuredMap.get(skill.id) ?? builtinById.get(skill.id);
+        if (base) {
             configuredMap.set(skill.id, {
-                ...existing,
-                config: { ...existing.config, ...skill.config },
-                instruction: skill.instruction ?? existing.instruction,
-                mcp: skill.mcp ?? existing.mcp,
+                ...base,
+                config: { ...base.config, ...skill.config },
+                instruction: skill.instruction ?? base.instruction,
+                mcp: skill.mcp ?? base.mcp,
             });
         }
         else {

package/dist/skills/github.js

@@ -185,8 +185,14 @@ export const github = {
                         });
                     }
                 }
-                catch {
-                    // Label failure is non-fatal
+                catch (err) {
+                    // Label failure is non-fatal: the PR is already created and labeling
+                    // is a best-effort followup. Surface a single warn line naming the
+                    // PR + failure so operators can tell a label-misconfigured run from
+                    // a clean one. Without this log, a 5xx from /issues/:n/labels was
+                    // indistinguishable from success in CI output.
+                    const msg = err instanceof Error ? err.message : String(err);
+                    ctx.logger?.warn?.(`  github_create_pr: label POST failed for ${pr.html_url ?? `#${pr.number}`} — ${msg}`);
                 }
                 return reused ? { ...pr, reused: true } : pr;
             },

package/dist/skills/linear.js

@@ -107,6 +107,31 @@ export const linear = {
             }
           }`, { id: input.id }, ctx),
         },
+        {
+            name: "linear_list_comments",
+            description: "List comments on a Linear issue (returns id, body, author, and timestamp for each)",
+            input_schema: {
+                type: "object",
+                properties: {
+                    issueId: { type: "string", description: "Linear issue ID (UUID) or identifier (e.g. 'OFF-1020')" },
+                    limit: { type: "number", description: "Max comments to return (default: 50)" },
+                },
+                required: ["issueId"],
+            },
+            handler: async (input, ctx) => {
+                const data = await linearGql(`query($id: String!, $first: Int) {
+            issue(id: $id) {
+              comments(first: $first) {
+                nodes { id body createdAt user { name } }
+              }
+            }
+          }`, { id: input.issueId, first: input.limit ?? 50 }, ctx);
+                if (!data?.issue) {
+                    throw new Error(`[Linear] linear_list_comments found no issue "${input.issueId}". Raw response: ${JSON.stringify(data)}`);
+                }
+                return data;
+            },
+        },
         {
             name: "linear_list_teams",
             description: "List Linear teams (needed for teamId when creating issues)",
@@ -181,6 +206,7 @@ export const linear = {
         linear_update_issue: ["save_issue"],
         linear_search_issues: ["list_issues"],
         linear_add_comment: ["save_comment"],
+        linear_list_comments: ["list_comments"],
         linear_list_teams: ["list_teams"],
         linear_list_labels: ["list_issue_labels"],
     },

package/dist/skills/notification.d.ts

@@ -8,4 +8,21 @@
  * This skill handles generic webhooks, Discord, Teams, and email.
  */
 import type { Skill } from "../types.js";
+/**
+ * Resolve the destination URL for `notify_webhook`.
+ *
+ * Trust model: the LLM controls tool arguments at runtime, and resolved source
+ * content is attacker-influenceable (prompt injection). A free-form `url`
+ * override would turn `notify_webhook` into an arbitrary exfiltration sink, so
+ * the destination is locked to operator-configured values:
+ *
+ *   - With no override, the configured `NOTIFICATION_WEBHOOK_URL` is used.
+ *   - An `override` is only honored when its host matches the configured
+ *     webhook's host, or a host on the `NOTIFICATION_WEBHOOK_ALLOWED_HOSTS`
+ *     allowlist (comma-separated, host[:port], case-insensitive).
+ *   - Anything else is rejected with a clear error.
+ *
+ * Returns the URL to POST to, or throws an `Error` the caller surfaces.
+ */
+export declare function resolveWebhookUrl(override: string | undefined, config: Record<string, string | undefined>): string;
 export declare const notification: Skill;

package/dist/skills/notification.js

@@ -7,6 +7,58 @@
  * For Slack-specific notifications, use the Slack skill instead.
  * This skill handles generic webhooks, Discord, Teams, and email.
  */
+/**
+ * Resolve the destination URL for `notify_webhook`.
+ *
+ * Trust model: the LLM controls tool arguments at runtime, and resolved source
+ * content is attacker-influenceable (prompt injection). A free-form `url`
+ * override would turn `notify_webhook` into an arbitrary exfiltration sink, so
+ * the destination is locked to operator-configured values:
+ *
+ *   - With no override, the configured `NOTIFICATION_WEBHOOK_URL` is used.
+ *   - An `override` is only honored when its host matches the configured
+ *     webhook's host, or a host on the `NOTIFICATION_WEBHOOK_ALLOWED_HOSTS`
+ *     allowlist (comma-separated, host[:port], case-insensitive).
+ *   - Anything else is rejected with a clear error.
+ *
+ * Returns the URL to POST to, or throws an `Error` the caller surfaces.
+ */
+export function resolveWebhookUrl(override, config) {
+    const configured = config.NOTIFICATION_WEBHOOK_URL;
+    if (override === undefined || override === "") {
+        if (!configured) {
+            throw new Error("[Notification] No webhook URL configured (set NOTIFICATION_WEBHOOK_URL)");
+        }
+        return configured;
+    }
+    // An override was supplied — only honor it if its host is allowlisted.
+    let overrideHost;
+    try {
+        overrideHost = new URL(override).host.toLowerCase();
+    }
+    catch {
+        throw new Error(`[Notification] Invalid webhook url override: ${override}`);
+    }
+    const allowed = new Set();
+    if (configured) {
+        try {
+            allowed.add(new URL(configured).host.toLowerCase());
+        }
+        catch {
+            // Misconfigured NOTIFICATION_WEBHOOK_URL — ignore for allowlist purposes.
+        }
+    }
+    for (const host of (config.NOTIFICATION_WEBHOOK_ALLOWED_HOSTS ?? "").split(",")) {
+        const h = host.trim().toLowerCase();
+        if (h)
+            allowed.add(h);
+    }
+    if (allowed.has(overrideHost))
+        return override;
+    throw new Error(`[Notification] Refusing to POST to non-allowlisted host "${overrideHost}". ` +
+        `Destination is locked to NOTIFICATION_WEBHOOK_URL; ` +
+        `add the host to NOTIFICATION_WEBHOOK_ALLOWED_HOSTS to permit it.`);
+}
 export const notification = {
     id: "notification",
     name: "Notification",
@@ -18,6 +70,12 @@ export const notification = {
             required: false,
             env: "NOTIFICATION_WEBHOOK_URL",
         },
+        NOTIFICATION_WEBHOOK_ALLOWED_HOSTS: {
+            description: "Comma-separated host allowlist (host[:port]) for the notify_webhook url override. " +
+                "The configured NOTIFICATION_WEBHOOK_URL host is always allowed.",
+            required: false,
+            env: "NOTIFICATION_WEBHOOK_ALLOWED_HOSTS",
+        },
         DISCORD_WEBHOOK_URL: {
             description: "Discord webhook URL",
             required: false,
@@ -37,19 +95,23 @@ export const notification = {
     tools: [
         {
             name: "notify_webhook",
-            description: "Send a JSON payload to a webhook URL",
+            description: "Send a JSON payload to the configured notification webhook (NOTIFICATION_WEBHOOK_URL). " +
+                "The destination is fixed: an optional `url` is only honored when its host is on the " +
+                "NOTIFICATION_WEBHOOK_ALLOWED_HOSTS allowlist; arbitrary hosts are rejected.",
             input_schema: {
                 type: "object",
                 properties: {
-                    url: { type: "string", description: "Webhook URL (overrides NOTIFICATION_WEBHOOK_URL)" },
+                    url: {
+                        type: "string",
+                        description: "Optional webhook URL. Only honored when its host matches NOTIFICATION_WEBHOOK_URL " +
+                            "or an entry in NOTIFICATION_WEBHOOK_ALLOWED_HOSTS; otherwise rejected.",
+                    },
                     payload: { type: "object", description: "JSON payload to send" },
                 },
                 required: ["payload"],
             },
             handler: async (input, ctx) => {
-                const url = input.url ?? ctx.config.NOTIFICATION_WEBHOOK_URL;
-                if (!url)
-                    throw new Error("No webhook URL provided or configured");
+                const url = resolveWebhookUrl(input.url, ctx.config);
                 const res = await fetch(url, {
                     method: "POST",
                     headers: { "Content-Type": "application/json" },

package/dist/source-resolver.js

@@ -6,9 +6,17 @@
  * (Zod schema, classifier, types) can be imported without pulling `node:fs`
  * or `node:crypto` into bundlers that target the browser.
  */
+import * as dns from "node:dns/promises";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { normalizeSource } from "./sources.js";
+/** Schemes a `url:` source is allowed to use. Everything else is rejected. */
+const ALLOWED_URL_SCHEMES = new Set(["http:", "https:"]);
+/** Default DNS resolver used when the context does not inject one. */
+const defaultDnsLookup = async (hostname) => {
+    const records = await dns.lookup(hostname, { all: true });
+    return records.map((r) => r.address);
+};
 /**
  * Produce a stable 16-hex-char hash of `content` for use as a cache key /
  * change-detection ID.
@@ -46,6 +54,7 @@ export async function resolveSource(source, fieldPath, ctx) {
     }
     if (kind === "file") {
         const absolute = path.isAbsolute(value) ? value : path.resolve(ctx.cwd, value);
+        assertFileWithinRoot(absolute, ctx, fieldPath);
         let content;
         try {
             content = await fs.readFile(absolute, "utf-8");
@@ -78,8 +87,12 @@ export async function resolveSource(source, fieldPath, ctx) {
             throw new Error(`SOURCE_INVALID_TYPE: unknown resolver type "${source.type}" on ${value} (referenced by ${fieldPath}). v1 supports only "fetch".`);
         }
         const url = value;
-        const headers = buildFetchHeaders(url, ctx);
-        const res = await fetchWithRetry(url, headers, fieldPath);
+        assertAllowedScheme(url, fieldPath);
+        // Validate the initial host before sending anything. Redirect hops are
+        // re-validated per-hop inside fetchWithRetry (redirect: "manual").
+        await assertSafeHost(url, ctx, fieldPath);
+        const headers = await buildFetchHeaders(url, ctx);
+        const res = await fetchWithRetry(url, headers, fieldPath, ctx);
         if (res.status === 401 || res.status === 403) {
             throw new Error(`SOURCE_URL_AUTH_REQUIRED: ${url} returned HTTP ${res.status} (referenced by ${fieldPath}). Configure fetch.auth in .sweny.yml or set SWENY_FETCH_TOKEN.`);
         }
@@ -124,11 +137,19 @@ function canonicalKey(source, ctx) {
     return null;
 }
 const RETRY_DELAYS = [250, 1000]; // ms — exponential backoff for 5xx
-async function fetchWithRetry(url, headers, fieldPath) {
+const MAX_REDIRECTS = 5;
+/**
+ * Fetch with retry on 5xx/network errors AND manual redirect handling. Each
+ * redirect hop is re-validated (scheme + host SSRF check + token scoping) so a
+ * benign first host cannot redirect to the cloud metadata endpoint or another
+ * private target, and a credential meant for host A is never replayed to host
+ * B unless B is also allowlisted.
+ */
+async function fetchWithRetry(startUrl, startHeaders, fieldPath, ctx) {
     let lastError;
     for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
         try {
-            const res = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
+            const res = await fetchFollowingRedirects(startUrl, startHeaders, fieldPath, ctx);
             // Don't retry on 4xx (client errors) or 2xx (success)
             if (res.status < 500)
                 return res;
@@ -140,6 +161,9 @@ async function fetchWithRetry(url, headers, fieldPath) {
             return res; // final 5xx — let caller handle it
         }
         catch (err) {
+            // SSRF rejections are not transient — surface immediately, do not retry.
+            if (err instanceof Error && err.message.startsWith("SOURCE_URL_BLOCKED"))
+                throw err;
             lastError = err instanceof Error ? err : new Error(String(err));
             if (attempt < RETRY_DELAYS.length) {
                 await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
@@ -147,9 +171,36 @@ async function fetchWithRetry(url, headers, fieldPath) {
             }
         }
     }
-    throw new Error(`SOURCE_URL_UNREACHABLE: ${url} (referenced by ${fieldPath}): ${lastError?.message ?? "unknown error"}. Pass --offline to skip URL sources.`);
+    throw new Error(`SOURCE_URL_UNREACHABLE: ${startUrl} (referenced by ${fieldPath}): ${lastError?.message ?? "unknown error"}. Pass --offline to skip URL sources.`);
+}
+async function fetchFollowingRedirects(startUrl, startHeaders, fieldPath, ctx) {
+    let currentUrl = startUrl;
+    let headers = startHeaders;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const res = await fetch(currentUrl, {
+            headers,
+            redirect: "manual",
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!isRedirect(res.status))
+            return res;
+        const location = res.headers.get("location");
+        if (!location)
+            return res; // redirect status with no Location — let caller handle
+        const nextUrl = new URL(location, currentUrl).toString();
+        assertAllowedScheme(nextUrl, fieldPath);
+        await assertSafeHost(nextUrl, ctx, fieldPath);
+        // Re-scope the credential for the redirect target. A token for host A is
+        // dropped on a hop to host B unless B is also explicitly allowlisted.
+        headers = await buildFetchHeaders(nextUrl, ctx);
+        currentUrl = nextUrl;
+    }
+    throw new Error(`SOURCE_URL_UNREACHABLE: ${startUrl} (referenced by ${fieldPath}): too many redirects (>${MAX_REDIRECTS}).`);
+}
+function isRedirect(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
 }
-function buildFetchHeaders(url, ctx) {
+async function buildFetchHeaders(url, ctx) {
     const headers = {
         Accept: "text/plain, text/markdown, */*",
     };
@@ -158,6 +209,12 @@ function buildFetchHeaders(url, ctx) {
         headers.Authorization = `Bearer ${token}`;
     return headers;
 }
+/**
+ * Resolve the bearer token for a URL, but ONLY if the URL's host is on the
+ * fetch-token allowlist. There is no blanket `SWENY_FETCH_TOKEN` fallback to
+ * arbitrary hosts: a credential is never sent to a host the operator did not
+ * explicitly authorize.
+ */
 function resolveFetchToken(url, ctx) {
     let host;
     try {
@@ -166,9 +223,177 @@ function resolveFetchToken(url, ctx) {
     catch {
         return undefined;
     }
+    if (!isTokenHostAllowed(host, ctx))
+        return undefined;
     const envVar = ctx.authConfig[host];
     if (envVar && ctx.env[envVar])
         return ctx.env[envVar];
     const fallback = ctx.env.SWENY_FETCH_TOKEN;
     return fallback || undefined;
 }
+/**
+ * A host may receive the fetch token if it is explicitly allowlisted. The
+ * allowlist is `fetchTokenHosts` when provided, otherwise the keys of
+ * `authConfig` (the hosts the operator configured a per-host mapping for).
+ */
+function isTokenHostAllowed(host, ctx) {
+    const allow = ctx.fetchTokenHosts ?? Object.keys(ctx.authConfig);
+    return allow.includes(host);
+}
+function assertAllowedScheme(url, fieldPath) {
+    let scheme;
+    try {
+        scheme = new URL(url).protocol;
+    }
+    catch {
+        throw new Error(`SOURCE_URL_BLOCKED: malformed URL "${url}" (referenced by ${fieldPath}).`);
+    }
+    if (!ALLOWED_URL_SCHEMES.has(scheme)) {
+        throw new Error(`SOURCE_URL_BLOCKED: scheme "${scheme}" not allowed for ${url} (referenced by ${fieldPath}). Only http and https are permitted.`);
+    }
+}
+/**
+ * Reject a URL whose host resolves to a private, loopback, or link-local
+ * address (SSRF guard). Literal-IP hosts are checked directly. Hostnames are
+ * resolved via the injected DNS lookup and every returned address is checked.
+ * A hostname that fails to resolve is allowed through (the subsequent fetch
+ * will simply fail) so that this guard does not turn DNS outages or unknown
+ * test hosts into hard validation errors.
+ */
+async function assertSafeHost(url, ctx, fieldPath) {
+    const hostname = new URL(url).hostname;
+    const literal = stripIpv6Brackets(hostname);
+    if (isIpAddress(literal)) {
+        if (isBlockedIp(literal)) {
+            throw new Error(`SOURCE_URL_BLOCKED: ${url} resolves to blocked address ${literal} (referenced by ${fieldPath}). Private, loopback, and link-local hosts are not allowed.`);
+        }
+        return;
+    }
+    const lookup = ctx.dnsLookup ?? defaultDnsLookup;
+    let addresses;
+    try {
+        addresses = await lookup(hostname);
+    }
+    catch {
+        return; // unresolved host — let fetch fail naturally
+    }
+    for (const addr of addresses) {
+        if (isBlockedIp(addr)) {
+            throw new Error(`SOURCE_URL_BLOCKED: ${url} resolves to blocked address ${addr} (referenced by ${fieldPath}). Private, loopback, and link-local hosts are not allowed.`);
+        }
+    }
+}
+function stripIpv6Brackets(host) {
+    return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+function isIpAddress(host) {
+    return isIpv4(host) || host.includes(":");
+}
+function isIpv4(host) {
+    const parts = host.split(".");
+    if (parts.length !== 4)
+        return false;
+    return parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255);
+}
+/**
+ * True if `ip` (v4 or v6 literal) is one of the address ranges that must never
+ * be reachable from a source fetch: loopback, private (RFC1918), link-local
+ * (including the cloud metadata endpoint 169.254.169.254), CGNAT, unspecified,
+ * and the IPv6 equivalents (::1, fe80::/10, fc00::/7, IPv4-mapped forms).
+ */
+function isBlockedIp(ip) {
+    const v4 = ipv4Octets(ip);
+    if (v4)
+        return isBlockedIpv4(v4);
+    return isBlockedIpv6(ip);
+}
+function ipv4Octets(ip) {
+    if (!isIpv4(ip))
+        return null;
+    return ip.split(".").map(Number);
+}
+function isBlockedIpv4([a, b]) {
+    if (a === 0)
+        return true; // 0.0.0.0/8 (incl. unspecified)
+    if (a === 10)
+        return true; // 10.0.0.0/8 private
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a >= 224)
+        return true; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved
+    return false;
+}
+function isBlockedIpv6(raw) {
+    const ip = raw.toLowerCase().split("%")[0]; // drop zone id
+    if (ip === "::1" || ip === "::")
+        return true; // loopback / unspecified
+    const embedded = embeddedIpv4(ip);
+    if (embedded)
+        return isBlockedIpv4(embedded);
+    const firstGroup = ip.split(":")[0];
+    const hextet = parseInt(firstGroup || "0", 16);
+    if ((hextet & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    if ((hextet & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique local
+    return false;
+}
+/**
+ * Extract the embedded IPv4 address from an IPv4-mapped IPv6 literal, handling
+ * both the dotted tail form (`::ffff:1.2.3.4`) and the hex form the WHATWG URL
+ * parser normalizes to (`::ffff:0102:0304`).
+ *
+ * Only `::ffff:`-prefixed (IPv4-mapped) addresses are unwrapped. A dotted tail
+ * on any other prefix (e.g. `fe80::1.2.3.4`) is NOT treated as an embedded
+ * IPv4: unwrapping it would skip the link-local / unique-local hextet checks
+ * below and let `fe80::1.2.3.4` masquerade as the public address 1.2.3.4. In
+ * practice the WHATWG URL parser already normalizes such inputs to hex form, so
+ * this is defense-in-depth, but the predicate must be correct on its own.
+ */
+function embeddedIpv4(ip) {
+    if (!ip.includes("::ffff:"))
+        return null;
+    // Dotted tail form: ::ffff:1.2.3.4
+    const lastColon = ip.lastIndexOf(":");
+    const tail = lastColon >= 0 ? ip.slice(lastColon + 1) : ip;
+    if (tail.includes("."))
+        return ipv4Octets(tail);
+    // Hex form: an IPv4-mapped address ends in two hextets after ::ffff:.
+    const groups = ip.split(":").filter((g) => g.length > 0);
+    if (groups.length < 2)
+        return null;
+    const hi = parseInt(groups[groups.length - 2], 16);
+    const lo = parseInt(groups[groups.length - 1], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo))
+        return null;
+    return [(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff];
+}
+/**
+ * Enforce the optional repo-root file sandbox. The sandbox is opt-in: it only
+ * applies when `fileRoot` is set (preserving legacy "read anywhere" behavior
+ * for callers that don't configure a root). When active, a `file:` source must
+ * resolve to a path inside `fileRoot`; `..` traversal and absolute paths that
+ * escape the root are rejected. Set `allowFileOutsideRoot` to opt back out even
+ * when a root is configured.
+ */
+function assertFileWithinRoot(absolute, ctx, fieldPath) {
+    if (ctx.allowFileOutsideRoot)
+        return;
+    if (!ctx.fileRoot)
+        return; // sandbox not configured — legacy behavior
+    const root = path.resolve(ctx.fileRoot);
+    const normalized = path.resolve(absolute);
+    const rel = path.relative(root, normalized);
+    const escapes = rel === ".." || rel.startsWith(".." + path.sep) || path.isAbsolute(rel);
+    if (escapes) {
+        throw new Error(`SOURCE_FILE_OUTSIDE_ROOT: ${absolute} is outside the allowed root ${root} (referenced by ${fieldPath}). Set allowFileOutsideRoot to permit reads outside the repo.`);
+    }
+}

package/dist/sources.d.ts

@@ -64,10 +64,43 @@ export type SourceResolutionMap = Record<string, ResolvedSource>;
  */
 export declare function classifySource(raw: string): SourceKind;
 export declare function normalizeSource(source: Source): [SourceKind, string];
+/**
+ * Result of a DNS lookup: one or more resolved IP addresses for a hostname.
+ * Injectable via {@link SourceResolutionContext.dnsLookup} so SSRF host
+ * validation is deterministic in tests (no real network).
+ */
+export type DnsLookup = (hostname: string) => Promise<string[]>;
 export type SourceResolutionContext = {
     cwd: string;
     env: NodeJS.ProcessEnv;
     authConfig: Record<string, string>;
     offline: boolean;
     logger: Logger;
+    /**
+     * Hosts the per-host fetch token (`fetch.auth` mapping) or the
+     * `SWENY_FETCH_TOKEN` env var may be sent to. The token is ONLY attached to
+     * requests whose host (and every redirect hop's host) appears here. There is
+     * deliberately no blanket fallback: a credential is never sent to a host the
+     * operator did not explicitly allow. When omitted, the allowlist is derived
+     * from the keys of `authConfig`.
+     */
+    fetchTokenHosts?: string[];
+    /**
+     * Restrict `file:` source resolution to this directory tree (the repo root,
+     * typically `cwd`). Relative and absolute paths that escape it via `..` or
+     * symlinks are rejected. Defaults to `cwd`. Set
+     * {@link allowFileOutsideRoot} to opt out.
+     */
+    fileRoot?: string;
+    /**
+     * Opt out of the {@link fileRoot} sandbox, permitting `file:` sources to read
+     * anywhere on disk (legacy behavior). Defaults to `false`.
+     */
+    allowFileOutsideRoot?: boolean;
+    /**
+     * Injected DNS resolver for SSRF host validation. Defaults to a
+     * `node:dns`-backed lookup. Tests inject a stub to assert IP-blocking without
+     * touching the network.
+     */
+    dnsLookup?: DnsLookup;
 };