javascript-solid-server 0.0.177 → 0.0.179

package/docs/lws.md

@@ -1,16 +1,17 @@
 # LWS / Controlled Identifiers (CID v1)
 
-JSS pod profiles are aligned with the W3C [Linked Web Storage 1.0 Authentication Suite](https://www.w3.org/news/2026/first-public-working-drafts-for-the-linked-web-storage-lws-1-0-authentication-suite/) (FPWDs published 2026-04-23) and its substrate, [W3C Controlled Identifiers v1.0](https://www.w3.org/TR/cid-1.0/).
+JSS is aligned end-to-end with the W3C [Linked Web Storage 1.0 Authentication Suite](https://www.w3.org/news/2026/first-public-working-drafts-for-the-linked-web-storage-lws-1-0-authentication-suite/) (FPWDs published 2026-04-23) and its substrate, [W3C Controlled Identifiers v1.0](https://www.w3.org/TR/cid-1.0/) — pod profiles are CID-shaped, users add keys via the [doctor](https://jss.live/doctor/), and the server accepts strict LWS10-CID JWTs as an HTTP auth method alongside the existing Solid-OIDC and NIP-98 paths.
 
-The work is phased — see [#386](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/386) for the convergence tracker and [#319](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/319) for the FPWD-alignment audit.
+Convergence tracker: [#386](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/386). FPWD-alignment audit: [#319](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/319).
 
-## Three levels of compatibility
+## Compatibility, by level
 
 | | What it means | Status |
 |---|---|---|
 | **1. Profile shape** | A WebID profile that's structurally a W3C Controlled Identifier document — right `@context`, right vocabulary, parseable as a CID document by any LWS-aware tool | ✅ **Yes** (since v0.0.174, [#388](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/388)) |
-| **2. Profile carries keys** | The CID document actually declares `verificationMethod` entries an LWS verifier can look up by `kid` | ❌ Phase B — a separate "doctor / add-keys" app PATCHes them in after authentication. Out of JSS server scope. |
-| **3. Server accepts LWS-CID JWTs** | An incoming request with an LWS-CID self-signed JWT (`sub`/`iss`/`client_id` triple-equality, `kid` lookup against the WebID's `verificationMethod`, signature check) | ❌ Phase 3 of [#386](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/386) — JSS still only knows OIDC/DPoP, NIP-98, passkey, simple bearer |
+| **2. Profile carries keys** | The CID document actually declares `verificationMethod` entries an LWS verifier can look up by `kid` | ✅ Browser-side via the [doctor](https://jss.live/doctor/) — [B.2](https://github.com/JavaScriptSolidServer/doctor/pull/2) for Nostr/Multikey, [B.3](https://github.com/JavaScriptSolidServer/doctor/pull/4) for ES256K/JsonWebKey. The doctor authenticates as the WebID owner via Solid-OIDC and PATCHes the VM into the profile. |
+| **3. Server accepts LWS-CID JWTs** | An incoming request with an LWS-CID self-signed JWT (`sub`/`iss`/`client_id` triple-equality, `kid` lookup against the WebID's `verificationMethod`, signature check) | ✅ Shipped in v0.0.177 ([#398](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/398)). Strict FPWD §4 — ES256K is the focus algorithm; ES256, ES384, EdDSA, RS256 also accepted. |
+| **Bonus: NIP-98 → WebID** | A Schnorr-signed NIP-98 request authenticates as the WebID (not `did:nostr:`) when the pubkey is declared as a CID `verificationMethod` referenced from `authentication` | ✅ Shipped in v0.0.178 ([#400](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/400)). No client-side change — the doctor's B.2 output is enough to light it up. |
 
 ## What Phase A actually does
 
@@ -37,35 +38,42 @@ A freshly-created pod's `profile/card.jsonld` looks like this (excerpt — the e
 }
 ```
 
-## What Phase B will add
+## Adding keys (Phase B — via the doctor)
 
-A standalone web app (separate repo, no JSS coupling) where the WebID owner authenticates via existing means (OIDC, NIP-98, passkey) and PATCHes their profile with one or more verification methods:
+The [doctor](https://jss.live/doctor/) is a separate browser-side tool that signs in to your pod via Solid-OIDC and writes verificationMethod entries to your profile. After the round-trip your profile has:
 
 ```jsonld
 "verificationMethod": [
-  { "id": "...#nostr-1", "type": "Multikey",   "controller": "...#me",
-    "publicKeyMultibase": "fe70102..." },
-  { "id": "...#did-key-1", "type": "Multikey", "controller": "...#me",
-    "publicKeyMultibase": "z6MkpT..." },
-  { "id": "...#passkey-1", "type": "JsonWebKey", "controller": "...#me",
-    "publicKeyJwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." } }
+  { "id": "...#nostr-key-1", "type": "Multikey",   "controller": "...#me",
+    "publicKeyMultibase": "fe70102…" },
+  { "id": "...#lws-key-1",   "type": "JsonWebKey", "controller": "...#me",
+    "publicKeyJwk": { "kty": "EC", "crv": "secp256k1", "alg": "ES256K", "x": "…", "y": "…" } }
 ],
-"authentication": ["...#nostr-1", "...#did-key-1", "...#passkey-1"]
+"authentication": ["...#nostr-key-1", "...#lws-key-1"]
 ```
 
+The Multikey entry handles did:nostr binding + NIP-98 lookup; the JsonWebKey entry handles strict LWS10-CID JWT auth. Both can be the same secp256k1 key — different signature schemes (Schnorr vs ECDSA), same private key.
+
 Because Phase A already declared the context terms, this is a pure data-layer PATCH — no `@context` rewrite needed.
 
-## What Phase 3 will add (server-side verifier)
+## Server-side verifier (Phase 3 — `src/auth/lws-cid.js`)
+
+When an incoming request carries an LWS-CID JWT (detected by an `Authorization: Bearer <jwt>` whose JWT-header `kid` is an http(s) URL with a fragment), JSS:
+
+1. Confirms `sub === iss === client_id` (canonicalized via URL parsing) — that URI is the WebID being claimed
+2. Validates `aud` includes the server origin, `exp` not past, `iat` recent, lifetime ≤ 1 hour
+3. Fetches the WebID profile through the shared SSRF guard — manual redirects with same-origin enforcement, 256 KB body cap, bounded LRU cache
+4. Confirms the profile's `@id` equals the JWT's `sub` (closes a profile-substitution attack)
+5. Looks up `kid` in `verificationMethod`; the entry must be referenced from `authentication` and its `controller` must match the profile's outer `controller`
+6. Verifies the JWT signature per RFC7515 §5.2. ES256K via `@noble/curves` (already in tree from NIP-98); ES256, ES384, EdDSA, RS256 via `jose`
+
+The verifier joins the existing auth methods (Solid-OIDC, NIP-98, Bearer-JWT-from-IDP, WebID-TLS) — preference order is OIDC → LWS-CID → NIP-98 → Bearer fallback (per [#306](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/306)).
 
-When an incoming request carries an LWS-CID JWT, JSS will:
+## NIP-98 → WebID upgrade (`src/auth/nostr.js`)
 
-1. Confirm `sub`/`iss`/`client_id` are the same URI (the caller's WebID)
-2. Dereference the WebID, parse it as a CID document
-3. Look up `kid` in the document's `verificationMethod` array
-4. Confirm the method is in `authentication`
-5. Verify the JWT signature with that public key
+Built on top of the LWS-CID infrastructure ([#400](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/400)): when a NIP-98 request's signing pubkey is declared as a CID `verificationMethod` (and the VM is in `authentication`) on the resource owner's WebID profile, the request authenticates as the WebID instead of `did:nostr:<pubkey>`. Match is by f-form Multikey or by JsonWebKey full-point (x AND y, BIP-340 even-y). Profile fetch uses the same SSRF guard / cache as the LWS-CID verifier. No client-side change — Nostr clients sign as today.
 
-The verifier joins the existing auth methods (OIDC, NIP-98, etc.) — preference ordering tracked in [#306](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/306).
+So: anyone who's used the doctor's B.2 to add a Nostr Multikey VM gets WebID-based NIP-98 sign-in for free.
 
 ## Spec references
 
@@ -76,9 +84,12 @@ The verifier joins the existing auth methods (OIDC, NIP-98, etc.) — preference
 
 ## Related
 
-- [`docs/authentication.md`](authentication.md) — current JSS auth surface (OIDC, NIP-98, passkey, etc.)
+- [`docs/authentication.md`](authentication.md) — full JSS auth surface (OIDC, NIP-98, LWS-CID, passkey, etc.)
 - [`docs/nostr.md`](nostr.md) — Nostr relay + did:nostr resolution
+- [doctor](https://github.com/JavaScriptSolidServer/doctor) — the browser-side diagnostic + add-keys app
 - [#386](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/386) — convergence tracker
-- [#388](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/388) — Phase A PR
+- [#388](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/388) — Phase A (profile shape)
+- [#398](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/398) — Phase 3 (LWS-CID JWT verifier)
+- [#400](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/400) — NIP-98 → WebID via VM lookup
 - [#389](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/389) — `@context` array form support (turtle conneg)
 - [#390](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/390) — `@type:'@json'` literal handling (turtle conneg)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.177",
+  "version": "0.0.179",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/auth/cid-doc-fetch.js

@@ -0,0 +1,202 @@
+/**
+ * Shared CID-document / WebID-profile fetcher.
+ *
+ * Used by both the LWS10-CID JWT verifier (`src/auth/lws-cid.js`) and
+ * the NIP-98 → WebID VM-lookup path (`src/auth/nostr.js`). Centralized
+ * so future SSRF / redirect / DoS hardening only needs to land in one
+ * place.
+ *
+ * Defenses (mirrored from the original lws-cid implementation):
+ *
+ *   - URL validated through `validateExternalUrl` (loopback, private
+ *     IPs, http-in-prod blocked) on the original URL AND every
+ *     redirect Location.
+ *   - Manual redirect handling — no automatic following — capped at
+ *     MAX_REDIRECTS hops.
+ *   - Cross-origin redirects refused (an open redirect on the WebID's
+ *     host can't substitute an attacker-controlled CID document).
+ *   - Body size cap enforced via Content-Length up front AND a
+ *     streaming reader cap (cancel on overage), so untrusted hosts
+ *     can't OOM us with a large payload.
+ *   - 5-second timeout per request via AbortController.
+ *
+ * Throws on any failure; callers convert to whatever they want
+ * (LWS-CID surfaces the error string, the NIP-98 path treats
+ * throw-as-null and falls back to the existing did:nostr resolver).
+ */
+
+import { validateExternalUrl } from '../utils/ssrf.js';
+
+// Default body cap (256 KB) — CID documents are tiny in practice.
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const MAX_REDIRECTS = 5;
+const FETCH_TIMEOUT_MS = 5000;
+
+// Auth is on the hot path; refetching the CID document on every
+// request is unacceptable for both latency and reliability (and would
+// amplify self-traffic when the profile is hosted on this same
+// server). Bounded LRU — an attacker could otherwise grow the cache
+// without limit by sending tokens / requests with many distinct
+// document URLs. Mirrors the pattern in did-nostr.js.
+const profileCache = new Map(); // url -> { profile, timestamp, failureTtl?, error? }
+const PROFILE_CACHE_TTL = 5 * 60 * 1000; // 5 minutes for hits
+const PROFILE_FAILURE_TTL = 60 * 1000;   // 1 minute for misses
+const PROFILE_CACHE_MAX = 1000;
+
+/** @internal — exposed for tests */
+export function _clearProfileCacheForTests() {
+  profileCache.clear();
+}
+
+/**
+ * Fetch and parse a JSON CID document with SSRF, redirect, and
+ * body-size protections — and a bounded TTL cache so auth-path callers
+ * don't refetch on every request.
+ *
+ * Content-Type expectation: the response must declare a JSON-bearing
+ * Content-Type (matching `/json/`, e.g. `application/ld+json`,
+ * `application/json`, `application/json+ld`). A missing or non-JSON
+ * Content-Type rejects with a clear error rather than silently
+ * attempting JSON.parse — this caught real misconfigurations during
+ * #398 review where Turtle / HTML error pages were being served at
+ * profile URLs. Deployments serving WebID profiles should make sure
+ * their host returns the correct Content-Type for the CID document.
+ *
+ * Cache contract: keyed by `docUrl` only. All callers MUST pass
+ * consistent `opts` (in practice today everyone passes
+ * maxBytes = 256 KB). If a future caller needs a stricter limit, the
+ * cache key needs to incorporate it (or that caller needs its own
+ * cache) — otherwise a permissive entry would be returned to a strict
+ * caller and the cap wouldn't be re-enforced.
+ *
+ * @param {string} docUrl - URL to fetch (untrusted — comes from JWT
+ *   claims or is derived from a request).
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes=DEFAULT_MAX_BYTES]
+ * @returns {Promise<object>} parsed JSON
+ * @throws on any validation, network, redirect, size, or parse failure
+ */
+export async function fetchCidDocument(docUrl, opts = {}) {
+  // Cache hit (or recent failure) — return immediately. On hit we
+  // delete-then-set so this entry moves to the tail of the Map's
+  // insertion order, giving LRU eviction without a separate structure.
+  const cached = profileCache.get(docUrl);
+  if (cached) {
+    const ttl = cached.failureTtl ? PROFILE_FAILURE_TTL : PROFILE_CACHE_TTL;
+    if (Date.now() - cached.timestamp < ttl) {
+      profileCache.delete(docUrl);
+      profileCache.set(docUrl, cached);
+      if (cached.failureTtl) throw new Error(cached.error);
+      return cached.profile;
+    }
+    profileCache.delete(docUrl);
+  }
+
+  try {
+    const profile = await fetchCidDocumentNoCache(docUrl, opts);
+    setCached(docUrl, { profile, timestamp: Date.now() });
+    return profile;
+  } catch (err) {
+    setCached(docUrl, {
+      timestamp: Date.now(),
+      failureTtl: true,
+      error: err.message,
+    });
+    throw err;
+  }
+}
+
+/** Insert into the bounded LRU; evict the oldest entry past the cap. */
+function setCached(url, entry) {
+  profileCache.set(url, entry);
+  while (profileCache.size > PROFILE_CACHE_MAX) {
+    const oldest = profileCache.keys().next().value;
+    if (oldest === undefined) break;
+    profileCache.delete(oldest);
+  }
+}
+
+async function fetchCidDocumentNoCache(docUrl, opts = {}) {
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const originalOrigin = new URL(docUrl).origin;
+  let currentUrl = docUrl;
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const isLastAllowedHop = hop === MAX_REDIRECTS;
+    const validation = await validateExternalUrl(currentUrl, {
+      requireHttps: process.env.NODE_ENV === 'production',
+      blockPrivateIPs: true,
+      resolveDNS: true,
+    });
+    if (!validation.valid) {
+      throw new Error(`SSRF protection: ${validation.error}`);
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    let res;
+    try {
+      res = await fetch(currentUrl, {
+        headers: { Accept: 'application/ld+json, application/json;q=0.9' },
+        redirect: 'manual',
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (res.status >= 300 && res.status < 400) {
+      if (isLastAllowedHop) {
+        throw new Error(`too many redirects (>${MAX_REDIRECTS})`);
+      }
+      const loc = res.headers.get('location');
+      if (!loc) throw new Error(`redirect ${res.status} without Location`);
+      const nextUrl = new URL(loc, currentUrl).toString();
+      const nextOrigin = new URL(nextUrl).origin;
+      if (nextOrigin !== originalOrigin) {
+        throw new Error(`cross-origin redirect refused: ${originalOrigin} → ${nextOrigin}`);
+      }
+      currentUrl = nextUrl;
+      continue;
+    }
+
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+
+    const ct = (res.headers.get('content-type') || '').toLowerCase();
+    if (!ct.includes('json')) {
+      throw new Error(`unexpected content-type: ${ct || '(none)'}`);
+    }
+
+    const declared = Number(res.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      throw new Error(`CID document too large (Content-Length=${declared} > ${maxBytes})`);
+    }
+    const text = await readBodyWithCap(res, maxBytes);
+    return JSON.parse(text);
+  }
+  throw new Error('profile fetch loop exited unexpectedly');
+}
+
+async function readBodyWithCap(res, maxBytes) {
+  const reader = res.body?.getReader?.();
+  if (!reader) {
+    const text = await res.text();
+    if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+      throw new Error(`CID document too large (>${maxBytes} bytes)`);
+    }
+    return text;
+  }
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      try { await reader.cancel(); } catch { /* noop */ }
+      throw new Error(`CID document too large (>${maxBytes} bytes)`);
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength))).toString('utf8');
+}

package/src/auth/lws-cid.js

@@ -35,7 +35,10 @@
 import * as jose from 'jose';
 import { secp256k1 } from '@noble/curves/secp256k1';
 import { sha256 } from '@noble/hashes/sha256';
-import { validateExternalUrl } from '../utils/ssrf.js';
+import { fetchCidDocument, _clearProfileCacheForTests } from './cid-doc-fetch.js';
+
+// Re-export for the existing test suite, which already calls this.
+export { _clearProfileCacheForTests };
 
 // JWS algorithms we accept. ES256K (RFC8812) is the primary target —
 // secp256k1, the same curve as Nostr — but we support the common JWS
@@ -55,27 +58,11 @@ const MAX_LIFETIME = 3600; // 1 hour
 // Clock skew tolerance for exp/nbf checks (seconds).
 const CLOCK_SKEW = 60;
 
-// Profile fetch cache. Auth is on the hot path; refetching the CID
-// document on every request is unacceptable for both latency and
-// reliability. Mirrors the pattern in did-nostr.js, but bounded — an
-// attacker can otherwise grow the cache without limit by sending tokens
-// with many distinct `sub` URLs.
-const profileCache = new Map(); // url -> { profile, timestamp, failureTtl?, error? }
-const PROFILE_CACHE_TTL = 5 * 60 * 1000; // 5 minutes for hits
-const PROFILE_FAILURE_TTL = 60 * 1000;   // 1 minute for misses
-const PROFILE_CACHE_MAX = 1000;          // simple LRU bound
-
-// Manual-redirect cap so a chain can't loop or grind.
-const MAX_REDIRECTS = 5;
-
-// Max profile body size — guards against DoS via giant JSON bodies on
-// untrusted URLs. CID documents are tiny in practice (~1-5 KB).
-const MAX_PROFILE_BYTES = 256 * 1024; // 256 KB
-
-/** @internal — exposed for tests */
-export function _clearProfileCacheForTests() {
-  profileCache.clear();
-}
+// Max profile body size — passed to the shared fetcher. CID documents
+// are tiny in practice (~1-5 KB); 256 KB leaves plenty of headroom
+// while bounding any DoS attempt. The cache itself lives in
+// cid-doc-fetch.js so both this module and the NIP-98 path benefit.
+const MAX_PROFILE_BYTES = 256 * 1024;
 
 /**
  * Cheap detector — does this request carry an LWS-CID JWT?
@@ -427,165 +414,13 @@ function normalizeOrigin(s) {
   }
 }
 
-async function fetchProfile(docUrl) {
-  // Cache hit (or recent failure) — return immediately. On hit we
-  // delete-then-reset so this entry moves to the tail of the Map's
-  // insertion order, giving us LRU eviction without an extra structure.
-  const cached = profileCache.get(docUrl);
-  if (cached) {
-    const ttl = cached.failureTtl ? PROFILE_FAILURE_TTL : PROFILE_CACHE_TTL;
-    if (Date.now() - cached.timestamp < ttl) {
-      profileCache.delete(docUrl);
-      profileCache.set(docUrl, cached);
-      if (cached.failureTtl) throw new Error(cached.error);
-      return cached.profile;
-    }
-    profileCache.delete(docUrl);
-  }
-
-  try {
-    const profile = await fetchProfileNoCache(docUrl);
-    setCached(docUrl, { profile, timestamp: Date.now() });
-    return profile;
-  } catch (err) {
-    setCached(docUrl, {
-      timestamp: Date.now(),
-      failureTtl: true,
-      error: err.message,
-    });
-    throw err;
-  }
-}
-
-/** Insert into the bounded LRU; evict the oldest entry past the cap. */
-function setCached(url, entry) {
-  profileCache.set(url, entry);
-  while (profileCache.size > PROFILE_CACHE_MAX) {
-    // Map iterates in insertion order; first key is the oldest.
-    const oldest = profileCache.keys().next().value;
-    if (oldest === undefined) break;
-    profileCache.delete(oldest);
-  }
-}
-
-/**
- * Fetch the CID document with SSRF protection.
- *
- * docUrl comes from JWT claims (sub, kid) BEFORE the signature is
- * verified, so it's untrusted. We:
- *   1. Validate it through the existing SSRF guard (blocks loopback,
- *      private IPs, http (in production), DNS that resolves to private
- *      addresses).
- *   2. Disable automatic redirects and re-validate every Location to
- *      defeat redirect-based bypasses (mirrors the cors-proxy pattern).
- *      Cross-origin redirects are refused — otherwise a target
- *      attacker-controlled host could serve a substitute CID document
- *      for the WebID's origin.
- *   3. Cap redirects so a chain can't loop.
- *   4. Cap response body size so a giant payload can't OOM us.
- *   5. Always send a fresh Accept and a small read-side timeout.
- */
-async function fetchProfileNoCache(docUrl) {
-  const originalOrigin = new URL(docUrl).origin;
-  let currentUrl = docUrl;
-
-  // Hop 0 is the original request; up to MAX_REDIRECTS subsequent
-  // redirects are followed, after which we throw.
-  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
-    const isLastAllowedHop = hop === MAX_REDIRECTS;
-    const validation = await validateExternalUrl(currentUrl, {
-      // Allow http on dev only — production deploys should always be https.
-      requireHttps: process.env.NODE_ENV === 'production',
-      blockPrivateIPs: true,
-      resolveDNS: true,
-    });
-    if (!validation.valid) {
-      throw new Error(`SSRF protection: ${validation.error}`);
-    }
-
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 5000);
-    let res;
-    try {
-      res = await fetch(currentUrl, {
-        // Prefer JSON-LD but accept plain JSON too — some WebID hosts
-        // serve `application/json` for `card.jsonld`. The body is JSON
-        // either way; we don't perform JSON-LD-specific processing here.
-        headers: { Accept: 'application/ld+json, application/json;q=0.9' },
-        redirect: 'manual',
-        signal: controller.signal,
-      });
-    } finally {
-      clearTimeout(timer);
-    }
-
-    // Manual redirect handling — re-validate every Location and require
-    // same-origin so a redirect can't substitute an attacker-controlled
-    // CID document for the WebID's origin.
-    if (res.status >= 300 && res.status < 400) {
-      if (isLastAllowedHop) {
-        throw new Error(`too many redirects (>${MAX_REDIRECTS})`);
-      }
-      const loc = res.headers.get('location');
-      if (!loc) throw new Error(`redirect ${res.status} without Location`);
-      const nextUrl = new URL(loc, currentUrl).toString();
-      const nextOrigin = new URL(nextUrl).origin;
-      if (nextOrigin !== originalOrigin) {
-        throw new Error(
-          `cross-origin redirect refused: ${originalOrigin} → ${nextOrigin}`,
-        );
-      }
-      currentUrl = nextUrl;
-      continue;
-    }
-
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status}`);
-    }
-
-    // Size guard. Two layers: trust Content-Length when present, then
-    // also enforce as we read so a streaming response can't lie.
-    const declared = Number(res.headers.get('content-length'));
-    if (Number.isFinite(declared) && declared > MAX_PROFILE_BYTES) {
-      throw new Error(
-        `CID document too large (Content-Length=${declared} > ${MAX_PROFILE_BYTES})`,
-      );
-    }
-    const text = await readBodyWithCap(res, MAX_PROFILE_BYTES);
-    return JSON.parse(text);
-  }
-  // Loop exited without returning or redirecting — defensive fallback.
-  throw new Error('profile fetch loop exited unexpectedly');
-}
-
 /**
- * Read response body with a hard byte cap. Aborts the stream as soon as
- * the cap is exceeded so we don't buffer the entire untrusted payload.
+ * Fetch the CID document. Delegates to the shared `fetchCidDocument`
+ * helper which handles SSRF / redirects / body cap AND a bounded TTL
+ * cache (see src/auth/cid-doc-fetch.js).
  */
-async function readBodyWithCap(res, maxBytes) {
-  const reader = res.body?.getReader?.();
-  if (!reader) {
-    // No streaming reader (older runtimes / mocked responses) — fall
-    // back to .text() but enforce the cap after the fact.
-    const text = await res.text();
-    if (Buffer.byteLength(text, 'utf8') > maxBytes) {
-      throw new Error(`CID document too large (>${maxBytes} bytes)`);
-    }
-    return text;
-  }
-  const chunks = [];
-  let total = 0;
-  for (;;) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    total += value.byteLength;
-    if (total > maxBytes) {
-      try { await reader.cancel(); } catch { /* noop */ }
-      throw new Error(`CID document too large (>${maxBytes} bytes)`);
-    }
-    chunks.push(value);
-  }
-  return Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength))).toString('utf8');
+async function fetchProfile(docUrl) {
+  return fetchCidDocument(docUrl, { maxBytes: MAX_PROFILE_BYTES });
 }
 
 function findVerificationMethod(profile, kid, baseUrl) {
@@ -613,7 +448,9 @@ function isInProofPurpose(profile, predicate, kid, baseUrl) {
   return false;
 }
 
-function normalizeControllers(value, baseUrl) {
+// Exported so the NIP-98 → WebID path (src/auth/nostr.js) can perform
+// the same controller consistency check the LWS-CID verifier uses.
+export function normalizeControllers(value, baseUrl) {
   if (value === undefined || value === null) return [];
   const list = Array.isArray(value) ? value : [value];
   const out = [];