@peac/protocol 0.16.4 → 0.16.5

package/dist/_internal/address-policy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Address policy for outbound key and pointer fetches.
+ *
+ * An address is allowed only when it is a global unicast address outside every
+ * block in the IANA IPv4 and IPv6 Special-Purpose Address Registries (RFC 6890
+ * and updates). IPv4-mapped IPv6 addresses (::ffff:0:0/96) and NAT64
+ * well-known prefix addresses (64:ff9b::/96) are judged by the embedded IPv4
+ * address. Anything that does not parse as an address is refused.
+ *
+ * Pure function: no I/O, runtime-neutral.
+ */
+export type AddressBlockReason = 'private_ip' | 'loopback' | 'link_local';
+export type AddressVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: AddressBlockReason;
+};
+/**
+ * Classify an IP address string against the address policy.
+ */
+export declare function classifyAddress(ip: string): AddressVerdict;
+/**
+ * Return the IP literal carried by a URL hostname (brackets removed), or null
+ * for a domain name. WHATWG URL parsing has already normalised IPv4 forms.
+ */
+export declare function hostIpLiteral(hostname: string): string | null;
+//# sourceMappingURL=address-policy.d.ts.map

package/dist/_internal/address-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-policy.d.ts","sourceRoot":"","sources":["../../src/_internal/address-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAE1E,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAmJhG;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAM1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI7D"}

package/dist/index.cjs

@@ -1530,6 +1530,138 @@ async function fetchDiscovery(issuerUrl) {
     );
   }
 }
