javascript-solid-server 0.0.181 → 0.0.183

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.181",
+  "version": "0.0.183",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

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/src/rdf/turtle.js

@@ -164,6 +164,47 @@ function quadsToJsonLd(quads, baseUri, prefixes = {}) {
   return nodes.map((node, i) => i === 0 ? { '@context': context, ...node } : node);
 }
 
+/**
+ * Read a JSON-LD node's identifier, accepting both the explicit
+ * `@id` form AND the unprefixed `id` alias that JSON-LD 1.1 treats
+ * as equivalent (and that Solid profiles in the wild use). Same
+ * fallback for `@type` / `type`.
+ *
+ * Without this aliasing, nested objects authored with `id`/`type`
+ * (e.g. a CID v1 verificationMethod entry) get silently dropped:
+ *   - the predicate-→-IRI quad isn't emitted (valueToTerm sees
+ *     no `@id` and returns null)
+ *   - the BFS enqueue check (`v['@id']`) is false, so the nested
+ *     object's own triples are never written either
+ *   - net result: the entire `cid:verificationMethod` predicate
+ *     and the `#nostr-key-1` resource block disappear from Turtle.
+ *
+ * #415.
+ */
+function getNodeId(n) {
+  if (!n || typeof n !== 'object') return undefined;
+  const v = n['@id'] !== undefined ? n['@id'] : n.id;
+  // Strict string-only — downstream resolveUri/`.startsWith` would
+  // throw on a number, null, or object. Malformed user content
+  // (a profile that authored `id: 42`) shouldn't crash conneg;
+  // treat non-string identifiers as absent.
+  return typeof v === 'string' ? v : undefined;
+}
+function getNodeType(n) {
+  if (!n || typeof n !== 'object') return undefined;
+  const v = n['@type'] !== undefined ? n['@type'] : n.type;
+  // Accept string OR array — expandUri/`.includes` would throw on
+  // anything else. For arrays, filter to string entries downstream
+  // (handled by Array.isArray + the per-entry expandUri call which
+  // assumes string; we filter here to be safe).
+  if (typeof v === 'string') return v;
+  if (Array.isArray(v)) {
+    const strs = v.filter(t => typeof t === 'string');
+    return strs.length > 0 ? strs : undefined;
+  }
+  return undefined;
+}
+
 /**
  * Convert JSON-LD to N3.js quads
  */
