neotoma 0.18.8 → 0.20.0

package/dist/actions.d.ts

@@ -2,6 +2,7 @@ import express from "express";
 import { type GuestIdentity } from "./services/access_policy.js";
 import { type AgentIdentity } from "./crypto/agent_identity.js";
 import { type NeotomaSandboxModeName } from "./services/sandbox_mode.js";
+import { OAuthKeySessionStore } from "./services/oauth_key_gate.js";
 import { type StoreInterpretationInput } from "./shared/action_schemas.js";
 /** Exposed for the /me route and any other surface that needs the boot-time mode verdict. */
 export declare function getResolvedServerMode(): NeotomaSandboxModeName | null;
@@ -76,6 +77,51 @@ export declare function isTrustedProxyIP(ip: string, env?: NodeJS.ProcessEnv): b
  * entirely and remains valid for single-host deployments without a tunnel.
  */
 export declare function isLocalRequest(req: express.Request): boolean;
+/** Exported for tests asserting the cookie maxAge and the server-side session
+ *  expiry agree — the invariant setOAuthKeySessionCookie's docstring names. */
+export declare const oauthKeySessions: OAuthKeySessionStore;
+/**
+ * Lifetime of a SIGN-IN session (Google). Distinct from the key-entry gate's
+ * short default: a user who signs in expects to stay signed in, whereas the
+ * key-entry gate deliberately closes fast. Reusing the 15-minute gate TTL for
+ * sign-in is what logged hosted-instance users out every quarter hour (#2005).
+ *
+ * Override with NEOTOMA_SIGN_IN_SESSION_TTL_MIN (minutes). Default 7 days.
+ */
+export declare const DEFAULT_SIGN_IN_SESSION_TTL_MIN: number;
+/** Upper bound for the sign-in TTL override: 365 days in minutes. A value past
+ *  this is a typo (an extra zero), not an intent — without a ceiling,
+ *  "9999999999999" yields a ~19-million-year session. Mirrors the low-end
+ *  guard rather than guarding only one side (#2007 qa lens). */
+export declare const MAX_SIGN_IN_SESSION_TTL_MIN: number;
+/**
+ * Parse NEOTOMA_SIGN_IN_SESSION_TTL_MIN into milliseconds. Exported (and pure)
+ * so the override's precedence and malformed-input behavior are directly
+ * testable — a silently-wrong TTL here reintroduces exactly the desync class
+ * this change fixes.
+ *
+ * Precedence: an integer within (0, MAX_SIGN_IN_SESSION_TTL_MIN] wins.
+ * Everything else — unset, non-numeric, zero, negative, or above the ceiling —
+ * falls back to the 7-day default rather than producing a degenerate session.
+ *
+ * Note on parseInt semantics, deliberately kept: "7.5" truncates to 7 minutes
+ * and "1e10" parses as 1 minute (parseInt stops at the 'e'). Both are accepted
+ * as-is because they are in-range integers after parsing; the fallback exists
+ * for values that are absent, unparseable, or out of range, not to second-guess
+ * a caller who wrote a decimal. Asserted in tests so the behavior is documented
+ * rather than incidental.
+ */
+export declare function resolveSignInSessionTtlMs(raw: string | undefined): number;
+/**
+ * Issue an OAuth key-session cookie. `ttlMs` covers BOTH the server-side
+ * session and the cookie's own maxAge — they must agree, or the browser keeps
+ * presenting a cookie the server has already forgotten (or vice versa).
+ * Omit it for the short key-entry gate; pass SIGN_IN_SESSION_TTL_MS for
+ * sign-in (#2005).
+ */
+export declare function setOAuthKeySessionCookie(req: express.Request, res: express.Response, ttlMs?: number): string;
+/** Resolve the local-auth user_id a Google-verified session (if any) mapped to this request. */
+export declare function getGoogleVerifiedUserId(req: express.Request): string | undefined;
 /**
  * Derive the canonical `@authority` the AAuth profile requires (AAuth §10.3.1).
  * We trust explicit configuration first, then fall back to the host the
@@ -111,6 +157,18 @@ export declare function routeAllowsLocalIssueWriteFallback(req: Pick<express.Req
 export declare function routeConsumesGuestWriteBudget(req: Pick<express.Request, "method" | "path">): boolean;
 /** Exported for unit tests: guest-rate-limit key precedence is thumbprint -> guest token -> IP. */
 export declare function guestWriteRateLimitKey(req: express.Request): string;
