neotoma 0.18.2 → 0.18.4

package/dist/actions.d.ts

@@ -97,6 +97,16 @@ type GuestPrincipal = {
 type RoutePrincipal = UserPrincipal | GuestPrincipal;
 /** 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;
+/**
+ * Exported for unit tests: the two issue-write routes that extend local-loopback
+ * trust to unauthenticated requests. A local request to `/issues/submit` or
+ * `/issues/add_message` with no `Authorization: Bearer` header falls through to
+ * the local dev user — the same offline-developer trust the entity-read routes
+ * already grant (see `resolveGuestUserId`). This is the ONLY place that trust is
+ * widened; every other route still requires a Bearer token, and remote requests
+ * (non-loopback / untrusted XFF) get AUTH_REQUIRED on these routes too.
+ */
+export declare function routeAllowsLocalIssueWriteFallback(req: Pick<express.Request, "method" | "path">): boolean;
 /** Exported for unit tests: guest-capable routes that mutate state and should consume a guest write-rate budget. */
 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. */

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

@@ -2611,6 +2611,23 @@ export function routeAcceptsGuestPrincipal(req) {
     }
     return false;
 }
+/**
+ * Exported for unit tests: the two issue-write routes that extend local-loopback
+ * trust to unauthenticated requests. A local request to `/issues/submit` or
+ * `/issues/add_message` with no `Authorization: Bearer` header falls through to
+ * the local dev user — the same offline-developer trust the entity-read routes
+ * already grant (see `resolveGuestUserId`). This is the ONLY place that trust is
+ * widened; every other route still requires a Bearer token, and remote requests
+ * (non-loopback / untrusted XFF) get AUTH_REQUIRED on these routes too.
+ */
+export function routeAllowsLocalIssueWriteFallback(req) {
+    const path = req.path;
+    return (req.method === "POST" &&
+        (path === "/issues/submit" ||
+            path === "/api/issues/submit" ||
+            path === "/issues/add_message" ||
+            path === "/api/issues/add_message"));
+}
 /** Exported for unit tests: guest-capable routes that mutate state and should consume a guest write-rate budget. */
 export function routeConsumesGuestWriteBudget(req) {
     const path = req.path;
@@ -2704,6 +2721,24 @@ async function resolveRoutePrincipal(req, accept) {
         }
     }
     if (accept.includes("user")) {
+        // Local-loopback trust for the two issue-write routes: a local request with
+        // no Bearer token resolves to the local dev user instead of failing
+        // AUTH_REQUIRED. This mirrors the existing local fallback in
+        // `resolveGuestUserId` and keeps `neotoma issues create` working offline
+        // (gh-CLI auth alone does not configure a Neotoma Bearer token). Scoped as
+        // narrowly as possible: ONLY these routes, ONLY local requests, ONLY when
+        // no Bearer header is present — remote/Bearer requests fall through to the
+        // normal `getAuthenticatedUserId` gate below.
+        const headerAuth = (req.headers.authorization || req.headers.Authorization || "");
+        if (routeAllowsLocalIssueWriteFallback(req) &&
+            isLocalRequest(req) &&
+            !headerAuth.startsWith("Bearer ")) {
+            const userId = _localSandboxActive ? ensureLocalSandboxUser().id : ensureLocalDevUser().id;
+            // Stamp the principal so a later `getAuthenticatedUserId` in the handler
+            // resolves the same local user without re-tripping the missing-Bearer gate.
+            stampUserPrincipal(req, userId);
+            return { kind: "user", userId };
+        }
         const userId = await getAuthenticatedUserId(req, (req.body?.user_id ??
             req.query.user_id));
         return { kind: "user", userId };
@@ -5704,6 +5739,12 @@ export async function storeStructuredForApi(params) {
         }
     }
     const createdEntities = [];
