@aixle/insights 0.2.4-staging → 0.2.5-staging

package/README.md

@@ -162,6 +162,12 @@ Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per
 }
 ```
 
+The file is optional — an absent `config.json` is the normal case and is silent. A file that is
+present but unusable is ignored entirely (every override falls back to its default) and a
+`config_parse_failed` line is written to `mcp.log`. That covers malformed JSON and valid JSON that
+isn't an object, including a **top-level array** — a common mistake when writing per-model rates.
+Nothing is printed to the terminal, so check the log if an override appears to have no effect.
+
 ## Security
 
 `@aixle/insights` enforces HTTPS for any remote host. Plaintext `http://` is allowed only for loopback (`localhost`, `127.0.0.0/8`, `[::1]`) so that local-dev flows against `make up` continue to work without friction.
@@ -188,6 +194,22 @@ The runtime gate exists because `init`'s two gates only run once, at login time.
 
 The Keycloak issuer URL (`--keycloak-url` / `KEYCLOAK_ISSUER`) is **not** TLS-gated by this package. Same threat model, different ticket — tracked separately. For now, use HTTPS for any remote Keycloak issuer; the OIDC device-flow library will fail the request if the cert is invalid, but it will not refuse to attempt plaintext.
 
+### Local store integrity
+
+Transport security covers data in flight. The other half of the threat model is what the package
+reads back off the local machine: credentials (keychain or file), `config.json`, and state files are
+all attacker-writable if the account is compromised, so none of them is trusted on read.
+
+Each is validated every time it is loaded. A payload that fails to parse, or that parses but does
+not match the expected shape, is **rejected** and the caller falls back to its documented default —
+no credentials, no config overrides, fresh state. Every rejection is recorded in `mcp.log`, so a
+corrupted or tampered store is distinguishable from one that was never created; before this, both
+were silent and looked identical to a fresh install. See
+[Diagnostics](#diagnostics) for the event names.
+
+Log fields carry only the file path (or the keychain service name) and a short machine-readable
+reason. File contents, keychain payloads, and tokens are never logged.
+
 ## Cursor hook forwarder (opt-in)
 
 `aixle-insights init --hooks --tool-name cursor` installs a Node script as a Cursor hook (`~/.cursor/hooks.json`). The script appends redacted hook payloads to `~/.aixle-insights/hooks-queue.ndjson`; the background sync drains the queue on its next cycle and POSTs the events with accurate per-turn model attribution. Requires a Cursor restart after install. To remove, run `aixle-insights uninstall-hooks` and restart Cursor again.
@@ -225,6 +247,35 @@ aixle-insights verify-hooks  # JSON: hooks installed + queue depth
 
 `mcp.log` (rotates at 5 MiB to `mcp.log.1`) under the app home directory captures operational events. Inside Claude Code, the **`aixle_insights_status`** MCP tool returns the same diagnostic structure as `aixle-insights health`.
 
+### Local-store integrity events
+
+These four are the only signal that a local store was present but unusable — `health` and
+`aixle_insights_status` do **not** report them, so `mcp.log` is the sole surface:
+
+| Event | Fires when |
+|---|---|
+| `credentials_parse_failed` | `credentials.json` exists but was rejected |
+| `credentials_keytar_parse_failed` | the OS keychain entry exists but was rejected |
+| `config_parse_failed` | `config.json` exists but was rejected |
+| `state_parse_failed` | a state file exists but was rejected |
+
+Each carries a `reason` distinguishing the two failure modes:
+
+- `invalid_json` — the payload did not parse at all.
+- `invalid_shape` — it parsed, but validation rejected it: credentials with no usable token, a
+  `config.json` that is a JSON array, a state file missing `version` / `sessions`, and so on.
+
+Three properties are worth relying on:
+
+- An **absent** file never warns. That is the everyday case (most users never create a
+  `config.json`, and every machine starts with no state file), so a warning always means something
+  is actually there and wrong.
+- A **missing or disabled OS keychain** never warns either — falling back to the file is expected
+  on headless Linux, CI, and containers, not an error.
+- All four are written to the log **only**, never mirrored to stderr, because stray output on the
+  stdio transport corrupts the MCP protocol. Emitting a warning never changes the fallback the
+  caller returns.
+
 ## Troubleshooting
 
 | Symptom | Most likely cause | Fix |
@@ -236,6 +287,9 @@ aixle-insights verify-hooks  # JSON: hooks installed + queue depth
 | `health` shows `authenticated: true` but `last_result` is `sent: 0, failed: N` cycle after cycle | Same as the 401 row above. `authenticated` only proves the OIDC token was acquired, not that the ingest token still validates server-side. | Re-init as above. |
 | `last_result` reports `sent: N` but the Events UI shows nothing | The Temporal worker is not running. The ingest endpoint returns HTTP 202 (queued) regardless of worker state. | `make worker` (or check `docker ps` for `db90-worker`). See [LOCAL-DEV.md](./LOCAL-DEV.md) §1. |
 | `sync_lock_skip {reason: "advisory_lock_held"}` in the log | Another sync cycle is still holding `~/.aixle-insights/state.lock`. | Wait for it to finish; only delete the lock file (`rm -f ~/.aixle-insights/state.lock`) after confirming no `aixle-insights run` process is alive (`pgrep -fa aixle-insights`). |
+| `health` reports `authenticated: false` right after a successful `init`, and `credentials_parse_failed` or `credentials_keytar_parse_failed` is in the log | The credential store exists but was rejected, so it is treated as absent. The `reason` field says whether it failed to parse (`invalid_json`) or parsed into the wrong shape (`invalid_shape`). | Re-run `init`. If you hand-edited `credentials.json` for local testing, remember the keychain is read **first** — see [State + credentials](#state--credentials). |
+| A `config.json` override has no effect, and `config_parse_failed` is in the log | The file is malformed, or is valid JSON that is not an object — a top-level array is the usual mistake. | Fix it to match the shape under [Environment](#environment); until it parses, every override is ignored. |
+| Sync re-sends history that was already delivered, and `state_parse_failed` is in the log | A state file was present but rejected, so sync fell back to fresh state and lost its dedup checkpoints. | This is recovery, not a loop — the next successful cycle writes valid state. Ingest upserts by session, so duplicates are absorbed. Worth investigating what wrote the bad file. |
 | `aixle-insights --help` doesn't list `--insecure` | You're running an older published version of the package, not the local source. | `which aixle-insights` shows the path. To run local source: `cd packages/tools/aixle-insights && npm run build && npm link`. To return to the published version: `npm unlink -g @aixle/insights && npm install -g @aixle/insights@latest`. |
 | Not sure whether `aixle-insights` is a `npm link` or a real install | Real installs are regular files; `npm link` is a symlink chain into the repo. | `readlink "$(which aixle-insights)"` shows the link target if any. A linked install will trace back to a path under your monorepo checkout. |
 

package/dist/auth/credentials.js

@@ -4,6 +4,7 @@ import { userInfo } from "node:os";
 import { join } from "node:path";
 import { getAppDir } from "../state.js";
 import { mcpLog } from "../log.js";
+import { describeReadFailure } from "../lib/parse-error.js";
 export const KEYTAR_SERVICE = "aixle-insights";
 const KEYTAR_ACCOUNT = "aixle-insights-ingest-credential";
 function credentialsPath(appDir) {
@@ -62,15 +63,23 @@ export function loadCredentialsFromFileOnly(appDir = getAppDir()) {
     const filePath = credentialsPath(appDir);
     if (!existsSync(filePath))
         return null;
+    let raw;
     try {
-        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
-        return normalizeLoadedCredentials(raw);
+        raw = JSON.parse(readFileSync(filePath, "utf-8"));
     }
     catch (err) {
-        // File exists (checked above) but failed to parse/normalize — distinguishes tampering from "never created".
-        mcpLog.warn("credentials_parse_failed", { path: filePath, error: err instanceof Error ? err.message : String(err) }, false);
+        // File exists (checked above) but is not readable/valid JSON — distinguishes tampering from "never created".
+        mcpLog.warn("credentials_parse_failed", { path: filePath, ...describeReadFailure(err) }, false);
         return null;
     }
+    const normalized = normalizeLoadedCredentials(raw);
+    if (normalized === null) {
+        // Valid JSON, but not a credential shape we accept. `normalizeLoadedCredentials` signals
+        // rejection by returning null and never throws, so this cannot surface in the catch
+        // above — without this branch a plausible-looking replacement file stays silent. (DB90DV-699)
+        mcpLog.warn("credentials_parse_failed", { path: filePath, reason: "invalid_shape" }, false);
+    }
+    return normalized;
 }
 async function tryKeytarGet() {
     if (keytarDisabled())
@@ -86,15 +95,22 @@ async function tryKeytarGet() {
     }
     if (!raw)
         return null;
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        return normalizeLoadedCredentials(parsed);
+        parsed = JSON.parse(raw);
     }
     catch (err) {
-        // Keychain entry exists (checked above) but failed to parse/normalize — distinguishes tampering from "no entry".
-        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, error: err instanceof Error ? err.message : String(err) }, false);
+        // Keychain entry exists (checked above) but is not valid JSON — distinguishes tampering from "no entry".
+        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, ...describeReadFailure(err) }, false);
         return null;
     }
