kubeagent 0.1.36 → 0.1.44

package/README.md

@@ -27,6 +27,7 @@ kubeagent watch
 | `status` | Quick cluster health check (no LLM) |
 | `onboard` | Scan cluster + codebases, generate knowledge base |
 | `watch` | Continuous monitoring with auto-remediation |
+| `check` | One-shot cluster health check for CI pipelines (read-only by default, JSON output, exit codes) |
 | `diagnose <resource>` | One-shot diagnosis of a pod/deployment/service |
 | `scan <directory>` | Match local project directories to cluster deployments |
 | `scan-apps` | Detect OSS apps in the cluster, list affected workloads + ingress domains, check for CVEs / EOL (`--report` for AI-prioritized remediation) |
@@ -43,6 +44,30 @@ kubeagent watch
 - `-i, --interval <seconds>` — Check interval for `watch` (default: 300)
 - `--no-interactive` — Auto-deny all approvals, skip questions (for `watch` in background/CI)
 
+## CI Usage
+
+`kubeagent check` is the one-shot mode for CI pipelines. It scans the cluster, prints a report, and exits with a code your build can gate on — no daemon, no prompts, no onboarding required.
+
+```bash
+# After deploying: confirm pods reached Ready
+kubectl rollout status deployment/my-app -n my-ns --timeout=5m
+
+# Then confirm the system is actually healthy
+kubeagent check -n my-ns
+```
+
+The two steps are complementary: `rollout status` answers *"did Kubernetes accept the deploy?"*, `kubeagent check` answers *"is the system actually healthy?"* — catching crashloops, evicted pods, and failed jobs that surface seconds after pods reach Ready.
+
+**Exit codes:** `0` = no issues at/above threshold · `1` = issues found · `2` = kubeagent error (unreachable cluster, bad flag, timeout).
+
+**Common flags:**
+- `-n, --namespace <ns>` — scope to one or more namespaces (repeatable)
+- `--fail-on <severity>` — fail-threshold: `info`, `warning`, or `critical` (default: `critical`)
+- `--format json` — emit a versioned JSON report instead of human output
+- `--diagnose` — run LLM root-cause analysis on findings (requires `KUBEAGENT_API_KEY` env var)
+
+See [docs/CI.md](docs/CI.md) for full reference, GitHub Actions and GitLab CI snippets, and the JSON schema.
+
 ## Knowledge Base
 
 KubeAgent builds a per-cluster knowledge base at `~/.kubeagent/clusters/<context>/` during onboarding:
@@ -124,6 +149,13 @@ Safe actions (pod restarts, rollout restarts, scaling up) are applied automatica
 **Where is my API key stored?**
 Credentials are stored locally at `~/.kubeagent/auth.json` and are never sent anywhere except the KubeAgent API.
 
