neotoma 0.22.1 → 0.22.2

package/dist/actions.d.ts

@@ -141,6 +141,19 @@ type GuestPrincipal = {
     accessToken?: string;
 };
 type RoutePrincipal = UserPrincipal | GuestPrincipal;
+/**
+ * Static path segments under `/entities/` that are routes in their own right,
+ * not entity ids. The `/entities/:id` family of guest-eligible reads must never
+ * treat these as an id (issue #2208): `/entities/duplicates` matched the
+ * `:id`-shaped guest regex below, so a guest principal could be stamped onto a
+ * route whose handler calls `getAuthenticatedUserId()` and 500s.
+ *
+ * Keep in sync with the `app.get("/entities/<segment>")` registrations. The
+ * boot-time assertion in `assertNoShadowedRoutes()` fails the process if a new
+ * static `/entities/*` route is added without being registered ahead of
+ * `/entities/:id`, which is the other half of this invariant.
+ */
+export declare const RESERVED_ENTITY_PATH_SEGMENTS: Set<string>;
 /** Exported for unit tests: routes where guest (AAuth / guest token) may be stamped before handlers run. */
 export declare function routeAcceptsGuestPrincipal(req: Pick<express.Request, "method" | "path">): boolean;
 /**

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/actions.js

@@ -18,11 +18,14 @@ import { encryptResponseMiddleware } from "./middleware/encrypt_response.js";
 import { unknownFieldsGuard } from "./middleware/unknown_fields_guard.js";
 import { aauthVerify, getAAuthContextFromRequest, getAttributionDecisionFromRequest, } from "./middleware/aauth_verify.js";
 import { attributionContext } from "./middleware/attribution_context.js";
+import { dbAbortContext } from "./middleware/db_abort_context.js";
 import { aauthAdmission, getAAuthAdmissionFromRequest } from "./middleware/aauth_admission.js";
 import { buildSessionInfo, normalizeSessionOrigin } from "./services/session_info.js";
+import { probeReadiness } from "./services/readiness.js";
 import { AttributionPolicyError, enforceAttributionPolicy } from "./services/attribution_policy.js";
 import { OverridePolicyViolationError } from "./services/override_validation.js";
 import { CursorError } from "./services/entity_cursor.js";
+import { assertNoShadowedRoutes } from "./services/route_shadowing.js";
 import { StorePolicyUnavailableError } from "./services/instance_policy.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
 import { assertGuestWriteAllowed, AccessPolicyError, } from "./services/access_policy.js";
@@ -34,6 +37,7 @@ import { createAgentIdentity as buildAgentIdentity, getAgentIdentityFromRequest,
 import { initServerKeys } from "./services/encryption_service.js";
 import { storeRawContent, downloadRawContent, resolveLocalSourceFilePath, SourceFileNotFoundError, } from "./services/raw_storage.js";
 import { attachSourceLabelsToObservations } from "./services/observation_source_label.js";
+import { isFilesystemLocalToCaller, buildFilePathServerLocalError, decodeFileContent, FileInputError, } from "./services/file_input_diagnostics.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { NeotomaServer } from "./server.js";
@@ -1517,6 +1521,10 @@ app.use(aauthVerify({
 // may nest a more specific `runWithRequestContext` — nested scopes
 // shadow outer ones exactly as intended.
 app.use(attributionContext());
+// Bind a per-request AbortSignal so DB reads stop consuming a reader-pool slot
+// when the client hangs up (#2217). Reads only — a write must not be abandoned
+// half-applied. No-op on backends without a worker pool.
+app.use(dbAbortContext());
 // Stronger AAuth Admission plan: resolve verified AAuth identities to
 // `agent_grant` entities and stamp `req.aauthAdmission` /
 // `req.authenticatedUserId`. Runs after attributionContext so the
@@ -2024,6 +2032,10 @@ function sendValidationError(res, issues) {
     }));
 }
 // Public health endpoint (no auth)
+//
+// LIVENESS ONLY. This reads package.json off disk and never touches the
+// database, so it returns 200 throughout a total read outage. Do not use it as
+// a Fly health check or as a watchdog's healthy verdict — use /ready below.
 app.get("/health", (_req, res) => {
     let version = "0.0.0";
     try {
@@ -2036,6 +2048,21 @@ app.get("/health", (_req, res) => {
     }
     return res.json({ ok: true, version });
 });
+// Public readiness endpoint (no auth). This is what Fly's health check hits —
+// see the [[http_service.checks]] block in fly.toml.
+//
+// Unlike /health above, it exercises the real read path and returns 503 when
+// the database is unreachable, erroring, or too slow. See
+// src/services/readiness.ts for exactly what a passing result does and does
+// not prove.
+app.get("/ready", async (_req, res) => {
+    const result = await probeReadiness(db);
+    if (!result.ok) {
+        logger.warn(`[Ready] database probe failed after ${result.latency_ms}ms: ${result.error}`);
+        return res.status(503).json(result);
+    }
+    return res.json(result);
+});
 // ============================================================================
 // Sandbox endpoints
 //
@@ -2467,6 +2494,24 @@ app.get("/mcp/oauth/google/callback", async (req, res) => {
         return failWith(error?.message ?? "Google sign-in failed.");
     }
 });
+/**
+ * Send an authorize-endpoint refusal as plain text.
+ *
+ * `res.send(string)` defaults to `text/html`, which makes the body an HTML sink.
+ * That matters here because this endpoint is reached by a BROWSER, before any
+ * authentication, with a `redirect_uri` supplied by whoever crafted the link —
+ * so anything echoed from the request into an HTML body would execute on this
+ * instance's own origin. Setting `text/plain` removes the sink rather than
+ * filtering it, which is what makes it safe to name the rejected redirect_uri
+ * in the body below.
+ *
+ * Plain text (rather than the canonical JSON ErrorEnvelope) is also the right
+ * shape for the reader: this renders in a browser address bar mid-redirect, for
+ * a human. Declared as `text/plain` in openapi.yaml under `mcpOAuthAuthorize`.
+ */
+function sendAuthorizeRefusal(res, status, message) {
+    return res.status(status).type("text/plain").send(message);
+}
 // RFC 8414 authorization endpoint (GET) for Cursor and other OAuth clients
 app.get("/mcp/oauth/authorize", async (req, res) => {
     try {
@@ -2485,11 +2530,11 @@ app.get("/mcp/oauth/authorize", async (req, res) => {
         });
         if (!redirect_uri) {
             logger.warn("[MCP OAuth] Authorize rejected: missing redirect_uri");
-            return res.status(400).send("redirect_uri is required");
+            return sendAuthorizeRefusal(res, 400, "redirect_uri is required");
         }
         if (!state) {
             logger.warn("[MCP OAuth] Authorize rejected: missing state");
-            return res.status(400).send("state is required");
+            return sendAuthorizeRefusal(res, 400, "state is required");
         }
         const isOpenAiCustomGptRedirect = redirect_uri &&
             (redirect_uri.includes("chatgpt.com") || redirect_uri.includes("chat.openai.com"));
@@ -2498,7 +2543,7 @@ app.get("/mcp/oauth/authorize", async (req, res) => {
             logger.warn("[MCP OAuth] Authorize rejected: missing PKCE for non-OpenAI redirect", {
                 redirect_uri: sanitizeRedirectUriForLog(redirect_uri),
             });
-            return res.status(400).send("code_challenge and code_challenge_method=S256 are required");
+            return sendAuthorizeRefusal(res, 400, "code_challenge and code_challenge_method=S256 are required");
         }
         if (!hasPkce && isOpenAiCustomGptRedirect) {
             // Allow OAuth without client PKCE for OpenAI Custom GPT only (weaker security; see docs).
@@ -2509,9 +2554,7 @@ app.get("/mcp/oauth/authorize", async (req, res) => {
             return res.redirect(`/mcp/oauth/key-auth?next=${encodeURIComponent(nextPath)}`);
         }
         if (dev_stub === "1" || dev_stub === "true") {
-            return res
-                .status(400)
-                .send("dev_stub is disabled. OAuth requires key authentication via /mcp/oauth/key-auth.");
+            return sendAuthorizeRefusal(res, 400, "dev_stub is disabled. OAuth requires key authentication via /mcp/oauth/key-auth.");
         }
         if (config.storageBackend === "local") {
             // When reached via tunnel, only allow redirect_uri to localhost, app schemes, or OpenAI Custom GPT
@@ -2521,12 +2564,31 @@ app.get("/mcp/oauth/authorize", async (req, res) => {
                 // proxy) so an Inspector callback on this instance's own origin is allowed.
                 const selfHost = req.header("x-forwarded-host")?.split(",")[0]?.trim() || req.get("host");
                 if (!isRedirectUriAllowedForTunnel(redirect_uri, selfHost)) {
+                    // Name the config variable and whether it is even set: an operator who
+                    // has configured a callback and still gets refused otherwise has no way
+                    // to tell a typo from an unset variable from an exact-match miss.
+                    const trustedCount = config.oauthTrustedCallbackUrls.length;
+                    const sanitizedRedirectUri = sanitizeRedirectUriForLog(redirect_uri);
                     logger.warn("[MCP OAuth] Authorize rejected: redirect_uri not allowed for tunnel", {
-                        redirect_uri: sanitizeRedirectUriForLog(redirect_uri),
+                        redirect_uri: sanitizedRedirectUri,
+                        trusted_callback_urls_configured: trustedCount,
                     });
-                    return res
-                        .status(400)
-                        .send("redirect_uri is not allowed when connecting via a tunnel. Use cursor://, localhost, loopback, or trusted callback URLs (OpenAI/Claude).");
+                    return sendAuthorizeRefusal(res, 400, "redirect_uri is not allowed when connecting via a tunnel. Use cursor://, localhost, loopback, or trusted callback URLs (OpenAI/Claude). " +
+                        // Echo what the server actually compared. An operator on a hosted
+                        // deploy has no log access, and every likely failure here is a
+                        // NEAR miss (trailing slash, port, case, a dot segment that
+                        // resolved) — indistinguishable from a typo or a client-side bug
+                        // without seeing the value the server saw. Safe to echo because
+                        // this response is text/plain (see sendAuthorizeRefusal) and
+                        // because the value is sanitized: scheme, host and path only,
+                        // with query and fragment — where the code and state live —
+                        // already stripped.
+                        (sanitizedRedirectUri
+                            ? `The server compared: ${sanitizedRedirectUri} (query and fragment ignored). `
+                            : "") +
+                        (trustedCount > 0
+                            ? `This instance has ${trustedCount} operator-configured callback URL(s) in NEOTOMA_OAUTH_TRUSTED_CALLBACK_URLS; none matched. That list is matched on the EXACT full callback URL: scheme, host, port and path must all agree. The host is compared case-insensitively and the path case-sensitively; a trailing slash and a default port (:443) are insignificant; query and fragment are ignored; and plaintext http: is only honoured for loopback hosts.`
+                            : "To trust a self-hosted app's callback, set NEOTOMA_OAUTH_TRUSTED_CALLBACK_URLS to its exact full callback URL (for example https://app.example.com/auth/callback)."));
                 }
             }
             const { randomUUID } = await import("node:crypto");
@@ -2581,7 +2643,7 @@ app.get("/mcp/oauth/authorize", async (req, res) => {
     }
     catch (error) {
         logError("MCPOAuthAuthorize", req, error);
-        return res.status(500).send(error.message ?? "Authorization failed");
+        return sendAuthorizeRefusal(res, 500, error.message ?? "Authorization failed");
     }
 });
 // Local OAuth login page (local backend only)
@@ -2919,10 +2981,23 @@ function explicitGuestAccessTokenFromRequest(req) {
     }
     return undefined;
 }
+/**
+ * Static path segments under `/entities/` that are routes in their own right,
+ * not entity ids. The `/entities/:id` family of guest-eligible reads must never
+ * treat these as an id (issue #2208): `/entities/duplicates` matched the
+ * `:id`-shaped guest regex below, so a guest principal could be stamped onto a
+ * route whose handler calls `getAuthenticatedUserId()` and 500s.
+ *
+ * Keep in sync with the `app.get("/entities/<segment>")` registrations. The
+ * boot-time assertion in `assertNoShadowedRoutes()` fails the process if a new
+ * static `/entities/*` route is added without being registered ahead of
+ * `/entities/:id`, which is the other half of this invariant.
+ */
+export const RESERVED_ENTITY_PATH_SEGMENTS = new Set(["duplicates", "merge", "split", "query"]);
 /** Exported for unit tests: routes where guest (AAuth / guest token) may be stamped before handlers run. */
 export function routeAcceptsGuestPrincipal(req) {
     const path = req.path;
-    if ((req.method === "POST" &&
+    if (req.method === "POST" &&
         (path === "/issues/submit" ||
             path === "/api/issues/submit" ||
             path === "/issues/status" ||
@@ -2932,12 +3007,19 @@ export function routeAcceptsGuestPrincipal(req) {
             path === "/subscribe" ||
             path === "/unsubscribe" ||
             path === "/list_subscriptions" ||
-            path === "/get_subscription_status")) ||
-        (req.method === "GET" &&
-            (/^\/entities\/[^/]+(?:\/(?:observations|relationships|html))?$/.test(path) ||
-                path === "/events/stream"))) {
+            path === "/get_subscription_status")) {
         return true;
     }
+    if (req.method === "GET") {
+        if (path === "/events/stream")
+            return true;
+        const match = /^\/entities\/([^/]+)(?:\/(?:observations|relationships|html))?$/.exec(path);
+        if (!match)
+            return false;
+        // Fail closed: a reserved static segment is a route, not an entity id, so it
+        // is not guest-eligible unless it is explicitly listed as such above.
+        return !RESERVED_ENTITY_PATH_SEGMENTS.has(match[1]);
+    }
     return false;
 }
 /**
@@ -3262,7 +3344,8 @@ app.use(async (req, res, next) => {
         (req.method === "GET" &&
             (req.path === "/openapi.yaml" ||
                 req.path === "/openapi_actions.yaml" ||
-                req.path === "/health")) ||
+                req.path === "/health" ||
+                req.path === "/ready")) ||
         (req.method === "POST" && req.path === "/auth/dev-signin")) {
         return next();
     }
@@ -3846,6 +3929,53 @@ app.all("/entities", (req, res) => {
         supported: ["GET /entities", "POST /entities/query"],
     });
 });
+// IMPORTANT (issue #2208): this static route MUST stay registered before
+// `GET /entities/:id` below. Express matches first-wins, so a param route
+// registered earlier would capture `id = "duplicates"` and 404. The
+// boot-time assertion in assertNoShadowedRoutes() enforces this invariant.
+// GET /entities/duplicates - List candidate duplicate entity pairs (R5).
+// Read-only fuzzy post-hoc detector. Never auto-merges. Hands off to
+// /entities/merge once an operator or agent confirms a pair.
+app.get("/entities/duplicates", async (req, res) => {
+    try {
+        const entityType = typeof req.query.entity_type === "string" ? req.query.entity_type : undefined;
+        if (!entityType) {
+            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "entity_type query parameter is required");
+        }
+        const providedUserId = typeof req.query.user_id === "string" ? req.query.user_id : undefined;
+        const authenticatedUserId = await getAuthenticatedUserId(req, providedUserId);
+        if (providedUserId && providedUserId !== authenticatedUserId) {
+            return sendError(res, 403, "FORBIDDEN", "user_id does not match authenticated user.");
+        }
+        const thresholdRaw = typeof req.query.threshold === "string" ? req.query.threshold : undefined;
+        const limitRaw = typeof req.query.limit === "string" ? req.query.limit : undefined;
+        const threshold = thresholdRaw ? Number(thresholdRaw) : undefined;
+        if (threshold !== undefined && (Number.isNaN(threshold) || threshold <= 0 || threshold > 1)) {
+            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "threshold must be a number in (0, 1]");
+        }
+        const limit = limitRaw ? Number(limitRaw) : undefined;
+        if (limit !== undefined && (!Number.isFinite(limit) || limit < 1 || limit > 200)) {
+            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "limit must be an integer in [1, 200]");
+        }
+        const { findDuplicateCandidates } = await import("./services/duplicate_detection.js");
+        const candidates = await findDuplicateCandidates({
+            entityType,
+            userId: authenticatedUserId,
+            threshold,
+            limit,
+        });
+        return res.json({
+            candidates,
+            entity_type: entityType,
+            threshold: threshold ?? null,
+        });
+    }
+    catch (error) {
+        logError("APIError:entities_duplicates", req, error);
+        const message = error instanceof Error ? error.message : "Failed to list potential duplicates";
+        return sendError(res, 500, "DB_QUERY_FAILED", message);
+    }
+});
 // GET /api/entities/:id - Get entity detail with snapshot and provenance (FU-601)
 // REQUIRES AUTHENTICATION - verifies entity belongs to authenticated user
 app.get("/entities/:id", async (req, res) => {
@@ -4362,27 +4492,30 @@ app.get("/schemas/:entity_type", async (req, res) => {
         const entityType = decodeURIComponent(req.params.entity_type);
         const { SchemaRegistryService } = await import("./services/schema_registry.js");
         const schemaRegistry = new SchemaRegistryService();
-        // Handle authentication - support both Ed25519 and session tokens
-        const headerAuth = req.headers.authorization || "";
-        let userId = req.query.user_id;
-        if (headerAuth.startsWith("Bearer ")) {
-            const token = headerAuth.slice("Bearer ".length).trim();
-            // Try to validate as Ed25519 bearer token first
-            const registered = ensurePublicKeyRegistered(token);
-            if (!registered || !isBearerTokenValid(token)) {
-                // Try to validate as session token
-                try {
-                    const { validateSessionToken } = await import("./services/mcp_auth.js");
-                    const validated = await validateSessionToken(token);
-                    // Use validated user ID if not provided in query
-                    userId = userId || validated.userId;
-                }
-                catch {
-                    // Not a valid token - continue without user_id (will try global schema)
-                }
-            }
-            // If Ed25519 token is valid, use user_id from query (Ed25519 tokens don't contain user info)
-        }
+        // SECURITY (GHSA-f48j-993h-g6qr): `user_id` selects the schema SCOPE that
+        // loadActiveSchema reads — a user-scoped row shadows the global one — so it
+        // carries the safety meaning for this route and must be validated against
+        // the authenticated principal, never used as supplied.
+        //
+        // This route previously initialised `userId` straight from
+        // `req.query.user_id` and ran its own Bearer/session handling, so the query
+        // value became the scope rather than a request for one. That bespoke block
+        // is removed in favour of the shared guard its sibling GET /schemas already
+        // uses. Nothing is lost by removing it: the app-wide auth middleware runs
+        // ahead of this route (this path is not on the public allowlist, which is
+        // only /openapi*.yaml, /health and /ready), validates Ed25519 bearers
+        // *including the request signature*, falls through to the same
+        // validateSessionToken for session bearers, stamps the principal, and 401s
+        // an unresolvable token. The route-level copy did strictly less — no
+        // signature verification, and a silent fall-through that kept the
+        // caller-supplied id when validation failed.
+        //
+        // Legitimate callers are unaffected: the CLI's optional --user-id and the
+        // eval harness pass nothing by default, so the principal resolves itself,
+        // and getAuthenticatedUserId still honours the local-dev override for CLI
+        // and dev flows. Built-in/code-defined schema discovery is unchanged — it
+        // is the fallback below, reached the same way once the scope is resolved.
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
         // Try to load active schema (global or user-specific), then fallback to code-defined schemas
         let schema = await schemaRegistry.loadActiveSchema(entityType, userId);
         if (!schema) {
@@ -4407,9 +4540,11 @@ app.get("/schemas/:entity_type", async (req, res) => {
         return res.json(schema);
     }
     catch (error) {
-        logError("APIError:schema_detail", req, error);
-        const message = error instanceof Error ? error.message : "Failed to get schema";
-        return sendError(res, 500, "DB_QUERY_FAILED", message);
+        // Routed through handleApiError so a rejected user_id surfaces as 403 and an
+        // unresolved principal as 401 — the same mapping GET /schemas gets. The
+        // previous bespoke catch turned every failure into a 500, which would have
+        // reported the guard's refusal as a server fault.
+        return handleApiError(req, res, error, "Failed to get schema", "DB_QUERY_FAILED", "APIError:schema_detail");
     }
 });
 /**
@@ -6862,7 +6997,9 @@ export async function storeStructuredForApi(params) {
 // boundary" section in src/services/instance_policy.ts's docblock.
 async function storeUnstructuredForApi(params) {
     const { fileContent, fileBuffer, filePath, mimeType, idempotencyKey, originalFilename, sourceType, userId, storageMode = "inline", } = params;
-    const resolvedFileBuffer = fileBuffer ?? (fileContent !== undefined ? Buffer.from(fileContent, "base64") : undefined);
+    // decodeFileContent rejects non-base64 instead of letting Node discard the
+    // invalid characters and store corrupted bytes (#2325).
+    const resolvedFileBuffer = fileBuffer ?? (fileContent !== undefined ? decodeFileContent(fileContent) : undefined);
     if (!resolvedFileBuffer && storageMode !== "reference") {
         throw new Error("fileContent or fileBuffer is required for inline storage");
     }
@@ -6939,9 +7076,24 @@ async function handleStorePost(req, res) {
             let originalFilename = parsed.data.original_filename;
             let resolvedFileBuffer;
             if (hasFilePath) {
+                // `file_path` resolves against *this* process's filesystem. On a remote
+                // instance it cannot mean the caller's disk, and the old failure here
+                // was a bare Node ENOENT — worse than MCP's, which at least named the
+                // path. Both transports now fail identically (#2325).
+                if (!isFilesystemLocalToCaller()) {
+                    const serverLocal = buildFilePathServerLocalError(parsed.data.file_path);
+                    sendError(res, 400, serverLocal.code, serverLocal.message, serverLocal.details);
+                    return null;
+                }
                 const resolvedPath = path.isAbsolute(parsed.data.file_path)
                     ? parsed.data.file_path
                     : path.resolve(process.cwd(), parsed.data.file_path);
+                if (!fs.existsSync(resolvedPath)) {
+                    sendError(res, 400, "ERR_FILE_NOT_FOUND", `File not found: ${resolvedPath}`, {
+                        file_path: parsed.data.file_path,
+                    });
+                    return null;
+                }
                 if (parsed.data.source_storage === "reference") {
                     // For reference mode, don't read the file buffer, just use the path
                     if (!mimeType) {
@@ -7038,6 +7190,13 @@ async function handleStorePost(req, res) {
         if (error instanceof Error && error.message.includes("Not authenticated")) {
             return sendError(res, 401, "AUTH_REQUIRED", error.message);
         }
+        // A bad file input is the caller's payload, not a server fault: 400 with
+        // the code, never the generic 500 below. Falling through would have made a
+        // non-base64 `file_content` look like a server outage (#2325).
+        if (error instanceof FileInputError) {
+            logWarn("FileInputError:store", req, { code: error.code });
+            return sendError(res, 400, error.code, error.message, error.details);
+        }
         const errCode = error && typeof error === "object" ? error.code : undefined;
         if (errCode === "ERR_FORBIDDEN_ENTITY_TYPE" || errCode === "ERR_PLURAL_ENTITY_TYPE") {
             const message = error instanceof Error ? error.message : String(error);
@@ -7480,49 +7639,9 @@ app.post("/observations/query", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", message);
     }
 });
-// GET /entities/duplicates - List candidate duplicate entity pairs (R5).
-// Read-only fuzzy post-hoc detector. Never auto-merges. Hands off to
-// /entities/merge once an operator or agent confirms a pair.
-app.get("/entities/duplicates", async (req, res) => {
-    try {
-        const entityType = typeof req.query.entity_type === "string" ? req.query.entity_type : undefined;
-        if (!entityType) {
-            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "entity_type query parameter is required");
-        }
-        const providedUserId = typeof req.query.user_id === "string" ? req.query.user_id : undefined;
-        const authenticatedUserId = await getAuthenticatedUserId(req, providedUserId);
-        if (providedUserId && providedUserId !== authenticatedUserId) {
-            return sendError(res, 403, "FORBIDDEN", "user_id does not match authenticated user.");
-        }
-        const thresholdRaw = typeof req.query.threshold === "string" ? req.query.threshold : undefined;
-        const limitRaw = typeof req.query.limit === "string" ? req.query.limit : undefined;
-        const threshold = thresholdRaw ? Number(thresholdRaw) : undefined;
-        if (threshold !== undefined && (Number.isNaN(threshold) || threshold <= 0 || threshold > 1)) {
-            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "threshold must be a number in (0, 1]");
-        }
-        const limit = limitRaw ? Number(limitRaw) : undefined;
-        if (limit !== undefined && (!Number.isFinite(limit) || limit < 1 || limit > 200)) {
-            return sendError(res, 400, "VALIDATION_INVALID_FORMAT", "limit must be an integer in [1, 200]");
-        }
-        const { findDuplicateCandidates } = await import("./services/duplicate_detection.js");
-        const candidates = await findDuplicateCandidates({
-            entityType,
-            userId: authenticatedUserId,
-            threshold,
-            limit,
-        });
-        return res.json({
-            candidates,
-            entity_type: entityType,
-            threshold: threshold ?? null,
-        });
-    }
-    catch (error) {
-        logError("APIError:entities_duplicates", req, error);
-        const message = error instanceof Error ? error.message : "Failed to list potential duplicates";
-        return sendError(res, 500, "DB_QUERY_FAILED", message);
-    }
-});
+// NOTE: `GET /entities/duplicates` is registered earlier in this file,
+// immediately before `GET /entities/:id`. A static path must be registered
+// before any param route that would also match it (issue #2208).
 // POST /api/entities/merge - Merge duplicate entities
 // REQUIRES AUTHENTICATION - validates user_id matches authenticated user and entities belong to user
 app.post("/entities/merge", async (req, res) => {
@@ -9484,18 +9603,27 @@ app.post("/health_check_snapshots", async (req, res) => {
             }
         }
         let fixedCount = 0;
+        let redirectedCount = 0;
         if (auto_fix && staleEntities.length > 0) {
             // Recompute snapshots for stale entities using observationReducer
             const { observationReducer } = await import("./reducers/observation_reducer.js");
+            const { resolveOwnedObservations } = await import("./services/attachment_resolution.js");
             for (const entity of staleEntities) {
                 try {
-                    // Get all observations for this entity
-                    const { data: observations } = await db
-                        .from("observations")
-                        .select("*")
-                        .eq("entity_id", entity.entity_id)
-                        .order("observed_at", { ascending: false });
-                    if (!observations || observations.length === 0)
+                    // #2343: the observations ATTACHED to this entity, resolved through
+                    // the declared layer, and null when the id is redirected — a
+                    // tombstone owns no snapshot, so auto-fix must skip it rather than
+                    // upsert the survivor's snapshot under the tombstone's id.
+                    // `null` scope, deliberately: this endpoint's observation fetch was
+                    // unscoped before #2343, and adding a user_id filter here would
+                    // change which rows the reducer sees. Routing the fetch through the
+                    // seam is this PR's job; tightening this endpoint's tenancy is not.
+                    const observations = await resolveOwnedObservations(entity.entity_id, null);
+                    if (observations === null) {
+                        redirectedCount++;
+                        continue;
+                    }
+                    if (observations.length === 0)
                         continue;
                     // Recompute snapshot
                     const newSnapshot = await observationReducer.computeSnapshot(entity.entity_id, observations);
@@ -9529,11 +9657,15 @@ app.post("/health_check_snapshots", async (req, res) => {
             message: staleEntities.length === 0
                 ? "All snapshots healthy"
                 : auto_fix
-                    ? `Found ${staleEntities.length} stale snapshots, fixed ${fixedCount}`
+                    ? `Found ${staleEntities.length} stale snapshots, fixed ${fixedCount}` +
+                        (redirectedCount > 0
+                            ? `, skipped ${redirectedCount} redirected (merged-away) id(s)`
+                            : "")
                     : `Found ${staleEntities.length} stale snapshots`,
             checked: staleSnapshots?.length || 0,
             stale: staleEntities.length,
             fixed: auto_fix ? fixedCount : undefined,
+            skipped_redirected: auto_fix ? redirectedCount : undefined,
             stale_snapshots: staleEntities,
         });
     }
@@ -9747,9 +9879,20 @@ function emitSandboxBootBanner(mode, reason, shouldRefuseBoot, refusePolicy, pro
     });
     process.stderr.write(lines.join("\n"));
 }
+/**
+ * Fail the boot if any static route is unreachable because an earlier param
+ * route matches it first (issue #2208). Runs after every route registration
+ * and before the process binds a port: an unreachable route table is not a
+ * runnable state, and a warning is what let `GET /entities/duplicates` ship
+ * broken for months.
+ */
+function assertRouteTableIsReachable() {
+    assertNoShadowedRoutes(app);
+}
 /** Try to bind on a port; resolves with server and port, or rejects on error (e.g. EADDRINUSE). */
 function tryListen(port) {
     return new Promise((resolve, reject) => {
+        assertRouteTableIsReachable();
         const server = app.listen(port, () => {
             // When `port === 0` the OS assigns an ephemeral port. We must report
             // the actually-bound port back to callers (the eval harness's