+    const normalized = normalizeLoadedCredentials(parsed);
+    if (normalized === null) {
+        // Same shape-rejection hole as the file path above. Fields stay service-only — never the
+        // keychain payload. (DB90DV-699)
+        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, reason: "invalid_shape" }, false);
+    }
+    return normalized;
 }
 async function tryKeytarSet(payload) {
     if (keytarDisabled())

package/dist/lib/config.d.ts

@@ -12,8 +12,8 @@ export interface BaseConfig {
  * Load a connector's `config.json` from disk. Returns `{}` on missing or
  * malformed files — callers fall back to env vars / CLI flags / defaults.
  *
- * @param configDir Directory containing `config.json`, typically the
- *                  connector's `APP_DIR` (`~/.db90-claude` / `~/.db90-cursor`).
+ * @param configDir Directory containing `config.json`, typically the app home directory
+ *                  (`~/.aixle-insights`, or `AIXLE_INSIGHTS_HOME` when set).
  * @param parsePricing Optional callback that extracts a connector-specific
  *                     pricing shape from the raw parsed JSON. Returns
  *                     `undefined` when the pricing block is missing or invalid.

package/dist/lib/config.js

@@ -1,12 +1,13 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { mcpLog } from "../log.js";
+import { describeReadFailure } from "./parse-error.js";
 /**
  * Load a connector's `config.json` from disk. Returns `{}` on missing or
  * malformed files — callers fall back to env vars / CLI flags / defaults.
  *
- * @param configDir Directory containing `config.json`, typically the
- *                  connector's `APP_DIR` (`~/.db90-claude` / `~/.db90-cursor`).
+ * @param configDir Directory containing `config.json`, typically the app home directory
+ *                  (`~/.aixle-insights`, or `AIXLE_INSIGHTS_HOME` when set).
  * @param parsePricing Optional callback that extracts a connector-specific
  *                     pricing shape from the raw parsed JSON. Returns
  *                     `undefined` when the pricing block is missing or invalid.
@@ -16,29 +17,36 @@ import { mcpLog } from "../log.js";
  */
 export function loadBaseConfig(configDir, parsePricing) {
     const configPath = join(configDir, "config.json");
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
-        if (typeof parsed === "object" && parsed !== null) {
-            const obj = parsed;
-            const result = {
-                token: typeof obj.token === "string" ? obj.token : undefined,
-                host: typeof obj.host === "string" ? obj.host : undefined,
-                project_id: typeof obj.project_id === "string" ? obj.project_id : undefined,
-            };
-            if (parsePricing) {
-                const pricing = parsePricing(obj);
-                if (pricing !== undefined)
-                    result.pricing = pricing;
-            }
-            return result;
-        }
+        parsed = JSON.parse(readFileSync(configPath, "utf-8"));
     }
     catch (err) {
         const code = err?.code;
         if (code !== "ENOENT") {
-            // Config file exists but failed to parse — distinguishes tampering from "never created".
-            mcpLog.warn("config_parse_failed", { path: configPath, error: err instanceof Error ? err.message : String(err) }, false);
+            // Config file exists but is not valid JSON — distinguishes tampering from "never created".
+            // ENOENT stays silent: this file is optional and most users never create it.
+            mcpLog.warn("config_parse_failed", { path: configPath, ...describeReadFailure(err) }, false);
         }
+        return {};
+    }
+    // Valid JSON, but not a config object. Arrays are rejected explicitly because
+    // `typeof [] === "object"` would otherwise let them reach the happy path and be handed
+    // to `parsePricing`. Previously every non-object fell through silently. (DB90DV-699)
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        mcpLog.warn("config_parse_failed", { path: configPath, reason: "invalid_shape" }, false);
+        return {};
+    }
+    const obj = parsed;
+    const result = {
+        token: typeof obj.token === "string" ? obj.token : undefined,
+        host: typeof obj.host === "string" ? obj.host : undefined,
+        project_id: typeof obj.project_id === "string" ? obj.project_id : undefined,
+    };
+    if (parsePricing) {
+        const pricing = parsePricing(obj);
+        if (pricing !== undefined)
+            result.pricing = pricing;
     }
-    return {};
+    return result;
 }