+## Links
+
+- [Homepage](https://kubeagent.net)
+- [Blog](https://kubeagent.net/blog/) — incident walkthroughs, agentic-diagnosis patterns, on-call economics ([RSS](https://kubeagent.net/blog/rss.xml))
+- [Docs](https://kubeagent.net/docs)
+- [Sign up](https://app.kubeagent.net/register)
+
 ## License
 
 Proprietary — see [LICENSE](./LICENSE) for details. Commercial use requires a paid plan at [kubeagent.net](https://kubeagent.net).

package/dist/auth.js

@@ -7,7 +7,22 @@ import { dbg } from "./debug.js";
 function authPath() {
     return join(configDir(), "auth.json");
 }
+const DEFAULT_SERVER_URL = "https://api.kubeagent.net";
+const DEFAULT_APP_URL = "https://app.kubeagent.net";
 export function loadAuth() {
+    // Env-var path for CI: KUBEAGENT_API_KEY takes precedence so machines can
+    // run without a local auth.json. KUBEAGENT_SERVER_URL / KUBEAGENT_APP_URL
+    // are optional overrides for self-hosted setups.
+    const envKey = process.env.KUBEAGENT_API_KEY;
+    if (envKey) {
+        dbg("auth", "loaded from env", { keyPrefix: envKey.slice(0, 12) + "..." });
+        return {
+            serverUrl: process.env.KUBEAGENT_SERVER_URL ?? DEFAULT_SERVER_URL,
+            appUrl: process.env.KUBEAGENT_APP_URL ?? DEFAULT_APP_URL,
+            token: envKey,
+            apiKey: envKey,
+        };
+    }
     const path = authPath();
     if (!existsSync(path)) {
         dbg("auth", "no auth file found", { path });

package/dist/check/index.js

@@ -0,0 +1,77 @@
+import chalk from "chalk";
+export const SEVERITY_RANK = {
+    info: 0,
+    warning: 1,
+    critical: 2,
+};
+export function isValidSeverity(s) {
+    return s === "info" || s === "warning" || s === "critical";
+}
+export function filterIssuesByNamespace(issues, namespaces) {
+    if (namespaces === "all" || namespaces.length === 0)
+        return issues;
+    const set = new Set(namespaces);
+    return issues.filter((i) => set.has(i.namespace));
+}
+export function summarizeIssues(issues, podCount, nodeCount) {
+    return {
+        critical: issues.filter((i) => i.severity === "critical").length,
+        warning: issues.filter((i) => i.severity === "warning").length,
+        info: issues.filter((i) => i.severity === "info").length,
+        podCount,
+        nodeCount,
+    };
+}
+export function computeExitCode(summary, failOn) {
+    const threshold = SEVERITY_RANK[failOn];
+    const triggered = [];
+    if (SEVERITY_RANK.critical >= threshold && summary.critical > 0)
+        triggered.push("critical");
+    if (SEVERITY_RANK.warning >= threshold && summary.warning > 0)
+        triggered.push("warning");
+    if (SEVERITY_RANK.info >= threshold && summary.info > 0)
+        triggered.push("info");
+    if (triggered.length === 0) {
+        return { code: 0, reason: `no issues at or above fail-on=${failOn}` };
+    }
+    return { code: 1, reason: `fail-on=${failOn} threshold met (${triggered.join(", ")})` };
+}
+export function renderJson(report) {
+    return JSON.stringify({
+        ...report,
+        issues: report.issues.map((i) => ({
+            kind: i.kind,
+            severity: i.severity,
+            namespace: i.namespace,
+            resource: i.resource,
+            message: i.message,
+            details: i.details,
+        })),
+    }, null, 2);
+}
+export function renderHuman(report) {
+    const lines = [];
+    const nsLabel = report.namespaces === "all" ? "all" : report.namespaces.join(", ");
+    lines.push(`KubeAgent check — context: ${chalk.cyan(report.context)}  namespace: ${chalk.cyan(nsLabel)}`);
+    const { summary, durationMs } = report;
+    const headlineIcon = summary.critical > 0 ? chalk.red("✖") : summary.warning > 0 ? chalk.yellow("⚠") : chalk.green("✔");
+    const headlineMsg = summary.critical + summary.warning + summary.info === 0
+        ? "all clear"
+        : `${summary.critical} critical, ${summary.warning} warnings, ${summary.info} info`;
+    lines.push(`${headlineIcon} ${headlineMsg} ${chalk.dim(`(scanned ${summary.podCount} pods, ${summary.nodeCount} nodes in ${(durationMs / 1000).toFixed(1)}s)`)}`);
+    if (report.issues.length > 0) {
+        lines.push("");
+        for (const issue of report.issues) {
+            const sevColor = issue.severity === "critical" ? chalk.red : issue.severity === "warning" ? chalk.yellow : chalk.dim;
+            lines.push(`  ${sevColor(issue.severity.padEnd(8))}  ${issue.namespace}  ${chalk.dim(issue.kind.padEnd(16))}  ${issue.resource}  ${issue.message}`);
+        }
+    }
+    if (report.diagnosis) {
+        lines.push("");
+        lines.push(chalk.bold("Diagnosis:"));
+        lines.push(report.diagnosis.analysis);
+    }
+    lines.push("");
+    lines.push(chalk.dim(`Exit: ${report.exit.code} (${report.exit.reason})`));
+    return lines.join("\n");
+}

package/dist/check/run.js

@@ -0,0 +1,114 @@
+import chalk from "chalk";
+import { kubectl } from "../kubectl.js";
+import { runChecks } from "../monitor/index.js";
+import { computeExitCode, isValidSeverity, renderHuman, renderJson, summarizeIssues, } from "./index.js";
+class CheckError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+    }
+}
+function emitError(message, hint) {
+    process.stderr.write(chalk.red(`✖ ${message}\n`));
+    if (hint)
+        process.stderr.write(chalk.dim(`  ${hint}\n`));
+    process.exit(2);
+}
+export async function runCheck(opts) {
+    // --- flag validation ---
+    if (!isValidSeverity(opts.failOn)) {
+        emitError(`invalid --fail-on value "${opts.failOn}"`, "expected one of: info, warning, critical");
+    }
+    if (opts.format !== "human" && opts.format !== "json") {
+        emitError(`invalid --format value "${opts.format}"`, "expected one of: human, json");
+    }
+    const timeoutSec = Number.parseInt(opts.timeout, 10);
+    if (!Number.isFinite(timeoutSec) || timeoutSec <= 0) {
+        emitError(`invalid --timeout value "${opts.timeout}"`, "expected a positive integer (seconds)");
+    }
+    if (opts.diagnose && !process.env.KUBEAGENT_API_KEY) {
+        emitError("--diagnose requires KUBEAGENT_API_KEY env var", "set it as a CI secret, e.g. in GitHub Actions: env: { KUBEAGENT_API_KEY: ${{ secrets.KUBEAGENT_API_KEY }} }");
+    }
+    const failOn = opts.failOn;
+    const namespaces = opts.allNamespaces || !opts.namespace || opts.namespace.length === 0
+        ? "all"
+        : opts.namespace;
+    // --- run with timeout wrapper ---
+    const startedAt = Date.now();
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(new CheckError(`check timed out after ${timeoutSec}s`)), timeoutSec * 1000);
+    });
+    try {
+        const report = await Promise.race([
+            doCheck({ failOn, namespaces, format: opts.format, context: opts.context, diagnose: !!opts.diagnose, startedAt }),
+            timeoutPromise,
+        ]);
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        const output = opts.format === "json" ? renderJson(report) : renderHuman(report);
+        process.stdout.write(output + "\n");
+        process.exit(report.exit.code);
+    }
+    catch (err) {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        const message = err.message || "check failed";
+        if (err instanceof CheckError) {
+            emitError(message, err.hint);
+        }
+        emitError(message);
+    }
+}
+async function doCheck(args) {
+    const { failOn, namespaces, context, diagnose: shouldDiagnose, startedAt } = args;
+    const kubectlOpts = context ? { context } : {};
+    // Preflight: confirm the cluster is reachable so we fail fast with exit 2
+    // rather than a confusing kubectl error mid-scan.
+    try {
+        await kubectl(["cluster-info", "--request-timeout=5s"], kubectlOpts);
+    }
+    catch (err) {
+        throw new CheckError(`cannot reach cluster: ${err.message}`, "check your kubeconfig and --context flag");
+    }
+    // Resolve effective context name for the report (kubectl current-context
+    // is fine when --context not passed).
+    let effectiveContext = context ?? "(current-context)";
+    if (!context) {
+        try {
+            effectiveContext = (await kubectl(["config", "current-context"])).trim();
+        }
+        catch {
+            // non-fatal — keep the placeholder
+        }
+    }
+    // Scope kubectl queries to the requested namespaces so namespace-bound
+    // CI service accounts don't need cluster-wide list permissions.
+    const scope = namespaces === "all" ? undefined : { namespaces };
+    const summaryResult = await runChecks(kubectlOpts, true, scope);
+    const filteredIssues = summaryResult.issues;
+    const summary = summarizeIssues(filteredIssues, summaryResult.podCount, summaryResult.nodeCount);
+    let diagnosis = null;
+    if (shouldDiagnose && filteredIssues.length > 0) {
+        const { diagnose } = await import("../diagnoser/index.js");
+        const result = await diagnose(filteredIssues, "", context, {
+            autoFix: false,
+            noInteractive: true,
+            onApproval: async () => false,
+        });
+        diagnosis = { analysis: result.analysis };
+    }
+    const exit = computeExitCode(summary, failOn);
+    return {
+        version: 1,
+        context: effectiveContext,
+        namespaces,
+        scannedAt: new Date(startedAt).toISOString(),
+        durationMs: Date.now() - startedAt,
+        summary,
+        issues: filteredIssues,
+        diagnosis,
+        exit,
+    };
+}

package/dist/cli.js

@@ -170,6 +170,20 @@ program
     // Keep process alive
     await new Promise(() => { });
 });
