javascript-solid-server 0.0.179 → 0.0.180

package/src/auth/nostr-keys.js

@@ -0,0 +1,112 @@
+/**
+ * Shared Nostr-key encoding helpers.
+ *
+ * Lives in its own module so both the NIP-98 verifier
+ * (`src/auth/nostr.js`) and the well-known DID-doc publisher
+ * (`src/idp/well-known-did-nostr.js`) can use it without forming a
+ * circular import.
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1';
+
+/** Multicodec varint for secp256k1-pub: 0xe7 0x01 → "e701" hex. */
+const MULTICODEC_SECP256K1_PUB_HEX = 'e701';
+
+/**
+ * Validate a secp256k1 JWK as a Nostr key and return its x-only
+ * pubkey hex. Returns `null` if the JWK isn't a Nostr-shaped key
+ * or its `y` doesn't match the BIP-340 canonical (even-y) point
+ * for the declared `x`.
+ *
+ * Why y matters: every secp256k1 x has TWO valid points (positive
+ * and negative y). Nostr uses x-only pubkeys, which by BIP-340
+ * convention always pick the even-y point. A profile that declares
+ * a JWK with the right x but the wrong y is NOT the user's Nostr
+ * key — accepting it would let an attacker plant a JWK at someone
+ * else's WebID and have the indexer publish it as theirs.
+ *
+ * The verifier in src/auth/nostr.js (jwkMatchesNostrPubkey) does
+ * the same check. Keeping the indexer in sync prevents the
+ * "indexed but verifier rejects" inconsistency that would surface
+ * as a 401 on a key the well-known endpoint had advertised.
+ */
+export function pubkeyFromValidatedJwk(jwk) {
+  if (!jwk || typeof jwk !== 'object') return null;
+  if (jwk.kty !== 'EC') return null;
+  if (jwk.crv !== 'secp256k1' && jwk.crv !== 'P-256K') return null;
+  if (typeof jwk.x !== 'string' || typeof jwk.y !== 'string') return null;
+  let xHex;
+  try {
+    xHex = Buffer.from(jwk.x.replace(/-/g, '+').replace(/_/g, '/'), 'base64')
+      .toString('hex').toLowerCase();
+  } catch { return null; }
+  if (!/^[0-9a-f]{64}$/.test(xHex)) return null;
+  let canonicalY;
+  try {
+    // Compressed SEC1 encoding for the EVEN-y point at this x.
+    const point = secp256k1.ProjectivePoint.fromHex('02' + xHex);
+    canonicalY = point.toAffine().y.toString(16).padStart(64, '0');
+  } catch { return null; }
+  let jwkYHex;
+  try {
+    jwkYHex = Buffer.from(jwk.y.replace(/-/g, '+').replace(/_/g, '/'), 'base64')
+      .toString('hex').toLowerCase();
+  } catch { return null; }
+  if (jwkYHex !== canonicalY) return null;
+  return xHex;
+}
+
+/**
+ * Decode an f-form Multikey for secp256k1-pub back into the 32-byte
+ * x-only pubkey hex. Returns null if the input isn't this shape.
+ *
+ * The f-form recipe (per CCG community#254 / did:nostr): multibase
+ * `f` (base16-lower) + multicodec `e701` + parity byte (`02`/`03`)
+ * + 32-byte xonly pubkey.
+ */
+export function decodeFFormSecp256k1(mb) {
+  if (typeof mb !== 'string' || !mb.startsWith('f')) return null;
+  const hex = mb.slice(1).toLowerCase();
+  if (!/^[0-9a-f]+$/.test(hex)) return null;
+  if (!hex.startsWith(MULTICODEC_SECP256K1_PUB_HEX)) return null;
+  const rest = hex.slice(MULTICODEC_SECP256K1_PUB_HEX.length);
+  // Expect parity byte (02/03) + 32-byte xonly = 66 hex chars.
+  if (rest.length !== 66) return null;
+  const parity = rest.slice(0, 2);
+  if (parity !== '02' && parity !== '03') return null;
+  return rest.slice(2);
+}
+
+/**
+ * Enumerate every Nostr pubkey declared in a profile's
+ * `verificationMethod` entries. Matches both encodings:
+ *   - f-form Multikey (`publicKeyMultibase`)
+ *   - JsonWebKey (`kty: EC, crv: secp256k1`) — derives x as the pubkey
+ *
+ * Returns `[ { pubkey, vm } ]` — the VM is returned alongside so
+ * callers can do further checks (`controller`, `authentication`
+ * membership, etc.) without re-parsing.
+ */
+export function extractNostrPubkeysFromProfile(profile) {
+  if (!profile || typeof profile !== 'object') return [];
+  const out = [];
+  const raw = profile.verificationMethod;
+  const vms = raw === undefined || raw === null ? []
+            : Array.isArray(raw) ? raw : [raw];
+  for (const vm of vms) {
+    if (!vm || typeof vm !== 'object') continue;
+    if (typeof vm.publicKeyMultibase === 'string') {
+      const xonly = decodeFFormSecp256k1(vm.publicKeyMultibase);
+      if (xonly) out.push({ pubkey: xonly, vm });
+    } else if (vm.publicKeyJwk && typeof vm.publicKeyJwk === 'object') {
+      // Require y to match the BIP-340 canonical point — the same
+      // check the NIP-98 verifier applies. Without this, the indexer
+      // could publish a JWK that the verifier will then reject,
+      // surfacing as a 401 on a key the well-known endpoint had
+      // advertised as authentic.
+      const xonly = pubkeyFromValidatedJwk(vm.publicKeyJwk);
+      if (xonly) out.push({ pubkey: xonly, vm });
+    }
+  }
+  return out;
+}

