@sonordev/contracts 2.10.0 → 2.11.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2.11.0
+
+- Add `@sonordev/contracts/public-url-host`: the pure `isBlockedPublicUrlHost` predicate shared by Sonor and Signal, including private IPv4 and IPv6 ranges, mapped/compatible IPv4, and local hostname suffixes. It uses the standard URL parser without Node dependencies. Scoped IPv6 addresses are refused without throwing. Callers retain URL validation, DNS resolution/address pinning, and redirect protections.
+
 ## 2.10.0
 
 A minor release: two new functions in `@sonordev/contracts/page-titles`. Every entry is otherwise unchanged.

package/README.md

@@ -37,6 +37,22 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/page-titles` | A page's own name: its title without the brand (`titleHead`), a readable label from a slug (`slugLabel`), whether a value is a route placeholder like `:slug` (`isRoutePlaceholder`), whether a value is a page's address and not its name (`isPageAddress`), and whether a stored title is a name when every piece between its pipes is judged (`isPageName`) | Signal's site-architecture writer, the agency site kit's portfolio components |
 | `@sonordev/contracts/broadcast-layouts` | Which Broadcast card layouts are drawn (centered `headline`, low `anchor`), which retired IDs still read and what each draws as (`normalizeArticleCoverLayout`), the Broadcast styles, and the review compositions with the frozen draw that gives each review its own (`reviewCardVariationFromDigest`) | the Sonor API's card renderers and settings, Signal's agent tools, the dashboard's pickers |
 | `@sonordev/contracts/publication-branding` | What a publication's branding may hold and what a change may set (`createPublicationBrandingValidator`), how a change merges, the editorial charter, and safe font stacks | the Sonor API stores and resolves it, Signal checks an agent's change before filing it, the dashboard edits it |
+| `@sonordev/contracts/public-url-host` | Which literal hosts are refused as public fetch destinations (`isBlockedPublicUrlHost`) | the Sonor API and Signal's URL validators and network fetchers |
+
+## Public URL hosts
+
+`isBlockedPublicUrlHost(host)` shares the APIs' loopback, private IPv4,
+link-local, carrier-grade NAT, multicast/reserved IPv4, private IPv6 and local
+hostname checks. It checks IPv4-mapped and IPv4-compatible IPv6 destinations
+too, with or without brackets. It uses the standard `URL` parser, with no
+Node, DNS or network dependencies. Scoped IPv6 addresses are refused.
+
+Pass the **parsed `URL.hostname`**, so alternate IPv4 spellings such as
+`127.1` and `0x7f000001` are normalized first, or pass a DNS result's address.
+This predicate doesn't validate a URL or trim a raw string. A `false` result
+isn't proof a destination is public: the fetcher still validates the protocol,
+credentials and port, checks the DNS addresses it connects to, and applies its
+redirect policy on each hop. Those network protections stay in the APIs.
 
 ## Schema placeholders
 
@@ -740,9 +756,10 @@ valid, so the validator lives here once.
 
 ```ts
 import { createPublicationBrandingValidator } from '@sonordev/contracts/publication-branding'
+import { isBlockedPublicUrlHost } from '@sonordev/contracts/public-url-host'
 
-// Bind it once, to the server's own private-address guard.
-const branding = createPublicationBrandingValidator({ isBlockedHost })
+// Bind it once to the same literal-host policy both APIs use.
+const branding = createPublicationBrandingValidator({ isBlockedHost: isBlockedPublicUrlHost })
 
 branding.validatePublicationBrandingPatch({ colors: { primary: '#ABC' } })
 // { colors: { primary: '#aabbcc' } }
