@cosmicdrift/kumiko-http 0.286.0 → 0.288.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-http",
-  "version": "0.286.0",
+  "version": "0.288.0",
   "description": "SSRF-safe egress fetch for Kumiko: a single egress(policy) entry point that enforces external/internal/tenant-supplied host policy, DNS-rebinding-safe resolve-then-pin, and no external runtime dependencies.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "export isPublicHost for create-time SSRF precheck without a real fetch",
+    "detail": "Adds `isPublicHost(raw: string, lookupFn?: typeof lookup): Promise<boolean>` to\n`@cosmicdrift/kumiko-http` (and re-exported from `@cosmicdrift/kumiko-framework/http`).\nIt runs the same range-table and DNS-rebinding-safe single-resolution check\n`egress()` uses internally via `resolvePublicHost`, but performs no connection —\nuseful for validating tenant-supplied URLs (e.g. webhook registration) up front.\nNever throws: parse failures, non-http(s) schemes, embedded credentials, DNS\nfailures, and blocked ranges all resolve to `false` rather than rejecting."
+  },
   {
     "version": "0.284.0",
     "type": "improvement",

package/src/index.ts

@@ -1,2 +1,3 @@
 export { egress } from "./egress";
 export type { EgressPolicy } from "./policy";
+export { isPublicHost } from "./policy";

package/src/policy.ts

@@ -1,8 +1,9 @@
 // Egress trust boundary. `EgressPolicy` and the checks below back the single
-// exported way to speak outward, `egress()` in ./egress.ts — this module and
-// its exports stay off the package's public barrel (index.ts) on purpose:
-// call sites bind a policy once via `egress(policy)` and never see the range
-// table or the allowlist check directly.
+// exported way to speak outward, `egress()` in ./egress.ts. Only `isPublicHost`
+// reaches the package's public barrel (index.ts), as a boolean pre-check for
+// create-time validation — call sites otherwise bind a policy once via
+// `egress(policy)` and never see the range table or the allowlist check
+// directly.
 //
 // `external` and `tenant-supplied` resolve to the identical set of checks
 // below (deny private/reserved/link-local + no redirects). They stay
@@ -177,6 +178,25 @@ export async function resolvePublicHost(
   return { address: chosen.address, family: chosen.family === 6 ? 6 : 4 };
 }
 
+// Create-time validation for tenant-supplied URLs (e.g. webhook registration)
+// where rejecting at registration is better UX than failing later at fetch
+// time. Runs the same resolution as `egress()` without connecting anywhere,
+// and never throws — bad input (unparsable URL, non-http(s) scheme, embedded
+// credentials, DNS failure, blocked range) all just resolve to `false`.
+export async function isPublicHost(
+  raw: string,
+  lookupFn: typeof lookup = lookup,
+): Promise<boolean> {
+  try {
+    const url = new URL(raw);
+    assertHttpScheme(url);
+    await resolvePublicHost(url, lookupFn);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // Explicit allowlist check for `internal` — the hostname (not the resolved
 // IP) must appear verbatim (case-insensitive) in `allowHosts`. No range
 // check: `internal` targets are deliberately private/cluster-local.