@@ -181,8 +222,8 @@ function jsonLdToQuads(jsonLd, baseUri) {
     if (doc['@context']) {
       mergedContext = { ...mergedContext, ...doc['@context'] };
     }
-    // Each document with @id is a node (no @graph needed)
-    if (doc['@id']) {
+    // Each document with @id (or `id` alias) is a node (no @graph needed)
+    if (getNodeId(doc) !== undefined) {
       nodes.push(doc);
     }
   }
@@ -206,16 +247,18 @@ function jsonLdToQuads(jsonLd, baseUri) {
   const queue = [...nodes];
   for (let i = 0; i < queue.length; i++) {
     const node = queue[i];
-    if (!node['@id']) continue;
-    const subjectUri = resolveUri(node['@id'], baseUri);
+    const nodeId = getNodeId(node);
+    if (nodeId === undefined) continue;
+    const subjectUri = resolveUri(nodeId, baseUri);
 
     const subject = subjectUri.startsWith('_:')
       ? blankNode(subjectUri.slice(2))
       : namedNode(subjectUri);
 
-    // Handle @type
-    if (node['@type']) {
-      const types = Array.isArray(node['@type']) ? node['@type'] : [node['@type']];
+    // Handle @type (or `type` alias).
+    const nodeType = getNodeType(node);
+    if (nodeType !== undefined) {
+      const types = Array.isArray(nodeType) ? nodeType : [nodeType];
       for (const type of types) {
         const typeUri = expandUri(type, context);
         quads.push(quad(
@@ -226,9 +269,13 @@ function jsonLdToQuads(jsonLd, baseUri) {
       }
     }
 
-    // Handle other properties
+    // Handle other properties. Skip `@`-prefixed keys AND the `id`/
+    // `type` aliases (handled above as @id/@type) — emitting them as
+    // predicates would produce malformed triples like `<id>` and
+    // `<type>` since the names don't expand to URIs via context.
     for (const [key, value] of Object.entries(node)) {
       if (key.startsWith('@')) continue;
+      if (key === 'id' || key === 'type') continue;
 
       const predicateUri = expandUri(key, context);
       const predicate = namedNode(predicateUri);
@@ -243,15 +290,16 @@ function jsonLdToQuads(jsonLd, baseUri) {
         if (object) {
           quads.push(quad(subject, predicate, object));
         }
-        // If v is a nested node (object with @id and at least one non-@value
-        // own property beyond @id), enqueue it so its triples are also
-        // emitted. Object-identity tracking (WeakSet) prevents the same
-        // nested object from being enqueued twice, which would otherwise
-        // loop for graphs that reuse an object reference (cycles).
+        // If v is a nested node (object with @id/id and at least one
+        // own property beyond the identifier), enqueue it so its
+        // triples are also emitted. Object-identity tracking
+        // (WeakSet) prevents the same nested object from being
+        // enqueued twice, which would otherwise loop for graphs
+        // that reuse an object reference (cycles).
         if (v && typeof v === 'object' && !Array.isArray(v) &&
-            v['@id'] && v['@value'] === undefined &&
+            getNodeId(v) !== undefined && v['@value'] === undefined &&
             !enqueuedNested.has(v)) {
-          const hasOwnClaims = Object.keys(v).some(k => k !== '@id');
+          const hasOwnClaims = Object.keys(v).some(k => k !== '@id' && k !== 'id');
           if (hasOwnClaims) {
             enqueuedNested.add(v);
             queue.push(v);
@@ -348,9 +396,18 @@ function valueToTerm(value, baseUri, context, isIdType = false) {
 
   // Object values
   if (typeof value === 'object') {
-    // @id reference
-    if (value['@id']) {
-      const uri = resolveUri(value['@id'], baseUri);
+    // @id reference (or `id` alias — same JSON-LD 1.1 convention).
+    // This is what makes the predicate-→-IRI quad get emitted for
+    // nested objects authored with `id` instead of `@id`. Without
+    // it, an inline verificationMethod with `id`/`type` returned
+    // null here and the parent predicate triple was lost.
+    //
+    // String-only — a numeric or null `@id`/`id` would crash
+    // resolveUri's `.startsWith`. Treat as absent and fall through
+    // to the @value/@language branches below.
+    const rawObjId = value['@id'] !== undefined ? value['@id'] : value.id;
+    if (typeof rawObjId === 'string') {
+      const uri = resolveUri(rawObjId, baseUri);
       return uri.startsWith('_:')
         ? blankNode(uri.slice(2))
         : namedNode(uri);

package/test/turtle.test.js

@@ -85,6 +85,74 @@ describe('turtle converter — unit (#320 follow-ups)', () => {
       `Turtle output must not contain object-stringification, got:\n${content}`);
   });
 
+  it('nested object with `id`/`type` aliases survives the conversion (#415)', async () => {
+    // Solid profiles use the JSON-LD 1.1 `id`/`type` aliases for
+    // nested resources (no `@`). The converter must accept both
+    // forms — without this, a CID v1 verificationMethod object
+    // gets silently dropped:
+    //   - the `cid:verificationMethod` predicate isn't emitted
+    //   - the nested `#nostr-key-1` resource (Multikey, controller,
+    //     publicKeyMultibase) isn't emitted either
+    // Net: third-party Turtle consumers see `cid:authentication
+    // <#nostr-key-1>` with no description of `#nostr-key-1`.
+    const doc = {
+      '@context': {
+        cid: 'https://www.w3.org/ns/cid/v1#',
+        verificationMethod: { '@id': 'cid:verificationMethod', '@container': '@set' },
+        authentication: { '@id': 'cid:authentication', '@type': '@id', '@container': '@set' },
+        controller: { '@id': 'cid:controller', '@type': '@id' },
+        publicKeyMultibase: { '@id': 'cid:publicKeyMultibase' },
+      },
+      '@id': 'https://example.test/profile/card.jsonld#me',
+      verificationMethod: [{
+        // Aliases — `id`/`type`, not `@id`/`@type`.
+        id: 'https://example.test/profile/card.jsonld#k',
+        type: 'Multikey',
+        controller: 'https://example.test/profile/card.jsonld#me',
+        publicKeyMultibase: 'fe70102de7ec',
+      }],
+      authentication: ['https://example.test/profile/card.jsonld#k'],
+    };
+    const { content } = await fromJsonLd(doc, 'text/turtle', 'https://example.test/', true);
+
+    // The cid:verificationMethod predicate must connect #me to the VM.
+    assert.match(content, /cid:verificationMethod|<https:\/\/www\.w3\.org\/ns\/cid\/v1#verificationMethod>/,
+      `cid:verificationMethod predicate missing from Turtle:\n${content}`);
+    // The VM resource must be described — its type, controller, key.
+    assert.ok(content.includes('https://example.test/profile/card.jsonld#k'),
+      `VM #k must appear in Turtle:\n${content}`);
+    assert.match(content, /Multikey|<https:\/\/www\.w3\.org\/ns\/cid\/v1#Multikey>/,
+      `Multikey type missing from Turtle:\n${content}`);
+    assert.ok(content.includes('fe70102de7ec'),
+      `publicKeyMultibase value missing from Turtle:\n${content}`);
+    assert.match(content, /cid:controller|<https:\/\/www\.w3\.org\/ns\/cid\/v1#controller>/,
+      `cid:controller predicate missing on the VM:\n${content}`);
+  });
+
+  it('malformed `id`/`type` values are silently dropped, not crashed on (#415 review)', async () => {
+    // Profiles in the wild can have malformed user-authored content
+    // — e.g. `id: 42` or `type: null`. The converter must NOT throw
+    // (downstream `resolveUri.startsWith` and `expandUri.includes`
+    // assume strings); it should treat the malformed value as absent
+    // and skip the affected resource cleanly.
+    const doc = {
+      '@context': { 'cid': 'https://www.w3.org/ns/cid/v1#' },
+      '@id': 'https://example.test/s',
+      // Nested object with a non-string `id` — must not crash.
+      'cid:bad1': { id: 42, 'cid:foo': 'x' },
+      // Nested object with a null `type` — must not crash.
+      'cid:bad2': { id: 'https://example.test/n2', type: null, 'cid:foo': 'x' },
+      // Array `type` with mixed string/non-string entries — string
+      // entries should still emit.
+      'cid:mixed': { id: 'https://example.test/n3', type: ['Multikey', 42, null], 'cid:foo': 'x' },
+    };
+    const { content } = await fromJsonLd(doc, 'text/turtle', 'https://example.test/', true);
+    assert.ok(typeof content === 'string', 'must produce a string output, not throw');
+    // The valid string type entry should survive in the mixed-type case.
+    assert.ok(content.includes('https://example.test/n3'),
+      `node n3 should appear:\n${content}`);
+  });
+
   it('cyclical nested node reference does not hang', async () => {
     // Two nested nodes reference each other. BFS must not loop.
     const a = { '@id': 'https://example.test/a', 'ex:knows': null };

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');
+  });
+});