package/dist/lib/parse-error.d.ts

@@ -0,0 +1,21 @@
+export type ReadFailureReason = "invalid_json" | "unreadable";
+/**
+ * Classifies a caught error from `JSON.parse(readFileSync(...))` (or a parsed keychain
+ * payload) into a log-safe reason + error string.
+ *
+ * V8's `JSON.parse` throws a `SyntaxError` whose `.message` can embed a prefix (or, for a
+ * short enough input, the entirety) of the unparsed content — e.g.
+ * `JSON.parse("example_local_fixture_1234567890")` produces
+ * `Unexpected token 'e', "example_lo"... is not valid JSON`. Logging that message would
+ * leak exactly the secret content the parse-failure events exist to describe without
+ * exposing (see `credentials_parse_failed` / `credentials_keytar_parse_failed` /
+ * `config_parse_failed` / `state_parse_failed`). So for a `SyntaxError` this reports only
+ * the error name, never `.message`.
+ *
+ * Any other error (fs I/O — `EACCES`, `EISDIR`, etc.) is reported as `unreadable` using its
+ * errno `code`, which never contains file content and is more actionable than a bare name.
+ */
+export declare function describeReadFailure(err: unknown): {
+    reason: ReadFailureReason;
+    error: string;
+};

package/dist/lib/parse-error.js

