@manifest-network/manifest-agent-core 0.9.0

package/dist/internals/find-sku-uuid.d.ts

@@ -0,0 +1,40 @@
+import { CosmosClientManager } from "@manifest-network/manifest-mcp-core";
+
+//#region src/internals/find-sku-uuid.d.ts
+/**
+ * Resolve a SKU-tier name (e.g. `'docker-micro'`, `'small'`) to its on-chain
+ * UUID + the UUID of its publishing provider. Mirrors fred's internal
+ * `findSkuUuid` helper at `packages/fred/src/tools/deployApp.ts:L62`.
+ *
+ * Used by `deploy-app.ts`'s pre-broadcast fee-estimation step (the
+ * `cosmosEstimateFee('billing', 'create-lease', ...)` call needs the SKU
+ * UUID as part of the item-arg string format `sku-uuid:quantity[:service-name]`).
+ *
+ * **Why duplicated (not imported from fred):** fred's `findSkuUuid` is an
+ * internal helper, not re-exported from `packages/fred/src/index.ts`.
+ * Per team-lead-2's Path 2 verdict (vs Path 1 export-from-fred), the
+ * helper is duplicated here because:
+ *
+ *   1. Stateless query helper — zero cross-instance drift risk
+ *      (unlike `AuthTimestampTracker` which has cross-call state).
+ *   2. fred's barrel deliberately keeps this helper internal; making it
+ *      public would be an architectural decision, not an oversight fix.
+ *   3. The duplicated logic uses only already-exported core symbols
+ *      (`createPagination`, `MAX_PAGE_LIMIT`, `ManifestMCPError`).
+ *   4. Drift bounded by the shared `@manifest-network/manifestjs@2.4.1`
+ *      proto pin — both fred and agent-core import the same SKU types.
+ *
+ * Throws `ManifestMCPError(QUERY_FAILED)` when no active SKU matches
+ * the requested `size`. Error message includes the available SKU names
+ * for caller-side debugging.
+ */
+interface SkuResolution {
+  /** On-chain SKU UUID. Used in `create-lease` item-arg construction. */
+  readonly skuUuid: string;
+  /** Publishing provider's UUID. Required by some downstream chain queries. */
+  readonly providerUuid: string;
+}
+declare function findSkuUuid(clientManager: CosmosClientManager, size: string): Promise<SkuResolution>;
+//#endregion
+export { SkuResolution, findSkuUuid };
+//# sourceMappingURL=find-sku-uuid.d.ts.map

package/dist/internals/find-sku-uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-sku-uuid.d.ts","names":[],"sources":["../../src/internals/find-sku-uuid.ts"],"mappings":";;;;;AAmCA;;;;;AAOA;;;;;;;;;;;;;;;;;;;;UAPiB,aAAA;;WAEN,OAAA;;WAEA,YAAA;AAAA;AAAA,iBAGW,WAAA,CACpB,aAAA,EAAe,mBAAA,EACf,IAAA,WACC,OAAA,CAAQ,aAAA"}

package/dist/internals/find-sku-uuid.js

@@ -0,0 +1,20 @@
+import { MAX_PAGE_LIMIT, ManifestMCPError, ManifestMCPErrorCode, createPagination } from "@manifest-network/manifest-mcp-core";
+//#region src/internals/find-sku-uuid.ts
+async function findSkuUuid(clientManager, size) {
+	const queryClient = await clientManager.getQueryClient();
+	const pagination = createPagination(MAX_PAGE_LIMIT);
+	const result = await queryClient.liftedinit.sku.v1.sKUs({
+		activeOnly: true,
+		pagination
+	});
+	for (const sku of result.skus) if (sku.name === size) return {
+		skuUuid: sku.uuid,
+		providerUuid: sku.providerUuid
+	};
+	const available = result.skus.map((s) => s.name);
+	throw new ManifestMCPError(ManifestMCPErrorCode.QUERY_FAILED, `SKU tier "${size}" not found. Available: ${available.join(", ")}`);
+}
+//#endregion
+export { findSkuUuid };
+
+//# sourceMappingURL=find-sku-uuid.js.map

package/dist/internals/find-sku-uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-sku-uuid.js","names":[],"sources":["../../src/internals/find-sku-uuid.ts"],"sourcesContent":["import {\n  type CosmosClientManager,\n  createPagination,\n  MAX_PAGE_LIMIT,\n  ManifestMCPError,\n  ManifestMCPErrorCode,\n} from '@manifest-network/manifest-mcp-core';\n\n/**\n * Resolve a SKU-tier name (e.g. `'docker-micro'`, `'small'`) to its on-chain\n * UUID + the UUID of its publishing provider. Mirrors fred's internal\n * `findSkuUuid` helper at `packages/fred/src/tools/deployApp.ts:L62`.\n *\n * Used by `deploy-app.ts`'s pre-broadcast fee-estimation step (the\n * `cosmosEstimateFee('billing', 'create-lease', ...)` call needs the SKU\n * UUID as part of the item-arg string format `sku-uuid:quantity[:service-name]`).\n *\n * **Why duplicated (not imported from fred):** fred's `findSkuUuid` is an\n * internal helper, not re-exported from `packages/fred/src/index.ts`.\n * Per team-lead-2's Path 2 verdict (vs Path 1 export-from-fred), the\n * helper is duplicated here because:\n *\n *   1. Stateless query helper — zero cross-instance drift risk\n *      (unlike `AuthTimestampTracker` which has cross-call state).\n *   2. fred's barrel deliberately keeps this helper internal; making it\n *      public would be an architectural decision, not an oversight fix.\n *   3. The duplicated logic uses only already-exported core symbols\n *      (`createPagination`, `MAX_PAGE_LIMIT`, `ManifestMCPError`).\n *   4. Drift bounded by the shared `@manifest-network/manifestjs@2.4.1`\n *      proto pin — both fred and agent-core import the same SKU types.\n *\n * Throws `ManifestMCPError(QUERY_FAILED)` when no active SKU matches\n * the requested `size`. Error message includes the available SKU names\n * for caller-side debugging.\n */\nexport interface SkuResolution {\n  /** On-chain SKU UUID. Used in `create-lease` item-arg construction. */\n  readonly skuUuid: string;\n  /** Publishing provider's UUID. Required by some downstream chain queries. */\n  readonly providerUuid: string;\n}\n\nexport async function findSkuUuid(\n  clientManager: CosmosClientManager,\n  size: string,\n): Promise<SkuResolution> {\n  const queryClient = await clientManager.getQueryClient();\n  const pagination = createPagination(MAX_PAGE_LIMIT);\n  const result = await queryClient.liftedinit.sku.v1.sKUs({\n    activeOnly: true,\n    pagination,\n  });\n\n  for (const sku of result.skus) {\n    if (sku.name === size) {\n      return { skuUuid: sku.uuid, providerUuid: sku.providerUuid };\n    }\n  }\n\n  const available = result.skus.map((s) => s.name);\n  throw new ManifestMCPError(\n    ManifestMCPErrorCode.QUERY_FAILED,\n    `SKU tier \"${size}\" not found. Available: ${available.join(', ')}`,\n  );\n}\n"],"mappings":";;AA0CA,eAAsB,YACpB,eACA,MACwB;CACxB,MAAM,cAAc,MAAM,cAAc,gBAAgB;CACxD,MAAM,aAAa,iBAAiB,eAAe;CACnD,MAAM,SAAS,MAAM,YAAY,WAAW,IAAI,GAAG,KAAK;EACtD,YAAY;EACZ;EACD,CAAC;AAEF,MAAK,MAAM,OAAO,OAAO,KACvB,KAAI,IAAI,SAAS,KACf,QAAO;EAAE,SAAS,IAAI;EAAM,cAAc,IAAI;EAAc;CAIhE,MAAM,YAAY,OAAO,KAAK,KAAK,MAAM,EAAE,KAAK;AAChD,OAAM,IAAI,iBACR,qBAAqB,cACrB,aAAa,KAAK,0BAA0B,UAAU,KAAK,KAAK,GACjE"}

package/dist/internals/format-success.d.ts

