haechi-auth-jwt 0.2.1 → 0.3.0

package/README.md

@@ -2,6 +2,14 @@
 
 A **headless** JWKS bearer (JWT) `authProvider` for Haechi. It verifies an `Authorization: Bearer <jwt>` against an issuer's JWKS and resolves a **PII-safe identity** — using `node:` builtins only (no `jose`). Published independently as `haechi-auth-jwt`; it adds **no runtime dependency** to core.
 
+## Install
+
+```sh
+npm install haechi haechi-auth-jwt   # peer: haechi >=0.8.0 <2.0.0
+```
+
+**`haechi` (the core) must be installed** — it is a peer dependency, not bundled. This satellite imports `haechi/runtime` and reuses your installed `haechi` instance (single crypto/identity surface), so install the core alongside it.
+
 ## Usage
 
 ```js
@@ -32,14 +40,14 @@ Wired via **injection** (`auth.provider: "external"`); dynamic loading stays ban
 - **The token never picks the algorithm.** The verifier uses the configured `algorithms` allowlist and the JWK type. `alg: "none"` is rejected; HMAC (`HS*`) is not allowed (alg-confusion defence); a JWKS public key is only ever used with its matching asymmetric algorithm. ES256 uses `dsaEncoding: "ieee-p1363"` (a JWS ES256 signature is raw R‖S, which `node:crypto` otherwise mis-verifies).
 - **`kid` required**, key selected by `kid`. **RSA ≥ 2048 bits.** JWK `use` must be `sig`; `key_ops` must not include `encrypt`/`decrypt`. Only JWS is accepted (`typ: "JWE"` rejected).
 - **Claims fully validated:** `iss` exact match; `aud` (string or array) must contain the configured audience; `sub` required non-empty; `exp`/`nbf` required and checked with a bounded `clockSkewSeconds` (default 60, **max 300**).
-- **JWKS fetching is SSRF-hardened:** `issuer` and `jwksUri` must be **HTTPS** and share a host (single-origin issuers only in 0.8); requests to private/loopback/link-local/metadata addresses are refused (literal host + resolved IPs); fetch has a timeout and a 1 MiB response cap; JSON parsing is depth-bounded; JWT segments are strict base64url.
+- **JWKS fetching is SSRF-hardened:** `issuer` and `jwksUri` must be **HTTPS**, and the JWKS host must equal the issuer host **or** be listed in `trustedEndpointHosts` (multi-origin / CDN-fronted IdPs — see below; empty by default ⇒ strict single-origin); requests to private/loopback/link-local/metadata addresses are refused (literal host + resolved IPs) regardless of the allowlist; fetch has a timeout and a 1 MiB response cap; JSON parsing is depth-bounded; JWT segments are strict base64url.
 - **JWKS cache is bounded:** TTL-cached; an unknown `kid` triggers at most one refetch per cooldown (no fetch-storm against the IdP).
 - **Identity is PII-safe (fail-closed):** a `cryptoProvider` with `hmac()` is required; `subjectHash`/`issuerHash` are keyed HMAC-SHA-256 (`haechi:identity:hash:v1`, built by core's `buildExternalIdentity`) — raw `sub`/`iss` are never stored or logged. `scopes` from the configured scope claim; `labels` from an allowlisted claim mapping.
 - **Fail-closed everywhere:** any verification error → `authenticate` returns `null` (deny), never throws into the request path, and echoes no token detail.
 
 ## `createJwtVerifier` (the reusable primitive)
 
-`createJwtVerifier(options)` is the standalone, audited JWS/JWKS verification path that `createJwtAuthProvider` is built on. It takes the verification-only options (`issuer`, `audience`, `jwksUri`, `algorithms`, `clockSkewSeconds`, JWKS cache/fetch knobs, `now`) — **no `cryptoProvider`, `claimMappings`, or `allowedLabelKeys`** (those stay in the provider) — and returns `{ verify }`:
+`createJwtVerifier(options)` is the standalone, audited JWS/JWKS verification path that `createJwtAuthProvider` is built on. It takes the verification-only options (`issuer`, `audience`, `jwksUri`, `trustedEndpointHosts`, `algorithms`, `clockSkewSeconds`, JWKS cache/fetch knobs, `now`) — **no `cryptoProvider`, `claimMappings`, or `allowedLabelKeys`** (those stay in the provider) — and returns `{ verify }`:
 
 ```js
 const verifier = createJwtVerifier({ issuer, audience, jwksUri /* ... */ });
