javascript-solid-server 0.0.180 → 0.0.182

package/.claude/settings.local.json

@@ -410,7 +410,8 @@
       "Bash(/usr/bin/chromium-browser --headless --no-sandbox --disable-gpu --hide-scrollbars --window-size=480,800 --screenshot=/tmp/consent-preview.png file:///tmp/consent-preview.html)",
       "Bash(cp /tmp/consent-preview.html ~/consent-preview.html)",
       "Read(//home/melvin/**)",
-      "Bash(/usr/bin/chromium-browser --headless --no-sandbox --disable-gpu --hide-scrollbars --window-size=520,900 --screenshot=consent.png file:///home/melvin/consent-preview.html)"
+      "Bash(/usr/bin/chromium-browser --headless --no-sandbox --disable-gpu --hide-scrollbars --window-size=520,900 --screenshot=consent.png file:///home/melvin/consent-preview.html)",
+      "Bash(sed -i '0,/\"version\": \"0.0.181\"/{s/\"version\": \"0.0.181\"/\"version\": \"0.0.182\"/}' package-lock.json)"
     ]
   }
 }

package/package.json

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

package/src/handlers/resource.js

@@ -28,6 +28,14 @@ const LIVE_RELOAD_SCRIPT = `<script>(function(){var ws=new WebSocket((location.p
 // where a cached data variant was served on top-level navigation (#315).
 const RDF_CACHE_CONTROL = 'private, no-cache, must-revalidate';
 
+// Detects when the request's Accept header explicitly names a JSON
+// media type. Used by the container/index.html branches of GET and HEAD
+// to decide whether to surface the embedded JSON-LD data island —
+// without this guard, selectContentType's `*/*` arm would divert plain
+// browser requests into the RDF branch (#409). Hoisted so GET and HEAD
+// can't drift apart silently.
+const EXPLICIT_JSON_RE = /\b(application\/ld\+json|application\/json)\b/i;
+
 /**
  * Inject live reload script into HTML content
  */