+program
+    .command("check")
+    .description("One-shot cluster health check (CI-friendly, read-only by default)")
+    .option("-c, --context <context>", "Kubernetes context (defaults to kubeconfig current-context)")
+    .option("-n, --namespace <namespace>", "Limit scope to namespace (repeatable)", (val, prev) => [...(prev ?? []), val], undefined)
+    .option("--all-namespaces", "Scan all namespaces (default; overrides -n if both set)")
+    .option("--fail-on <severity>", "Exit non-zero on issues >= severity (info|warning|critical)", "critical")
+    .option("--format <fmt>", "Output format: human|json", "human")
+    .option("--diagnose", "Run LLM analysis on findings (requires KUBEAGENT_API_KEY)")
+    .option("--timeout <seconds>", "Max time for the check itself", "60")
+    .action(async (opts) => {
+    const { runCheck } = await import("./check/run.js");
+    await runCheck(opts);
+});
 program
     .command("diagnose <resource>")
     .description("One-shot diagnosis of a specific pod/deployment/service")
@@ -338,12 +352,21 @@ program
     .action(async (opts) => {
     const { detectApplications, formatApplicationsMarkdown } = await import("./detector/index.js");
     const { writeApplicationsKb, ensureKbDir } = await import("./kb/writer.js");
-    const contextName = opts.context ?? "default";
+    const { kubectl } = await import("./kubectl.js");
+    let contextName = opts.context;
+    if (!contextName) {
+        try {
+            contextName = (await kubectl(["config", "current-context"])).trim();
+        }
+        catch {
+            contextName = "default";
+        }
+    }
     const spinner = ora("Scanning cluster for OSS applications...").start();
     let result;
     try {
         result = await detectApplications({
-            context: opts.context,
+            context: contextName,
             noCache: opts.cache === false,
             onProgress: (step) => {
                 spinner.text = `Scanning cluster for OSS applications — ${step}...`;

package/dist/detector/sources.js

@@ -51,7 +51,7 @@ export async function fetchWorkloadCandidates(options) {
         all.push(...extractFromWorkload("DaemonSet", w));
     return all;
 }
-function decodeHelmRelease(b64) {
+export function decodeHelmRelease(b64) {
     try {
         // Helm v3 stores releases as base64(gzip(json)). When fetched via
         // `kubectl get secrets -o json`, the API server applies its own base64

package/dist/diagnoser/index.js

@@ -19,6 +19,32 @@ function truncateOutput(output) {
     const half = Math.floor(MAX_TOOL_OUTPUT_CHARS / 2);
     return output.slice(0, half) + "\n\n... [truncated] ...\n\n" + output.slice(-half);
 }
+/**
+ * Decide whether a tool call may execute, given the set of auto-safe actions and
+ * the (optional) approval callback.
+ *
+ * Security-critical: a missing/undefined `onApproval` MUST mean DENY for any
+ * action that is not in `safeActions`. In non-interactive mode the CLI passes no
+ * (or a deny-all) approver, and destructive remediation (e.g. scale-to-0) must
+ * never run unattended.
+ */
+export async function resolveApprovalDecision(toolName, params, safeActions, onApproval) {
+    // Safe (read-only or explicitly allowlisted) actions auto-execute.
+    if (safeActions.has(toolName))
+        return { execute: true };
+    // Non-safe action requires approval regardless of whether a callback exists.
+    if (!onApproval) {
+        return {
+            execute: false,
+            reason: "Action requires approval but no approver is available (non-interactive mode); denied. Propose a safe alternative or escalate to a human.",
+        };
+    }
+    const approved = await onApproval(toolName, params);
+    if (!approved) {
+        return { execute: false, reason: "Action denied by user. Propose an alternative." };
+    }
+    return { execute: true };
+}
 async function askUserQuestion(question, choices) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     return new Promise((resolve) => {
@@ -184,17 +210,17 @@ If it requires a risky action (rollback, delete, scale to zero), propose it but
                         });
                         continue;
                     }
-                    // Check if action requires approval
-                    if (!effectiveSafeActions.has(block.name) && options?.onApproval) {
-                        const approved = await options.onApproval(block.name, block.input);
-                        if (!approved) {
-                            toolResults.push({
-                                type: "tool_result",
-                                tool_use_id: block.id,
-                                content: "Action denied by user. Propose an alternative.",
-                            });
-                            continue;
-                        }
+                    // Check if action requires approval. A missing onApproval callback
+                    // (non-interactive mode) means DENY for any non-safe action — never
+                    // execute destructive remediation unattended.
+                    const decision = await resolveApprovalDecision(block.name, block.input, effectiveSafeActions, options?.onApproval);
+                    if (!decision.execute) {
+                        toolResults.push({
+                            type: "tool_result",
+                            tool_use_id: block.id,
+                            content: decision.reason,
+                        });
+                        continue;
                     }
                     try {
                         const result = await executor(block.input, { context: clusterContext });

package/dist/monitor/index.js

@@ -33,28 +33,59 @@ function deduplicateIssues(issues) {
         return true;
     });
 }
-export async function runChecks(options, withSummary) {
+export async function runChecks(options, withSummary, scope) {
     const allIssues = [];
-    // Get all pods across namespaces
-    const podList = (await kubectlJson(["get", "pods", "--all-namespaces"], options));
-    allIssues.push(...findPodIssues(podList));
-    // Get nodes
-    const nodeList = (await kubectlJson(["get", "nodes"], options));
+    const scoped = scope?.namespaces && scope.namespaces.length > 0 ? scope.namespaces : null;
+    // Pods: query per-namespace when scoped (so ns-bound service accounts
+    // don't need cluster-wide list-pods), otherwise all-namespaces.
+    let podCount = 0;
+    if (scoped) {
+        for (const ns of scoped) {
+            const list = (await kubectlJson(["get", "pods", "-n", ns], options).catch(() => ({ items: [] })));
+            allIssues.push(...findPodIssues(list));
+            podCount += list.items.length;
+        }
+    }
+    else {
+        const podList = (await kubectlJson(["get", "pods", "--all-namespaces"], options));
+        allIssues.push(...findPodIssues(podList));
+        podCount = podList.items.length;
+    }
+    // Nodes: cluster-scoped. Tolerate forbidden so ns-bound service accounts
+    // still get a useful pod-level report (node issues just don't apply to them).
+    const nodeList = (await kubectlJson(["get", "nodes"], options).catch(() => ({ items: [] })));
     allIssues.push(...findNodeIssues(nodeList));
-    // Get failed jobs
-    const jobList = (await kubectlJson(["get", "jobs", "--all-namespaces", "--field-selector=status.failed>0"], options).catch(() => ({ items: [] })));
-    allIssues.push(...findJobIssues(jobList));
+    // Failed jobs: per-namespace when scoped, otherwise all-namespaces.
+    if (scoped) {
+        for (const ns of scoped) {
+            const list = (await kubectlJson(["get", "jobs", "-n", ns, "--field-selector=status.failed>0"], options).catch(() => ({ items: [] })));
+            allIssues.push(...findJobIssues(list));
+        }
+    }
+    else {
+        const jobList = (await kubectlJson(["get", "jobs", "--all-namespaces", "--field-selector=status.failed>0"], options).catch(() => ({ items: [] })));
+        allIssues.push(...findJobIssues(jobList));
+    }
     const issues = deduplicateIssues(allIssues);
     if (!withSummary)
         return issues;
-    // Fetch namespace count (non-fatal)
-    const nsList = await kubectlJson(["get", "namespaces"], options)
-        .catch(() => ({ items: [] }));
+    // Namespace count: cluster-scoped, tolerate forbidden the same way as nodes.
+    // When the caller already specified namespaces, use that length so the
+    // summary reflects the requested scope, not the cluster's namespace total.
+    let namespaceCount;
+    if (scoped) {
+        namespaceCount = scoped.length;
+    }
+    else {
+        const nsList = await kubectlJson(["get", "namespaces"], options)
+            .catch(() => ({ items: [] }));
+        namespaceCount = nsList.items.length;
+    }
     return {
         issues,
-        podCount: podList.items.length,
+        podCount,
         nodeCount: nodeList.items.length,
-        namespaceCount: nsList.items.length,
+        namespaceCount,
     };
 }
 // How long a pod must be Pending before it's reported as an issue.

package/dist/notify/discord.js

@@ -1,3 +1,4 @@
+import { isSafeWebhookUrl } from "./ssrf-guard.js";
 const CRITICAL_COLOR = 0xe74c3c; // red
 const WARNING_COLOR = 0xf39c12; // yellow
 const INFO_COLOR = 0x3498db; // blue
@@ -32,15 +33,9 @@ function formatDiscordPayload(issues, clusterContext) {
     };
 }
 async function postToDiscord(webhookUrl, payload) {
-    try {
-        const url = new URL(webhookUrl);
-        if (!["https:", "http:"].includes(url.protocol)) {
-            console.error("Discord: invalid URL protocol");
-            return;
-        }
-    }
-    catch {
-        console.error("Discord: invalid webhook URL");
+    // SSRF guard: reject invalid URLs and hosts in private/loopback/metadata ranges.
+    if (!(await isSafeWebhookUrl(webhookUrl))) {
+        console.error("Discord: invalid or unsafe webhook URL (must be a public host)");
         return;
     }
     try {
@@ -48,6 +43,8 @@ async function postToDiscord(webhookUrl, payload) {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(payload),
+            // Don't follow redirects to internal addresses (see ssrf-guard).
+            redirect: "error",
             signal: AbortSignal.timeout(10_000),
         });
         if (!res.ok)

package/dist/notify/ssrf-guard.js

@@ -0,0 +1,150 @@
+import { promises as dns } from "node:dns";
+import { isIP } from "node:net";
+/**
+ * Minimal SSRF guard for the CLI. The CLI is a separate package from the server
+ * (they do not share runtime code — see CLAUDE.md), so this duplicates the core
+ * of `server/src/lib/ssrf-guard.ts`: reject user-supplied webhook URLs that point
+ * at private/loopback/link-local/ULA/metadata/CGNAT ranges, resolving hostnames
+ * (all addresses) to defeat the common DNS-rebinding case.
+ */
+function ipv4ToInt(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return null;
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const n = Number(part);
+        if (n > 255)
+            return null;
+        value = value * 256 + n;
+    }
+    return value >>> 0;
+}
+function inV4Range(ipInt, cidrBase, prefix) {
+    const base = ipv4ToInt(cidrBase);
+    if (base === null)
+        return false;
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    return (ipInt & mask) === (base & mask);
+}
+function isBlockedIPv4(ip) {
+    const n = ipv4ToInt(ip);
+    if (n === null)
+        return true;
+    return (inV4Range(n, "10.0.0.0", 8) ||
+        inV4Range(n, "172.16.0.0", 12) ||
+        inV4Range(n, "192.168.0.0", 16) ||
+        inV4Range(n, "127.0.0.0", 8) ||
+        inV4Range(n, "169.254.0.0", 16) ||
+        inV4Range(n, "100.64.0.0", 10) ||
+        inV4Range(n, "0.0.0.0", 8));
+}
+function ipv6ToGroups(ipRaw) {
+    let ip = ipRaw.toLowerCase();
+    const pct = ip.indexOf("%");
+    if (pct !== -1)
+        ip = ip.slice(0, pct);
+    let v4Tail = null;
+    const lastColon = ip.lastIndexOf(":");
+    const tail = lastColon === -1 ? "" : ip.slice(lastColon + 1);
+    if (tail.includes(".")) {
+        const v4 = ipv4ToInt(tail);
+        if (v4 === null)
+            return null;
+        v4Tail = [(v4 >>> 16) & 0xffff, v4 & 0xffff];
+        ip = ip.slice(0, lastColon + 1);
+    }
+    const halves = ip.split("::");
+    if (halves.length > 2)
+        return null;
+    const parseSide = (side) => {
+        if (side === "")
+            return [];
+        const out = [];
+        for (const h of side.split(":")) {
+            if (h === "" || !/^[0-9a-f]{1,4}$/.test(h))
+                return null;
+            out.push(parseInt(h, 16));
+        }
+        return out;
+    };
+    const left = parseSide(halves[0]);
+    if (left === null)
+        return null;
+    let groups;
+    if (halves.length === 2) {
+        const right = parseSide(halves[1]);
+        if (right === null)
+            return null;
+        const rightAll = v4Tail ? [...right, ...v4Tail] : right;
+        const fill = 8 - left.length - rightAll.length;
+        if (fill < 0)
+            return null;
+        groups = [...left, ...Array(fill).fill(0), ...rightAll];
+    }
+    else {
+        groups = v4Tail ? [...left, ...v4Tail] : left;
+    }
+    if (groups.length !== 8)
+        return null;
+    return groups;
+}
+function isBlockedIPv6(ip) {
+    const g = ipv6ToGroups(ip);
+    if (g === null)
+        return true;
+    if (g.slice(0, 7).every((x) => x === 0) && g[7] === 1)
+        return true; // ::1
+    if (g.every((x) => x === 0))
+        return true; // ::
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10
+    const isMapped = g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff;
+    const isCompat = g.slice(0, 6).every((x) => x === 0) && (g[6] !== 0 || g[7] > 1);
+    if (isMapped || isCompat) {
+        const v4 = `${(g[6] >> 8) & 0xff}.${g[6] & 0xff}.${(g[7] >> 8) & 0xff}.${g[7] & 0xff}`;
+        return isBlockedIPv4(v4);
+    }
+    return false;
+}
+function isBlockedIP(ip) {
+    const kind = isIP(ip);
+    if (kind === 4)
+        return isBlockedIPv4(ip);
+    if (kind === 6)
+        return isBlockedIPv6(ip);
+    return false;
+}
+/**
+ * Returns true if the URL is safe to fetch (public host, valid scheme).
+ * Returns false for invalid URLs or hosts in any blocked range.
+ */
+export async function isSafeWebhookUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return false;
+    }
+    if (!["https:", "http:"].includes(url.protocol))
+        return false;
+    let host = url.hostname;
+    if (host.startsWith("[") && host.endsWith("]"))
+        host = host.slice(1, -1);
+    if (isIP(host) !== 0)
+        return !isBlockedIP(host);
+    try {
+        const records = await dns.lookup(host, { all: true });
+        if (records.length === 0)
+            return false;
+        return records.every((r) => !isBlockedIP(r.address));
+    }
+    catch {
+        return false;
+    }
+}