@@ -0,0 +1,25 @@
+/**
+ * Classifies a caught error from `JSON.parse(readFileSync(...))` (or a parsed keychain
+ * payload) into a log-safe reason + error string.
+ *
+ * V8's `JSON.parse` throws a `SyntaxError` whose `.message` can embed a prefix (or, for a
+ * short enough input, the entirety) of the unparsed content — e.g.
+ * `JSON.parse("example_local_fixture_1234567890")` produces
+ * `Unexpected token 'e', "example_lo"... is not valid JSON`. Logging that message would
+ * leak exactly the secret content the parse-failure events exist to describe without
+ * exposing (see `credentials_parse_failed` / `credentials_keytar_parse_failed` /
+ * `config_parse_failed` / `state_parse_failed`). So for a `SyntaxError` this reports only
+ * the error name, never `.message`.
+ *
+ * Any other error (fs I/O — `EACCES`, `EISDIR`, etc.) is reported as `unreadable` using its
+ * errno `code`, which never contains file content and is more actionable than a bare name.
+ */
+export function describeReadFailure(err) {
+    if (err instanceof SyntaxError) {
+        return { reason: "invalid_json", error: "SyntaxError" };
+    }
+    const code = err?.code;
+    if (code)
+        return { reason: "unreadable", error: code };
+    return { reason: "unreadable", error: err instanceof Error ? err.name : "unknown_error" };
+}

package/dist/state.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { createHash, randomBytes } from "node:crypto";
 import { mcpLog } from "./log.js";