@@ -161,7 +169,16 @@ export async function handleGet(request, reply) {
       const wantsTurtle = negotiated === RDF_TYPES.TURTLE
         || negotiated === RDF_TYPES.N3
         || negotiated === 'application/n-triples';
-      const wantsJsonLd = negotiated === RDF_TYPES.JSON_LD;
+      // Only treat as JSON-LD when Accept *explicitly* asks for JSON.
+      // selectContentType doesn't recognize text/html or
+      // application/xhtml+xml, so for a browser Accept like
+      // `text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8`
+      // it walks past those unsupported types and lands on `*/*`, which
+      // returns JSON-LD — diverting plain browser GETs into the RDF
+      // branch and serving the embedded data island instead of the
+      // index.html body. Mirrors the HEAD-handler logic below (#409).
+      const explicitJson = EXPLICIT_JSON_RE.test(acceptHeader);
+      const wantsJsonLd = negotiated === RDF_TYPES.JSON_LD && explicitJson;
 
       if (wantsTurtle || wantsJsonLd) {
         // Extract JSON-LD from HTML data island
@@ -601,7 +618,7 @@ export async function handleHead(request, reply) {
         // For an index.html container, only override to JSON-LD if the
         // Accept header explicitly asked for JSON; otherwise fall back
         // to text/html so HEAD matches the index.html that GET serves.
-        const explicitJson = /\b(application\/ld\+json|application\/json)\b/i.test(acceptHeader);
+        const explicitJson = EXPLICIT_JSON_RE.test(acceptHeader);
         contentType = (indexExists && !explicitJson) ? 'text/html' : 'application/ld+json';
       } else {
         contentType = indexExists ? 'text/html' : 'application/ld+json';

package/src/idp/well-known-did-nostr.js

@@ -138,45 +138,85 @@ async function rebuildPubkeyIndex() {
       continue;
     }
     if (!account?.webId) continue;
-    const profilePath = profilePathFromWebId(dataRoot, account.webId, accountId);
-    if (!profilePath) continue;
-    let profile;
+    // Probe candidate paths in order until one ALSO passes the @id
+    // check. Multiple candidates can exist on disk simultaneously
+    // (e.g. root pod and named pods coexisting under the same
+    // dataRoot, or a subdomain pod with a coincidentally-named
+    // path-mode dir). The path-mode candidate may exist but belong
+    // to a different account — keep going until we find one whose
+    // declared `@id` matches account.webId.
+    const { paths: candidates, skipped: containmentSkipped } =
+      profilePathCandidates(dataRoot, account.webId, account.podName);
+    // Track per-candidate failure reasons so operators get a precise
+    // diagnostic when nothing matches — distinguishing
+    // "profile genuinely missing" from "@id mismatch" from "oversized"
+    // from "containment rejected".
+    const reasons = containmentSkipped.map(s => `${s.path}: ${s.reason}`);
+    let profile = null;
     let mtimeMs = 0;
-    try {
-      const stat = await fs.stat(profilePath);
-      mtimeMs = stat.mtimeMs;
-      // Size cap to bound per-rebuild memory/CPU. A user can write
-      // their own profile, and TTL-expired rebuilds can be triggered
-      // by attacker-driven NIP-98 traffic — without this an
-      // adversarially-large profile could pin the event loop on
-      // JSON.parse during the rebuild loop.
+    for (const candidate of candidates) {
+      let stat;
+      try {
+        stat = await fs.stat(candidate);
+      } catch (err) {
+        reasons.push(`${candidate}: ${err.code || 'stat-error'}`);
+        continue;
+      }
+      if (!stat.isFile()) {
+        reasons.push(`${candidate}: not-a-regular-file`);
+        continue;
+      }
       if (stat.size > MAX_PROFILE_BYTES) {
-        console.error(
-          `well-known-did-nostr: skipping account ${accountId} ` +
-          `— profile size ${stat.size} > ${MAX_PROFILE_BYTES} bytes`,
-        );
+        // Funnel through the rate-limited per-account logger
+        // (when no candidate matches at all). Direct console.error
+        // would spam logs every TTL rebuild for any account whose
+        // profile is oversized at one candidate but matches at
+        // another — and on every rebuild for genuinely-oversized
+        // accounts.
+        reasons.push(`${candidate}: oversized (${stat.size} > ${MAX_PROFILE_BYTES})`);
         continue;
       }
-      const text = await fs.readFile(profilePath, 'utf8');
-      profile = JSON.parse(text);
-    } catch (err) {
-      // Log so operators can debug "why isn't my pubkey publishing?".
-      // Rate-limited per account so a single perpetually-broken
-      // profile can't flood logs every TTL cycle.
-      logProfileFailure(accountId, profilePath, err);
-      continue; // unreadable / malformed — skip
+      let parsed;
+      try {
+        parsed = JSON.parse(await fs.readFile(candidate, 'utf8'));
+      } catch (err) {
+        reasons.push(`${candidate}: parse-error (${err.message})`);
+        continue;
+      }
+      const declaredSubject = absolutize(parsed?.['@id'] || parsed?.id, stripHashIfAny(account.webId));
+      if (declaredSubject !== account.webId) {
+        reasons.push(`${candidate}: @id-mismatch (declared=${declaredSubject || '(none)'})`);
+        continue;
+      }
+      profile = parsed;
+      mtimeMs = stat.mtimeMs;
+      break;
+    }
+    if (!profile) {
+      // Nothing on disk matched. Surface the precise per-candidate
+      // failure reasons so operators can distinguish ENOENT (profile
+      // genuinely missing) from @id mismatch (wrong subdomain config?)
+      // from containment rejection (malformed webId path) without
+      // having to grep the file system.
+      //
+      // Keep the `path` argument to logProfileFailure path-shaped so
+      // downstream log readers don't get a giant summary string in
+      // the `profile=...` field. Per-candidate detail goes into
+      // `err.message` as a single line.
+      const summary = reasons.length ? reasons.join(' | ') : '(no candidates)';
+      logProfileFailure(accountId, '(multiple candidates)', {
+        code: 'NO_CANDIDATE_MATCHED',
+        message: `no candidate profile matched ${account.webId} — tried: ${summary}`,
+      });
+      continue;
     }
-    // CID semantics — match the resource-side checks:
-    // (1) profile's @id MUST match the account's webId (no fragment-
-    //     swapping attack via a stored profile that claims to be
-    //     someone else)
+    // CID semantics (continued) — match the resource-side checks:
     // (2) VM's controller MUST be in the profile's expected controller
     //     set (declared `controller`, with @id fallback)
     // (3) VM MUST be referenced from `authentication` — a key in
     //     verificationMethod alone (no auth membership) shouldn't be
     //     published as authentic
-    const profileSubject = absolutize(profile?.['@id'] || profile?.id, stripHashIfAny(account.webId));
-    if (!profileSubject || profileSubject !== account.webId) continue;
+    const profileSubject = account.webId;  // already validated above
     const expectedControllers = collectControllerIds(profile, profileSubject);
     if (expectedControllers.size === 0) continue;
     // Pass the already-validated absolute subject as the base. Without
@@ -260,6 +300,64 @@ export function profilePathFromWebId(dataRoot, webId, accountId = 'unknown') {
   return resolved;
 }
 
+/**
+ * Build the candidate filesystem paths to probe for a given WebID,
+ * covering the deployment shapes JSS supports:
+ *
+ *   1. Path-mode named pod  (host=`example.com`, path=`/alice/profile/card.jsonld`)
+ *      → `<dataRoot>/alice/profile/card.jsonld`
+ *   2. Root pod (single-user) (host=`example.com`, path=`/profile/card.jsonld`)
+ *      → `<dataRoot>/profile/card.jsonld`
+ *   3. Subdomain-mode pod   (host=`alice.example.com`, path=`/profile/card.jsonld`)
+ *      → `<dataRoot>/alice/profile/card.jsonld`
+ *
+ * The subdomain candidate (3) is gated on `podName` matching the
+ * WebID host's first DNS label — without that gate, a root-pod
+ * WebID (`example.com`) would also emit `<dataRoot>/example/...`,
+ * which could be a different account's pod dir.
+ *
+ * Returns `{ paths, skipped }`:
+ *   - `paths` — absolute, containment-passed candidates to probe
+ *     in order
+ *   - `skipped` — diagnostic entries for paths rejected at this
+ *     stage (today only "outside-dataRoot"). Surfaced through the
+ *     rebuild loop's failure log so operators can distinguish
+ *     traversal / misconfig from "profile not on disk."
+ *
+ * @internal exported for tests
+ */
+export function profilePathCandidates(dataRoot, webId, podName = null) {
+  if (typeof webId !== 'string') return { paths: [], skipped: [] };
+  let url;
+  try { url = new URL(webId); } catch { return { paths: [], skipped: [] }; }
+  const pathnameRel = url.pathname.replace(/^\/+/, '');
+  const dataRootAbs = path.resolve(dataRoot);
+  const insideRoot = (p) => p === dataRootAbs || p.startsWith(dataRootAbs + path.sep);
+  const paths = [];
+  const skipped = [];
+  const consider = (...parts) => {
+    const r = path.resolve(dataRootAbs, ...parts);
+    if (!insideRoot(r)) {
+      skipped.push({ path: r, reason: 'outside-dataRoot' });
+      return;
+    }
+    if (!paths.includes(r)) paths.push(r);
+  };
+  // Path-mode named pod OR root pod.
+  consider(pathnameRel);
+  // Subdomain mode: only when the WebID host's first DNS label
+  // matches the account's podName (case-insensitive — DNS is).
+  if (typeof podName === 'string' && podName.length > 0) {
+    const host = url.hostname.toLowerCase();
+    const expected = podName.toLowerCase() + '.';
+    if (host.startsWith(expected)) {
+      consider(podName, pathnameRel);
+    }
+  }
+  return { paths, skipped };
+}
+
+
 function collectControllerIds(source, baseUrl) {
   const out = new Set();
   const c = source?.controller;

package/test/conneg.test.js

@@ -677,4 +677,86 @@ describe('Content Negotiation — q-weights and HEAD/GET parity (#325)', () => {
       assert.strictEqual(ct(authed), ct(anon));
     });
   });
+
+  describe('container with index.html — browser Accept (#409)', () => {
+    // Regression: a container that has an index.html with a *valid*
+    // <script type="application/ld+json"> data island used to return that
+    // data island as application/ld+json to plain browser GETs.
+    // selectContentType iterates the Accept list — for a browser sending
+    // `Accept: text/html, ..., */*;q=0.8` it sees text/html (and other
+    // HTML-ish types) but doesn't recognize any of them, then hits the
+    // `*/*` arm and returns JSON-LD, so the user-visible page silently
+    // flipped to JSON.
+    const HTML_WITH_JSONLD = '<!DOCTYPE html><html><head><title>Home</title>'
+      + '<script type="application/ld+json">'
+      + JSON.stringify({ '@context': { foaf: 'http://xmlns.com/foaf/0.1/' }, '@id': '#me', 'foaf:name': 'Carol' })
+      + '</script></head><body><h1>hello</h1></body></html>';
+
+    before(async () => {
+      // Container with an index.html containing a parseable JSON-LD island.
+      await request('/qwtest/public/page/', { method: 'PUT', auth: 'qwtest' });
+      await request('/qwtest/public/page/index.html', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'text/html' },
+        body: HTML_WITH_JSONLD,
+        auth: 'qwtest'
+      });
+    });
+
+    it('browser Accept (text/html with */*;q=0.8) → text/html, not JSON-LD', async () => {
+      const res = await request('/qwtest/public/page/', {
+        headers: { Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' }
+      });
+      assertStatus(res, 200);
+      assert.strictEqual(ct(res), 'text/html',
+        'browser GET on a container with index.html must return the HTML body, not the embedded data island');
+      const body = await res.text();
+      assert.ok(body.includes('<h1>hello</h1>'), 'response should be the index.html body');
+    });
+
+    it('plain Accept: text/html → text/html', async () => {
+      const res = await request('/qwtest/public/page/', { headers: { Accept: 'text/html' } });
+      assertStatus(res, 200);
+      assert.strictEqual(ct(res), 'text/html');
+    });
+
+    it('explicit Accept: application/ld+json → JSON-LD from data island still works', async () => {
+      const res = await request('/qwtest/public/page/', {
+        headers: { Accept: 'application/ld+json' }
+      });
+      assertStatus(res, 200);
+      assert.strictEqual(ct(res), 'application/ld+json');
+      const body = await res.json();
+      assert.strictEqual(body['foaf:name'], 'Carol',
+        'should still extract the data island when JSON-LD is explicitly asked for');
+    });
+
+    it('explicit Accept: text/turtle → Turtle from data island still works', async () => {
+      const res = await request('/qwtest/public/page/', { headers: { Accept: 'text/turtle' } });
+      assertStatus(res, 200);
+      assert.strictEqual(ct(res), 'text/turtle');
+      const body = await res.text();
+      assert.ok(body.includes('Carol'), 'turtle output should contain the data island content');
+    });
+
+    // The original bug was specifically GET vs HEAD divergence — the HEAD
+    // handler already had the explicitJson guard, GET didn't. Pin the
+    // parity here so any future drift between the two branches fails.
+    const parityCases = [
+      ['browser Accept',  { Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' }],
+      ['Accept: text/html', { Accept: 'text/html' }],
+      ['Accept: application/ld+json', { Accept: 'application/ld+json' }],
+      ['Accept: text/turtle', { Accept: 'text/turtle' }]
+    ];
+    for (const [label, headers] of parityCases) {
+      it(`HEAD === GET content-type — ${label}`, async () => {
+        const get = await request('/qwtest/public/page/', { headers });
+        const head = await request('/qwtest/public/page/', { method: 'HEAD', headers });
+        assert.strictEqual(get.status, 200);
+        assert.strictEqual(head.status, 200);
+        assert.strictEqual(ct(head), ct(get),
+          `HEAD ct (${ct(head)}) must equal GET ct (${ct(get)}) for ${label}`);
+      });
+    }
+  });
 });

package/test/well-known-did-nostr.test.js

@@ -14,7 +14,11 @@ import fs from 'fs-extra';
 import { createServer as createNetServer } from 'net';
 import { generateSecretKey, getPublicKey } from '../src/nostr/event.js';
 import { createServer } from '../src/server.js';
-import { _resetIndexForTests, profilePathFromWebId } from '../src/idp/well-known-did-nostr.js';
+import {
+  _resetIndexForTests,
+  profilePathFromWebId,
+  profilePathCandidates,
+} from '../src/idp/well-known-did-nostr.js';
 import { extractNostrPubkeysFromProfile } from '../src/auth/nostr.js';
 
 const TEST_HOST = '127.0.0.1';
@@ -301,6 +305,123 @@ describe('GET /.well-known/did/nostr/:pubkey (#407)', () => {
     assert.strictEqual(doc.alsoKnownAs[0], rootWebId);
   });
 
+  it('indexes subdomain-mode pods (#411): /<host-first-label>/profile/...', async () => {
+    // Subdomain layout: WebID host = `<podname>.<basedomain>` and
+    // the profile lives at `<DATA_ROOT>/<podname>/profile/card.jsonld`
+    // (NOT at `<DATA_ROOT>/profile/card.jsonld`). Pre-#411 the
+    // indexer derived the path from `webIdUrl.pathname` only,
+    // dropped the subdomain, and ENOENT-skipped every subdomain
+    // pod silently — so the entire `Sign in with Schnorr` zero-
+    // typing UX fell through to the typed-username fallback on
+    // every subdomain-mode deployment (e.g. solid.social).
+    //
+    // This test ALSO exercises the "first candidate exists but
+    // belongs to a different account" path: we write a coexisting
+    // root-pod profile at `<TEST_DATA_DIR>/profile/card.jsonld`
+    // for an UNRELATED account (different webId, different VM).
+    // The subdomain account's path-mode candidate hits that file,
+    // fails the @id check, and the loop must fall through to the
+    // subdomain candidate. Self-contained — doesn't depend on
+    // earlier tests' fixtures or test-execution order.
+    //
+    // Snapshot any pre-existing file at the decoy path so the
+    // earlier "indexes root-level pods" test's fixture (or any
+    // future fixture sharing that path) can be restored after
+    // this test runs. Without this snapshot, deleting the decoy
+    // unconditionally would silently wipe legitimate state.
+    const decoyPk = getPublicKey(generateSecretKey()); // unrelated key
+    const decoyProfilePath = path.join(TEST_DATA_DIR, 'profile', 'card.jsonld');
+    const decoyWebId = `${baseUrl}/profile/card.jsonld#decoy`;
+    const sk = generateSecretKey();
+    const subPk = getPublicKey(sk);
+    const subWebId = 'http://sub.example.test/profile/card.jsonld#me';
+    const subProfilePath = path.join(TEST_DATA_DIR, 'sub', 'profile', 'card.jsonld');
+    const VM_ID = 'http://sub.example.test/profile/card.jsonld#k';
+    const accountsDir = path.join(TEST_DATA_DIR, '.idp', 'accounts');
+    const indexPath = path.join(accountsDir, '_webid_index.json');
+    const accountId = 'subdomain-pod-test-account';
+
+    // Snapshot any pre-existing file at the decoy path so a prior
+    // fixture (e.g. the "indexes root-level pods" test's profile
+    // at the same location) can be restored at cleanup. ENOENT
+    // means "didn't exist; remove on cleanup."
+    let decoySnapshot = null;
+    try {
+      decoySnapshot = await fs.readFile(decoyProfilePath, 'utf8');
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+
+    // Mutate fixtures inside try; cleanup runs regardless of
+    // whether assertions throw, so a future regression doesn't
+    // leak filesystem state and turn the suite order-dependent.
+    try {
+      await fs.ensureDir(path.dirname(decoyProfilePath));
+      await fs.writeJson(decoyProfilePath, {
+        '@context': 'https://www.w3.org/ns/solid/v1',
+        '@id': decoyWebId,
+        verificationMethod: [{
+          id: `${decoyWebId.replace('#decoy', '')}#k`,
+          type: 'Multikey',
+          controller: decoyWebId,
+          publicKeyMultibase: fformMultikey(decoyPk),
+        }],
+        authentication: [`${decoyWebId.replace('#decoy', '')}#k`],
+      }, { spaces: 2 });
+
+      await fs.ensureDir(path.dirname(subProfilePath));
+      await fs.writeJson(subProfilePath, {
+        '@context': 'https://www.w3.org/ns/solid/v1',
+        '@id': subWebId,
+        verificationMethod: [{
+          id: VM_ID,
+          type: 'Multikey',
+          controller: subWebId,
+          publicKeyMultibase: fformMultikey(subPk),
+        }],
+        authentication: [VM_ID],
+      }, { spaces: 2 });
+
+      const idx = await fs.readJson(indexPath);
+      idx[subWebId] = accountId;
+      await fs.writeJson(indexPath, idx, { spaces: 2 });
+      await fs.writeJson(path.join(accountsDir, `${accountId}.json`), {
+        id: accountId,
+        podName: 'sub',
+        webId: subWebId,
+        email: 'sub@example.test',
+      }, { spaces: 2 });
+
+      const r = await fetch(`${baseUrl}/.well-known/did/nostr/${subPk}.json`);
+      assert.strictEqual(r.status, 200, 'subdomain-mode pod must be findable');
+      const doc = await r.json();
+      assert.strictEqual(doc.id, `did:nostr:${subPk}`);
+      assert.strictEqual(doc.alsoKnownAs[0], subWebId);
+    } finally {
+      // Restore decoy (or delete if it was created by this test).
+      if (decoySnapshot !== null) {
+        try { await fs.writeFile(decoyProfilePath, decoySnapshot, 'utf8'); }
+        catch { /* best effort */ }
+      } else {
+        try { await fs.remove(decoyProfilePath); } catch { /* best effort */ }
+      }
+      // Subdomain fixture file + empty parent dirs. fs-extra's
+      // `remove` handles both files and (recursively) dirs and
+      // is a no-op on missing paths — replaces the deprecated
+      // node `fs.rmdir`.
+      try { await fs.remove(subProfilePath); } catch { /* best effort */ }
+      try { await fs.remove(path.dirname(subProfilePath)); } catch { /* best effort */ }
+      try { await fs.remove(path.dirname(path.dirname(subProfilePath))); } catch { /* best effort */ }
+      // Index entry + account record.
+      try {
+        const idx = await fs.readJson(indexPath);
+        delete idx[subWebId];
+        await fs.writeJson(indexPath, idx, { spaces: 2 });
+      } catch { /* best effort */ }
+      try { await fs.remove(path.join(accountsDir, `${accountId}.json`)); } catch { /* best effort */ }
+    }
+  });
+
   // No `it()` here — path containment is now exercised directly
   // by unit tests on `profilePathFromWebId` below. The previous
   // integration-style test couldn't actually trigger the
@@ -629,3 +750,104 @@ describe('profilePathFromWebId — DATA_ROOT containment', () => {
     }
   });
 });