@@ -0,0 +1,35 @@
+import { RunningEndpoint } from "./connection.js";
+
+//#region src/internals/format-success.d.ts
+/** Deploy response shape consumed by `formatSuccess`. Subset of fred's `mcp__manifest-fred__deploy_app` response. */
+interface DeployResponse {
+  /** Chain lease state — int (raw) or `LEASE_STATE_*` string (codec). */
+  state?: number | string;
+  /** Provider UUID — rendered as-is (catalog has no friendly-name field). */
+  provider_uuid?: string;
+  /** Custom domain attached to the lease item; populated when set-domain confirmed. */
+  custom_domain?: string;
+  /** Provider connection payload — walked by `connection.ts`. */
+  connection?: unknown;
+  /**
+   * Top-level URL — legacy fallback when provider reports
+   * `connection.host` / `connection.ports` shape rather than
+   * `connection.instances`. Used when no FQDN can be extracted from
+   * `connection`. Defensive: `classify-deploy-response.ts:43-51,76-80`
+   * already defends against the same legacy shape; mirroring here keeps
+   * the renderer consistent with the classifier so a fred response of
+   * `{ url: 'https://app.example.com/' }` renders an Ingress line
+   * rather than `(none …)`.
+   */
+  url?: string;
+}
+interface FormatSuccessInput {
+  /** Validated lease UUID (RFC 4122 v1-v5). */
+  leaseUuid: string;
+  /** Deploy response from `deploy_app` (or equivalent atomic broadcast). */
+  deployResponse: DeployResponse;
+}
+declare function formatSuccess(input: FormatSuccessInput): string;
+//#endregion
+export { DeployResponse, FormatSuccessInput, type RunningEndpoint, formatSuccess };
+//# sourceMappingURL=format-success.d.ts.map

package/dist/internals/format-success.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-success.d.ts","names":[],"sources":["../../src/internals/format-success.ts"],"mappings":";;;;UA4CiB,cAAA;EAAA;EAEf,KAAA;;EAEA,aAAA;EAFA;EAIA,aAAA;EAAA;EAEA,UAAA;EAWA;;;AAGF;;;;;;;EAHE,GAAA;AAAA;AAAA,UAGe,kBAAA;EAOY;EAL3B,SAAA;EAKmC;EAHnC,cAAA,EAAgB,cAAA;AAAA;AAAA,iBAGF,aAAA,CAAc,KAAA,EAAO,kBAAA"}

package/dist/internals/format-success.js

@@ -0,0 +1,80 @@
+import { decode } from "./lease-state.js";
+import { extractRunningEndpoints, formatEndpointAsIngress, normalizeFredUrl } from "./connection.js";
+//#region src/internals/format-success.ts
+/**
+* Render the user-facing "Deployed." block for a successful `deployApp` run.
+*
+* Takes `lease-uuid` and `deploy_response` via the typed `FormatSuccessInput`.
+*
+* Output is plain text suitable for direct chat display. Designed to be
+* printed verbatim by `deployApp` (and downstream renderers) — no
+* paraphrasing or surrounding prose.
+*
+* **Lease-state decoding:** `deploy_response.state` may be an integer (raw
+* chain emit) or a `LEASE_STATE_*` string (codec.toJSON form). Both flow
+* through `lease-state.ts:decode`. Unknown values render as
+* `UNKNOWN(<raw>)` so the raw remains visible.
+*
+* **Multi-instance / multi-service stacks** emit `Ingresses:` followed by
+* one bare FQDN per UNIQUE FQDN across running instances. Instances
+* sharing an FQDN (e.g. replicas behind one subdomain) are deduped by
+* `extractRunningEndpoints`.
+*
+* **Custom-domain line** is emitted BEFORE the Ingress block when the
+* deploy response carries a `custom_domain` (the set-domain tx confirmed
+* alongside create-lease). The "(provisioning)" qualifier reflects that
+* the chain tx confirmed but the provider may still be issuing the cert.
+*
+* **Provider rendering**: the CJS once attempted to resolve a friendly
+* provider name via `browse_catalog` and dropped it when upstream's
+* catalog shape carried no `name` field. The TS port keeps the
+* `provider_uuid` rendering for the same reason — if upstream later adds
+* `name`, restore via a thin helper.
+*/
+/** RFC 4122 UUID — 36 chars, hex + 4 hyphens, lowercase or upper. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function formatSuccess(input) {
+	if (!UUID_RE.test(input.leaseUuid)) throw new TypeError(`formatSuccess: leaseUuid must be a UUID; got "${input.leaseUuid}"`);
+	if (input.deployResponse === null || typeof input.deployResponse !== "object") throw new TypeError("formatSuccess: deployResponse must be a non-null object");
+	const dr = input.deployResponse;
+	const providerName = typeof dr.provider_uuid === "string" && dr.provider_uuid.length > 0 ? dr.provider_uuid : "(unknown)";
+	const stateName = decodeStateName(dr.state);
+	const ingresses = extractRunningEndpoints(dr.connection).map(formatEndpointAsIngress).filter((s) => typeof s === "string" && s.length > 0);
+	const hasIngress = ingresses.length > 0 || typeof dr.url === "string" && dr.url.length > 0;
+	const lines = [
+		"Deployed.",
+		`  Provider:      ${providerName}`,
+		`  Lease UUID:    ${input.leaseUuid}`,
+		`  Lease Status:  ${stateName}`
+	];
+	if (typeof dr.custom_domain === "string" && dr.custom_domain.length > 0) {
+		lines.push(`  Custom domain (provisioning):  https://${dr.custom_domain}/`);
+		lines.push(hasIngress ? "    — TLS may take a few minutes; the Ingress URL below works immediately." : "    — TLS may take a few minutes.");
+	}
+	if (ingresses.length === 0) if (typeof dr.url === "string" && dr.url.length > 0) lines.push(`  Ingress:       ${normalizeFredUrl(dr.url)}`);
+	else lines.push("  Ingress:       (none — service is internal or no FQDN reported)");
+	else if (ingresses.length === 1) lines.push(`  Ingress:       ${ingresses[0]}`);
+	else {
+		lines.push("  Ingresses:");
+		for (const fqdn of ingresses) lines.push(`    - ${fqdn}`);
+	}
+	lines.push("");
+	lines.push(`For logs / status:  /manifest-agent:troubleshoot-deployment ${input.leaseUuid}`);
+	return lines.join("\n");
+}
+/**
+* Return the user-facing form of a lease state. The `LEASE_STATE_` prefix
+* is stripped for display (e.g. `LEASE_STATE_ACTIVE` → `ACTIVE`). Unknown
+* decodes render as `UNKNOWN(<raw>)` so the raw remains visible; absent
+* state renders as `(unknown)`.
+*/
+function decodeStateName(state) {
+	if (state === void 0) return "(unknown)";
+	const canonical = decode(state);
+	if (canonical !== void 0) return canonical.slice(12);
+	return `UNKNOWN(${String(state)})`;
+}
+//#endregion
+export { formatSuccess };
+
+//# sourceMappingURL=format-success.js.map