package/src/auth/nostr.js

@@ -14,10 +14,14 @@
  *      Match by f-form Multikey or by JsonWebKey x/y coordinates. If
  *      found, authenticate as the WebID. (#399 — pairs with the
  *      LWS10-CID verifier.)
- *   2. Resolve via the existing did:nostr DID-document path
+ *   2. (IdP-only) Look up the pubkey in the local in-process index
+ *      built from `<DATA_ROOT>/.idp/accounts/_webid_index.json`.
+ *      No HTTP, no SSRF surface — direct function call. Catches
+ *      same-pod users without a third-party round-trip. (#407)
+ *   3. Resolve via the external did:nostr DID-document path
  *      (nostr.social `.well-known` + bidirectional alsoKnownAs).
- *      If found, authenticate as the WebID it points to.
- *   3. Otherwise return `did:nostr:<64-char-hex-pubkey>` as the
+ *      Used for cross-pod identities; SSRF + redirect hardened.
+ *   4. Otherwise return `did:nostr:<64-char-hex-pubkey>` as the
  *      agent identity (the original behavior).
  */
 
@@ -25,8 +29,14 @@ import { verifyEvent, getEventHash } from '../nostr/event.js';
 import { secp256k1 } from '@noble/curves/secp256k1';
 import crypto from 'crypto';
 import { resolveDidNostrToWebId } from './did-nostr.js';
+// resolveDidNostrLocally is loaded lazily (inside the idpEnabled
+// branch) so non-IdP deployments don't pay the IdP/accounts module
+// startup cost (bcryptjs, oidc-provider helpers, etc.) just by
+// importing the NIP-98 verifier.
 import { fetchCidDocument } from './cid-doc-fetch.js';
 import { normalizeControllers } from './lws-cid.js'; // shared JSON-LD controller helper
+import { decodeFFormSecp256k1, extractNostrPubkeysFromProfile } from './nostr-keys.js'; // re-exported for back-compat
+export { extractNostrPubkeysFromProfile };
 
 // NIP-98 event kind (references RFC 7235)
 const HTTP_AUTH_KIND = 27235;
@@ -34,11 +44,6 @@ const HTTP_AUTH_KIND = 27235;
 // Timestamp tolerance in seconds
 const TIMESTAMP_TOLERANCE = 60;
 
-// Multicodec varint for secp256k1-pub: 0xe7 0x01 → "e701" hex.
-// Used to decode f-form Multikey verificationMethod values back into
-// the 32-byte x-only Nostr pubkey.
-const MULTICODEC_SECP256K1_PUB_HEX = 'e701';
-
 // Profile-fetch body-size cap. Matches the LWS-CID verifier; both
 // callers go through the shared fetchCidDocument helper.
 const MAX_PROFILE_BYTES = 256 * 1024;
@@ -282,9 +287,30 @@ export async function verifyNostrAuth(request) {
     return { webId: vmWebId, error: null };
   }
 
-  // Second lookup: existing did:nostr DID-document resolver. Fetches
-  // an external DID doc (e.g. nostr.social/.well-known/...) and checks
-  // bidirectional alsoKnownAs ↔ WebID linking.
+  // Second lookup: in-process local DID resolution (#407). Fast path
+  // — direct function call into the local account index, no HTTP
+  // fetch, no SSRF surface from request-controlled headers. Catches
+  // any user who's published a Nostr Multikey VM into their profile
+  // on this same pod.
+  //
+  // Gated on idpEnabled because the index reads from
+  // <DATA_ROOT>/.idp/accounts which only exists when the IdP layer
+  // is in use. On non-IdP deployments the local resolver has nothing
+  // to find and would just spin disk on every request.
+  if (request.idpEnabled) {
+    // Dynamic import: only load the IdP-accounts stack when IdP is
+    // actually enabled. Cached after first load (ESM module caching).
+    const { resolveDidNostrLocally } = await import('../idp/well-known-did-nostr.js');
+    const localWebId = await resolveDidNostrLocally(event.pubkey);
+    if (localWebId) {
+      return { webId: localWebId, error: null };
+    }
+  }
+
+  // Third lookup: external did:nostr DID-document resolver. Fetches
+  // a DID doc from the configured external resolver (nostr.social) and
+  // checks bidirectional alsoKnownAs ↔ WebID linking. Used only for
+  // cross-pod identities (the local case is handled above).
   const resolvedWebId = await resolveDidNostrToWebId(event.pubkey);
   if (resolvedWebId) {
     return { webId: resolvedWebId, error: null };
@@ -599,23 +625,6 @@ function findNostrVmInProfile(profile, pubkeyHex, baseUrl) {
   return null;
 }
 
-/**
- * Decode an f-form Multikey for secp256k1-pub back into the 32-byte
- * x-only pubkey hex. Returns null if the input isn't this shape.
- */
-function decodeFFormSecp256k1(mb) {
-  if (typeof mb !== 'string' || !mb.startsWith('f')) return null;
-  const hex = mb.slice(1).toLowerCase();
-  if (!/^[0-9a-f]+$/.test(hex)) return null;
-  if (!hex.startsWith(MULTICODEC_SECP256K1_PUB_HEX)) return null;
-  const rest = hex.slice(MULTICODEC_SECP256K1_PUB_HEX.length);
-  // Expect parity byte (02/03) + 32-byte xonly = 66 hex chars.
-  if (rest.length !== 66) return null;
-  const parity = rest.slice(0, 2);
-  if (parity !== '02' && parity !== '03') return null;
-  return rest.slice(2);
-}
-
 function hexToBase64url(hex) {
   return Buffer.from(hex, 'hex').toString('base64')
     .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

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

@@ -0,0 +1,458 @@
+/**
+ * did:nostr HTTP resolution endpoint.
+ *
+ * Implements the well-known path from the did:nostr spec:
+ *
+ *   GET /.well-known/did/nostr/<pubkey>.json
+ *   GET /.well-known/did/nostr/<pubkey>.jsonld
+ *   GET /.well-known/did/nostr/<pubkey>
+ *
+ * For any local account whose WebID profile declares this Nostr pubkey
+ * as a CID `verificationMethod` referenced from `authentication`, JSS
+ * generates a DID document on the fly with `alsoKnownAs: [<webId>]`.
+ * Other resolvers (nostr.social, nostr.rocks, JSS's own
+ * `src/auth/did-nostr.js`) can then fetch the DID doc from this pod
+ * and follow the WebID linkage — making the pod its own
+ * authoritative DID resolver for its accounts.
+ *
+ * Closes the "type your username" UX hack on the IdP login page
+ * (#403 / #405): the existing did-nostr resolver finds local users
+ * via this endpoint without any user-typed hint.
+ */
+
+import path from 'path';
+import fs from 'fs-extra';
+import { findById } from './accounts.js';
+import { extractNostrPubkeysFromProfile } from '../auth/nostr-keys.js';
+
+// In-memory pubkey → resolved-account-record index. Built lazily
+// from disk; rebuilt when the TTL expires. Real production wants
+// a write-path hook on LDP PUT/PATCH so updates are immediate;
+// that's filed as a follow-up.
+//
+// Each entry stores `{ accountId, webId, mtimeMs }` so the hot
+// path (NIP-98 auth via resolveDidNostrLocally + every DID-doc
+// request) can answer without re-reading the account JSON from
+// disk. accountId is kept for log diagnostics; webId is what
+// the resolver actually needs.
+let pubkeyIndex = null; // Map<pubkeyHex, { accountId, webId, mtimeMs }>
+let indexBuiltAt = 0;
+let rebuildInFlight = null; // Promise — in-flight rebuild dedup
+const INDEX_TTL_MS = 5 * 60 * 1000;
+
+// Rate-limit "profile unreadable" log spam. A single broken profile
+// shouldn't flood logs every 5 minutes (every TTL rebuild) — but the
+// first occurrence per rebuild cycle MUST be logged so operators can
+// debug "why isn't my pubkey publishing?" without grepping silence.
+const PROFILE_LOG_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+const profileLogTracker = new Map(); // accountId -> last logged ms
+function logProfileFailure(accountId, profilePath, err) {
+  const now = Date.now();
+  const last = profileLogTracker.get(accountId) || 0;
+  if (now - last < PROFILE_LOG_INTERVAL_MS) return;
+  profileLogTracker.set(accountId, now);
+  // Trim the tracker so it can't grow without bound.
+  if (profileLogTracker.size > 10_000) {
+    const oldest = profileLogTracker.keys().next().value;
+    if (oldest !== undefined) profileLogTracker.delete(oldest);
+  }
+  console.error(
+    `well-known-did-nostr: skipping account ${accountId} ` +
+    `(profile=${profilePath}): ${err.code || err.name || 'error'} ${err.message}`,
+  );
+}
+// Size cap on per-account profile reads. WebID profiles are tiny —
+// 64 KB is generous and matches the bound the LDP layer would impose
+// for any sane profile. A user shouldn't be able to make the indexer
+// allocate megabytes by writing a giant profile, especially since
+// rebuilds can be triggered by attacker-driven NIP-98 traffic once
+// the TTL expires.
+const MAX_PROFILE_BYTES = 64 * 1024;
+
+/** @internal — exposed for tests */
+export function _resetIndexForTests() {
+  pubkeyIndex = null;
+  indexBuiltAt = 0;
+  rebuildInFlight = null;
+  profileLogTracker.clear();
+}
+
+// Match the layout in src/idp/accounts.js — accounts live under
+// <DATA_ROOT>/.idp/accounts. Computed lazily so DATA_ROOT changes
+// (test setup, env override) are picked up.
+function getAccountsDir() {
+  const dataRoot = process.env.DATA_ROOT || './data';
+  return path.join(dataRoot, '.idp', 'accounts');
+}
+function getWebIdIndexPath() {
+  return path.join(getAccountsDir(), '_webid_index.json');
+}
+
+/**
+ * Read a JSON file. Returns null in two cases (with different
+ * semantics, kept the same return shape for caller simplicity):
+ *
+ *   - ENOENT — silently null. The index file legitimately doesn't
+ *     exist on a fresh deployment with no accounts yet.
+ *   - Any other error (parse error, permission denied, etc.) — null
+ *     PLUS a loud console.error so operational issues surface in logs
+ *     instead of silently disabling DID-doc publishing.
+ */
+async function readJsonOrEmpty(file) {
+  try {
+    return await fs.readJson(file);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    console.error(`well-known-did-nostr: failed to read ${file}: ${err.message}`);
+    return null;
+  }
+}
+
+async function rebuildPubkeyIndex() {
+  const idx = new Map();
+  const dataRoot = process.env.DATA_ROOT || './data';
+  const webIdIndex = await readJsonOrEmpty(getWebIdIndexPath());
+  if (!webIdIndex) {
+    pubkeyIndex = idx;
+    indexBuiltAt = Date.now();
+    return;
+  }
+  // Track pubkeys that appear under more than one account so we can
+  // EXCLUDE them rather than silently picking one. An ambiguous binding
+  // would make resolution depend on insertion order and be hard to
+  // diagnose; better to refuse and log loudly.
+  const seenAccounts = new Map(); // pubkey -> Set<accountId>
+  for (const [, accountId] of Object.entries(webIdIndex)) {
+    // Wrap each account read so one corrupt/unreadable account file
+    // can't take down resolution for everyone — the index would just
+    // skip that account and a single 500 wouldn't cascade across the
+    // whole pod's NIP-98 traffic.
+    let account;
+    try {
+      account = await findById(accountId);
+    } catch (err) {
+      console.error(
+        `well-known-did-nostr: skipping account ${accountId} ` +
+        `(read failed: ${err.message})`,
+      );
+      continue;
+    }
+    if (!account?.webId) continue;
+    const profilePath = profilePathFromWebId(dataRoot, account.webId, accountId);
+    if (!profilePath) continue;
+    let profile;
+    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.
+      if (stat.size > MAX_PROFILE_BYTES) {
+        console.error(
+          `well-known-did-nostr: skipping account ${accountId} ` +
+          `— profile size ${stat.size} > ${MAX_PROFILE_BYTES} 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
+    }
+    // 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)
+    // (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 expectedControllers = collectControllerIds(profile, profileSubject);
+    if (expectedControllers.size === 0) continue;
+    // Pass the already-validated absolute subject as the base. Without
+    // this, profiles with a relative subject (e.g. `"@id": "#me"`)
+    // would absolutize their `authentication` entries against an
+    // unusable base, leaving the IDs relative — and then the
+    // `authIds.has(vmId)` check below would never match even when the
+    // VM is actually authenticated.
+    const authIds = collectAuthenticationIds(profile, stripHashIfAny(profileSubject));
+
+    for (const { pubkey, vm } of extractNostrPubkeysFromProfile(profile)) {
+      const vmId = absolutize(vm.id || vm['@id'], stripHashIfAny(profileSubject));
+      if (!vmId || !authIds.has(vmId)) continue;
+      const vmCtrls = collectControllerIds({ controller: vm.controller }, profileSubject);
+      let controllerOk = false;
+      for (const c of vmCtrls) {
+        if (expectedControllers.has(c)) { controllerOk = true; break; }
+      }
+      if (!controllerOk) continue;
+
+      // Duplicate-pubkey detection: track every account that claims
+      // it; resolve at the end of the scan.
+      if (!seenAccounts.has(pubkey)) seenAccounts.set(pubkey, new Set());
+      seenAccounts.get(pubkey).add(accountId);
+      // Cache the resolved webId in the index so the lookup hot
+      // path doesn't have to re-read the account JSON.
+      if (!idx.has(pubkey)) idx.set(pubkey, { accountId, webId: account.webId, mtimeMs });
+    }
+  }
+  // Drop ambiguous pubkeys and warn loudly.
+  for (const [pubkey, accountIds] of seenAccounts) {
+    if (accountIds.size > 1) {
+      console.error(
+        `well-known-did-nostr: pubkey ${pubkey} claimed by ` +
+        `${accountIds.size} accounts (${[...accountIds].join(', ')}) — ` +
+        `omitting from index to avoid ambiguous resolution`,
+      );
+      idx.delete(pubkey);
+    }
+  }
+  pubkeyIndex = idx;
+  indexBuiltAt = Date.now();
+}
+
+/**
+ * Derive the on-disk profile path from a WebID (and validate
+ * containment in DATA_ROOT). Returns the absolute filesystem path
+ * or `null` if the WebID is unparseable / would escape dataRoot.
+ *
+ * Why a separate function: WHATWG URL parsing already strips most
+ * `..` traversal at the URL layer, but the path-resolve containment
+ * check is defense-in-depth for any future caller that bypasses
+ * URL parsing (string manipulation, alternate parser, etc.). Lives
+ * in its own function so the containment branch is unit-testable
+ * with raw inputs that DON'T go through `new URL()`.
+ *
+ * @internal exported for tests
+ */
+export function profilePathFromWebId(dataRoot, webId, accountId = 'unknown') {
+  if (typeof webId !== 'string') return null;
+  let pathname;
+  try {
+    pathname = new URL(webId).pathname;
+  } catch {
+    return null;
+  }
+  // Strip leading `/` so it's treated as a relative segment, then
+  // resolve and assert the result is at-or-under dataRootAbs. An
+  // account record whose webId path resolves outside dataRoot is
+  // never indexed.
+  const relPath = pathname.replace(/^\/+/, '');
+  const dataRootAbs = path.resolve(dataRoot);
+  const resolved = path.resolve(dataRootAbs, relPath);
+  if (resolved !== dataRootAbs && !resolved.startsWith(dataRootAbs + path.sep)) {
+    console.error(
+      `well-known-did-nostr: account ${accountId} webId ${webId} ` +
+      `resolves outside dataRoot (${resolved}) — skipping`,
+    );
+    return null;
+  }
+  return resolved;
+}
+
+function collectControllerIds(source, baseUrl) {
+  const out = new Set();
+  const c = source?.controller;
+  const list = Array.isArray(c) ? c : (c ? [c] : []);
+  for (const ent of list) {
+    let id;
+    if (typeof ent === 'string') id = ent;
+    else if (ent && typeof ent === 'object') id = ent['@id'] || ent.id;
+    if (id) out.add(absolutize(id, baseUrl));
+  }
+  // Fallback to @id when no explicit controller (CID v1 self-control).
+  if (out.size === 0 && source && (source['@id'] || source.id)) {
+    out.add(absolutize(source['@id'] || source.id, baseUrl));
+  }
+  return out;
+}
+
+/**
+ * Resolve a profile's `authentication` entries to a Set of absolute
+ * IDs. Caller MUST pass an already-absolute base URL — re-deriving
+ * the base from `profile['@id']` here would fail when the profile
+ * subject is relative (e.g. `"@id": "#me"`), leaving the resulting
+ * IDs relative and silently breaking the auth-membership check.
+ */
+function collectAuthenticationIds(profile, baseUrl) {
+  const out = new Set();
+  const auth = profile?.authentication;
+  const list = Array.isArray(auth) ? auth : (auth ? [auth] : []);
+  for (const ent of list) {
+    let id;
+    if (typeof ent === 'string') id = ent;
+    else if (ent && typeof ent === 'object') id = ent['@id'] || ent.id;
+    if (id) out.add(absolutize(id, baseUrl));
+  }
+  return out;
+}
+
+function absolutize(u, base) {
+  if (!u) return u;
+  try { return new URL(u, base).toString(); } catch { return u; }
+}
+
+function stripHashIfAny(u) {
+  if (typeof u !== 'string') return u;
+  try { const url = new URL(u); url.hash = ''; return url.toString(); }
+  catch { return u; }
+}
+
+async function findAccountByNostrPubkey(pubkeyHex) {
+  const lower = pubkeyHex.toLowerCase();
+  if (!pubkeyIndex || (Date.now() - indexBuiltAt) > INDEX_TTL_MS) {
+    // Dedup concurrent rebuilds: under a burst of requests that all
+    // arrive after the TTL expires, only ONE rebuild runs and every
+    // other caller awaits its promise. Without this, N concurrent
+    // requests would each do a full disk scan + parse pass, with
+    // N-1 of them throwing away their result.
+    if (!rebuildInFlight) {
+      rebuildInFlight = rebuildPubkeyIndex().finally(() => {
+        rebuildInFlight = null;
+      });
+    }
+    await rebuildInFlight;
+  }
+  const entry = pubkeyIndex.get(lower);
+  if (!entry) return null;
+  // The webId is now stored on the index entry — no per-request
+  // findById disk read needed. NIP-98 auth (via
+  // resolveDidNostrLocally) and DID-doc generation hit this on
+  // every request, so dropping the I/O matters.
+  return { account: { webId: entry.webId }, mtimeMs: entry.mtimeMs };
+}
+
+/**
+ * In-process local DID resolution: given a Nostr pubkey, return the
+ * matching account's WebID without any network fetch. Lets the
+ * verifyNostrAuth resolver chain prefer local users via direct
+ * function call instead of a same-host HTTP loop, removing both the
+ * latency and the SSRF surface that came with feeding request-
+ * controlled host headers into a `fetch()`.
+ *
+ * Returns null for non-local pubkeys (caller falls back to the
+ * external HTTP resolver, with SSRF protection).
+ */
+export async function resolveDidNostrLocally(pubkeyHex) {
+  if (typeof pubkeyHex !== 'string' || !/^[0-9a-f]{64}$/i.test(pubkeyHex)) return null;
+  const found = await findAccountByNostrPubkey(pubkeyHex.toLowerCase());
+  return found?.account?.webId || null;
+}
+
+/**
+ * Build a CID-shaped DID document for a Nostr pubkey + account pair.
+ *
+ * Uses the spec example's vocabulary (Multikey + publicKeyMultibase)
+ * for max interop with our own resolver and the W3C VC track. The
+ * Multikey value is computed deterministically from the pubkey via
+ * the f-form recipe (multibase `f` + multicodec `e701` + parity byte
+ * `02` + 32-byte xonly hex) — the same shape the doctor's B.2 emits.
+ */
+function buildDidDocument({ pubkey, webId }) {
+  const did = `did:nostr:${pubkey.toLowerCase()}`;
+  const multikey = `f` + `e701` + `02` + pubkey.toLowerCase();
+  const vmId = `${did}#key1`;
+  return {
+    '@context': ['https://w3id.org/did', 'https://w3id.org/nostr/context'],
+    'id': did,
+    'type': 'DIDNostr',
+    'alsoKnownAs': [webId],
+    'verificationMethod': [{
+      'id': vmId,
+      'type': 'Multikey',
+      'controller': did,
+      'publicKeyMultibase': multikey,
+    }],
+    'authentication': [vmId],
+    'assertionMethod': [vmId],
+  };
+}
+
+/**
+ * Fastify handler for GET /.well-known/did/nostr/:pubkeyAndExt
+ *
+ * The :pubkeyAndExt parameter accepts `<pubkey>`, `<pubkey>.json`, or
+ * `<pubkey>.jsonld`; the body is the same DID doc either way. The
+ * spec specifies `.json` as the canonical path, so that's the
+ * primary; the others are friendly aliases.
+ *
+ * The data root is read from `process.env.DATA_ROOT` (matching
+ * `accounts.js`). We don't accept a parameter for it because the
+ * account-index path is derived from the same env elsewhere — taking
+ * a parameter would create two sources of truth and be misleading.
+ */
+export function buildWellKnownDidNostrHandler() {
+  return async function handleWellKnownDidNostr(request, reply) {
+    const raw = String(request.params.pubkeyAndExt || '');
+    const ext = raw.endsWith('.jsonld') ? '.jsonld'
+              : raw.endsWith('.json') ? '.json'
+              : '';
+    const pubkey = (ext ? raw.slice(0, -ext.length) : raw).toLowerCase();
+    // Per-status header policy (so success and failure responses are
+    // both predictable to clients/CDNs):
+    //   200  Cache-Control: max-age=3600  — DID doc seldom changes
+    //   404  Cache-Control: max-age=60    — short TTL so a newly added
+    //                                       key surfaces quickly
+    //   400  Cache-Control: no-store      — request was malformed; never cache
+    // Nostr-Timestamp is set on EVERY response (including errors) per
+    // the did:nostr spec recommendation that clients can correlate the
+    // resolver's clock with the answer they got. Last-Modified only
+    // makes sense for 200 (it tracks the underlying profile mtime);
+    // for errors we omit it because there's no underlying resource.
+    const nowEpoch = Math.floor(Date.now() / 1000);
+    if (!/^[0-9a-f]{64}$/.test(pubkey)) {
+      return reply.code(400)
+        .header('Content-Type', 'application/json')
+        .header('Cache-Control', 'no-store')
+        .header('Nostr-Timestamp', String(nowEpoch))
+        .send({ error: 'pubkey must be 64 hex chars' });
+    }
+    const found = await findAccountByNostrPubkey(pubkey);
+    if (!found?.account) {
+      return reply.code(404)
+        .header('Cache-Control', 'max-age=60')
+        .header('Content-Type', 'application/json')
+        .header('Nostr-Timestamp', String(nowEpoch))
+        .send({ error: 'no local account claims this pubkey' });
+    }
+    const { account, mtimeMs } = found;
+    if (!account.webId) {
+      // Defensive — every account has a webId, but if one slips through,
+      // the DID doc would be useless without alsoKnownAs.
+      return reply.code(404)
+        .header('Cache-Control', 'max-age=60')
+        .header('Content-Type', 'application/json')
+        .header('Nostr-Timestamp', String(nowEpoch))
+        .send({ error: 'account has no webId' });
+    }
+
+    const didDoc = buildDidDocument({ pubkey, webId: account.webId });
+    const contentType = ext === '.jsonld'
+      ? 'application/did+ld+json; charset=utf-8'
+      : 'application/did+json; charset=utf-8';
+    // Two distinct timestamp semantics, two distinct headers:
+    //   - Nostr-Timestamp: the resolver's clock at answer time (uniform
+    //     across 200/404/400 — clients use it to correlate the resolver
+    //     clock with their own, regardless of cache hits).
+    //   - Last-Modified: when the underlying mapping (the user's
+    //     profile file) actually changed — only meaningful for 200,
+    //     so clients/CDNs can do conditional GET against the source.
+    const lastModifiedDate = mtimeMs > 0 ? new Date(mtimeMs) : new Date(indexBuiltAt);
+    return reply
+      .header('Content-Type', contentType)
+      .header('Cache-Control', 'max-age=3600')
+      .header('Nostr-Timestamp', String(nowEpoch))
+      .header('Last-Modified', lastModifiedDate.toUTCString())
+      .send(didDoc);
+  };
+}