neotoma 0.10.1 → 0.11.1

package/README.md

@@ -100,8 +100,8 @@ The agent handles npm install, initialization, and MCP configuration. **Manual i
 ```bash
 npm install -g neotoma
 neotoma init
+neotoma setup --tool <cursor|claude-code|codex> --yes
 neotoma mcp config
-neotoma mcp check --mcp-transport a
 ```
 
 More options: [Docker](docs/developer/docker.md) | [CLI reference](docs/developer/cli_reference.md) | [Getting started](docs/developer/getting_started.md)
@@ -221,7 +221,7 @@ Neotoma exposes state via MCP. Local storage only in preview. Local built-in aut
 
 **Setup guides:** [Cursor](https://neotoma.io/neotoma-with-cursor) · [Claude Code](https://neotoma.io/neotoma-with-claude-code) · [Claude](https://neotoma.io/neotoma-with-claude) · [ChatGPT](https://neotoma.io/neotoma-with-chatgpt) · [Codex](https://neotoma.io/neotoma-with-codex) · [OpenCode](docs/integrations/hooks/opencode.md) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw) · [IronClaw](https://neotoma.io/neotoma-with-ironclaw)
 
-For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh`) or signed shim (`scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh`) instead of pointing installed MCP clients at a `tsx watch` stdio process. `neotoma mcp check` defaults to **`a`**: signed + AAuth with **neotoma-dev → dev** and **neotoma → prod** HTTP `/mcp` behind stdio; use `--mcp-transport c` for direct stdio, **`d`** if both MCP entries should target prod.
+For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh`) or signed shim (`scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh`) instead of pointing installed MCP clients at a `tsx watch` stdio process. `neotoma mcp config` defaults to **`b`** for low-friction local stdio setup; use **`a`** for signed + AAuth HTTP `/mcp` proxy entries when the Neotoma API is running, **`c`** for direct stdio, or **`d`** when both MCP entries should target prod.
 
 **Agent behavior contract:** Store first, retrieve before storing, extract entities from user input, create tasks for commitments, and attach bounded host context such as repository name/root scope when available. Full instructions: [MCP instructions](docs/developer/mcp/instructions.md) and [CLI agent instructions](docs/developer/cli_agent_instructions.md).
 

package/dist/actions.d.ts