+import { describeReadFailure } from "./lib/parse-error.js";
 export function getAppDir() {
     const override = process.env["AIXLE_INSIGHTS_HOME"]?.trim();
     if (override && override.length > 0)
@@ -90,48 +91,50 @@ export function migrateLegacyState(dir, host, token) {
 }
 export function readState(dir, host, token) {
     const filePath = stateFilePath(dir ?? getAppDir(), host, token);
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
-        if (typeof parsed === "object" && parsed !== null) {
-            const p = parsed;
-            if (typeof p.version === "number" &&
-                typeof p.sessions === "object" &&
-                p.sessions !== null) {
-                const lastRecentCommitHashes = Array.isArray(p.lastRecentCommitHashes)
-                    ? p.lastRecentCommitHashes.filter((h) => typeof h === "string")
-                    : undefined;
-                const out = {
-                    version: p.version,
-                    sessions: p.sessions,
-                };
-                if (lastRecentCommitHashes !== undefined) {
-                    out.lastRecentCommitHashes = lastRecentCommitHashes;
-                }
-                if ("mcp_operator" in p) {
-                    const mcp = parseMcpOperator(p.mcp_operator);
-                    if (mcp)
-                        out.mcp_operator = mcp;
-                }
-                if ("rate_limited_until" in p) {
-                    if (typeof p.rate_limited_until === "string") {
-                        out.rate_limited_until = p.rate_limited_until;
-                    }
-                    else if (p.rate_limited_until === null) {
-                        out.rate_limited_until = null;
-                    }
-                }
-                return out;
-            }
-        }
+        parsed = JSON.parse(readFileSync(filePath, "utf-8"));
     }
     catch (err) {
         const code = err?.code;
         if (code !== "ENOENT") {
-            // State file exists but failed to parse — distinguishes tampering from "never created".
-            mcpLog.warn("state_parse_failed", { path: filePath, error: err instanceof Error ? err.message : String(err) }, false);
+            // State file exists but is not valid JSON — distinguishes tampering from "never created".
+            // ENOENT stays silent: that is the normal first-run case.
+            mcpLog.warn("state_parse_failed", { path: filePath, ...describeReadFailure(err) }, false);
+        }
+        return { version: 1, sessions: {} };
+    }
+    const p = typeof parsed === "object" && parsed !== null ? parsed : null;
+    if (p === null || typeof p.version !== "number" || typeof p.sessions !== "object" || p.sessions === null) {
+        // Valid JSON, wrong shape. This fallback discards every dedup checkpoint and causes a full
+        // re-send, so it is the most consequential of the four to have been silent. (DB90DV-699)
+        mcpLog.warn("state_parse_failed", { path: filePath, reason: "invalid_shape" }, false);
+        return { version: 1, sessions: {} };
+    }
+    const lastRecentCommitHashes = Array.isArray(p.lastRecentCommitHashes)
+        ? p.lastRecentCommitHashes.filter((h) => typeof h === "string")
+        : undefined;
+    const out = {
+        version: p.version,
+        sessions: p.sessions,
+    };
+    if (lastRecentCommitHashes !== undefined) {
+        out.lastRecentCommitHashes = lastRecentCommitHashes;
+    }
+    if ("mcp_operator" in p) {
+        const mcp = parseMcpOperator(p.mcp_operator);
+        if (mcp)
+            out.mcp_operator = mcp;
+    }
+    if ("rate_limited_until" in p) {
+        if (typeof p.rate_limited_until === "string") {
+            out.rate_limited_until = p.rate_limited_until;
+        }
+        else if (p.rate_limited_until === null) {
+            out.rate_limited_until = null;
         }
     }
-    return { version: 1, sessions: {} };
+    return out;
 }
 /** Atomic write: write to a temp file then rename over the target. */
 export function writeState(state, dir, host, token) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aixle/insights",
-  "version": "0.2.4-staging",
+  "version": "0.2.5-staging",
   "description": "stdio MCP server for AI coding-assistant telemetry — Claude transcript sync + Cursor SQLite ingest.",
   "type": "module",
   "bin": {