@@ -49,6 +57,35 @@ const claims2 = await verifier.verify(jwt, { expectedNonce }); // + OIDC nonce c
 
 `verify(jwt)` does exactly the 0.8 bearer work — signature + `alg`/`kid`/RSA-bits + `iss`/`aud`/`exp`/`nbf` — and returns the **validated claims object** (not an identity) or `null` on any failure (fully fail-closed). `nonce` is **not** part of the bearer surface: it is checked only when `expectedNonce` is passed, and is a no-op when omitted. This is the single verification path reused by the `haechi-auth-oidc` broker (0.9).
 
-## Scope (0.8)
+### `trustedEndpointHosts` (multi-origin / CDN-fronted IdPs)
+
+`trustedEndpointHosts` (an array of **bare hostnames**, default `[]`) lets an operator pin additional hosts that are allowed to serve this IdP's JWKS when the JWKS host differs from the issuer host — the common shape for a CDN-fronted or custom-domain IdP (Azure AD B2C, Auth0). A JWKS host is accepted **iff** it equals the issuer host **OR** it is listed in `trustedEndpointHosts`:
+
+```js
+const verifier = createJwtVerifier({
+  issuer: "https://login.contoso.com",                       // issuer host: login.contoso.com
+  audience: "haechi-gateway",
+  jwksUri: "https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_signin/discovery/v2.0/keys",
+  trustedEndpointHosts: ["contoso.b2clogin.com"]             // pin the differing JWKS host
+});
+```
+
+This option **relaxes ONLY the same-host string check**. Every other guard still runs **unconditionally**:
+
+- `jwksUri` must still be **`https`**.
+- The `isBlockedAddress` **SSRF guard** still refuses a private/loopback/link-local/metadata host (literal host at construction + every DNS-resolved address before each fetch) — you cannot allowlist `169.254.169.254` or a loopback host.
+- The set is **config-only**: it is built exclusively from the operator-supplied array, **never** from discovery- or JWKS-document content, so an attacker who controls the JWKS payload cannot introduce a new host.
+
+Each entry must be a bare hostname (no scheme, path, port, or whitespace) or construction throws. **Empty/absent ⇒ strict single-origin** (the JWKS host must equal the issuer host — the default, zero behavior change).
+
+## 한국어 (요약)
+
+이 위성에는 별도 `README.ko.md` 형제 파일이 없습니다(저장소의 다른 위성 README도 모두 영문 단독입니다). 영문-주 + 한국어-형제 관례에 따라 핵심 내용을 아래에 요약합니다.
+
+`createJwtVerifier`의 `trustedEndpointHosts`(bare 호스트명 배열, 기본 `[]`)는 운영자가 issuer 호스트와 다른 JWKS 호스트를 허용하도록 핀하는 옵션입니다(CDN-fronted / 커스텀 도메인 IdP — Azure AD B2C, Auth0). JWKS 호스트는 issuer 호스트와 같거나 `trustedEndpointHosts`에 포함될 때**만** 허용됩니다. 예: issuer `https://login.contoso.com`, jwksUri `https://contoso.b2clogin.com/.../keys`, `trustedEndpointHosts: ["contoso.b2clogin.com"]`.
+
+이 옵션은 **same-host 문자열 검사만 완화**합니다. `https` 요구, `isBlockedAddress` SSRF 가드(private/loopback/link-local/metadata 호스트 거부 — `169.254.169.254`나 loopback은 allowlist에 추가해도 거부됨)는 **무조건** 실행됩니다. 이 집합은 **설정 전용**으로 discovery/JWKS 문서 내용에서는 절대 만들어지지 않으므로, JWKS 페이로드를 장악한 공격자가 새 호스트를 주입할 수 없습니다. 비어 있거나 없으면 **엄격한 single-origin**(JWKS 호스트 == issuer 호스트)이 기본값입니다.
+
+## Scope
 