@@ -2,17 +2,11 @@ import express from "express";
 import { type StoreInterpretationInput } from "./shared/action_schemas.js";
 export declare const app: import("express-serve-static-core").Express;
 /**
- * True when the request arrived over a loopback socket.
+ * True when the request is genuinely local to this process.
  *
- * SECURITY: derived from the TCP socket's remote address, NOT the `Host`
- * header. `req.headers.host` is attacker-controlled; using it to gate
- * authentication / auto-approval produces a trivial bypass when the server is
- * bound to a non-loopback interface. We check `req.socket.remoteAddress`
- * directly so spoofed `Host: localhost` headers do not promote a remote
- * caller into the local-dev trust zone.
- *
- * Express's `req.ip` is also unsafe here because `trust proxy` honours the
- * X-Forwarded-For header — any caller can claim to be loopback.
+ * SECURITY: a same-host reverse proxy (Caddy, nginx, Cloudflare tunnel, etc.)
+ * connects to Node over loopback even for public internet callers. In
+ * production, loopback alone is therefore not enough to grant local-dev auth.
  */
 export declare function isLocalRequest(req: express.Request): boolean;
 /**

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AA2G9B,OAAO,EAyBL,KAAK,wBAAwB,EAG9B,MAAM,4BAA4B,CAAC;AA+BpC,eAAO,MAAM,GAAG,6CAAY,CAAC;AAygB7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AAiyHD,KAAK,oBAAoB,GAAG;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAuDF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACvC,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cA+gBS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;mBA3JV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;;;;;;;GAsG3B;AA+iED,wBAAsB,eAAe;;;eA2FpC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AA4G9B,OAAO,EAyBL,KAAK,wBAAwB,EAE9B,MAAM,4BAA4B,CAAC;AA+BpC,eAAO,MAAM,GAAG,6CAAY,CAAC;AAiiB7B;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAa5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AAiyHD,KAAK,oBAAoB,GAAG;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAuDF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACvC,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cA+gBS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;mBA3JV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;;;;;;;GAsG3B;AAmhED,wBAAsB,eAAe;;;eA8FpC"}

package/dist/actions.js

@@ -10,6 +10,7 @@ import { db } from "./db.js";
 import { config } from "./config.js";
 import fs from "fs";
 import path from "path";
+import { writeLocalHttpPortFile } from "./utils/local_http_port_file.js";
 import yaml from "js-yaml";
 import { ensurePublicKeyRegistered, getPublicKey, getUserIdFromBearerToken, isBearerTokenValid, } from "./services/public_key_registry.js";
 import { verifyRequest, parseAuthHeader } from "./crypto/auth.js";
@@ -43,7 +44,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 { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateInterpretationRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, StoreUnstructuredRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
+import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateInterpretationRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
 import { getMimeTypeFromExtension } from "./services/file_text_extraction.js";
 import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers.js";
 import { retrieveEntityByIdentifierWithFallback } from "./shared/action_handlers/entity_identifier_handler.js";
@@ -521,34 +522,50 @@ app.get("/mcp-interaction-instructions", (_req, res) => {
 const mcpTransports = new Map();
 // Store server instances by session ID to preserve authentication state
 const mcpServerInstances = new Map();
-/**
- * True when the request arrived over a loopback socket.
- *
- * SECURITY: derived from the TCP socket's remote address, NOT the `Host`
- * header. `req.headers.host` is attacker-controlled; using it to gate
- * authentication / auto-approval produces a trivial bypass when the server is
- * bound to a non-loopback interface. We check `req.socket.remoteAddress`
- * directly so spoofed `Host: localhost` headers do not promote a remote
- * caller into the local-dev trust zone.
- *
- * Express's `req.ip` is also unsafe here because `trust proxy` honours the
- * X-Forwarded-For header — any caller can claim to be loopback.
- */
-export function isLocalRequest(req) {
-    const remote = (req.socket?.remoteAddress || "").toLowerCase();
+function isLoopbackAddress(value) {
+    const remote = (value || "").trim().toLowerCase();
     if (!remote)
         return false;
-    // Unix-domain socket requests have no remote address; treat as non-local.
     if (remote === "127.0.0.1" || remote === "::1")
         return true;
-    // IPv4 loopback range (127.0.0.0/8)
     if (remote.startsWith("127."))
         return true;
-    // IPv4-mapped IPv6 loopback (e.g. ::ffff:127.0.0.1)
     if (remote.startsWith("::ffff:127."))
         return true;
     return false;
 }
+function forwardedForValues(req) {
+    const headers = req.headers || {};
+    const raw = headers["x-forwarded-for"] || headers["X-Forwarded-For"];
+    const values = Array.isArray(raw) ? raw : raw ? [raw] : [];
+    return values
+        .flatMap((value) => String(value).split(","))
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function isProductionEnvironment(env = process.env) {
+    const value = (env.NEOTOMA_ENV || "development").trim().toLowerCase();
+    return value === "production" || value === "prod";
+}
+/**
+ * True when the request is genuinely local to this process.
+ *
+ * SECURITY: a same-host reverse proxy (Caddy, nginx, Cloudflare tunnel, etc.)
+ * connects to Node over loopback even for public internet callers. In
+ * production, loopback alone is therefore not enough to grant local-dev auth.
+ */
+export function isLocalRequest(req) {
+    if (!isLoopbackAddress(req.socket?.remoteAddress))
+        return false;
+    const forwardedFor = forwardedForValues(req);
+    if (forwardedFor.length > 0) {
+        return forwardedFor.every(isLoopbackAddress);
+    }
+    if (isProductionEnvironment() && process.env.NEOTOMA_TRUST_PROD_LOOPBACK === "1") {
+        return true;
+    }
+    return !isProductionEnvironment();
+}
 const OAUTH_KEY_SESSION_COOKIE = "neotoma_oauth_key_session";
 const oauthKeySessions = new OAuthKeySessionStore();
 function readCookie(req, name) {
@@ -4053,7 +4070,7 @@ export async function storeStructuredForApi(params) {
         const entityTypes = entities
             .map((entity) => entity?.entity_type)
             .filter((t) => typeof t === "string" && t.length > 0);
-        enforceAgentCapability("store_structured", entityTypes, capabilityCtx);
+        enforceAgentCapability("store", entityTypes, capabilityCtx);
         const relationshipOp = Array.isArray(relationships) && relationships.length > 0;
         if (relationshipOp) {
             enforceAgentCapability("create_relationship", entityTypes, capabilityCtx);
@@ -4069,7 +4086,7 @@ export async function storeStructuredForApi(params) {
             .filter((t) => typeof t === "string" && t.length > 0);
         assertCanWriteProtectedBatch({
             entity_types: entityTypes,
-            op: "store_structured",
+            op: "store",
             identity: getCurrentAgentIdentity(),
             admission: getCurrentAAuthAdmission(),
         });
@@ -4663,33 +4680,6 @@ if (isSandboxMode()) {
     app.post("/sandbox/aauth-only/store", writeRateLimit, aauthRequired, handleStorePost);
     logger.info("[Sandbox] AAuth-required write route enabled at POST /sandbox/aauth-only/store");
 }
-// POST /api/store/unstructured - Store raw file (base64), optional AI interpretation
-app.post("/store/unstructured", async (req, res) => {
-    const parsed = StoreUnstructuredRequestSchema.safeParse(req.body);
-    if (!parsed.success) {
-        logWarn("ValidationError:store_unstructured", req, { issues: parsed.error.issues });
-        return sendValidationError(res, parsed.error.issues);
-    }
-    try {
-        const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const response = await storeUnstructuredForApi({
-            userId,
-            fileContent: parsed.data.file_content,
-            mimeType: parsed.data.mime_type,
-            idempotencyKey: parsed.data.idempotency_key,
-            originalFilename: parsed.data.original_filename,
-        });
-        return res.status(200).json(response);
-    }
-    catch (error) {
-        if (error instanceof Error && error.message.includes("Not authenticated")) {
-            return sendError(res, 401, "AUTH_REQUIRED", error.message);
-        }
-        logError("APIError:store_unstructured", req, error);
-        const message = error instanceof Error ? error.message : "Failed to store unstructured file";
-        return sendError(res, 500, "DB_QUERY_FAILED", message);
-    }
-});
 // POST /api/observations/query - Query observations
 app.post("/observations/query", async (req, res) => {
     const parsed = ObservationsQueryRequestSchema.safeParse(req.body);
@@ -6152,6 +6142,9 @@ export async function startHTTPServer() {
             }
             // eslint-disable-next-line no-console
             console.log(`HTTP Actions listening on :${boundPort}`);
+            if (process.env.NODE_ENV !== "test") {
+                writeLocalHttpPortFile(config.projectRoot, boundPort);
+            }
             // Start background OAuth state cleanup job
             import("./services/mcp_oauth.js").then((oauth) => {
                 oauth.startStateCleanupJob();