+/**
+ * Issue *submission* is the one route a third party may reach with no identity
+ * at all: the guest access token is minted BY the submit, so requiring one to
+ * perform it is a chicken-and-egg that closes the inbox to first contact.
+ *
+ * Deliberately submit-only. `add_message` stays authenticated: by the time a
+ * reporter has a thread to append to, they hold the token returned by their
+ * submit, so anonymity buys nothing there — and letting an unidentified caller
+ * write into an existing thread is a strictly wider blast radius than letting
+ * them open a new one. The token is what proves "I opened this thread".
+ */
+export declare function routeAcceptsAnonymousIssueSubmit(req: Pick<express.Request, "method" | "path">): boolean;
 /**
  * Derive a userId for a guest principal from the validated token grant.
  *
@@ -180,6 +238,7 @@ export declare function storeStructuredForApi(params: {
         observation_index: number;
         entity_type: string;
         entity_id: string;
+        details?: Record<string, unknown>;
     }[] | undefined;
     warnings?: {
         code: string;

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

@@ -22,6 +22,7 @@ import { aauthAdmission, getAAuthAdmissionFromRequest } from "./middleware/aauth
 import { buildSessionInfo, normalizeSessionOrigin } from "./services/session_info.js";
 import { AttributionPolicyError, enforceAttributionPolicy } from "./services/attribution_policy.js";
 import { OverridePolicyViolationError } from "./services/override_validation.js";
+import { CursorError } from "./services/entity_cursor.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
 import { assertGuestWriteAllowed, AccessPolicyError, } from "./services/access_policy.js";
 import { hashGuestAccessToken } from "./services/guest_access_token.js";
@@ -53,6 +54,7 @@ import { resolveSandboxReportTransport } from "./services/sandbox/transport.js";
 import { getSqliteDb } from "./repositories/sqlite/sqlite_client.js";
 import { getMcpAuthToken } from "./crypto/mcp_auth_token.js";
 import { isOauthKeyCredentialValid, normalizeOauthNextPath, OAuthKeySessionStore, } from "./services/oauth_key_gate.js";
+import { buildGoogleAuthorizeUrl, createGoogleSigninNonce, consumeGoogleSigninNonce, exchangeGoogleAuthorizationCode, getSharedGraphUserId, GoogleIdTokenError, isGoogleSigninEnabled, verifyGoogleIdToken, } from "./services/google_oidc.js";
 import { AnalyzeSchemaCandidatesRequestSchema, AuditUndeclaredFragmentsRequestSchema, CorrectEntityRequestSchema, CreateInterpretationRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, IssuesBulkEntityIdsRequestSchema, IssuesAddMessageRequestSchema, IssuesGetStatusRequestSchema, IssuesSubmitRequestSchema, IssuesSyncRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, RELATIONSHIP_ENTITY_ID_FORMAT_HINT, RELATIONSHIP_ENTITY_ID_FORMAT_ISSUE_CODE, StoreRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
 import { getMimeTypeFromExtension } from "./services/file_text_extraction.js";
 import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers.js";
@@ -1095,7 +1097,47 @@ export function isLocalRequest(req) {
     return !isProductionEnvironment();
 }
 const OAUTH_KEY_SESSION_COOKIE = "neotoma_oauth_key_session";
-const oauthKeySessions = new OAuthKeySessionStore();
+/** Exported for tests asserting the cookie maxAge and the server-side session
+ *  expiry agree — the invariant setOAuthKeySessionCookie's docstring names. */
+export const oauthKeySessions = new OAuthKeySessionStore();
+/**
+ * Lifetime of a SIGN-IN session (Google). Distinct from the key-entry gate's
+ * short default: a user who signs in expects to stay signed in, whereas the
+ * key-entry gate deliberately closes fast. Reusing the 15-minute gate TTL for
+ * sign-in is what logged hosted-instance users out every quarter hour (#2005).
+ *
+ * Override with NEOTOMA_SIGN_IN_SESSION_TTL_MIN (minutes). Default 7 days.
+ */
+export const DEFAULT_SIGN_IN_SESSION_TTL_MIN = 7 * 24 * 60;
+/** Upper bound for the sign-in TTL override: 365 days in minutes. A value past
+ *  this is a typo (an extra zero), not an intent — without a ceiling,
+ *  "9999999999999" yields a ~19-million-year session. Mirrors the low-end
+ *  guard rather than guarding only one side (#2007 qa lens). */
+export const MAX_SIGN_IN_SESSION_TTL_MIN = 365 * 24 * 60;
+/**
+ * Parse NEOTOMA_SIGN_IN_SESSION_TTL_MIN into milliseconds. Exported (and pure)
+ * so the override's precedence and malformed-input behavior are directly
+ * testable — a silently-wrong TTL here reintroduces exactly the desync class
+ * this change fixes.
+ *
+ * Precedence: an integer within (0, MAX_SIGN_IN_SESSION_TTL_MIN] wins.
+ * Everything else — unset, non-numeric, zero, negative, or above the ceiling —
+ * falls back to the 7-day default rather than producing a degenerate session.
+ *
+ * Note on parseInt semantics, deliberately kept: "7.5" truncates to 7 minutes
+ * and "1e10" parses as 1 minute (parseInt stops at the 'e'). Both are accepted
+ * as-is because they are in-range integers after parsing; the fallback exists
+ * for values that are absent, unparseable, or out of range, not to second-guess
+ * a caller who wrote a decimal. Asserted in tests so the behavior is documented
+ * rather than incidental.
+ */
+export function resolveSignInSessionTtlMs(raw) {
+    const parsed = Number.parseInt(raw || "", 10);
+    const inRange = Number.isFinite(parsed) && parsed > 0 && parsed <= MAX_SIGN_IN_SESSION_TTL_MIN;
+    const minutes = inRange ? parsed : DEFAULT_SIGN_IN_SESSION_TTL_MIN;
+    return minutes * 60 * 1000;
+}
+const SIGN_IN_SESSION_TTL_MS = resolveSignInSessionTtlMs(process.env.NEOTOMA_SIGN_IN_SESSION_TTL_MIN);
 function readCookie(req, name) {
     const header = (req.headers["cookie"] || req.headers["Cookie"] || "");
     if (!header)
@@ -1321,8 +1363,15 @@ function hasValidOAuthKeySession(req) {
     const token = readCookie(req, OAUTH_KEY_SESSION_COOKIE);
     return oauthKeySessions.isValid(token);
 }
-function setOAuthKeySessionCookie(req, res) {
-    const token = oauthKeySessions.create();
+/**
+ * Issue an OAuth key-session cookie. `ttlMs` covers BOTH the server-side
+ * session and the cookie's own maxAge — they must agree, or the browser keeps
+ * presenting a cookie the server has already forgotten (or vice versa).
+ * Omit it for the short key-entry gate; pass SIGN_IN_SESSION_TTL_MS for
+ * sign-in (#2005).
+ */
+export function setOAuthKeySessionCookie(req, res, ttlMs) {
+    const token = oauthKeySessions.create(Date.now(), ttlMs);
     const forwardedProto = (req.headers["x-forwarded-proto"] || req.headers["X-Forwarded-Proto"])
         ?.split(",")[0]
         ?.trim()
@@ -1333,8 +1382,16 @@ function setOAuthKeySessionCookie(req, res) {
         sameSite: "lax",
         secure,
         path: "/mcp/oauth",
-        maxAge: 15 * 60 * 1000,
+        maxAge: ttlMs != null && ttlMs > 0 ? ttlMs : 15 * 60 * 1000,
     });
+    return token;
+}
+/** Resolve the local-auth user_id a Google-verified session (if any) mapped to this request. */
+export function getGoogleVerifiedUserId(req) {
+    const token = readCookie(req, OAUTH_KEY_SESSION_COOKIE);
+    // getBoundUser enforces session validity itself, so an expired session can
+    // never resolve a user even if a binding is still in memory.
+    return oauthKeySessions.getBoundUser(token);
 }
 /**
  * Derive the canonical `@authority` the AAuth profile requires (AAuth §10.3.1).
@@ -1631,11 +1688,11 @@ app.all("/mcp", async (req, res) => {
             const hadSessionHeader = typeof sessionId === "string" && sessionId.length > 0;
             if (hadSessionHeader) {
                 logger.warn(`[MCP HTTP] Unknown or expired Mcp-Session-Id (first 8 chars): ${sessionId.slice(0, 8)}... often wrong replica behind a load balancer, API restart, or stale client state`);
-                return res.status(503).json({
+                return res.status(404).json({
                     jsonrpc: "2.0",
                     error: {
                         code: -32001,
-                        message: "Service Unavailable: MCP session is unknown on this API instance. If you run multiple replicas, enable sticky sessions for POST /mcp (or route /mcp to a single instance). Otherwise restart the MCP client so initialize runs again after a server restart.",
+                        message: "Not Found: MCP session is unknown or expired on this API instance. The client should re-initialize by sending a new InitializeRequest without a session ID. If you run multiple replicas, enable sticky sessions for POST /mcp (or route /mcp to a single instance).",
                     },
                     id: rpcId,
                 });
@@ -1886,9 +1943,32 @@ function sendStoreValidationError(res, issues) {
     }
     return sendValidationError(res, issues);
 }
+/**
+ * Lift a structured `hint` off the first Zod issue that carries one.
+ *
+ * Zod nests custom issue metadata under `params`, so a `ctx.addIssue({ params:
+ * { hint } })` lands at `details.issues[].params.hint`. Clients (and the
+ * legacy-payload replay harness, per docs/subsystems/errors.md § Tightening-change
+ * hint obligation) read the migration hint from the flat `details.hint` slot that
+ * every other standard-envelope error uses. Without this lift, a tightening can
+ * populate `hint` exactly as the guardrail requires and still be invisible to the
+ * gate meant to catch it.
+ */
+function firstIssueHint(issues) {
+    if (!Array.isArray(issues))
+        return undefined;
+    for (const issue of issues) {
+        const hint = issue?.params?.hint;
+        if (typeof hint === "string" && hint.length > 0)
+            return hint;
+    }
+    return undefined;
+}
 function sendValidationError(res, issues) {
+    const hint = firstIssueHint(issues);
     return res.status(400).json(buildErrorEnvelope("VALIDATION_INVALID_FORMAT", "Invalid request payload.", {
         issues,
+        ...(hint ? { hint } : {}),
     }));
 }
 // Public health endpoint (no auth)
@@ -2104,10 +2184,19 @@ app.get("/mcp/oauth/key-auth", async (req, res) => {
     const nextPathEscaped = escapeHtml(nextPath);
     const hasBearerFallback = Boolean((process.env.NEOTOMA_BEARER_TOKEN || "").trim());
     const defaultCredentialMode = hasBearerFallback ? "bearer" : "private_key";
+    const googleEnabled = isGoogleSigninEnabled();
+    const googleStartHref = `/mcp/oauth/google/start?next=${encodeURIComponent(nextPath)}`;
     return res.send(renderOauthPage({
         title: "Authenticate OAuth preflight",
         subtitle: "Choose one credential path below, then continue to complete OAuth authorization.",
         contentHtml: `
+      ${googleEnabled
+            ? `<div class="actions" style="margin-bottom: 1rem;">
+        <a class="btn-link" href="${escapeHtml(googleStartHref)}">Sign in with Google</a>
+      </div>
+      <div class="notice">Signs you in as your own Neotoma user if your Google account's verified email is on this server's approved list. Doesn't require a private key.</div>
+      <hr style="margin: 1.5rem 0; border: none; border-top: 1px solid hsl(var(--border));" />`
+            : ""}
       <form method="post" action="/mcp/oauth/key-auth" id="oauth-key-auth-form">
         <input type="hidden" name="next" value="${nextPathEscaped}" />
         <input type="hidden" name="credential_mode" id="credential_mode" value="${defaultCredentialMode}" />
@@ -2213,6 +2302,109 @@ app.post("/mcp/oauth/key-auth", express.urlencoded({ extended: true }), async (r
     setOAuthKeySessionCookie(req, res);
     return res.redirect(nextPath);
 });
+/**
+ * "Sign in with Google" entry point. Additive to, and independent of, the
+ * key/mnemonic/bearer credential form above — feature-flagged off unless
+ * NEOTOMA_GOOGLE_CLIENT_ID + NEOTOMA_APPROVED_EMAILS are both configured.
+ * AUTH-LAYER ONLY: this establishes who the person is (their own user_id
+ * via the existing per-email primitive); it does not touch data-sharing or
+ * read-scoping.
+ */
+app.get("/mcp/oauth/google/start", async (req, res) => {
+    if (!isGoogleSigninEnabled()) {
+        return res.status(404).send("Not found");
+    }
+    const nextPath = normalizeOauthNextPath(req.query.next || undefined);
+    const nonce = createGoogleSigninNonce(nextPath);
+    const redirectUri = `${req.protocol}://${req.get("host") || ""}/mcp/oauth/google/callback`;
+    try {
+        const authorizeUrl = buildGoogleAuthorizeUrl({ redirectUri, nonce });
+        return res.redirect(authorizeUrl);
+    }
+    catch (error) {
+        logError("GoogleOAuthStart", req, error);
+        return res.status(500).send(error?.message ?? "Failed to start Google sign-in");
+    }
+});
+app.get("/mcp/oauth/google/callback", async (req, res) => {
+    if (!isGoogleSigninEnabled()) {
+        return res.status(404).send("Not found");
+    }
+    const errorParam = req.query.error?.trim();
+    const code = req.query.code?.trim();
+    const nonceParam = req.query.state?.trim();
+    const failWith = (subtitle) => {
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        return res.status(401).send(renderOauthPage({
+            title: "Google sign-in failed",
+            subtitle,
+            contentHtml: `<div class="actions">
+          <a class="btn-link secondary" href="/mcp/oauth/key-auth">Back to authentication</a>
+        </div>`,
+        }));
+    };
+    if (errorParam) {
+        logger.warn("[Google OAuth] Callback returned an error", { error: errorParam });
+        return failWith("Google sign-in was cancelled or denied.");
+    }
+    if (!code || !nonceParam) {
+        return failWith("Missing code or state from Google callback.");
+    }
+    const nonceEntry = consumeGoogleSigninNonce(nonceParam);
+    if (!nonceEntry) {
+        return failWith("This sign-in link has expired or was already used. Please try again.");
+    }
+    // Same nextPath contract as the key/mnemonic/bearer path above: normalized
+    // back to a /mcp/oauth/* path (typically /mcp/oauth/authorize?...), never
+    // an external URL.
+    const nextPath = normalizeOauthNextPath(nonceEntry.next);
+    const redirectUri = `${req.protocol}://${req.get("host") || ""}/mcp/oauth/google/callback`;
+    try {
+        const { idToken } = await exchangeGoogleAuthorizationCode({ code, redirectUri });
+        const { email } = await verifyGoogleIdToken(idToken);
+        // Resolve the verified email to a stable user_id via the EXISTING per-email
+        // primitive (local_auth.ts) — the same primitive createLocalAuthUser /
+        // hashEmailToUserId already uses elsewhere. By default this person is
+        // admitted as their own isolated user_id, same as any other local-auth user.
+        const { createLocalAuthUser } = await import("./services/local_auth.js");
+        const { randomBytes } = await import("node:crypto");
+        // Password is unused for Google-authenticated users (they never log in
+        // with it) — generate an unguessable throwaway so createLocalAuthUser's
+        // shared code path is satisfied without weakening any other account.
+        const throwawayPassword = randomBytes(32).toString("hex");
+        const perEmailUser = createLocalAuthUser(email, throwawayPassword);
+        // Shared-graph opt-in: when NEOTOMA_SHARED_GRAPH_USER_ID is set, an
+        // approved teammate (the email already passed the allowlist inside
+        // verifyGoogleIdToken) is bound to the shared graph's user_id instead of
+        // their isolated per-email one — so the whole allowlisted team, plus the
+        // bearer/MCP identity that owns the data, share one populated graph. Unset
+        // → isolated per-email behavior (unchanged). See getSharedGraphUserId.
+        const resolvedUserId = getSharedGraphUserId() ?? perEmailUser.id;
+        // Mark this browser session as Google-verified and bound to the resolved
+        // user_id, exactly the same OAuth key-session cookie the private-key/
+        // mnemonic/bearer path sets. `/mcp/oauth/authorize` -> `/mcp/oauth/
+        // local-login` then runs completely unmodified, except local-login now
+        // resolves the user via this session instead of always ensureLocalDevUser().
+        // Sign-in gets the long session TTL, not the key-entry gate's 15 minutes,
+        // and the user binding lives in the same store so it expires with it (#2005).
+        const sessionToken = setOAuthKeySessionCookie(req, res, SIGN_IN_SESSION_TTL_MS);
+        oauthKeySessions.bindUser(sessionToken, resolvedUserId);
+        return res.redirect(nextPath);
+    }
+    catch (error) {
+        logError("GoogleOAuthCallback", req, error);
+        if (error instanceof GoogleIdTokenError) {
+            if (error.code === "EMAIL_NOT_APPROVED") {
+                return failWith("Your Google account is not on the approved list for this server.");
+            }
+            if (error.code === "EMAIL_NOT_VERIFIED") {
+                return failWith("Your Google account's email is not verified.");
+            }
+            return failWith("Google sign-in could not be verified.");
+        }
+        return failWith(error?.message ?? "Google sign-in failed.");
+    }
+});
 // RFC 8414 authorization endpoint (GET) for Cursor and other OAuth clients
 app.get("/mcp/oauth/authorize", async (req, res) => {
     try {
@@ -2263,7 +2455,10 @@ app.get("/mcp/oauth/authorize", async (req, res) => {
             // When reached via tunnel, only allow redirect_uri to localhost, app schemes, or OpenAI Custom GPT
             if (!isLocalRequest(req)) {
                 const { isRedirectUriAllowedForTunnel } = await import("./services/mcp_oauth.js");
-                if (!isRedirectUriAllowedForTunnel(redirect_uri)) {
+                // Public host as seen from outside the tunnel (x-forwarded-host set by the
+                // 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)) {
                     logger.warn("[MCP OAuth] Authorize rejected: redirect_uri not allowed for tunnel", {
                         redirect_uri: sanitizeRedirectUriForLog(redirect_uri),
                     });
@@ -2378,9 +2573,15 @@ app.get("/mcp/oauth/local-login", async (req, res) => {
         }));
     }
     try {
-        const devUser = ensureLocalDevUser();
+        // If this browser session was admitted via Google sign-in (see
+        // /mcp/oauth/google/callback), complete authorization as THAT verified
+        // user's own user_id instead of the shared dev user. Every other path
+        // (no Google session on this cookie — the default, and the only
+        // possibility when the Google feature flag is off) is unchanged.
+        const googleUserId = getGoogleVerifiedUserId(req);
+        const resolvedUserId = googleUserId ?? ensureLocalDevUser().id;
         const { completeLocalAuthorization } = await import("./services/mcp_oauth.js");
-        const { connectionId, redirectUri, clientState } = await completeLocalAuthorization(state, devUser.id);
+        const { connectionId, redirectUri, clientState } = await completeLocalAuthorization(state, resolvedUserId);
         const frontendBase = process.env.NEOTOMA_FRONTEND_URL || process.env.FRONTEND_URL || "http://localhost:5195";
         const frontendOauth = `${frontendBase}/oauth`;
         if (redirectUri) {
@@ -2734,6 +2935,23 @@ function guestWriteRateLimit(req, res, next) {
         return next();
     void guestWriteRateLimitMiddleware(req, res, next);
 }
+/**
+ * Issue *submission* is the one route a third party may reach with no identity
+ * at all: the guest access token is minted BY the submit, so requiring one to
+ * perform it is a chicken-and-egg that closes the inbox to first contact.
+ *
+ * Deliberately submit-only. `add_message` stays authenticated: by the time a
+ * reporter has a thread to append to, they hold the token returned by their
+ * submit, so anonymity buys nothing there — and letting an unidentified caller
+ * write into an existing thread is a strictly wider blast radius than letting
+ * them open a new one. The token is what proves "I opened this thread".
+ */
+export function routeAcceptsAnonymousIssueSubmit(req) {
+    return (req.method === "POST" && (req.path === "/issues/submit" || req.path === "/api/issues/submit"));
+}
+function buildAnonymousGuestPrincipal() {
+    return { kind: "guest", guestId: {}, agentIdentity: null, accessToken: undefined };
+}
 function buildGuestPrincipalFromRequest(req) {
     const agentIdentity = getCurrentAgentIdentity();
     const accessToken = guestAccessTokenFromRequest(req);
@@ -2757,8 +2975,21 @@ async function maybeStampGuestPrincipal(req) {
     if (!routeAcceptsGuestPrincipal(req))
         return false;
     const guestPrincipal = buildGuestPrincipalFromRequest(req);
-    if (!guestPrincipal)
-        return false;
+    if (!guestPrincipal) {
+        // No AAuth signature and no guest token: for issue submission this is the
+        // NORMAL first contact from a third party's agent, since the token is an
+        // OUTPUT of the submit rather than a precondition for it (#1953). Remains
+        // the operator's switch — NEOTOMA_ACCESS_POLICY_ISSUE=closed shuts it.
+        if (!routeAcceptsAnonymousIssueSubmit(req))
+            return false;
+        const { resolveAccessPolicy } = await import("./services/access_policy.js");
+        const mode = await resolveAccessPolicy("issue");
+        if (mode !== "submit_only" && mode !== "submitter_scoped" && mode !== "open") {
+            return false;
+        }
+        stampGuestPrincipal(req, buildAnonymousGuestPrincipal());
+        return true;
+    }
     const headerAuth = (req.headers.authorization || req.headers.Authorization || "");
     if (headerAuth.startsWith("Bearer ") && guestPrincipal.accessToken) {
         const { validateGuestAccessToken } = await import("./services/guest_access_token.js");
@@ -3321,6 +3552,12 @@ function handleApiError(req, res, error, defaultMessage, errorCode = "DB_QUERY_F
             .status(403)
             .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
     }
+    if (error instanceof CursorError) {
+        logWarn(logContext || "CursorRejection", req, error.toErrorEnvelope());
+        return res
+            .status(error.statusCode)
+            .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
+    }
     if (error instanceof IssueValidationError) {
         logWarn(logContext || "IssueValidationError", req, {
             code: error.code,
@@ -3371,8 +3608,8 @@ async function runEntitiesQuery(req, res, rawInput) {
         // scoping only via getAuthenticatedUserId; it is never read directly off
         // the request for access control.
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const { entity_type, entity_types, search, limit, offset, sort_by, sort_order, published, published_after, published_before, include_snapshots, include_merged, updated_since, created_since, identity_basis, snapshot_filters, exclude_bookkeeping, } = parsed.data;
-        const { entities, total, applied_search_strategies, search_mode } = await queryEntitiesWithCount({
+        const { entity_type, entity_types, search, limit, offset, cursor, sort_by, sort_order, published, published_after, published_before, include_snapshots, include_merged, updated_since, created_since, identity_basis, snapshot_filters, exclude_bookkeeping, } = parsed.data;
+        const { entities, total, applied_search_strategies, search_mode, next_cursor } = await queryEntitiesWithCount({
             userId,
             entityType: entity_type,
             entityTypes: entity_types,
@@ -3386,6 +3623,7 @@ async function runEntitiesQuery(req, res, rawInput) {
             search,
             limit,
             offset,
+            cursor,
             updatedSince: updated_since,
             createdSince: created_since,
             identityBasis: identity_basis,
@@ -3399,6 +3637,7 @@ async function runEntitiesQuery(req, res, rawInput) {
             offset,
             ...(applied_search_strategies ? { applied_search_strategies } : {}),
             search_mode,
+            ...(next_cursor ? { next_cursor } : {}),
         });
     }
     catch (error) {
@@ -3439,6 +3678,7 @@ function coerceEntitiesQueryParams(query) {
         "updated_since",
         "created_since",
         "identity_basis",
+        "cursor",
     ]) {
         const value = readString(key);
         if (value !== undefined)
@@ -5834,6 +6074,12 @@ export async function storeStructuredForApi(params) {
     // entity_id.
     const priorSnapshotByEntityId = new Map();
     const newSnapshotByEntityId = new Map();
+    // #1963: auto-link may retract a stale reference-field edge (e.g. a contact's
+    // organization moved companies). A retraction *failure* must not be silent —
+    // that would reproduce the very silent-drift bug this fix exists to close, one
+    // layer up. Accumulate per-observation retraction outcomes here so the
+    // schemaStoreWarnings pass below can surface them on the store response.
+    const autoLinkRetractionByObsIndex = new Map();
     for (const r of resolved) {
         let observation_id = null;
         let snapshotAfter = null;
@@ -5917,14 +6163,25 @@ export async function storeStructuredForApi(params) {
                 const schemaEntry = await schemaRegistry.loadActiveSchema(r.entity_type, userId);
                 if (schemaEntry?.schema_definition?.reference_fields?.length) {
                     const { autoLinkReferenceFields } = await import("./services/schema_reference_linking.js");
-                    await autoLinkReferenceFields({
+                    const autoLinkResult = await autoLinkReferenceFields({
                         entityId: r.entity_id,
                         entityType: r.entity_type,
                         fields: r.fields,
                         schema: schemaEntry.schema_definition,
                         userId,
                         sourceId: observationSourceId,
+                        commit,
                     });
+                    if (autoLinkResult.retracted > 0 || autoLinkResult.retraction_failures > 0) {
+                        autoLinkRetractionByObsIndex.set(r.observation_index, {
+                            entity_type: r.entity_type,
+                            entity_id: r.entity_id,
+                            retracted: autoLinkResult.retracted,
+                            retraction_failures: autoLinkResult.retraction_failures,
+                            failed_target_entity_ids: autoLinkResult.failed_retraction_target_entity_ids,
+                            failed_retractions: autoLinkResult.failed_retractions,
+                        });
+                    }
                 }
             }
             catch (linkErr) {
@@ -6254,6 +6511,46 @@ export async function storeStructuredForApi(params) {
             }
         }
     }
+    // #1963: surface auto-link edge retractions on the store response so a
+    // retraction — and especially a retraction *failure* — is never silent. A
+    // failure means a stale reference-field edge may still be live despite the
+    // store reporting success, so it is emitted as its own actionable warning.
+    for (const [obsIndex, rec] of autoLinkRetractionByObsIndex) {
+        if (rec.retraction_failures > 0) {
+            schemaStoreWarnings.push({
+                code: "AUTO_LINK_RETRACTION_FAILED",
+                message: `Auto-link retraction failed for ${rec.retraction_failures} stale ` +
+                    `reference-field edge(s) on ${rec.entity_type}/${rec.entity_id}. ` +
+                    `A superseded edge (e.g. a prior works_at) may still be live even though ` +
+                    `the store succeeded. To clean up, call delete_relationship for each ` +
+                    `stale edge in details.stale_edges, or re-run the store.`,
+                observation_index: obsIndex,
+                entity_type: rec.entity_type,
+                entity_id: rec.entity_id,
+                // Structured remediation: each entry is a ready-to-use delete_relationship
+                // argument set, so the caller needs no knowledge of its own schema.
+                details: {
+                    stale_edges: rec.failed_retractions.map((f) => ({
+                        source_entity_id: rec.entity_id,
+                        target_entity_id: f.target_entity_id,
+                        relationship_type: f.relationship_type,
+                        field_name: f.field,
+                    })),
+                },
+            });
+        }
+        else if (rec.retracted > 0) {
+            schemaStoreWarnings.push({
+                code: "AUTO_LINK_EDGE_RETRACTED",
+                message: `Retracted ${rec.retracted} stale auto-linked reference-field edge(s) on ` +
+                    `${rec.entity_type}/${rec.entity_id} because the field's resolved target ` +
+                    `changed (#1963).`,
+                observation_index: obsIndex,
+                entity_type: rec.entity_type,
+                entity_id: rec.entity_id,
+            });
+        }
+    }
     const unknownFieldNames = Array.from(unknownFieldNamesSet).sort();
     // Conditional hint (#1549): update_schema_incremental requires the schema to
     // declare canonical_name_fields, else it dead-ends on
@@ -7879,6 +8176,10 @@ const handleIssuesSubmitHttp = async (req, res) => {
                         author: parsed.data.author,
                         local_issue_id: parsed.data.local_issue_id,
                         submission_timestamp: parsed.data.submission_timestamp,
+                        reporter_git_sha: parsed.data.reporter_git_sha,
+                        reporter_git_ref: parsed.data.reporter_git_ref,
+                        reporter_channel: parsed.data.reporter_channel,
+                        reporter_app_version: parsed.data.reporter_app_version,
                     });
                     return {
                         issue_number: 0,
@@ -8261,7 +8562,7 @@ app.post("/update_schema_incremental", async (req, res) => {
     }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const { entity_type, fields_to_add, fields_to_remove, schema_version, user_specific = false, activate = true, migrate_existing = false, force = false, } = parsed.data;
+        const { entity_type, fields_to_add, fields_to_remove, canonical_name_fields, schema_version, user_specific = false, activate = true, migrate_existing = false, force = false, } = parsed.data;
         const { schemaRegistry } = await import("./services/schema_registry.js");
         let newSchema;
         try {
@@ -8269,6 +8570,11 @@ app.post("/update_schema_incremental", async (req, res) => {
                 entity_type,
                 fields_to_add: (fields_to_add || []),
                 fields_to_remove: fields_to_remove || [],
+                // #2018: thread the identity-rule change through the HTTP/offline path.
+                // Omitted here originally, so CLI/HTTP callers silently no-op'd the
+                // re-key (the MCP server handler had it, but this Express route — which
+                // the CLI offline transport uses — did not).
+                canonical_name_fields,
                 schema_version,
                 user_specific,
                 user_id: userId,
@@ -8295,6 +8601,10 @@ app.post("/update_schema_incremental", async (req, res) => {
             schema: newSchema,
             schema_version: newSchema.schema_version,
             fields_removed: fields_to_remove || [],
+            // Echo the resolved identity rule so CLI/HTTP callers can confirm the
+            // re-key without a second describe_entity_type round trip (#2020 ux).
+            canonical_name_fields: newSchema.schema_definition
+                .canonical_name_fields ?? null,
         });
     }
     catch (error) {