package/dist/internals/format-success.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-success.js","names":["decodeLeaseState"],"sources":["../../src/internals/format-success.ts"],"sourcesContent":["import {\n  extractRunningEndpoints,\n  formatEndpointAsIngress,\n  normalizeFredUrl,\n  type RunningEndpoint,\n} from './connection.js';\nimport { decode as decodeLeaseState } from './lease-state.js';\n\n/**\n * Render the user-facing \"Deployed.\" block for a successful `deployApp` run.\n *\n * Takes `lease-uuid` and `deploy_response` via the typed `FormatSuccessInput`.\n *\n * Output is plain text suitable for direct chat display. Designed to be\n * printed verbatim by `deployApp` (and downstream renderers) — no\n * paraphrasing or surrounding prose.\n *\n * **Lease-state decoding:** `deploy_response.state` may be an integer (raw\n * chain emit) or a `LEASE_STATE_*` string (codec.toJSON form). Both flow\n * through `lease-state.ts:decode`. Unknown values render as\n * `UNKNOWN(<raw>)` so the raw remains visible.\n *\n * **Multi-instance / multi-service stacks** emit `Ingresses:` followed by\n * one bare FQDN per UNIQUE FQDN across running instances. Instances\n * sharing an FQDN (e.g. replicas behind one subdomain) are deduped by\n * `extractRunningEndpoints`.\n *\n * **Custom-domain line** is emitted BEFORE the Ingress block when the\n * deploy response carries a `custom_domain` (the set-domain tx confirmed\n * alongside create-lease). The \"(provisioning)\" qualifier reflects that\n * the chain tx confirmed but the provider may still be issuing the cert.\n *\n * **Provider rendering**: the CJS once attempted to resolve a friendly\n * provider name via `browse_catalog` and dropped it when upstream's\n * catalog shape carried no `name` field. The TS port keeps the\n * `provider_uuid` rendering for the same reason — if upstream later adds\n * `name`, restore via a thin helper.\n */\n\n/** RFC 4122 UUID — 36 chars, hex + 4 hyphens, lowercase or upper. */\nconst UUID_RE =\n  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/** Deploy response shape consumed by `formatSuccess`. Subset of fred's `mcp__manifest-fred__deploy_app` response. */\nexport interface DeployResponse {\n  /** Chain lease state — int (raw) or `LEASE_STATE_*` string (codec). */\n  state?: number | string;\n  /** Provider UUID — rendered as-is (catalog has no friendly-name field). */\n  provider_uuid?: string;\n  /** Custom domain attached to the lease item; populated when set-domain confirmed. */\n  custom_domain?: string;\n  /** Provider connection payload — walked by `connection.ts`. */\n  connection?: unknown;\n  /**\n   * Top-level URL — legacy fallback when provider reports\n   * `connection.host` / `connection.ports` shape rather than\n   * `connection.instances`. Used when no FQDN can be extracted from\n   * `connection`. Defensive: `classify-deploy-response.ts:43-51,76-80`\n   * already defends against the same legacy shape; mirroring here keeps\n   * the renderer consistent with the classifier so a fred response of\n   * `{ url: 'https://app.example.com/' }` renders an Ingress line\n   * rather than `(none …)`.\n   */\n  url?: string;\n}\n\nexport interface FormatSuccessInput {\n  /** Validated lease UUID (RFC 4122 v1-v5). */\n  leaseUuid: string;\n  /** Deploy response from `deploy_app` (or equivalent atomic broadcast). */\n  deployResponse: DeployResponse;\n}\n\nexport function formatSuccess(input: FormatSuccessInput): string {\n  if (!UUID_RE.test(input.leaseUuid)) {\n    throw new TypeError(\n      `formatSuccess: leaseUuid must be a UUID; got \"${input.leaseUuid}\"`,\n    );\n  }\n  if (\n    input.deployResponse === null ||\n    typeof input.deployResponse !== 'object'\n  ) {\n    throw new TypeError(\n      'formatSuccess: deployResponse must be a non-null object',\n    );\n  }\n\n  const dr = input.deployResponse;\n  const providerName =\n    typeof dr.provider_uuid === 'string' && dr.provider_uuid.length > 0\n      ? dr.provider_uuid\n      : '(unknown)';\n  const stateName = decodeStateName(dr.state);\n  const endpoints = extractRunningEndpoints(dr.connection);\n  const ingresses = endpoints\n    .map(formatEndpointAsIngress)\n    .filter((s): s is string => typeof s === 'string' && s.length > 0);\n  // Copilot review fix (PR #58 r3250192778): the custom-domain block's\n  // TLS note (\\\"the Ingress URL below works immediately\\\") promises a\n  // URL that may not exist when `connection.instances` is empty AND\n  // there's no top-level `url`. Compute ingress availability up-front\n  // so the custom-domain block can branch its second line accordingly.\n  const hasIngress =\n    ingresses.length > 0 || (typeof dr.url === 'string' && dr.url.length > 0);\n\n  const lines: string[] = [\n    'Deployed.',\n    `  Provider:      ${providerName}`,\n    `  Lease UUID:    ${input.leaseUuid}`,\n    `  Lease Status:  ${stateName}`,\n  ];\n\n  // Custom-domain block — chain tx confirmed, provider may still be\n  // provisioning. Present BEFORE Ingress so the user sees the requested\n  // endpoint first, alongside the immediately-working provider FQDN (if\n  // any). The TLS note's \"Ingress URL below works immediately\" promise\n  // only fires when an Ingress is actually present (r3250192778).\n  if (typeof dr.custom_domain === 'string' && dr.custom_domain.length > 0) {\n    lines.push(`  Custom domain (provisioning):  https://${dr.custom_domain}/`);\n    lines.push(\n      hasIngress\n        ? '    — TLS may take a few minutes; the Ingress URL below works immediately.'\n        : '    — TLS may take a few minutes.',\n    );\n  }\n\n  if (ingresses.length === 0) {\n    // Legacy fallback: when no FQDN can be extracted from `connection`\n    // (e.g. providers reporting the older `connection.host` / `ports`\n    // shape rather than `connection.instances`), fred may still surface\n    // the URL at the top level. `normalizeFredUrl` is the shared helper\n    // (mirrored across `classify-deploy-response.ts`, this renderer,\n    // and `deploy-app.ts`'s `DeployResult.urls` fallback). The\n    // `(none …)` fallback stays for the truly-empty case.\n    if (typeof dr.url === 'string' && dr.url.length > 0) {\n      lines.push(`  Ingress:       ${normalizeFredUrl(dr.url)}`);\n    } else {\n      lines.push(\n        '  Ingress:       (none — service is internal or no FQDN reported)',\n      );\n    }\n  } else if (ingresses.length === 1) {\n    lines.push(`  Ingress:       ${ingresses[0]}`);\n  } else {\n    lines.push('  Ingresses:');\n    for (const fqdn of ingresses) {\n      lines.push(`    - ${fqdn}`);\n    }\n  }\n  lines.push('');\n  lines.push(\n    `For logs / status:  /manifest-agent:troubleshoot-deployment ${input.leaseUuid}`,\n  );\n\n  return lines.join('\\n');\n}\n\n/**\n * Return the user-facing form of a lease state. The `LEASE_STATE_` prefix\n * is stripped for display (e.g. `LEASE_STATE_ACTIVE` → `ACTIVE`). Unknown\n * decodes render as `UNKNOWN(<raw>)` so the raw remains visible; absent\n * state renders as `(unknown)`.\n */\nfunction decodeStateName(state: number | string | undefined): string {\n  if (state === undefined) return '(unknown)';\n  const canonical = decodeLeaseState(state);\n  if (canonical !== undefined) {\n    return canonical.slice('LEASE_STATE_'.length);\n  }\n  return `UNKNOWN(${String(state)})`;\n}\n\n// Re-export for callers that want to walk endpoints themselves without\n// re-importing from `./connection.js`. Keeps `format-success.ts` the\n// single consumer-facing entry for success-rendering plumbing.\nexport type { RunningEndpoint };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAM,UACJ;AAgCF,SAAgB,cAAc,OAAmC;AAC/D,KAAI,CAAC,QAAQ,KAAK,MAAM,UAAU,CAChC,OAAM,IAAI,UACR,iDAAiD,MAAM,UAAU,GAClE;AAEH,KACE,MAAM,mBAAmB,QACzB,OAAO,MAAM,mBAAmB,SAEhC,OAAM,IAAI,UACR,0DACD;CAGH,MAAM,KAAK,MAAM;CACjB,MAAM,eACJ,OAAO,GAAG,kBAAkB,YAAY,GAAG,cAAc,SAAS,IAC9D,GAAG,gBACH;CACN,MAAM,YAAY,gBAAgB,GAAG,MAAM;CAE3C,MAAM,YADY,wBAAwB,GAAG,WAAW,CAErD,IAAI,wBAAwB,CAC5B,QAAQ,MAAmB,OAAO,MAAM,YAAY,EAAE,SAAS,EAAE;CAMpE,MAAM,aACJ,UAAU,SAAS,KAAM,OAAO,GAAG,QAAQ,YAAY,GAAG,IAAI,SAAS;CAEzE,MAAM,QAAkB;EACtB;EACA,oBAAoB;EACpB,oBAAoB,MAAM;EAC1B,oBAAoB;EACrB;AAOD,KAAI,OAAO,GAAG,kBAAkB,YAAY,GAAG,cAAc,SAAS,GAAG;AACvE,QAAM,KAAK,4CAA4C,GAAG,cAAc,GAAG;AAC3E,QAAM,KACJ,aACI,+EACA,oCACL;;AAGH,KAAI,UAAU,WAAW,EAQvB,KAAI,OAAO,GAAG,QAAQ,YAAY,GAAG,IAAI,SAAS,EAChD,OAAM,KAAK,oBAAoB,iBAAiB,GAAG,IAAI,GAAG;KAE1D,OAAM,KACJ,oEACD;UAEM,UAAU,WAAW,EAC9B,OAAM,KAAK,oBAAoB,UAAU,KAAK;MACzC;AACL,QAAM,KAAK,eAAe;AAC1B,OAAK,MAAM,QAAQ,UACjB,OAAM,KAAK,SAAS,OAAO;;AAG/B,OAAM,KAAK,GAAG;AACd,OAAM,KACJ,+DAA+D,MAAM,YACtE;AAED,QAAO,MAAM,KAAK,KAAK;;;;;;;;AASzB,SAAS,gBAAgB,OAA4C;AACnE,KAAI,UAAU,KAAA,EAAW,QAAO;CAChC,MAAM,YAAYA,OAAiB,MAAM;AACzC,KAAI,cAAc,KAAA,EAChB,QAAO,UAAU,MAAM,GAAsB;AAE/C,QAAO,WAAW,OAAO,MAAM,CAAC"}

package/dist/internals/guarded-fetch.d.ts

@@ -0,0 +1,138 @@
+//#region src/internals/guarded-fetch.d.ts
+/**
+ * SSRF-guarded `fetch` factory. A Node-native undici Dispatcher that
+ * DNS-resolves once at connect time and rejects any address whose
+ * `ipaddr.js` range is not `'unicast'`.
+ *
+ * Why DIY rather than `request-filtering-agent`: the library only works with
+ * `http`/`https`.Agent (legacy http API) and explicitly does NOT plug into
+ * undici / native `fetch` per its v3.2.0 README. Re-routing the same
+ * blocking semantics through undici's Dispatcher hook lets agent-core's
+ * `inspectImage` (and future consumers) use native `fetch` while preserving
+ * the same SSRF posture.
+ *
+ * Design (architect-blessed):
+ * - **`ipaddr.js`'s `range()` is the source of truth.** Same approach as
+ *   `request-filtering-agent`: block any IP whose range is not `'unicast'`.
+ *   This covers loopback / private / link-local / multicast / broadcast /
+ *   reserved / carrier-grade-NAT / unspecified / ipv4Mapped / etc. via the
+ *   library's well-maintained RFC-classification table.
+ * - **IPv4-mapped IPv6 normalization** (security-critical). An attacker
+ *   writing `::ffff:127.0.0.1` would otherwise sit in `ipaddr.js`'s
+ *   `'ipv4Mapped'` IPv6 range — coincidentally blocked, but for the
+ *   structural reason ("v4-mapped form") rather than the security reason
+ *   ("loopback target"). We normalize first so the block is justified.
+ *   Without this step, a v4-mapped form of a PUBLIC IPv4 (`::ffff:8.8.8.8`)
+ *   would also be blocked (wrong outcome — public IP is fine via
+ *   v4-mapped). Normalization gets both cases right.
+ * - **DNS-resolve INSIDE the connect hook** to close the TOCTOU window
+ *   between resolve and TCP connect. The resolved IP gets substituted as
+ *   the connect hostname so the kernel doesn't re-resolve.
+ * - **Module-level singleton Dispatcher**, lazy-instantiated on first
+ *   `createGuardedFetch()` invocation. Mirrors the CJS singleton-agent
+ *   pattern; avoids the aggressive `setGlobalDispatcher()` side-effect.
+ * - **Construction-time runtime check** (`typeof process === 'undefined'`)
+ *   throws a clear error on browser/Deno so the failure is actionable, not
+ *   a confusing mid-fetch module-resolution error.
+ * - **Redirect safety:** undici re-fires the connect hook on every cross-
+ *   host redirect; same-host redirects reuse the checked socket. The fetch
+ *   closure does NOT need `redirect: 'manual'` — default `follow` is safe
+ *   by construction.
+ *
+ * Blocked-range exports (`BLOCKED_RANGES_IPV4`, `BLOCKED_RANGES_IPV6`) are
+ * provided for audit + test purposes: they enumerate the `ipaddr.js`
+ * `range()` classifications we treat as non-`unicast` with their RFC
+ * citations, so a reviewer can grep the code without consulting the
+ * `ipaddr.js` source.
+ *
+ * Cross-platform note: agent-core's `tsdown.config.ts` targets
+ * `platform: 'neutral'`. `ipaddr.js` is isomorphic (pure JS, no node:*
+ * imports), so the static import is fine. `undici` and `node:dns/promises`
+ * + `node:net` are Node-only — dynamic-imported INSIDE the lazy singleton
+ * creation so the package stays importable from browsers / Deno (calling
+ * `createGuardedFetch()` from those throws the construction-time error
+ * with actionable guidance).
+ */
+type GuardedFetch = typeof fetch;
+/**
+ * `ipaddr.js`-classified IPv4 range labels we block (i.e., everything
+ * except `'unicast'`). Exposed as a module-level constant so the audit
+ * trail is greppable and a future range-list update is a focused edit.
+ *
+ * RFC citations included for each label for audit visibility — `ipaddr.js`
+ * owns the actual CIDR tables that map IPs to these labels.
+ */
+declare const BLOCKED_RANGES_IPV4: ReadonlyArray<{
+  readonly range: string;
+  readonly rfc: string;
+}>;
+/**
+ * `ipaddr.js`-classified IPv6 range labels we block. Note: `'ipv4Mapped'`
+ * is NOT included here because we normalize IPv4-mapped IPv6 addresses to
+ * their underlying IPv4 form BEFORE the range check — otherwise a v4-
+ * mapped form of a public IP (`::ffff:8.8.8.8`) would be wrongly blocked,
+ * and a v4-mapped form of a private IP (`::ffff:127.0.0.1`) would be
+ * blocked only structurally (not for the security reason).
+ */
+declare const BLOCKED_RANGES_IPV6: ReadonlyArray<{
+  readonly range: string;
+  readonly rfc: string;
+}>;
+/**
+ * SSRF block-check for a single IP string. **Allow-list policy:** only
+ * ipaddr.js's `'unicast'` classification is permitted; every other range
+ * label is blocked.
+ *
+ * The prior deny-list implementation iterated BLOCKED_RANGES_* and let
+ * anything not explicitly enumerated fall through as "allowed" — a
+ * security-critical bias error. IPv6 categories like `6to4` (which can
+ * wrap loopback or RFC 1918 IPs as `2002:7f00::/24` etc.), `teredo`,
+ * `rfc6052` (NAT64), and `discard` were ALL un-named and therefore
+ * allowed-by-omission. Under the allow-list policy, these all
+ * default-deny along with any future ipaddr.js classification we
+ * haven't audited.
+ *
+ * Returned `{range, rfc}` descriptor sources:
+ *   - **Named in BLOCKED_RANGES_IPV4 / BLOCKED_RANGES_IPV6** → returns
+ *     that entry verbatim (carries the audited RFC citation).
+ *   - **Unknown non-unicast label** → synthesizes
+ *     `{range: <label>, rfc: 'ipaddr.js classification (default-deny non-unicast)'}`.
+ *     The audit string is generic but the block decision is correct;
+ *     a future PR can promote frequently-seen labels into
+ *     BLOCKED_RANGES_* with proper RFC citations.
+ *
+ * IPv4-mapped IPv6 addresses (`::ffff:1.2.3.4`) are normalized to their
+ * IPv4 form before the range check so the security verdict tracks the
+ * underlying IP, not the structural wrapping.
+ *
+ * Throws `Error` on unparseable input — callers should catch and treat
+ * "unparseable" as "block" (defense-in-depth — better to refuse than to
+ * pass through to network on garbage input).
+ */
+declare function isBlocked(ipString: string): {
+  range: string;
+  rfc: string;
+} | null;
+/**
+ * Build the SSRF-guarded fetch closure. Construction-time runtime check
+ * gates Node-only — browser / Deno consumers either pass their own
+ * `opts.fetch` to consumers like `inspectImage` or accept this error.
+ *
+ * The returned function matches `typeof fetch` and lazy-instantiates the
+ * undici Dispatcher on first invocation. Subsequent calls share the
+ * cached singleton.
+ *
+ * **Important: uses undici's own `fetch`**, not Node's built-in. Node's
+ * built-in fetch is backed by its bundled undici, which is pinned to
+ * Node's release-cycle version (Node 22 → undici 6.x). The npm-installed
+ * `undici` package may be newer, and the Dispatcher protocol between
+ * versions isn't guaranteed compatible (we observed "invalid
+ * onRequestStart method" when mixing Node 22's fetch with undici@8 Agent).
+ * Routing through undici's own fetch (same package version as the Agent)
+ * sidesteps the mismatch. The function signature stays identical to
+ * Node's `fetch` so consumers can't tell the difference.
+ */
+declare function createGuardedFetch(): GuardedFetch;
+//#endregion
+export { BLOCKED_RANGES_IPV4, BLOCKED_RANGES_IPV6, GuardedFetch, createGuardedFetch, isBlocked };
+//# sourceMappingURL=guarded-fetch.d.ts.map

package/dist/internals/guarded-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-fetch.d.ts","names":[],"sources":["../../src/internals/guarded-fetch.ts"],"mappings":";;AAyDA;;;;;AAUA;;;;;;;;;AA+BA;;;;;;;;;AA2CA;;;;;;;;;AAqEA;;;;;;;;;;;;;;;;;;;;;KAzJY,YAAA,UAAsB,KAAA;;;;;;;;;cAUrB,mBAAA,EAAqB,aAAA;EAAA,SACvB,KAAA;EAAA,SACA,GAAA;AAAA;;;;;;;;;cA6BE,mBAAA,EAAqB,aAAA;EAAA,SACvB,KAAA;EAAA,SACA,GAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyCK,SAAA,CAAU,QAAA;EACxB,KAAA;EACA,GAAA;AAAA;;;;;;;;;;;;;;;;;;;;iBAmEc,kBAAA,CAAA,GAAsB,YAAA"}

package/dist/internals/guarded-fetch.js

@@ -0,0 +1,242 @@
+import ipaddr from "ipaddr.js";
+//#region src/internals/guarded-fetch.ts
+/**
+* `ipaddr.js`-classified IPv4 range labels we block (i.e., everything
+* except `'unicast'`). Exposed as a module-level constant so the audit
+* trail is greppable and a future range-list update is a focused edit.
+*
+* RFC citations included for each label for audit visibility — `ipaddr.js`
+* owns the actual CIDR tables that map IPs to these labels.
+*/
+const BLOCKED_RANGES_IPV4 = [
+	{
+		range: "unspecified",
+		rfc: "RFC 1122 §3.2.1.3 — 0.0.0.0/8 (this network / meta)"
+	},
+	{
+		range: "private",
+		rfc: "RFC 1918 — 10/8, 172.16/12, 192.168/16 (private)"
+	},
+	{
+		range: "loopback",
+		rfc: "RFC 5735 — 127/8 (loopback)"
+	},
+	{
+		range: "linkLocal",
+		rfc: "RFC 3927 — 169.254/16 (link-local, incl. AWS/GCP/Azure metadata at 169.254.169.254)"
+	},
+	{
+		range: "carrierGradeNat",
+		rfc: "RFC 6598 — 100.64/10 (carrier-grade NAT)"
+	},
+	{
+		range: "broadcast",
+		rfc: "RFC 919 — 255.255.255.255 (limited broadcast)"
+	},
+	{
+		range: "multicast",
+		rfc: "RFC 5771 — 224/4 (multicast)"
+	},
+	{
+		range: "reserved",
+		rfc: "RFC 1112 / 6890 — 240/4, 192.0.0/24, 198.18/15 etc. (reserved)"
+	}
+];
+/**
+* `ipaddr.js`-classified IPv6 range labels we block. Note: `'ipv4Mapped'`
+* is NOT included here because we normalize IPv4-mapped IPv6 addresses to
+* their underlying IPv4 form BEFORE the range check — otherwise a v4-
+* mapped form of a public IP (`::ffff:8.8.8.8`) would be wrongly blocked,
+* and a v4-mapped form of a private IP (`::ffff:127.0.0.1`) would be
+* blocked only structurally (not for the security reason).
+*/
+const BLOCKED_RANGES_IPV6 = [
+	{
+		range: "unspecified",
+		rfc: "RFC 4291 — :: (unspecified)"
+	},
+	{
+		range: "loopback",
+		rfc: "RFC 4291 — ::1/128 (loopback)"
+	},
+	{
+		range: "linkLocal",
+		rfc: "RFC 4291 — fe80::/10 (link-local)"
+	},
+	{
+		range: "uniqueLocal",
+		rfc: "RFC 4193 — fc00::/7 (unique local / private)"
+	},
+	{
+		range: "multicast",
+		rfc: "RFC 4291 — ff00::/8 (multicast)"
+	},
+	{
+		range: "reserved",
+		rfc: "RFC 4291 / 5156 — various reserved blocks"
+	}
+];
+/**
+* SSRF block-check for a single IP string. **Allow-list policy:** only
+* ipaddr.js's `'unicast'` classification is permitted; every other range
+* label is blocked.
+*
+* The prior deny-list implementation iterated BLOCKED_RANGES_* and let
+* anything not explicitly enumerated fall through as "allowed" — a
+* security-critical bias error. IPv6 categories like `6to4` (which can
+* wrap loopback or RFC 1918 IPs as `2002:7f00::/24` etc.), `teredo`,
+* `rfc6052` (NAT64), and `discard` were ALL un-named and therefore
+* allowed-by-omission. Under the allow-list policy, these all
+* default-deny along with any future ipaddr.js classification we
+* haven't audited.
+*
+* Returned `{range, rfc}` descriptor sources:
+*   - **Named in BLOCKED_RANGES_IPV4 / BLOCKED_RANGES_IPV6** → returns
+*     that entry verbatim (carries the audited RFC citation).
+*   - **Unknown non-unicast label** → synthesizes
+*     `{range: <label>, rfc: 'ipaddr.js classification (default-deny non-unicast)'}`.
+*     The audit string is generic but the block decision is correct;
+*     a future PR can promote frequently-seen labels into
+*     BLOCKED_RANGES_* with proper RFC citations.
+*
+* IPv4-mapped IPv6 addresses (`::ffff:1.2.3.4`) are normalized to their
+* IPv4 form before the range check so the security verdict tracks the
+* underlying IP, not the structural wrapping.
+*
+* Throws `Error` on unparseable input — callers should catch and treat
+* "unparseable" as "block" (defense-in-depth — better to refuse than to
+* pass through to network on garbage input).
+*/
+function isBlocked(ipString) {
+	let parsed = ipaddr.parse(ipString);
+	if (parsed.kind() === "ipv6") {
+		const v6 = parsed;
+		if (v6.isIPv4MappedAddress()) parsed = v6.toIPv4Address();
+	}
+	const rangeLabel = parsed.range();
+	if (rangeLabel === "unicast") return null;
+	const named = (parsed.kind() === "ipv4" ? BLOCKED_RANGES_IPV4 : BLOCKED_RANGES_IPV6).find((r) => r.range === rangeLabel);
+	if (named) return named;
+	return {
+		range: rangeLabel,
+		rfc: "ipaddr.js classification (default-deny non-unicast)"
+	};
+}
+/**
+* Cache the in-flight Promise (not the resolved value) so concurrent first-
+* call racers share the same construction and don't double-build the
+* undici Agent. Resolves to the singleton DispatcherCache. After
+* resolution, subsequent calls await the already-settled Promise (cheap).
+*/
+let cachedP;
+/**
+* Build the SSRF-guarded fetch closure. Construction-time runtime check
+* gates Node-only — browser / Deno consumers either pass their own
+* `opts.fetch` to consumers like `inspectImage` or accept this error.
+*
+* The returned function matches `typeof fetch` and lazy-instantiates the
+* undici Dispatcher on first invocation. Subsequent calls share the
+* cached singleton.
+*
+* **Important: uses undici's own `fetch`**, not Node's built-in. Node's
+* built-in fetch is backed by its bundled undici, which is pinned to
+* Node's release-cycle version (Node 22 → undici 6.x). The npm-installed
+* `undici` package may be newer, and the Dispatcher protocol between
+* versions isn't guaranteed compatible (we observed "invalid
+* onRequestStart method" when mixing Node 22's fetch with undici@8 Agent).
+* Routing through undici's own fetch (same package version as the Agent)
+* sidesteps the mismatch. The function signature stays identical to
+* Node's `fetch` so consumers can't tell the difference.
+*/
+function createGuardedFetch() {
+	if (typeof process === "undefined" || !process.versions?.node) throw new Error("createGuardedFetch requires a Node.js runtime. On browser/Deno consumers, pass `opts.fetch` directly with your own SSRF-guarded implementation. See agent-core README.");
+	return async (input, init) => {
+		if (!cachedP) cachedP = buildSsrfDispatcher().catch((err) => {
+			cachedP = void 0;
+			throw err;
+		});
+		const c = await cachedP;
+		const initWithDispatcher = {
+			...init ?? {},
+			dispatcher: c.dispatcher
+		};
+		return c.fetch(input, initWithDispatcher);
+	};
+}
+/**
+* Lazy dynamic-import of Node-only modules so the package stays importable
+* from non-Node consumers. The runtime check in `createGuardedFetch`
+* already gates Node-only — this function is only reached on Node.
+*
+* Returns BOTH the dispatcher and undici's own `fetch` so the
+* `createGuardedFetch` closure can route through undici directly (avoiding
+* Node-bundled-undici vs npm-undici Dispatcher protocol mismatches).
+*/
+async function buildSsrfDispatcher() {
+	const [undici, dnsModule, netModule] = await Promise.all([
+		import("undici"),
+		import("node:dns/promises"),
+		import("node:net")
+	]);
+	const baseConnect = undici.buildConnector({});
+	return {
+		dispatcher: new undici.Agent({ connect: (options, callback) => {
+			const hostname = options.hostname ?? "";
+			resolveAndCheck(hostname, netModule, dnsModule).then((resolved) => {
+				if (resolved.blocked) {
+					callback(/* @__PURE__ */ new Error(`SSRF blocked: ${hostname} resolves to ${resolved.ip} which is in blocked range '${resolved.blocked.range}' (${resolved.blocked.rfc})`), null);
+					return;
+				}
+				baseConnect({
+					...options,
+					hostname: resolved.ip
+				}, callback);
+			}).catch((err) => {
+				const msg = err instanceof Error ? err.message : String(err);
+				callback(/* @__PURE__ */ new Error(`SSRF blocked: refused to connect to ${hostname}: ${msg}`), null);
+			});
+		} }),
+		fetch: undici.fetch
+	};
+}
+/**
+* Resolve the connection target's IP and check against the blocked-range
+* sets. Handles three input cases:
+*   1. Hostname is already an IP literal → check directly (no DNS lookup).
+*   2. Hostname is an FQDN → resolve via `dns.lookup` (returns first
+*      address; matches Node's default connection behavior).
+*   3. Resolution failure → throws, which the caller's `.catch` translates
+*      into a fail-closed SSRF-block error.
+*
+* **DELIBERATE DIVERGENCE FROM SPEC** — architect's spec said
+* `dns.resolve4` / `dns.resolve6`; this implementation uses `dns.lookup`.
+* Rationale: `dns.lookup` matches the kernel's actual connection-time
+* resolution path (hosts file + nsswitch.conf + DNS in order), so the IP
+* we check IS the IP the kernel would connect to. Using `resolve4/6`
+* would consult DNS only and miss the hosts-file path — if an attacker
+* could write to `/etc/hosts` (root only) the check would be incomplete
+* because the kernel's actual connect would use a different address than
+* the one we checked. Per threat model: hosts-file writes require root,
+* so an attacker capable of writing there already owns the machine; this
+* is "fixing the right problem" — the check should track what the kernel
+* does, not its own model of resolution.
+*
+* Documented in PR 2 description for reviewer awareness. If the threat
+* model expands to include shared-host scenarios where attacker-controlled
+* hosts entries are realistic, switch to `resolve4/6` and accept the
+* connect-time-mismatch risk.
+*/
+async function resolveAndCheck(hostname, netModule, dnsModule) {
+	let ip;
+	if (netModule.isIP(hostname) !== 0) ip = hostname;
+	else ip = (await dnsModule.lookup(hostname, { verbatim: true })).address;
+	const blocked = isBlocked(ip);
+	return {
+		ip,
+		blocked
+	};
+}
+//#endregion
+export { BLOCKED_RANGES_IPV4, BLOCKED_RANGES_IPV6, createGuardedFetch, isBlocked };
+
+//# sourceMappingURL=guarded-fetch.js.map

package/dist/internals/guarded-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-fetch.js","names":[],"sources":["../../src/internals/guarded-fetch.ts"],"sourcesContent":["import ipaddr from 'ipaddr.js';\n\n/**\n * SSRF-guarded `fetch` factory. A Node-native undici Dispatcher that\n * DNS-resolves once at connect time and rejects any address whose\n * `ipaddr.js` range is not `'unicast'`.\n *\n * Why DIY rather than `request-filtering-agent`: the library only works with\n * `http`/`https`.Agent (legacy http API) and explicitly does NOT plug into\n * undici / native `fetch` per its v3.2.0 README. Re-routing the same\n * blocking semantics through undici's Dispatcher hook lets agent-core's\n * `inspectImage` (and future consumers) use native `fetch` while preserving\n * the same SSRF posture.\n *\n * Design (architect-blessed):\n * - **`ipaddr.js`'s `range()` is the source of truth.** Same approach as\n *   `request-filtering-agent`: block any IP whose range is not `'unicast'`.\n *   This covers loopback / private / link-local / multicast / broadcast /\n *   reserved / carrier-grade-NAT / unspecified / ipv4Mapped / etc. via the\n *   library's well-maintained RFC-classification table.\n * - **IPv4-mapped IPv6 normalization** (security-critical). An attacker\n *   writing `::ffff:127.0.0.1` would otherwise sit in `ipaddr.js`'s\n *   `'ipv4Mapped'` IPv6 range — coincidentally blocked, but for the\n *   structural reason (\"v4-mapped form\") rather than the security reason\n *   (\"loopback target\"). We normalize first so the block is justified.\n *   Without this step, a v4-mapped form of a PUBLIC IPv4 (`::ffff:8.8.8.8`)\n *   would also be blocked (wrong outcome — public IP is fine via\n *   v4-mapped). Normalization gets both cases right.\n * - **DNS-resolve INSIDE the connect hook** to close the TOCTOU window\n *   between resolve and TCP connect. The resolved IP gets substituted as\n *   the connect hostname so the kernel doesn't re-resolve.\n * - **Module-level singleton Dispatcher**, lazy-instantiated on first\n *   `createGuardedFetch()` invocation. Mirrors the CJS singleton-agent\n *   pattern; avoids the aggressive `setGlobalDispatcher()` side-effect.\n * - **Construction-time runtime check** (`typeof process === 'undefined'`)\n *   throws a clear error on browser/Deno so the failure is actionable, not\n *   a confusing mid-fetch module-resolution error.\n * - **Redirect safety:** undici re-fires the connect hook on every cross-\n *   host redirect; same-host redirects reuse the checked socket. The fetch\n *   closure does NOT need `redirect: 'manual'` — default `follow` is safe\n *   by construction.\n *\n * Blocked-range exports (`BLOCKED_RANGES_IPV4`, `BLOCKED_RANGES_IPV6`) are\n * provided for audit + test purposes: they enumerate the `ipaddr.js`\n * `range()` classifications we treat as non-`unicast` with their RFC\n * citations, so a reviewer can grep the code without consulting the\n * `ipaddr.js` source.\n *\n * Cross-platform note: agent-core's `tsdown.config.ts` targets\n * `platform: 'neutral'`. `ipaddr.js` is isomorphic (pure JS, no node:*\n * imports), so the static import is fine. `undici` and `node:dns/promises`\n * + `node:net` are Node-only — dynamic-imported INSIDE the lazy singleton\n * creation so the package stays importable from browsers / Deno (calling\n * `createGuardedFetch()` from those throws the construction-time error\n * with actionable guidance).\n */\n\nexport type GuardedFetch = typeof fetch;\n\n/**\n * `ipaddr.js`-classified IPv4 range labels we block (i.e., everything\n * except `'unicast'`). Exposed as a module-level constant so the audit\n * trail is greppable and a future range-list update is a focused edit.\n *\n * RFC citations included for each label for audit visibility — `ipaddr.js`\n * owns the actual CIDR tables that map IPs to these labels.\n */\nexport const BLOCKED_RANGES_IPV4: ReadonlyArray<{\n  readonly range: string;\n  readonly rfc: string;\n}> = [\n  {\n    range: 'unspecified',\n    rfc: 'RFC 1122 §3.2.1.3 — 0.0.0.0/8 (this network / meta)',\n  },\n  { range: 'private', rfc: 'RFC 1918 — 10/8, 172.16/12, 192.168/16 (private)' },\n  { range: 'loopback', rfc: 'RFC 5735 — 127/8 (loopback)' },\n  {\n    range: 'linkLocal',\n    rfc: 'RFC 3927 — 169.254/16 (link-local, incl. AWS/GCP/Azure metadata at 169.254.169.254)',\n  },\n  { range: 'carrierGradeNat', rfc: 'RFC 6598 — 100.64/10 (carrier-grade NAT)' },\n  { range: 'broadcast', rfc: 'RFC 919 — 255.255.255.255 (limited broadcast)' },\n  { range: 'multicast', rfc: 'RFC 5771 — 224/4 (multicast)' },\n  {\n    range: 'reserved',\n    rfc: 'RFC 1112 / 6890 — 240/4, 192.0.0/24, 198.18/15 etc. (reserved)',\n  },\n];\n\n/**\n * `ipaddr.js`-classified IPv6 range labels we block. Note: `'ipv4Mapped'`\n * is NOT included here because we normalize IPv4-mapped IPv6 addresses to\n * their underlying IPv4 form BEFORE the range check — otherwise a v4-\n * mapped form of a public IP (`::ffff:8.8.8.8`) would be wrongly blocked,\n * and a v4-mapped form of a private IP (`::ffff:127.0.0.1`) would be\n * blocked only structurally (not for the security reason).\n */\nexport const BLOCKED_RANGES_IPV6: ReadonlyArray<{\n  readonly range: string;\n  readonly rfc: string;\n}> = [\n  { range: 'unspecified', rfc: 'RFC 4291 — :: (unspecified)' },\n  { range: 'loopback', rfc: 'RFC 4291 — ::1/128 (loopback)' },\n  { range: 'linkLocal', rfc: 'RFC 4291 — fe80::/10 (link-local)' },\n  { range: 'uniqueLocal', rfc: 'RFC 4193 — fc00::/7 (unique local / private)' },\n  { range: 'multicast', rfc: 'RFC 4291 — ff00::/8 (multicast)' },\n  { range: 'reserved', rfc: 'RFC 4291 / 5156 — various reserved blocks' },\n];\n\n/**\n * SSRF block-check for a single IP string. **Allow-list policy:** only\n * ipaddr.js's `'unicast'` classification is permitted; every other range\n * label is blocked.\n *\n * The prior deny-list implementation iterated BLOCKED_RANGES_* and let\n * anything not explicitly enumerated fall through as \"allowed\" — a\n * security-critical bias error. IPv6 categories like `6to4` (which can\n * wrap loopback or RFC 1918 IPs as `2002:7f00::/24` etc.), `teredo`,\n * `rfc6052` (NAT64), and `discard` were ALL un-named and therefore\n * allowed-by-omission. Under the allow-list policy, these all\n * default-deny along with any future ipaddr.js classification we\n * haven't audited.\n *\n * Returned `{range, rfc}` descriptor sources:\n *   - **Named in BLOCKED_RANGES_IPV4 / BLOCKED_RANGES_IPV6** → returns\n *     that entry verbatim (carries the audited RFC citation).\n *   - **Unknown non-unicast label** → synthesizes\n *     `{range: <label>, rfc: 'ipaddr.js classification (default-deny non-unicast)'}`.\n *     The audit string is generic but the block decision is correct;\n *     a future PR can promote frequently-seen labels into\n *     BLOCKED_RANGES_* with proper RFC citations.\n *\n * IPv4-mapped IPv6 addresses (`::ffff:1.2.3.4`) are normalized to their\n * IPv4 form before the range check so the security verdict tracks the\n * underlying IP, not the structural wrapping.\n *\n * Throws `Error` on unparseable input — callers should catch and treat\n * \"unparseable\" as \"block\" (defense-in-depth — better to refuse than to\n * pass through to network on garbage input).\n */\nexport function isBlocked(ipString: string): {\n  range: string;\n  rfc: string;\n} | null {\n  let parsed: ipaddr.IPv4 | ipaddr.IPv6 = ipaddr.parse(ipString);\n\n  // IPv4-mapped IPv6 normalization — security-critical. See doc-comment.\n  if (parsed.kind() === 'ipv6') {\n    const v6 = parsed as ipaddr.IPv6;\n    if (v6.isIPv4MappedAddress()) {\n      parsed = v6.toIPv4Address();\n    }\n  }\n\n  const rangeLabel = parsed.range();\n\n  // Allow-list gate: `'unicast'` is the only category permitted.\n  // Everything else defaults to block; the lookup below is for audit info.\n  if (rangeLabel === 'unicast') {\n    return null;\n  }\n\n  const list =\n    parsed.kind() === 'ipv4' ? BLOCKED_RANGES_IPV4 : BLOCKED_RANGES_IPV6;\n  // Both lists are short; linear scan is fine.\n  const named = list.find((r) => r.range === rangeLabel);\n  if (named) return named;\n\n  // Default-deny fallback for unknown non-unicast labels (6to4, teredo,\n  // rfc6052, discard, future categories ipaddr.js may add). The block\n  // decision is correct; the audit string is generic.\n  return {\n    range: rangeLabel,\n    rfc: 'ipaddr.js classification (default-deny non-unicast)',\n  };\n}\n\ninterface DispatcherCache {\n  dispatcher: unknown;\n  fetch: typeof fetch;\n}\n\n/**\n * Cache the in-flight Promise (not the resolved value) so concurrent first-\n * call racers share the same construction and don't double-build the\n * undici Agent. Resolves to the singleton DispatcherCache. After\n * resolution, subsequent calls await the already-settled Promise (cheap).\n */\nlet cachedP: Promise<DispatcherCache> | undefined;\n\n/**\n * Build the SSRF-guarded fetch closure. Construction-time runtime check\n * gates Node-only — browser / Deno consumers either pass their own\n * `opts.fetch` to consumers like `inspectImage` or accept this error.\n *\n * The returned function matches `typeof fetch` and lazy-instantiates the\n * undici Dispatcher on first invocation. Subsequent calls share the\n * cached singleton.\n *\n * **Important: uses undici's own `fetch`**, not Node's built-in. Node's\n * built-in fetch is backed by its bundled undici, which is pinned to\n * Node's release-cycle version (Node 22 → undici 6.x). The npm-installed\n * `undici` package may be newer, and the Dispatcher protocol between\n * versions isn't guaranteed compatible (we observed \"invalid\n * onRequestStart method\" when mixing Node 22's fetch with undici@8 Agent).\n * Routing through undici's own fetch (same package version as the Agent)\n * sidesteps the mismatch. The function signature stays identical to\n * Node's `fetch` so consumers can't tell the difference.\n */\nexport function createGuardedFetch(): GuardedFetch {\n  if (typeof process === 'undefined' || !process.versions?.node) {\n    throw new Error(\n      'createGuardedFetch requires a Node.js runtime. On browser/Deno consumers, pass `opts.fetch` directly with your own SSRF-guarded implementation. See agent-core README.',\n    );\n  }\n\n  return async (input, init) => {\n    // Cache the Promise rather than the resolved value to dedup concurrent\n    // first-call construction. Two callers racing through the lazy path\n    // would otherwise both call `buildSsrfDispatcher()` and end up with\n    // two undici Agents (no correctness bug, just double resource).\n    //\n    // Catch-and-reset on rejection: if `buildSsrfDispatcher()` ever fails\n    // (e.g., dynamic `import('undici')` throws on a runtime that masquerades\n    // as Node but lacks the module), the rejected Promise must NOT stay\n    // cached — otherwise every subsequent `createGuardedFetch()` call would\n    // re-throw the same error permanently. Clearing `cachedP` in the catch\n    // arm lets a future caller retry construction.\n    if (!cachedP) {\n      cachedP = buildSsrfDispatcher().catch((err: unknown) => {\n        cachedP = undefined;\n        throw err;\n      });\n    }\n    const c = await cachedP;\n    // undici's fetch accepts a `dispatcher` option natively. Cast the init\n    // to undici's expected shape — undici's fetch signature is structurally\n    // compatible with global fetch but TS can't see through the dispatcher\n    // field without a cast.\n    const initWithDispatcher = {\n      ...(init ?? {}),\n      dispatcher: c.dispatcher,\n    } as RequestInit;\n    return c.fetch(input, initWithDispatcher);\n  };\n}\n\n/**\n * Lazy dynamic-import of Node-only modules so the package stays importable\n * from non-Node consumers. The runtime check in `createGuardedFetch`\n * already gates Node-only — this function is only reached on Node.\n *\n * Returns BOTH the dispatcher and undici's own `fetch` so the\n * `createGuardedFetch` closure can route through undici directly (avoiding\n * Node-bundled-undici vs npm-undici Dispatcher protocol mismatches).\n */\nasync function buildSsrfDispatcher(): Promise<DispatcherCache> {\n  const [undici, dnsModule, netModule] = await Promise.all([\n    import('undici'),\n    import('node:dns/promises'),\n    import('node:net'),\n  ]);\n\n  const baseConnect = undici.buildConnector({});\n\n  const dispatcher = new undici.Agent({\n    connect: (options, callback) => {\n      // Defensive: undici's Connect signature carries hostname + port + others.\n      // We snapshot the original hostname for error messages; the resolved\n      // IP gets substituted into `options` before the underlying TCP connect\n      // so the kernel doesn't re-resolve (DNS-rebinding mitigation).\n      const hostname = (options as { hostname?: string }).hostname ?? '';\n\n      resolveAndCheck(hostname, netModule, dnsModule)\n        .then((resolved) => {\n          if (resolved.blocked) {\n            callback(\n              new Error(\n                `SSRF blocked: ${hostname} resolves to ${resolved.ip} which is in blocked range '${resolved.blocked.range}' (${resolved.blocked.rfc})`,\n              ),\n              null,\n            );\n            return;\n          }\n          // Substitute the resolved IP so the kernel doesn't re-resolve.\n          baseConnect(\n            { ...options, hostname: resolved.ip } as Parameters<\n              typeof baseConnect\n            >[0],\n            callback,\n          );\n        })\n        .catch((err: unknown) => {\n          const msg = err instanceof Error ? err.message : String(err);\n          // Fail closed — unparseable / unresolvable hostnames get rejected\n          // rather than passed through. This keeps the SSRF posture intact\n          // against DNS errors that might otherwise leak through.\n          callback(\n            new Error(\n              `SSRF blocked: refused to connect to ${hostname}: ${msg}`,\n            ),\n            null,\n          );\n        });\n    },\n  });\n\n  // undici's fetch has a structurally compatible signature with global fetch.\n  // Cast at the boundary; downstream consumers see `typeof fetch`.\n  return {\n    dispatcher,\n    fetch: undici.fetch as unknown as typeof fetch,\n  };\n}\n\n/**\n * Resolve the connection target's IP and check against the blocked-range\n * sets. Handles three input cases:\n *   1. Hostname is already an IP literal → check directly (no DNS lookup).\n *   2. Hostname is an FQDN → resolve via `dns.lookup` (returns first\n *      address; matches Node's default connection behavior).\n *   3. Resolution failure → throws, which the caller's `.catch` translates\n *      into a fail-closed SSRF-block error.\n *\n * **DELIBERATE DIVERGENCE FROM SPEC** — architect's spec said\n * `dns.resolve4` / `dns.resolve6`; this implementation uses `dns.lookup`.\n * Rationale: `dns.lookup` matches the kernel's actual connection-time\n * resolution path (hosts file + nsswitch.conf + DNS in order), so the IP\n * we check IS the IP the kernel would connect to. Using `resolve4/6`\n * would consult DNS only and miss the hosts-file path — if an attacker\n * could write to `/etc/hosts` (root only) the check would be incomplete\n * because the kernel's actual connect would use a different address than\n * the one we checked. Per threat model: hosts-file writes require root,\n * so an attacker capable of writing there already owns the machine; this\n * is \"fixing the right problem\" — the check should track what the kernel\n * does, not its own model of resolution.\n *\n * Documented in PR 2 description for reviewer awareness. If the threat\n * model expands to include shared-host scenarios where attacker-controlled\n * hosts entries are realistic, switch to `resolve4/6` and accept the\n * connect-time-mismatch risk.\n */\nasync function resolveAndCheck(\n  hostname: string,\n  netModule: typeof import('node:net'),\n  dnsModule: typeof import('node:dns/promises'),\n): Promise<{\n  ip: string;\n  blocked: { range: string; rfc: string } | null;\n}> {\n  let ip: string;\n  if (netModule.isIP(hostname) !== 0) {\n    ip = hostname;\n  } else {\n    // `dns.lookup` calls `getaddrinfo` and follows the kernel's resolution\n    // order (hosts → nsswitch → DNS, OS-defined), so the IP we check IS\n    // the IP the kernel uses at connect(2) time. `dns.resolve4`/`resolve6`\n    // would query system DNS only and miss `/etc/hosts` entries — a\n    // `/etc/hosts evil.example.com 127.0.0.1` line would slip past the\n    // SSRF check (DNS returns a clean IP) while the kernel connects to\n    // loopback. Architect-endorsed correction to the original spec.\n    //\n    // `verbatim: true` preserves OS-defined IPv4/IPv6 ordering to avoid\n    // reorder-induced check-vs-connect drift in mixed-family DNS responses.\n    const result = await dnsModule.lookup(hostname, { verbatim: true });\n    ip = result.address;\n  }\n  // Defense-in-depth: treat parse failures as blocks. ipaddr.parse throws\n  // for malformed input — catch in the caller via the .catch wiring.\n  const blocked = isBlocked(ip);\n  return { ip, blocked };\n}\n"],"mappings":";;;;;;;;;;AAmEA,MAAa,sBAGR;CACH;EACE,OAAO;EACP,KAAK;EACN;CACD;EAAE,OAAO;EAAW,KAAK;EAAoD;CAC7E;EAAE,OAAO;EAAY,KAAK;EAA+B;CACzD;EACE,OAAO;EACP,KAAK;EACN;CACD;EAAE,OAAO;EAAmB,KAAK;EAA4C;CAC7E;EAAE,OAAO;EAAa,KAAK;EAAiD;CAC5E;EAAE,OAAO;EAAa,KAAK;EAAgC;CAC3D;EACE,OAAO;EACP,KAAK;EACN;CACF;;;;;;;;;AAUD,MAAa,sBAGR;CACH;EAAE,OAAO;EAAe,KAAK;EAA+B;CAC5D;EAAE,OAAO;EAAY,KAAK;EAAiC;CAC3D;EAAE,OAAO;EAAa,KAAK;EAAqC;CAChE;EAAE,OAAO;EAAe,KAAK;EAAgD;CAC7E;EAAE,OAAO;EAAa,KAAK;EAAmC;CAC9D;EAAE,OAAO;EAAY,KAAK;EAA6C;CACxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCD,SAAgB,UAAU,UAGjB;CACP,IAAI,SAAoC,OAAO,MAAM,SAAS;AAG9D,KAAI,OAAO,MAAM,KAAK,QAAQ;EAC5B,MAAM,KAAK;AACX,MAAI,GAAG,qBAAqB,CAC1B,UAAS,GAAG,eAAe;;CAI/B,MAAM,aAAa,OAAO,OAAO;AAIjC,KAAI,eAAe,UACjB,QAAO;CAMT,MAAM,SAFJ,OAAO,MAAM,KAAK,SAAS,sBAAsB,qBAEhC,MAAM,MAAM,EAAE,UAAU,WAAW;AACtD,KAAI,MAAO,QAAO;AAKlB,QAAO;EACL,OAAO;EACP,KAAK;EACN;;;;;;;;AAcH,IAAI;;;;;;;;;;;;;;;;;;;;AAqBJ,SAAgB,qBAAmC;AACjD,KAAI,OAAO,YAAY,eAAe,CAAC,QAAQ,UAAU,KACvD,OAAM,IAAI,MACR,yKACD;AAGH,QAAO,OAAO,OAAO,SAAS;AAY5B,MAAI,CAAC,QACH,WAAU,qBAAqB,CAAC,OAAO,QAAiB;AACtD,aAAU,KAAA;AACV,SAAM;IACN;EAEJ,MAAM,IAAI,MAAM;EAKhB,MAAM,qBAAqB;GACzB,GAAI,QAAQ,EAAE;GACd,YAAY,EAAE;GACf;AACD,SAAO,EAAE,MAAM,OAAO,mBAAmB;;;;;;;;;;;;AAa7C,eAAe,sBAAgD;CAC7D,MAAM,CAAC,QAAQ,WAAW,aAAa,MAAM,QAAQ,IAAI;EACvD,OAAO;EACP,OAAO;EACP,OAAO;EACR,CAAC;CAEF,MAAM,cAAc,OAAO,eAAe,EAAE,CAAC;AA8C7C,QAAO;EACL,YA7CiB,IAAI,OAAO,MAAM,EAClC,UAAU,SAAS,aAAa;GAK9B,MAAM,WAAY,QAAkC,YAAY;AAEhE,mBAAgB,UAAU,WAAW,UAAU,CAC5C,MAAM,aAAa;AAClB,QAAI,SAAS,SAAS;AACpB,8BACE,IAAI,MACF,iBAAiB,SAAS,eAAe,SAAS,GAAG,8BAA8B,SAAS,QAAQ,MAAM,KAAK,SAAS,QAAQ,IAAI,GACrI,EACD,KACD;AACD;;AAGF,gBACE;KAAE,GAAG;KAAS,UAAU,SAAS;KAAI,EAGrC,SACD;KACD,CACD,OAAO,QAAiB;IACvB,MAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;AAI5D,6BACE,IAAI,MACF,uCAAuC,SAAS,IAAI,MACrD,EACD,KACD;KACD;KAEP,CAAC;EAMA,OAAO,OAAO;EACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BH,eAAe,gBACb,UACA,WACA,WAIC;CACD,IAAI;AACJ,KAAI,UAAU,KAAK,SAAS,KAAK,EAC/B,MAAK;KAaL,OADe,MAAM,UAAU,OAAO,UAAU,EAAE,UAAU,MAAM,CAAC,EACvD;CAId,MAAM,UAAU,UAAU,GAAG;AAC7B,QAAO;EAAE;EAAI;EAAS"}