@@ -755,8 +772,10 @@ branding.mergePublicationBrandingPatch(saved, { identity: { logos: { dark: null
 - **`createPublicationBrandingValidator({ isBlockedHost })`** returns the
   validator. A URL leaf must be a public HTTPS URL without credentials;
   whether its host is private (loopback, a LAN range, link-local,
-  `localhost`) is the caller's guard, because that check needs Node. It gets
-  `new URL(value).hostname`, so IPv6 keeps its brackets.
+  `localhost`) uses the injected guard. Both APIs pass the shared
+  `public-url-host` predicate, which doesn't need Node. It gets
+  `new URL(value).hostname`, so IPv6 keeps its brackets. DNS and connection
+  checks remain the responsibility of the fetcher.
 - **`validatePublicationBranding`** reads a whole saved profile.
   **`validatePublicationBrandingPatch`** reads a change: a leaf set to `null`
   clears that override, and a card layout must be one that's drawn today.

package/dist/public-url-host.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The shared literal-host SSRF policy. Pass URL.hostname (which canonicalizes
+ * numeric IPv4 spellings), or an address returned by a DNS lookup. IPv6 may
+ * have the brackets URL.hostname retains. This isn't a URL validator and
+ * doesn't trim input, resolve DNS, follow redirects or open a connection.
+ * Callers still enforce their protocol/port rules and check or pin the DNS
+ * addresses used by each connection; a false result alone can't prove a
+ * destination is public.
+ */
+export declare function isBlockedPublicUrlHost(rawHost: string): boolean;

package/dist/public-url-host.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// src/contracts/public-url-host.ts
+function isPrivateIpv4(a, b) {
+  return a === 127 || a === 10 || a === 0 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127 || a >= 224;
+}
+function ipv6Words(host) {
+  if (!host.includes(":") || !/^[a-f\d:.]+$/.test(host)) return null;
+  let canonical;
+  try {
+    canonical = new URL(`http://[${host}]/`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const sides = canonical.split("::");
+  const left = sides[0] ? sides[0].split(":") : [];
+  const right = sides.length > 1 && sides[1] ? sides[1].split(":") : [];
+  return [...left, ...Array(sides.length > 1 ? 8 - left.length - right.length : 0).fill("0"), ...right].map((word) => parseInt(word, 16));
+}
+function isBlockedPublicUrlHost(rawHost) {
+  const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
+  const blockedName = host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal");
+  if (host.includes(":") && host.includes("%")) return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  const blockedIp = !!ipv4 && isPrivateIpv4(Number(ipv4[1]), Number(ipv4[2]));
+  const words = ipv6Words(host);
+  const blockedIpv6 = !!words && // Unspecified/loopback, unique-local, link-local, deprecated site-local
+  // and multicast destinations aren't public logo/webhook endpoints.
+  (words.every((word) => word === 0) || words.slice(0, 7).every((word) => word === 0) && words[7] === 1 || (words[0] & 65024) === 64512 || (words[0] & 65472) === 65152 || (words[0] & 65472) === 65216 || (words[0] & 65280) === 65280 || // IPv4-mapped and older IPv4-compatible forms carry an IPv4 destination.
+  words.slice(0, 5).every((word) => word === 0) && [0, 65535].includes(words[5]) && isPrivateIpv4(words[6] >> 8, words[6] & 255));
+  return blockedName || blockedIp || blockedIpv6;
+}
+
+exports.isBlockedPublicUrlHost = isBlockedPublicUrlHost;

package/dist/public-url-host.mjs

@@ -0,0 +1,32 @@
+// src/contracts/public-url-host.ts
+function isPrivateIpv4(a, b) {
+  return a === 127 || a === 10 || a === 0 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127 || a >= 224;
+}
+function ipv6Words(host) {
+  if (!host.includes(":") || !/^[a-f\d:.]+$/.test(host)) return null;
+  let canonical;
+  try {
+    canonical = new URL(`http://[${host}]/`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const sides = canonical.split("::");
+  const left = sides[0] ? sides[0].split(":") : [];
+  const right = sides.length > 1 && sides[1] ? sides[1].split(":") : [];
+  return [...left, ...Array(sides.length > 1 ? 8 - left.length - right.length : 0).fill("0"), ...right].map((word) => parseInt(word, 16));
+}
+function isBlockedPublicUrlHost(rawHost) {
+  const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
+  const blockedName = host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal");
+  if (host.includes(":") && host.includes("%")) return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  const blockedIp = !!ipv4 && isPrivateIpv4(Number(ipv4[1]), Number(ipv4[2]));
+  const words = ipv6Words(host);
+  const blockedIpv6 = !!words && // Unspecified/loopback, unique-local, link-local, deprecated site-local
+  // and multicast destinations aren't public logo/webhook endpoints.
+  (words.every((word) => word === 0) || words.slice(0, 7).every((word) => word === 0) && words[7] === 1 || (words[0] & 65024) === 64512 || (words[0] & 65472) === 65152 || (words[0] & 65472) === 65216 || (words[0] & 65280) === 65280 || // IPv4-mapped and older IPv4-compatible forms carry an IPv4 destination.
+  words.slice(0, 5).every((word) => word === 0) && [0, 65535].includes(words[5]) && isPrivateIpv4(words[6] >> 8, words[6] & 255));
+  return blockedName || blockedIp || blockedIpv6;
+}
+
+export { isBlockedPublicUrlHost };

package/dist/publication-branding.d.ts

@@ -107,7 +107,7 @@ export interface PublicationBrandingValidatorOptions {
     /**
      * True when a URL's hostname must never be stored as a logo or publisher
      * URL: loopback, private and link-local ranges, `localhost` and the like.
-     * Each API passes its own server-side SSRF host guard. It receives
+     * Each API passes the shared `public-url-host` policy. It receives
      * `new URL(value).hostname`, so IPv6 keeps its brackets.
      */
     isBlockedHost: (hostname: string) => boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.10.0",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, and what a publication's branding may hold. Pure functions, no dependencies.",
+  "version": "2.11.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, what a publication's branding may hold, and which literal hosts are refused as public fetch destinations. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -141,6 +141,11 @@
       "types": "./dist/publication-branding.d.ts",
       "import": "./dist/publication-branding.mjs",
       "require": "./dist/publication-branding.js"
+    },
+    "./public-url-host": {
+      "types": "./dist/public-url-host.d.ts",
+      "import": "./dist/public-url-host.mjs",
+      "require": "./dist/public-url-host.js"
     }
   },
   "typesVersions": {