+
+// src/_internal/address-policy.ts
+var IPV4_OCTET = /^(?:0|[1-9]\d{0,2})$/;
+var IPV6_GROUP = /^[0-9a-fA-F]{1,4}$/;
+function parseIPv4(text) {
+  const parts = text.split(".");
+  if (parts.length !== 4) return null;
+  let value = 0;
+  for (const part of parts) {
+    if (!IPV4_OCTET.test(part)) return null;
+    const octet = Number(part);
+    if (octet > 255) return null;
+    value = value * 256 + octet;
+  }
+  return value;
+}
+function parseGroups(text) {
+  if (text === "") return [];
+  const groups = [];
+  for (const group of text.split(":")) {
+    if (!IPV6_GROUP.test(group)) return null;
+    groups.push(parseInt(group, 16));
+  }
+  return groups;
+}
+function parseIPv6(text) {
+  if (text.length === 0 || text.length > 45) return null;
+  let body = text;
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon === -1) return null;
+  const last = body.slice(lastColon + 1);
+  if (last.includes(".")) {
+    const v4 = parseIPv4(last);
+    if (v4 === null) return null;
+    body = `${body.slice(0, lastColon + 1)}${Math.floor(v4 / 65536).toString(16)}:${(v4 % 65536).toString(16)}`;
+  }
+  const halves = body.split("::");
+  if (halves.length > 2) return null;
+  const head = parseGroups(halves[0]);
+  if (head === null) return null;
+  if (halves.length === 1) return head.length === 8 ? head : null;
+  const tail = parseGroups(halves[1]);
+  if (tail === null) return null;
+  const fill = 8 - head.length - tail.length;
+  if (fill < 1) return null;
+  return [...head, ...new Array(fill).fill(0), ...tail];
+}
+var IPV4_BLOCKS = [
+  ["0.0.0.0", 8, "private_ip"],
+  ["10.0.0.0", 8, "private_ip"],
+  ["100.64.0.0", 10, "private_ip"],
+  ["127.0.0.0", 8, "loopback"],
+  ["169.254.0.0", 16, "link_local"],
+  ["172.16.0.0", 12, "private_ip"],
+  ["192.0.0.0", 24, "private_ip"],
+  ["192.0.2.0", 24, "private_ip"],
+  ["192.31.196.0", 24, "private_ip"],
+  ["192.52.193.0", 24, "private_ip"],
+  ["192.88.99.0", 24, "private_ip"],
+  ["192.168.0.0", 16, "private_ip"],
+  ["192.175.48.0", 24, "private_ip"],
+  ["198.18.0.0", 15, "private_ip"],
+  ["198.51.100.0", 24, "private_ip"],
+  ["203.0.113.0", 24, "private_ip"],
+  ["224.0.0.0", 4, "private_ip"],
+  ["240.0.0.0", 4, "private_ip"]
+];
+var IPV4_BLOCK_TABLE = IPV4_BLOCKS.map(([network, prefix, reason]) => {
+  const base = parseIPv4(network);
+  const size = 2 ** (32 - prefix);
+  return { start: base, end: base + size - 1, reason };
+});
+function classifyIPv4(value) {
+  for (const block of IPV4_BLOCK_TABLE) {
+    if (value >= block.start && value <= block.end) {
+      return { allowed: false, reason: block.reason };
+    }
+  }
+  return { allowed: true };
+}
+function matchesPrefix(groups, network, bits) {
+  for (let i = 0; i < 8; i++) {
+    const bitsHere = Math.min(16, Math.max(0, bits - 16 * i));
+    if (bitsHere === 0) return true;
+    const mask = 65535 << 16 - bitsHere & 65535;
+    if ((groups[i] & mask) !== (network[i] & mask)) return false;
+  }
+  return true;
+}
+function v6(text) {
+  return parseIPv6(text);
+}
+var GLOBAL_UNICAST_V6 = v6("2000::");
+var IPV6_BLOCKS_IN_GLOBAL = [
+  [v6("2001::"), 23],
+  [v6("2001:db8::"), 32],
+  [v6("2002::"), 16],
+  [v6("2620:4f:8000::"), 48],
+  [v6("3fff::"), 20]
+];
+var IPV6_LOOPBACK = v6("::1");
+var IPV6_LINK_LOCAL = v6("fe80::");
+var IPV4_MAPPED = v6("::ffff:0:0");
+var NAT64_WELL_KNOWN = v6("64:ff9b::");
+function classifyIPv6(groups) {
+  if (matchesPrefix(groups, IPV4_MAPPED, 96) || matchesPrefix(groups, NAT64_WELL_KNOWN, 96)) {
+    return classifyIPv4(groups[6] * 65536 + groups[7]);
+  }
+  if (!matchesPrefix(groups, GLOBAL_UNICAST_V6, 3)) {
+    if (matchesPrefix(groups, IPV6_LOOPBACK, 128)) return { allowed: false, reason: "loopback" };
+    if (matchesPrefix(groups, IPV6_LINK_LOCAL, 10)) return { allowed: false, reason: "link_local" };
+    return { allowed: false, reason: "private_ip" };
+  }
+  for (const [network, bits] of IPV6_BLOCKS_IN_GLOBAL) {
+    if (matchesPrefix(groups, network, bits)) return { allowed: false, reason: "private_ip" };
+  }
+  return { allowed: true };
+}
+function classifyAddress(ip) {
+  const v4 = parseIPv4(ip);
+  if (v4 !== null) return classifyIPv4(v4);
+  const groups = parseIPv6(ip);
+  if (groups !== null) return classifyIPv6(groups);
+  return { allowed: false, reason: "private_ip" };
+}
+function hostIpLiteral(hostname) {
+  if (hostname.startsWith("[") && hostname.endsWith("]")) return hostname.slice(1, -1);
+  if (/^[0-9.]+$/.test(hostname)) return hostname;
+  return null;
+}
+
+// src/ssrf-safe-fetch.ts
 var cachedCapabilities = null;
 function getSSRFCapabilities() {
   if (cachedCapabilities) {
@@ -1547,9 +1679,9 @@ function detectCapabilities() {
       networkIsolation: false,
       protectionLevel: "full",
       notes: [
-        "Full SSRF protection available via Node.js dns module",
-        "DNS resolution checked before HTTP connection",
-        "All RFC 1918 private ranges blocked"
+        "Hostnames are resolved once via the Node.js dns module",
+        "Every resolved address must be a global unicast address",
+        "The connection is made only to a vetted address"
       ]
     };
   }
@@ -1627,61 +1759,16 @@ function detectCapabilities() {
 function resetSSRFCapabilitiesCache() {
   cachedCapabilities = null;
 }
-function parseIPv4(ip) {
-  const parts = ip.split(".");
-  if (parts.length !== 4) return null;
-  const octets = [];
-  for (const part of parts) {
-    const num = parseInt(part, 10);
-    if (isNaN(num) || num < 0 || num > 255) return null;
-    octets.push(num);
-  }
-  return { octets };
-}
-function isInCIDR(ip, cidr) {
-  const [rangeStr, maskStr] = cidr.split("/");
-  const range = parseIPv4(rangeStr);
-  if (!range) return false;
-  const maskBits = parseInt(maskStr, 10);
-  if (isNaN(maskBits) || maskBits < 0 || maskBits > 32) return false;
-  const ipNum = ip.octets[0] << 24 | ip.octets[1] << 16 | ip.octets[2] << 8 | ip.octets[3];
-  const rangeNum = range.octets[0] << 24 | range.octets[1] << 16 | range.octets[2] << 8 | range.octets[3];
-  const mask = maskBits === 0 ? 0 : ~((1 << 32 - maskBits) - 1);
-  return (ipNum & mask) === (rangeNum & mask);
-}
-function isIPv6Loopback(ip) {
-  const normalized = ip.toLowerCase().replace(/^::ffff:/, "");
-  return normalized === "::1" || normalized === "0:0:0:0:0:0:0:1";
-}
-function isIPv6LinkLocal(ip) {
-  const normalized = ip.toLowerCase();
-  return normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb");
-}
 function isBlockedIP(ip) {
-  const ipv4Match = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
-  const effectiveIP = ipv4Match ? ipv4Match[1] : ip;
-  const ipv4 = parseIPv4(effectiveIP);
-  if (ipv4) {
-    if (isInCIDR(ipv4, "10.0.0.0/8") || isInCIDR(ipv4, "172.16.0.0/12") || isInCIDR(ipv4, "192.168.0.0/16")) {
-      return { blocked: true, reason: "private_ip" };
-    }
-    if (isInCIDR(ipv4, "127.0.0.0/8")) {
-      return { blocked: true, reason: "loopback" };
-    }
-    if (isInCIDR(ipv4, "169.254.0.0/16")) {
-      return { blocked: true, reason: "link_local" };
-    }
-    return { blocked: false };
-  }
-  if (isIPv6Loopback(ip)) {
-    return { blocked: true, reason: "loopback" };
-  }
-  if (isIPv6LinkLocal(ip)) {
-    return { blocked: true, reason: "link_local" };
-  }
-  return { blocked: false };
+  const verdict = classifyAddress(ip);
+  return verdict.allowed ? { blocked: false } : { blocked: true, reason: verdict.reason };
 }
 async function resolveHostname(hostname) {
+  const literal = hostIpLiteral(hostname);
+  if (literal !== null) {
+    const nodeRuntime = typeof process !== "undefined" && Boolean(process.versions?.node);
+    return { ok: true, ips: [literal], browser: !nodeRuntime };
+  }
   if (typeof process !== "undefined" && process.versions?.node) {
     try {
       const dns = await import('dns');
@@ -1712,7 +1799,10 @@ async function resolveHostname(hostname) {
           message: `DNS resolution failed for ${hostname}: ${ipv4Error.message}`
         };
       }
-      return { ok: true, ips: [], browser: false };
+      return {
+        ok: false,
+        message: `DNS resolution returned no addresses for ${hostname}`
+      };
     } catch (err) {
       return {
         ok: false,
@@ -1722,6 +1812,88 @@ async function resolveHostname(hostname) {
   }
   return { ok: true, ips: [], browser: true };
 }
+var NULL_BODY_STATUSES = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
+async function discardBody(response) {
+  await response.body?.cancel();
+}
+async function fetchFromVettedAddresses(url, addresses, headers, signal) {
+  const https = await import('https');
+  const { isIP } = await import('net');
+  const target = new URL(url);
+  const host = hostIpLiteral(target.hostname) ?? target.hostname;
+  if (addresses.length === 0 || isIP(host) !== 0 && !addresses.includes(host)) {
+    throw new Error(`Refusing to connect to an address that was not vetted: ${host}`);
+  }
+  const entries = addresses.map((address) => ({
+    address,
+    family: address.includes(":") ? 6 : 4
+  }));
+  const lookup = (_hostname, options, callback) => {
+    if (options.all) {
+      callback(null, entries);
+    } else {
+      callback(null, entries[0].address, entries[0].family);
+    }
+  };
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      target,
+      { method: "GET", headers, lookup, agent: false, signal },
+      (res) => {
+        try {
+          const status = res.statusCode ?? 0;
+          const responseHeaders = new Headers();
+          for (const [name, value] of Object.entries(res.headers)) {
+            if (value === void 0) continue;
+            if (Array.isArray(value)) {
+              for (const item of value) responseHeaders.append(name, item);
+            } else {
+              responseHeaders.set(name, value);
+            }
+          }
+          if (NULL_BODY_STATUSES.has(status)) {
+            res.resume();
+            resolve(new Response(null, { status, headers: responseHeaders }));
+            return;
+          }
+          let settled = false;
+          const body = new ReadableStream({
+            start(controller) {
+              res.on("data", (chunk) => {
+                if (settled) return;
+                controller.enqueue(new Uint8Array(chunk));
+                if ((controller.desiredSize ?? 0) <= 0) res.pause();
+              });
+              res.on("end", () => {
+                if (settled) return;
+                settled = true;
+                controller.close();
+              });
+              res.on("error", (err) => {
+                if (settled) return;
+                settled = true;
+                controller.error(err);
+              });
+            },
+            pull() {
+              res.resume();
+            },
+            cancel() {
+              settled = true;
+              res.destroy();
+            }
+          });
+          resolve(new Response(body, { status, headers: responseHeaders }));
+        } catch (err) {
+          res.destroy();
+          reject(err);
+        }
+      }
+    );
+    req.on("error", reject);
+    req.end();
+  });
+}
 async function ssrfSafeFetch(url, options = {}) {
   const {
     timeoutMs = kernel.VERIFIER_LIMITS.fetchTimeoutMs,
@@ -1770,38 +1942,44 @@ async function ssrfSafeFetch(url, options = {}) {
       blockedUrl: url
     };
   }
-  if (!dnsResult.browser) {
-    for (const ip of dnsResult.ips) {
-      const blockResult = isBlockedIP(ip);
-      if (blockResult.blocked) {
-        return {
-          ok: false,
-          reason: blockResult.reason,
-          message: `Blocked ${blockResult.reason} address: ${ip} for ${url}`,
-          blockedUrl: url
-        };
-      }
+  for (const ip of dnsResult.ips) {
+    const blockResult = isBlockedIP(ip);
+    if (blockResult.blocked) {
+      return {
+        ok: false,
+        reason: blockResult.reason,
+        message: `Blocked ${blockResult.reason} address: ${ip} for ${url}`,
+        blockedUrl: url
+      };
     }
   }
   let redirectCount = 0;
   let currentUrl = url;
+  let vettedAddresses = dnsResult.browser ? null : dnsResult.ips;
   const originalOrigin = parsedUrl.origin;
   while (true) {
     try {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-      const response = await fetch(currentUrl, {
-        headers: {
-          Accept: "application/json, text/plain",
-          ...headers
-        },
+      const requestHeaders = {
+        Accept: "application/json, text/plain",
+        ...headers
+      };
+      const response = vettedAddresses === null ? await fetch(currentUrl, {
+        headers: requestHeaders,
         signal: controller.signal,
         redirect: "manual"
         // Handle redirects manually for security
-      });
+      }) : await fetchFromVettedAddresses(
+        currentUrl,
+        vettedAddresses,
+        requestHeaders,
+        controller.signal
+      );
       clearTimeout(timeoutId);
       if (response.status >= 300 && response.status < 400) {
         const location = response.headers.get("location");
+        await discardBody(response);
         if (!location) {
           return {
             ok: false,
@@ -1870,24 +2048,24 @@ async function ssrfSafeFetch(url, options = {}) {
             blockedUrl: redirectUrl.href
           };
         }
-        if (!redirectDnsResult.browser) {
-          for (const ip of redirectDnsResult.ips) {
-            const blockResult = isBlockedIP(ip);
-            if (blockResult.blocked) {
-              return {
-                ok: false,
-                reason: blockResult.reason,
-                message: `Redirect to blocked ${blockResult.reason} address: ${ip}`,
-                blockedUrl: redirectUrl.href
-              };
-            }
+        for (const ip of redirectDnsResult.ips) {
+          const blockResult = isBlockedIP(ip);
+          if (blockResult.blocked) {
+            return {
+              ok: false,
+              reason: blockResult.reason,
+              message: `Redirect to blocked ${blockResult.reason} address: ${ip}`,
+              blockedUrl: redirectUrl.href
+            };
           }
         }
         currentUrl = redirectUrl.href;
+        vettedAddresses = redirectDnsResult.browser ? null : redirectDnsResult.ips;
         continue;
       }
       const contentLength = response.headers.get("content-length");
       if (contentLength && parseInt(contentLength, 10) > maxBytes) {
+        await discardBody(response);
         return {
           ok: false,
           reason: "response_too_large",
@@ -2118,6 +2296,25 @@ function mapSSRFError(reason, context) {
   }
   return { code, reason };
 }
+var CANONICAL_ED25519_X = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function jwkEntryProblem(entry) {
+  if (!isPlainObject(entry)) return "not an object";
+  if (entry.kty !== "OKP") return "kty must be OKP";
+  if (entry.crv !== "Ed25519") return "crv must be Ed25519";
+  if (typeof entry.x !== "string" || !CANONICAL_ED25519_X.test(entry.x)) {
+    return "x must be a canonical base64url 32-byte value";
+  }
+  if (Object.prototype.hasOwnProperty.call(entry, "d")) return "private key member d present";
+  if (entry.kid !== void 0 && typeof entry.kid !== "string") return "kid must be a string";
+  if (entry.use !== void 0 && entry.use !== "sig") return "use must be sig";
+  if (entry.alg !== void 0 && entry.alg !== "EdDSA" && entry.alg !== "Ed25519") {
+    return "alg must be EdDSA or Ed25519";
+  }
+  return null;
+}
 async function resolveJWKS(issuerUrl, options) {
   const cacheTtlMs = options?.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
   const maxCacheEntries = options?.maxCacheEntries ?? DEFAULT_MAX_CACHE_ENTRIES;
@@ -2207,9 +2404,9 @@ async function resolveJWKS(issuerUrl, options) {
       blockedUrl: jwksResult.blockedUrl
     };
   }
-  let jwks;
+  let parsed;
   try {
-    jwks = JSON.parse(jwksResult.body);
+    parsed = JSON.parse(jwksResult.body);
   } catch {
     return {
       ok: false,
@@ -2217,20 +2414,37 @@ async function resolveJWKS(issuerUrl, options) {
       message: "JWKS response is not valid JSON"
     };
   }
-  if (!jwks.keys || !Array.isArray(jwks.keys)) {
+  const rawKeys = isPlainObject(parsed) ? parsed.keys : void 0;
+  if (!Array.isArray(rawKeys)) {
     return {
       ok: false,
       code: "E_VERIFY_JWKS_INVALID",
       message: "JWKS missing required keys array"
     };
   }
-  if (jwks.keys.length > kernel.VERIFIER_LIMITS.maxJwksKeys) {
+  if (rawKeys.length > kernel.VERIFIER_LIMITS.maxJwksKeys) {
     return {
       ok: false,
       code: "E_VERIFY_JWKS_TOO_MANY_KEYS",
-      message: `JWKS has too many keys: ${jwks.keys.length} > ${kernel.VERIFIER_LIMITS.maxJwksKeys}`
+      message: `JWKS has too many keys: ${rawKeys.length} > ${kernel.VERIFIER_LIMITS.maxJwksKeys}`
     };
   }
+  const validKeys = [];
+  const skipped = [];
+  rawKeys.forEach((entry, index) => {
+    const problem = jwkEntryProblem(entry);
+    if (problem === null) {
+      validKeys.push(entry);
+    } else {
+      skipped.push(`#${index}: ${problem}`);
+    }
+  });
+  if (skipped.length > 0) {
+    console.warn(
+      `[peac:jwks] Skipped ${skipped.length} invalid JWKS entr${skipped.length === 1 ? "y" : "ies"} for ${normalizedIssuer} (${skipped.join("; ")})`
+    );
+  }
+  const jwks = { keys: validKeys };
   const kidReuseError = checkKidReuse(normalizedIssuer, jwks, now);
   if (kidReuseError) {
     return {
@@ -3269,9 +3483,13 @@ async function fetchIssuerJWKS(issuerOrigin) {
   return {
     jwks: result.jwks,
     fromCache: result.fromCache,
-    rawBytes: result.rawBytes
+    rawBytes: result.rawBytes,
+    revokedKeys: result.revokedKeys
   };
 }
+function findRevokedKey(kid, revokedKeys) {
+  return revokedKeys?.find((rk) => rk.kid === kid);
+}
 async function verifyReceiptCore(options) {
   const {
     receipt,
@@ -3441,6 +3659,19 @@ async function verifyReceiptCore(options) {
         from_cache: jwksResult.fromCache,
         keys_count: jwksResult.jwks.keys.length
       });
+      const revokedPinned = findRevokedKey(kid, jwksResult.revokedKeys);
+      if (revokedPinned) {
+        builder.fail("key.resolve", "E_REVOKED_KEY_USED", {
+          kid,
+          revoked_at: revokedPinned.revoked_at,
+          ...revokedPinned.reason && { reason: revokedPinned.reason }
+        });
+        builder.failure("key_not_found", normalizedIssuer, kid);
+        return {
+          valid: false,
+          report: includeMeta ? builder.addTimestamp().build() : builder.build()
+        };
+      }
       const jwk = jwksResult.jwks.keys.find((k) => k.kid === kid);
       if (!jwk) {
         builder.fail("key.resolve", "E_VERIFY_KEY_NOT_FOUND", {
@@ -3502,6 +3733,19 @@ async function verifyReceiptCore(options) {
       from_cache: jwksResult.fromCache,
       keys_count: jwksResult.jwks.keys.length
     });
+    const revoked = findRevokedKey(kid, jwksResult.revokedKeys);
+    if (revoked) {
+      builder.fail("key.resolve", "E_REVOKED_KEY_USED", {
+        kid,
+        revoked_at: revoked.revoked_at,
+        ...revoked.reason && { reason: revoked.reason }
+      });
+      builder.failure("key_not_found", normalizedIssuer, kid);
+      return {
+        valid: false,
+        report: includeMeta ? builder.addTimestamp().build() : builder.build()
+      };
+    }
     const jwk = jwksResult.jwks.keys.find((k) => k.kid === kid);
     if (!jwk) {
       builder.fail("key.resolve", "E_VERIFY_KEY_NOT_FOUND", {