+    // Issue #1839: capture each entity's prior and post-reduction snapshot so the
+    // store_warnings loop below can detect a NULL_CLEARED_FIELD event (an incoming
+    // null clearing a prior non-null value under highest_priority). Keyed by
+    // entity_id.
+    const priorSnapshotByEntityId = new Map();
+    const newSnapshotByEntityId = new Map();
     for (const r of resolved) {
         let observation_id = null;
         let snapshotAfter = null;
@@ -5715,6 +5756,7 @@ export async function storeStructuredForApi(params) {
                 .eq("user_id", userId)
                 .maybeSingle();
             const priorSnapshot = priorSnapRow?.snapshot ?? {};
+            priorSnapshotByEntityId.set(r.entity_id, priorSnapshot);
             const obsData = await createObservation({
                 entity_id: r.entity_id,
                 entity_type: r.entity_type,
@@ -5737,6 +5779,8 @@ export async function storeStructuredForApi(params) {
                 const snap = await recomputeSnapshot(r.entity_id, userId);
                 snapshotAfter =
                     snap?.snapshot ?? null;
+                if (snapshotAfter)
+                    newSnapshotByEntityId.set(r.entity_id, snapshotAfter);
             }
             catch (snapshotErr) {
                 logger.warn(`Snapshot recompute failed for ${r.entity_id}: ${snapshotErr}`);
@@ -6076,6 +6120,48 @@ export async function storeStructuredForApi(params) {
                 });
                 if (spWarn)
                     schemaStoreWarnings.push(spWarn);
+                // Issue #1838: SOURCE_PRIORITY_ESCALATION — mirror-image advisory. A
+                // write at the DEFAULT source_priority (100) into a `highest_priority`
+                // field silently OUTRANKS any prior observation written with an
+                // explicit lower priority. Non-blocking; reuses the same import.
+                const { buildSourcePriorityEscalationWarning } = await import("./services/source_priority_warning.js");
+                const spEsc = buildSourcePriorityEscalationWarning({
+                    sourcePriority,
+                    writtenFields: r.fields,
+                    mergePolicies: schemaEntry?.reducer_config?.merge_policies,
+                    observationIndex: r.observation_index,
+                    entityType: r.entity_type,
+                    entityId: r.entity_id,
+                });
+                if (spEsc)
+                    schemaStoreWarnings.push(spEsc);
+            }
+            // Issue #1839: NULL_CLEARED_FIELD — non-blocking advisory warning when an
+            // incoming null clears a prior non-null value under a `highest_priority`
+            // field. The clear is by design (null is an explicit tombstone), but it
+            // is silent today; this surfaces the data-loss vector. Warn-only: no
+            // change to snapshot computation or clearing semantics.
+            {
+                const mergePolicies = schemaEntry?.reducer_config?.merge_policies;
+                if (mergePolicies) {
+                    const priorSnapshot = priorSnapshotByEntityId.get(r.entity_id) ?? {};
+                    const newSnapshot = newSnapshotByEntityId.get(r.entity_id) ?? {};
+                    const { buildNullClearedFieldWarning } = await import("./services/null_cleared_field_warning.js");
+                    for (const field of Object.keys(r.fields)) {
+                        const nullWarn = buildNullClearedFieldWarning({
+                            field,
+                            strategy: mergePolicies[field]?.strategy,
+                            prior_value: priorSnapshot[field],
+                            incoming_value: r.fields[field],
+                            new_value: newSnapshot[field],
+                            observation_index: r.observation_index,
+                            entity_type: r.entity_type,
+                            entity_id: r.entity_id,
+                        });
+                        if (nullWarn)
+                            schemaStoreWarnings.push(nullWarn);
+                    }
+                }
             }
         }
     }
@@ -6191,10 +6277,35 @@ export async function storeStructuredForApi(params) {
     };
 }
 async function storeUnstructuredForApi(params) {
-    const { fileContent, fileBuffer, mimeType, idempotencyKey, originalFilename, sourceType, userId, } = params;
+    const { fileContent, fileBuffer, filePath, mimeType, idempotencyKey, originalFilename, sourceType, userId, storageMode = "inline", } = params;
     const resolvedFileBuffer = fileBuffer ?? (fileContent !== undefined ? Buffer.from(fileContent, "base64") : undefined);
-    if (!resolvedFileBuffer) {
-        throw new Error("fileContent or fileBuffer is required for unstructured storage");
+    if (!resolvedFileBuffer && storageMode !== "reference") {
+        throw new Error("fileContent or fileBuffer is required for inline storage");
+    }
+    if (storageMode === "reference") {
+        if (!filePath) {
+            throw new Error("filePath is required for reference storage mode");
+        }
+        const absolutePath = path.isAbsolute(filePath)
+            ? filePath
+            : path.resolve(process.cwd(), filePath);
+        const { storeRawReference } = await import("./services/raw_storage.js");
+        const referenceResult = await storeRawReference({
+            userId,
+            absolutePath,
+            mimeType,
+            originalFilename: originalFilename?.trim() || undefined,
+            idempotencyKey,
+            provenance: { upload_method: "api_store_reference", client: "api" },
+        });
+        return {
+            source_id: referenceResult.sourceId,
+            content_hash: referenceResult.contentHash,
+            storage_mode: "reference",
+            reference_path: referenceResult.path,
+            file_size: referenceResult.sizeBytes,
+            mime_type: referenceResult.mimeType,
+        };
     }
     const resolvedIdempotencyKey = idempotencyKey ??
         (await import("node:crypto")).createHash("sha256").update(resolvedFileBuffer).digest("hex");
@@ -6247,14 +6358,26 @@ async function handleStorePost(req, res) {
                 const resolvedPath = path.isAbsolute(parsed.data.file_path)
                     ? parsed.data.file_path
                     : path.resolve(process.cwd(), parsed.data.file_path);
-                resolvedFileBuffer = fs.readFileSync(resolvedPath);
-                if (!mimeType) {
-                    const ext = path.extname(resolvedPath).toLowerCase();
-                    mimeType = getMimeTypeFromExtension(ext) || "application/octet-stream";
+                if (parsed.data.source_storage === "reference") {
+                    // For reference mode, don't read the file buffer, just use the path
+                    if (!mimeType) {
+                        const ext = path.extname(resolvedPath).toLowerCase();
+                        mimeType = getMimeTypeFromExtension(ext) || "application/octet-stream";
+                    }
+                    originalFilename = originalFilename || path.basename(resolvedPath);
+                }
+                else {
+                    // For inline mode, read the file buffer
+                    resolvedFileBuffer = fs.readFileSync(resolvedPath);
+                    if (!mimeType) {
+                        const ext = path.extname(resolvedPath).toLowerCase();
+                        mimeType = getMimeTypeFromExtension(ext) || "application/octet-stream";
+                    }
+                    originalFilename = originalFilename || path.basename(resolvedPath);
                 }
-                originalFilename = originalFilename || path.basename(resolvedPath);
             }
-            if ((!fileContent && !resolvedFileBuffer) || !mimeType) {
+            if ((!fileContent && !resolvedFileBuffer && parsed.data.source_storage !== "reference") ||
+                !mimeType) {
                 sendError(res, 400, "VALIDATION_ERROR", "Unstructured store requires file_content+mime_type or file_path");
                 return null;
             }
@@ -6262,11 +6385,13 @@ async function handleStorePost(req, res) {
                 userId,
                 fileContent,
                 fileBuffer: resolvedFileBuffer,
+                filePath: parsed.data.file_path,
                 mimeType,
                 idempotencyKey: parsed.data.file_idempotency_key ??
                     (!hasEntities ? parsed.data.idempotency_key : undefined),
                 originalFilename,
                 sourceType: parsed.data.source_type,
+                storageMode: parsed.data.source_storage,
             });
         };
         if (hasUnstructured && parsed.data.interpretation?.source_ref === "unstructured") {