-Single-origin issuers only (issuer host == JWKS host). Multi-origin/CDN-fronted JWKS and full interactive OIDC (`haechi-auth-oidc`) are 0.9.
+Multi-origin / CDN-fronted JWKS is supported via `trustedEndpointHosts` (auth-jwt 0.3.0; see above). Full interactive OIDC (`haechi-auth-oidc`) is a separate satellite.

package/index.mjs

@@ -59,6 +59,66 @@ function parseHttpsUrl(value, label) {
   return url;
 }
 
+// Parse an IPv6 literal into its 16 octets (or null when it is not a valid IPv6
+// text form). This is the SOUND way to recognise an IPv4-mapped IPv6 address in
+// EVERY textual form: dotted (::ffff:127.0.0.1), HEX (::ffff:7f00:1), bracketed
+// ([::ffff:7f00:1], stripped by the caller), leading-zero (::ffff:7f00:0001),
+// mixed `::` compression, and case-insensitive ffff. We classify the last 32
+// bits as the embedded IPv4 ONLY when bytes 0..9 are zero and bytes 10..11 are
+// 0xffff (the ::ffff:0:0/96 IPv4-mapped prefix), so a genuinely public mapped
+// address (::ffff:8.8.8.8 == ::ffff:808:808) stays allowed and a non-mapped v6
+// (::ffff:0:7f00:1, NAT64 64:ff9b::…) is NOT mistaken for an embedded IPv4.
+//
+// Kept byte-for-behavior identical to packages/ssrf/index.mjs and
+// satellites/crypto-kms/vault.mjs (parity-tested) — see this module's header and
+// crypto-kms/ssrf-parity.test.mjs. The DELIBERATE 1.1 decoupling means each copy
+// carries this logic rather than importing haechi/ssrf.
+function ipv6ToBytes(str) {
+  let s = str;
+  // A trailing dotted IPv4 quad (::ffff:127.0.0.1) — peel it off into the final
+  // two hextets so the remaining text is pure hex groups.
+  let tailV4 = null;
+  if (s.includes(".")) {
+    const idx = s.lastIndexOf(":");
+    if (idx === -1) return null;
+    const quad = s.slice(idx + 1).split(".");
+    if (quad.length !== 4) return null;
+    const oct = quad.map(Number);
+    if (oct.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+    tailV4 = oct;
+    s = `${s.slice(0, idx + 1)}0:0`; // placeholder hextets; overwritten below
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null; // at most one "::"
+  const toGroups = (g) => (g === "" ? [] : g.split(":").map((h) => (/^[0-9a-fA-F]{1,4}$/.test(h) ? parseInt(h, 16) : NaN)));
+  const head = toGroups(halves[0]);
+  const tail = halves.length === 2 ? toGroups(halves[1]) : null;
+  if (head.some(Number.isNaN) || (tail && tail.some(Number.isNaN))) return null;
+  let groups;
+  if (tail === null) {
+    if (head.length !== 8) return null;
+    groups = head;
+  } else {
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0) return null;
+    groups = [...head, ...Array(missing).fill(0), ...tail];
+  }
+  if (groups.length !== 8) return null;
+  const bytes = [];
+  for (const g of groups) bytes.push((g >> 8) & 0xff, g & 0xff);
+  if (tailV4) { bytes[12] = tailV4[0]; bytes[13] = tailV4[1]; bytes[14] = tailV4[2]; bytes[15] = tailV4[3]; }
+  return bytes;
+}
+
+// Return the embedded IPv4 dotted quad of an IPv4-mapped IPv6 address, or null.
+function mappedIpv4(bare) {
+  const b = ipv6ToBytes(bare);
+  if (!b) return null;
+  for (let i = 0; i < 10; i += 1) if (b[i] !== 0) return null; // bytes 0..9 must be zero
+  if (b[10] !== 0xff || b[11] !== 0xff) return null;           // bytes 10..11 must be 0xffff
+  return `${b[12]}.${b[13]}.${b[14]}.${b[15]}`;
+}
+
 // Block literal addresses in private/loopback/link-local ranges + cloud metadata.
 // Applied to both a literal host in the URL and every DNS-resolved address.
 // Exported (additive, behavior-preserving — auth-jwt stays 0.2.0) so the
@@ -82,10 +142,11 @@ export function isBlockedAddress(host) {
   if (v === 6) {
     const h = bare.toLowerCase();
     if (h === "::1" || h === "::") return true;             // loopback / unspecified
-    if (h.startsWith("::ffff:")) {                          // IPv4-mapped
-      const mapped = h.slice("::ffff:".length);
-      if (isIP(mapped) === 4) return isBlockedAddress(mapped);
-    }
+    // IPv4-mapped IPv6 — normalise to the embedded IPv4 (handles dotted AND hex
+    // forms, e.g. ::ffff:127.0.0.1 and ::ffff:7f00:1) and run the v4 check, so a
+    // private/loopback/metadata target can't slip past as hex (P1-CR-002).
+    const mapped = mappedIpv4(bare);
+    if (mapped !== null) return isBlockedAddress(mapped);
     // Range-check the first hextet (startsWith("fe80") wrongly let fe81–febf
     // through): fe80::/10 link-local, fc00::/7 ULA, ff00::/8 multicast.
     const firstHextet = parseInt(h.split(":")[0] || "", 16);
@@ -152,6 +213,7 @@ export function createJwtVerifier(options = {}) {
     issuer,
     audience,
     jwksUri,
+    trustedEndpointHosts = [],
     algorithms = DEFAULT_ALGORITHMS,
     clockSkewSeconds = DEFAULT_CLOCK_SKEW_SECONDS,
     jwksTtlMs = DEFAULT_JWKS_TTL_MS,
@@ -171,9 +233,32 @@ export function createJwtVerifier(options = {}) {
     throw new Error("createJwtVerifier requires a non-empty audience");
   }
   const jwksUrl = parseHttpsUrl(jwksUri, "jwksUri");
-  if (jwksUrl.hostname.toLowerCase() !== issuerUrl.hostname.toLowerCase()) {
-    throw new Error("jwksUri host must equal the issuer host (single-origin issuers only in 0.8)");
+  // Operator-declared PINNED allowlist of additional hostnames permitted to
+  // serve this IdP's endpoints (e.g. an Azure AD B2C / Auth0 custom-domain JWKS
+  // host that differs from the issuer host). It RELAXES the same-host
+  // requirement ONLY — never the https or SSRF guards below — and is a fixed
+  // operator pin, so an attacker controlling the discovery/JWKS content cannot
+  // introduce a new host (the mix-up / SSRF defence stands). Empty/absent =>
+  // today's strict single-origin behavior (zero behavior change by default).
+  if (!Array.isArray(trustedEndpointHosts)) {
+    throw new Error("trustedEndpointHosts must be an array of bare hostnames");
+  }
+  const trustedHostSet = new Set();
+  for (const entry of trustedEndpointHosts) {
+    if (typeof entry !== "string" || !entry.trim()) {
+      throw new Error("each trustedEndpointHosts entry must be a non-empty hostname string");
+    }
+    if (/[\s/:]/.test(entry) || entry.includes("://")) {
+      throw new Error("each trustedEndpointHosts entry must be a bare hostname (no scheme, path, port, or whitespace)");
+    }
+    trustedHostSet.add(entry.toLowerCase());
+  }
+  const jwksHost = jwksUrl.hostname.toLowerCase();
+  if (jwksHost !== issuerUrl.hostname.toLowerCase() && !trustedHostSet.has(jwksHost)) {
+    throw new Error("jwksUri host must equal the issuer host or be listed in trustedEndpointHosts");
   }
+  // https (above) and SSRF (here) run UNCONDITIONALLY — the allowlist never
+  // bypasses them: an operator cannot allowlist 169.254.169.254 / loopback.
   if (isBlockedAddress(jwksUrl.hostname)) {
     throw new Error("jwksUri host resolves to a blocked (private/loopback/link-local/metadata) address");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haechi-auth-jwt",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Headless JWKS bearer (JWT) authProvider satellite for Haechi — node: builtins only, PII-safe identity.",
   "license": "Apache-2.0",
   "type": "module",