+
+describe('profilePathCandidates — deployment-shape coverage (#411)', () => {
+  // The original `profilePathFromWebId` only emitted ONE candidate
+  // (`<dataRoot><pathname>`), which broke subdomain-mode pods on
+  // solid.social: account `b0b1707f-...` with WebID
+  // `https://test.solid.social/profile/card.jsonld#me` lives on disk
+  // at `<dataRoot>/test/profile/card.jsonld`, but the indexer was
+  // looking at `<dataRoot>/profile/card.jsonld` and ENOENT-ing.
+  //
+  // `profilePathCandidates` returns the full ordered list. Tests
+  // cover all three deployment shapes JSS supports.
+  //
+  // DATA_ROOT is path.resolve()d so the assertions below build
+  // expected values via path.join — works on Windows (different
+  // separator/root) the same as on POSIX.
+  const DATA_ROOT = path.resolve('/srv/jss/data');
+
+  it('path-mode named pod: <dataRoot>/<pod>/profile/card.jsonld', () => {
+    const { paths } = profilePathCandidates(DATA_ROOT, 'https://example.com/alice/profile/card.jsonld#me');
+    const expected = path.join(DATA_ROOT, 'alice', 'profile', 'card.jsonld');
+    assert.ok(paths.includes(expected),
+      `expected ${expected}; got ${paths.join(', ')}`);
+  });
+
+  it('root pod: <dataRoot>/profile/card.jsonld', () => {
+    const { paths } = profilePathCandidates(DATA_ROOT, 'https://example.com/profile/card.jsonld#me');
+    const expected = path.join(DATA_ROOT, 'profile', 'card.jsonld');
+    assert.ok(paths.includes(expected),
+      `expected ${expected}; got ${paths.join(', ')}`);
+  });
+
+  it('subdomain-mode pod: emits <dataRoot>/<podName>/profile/... when host first label matches podName', () => {
+    const { paths } = profilePathCandidates(DATA_ROOT, 'https://test.solid.social/profile/card.jsonld#me', 'test');
+    const pathMode = path.join(DATA_ROOT, 'profile', 'card.jsonld');
+    const subdomain = path.join(DATA_ROOT, 'test', 'profile', 'card.jsonld');
+    assert.ok(paths.includes(pathMode),
+      `expected path-mode candidate ${pathMode}; got ${paths.join(', ')}`);
+    assert.ok(paths.includes(subdomain),
+      `expected subdomain candidate ${subdomain}; got ${paths.join(', ')}`);
+  });
+
+  it('does NOT emit a subdomain candidate when podName is omitted', () => {
+    const { paths } = profilePathCandidates(DATA_ROOT, 'https://test.solid.social/profile/card.jsonld#me');
+    assert.deepStrictEqual(paths, [path.join(DATA_ROOT, 'profile', 'card.jsonld')]);
+  });
+
+  it('does NOT emit a subdomain candidate when podName does not match the host first label', () => {
+    const { paths } = profilePathCandidates(DATA_ROOT, 'https://example.com/profile/card.jsonld#me', 'me');
+    assert.deepStrictEqual(paths, [path.join(DATA_ROOT, 'profile', 'card.jsonld')]);
+  });
+
+  it('does NOT emit a subdomain candidate for a single-label host', () => {
+    const { paths } = profilePathCandidates(DATA_ROOT, 'http://localhost/profile/card.jsonld#me', 'localhost');
+    assert.deepStrictEqual(paths, [path.join(DATA_ROOT, 'profile', 'card.jsonld')]);
+  });
+
+  it('returns empty paths for an unparseable webId', () => {
+    assert.deepStrictEqual(profilePathCandidates(DATA_ROOT, 'not a url'), { paths: [], skipped: [] });
+    assert.deepStrictEqual(profilePathCandidates(DATA_ROOT, null), { paths: [], skipped: [] });
+  });
+
+  it('every candidate stays inside dataRootAbs', () => {
+    const cases = [
+      ['https://example.com/alice/profile/card.jsonld#me', 'alice'],
+      ['https://alice.example.com/profile/card.jsonld#me', 'alice'],
+      ['https://h/../../../etc/passwd', null],
+      ['https://h.com/../../../etc/passwd', 'h'],
+    ];
+    for (const [w, podName] of cases) {
+      const { paths } = profilePathCandidates(DATA_ROOT, w, podName);
+      for (const c of paths) {
+        assert.ok(c === DATA_ROOT || c.startsWith(DATA_ROOT + path.sep),
+          `${w} (podName=${podName}) → ${c} escaped DATA_ROOT`);
+      }
+    }
+  });
+
+  it('returns the `{ paths, skipped }` shape so the caller can surface diagnostics', () => {
+    // Restructure of pass-2: the function returns BOTH the
+    // containment-passed paths AND a `skipped` list of rejected
+    // candidates with reasons. rebuildPubkeyIndex folds `skipped`
+    // into its per-account failure log so operators can
+    // distinguish "traversal/misconfig" from "profile not on disk."
+    //
+    // Through normal URL-parsed input the `skipped` list stays
+    // empty (URL normalization prevents traversal in pathname,
+    // and the podName-gated subdomain candidate rejects mismatches
+    // before path-resolve ever runs). The field exists as
+    // defense-in-depth for any future caller that bypasses URL
+    // parsing or feeds an externally-derived podName, AND so the
+    // rebuild loop's failure log has a hook to surface
+    // containment rejections instead of dropping them silently.
+    const result = profilePathCandidates(DATA_ROOT,
+      'https://alice.example.com/profile/card.jsonld#me', 'alice');
+    assert.ok(Array.isArray(result.paths), 'paths must be an array');
+    assert.ok(Array.isArray(result.skipped), 'skipped must be an array');
+    assert.ok(result.paths.length > 0, 'happy-path must yield paths');
+    assert.deepStrictEqual(result.skipped, [],
+      'normal URL-parsed input must produce no skipped entries');
+  });
+});