@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/mcp-platform-config.mjs

@@ -7,6 +7,7 @@
  */
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { memoryPort } from "./home-namespace.mjs";
 
 const ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -31,18 +32,16 @@ function resolveTemplateObject(input, resolvedValues, fallback) {
 // A value is unsafe to write into a host MCP env block when it is an unresolved
 // `__NAME__` template or a 1Password `op://` reference. The op:// form must never
 // be written verbatim: a host that cannot run `op read` would pass the literal
-// reference to the child process, and writing it persists secret topology on disk.
+// reference to the child process, and writing it persists secret topology into a
+// host-readable MCP config file on disk (claude_desktop_config.json, OpenCode
+// settings) — a different sink from Construct's own audit JSONL, where recording
+// the ref (not the value) is the accepted design (secret-audit-wiring.mjs,
+// remediation plan Epic 6, construct-trxz.6).
 
 function isUnwritableEnvValue(value) {
   return typeof value !== "string" || value.includes("__") || value.startsWith("op://");
 }
 
-function stripUnresolvedValues(input) {
-  return Object.fromEntries(
-    Object.entries(input).filter(([, value]) => !isUnwritableEnvValue(value)),
-  );
-}
-
 function resolveArgs(args, resolvedValues) {
   return (args ?? []).map((arg) =>
     typeof arg === "string" ? resolveTemplateString(arg, resolvedValues) : arg,
@@ -61,26 +60,60 @@ const SECRET_REF = {
   opencode: (name) => `{env:${name}}`,
 };
 
-// Local/stdio MCP env is materialized as resolved values rather than host env-ref
-// forms. The SECRET_REF syntaxes above are verified for the remote `headers` field
-// only; whether Claude / VS Code / OpenCode expand a `${VAR}`-style reference inside
-// a stdio `env` block is unconfirmed, so the value-to-reference flip is deferred. The
-// secret is still kept off disk by the child inheriting resolved env from the parent
-// (config.env -> loadConstructEnv -> process.env); `stripUnresolvedValues` guarantees
-// no unresolved template or op:// reference is persisted here.
-
-function buildLocalEnvironment(mcpDef, resolvedValues) {
-  return stripUnresolvedValues(resolveTemplateObject(mcpDef.env ?? {}, resolvedValues));
+// A stdio MCP env value that is a whole-value secret template (`__NAME__` as the
+// entire string) is a credential carrier: emit the host's env-reference form so the
+// live value never lands on disk, exactly as the remote `headers` path does. Claude
+// Code (`${VAR}`, documented at code.claude.com/docs/en/mcp under "Environment
+// variable expansion in .mcp.json," confirmed 2026-07 for construct-trxz.12 --
+// expansion applies to the file format, independent of which host-config file
+// Construct currently targets; see construct-ranh) and OpenCode (`{env:VAR}`, live-
+// validated against the installed binary for construct-trxz.12) each expand their
+// reference syntax inside a stdio env block, and the child still inherits the
+// resolved env from the parent (config.env -> loadConstructEnv -> process.env) as a
+// backstop. A composed value (a URL with an embedded port template, a plain literal)
+// is not a secret and is materialized so the child receives the concrete string;
+// op:// references and unresolved embedded templates are stripped, never persisted.
+
+const WHOLE_SECRET_TEMPLATE = /^__([A-Z0-9_]+)__$/;
+
+// VS Code's own MCP configuration reference (code.visualstudio.com/docs/agents/
+// reference/mcp-configuration, confirmed 2026-07 for construct-trxz.12) documents only
+// `${workspaceFolder}`-style predefined variables and `${input:id}` prompts for
+// mcp.json — no `${env:VAR}` substitution is listed as supported. Writing `${env:NAME}`
+// into a VS Code stdio `env` block would hand the child process that literal,
+// unexpanded string instead of the credential, so VS Code's local/stdio env keeps the
+// Codex-style materialize-or-strip treatment (flipWholeSecret: false) rather than the
+// reference flip Claude and OpenCode confirm via their own documented `${VAR}` /
+// `{env:VAR}` expansion.
+
+function buildLocalEnvironment(mcpDef, resolvedValues, secretRef, { flipWholeSecret = true } = {}) {
+  const source = mcpDef.env ?? {};
+  const out = {};
+  for (const [key, raw] of Object.entries(source)) {
+    const whole = flipWholeSecret && typeof raw === "string" ? raw.match(WHOLE_SECRET_TEMPLATE) : null;
+    if (whole) {
+      out[key] = secretRef(whole[1]);
+      continue;
+    }
+    const materialized = typeof raw === "string" ? resolveTemplateString(raw, resolvedValues) : raw;
+    if (!isUnwritableEnvValue(materialized)) out[key] = materialized;
+  }
+  return out;
 }
 
 function buildRemoteHeaders(mcpDef, secretRef) {
   return resolveTemplateObject(mcpDef.headers ?? {}, {}, secretRef);
 }
 
+// The memory bridge URL is templated from MEMORY_PORT; when a caller does not supply
+// one (an entry built outside a populated config.env), fall back to the derived per-home
+// port from home-namespace, never the dead legacy 8765 literal that produced the
+// split-brain against the actually-allocated port.
+
 function withMemoryDefaults(id, values) {
   if (id !== "memory") return values;
   if (values.MEMORY_PORT) return values;
-  return { ...values, MEMORY_PORT: "8765" };
+  return { ...values, MEMORY_PORT: String(memoryPort()) };
 }
 
 // auth defaults to "oauth": remote MCP servers (e.g. GitHub's hosted server) are
@@ -106,7 +139,7 @@ export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}, { host = "c
     };
   }
 
-  const env = buildLocalEnvironment(mcpDef, values);
+  const env = buildLocalEnvironment(mcpDef, values, secretRef, { flipWholeSecret: host !== "vscode" });
   return {
     command: mcpDef.command,
     args: resolveArgs(mcpDef.args, values),
@@ -137,7 +170,7 @@ export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}, { auth =
     };
   }
 
-  const environment = buildLocalEnvironment(mcpDef, runtimeValues);
+  const environment = buildLocalEnvironment(mcpDef, runtimeValues, SECRET_REF.opencode);
   return {
     id: openCodeId,
     entry: {

package/lib/mode-capabilities.mjs

@@ -0,0 +1,109 @@
+/**
+ * Deployment-mode capability registry.
+ *
+ * Maps each deployment mode (solo / team / enterprise) to its declared capabilities
+ * and their current implementation status. This is the single authoritative source
+ * for what a mode promises versus what is actually wired up at runtime.
+ *
+ * Status values:
+ *   'implemented'     — fully wired; production-safe.
+ *   'stub'            — code path exists but returns null / falls back silently.
+ *   'not-implemented' — no code path exists yet; will throw or degrade if invoked.
+ *
+ * How to add a new capability:
+ *   1. Add an entry to the relevant mode array in CAPABILITY_REGISTRY below.
+ *   2. Set status to 'not-implemented' or 'stub' until the implementation lands.
+ *   3. Flip to 'implemented' in the same PR that wires the real code.
+ *   4. Add a CHANGELOG entry referencing this file and the wiring commit.
+ */
+
+export const CAPABILITY_REGISTRY = {
+  solo: [
+    { id: 'filesystem-queue', label: 'Filesystem task queue', status: 'implemented' },
+    { id: 'local-memory', label: 'Local memory', status: 'implemented' },
+    { id: 'embedded-lancedb', label: 'Embedded LanceDB vector store', status: 'implemented' },
+    { id: 'direct-mcp', label: 'Direct MCP dispatch', status: 'implemented' },
+  ],
+  team: [
+    { id: 'postgres-queue', label: 'Postgres task queue', status: 'implemented' },
+    { id: 'shared-memory', label: 'Shared memory store', status: 'stub' },
+    { id: 'worker-heartbeat', label: 'Worker identity and heartbeat', status: 'implemented' },
+    { id: 'docker-workers', label: 'Docker worker pool', status: 'not-implemented' },
+    { id: 'central-telemetry', label: 'Central telemetry', status: 'stub' },
+    { id: 'brokered-mcp', label: 'Brokered MCP dispatch', status: 'stub' },
+  ],
+  enterprise: [
+    { id: 'tenant-isolation', label: 'Tenant isolation', status: 'not-implemented' },
+    { id: 'rbac', label: 'RBAC/ABAC', status: 'not-implemented' },
+    { id: 'worker-heartbeat', label: 'Worker identity and heartbeat', status: 'implemented' },
+    { id: 'isolated-workers', label: 'Isolated worker containers', status: 'not-implemented' },
+    { id: 'signed-mcp-allowlists', label: 'Signed MCP allowlists', status: 'not-implemented' },
+    { id: 'mandatory-audit', label: 'Mandatory audit log', status: 'implemented' },
+  ],
+};
+
+// Returns the capability list for the given mode, or an empty array for unknown modes.
+
+export function getCapabilities(mode) {
+  return CAPABILITY_REGISTRY[mode] ?? [];
+}
+
+// Aggregates the capability list into a single readiness label.
+// 'fully-implemented' — every capability is 'implemented'.
+// 'degraded'          — at least one is 'stub' (and none are 'not-implemented').
+// 'unsupported'       — at least one is 'not-implemented'.
+
+export function getModeCapabilityStatus(mode) {
+  const caps = getCapabilities(mode);
+  if (caps.length === 0) return 'unsupported';
+  if (caps.some(c => c.status === 'not-implemented')) return 'unsupported';
+  if (caps.some(c => c.status === 'stub')) return 'degraded';
+  return 'fully-implemented';
+}
+
+// Returns capabilities whose status is not 'implemented'.
+
+export function getUnsupportedCapabilities(mode) {
+  return getCapabilities(mode).filter(c => c.status !== 'implemented');
+}
+
+// The three valid status values, as a constant so callers don't string-compare.
+
+export const CAPABILITY_STATUSES = ['implemented', 'stub', 'not-implemented'];
+
+// ADR-0057 (LMCP-A7) partitions enterprise capabilities beyond the three raw
+// statuses above into four status-output categories: 'active' (implemented),
+// 'fail-closed' (architecturally non-trivial — must hard-error rather than
+// degrade silently), 'later' (no near-term implementation path, no runtime
+// effect), and 'absent' (not advertised at all, the default for any id in
+// neither set). construct status and construct doctor both key off this so a
+// fail-closed gap is never visually or behaviorally confused with a later one.
+
+export const ENTERPRISE_FAIL_CLOSED_IDS = new Set(['tenant-isolation', 'isolated-workers']);
+export const ENTERPRISE_LATER_IDS = new Set(['rbac', 'signed-mcp-allowlists']);
+
+export function categorizeEnterpriseCapability(cap) {
+  if (cap.status === 'implemented') return 'active';
+  if (ENTERPRISE_FAIL_CLOSED_IDS.has(cap.id)) return 'fail-closed';
+  if (ENTERPRISE_LATER_IDS.has(cap.id)) return 'later';
+  return 'absent';
+}
+
+// Test-only injection: temporarily append a capability to the given mode(s) and return a cleanup fn.
+
+export function _injectCapabilityForTesting({ id, label = id, modes = {} }) {
+  const injected = [];
+  for (const [mode, status] of Object.entries(modes)) {
+    if (!CAPABILITY_REGISTRY[mode]) CAPABILITY_REGISTRY[mode] = [];
+    const entry = { id, label, status };
+    CAPABILITY_REGISTRY[mode].push(entry);
+    injected.push({ mode, entry });
+  }
+  return function cleanup() {
+    for (const { mode, entry } of injected) {
+      const arr = CAPABILITY_REGISTRY[mode];
+      const idx = arr.indexOf(entry);
+      if (idx !== -1) arr.splice(idx, 1);
+    }
+  };
+}

package/lib/model-router.mjs

@@ -23,6 +23,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { spawnSync } from "child_process";
 import { hasAnySecret } from "./providers/secret-resolver.mjs";
 import { isOllamaModelInstalled, toOllamaNativeModelId } from "./ollama/installed-models.mjs";
@@ -177,6 +178,21 @@ export function selectLocalEditorModel(candidates = []) {
  *   - `resolve`: Function that maps selected tier values to concrete model IDs.
  *
  * Families are consulted in order; the first match wins.
+ *
+ * FALLBACK CATALOG ONLY (construct-at27): these dated ids are the last-resort
+ * defaults when a tier is unconfigured — runtime call sites must prefer the
+ * user's configured/selected models and degrade gracefully when a catalog id
+ * has been retired by the provider; never treat an entry here as guaranteed
+ * to exist.
+ *
+ * OpenRouter's free-tier rate limit is enforced per account across every
+ * `:free`-suffixed model, not per model id — pinning a different `:free`
+ * model does not avoid a 429 by itself. The `:free` ids below are
+ * cross-checked against a live `GET https://openrouter.ai/api/v1/models`
+ * response (construct-r7bp) so at least one alternate candidate remains
+ * live if a specific model is retired or under its own provider-side quota;
+ * durable retry/fallback handling of the shared account limit is
+ * construct-5wkl's scope, not this catalog.
  */
 const PROVIDER_FAMILY_TIERS = [
   {
@@ -236,7 +252,7 @@ const PROVIDER_FAMILY_TIERS = [
     options: {
       reasoning: ["openrouter/deepseek/deepseek-r1", "openrouter/deepseek/deepseek-v3"],
       standard: ["openrouter/deepseek/deepseek-v3", "openrouter/deepseek/deepseek-r1"],
-      fast: ["openrouter/qwen/qwen3-coder:free", "openrouter/deepseek/deepseek-v3"],
+      fast: ["openrouter/qwen/qwen3-coder:free", "openrouter/meta-llama/llama-3.3-70b-instruct:free", "openrouter/deepseek/deepseek-v3"],
     },
   },
   {
@@ -246,12 +262,12 @@ const PROVIDER_FAMILY_TIERS = [
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "openrouter/qwen/qwen3-coder",
       standard: standard ?? "openrouter/qwen/qwen3-coder:free",
-      fast: fast ?? "openrouter/qwen/qwen2.5-coder-32b-instruct",
+      fast: fast ?? "openrouter/qwen/qwen-2.5-coder-32b-instruct",
     }),
     options: {
       reasoning: ["openrouter/qwen/qwen3-coder", "openrouter/qwen/qwen3-coder:free"],
-      standard: ["openrouter/qwen/qwen3-coder:free", "openrouter/qwen/qwen3-coder"],
-      fast: ["openrouter/qwen/qwen2.5-coder-32b-instruct", "openrouter/qwen/qwen3-coder:free"],
+      standard: ["openrouter/qwen/qwen3-coder:free", "openrouter/qwen/qwen3-next-80b-a3b-instruct:free", "openrouter/qwen/qwen3-coder"],
+      fast: ["openrouter/qwen/qwen-2.5-coder-32b-instruct", "openrouter/qwen/qwen3-coder:free"],
     },
   },
   {
@@ -313,7 +329,7 @@ const PROVIDER_FAMILY_TIERS = [
     }),
     options: {
       reasoning: ["openrouter/openrouter/free", "openrouter/qwen/qwen3-coder", "openrouter/deepseek/deepseek-r1"],
-      standard: ["openrouter/openrouter/free", "openrouter/qwen/qwen3-coder:free", "openrouter/google/gemini-2.0-flash-001"],
+      standard: ["openrouter/openrouter/free", "openrouter/qwen/qwen3-coder:free", "openrouter/openai/gpt-oss-120b:free", "openrouter/google/gemini-2.0-flash-001"],
       fast: ["openrouter/openrouter/free", "openrouter/qwen/qwen3-coder:free", "openrouter/meta-llama/llama-3.3-70b-instruct:free"],
     },
   },
@@ -413,8 +429,10 @@ function isProviderConfigured(familyId, env, { allowAmbient = true } = {}) {
   const varNames = PROVIDER_ENV_MAP[familyId];
   if (!varNames?.length) return false;
 
-  // Special case: Ollama on default port (no OLLAMA_BASE_URL needed)
-  if (familyId === 'ollama') {
+  // Special case: Ollama on default port (no OLLAMA_BASE_URL needed). Ambient-gated:
+  // a hermetic caller (allowAmbient: false — functional tests, credential-fallback
+  // resolution against a synthetic env) must not probe the machine's local daemon.
+  if (familyId === 'ollama' && allowAmbient) {
     try {
       const r = spawnSync('curl', ['-s', '--connect-timeout', '1', '-o', '/dev/null', '-w', '%{http_code}', 'http://localhost:11434/api/tags'], { encoding: 'utf8', timeout: 3000 });
       if (r.status === 0 && r.stdout?.trim() === '200') return true;
@@ -431,8 +449,9 @@ function isProviderConfigured(familyId, env, { allowAmbient = true } = {}) {
   if (hasAnySecret(varNames, { env, allowAmbient })) return true;
 
   // GitHub Copilot authenticates via OAuth rather than an API key: a stored
-  // device-flow credential, or a gh CLI session as a fallback, both count.
-  if (familyId === 'github-copilot') {
+  // device-flow credential, or a gh CLI session as a fallback, both count. Both
+  // checks read machine-local state outside `env`, so they are ambient-gated too.
+  if (familyId === 'github-copilot' && allowAmbient) {
     if (hasCopilotCredential()) return true;
     try {
       const r = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 3000 });
@@ -1282,6 +1301,20 @@ export function setModelWithTierInference(envPath, tier, modelId, registryModels
   return resolved;
 }
 
+// Optional operator-supplied tier defaults, resolved under the toolkit dir
+// (CX_TOOLKIT_DIR wins, else the installed package root). No active registry
+// ships — a starter template lives at specialists/org/models.json.example — so
+// an unconfigured machine degrades honestly (no implicit model defaults) rather
+// than resolving a model whose credentials may be absent. A dropped-in
+// models.json supplies registry-sourced tier defaults that an env pin overrides.
+
+const MODEL_REGISTRY_MODULE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function defaultModelRegistryPath(env = process.env) {
+  const root = env.CX_TOOLKIT_DIR || MODEL_REGISTRY_MODULE_ROOT;
+  return path.join(root, "specialists", "org", "models.json");
+}
+
 export function resolveModelTiers(options = {}) {
   const {
     env = process.env,

package/lib/models/catalog.mjs

@@ -11,9 +11,10 @@ import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import os from 'node:os';
 import { pollFreeModels } from '../model-free-selector.mjs';
-import { resolveFirstSecret } from '../providers/secret-resolver.mjs';
+import { resolveFirstSecret, hasAnySecret } from '../providers/secret-resolver.mjs';
 import { loadProjectConfig } from '../config/project-config.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
+import { loadManifestsFromDir, mergeManifests, resolveManifestDirs } from '../extensions/loader.mjs';
 
 export const MODEL_VISIBILITY_MODES = ['all_configured', 'tier_defaults', 'explicit'];
 
@@ -210,6 +211,44 @@ export function loadModelsCatalogContext({ cwd = process.cwd(), env = process.en
   return { modelsConfig, registryModels, liveModels };
 }
 
+// Bridge onto the unified extension registry (LMCP-B1/B4): model provider
+// families register `kind: 'model'` manifests under lib/extensions/manifests/
+// alongside data-source/queue/storage manifests, so `construct provider list`
+// can enumerate them through the same substrate. This is additive — it does
+// not replace PROVIDER_FAMILY_TIERS (lib/model-router.mjs), which still owns
+// tier resolution, live polling, and visibility filtering above.
+
+export const MODEL_MANIFEST_KIND = 'model';
+
+export function listModelProviderManifests({ rootDir = process.cwd(), homeDir } = {}) {
+  const dirs = resolveManifestDirs({ rootDir, homeDir });
+  const builtin = loadManifestsFromDir(dirs.builtin).manifests;
+  const user = loadManifestsFromDir(dirs.user).manifests;
+  const project = loadManifestsFromDir(dirs.project).manifests;
+  return mergeManifests(builtin, user, project).filter((m) => m.kind === MODEL_MANIFEST_KIND);
+}
+
+export function describeModelProviders({ rootDir = process.cwd(), homeDir, env = process.env, allowAmbient = true } = {}) {
+  return listModelProviderManifests({ rootDir, homeDir }).map((manifest) => {
+    const secretEnvKeys = Array.isArray(manifest.secretEnvKeys) ? manifest.secretEnvKeys : [];
+    const configured = secretEnvKeys.length === 0 || hasAnySecret(secretEnvKeys, { env, allowAmbient });
+    return {
+      id: manifest.id,
+      displayName: manifest.docs || manifest.id,
+      description: manifest.docs || null,
+      capabilities: Array.isArray(manifest.capabilities) ? manifest.capabilities : [],
+      kind: manifest.kind,
+      source: 'model-catalog',
+      health: {
+        ok: configured,
+        detail: configured
+          ? 'credentials configured'
+          : `missing env: ${secretEnvKeys.join(', ') || 'unknown'}`,
+      },
+    };
+  });
+}
+
 export function isModelVisible(modelId, {
   visibility = DEFAULT_MODELS_CONFIG.visibility,
   registryModels = {},

package/lib/net-guard.mjs

@@ -0,0 +1,247 @@
+/**
+ * lib/net-guard.mjs — shared SSRF / DNS-rebinding egress guard (LMCP-N7).
+ *
+ * Every outbound HTTP call Construct makes on behalf of a manifest, provider,
+ * or url-type MCP entry is attacker-influenced in its destination: a malicious
+ * manifest URL or a rebinding DNS record can point an otherwise-trusted call at
+ * a loopback or private-range service and pivot into the host. This guard is
+ * the single chokepoint that prevents that.
+ *
+ * Two properties, enforced together:
+ *   1. Address policy — the destination hostname is resolved and EVERY returned
+ *      address is classified; loopback, private, link-local (incl. cloud
+ *      metadata 169.254.169.254), CGNAT, and unspecified ranges are denied by
+ *      default. `allowPrivate: true` is the explicit, audited opt-out for
+ *      on-host/dev use.
+ *   2. Rebinding pinning — the address validated at check time is the exact
+ *      address the socket connects to. `resolveGuardedTarget` resolves ONCE and
+ *      returns a pinned IP; `guardedFetch` connects to that pinned IP with the
+ *      original hostname preserved as TLS servername + Host header, so a DNS
+ *      record that flips to a private address between check and connect can
+ *      never move the connection — the socket never re-resolves.
+ *
+ * The security decision lives entirely in the pure, network-free
+ * `classifyAddress` / `resolveGuardedTarget` (DNS is injectable), so the policy
+ * is unit-testable without a socket; `guardedFetch` is the thin I/O shell.
+ */
+
+import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
+import { lookup as dnsLookup } from 'node:dns';
+import { isIP } from 'node:net';
+import { promisify } from 'node:util';
+import { gunzipSync, inflateSync, brotliDecompressSync } from 'node:zlib';
+
+const dnsLookupAll = promisify(dnsLookup);
+
+export const DEFAULT_ALLOWED_SCHEMES = Object.freeze(['https:', 'http:']);
+
+/** Named egress-policy rejection; `.reason` is a stable machine tag. */
+export class SsrfBlockedError extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.name = 'SsrfBlockedError';
+    this.reason = reason;
+  }
+}
+
+function ipv4ToInt(ip) {
+  const parts = ip.split('.').map((n) => Number(n));
+  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+  return ((parts[0] << 24) >>> 0) + (parts[1] << 16) + (parts[2] << 8) + parts[3];
+}
+
+function inCidr4(ipInt, baseIp, prefix) {
+  const base = ipv4ToInt(baseIp);
+  const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+  return (ipInt & mask) === (base & mask);
+}
+
+const BLOCKED_V4 = [
+  ['0.0.0.0', 8, 'unspecified'],
+  ['10.0.0.0', 8, 'private-address'],
+  ['100.64.0.0', 10, 'cgnat'],
+  ['127.0.0.0', 8, 'loopback'],
+  ['169.254.0.0', 16, 'link-local'],
+  ['172.16.0.0', 12, 'private-address'],
+  ['192.0.0.0', 24, 'ietf-protocol'],
+  ['192.168.0.0', 16, 'private-address'],
+  ['198.18.0.0', 15, 'benchmark'],
+  ['224.0.0.0', 4, 'multicast'],
+  ['240.0.0.0', 4, 'reserved'],
+];
+
+/**
+ * Classify a raw IP literal. Returns a stable reason tag when the address is in
+ * a range that must not be reached from an attacker-influenced URL, or null
+ * when the address is a routable public address.
+ *
+ * @param {string} ip
+ * @returns {string|null}
+ */
+export function classifyAddress(ip) {
+  const family = isIP(ip);
+  if (family === 4) {
+    const asInt = ipv4ToInt(ip);
+    if (asInt === null) return 'unparseable';
+    for (const [base, prefix, reason] of BLOCKED_V4) {
+      if (inCidr4(asInt, base, prefix)) return reason;
+    }
+    return null;
+  }
+  if (family === 6) {
+    const norm = ip.toLowerCase().replace(/^\[|\]$/g, '');
+    if (norm === '::1') return 'loopback';
+    if (norm === '::' ) return 'unspecified';
+    if (norm.startsWith('fe80')) return 'link-local';
+    if (norm.startsWith('fc') || norm.startsWith('fd')) return 'unique-local';
+    // IPv4-mapped (::ffff:a.b.c.d) is classified on its embedded v4 address.
+    const mapped = norm.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped) return classifyAddress(mapped[1]);
+    return null;
+  }
+  return 'not-an-ip';
+}
+
+/**
+ * Validate a URL's scheme + host and resolve its hostname to a single pinned,
+ * policy-checked address. Pure with respect to the network: DNS is injected via
+ * `lookup`. Throws SsrfBlockedError on any violation.
+ *
+ * @param {string} rawUrl
+ * @param {object} [opts]
+ * @param {(hostname: string) => Promise<Array<{address: string, family: number}>>} [opts.lookup]
+ * @param {boolean} [opts.allowPrivate] - permit private/loopback ranges (audited opt-out)
+ * @param {string[]} [opts.allowedSchemes]
+ * @returns {Promise<{ url: URL, pinnedAddress: string, family: number, port: number, servername: string }>}
+ */
+export async function resolveGuardedTarget(rawUrl, opts = {}) {
+  const { allowPrivate = false, allowedSchemes = DEFAULT_ALLOWED_SCHEMES } = opts;
+  const lookup = opts.lookup ?? ((hostname) => dnsLookupAll(hostname, { all: true }));
+
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new SsrfBlockedError(`net-guard: not a valid URL: ${String(rawUrl).slice(0, 120)}`, 'invalid-url');
+  }
+
+  if (!allowedSchemes.includes(url.protocol)) {
+    throw new SsrfBlockedError(`net-guard: scheme '${url.protocol}' is not allowed`, 'blocked-scheme');
+  }
+
+  const hostname = url.hostname.replace(/^\[|\]$/g, '');
+
+  // A URL that already carries an IP literal skips DNS but is still classified —
+  // http://127.0.0.1 must be blocked exactly like a hostname resolving to it.
+  const literalFamily = isIP(hostname);
+  let addresses;
+  if (literalFamily) {
+    addresses = [{ address: hostname, family: literalFamily }];
+  } else {
+    addresses = await lookup(hostname);
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+      throw new SsrfBlockedError(`net-guard: '${hostname}' did not resolve to any address`, 'no-address');
+    }
+  }
+
+  // ALL resolved addresses must pass — a hostname that returns one public and
+  // one private address is rejected, never partially trusted.
+  for (const { address } of addresses) {
+    if (allowPrivate) continue;
+    const reason = classifyAddress(address);
+    if (reason) {
+      throw new SsrfBlockedError(`net-guard: '${hostname}' resolves to a blocked address (${address}: ${reason})`, reason);
+    }
+  }
+
+  const pinned = addresses[0];
+  const port = url.port ? Number(url.port) : (url.protocol === 'https:' ? 443 : 80);
+  return { url, pinnedAddress: pinned.address, family: pinned.family, port, servername: hostname };
+}
+
+function decodeBody(buffer, encoding) {
+  if (!buffer.length) return buffer;
+  try {
+    if (encoding === 'gzip') return gunzipSync(buffer);
+    if (encoding === 'deflate') return inflateSync(buffer);
+    if (encoding === 'br') return brotliDecompressSync(buffer);
+  } catch {
+    return buffer;
+  }
+  return buffer;
+}
+
+function makeResponse({ statusCode, headers, bodyBuffer, url }) {
+  const decoded = decodeBody(bodyBuffer, String(headers['content-encoding'] ?? '').toLowerCase());
+  const headerMap = new Map(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), Array.isArray(v) ? v.join(', ') : v]));
+  return {
+    status: statusCode,
+    ok: statusCode >= 200 && statusCode < 300,
+    url,
+    headers: { get: (name) => headerMap.get(String(name).toLowerCase()) ?? null },
+    async text() { return decoded.toString('utf8'); },
+    async json() { return JSON.parse(decoded.toString('utf8') || 'null'); },
+  };
+}
+
+/**
+ * fetch-compatible egress call that enforces the guard and connects to the
+ * pinned, validated address (rebinding-proof). Follows redirects manually,
+ * re-validating every hop through the same guard. Returns a minimal Response
+ * ({ status, ok, headers.get, text, json }) covering what the provider
+ * transports use.
+ *
+ * @param {string} rawUrl
+ * @param {{ method?: string, headers?: Record<string,string>, body?: string }} [init]
+ * @param {object} [opts] - forwarded to resolveGuardedTarget, plus maxRedirects
+ * @returns {Promise<object>}
+ */
+export async function guardedFetch(rawUrl, init = {}, opts = {}) {
+  const maxRedirects = opts.maxRedirects ?? 5;
+  let currentUrl = rawUrl;
+
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    const target = await resolveGuardedTarget(currentUrl, opts);
+    const res = await requestPinned(target, init);
+
+    if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+      currentUrl = new URL(res.headers.location, target.url).href;
+      if (res.statusCode === 303) { init = { ...init, method: 'GET', body: undefined }; }
+      continue;
+    }
+    return makeResponse({ statusCode: res.statusCode, headers: res.headers, bodyBuffer: res.bodyBuffer, url: target.url.href });
+  }
+  throw new SsrfBlockedError(`net-guard: exceeded ${maxRedirects} redirects for ${rawUrl}`, 'too-many-redirects');
+}
+
+function requestPinned(target, init) {
+  const { url, pinnedAddress, family, port, servername } = target;
+  const doRequest = url.protocol === 'https:' ? httpsRequest : httpRequest;
+
+  // The socket connects to the pinned IP; the hostname survives only as TLS
+  // servername + Host header. The custom lookup guarantees the pinned address
+  // is the only one the agent can dial — DNS is never consulted again here.
+  const pinnedLookup = (_hostname, _options, cb) => cb(null, pinnedAddress, family);
+
+  const options = {
+    method: init.method ?? 'GET',
+    host: servername,
+    port,
+    path: `${url.pathname}${url.search}`,
+    headers: { Host: url.host, ...(init.headers ?? {}) },
+    servername,
+    lookup: pinnedLookup,
+  };
+
+  return new Promise((resolve, reject) => {
+    const req = doRequest(options, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve({ statusCode: res.statusCode, headers: res.headers, bodyBuffer: Buffer.concat(chunks) }));
+    });
+    req.on('error', reject);
+    if (init.body) req.write(init.body);
+    req.end();
+  });
+}