@aixle/insights 0.1.1 → 0.2.1-staging

package/README.md

@@ -2,6 +2,83 @@
 
 stdio **MCP server** for AI coding-assistant telemetry. Ingests Claude Code JSONL transcripts and Cursor IDE SQLite telemetry into your organization's ingest API, exposes operator tools on the MCP bridge, and pairs with `aixle-insights init` so teammates can onboard without juggling cron jobs or brittle shell hooks.
 
+## Architecture reference
+
+For implementation architecture, design decisions, and package direction, see [`ARD.md`](./ARD.md).
+
+## Choosing a version
+
+Two channels are published. Pick one deliberately — they are **not** interchangeable.
+
+| | Production | Staging (QA) |
+|---|---|---|
+| Install | `npm i -g @aixle/insights` | `npm i -g @aixle/insights@staging` |
+| Version looks like | `0.2.0` | `0.2.1-staging` |
+| Points at | the production API | the staging API |
+| Who should use it | **everyone** | QA validating unreleased work |
+| Stability | released, supported | may change or break without notice |
+
+### Production — use this unless told otherwise
+
+```bash
+# One-shot via npx (recommended — always pulls the current release):
+npx -y @aixle/insights init \
+  --host https://insights.aixle.com \
+  --keycloak-url https://YOUR-KEYCLOAK/realms/YOUR_REALM
+
+# Or global install:
+npm i -g @aixle/insights
+aixle-insights --version    # e.g. 0.2.0  (no suffix)
+```
+
+### Staging — QA only
+
+Staging builds carry a `-staging` suffix and live on the `staging` dist-tag. You must ask for
+them explicitly; a plain `npm install` will never give you one.
+
+```bash
+# One-shot via npx:
+npx -y @aixle/insights@staging init \
+  --host https://staging.insights.aixle.com \
+  --keycloak-url https://YOUR-STAGING-KEYCLOAK/realms/YOUR_REALM
+
+# Or global install:
+npm i -g @aixle/insights@staging
+aixle-insights --version    # e.g. 0.2.1-staging  (note the suffix)
+```
+
+Point a staging build at the **staging** API host. Sending staging telemetry to production
+pollutes production analytics.
+
+### Which one do I have?
+
+```bash
+aixle-insights --version                 # a -staging suffix means a QA build
+npm view @aixle/insights dist-tags       # what each channel currently resolves to
+```
+
+Expected output — `latest` and `staging` move independently:
+
+```
+{ latest: '0.2.0', staging: '0.2.1-staging' }
+```
+
+### Switching back to production
+
+```bash
+npm i -g @aixle/insights@latest
+```
+
+Then re-run `init` against the production host, since credentials and the MCP entry are
+per-host.
+
+> **Why `npm install` never surprises you with a staging build:** `-staging` versions are semver
+> prereleases, and no ordinary version range resolves to a prerelease. `*`, `^0.2.0`, `~0.2.0`
+> and `>=0.1.0` all select `0.2.0` even when `0.2.1-staging` exists. Staging builds are
+> reachable only by exact version or the `staging` dist-tag.
+
+Maintainers: see [`../RELEASING.md`](../RELEASING.md) for how each channel is cut.
+
 ## Install
 
 ```bash
@@ -21,7 +98,7 @@ After `init` succeeds:
 
 1. **Restart Claude Code** — it discovers the new MCP server on the next launch.
 2. Open Claude Code; confirm `/mcp` lists **aixle-insights**.
-3. During a Claude session invoke the **`db90_status`** MCP tool (or `aixle-insights health` from the shell) to see connectivity + last sync metadata.
+3. During a Claude session invoke the **`aixle_insights_status`** MCP tool (or `aixle-insights health` from the shell) to see connectivity + last sync metadata.
 
 ## Multi-org
 
@@ -36,6 +113,14 @@ npx -y @aixle/insights init \
 
 You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin it via `mcpServers.aixle-insights.env` in `~/.claude.json`. The CLI flag overrides the env var when both are set.
 
+## First run and backfill
+
+Before you run `init`, the MCP server is a deliberate no-op: it does not read, buffer, or send anything, and it does not create any state files. Nothing is lost during this window — Claude Code's transcripts and Cursor's local telemetry stores are unaffected by whether `@aixle/insights` is watching them.
+
+The moment `init` succeeds, this package's per-credential state starts from empty (no watermark, no dedupe checkpoint). That means **the very first sync after `init` treats "everything currently on disk" as new** — Claude transcript JSONL files and Cursor SQLite history alike — and sends all of it, not just activity from that point forward. There is no separate "backfill mode" to opt into; it is simply what an empty watermark means the first time `run --once` or the background sync loop executes.
+
+If the MCP has been installed but never connected, `aixle-insights health` (or the `status` MCP tool) reports `needs_init: true` with a human-readable `onboarding_message` explaining exactly this — install-but-uninitialized is not a state you need to worry about losing data in.
+
 ## Commands
 
 | Command | What it does |
@@ -44,6 +129,8 @@ You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin
 | `aixle-insights run --once` | Perform one multi-tool sync, exit. Useful for cron / manual flushes. |
 | `aixle-insights run --once --full` | Backfill: ignore Cursor watermarks and commit-hash dedupe. |
 | `aixle-insights init` | Keycloak device login + persist credentials + merge `~/.claude.json` entry. |
+| `aixle-insights init --host <url>` | Use a DB90 API origin for token exchange. Remote hosts must use HTTPS; `http://localhost` and loopback addresses are allowed for local development. |
+| `aixle-insights init --insecure --host http://...` | Allow a remote plaintext HTTP host for a trusted non-production test endpoint. Prints a warning because tokens and telemetry can be exposed. |
 | `aixle-insights init --hooks --tool-name cursor` | Also install the Cursor-side hook forwarder (opt-in; requires Cursor restart). |
 | `aixle-insights uninstall-hooks` | Remove the hook forwarder + restore `~/.cursor/hooks.json` backup. |
 | `aixle-insights verify-hooks` | Print hooks install status + queue depth as JSON. |
@@ -59,6 +146,8 @@ You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin
 | `DB90_ORGANIZATION_ID` | Optional UUID scoping `init` to that org membership (header `X-Organization-ID`). |
 | `AIXLE_INSIGHTS_HOME` | Override the local state directory (defaults to `~/.aixle-insights/`). |
 
+Remote API and ingest hosts must use `https://`. Plaintext `http://` is local-dev-only for `localhost`, `127.0.0.0/8`, and `[::1]`; those loopback URLs work without warnings. A remote `http://` host is rejected during `init` unless you pass `--insecure`, which should only be used for trusted non-production test endpoints and will print a warning because ingest tokens and telemetry can cross the network unencrypted.
+
 Note: the `DB90_*` variables above are retained as compatibility names for the deployment-side Keycloak realm/client identifiers. Future versions may rename them with a deprecation window.
 
 Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per-model rates):
@@ -73,6 +162,32 @@ Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per
 }
 ```
 
+## 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.
+
+### Three gates
+
+| Gate | Where it fires | What it checks |
+|---|---|---|
+| CLI `--host` gate | `runInit()` at the top of `aixle-insights init`, before any network call to Keycloak | The `--host` value the user typed |
+| Post-exchange `ingestHost` gate | `auth/flow.ts`, immediately after the OIDC-for-ingest-token exchange returns, before persisting credentials to the keychain | The `ingestHost` returned by the server, in case it differs from `--host` |
+| Runtime send/lookup gate | `lib/client.ts`'s `postEvent` and `lib/project-resolver.ts`'s `lookupProjectByRemote`, immediately before every ingest POST and project-attribution GET | The `host` loaded from stored credentials, on **every** sync cycle — not just at `init` |
+
+All three gates use the same pure utility, `evaluateTransportSecurity()` in `src/lib/transport-security.ts`. The first two rejecting aborts `init` with exit code 1 and a single-line error naming the offending host. The third rejecting drops that send/lookup (logged via `console.error`, no retry) without aborting the whole sync cycle — a single tampered credential shouldn't crash background sync, it should just refuse to leak the token.
+
+The runtime gate exists because `init`'s two gates only run once, at login time. If `~/.aixle-insights/credentials.json` is edited afterward (by hand, by malware, or by disk corruption) to point at a plaintext `http://` remote, nothing previously re-checked the scheme before every subsequent sync sent the bearer token — DB90DV-539 closed that gap.
+
+### `--insecure` (init-only, consent persists to runtime)
+
+`aixle-insights init --insecure --host http://<remote>` downgrades the first two gates from "reject" to "warn + continue." It is intended only for trusted non-production test endpoints (e.g. a self-hosted staging on a private network without a TLS cert).
+
+`--insecure` is rejected on the `run` subcommand by design — the long-running MCP server should never run insecurely, and since `run` is normally spawned non-interactively (by Claude Code, via `~/.claude.json`), there is no ergonomic way to pass a flag to it per-cycle anyway. Instead, when `init --insecure` is used, that consent is recorded as `insecureHttpAllowed: true` on the stored credential (`StoredCredentials.insecureHttpAllowed` in `auth/credentials.ts`) and every later `run` reads it back — so a legitimately-approved trusted HTTP endpoint keeps syncing normally. A `credentials.json` that has an `http://` remote host **without** this flag set (e.g. because someone hand-edited the file after the fact, bypassing `init` entirely) is rejected by the runtime gate on every send.
+
+### What is NOT gated
+
+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.
+
 ## 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.
@@ -80,9 +195,25 @@ Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per
 ## State + credentials
 
 - **App home directory**: `~/.aixle-insights/` (override with `AIXLE_INSIGHTS_HOME`).
-- **Credentials**: OS keychain via `keytar` when available (service: `aixle-insights`); fallback file `~/.aixle-insights/credentials.json` with mode 0600 on POSIX.
+- **Credentials**: the OS keychain is the source of truth. On read, the keychain is consulted **first**; the file is only a fallback when the keychain is unavailable, empty, or explicitly disabled (`DB90_MCP_DISABLE_KEYTAR`). On write, credentials go to the keychain and the file is removed when the keychain write succeeds.
 - **State files**: `state-<hostname>-<token-hash>.json` per credential, plus `state.lock` advisory lock, `mcp.log` rotating diagnostic log, optional `hooks-queue.ndjson`.
 
+### Credential storage by OS
+
+The secure store is the platform's native keychain, accessed via `keytar` (service `aixle-insights`):
+
+| OS | Secure store | Availability | Fallback file protection |
+| --- | --- | --- | --- |
+| **macOS** | Keychain | reliably present | `credentials.json` written `chmod 0600` |
+| **Windows** | Credential Manager | reliably present | `credentials.json` best-effort locked via `icacls` (Node `chmod` cannot set NTFS ACLs) |
+| **Linux** | Secret Service (libsecret / GNOME Keyring / KWallet) | **often absent** on headless servers, minimal Docker images, and CI — no D-Bus secret service | `credentials.json` written `chmod 0600` |
+
+Notes:
+
+- **Windows**: don't set `DB90_MCP_DISABLE_KEYTAR` — Credential Manager is reliably present, and the plaintext fallback file cannot be locked down as tightly as the keychain. The `icacls` hardening is best-effort defense-in-depth.
+- **Linux**: when no Secret Service is running (common in headless/CI/container contexts), the tool degrades to the `chmod 0600` fallback file **by design** — this is the one environment where the file path is routinely exercised, and POSIX permissions protect it there.
+- A stale `credentials.json` sitting alongside a populated keychain entry is logged as drift (`credentials_file_shadowed_by_keychain` in `mcp.log`) and ignored in favour of the keychain.
+
 The internal state-file shape is implementation-detail; don't depend on it from outside this package.
 
 ## Diagnostics
@@ -92,7 +223,21 @@ aixle-insights health        # connectivity + last sync metadata
 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 **`db90_status`** MCP tool returns the same diagnostic structure as `aixle-insights health`.
+`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`.
+
+## Troubleshooting
+
+| Symptom | Most likely cause | Fix |
+|---|---|---|
+| `Error: DB90 API host <name> uses remote plaintext HTTP.` | You passed `--host http://<remote>` without `--insecure`. | Use `https://...`, or add `--insecure` if you know the endpoint is trusted and non-production. |
+| `Blocked event send — DB90 ingest host <name> uses remote plaintext HTTP.` (or `Blocked project lookup — ...`) in `mcp.log` / console during `run` | `credentials.json` (or the keychain entry) has an `http://` remote `host` without a recorded `--insecure` consent — most likely because it was edited outside of `init`. | Re-run `aixle-insights init --host https://... ` (or `init --insecure --host http://...` if the endpoint is genuinely trusted non-prod) to re-establish credentials with an explicit, recorded decision. |
+| `Auth failed: fetch failed` during `init` | The `--keycloak-url` host doesn't resolve (NXDOMAIN), is behind a VPN, or the TLS cert is bad. | Verify with `curl -sS https://<host>/realms/<realm>/.well-known/openid-configuration`. For DB90 staging, the canonical Keycloak URL is embedded in the SPA — `curl https://<APP_HOST> \| grep keycloakUrl` extracts the current value. |
+| `Failed to post event: HTTP 401 Unauthorized` repeated for every turn | Your saved ingest token has been rotated, revoked, or invalidated by a server redeploy. The ingest token is distinct from the Keycloak access token that `health` reports as `authenticated: true`. | Reset the keychain entry and re-run `init`: `security delete-generic-password -s "aixle-insights" -a "aixle-insights-ingest-credential"` then `rm -f ~/.aixle-insights/credentials.json` then `aixle-insights init --host ... --keycloak-url ...`. State files are **not** deleted, so already-sent sessions stay deduped. |
+| `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`). |
+| `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. |
 
 ## Local development — `/aixle-reset` skill
 
@@ -131,6 +276,12 @@ After the script reports success: **quit and reopen Claude Code / Cursor** so ea
 
 - Node.js ≥ 20.
 - macOS / Linux / Windows. On Windows, the package writes a `cmd /c npx …` wrapper in `~/.claude.json` so Claude Code can spawn the MCP server reliably.
+- `better-sqlite3` is a native module. After a Node upgrade, if SQLite reads start failing, rebuild it from the tools workspace:
+
+```bash
+cd packages/tools
+npm rebuild better-sqlite3
+```
 
 ## License
 

package/dist/auth/credentials.d.ts

@@ -5,6 +5,12 @@ export interface StoredCredentials {
     host: string;
     organizationId?: string;
     accounts: Partial<Record<TelemetryToolId, string>>;
+    /**
+     * Set only when the user explicitly passed `init --insecure` for this host.
+     * There is no `run --insecure` flag (by design — see README § Security), so
+     * runtime sync honors this persisted consent instead of re-prompting.
+     */
+    insecureHttpAllowed?: boolean;
 }
 export declare const KEYTAR_SERVICE = "aixle-insights";
 /** Returns true when at least one tool has a non-empty token. */
@@ -12,7 +18,7 @@ export declare function credentialsHaveAnyToken(creds: StoredCredentials): boole
 export declare function pickProjectLookupToken(creds: StoredCredentials): string | null;
 /** Read credentials from disk only (tests / fallback). */
 export declare function loadCredentialsFromFileOnly(appDir?: string): StoredCredentials | null;
-/** Prefer OS keychain when keytar works; otherwise read `credentials.json`. */
+/** Prefer the OS keychain when keytar works; fall back to `credentials.json`. */
 export declare function loadCredentials(appDir?: string): Promise<StoredCredentials | null>;
 /**
  * Persist multi-tool ingest tokens for one host namespace.

package/dist/auth/credentials.js

@@ -1,6 +1,9 @@
+import { execFileSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { userInfo } from "node:os";
 import { join } from "node:path";
 import { getAppDir } from "../state.js";
+import { mcpLog } from "../log.js";
 export const KEYTAR_SERVICE = "aixle-insights";
 const KEYTAR_ACCOUNT = "aixle-insights-ingest-credential";
 function credentialsPath(appDir) {
@@ -45,6 +48,7 @@ function normalizeLoadedCredentials(raw) {
             host,
             accounts: out,
             organizationId: typeof org === "string" ? org : undefined,
+            ...(o.insecureHttpAllowed === true ? { insecureHttpAllowed: true } : {}),
         };
     }
     const token = o.token;
@@ -62,22 +66,33 @@ export function loadCredentialsFromFileOnly(appDir = getAppDir()) {
         const raw = JSON.parse(readFileSync(filePath, "utf-8"));
         return normalizeLoadedCredentials(raw);
     }
-    catch {
+    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);
         return null;
     }
 }
 async function tryKeytarGet() {
     if (keytarDisabled())
         return null;
+    let raw;
     try {
         const keytar = await import("keytar");
-        const raw = await keytar.default.getPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
-        if (!raw)
-            return null;
+        raw = await keytar.default.getPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+    }
+    catch {
+        // Keytar unavailable (native module missing/unbuilt, no Secret Service, etc.) — silent fallback to file, same as tryKeytarSet.
+        return null;
+    }
+    if (!raw)
+        return null;
+    try {
         const parsed = JSON.parse(raw);
         return normalizeLoadedCredentials(parsed);
     }
-    catch {
+    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);
         return null;
     }
 }
@@ -100,8 +115,32 @@ async function tryKeytarDelete() {
         const keytar = await import("keytar");
         await keytar.default.deletePassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
     }
+    catch (err) {
+        // Non-fatal, but a stale keychain entry can mislead later loads — record it.
+        mcpLog.warn("keytar_delete_failed", { keytarService: KEYTAR_SERVICE, error: err instanceof Error ? err.message : String(err) }, false);
+    }
+}
+/**
+ * Best-effort NTFS ACL lock-down for the fallback credentials file on Windows.
+ *
+ * Node's file `mode` / `chmodSync` only toggle the read-only bit on Windows — they do NOT
+ * map to NTFS ACLs — so the POSIX `0o600` we set on other platforms has no real effect there.
+ * We shell out to the built-in `icacls` to drop inherited ACEs and grant only the current user
+ * full control. Mirrors the POSIX `chmod` best-effort: any failure is swallowed (the user-profile
+ * directory already blocks cross-user reads, and Windows Credential Manager — the preferred store
+ * via keytar — makes this fallback file rare in the first place).
+ */
+function restrictWindowsAclBestEffort(filePath) {
+    try {
+        const user = userInfo().username;
+        if (!user)
+            return;
+        execFileSync("icacls", [filePath, "/inheritance:r", "/grant:r", `${user}:F`], {
+            stdio: "ignore",
+        });
+    }
     catch {
-        // ignore
+        // best-effort, non-fatal — same posture as the POSIX chmod
     }
 }
 function writeFileCredential(appDir, creds) {
@@ -112,12 +151,16 @@ function writeFileCredential(appDir, creds) {
         host: creds.host,
         organizationId: creds.organizationId,
         accounts: { ...creds.accounts },
+        ...(creds.insecureHttpAllowed ? { insecureHttpAllowed: true } : {}),
     };
     writeFileSync(filePath, `${JSON.stringify(body, null, 2)}\n`, {
         encoding: "utf-8",
         mode: 0o600,
     });
-    if (process.platform !== "win32") {
+    if (process.platform === "win32") {
+        restrictWindowsAclBestEffort(filePath);
+    }
+    else {
         try {
             chmodSync(filePath, 0o600);
         }
@@ -132,19 +175,27 @@ function removeFileCredential(appDir) {
         try {
             unlinkSync(filePath);
         }
-        catch {
-            // ignore
+        catch (err) {
+            // A stale plaintext credentials.json left behind here is exactly the drift loadCredentials warns about.
+            mcpLog.warn("credentials_file_remove_failed", { path: filePath, error: err instanceof Error ? err.message : String(err) }, false);
         }
     }
 }
-/** Prefer OS keychain when keytar works; otherwise read `credentials.json`. */
+/** Prefer the OS keychain when keytar works; fall back to `credentials.json`. */
 export async function loadCredentials(appDir = getAppDir()) {
+    const fromKeytar = await tryKeytarGet();
+    if (fromKeytar) {
+        // Keychain is the source of truth; a lingering file is stale and silently shadowed it before this fix.
+        // Warn-only (log file, no stderr mirror): drift is recorded without spamming the background sync loop,
+        // and the next saveStoredCredentials removes the file. We do not mutate disk on a read.
+        if (existsSync(credentialsPath(appDir))) {
+            mcpLog.warn("credentials_file_shadowed_by_keychain", { path: credentialsPath(appDir), keytarService: KEYTAR_SERVICE }, false);
+        }
+        return fromKeytar;
+    }
     const fromFile = loadCredentialsFromFileOnly(appDir);
     if (fromFile)
         return fromFile;
-    const fromKeytar = await tryKeytarGet();
-    if (fromKeytar)
-        return fromKeytar;
     return null;
 }
 /**
@@ -154,7 +205,13 @@ export async function saveStoredCredentials(creds, appDir = getAppDir()) {
     if (!credentialsHaveAnyToken(creds)) {
         throw new Error("saveStoredCredentials requires at least one account token");
     }
-    const payload = JSON.stringify({ version: 2, ...creds, accounts: { ...creds.accounts } });
+    const payload = JSON.stringify({
+        version: 2,
+        host: creds.host,
+        organizationId: creds.organizationId,
+        accounts: { ...creds.accounts },
+        ...(creds.insecureHttpAllowed ? { insecureHttpAllowed: true } : {}),
+    });
     const keytarOk = await tryKeytarSet(payload);
     if (keytarOk) {
         removeFileCredential(appDir);

package/dist/auth/exchange.d.ts

@@ -11,7 +11,7 @@ export interface ExchangeResult {
 }
 type ExchangeToolId = "claude_code" | "cursor";
 export declare function exchangeIngestToken(params: {
-    db90Host: string;
+    apiHost: string;
     keycloakAccessToken: string;
     /** Legacy single-tool mint. Omit when tools is provided. */
     toolName?: ExchangeToolId;

package/dist/auth/exchange.js

@@ -1,7 +1,7 @@
 export async function exchangeIngestToken(params) {
     const fetchFn = params.fetchImpl ?? fetch;
     const requestedTools = params.tools?.length ? [...params.tools] : params.toolName ? [params.toolName] : [];
-    const base = params.db90Host.replace(/\/$/, "");
+    const base = params.apiHost.replace(/\/$/, "");
     const url = `${base}/api/v1/integrations/mcp/exchange`;
     const body = {};
     if (params.tools?.length) {

package/dist/auth/flow.d.ts

@@ -1,7 +1,7 @@
 import { defaultKeycloakClientId, defaultKeycloakIssuer } from "./keycloak.js";
 import type { TelemetryToolId } from "./credentials.js";
 export interface LoginAndPersistOptions {
-    db90Host: string;
+    apiHost: string;
     keycloakIssuer: string;
     /** @deprecated Prefer `tools`; kept for callers that mint a single ingest account. */
     toolName?: string;
@@ -11,12 +11,21 @@ export interface LoginAndPersistOptions {
     exchangeOrganizationId?: string;
     clientId?: string;
     appDir?: string;
+    allowInsecureHttp?: boolean;
+    /** Skip the "already authenticated" short-circuit and re-run the device flow. */
+    force?: boolean;
+    onSecurityWarning?: (message: string) => void;
     onVisitInstructions?: (verification_uri: string, user_code: string) => void;
     fetchImpl?: typeof fetch;
 }
 export declare function loginAndPersistCredentials(opts: LoginAndPersistOptions): Promise<{
     ok: true;
     organizationId: string;
+} | {
+    ok: true;
+    alreadyAuthenticated: true;
+    host: string;
+    organizationId?: string;
 } | {
     ok: false;
     error: string;

package/dist/auth/flow.js

@@ -2,15 +2,37 @@ import { exchangeIngestToken } from "./exchange.js";
 import { defaultKeycloakClientId, defaultKeycloakIssuer, obtainKeycloakAccessTokenViaDeviceFlow } from "./keycloak.js";
 import { loadCredentials, saveStoredCredentials } from "./credentials.js";
 import { getAppDir } from "../state.js";
+import { evaluateTransportSecurity } from "../lib/transport-security.js";
+function normalizeHostForComparison(host) {
+    return host.replace(/\/$/, "");
+}
+function credentialsCoverRequestedTools(creds, requestedTools) {
+    return requestedTools.every((tool) => {
+        const token = creds.accounts[tool];
+        return typeof token === "string" && token.length > 0;
+    });
+}
+function credentialsMatchRequestedScope(creds, opts, requestedTools) {
+    if (normalizeHostForComparison(creds.host) !== normalizeHostForComparison(opts.apiHost))
+        return false;
+    if (opts.exchangeOrganizationId && creds.organizationId !== opts.exchangeOrganizationId)
+        return false;
+    return credentialsCoverRequestedTools(creds, requestedTools);
+}
 export async function loginAndPersistCredentials(opts) {
+    const appDir = opts.appDir ?? getAppDir();
+    const requestedTools = opts.tools ?? ((opts.toolName ?? "claude_code") === "cursor" ? ["cursor"] : ["claude_code"]);
+    if (!opts.force) {
+        const existing = await loadCredentials(appDir);
+        if (existing && credentialsMatchRequestedScope(existing, opts, requestedTools)) {
+            return { ok: true, alreadyAuthenticated: true, host: existing.host, organizationId: existing.organizationId };
+        }
+    }
     const issuer = opts.keycloakIssuer.trim();
     if (!issuer) {
         return { ok: false, error: "Keycloak issuer is empty; set KEYCLOAK_ISSUER or pass --keycloak-url." };
     }
     const clientId = opts.clientId?.trim() || defaultKeycloakClientId();
-    const appDir = opts.appDir ?? getAppDir();
-    const requestedTools = opts.tools ??
-        ((opts.toolName ?? "claude_code") === "cursor" ? ["cursor"] : ["claude_code"]);
     let accessToken;
     try {
         accessToken = await obtainKeycloakAccessTokenViaDeviceFlow({
@@ -27,7 +49,7 @@ export async function loginAndPersistCredentials(opts) {
     try {
         if (requestedTools.length > 1) {
             exchanged = await exchangeIngestToken({
-                db90Host: opts.db90Host,
+                apiHost: opts.apiHost,
                 keycloakAccessToken: accessToken,
                 tools: requestedTools,
                 deviceLabel: opts.deviceLabel,
@@ -37,7 +59,7 @@ export async function loginAndPersistCredentials(opts) {
         }
         else {
             exchanged = await exchangeIngestToken({
-                db90Host: opts.db90Host,
+                apiHost: opts.apiHost,
                 keycloakAccessToken: accessToken,
                 toolName: requestedTools[0],
                 deviceLabel: opts.deviceLabel,
@@ -45,11 +67,22 @@ export async function loginAndPersistCredentials(opts) {
                 fetchImpl: opts.fetchImpl,
             });
         }
+        const ingestHostSecurity = evaluateTransportSecurity(exchanged.ingestHost, {
+            allowInsecureHttp: opts.allowInsecureHttp === true,
+            label: "DB90 ingest host",
+        });
+        if (!ingestHostSecurity.ok) {
+            return { ok: false, error: ingestHostSecurity.error };
+        }
+        if (ingestHostSecurity.warning) {
+            opts.onSecurityWarning?.(ingestHostSecurity.warning);
+        }
         const existing = await loadCredentials(appDir);
         const stored = {
             host: exchanged.ingestHost,
             organizationId: exchanged.organizationId,
             accounts: existing?.host === exchanged.ingestHost ? { ...existing.accounts } : {},
+            ...(opts.allowInsecureHttp === true ? { insecureHttpAllowed: true } : {}),
         };
         for (const tid of ["claude_code", "cursor"]) {
             const acc = exchanged.accounts[tid];

package/dist/auth/keycloak.d.ts

@@ -31,5 +31,5 @@ export declare function obtainKeycloakAccessTokenViaDeviceFlow(params: {
     onInstructions?: (verification_uri: string, user_code: string) => void;
     fetchImpl?: typeof fetch;
 }): Promise<string>;
-export declare function defaultKeycloakIssuer(): string;
+export declare function defaultKeycloakIssuer(ingestHost?: string): string;
 export declare function defaultKeycloakClientId(): string;

package/dist/auth/keycloak.js

@@ -2,6 +2,7 @@
  * RFC 8628 OAuth 2.0 Device Authorization Grant against Keycloak OIDC endpoints.
  */
 import { createHash, randomBytes } from "node:crypto";
+import { isLoopbackHost } from "../lib/transport-security.js";
 function normalizeIssuer(issuer) {
     return issuer.replace(/\/$/, "");
 }
@@ -154,13 +155,31 @@ export async function obtainKeycloakAccessTokenViaDeviceFlow(params) {
         fetchImpl: params.fetchImpl,
     });
 }
-export function defaultKeycloakIssuer() {
+export function defaultKeycloakIssuer(ingestHost) {
     const fromEnv = process.env["DB90_KEYCLOAK_ISSUER"]?.trim() ||
         process.env["KEYCLOAK_ISSUER"]?.trim();
     if (fromEnv)
         return fromEnv.replace(/\/$/, "");
     const useLocalDefault = ["1", "true", "yes"].includes(process.env["DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT"]?.toLowerCase() ?? "");
     if (useLocalDefault || process.env["NODE_ENV"] === "development") {
+        if (ingestHost) {
+            let hostname;
+            try {
+                hostname = new URL(ingestHost).hostname;
+            }
+            catch {
+                hostname = ingestHost;
+            }
+            if (!isLoopbackHost(hostname)) {
+                const reason = useLocalDefault
+                    ? `DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT=${process.env["DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT"]}`
+                    : `NODE_ENV=development`;
+                console.error(`[aixle-insights] Warning: ${reason} would redirect Keycloak authentication to ` +
+                    `http://localhost:8080, but the ingest host "${ingestHost}" is not localhost. ` +
+                    `Ignoring the local Keycloak default. Set DB90_KEYCLOAK_ISSUER explicitly.`);
+                return "";
+            }
+        }
         return "http://localhost:8080/realms/db90";
     }
     return "";

package/dist/cli.d.ts

@@ -7,8 +7,9 @@ import { migrateLegacyState, getAppDir } from "./state.js";
 import { syncTelemetryTools } from "./sync.js";
 import { mergePricing } from "./pricing.js";
 import { type InstallClaudeUserMcpOptions, type InstallResult } from "./install/claude.js";
+import { type InstallCursorUserMcpOptions } from "./install/cursor.js";
 export interface Args {
-    command: "init" | "health" | "run" | "help" | "uninstall-hooks" | "verify-hooks";
+    command: "init" | "health" | "run" | "help" | "uninstall-hooks" | "verify-hooks" | "uninstall-cursor-mcp";
     help: boolean;
     once: boolean;
     /** With `run --once`: ignore Cursor watermarks and commit hash dedupe. */
@@ -21,6 +22,8 @@ export interface Args {
     force?: boolean;
     /** When set on init, install the Cursor hooks forwarder into ~/.cursor/hooks.json. */
     hooks?: boolean;
+    /** Allow remote plaintext HTTP hosts for trusted non-production test environments. */
+    insecure?: boolean;
 }
 interface RunOnceDeps {
     loadCredentials: typeof loadCredentials;
@@ -37,12 +40,13 @@ interface InitDeps {
     defaultKeycloakIssuer: typeof defaultKeycloakIssuer;
     getAppDir: typeof getAppDir;
     installClaudeUserMcp: (options: InstallClaudeUserMcpOptions) => InstallResult;
+    installCursorUserMcp: (options: InstallCursorUserMcpOptions) => InstallResult;
     log: (message: string) => void;
     error: (message: string) => void;
 }
 /** Matches DB90 Rails `McpController` UUID check for `X-Organization-ID` (RFC 4122 variant). */
-export declare const DB90_ORGANIZATION_UUID_PATTERN: RegExp;
-export declare function isValidDb90OrganizationUuid(value: string): boolean;
+export declare const ORGANIZATION_UUID_PATTERN: RegExp;
+export declare function isValidOrganizationUuid(value: string): boolean;
 export declare function parseArgs(argv: string[]): Args;
 export declare function runInit(cliArgs: Args, deps?: Partial<InitDeps>): Promise<number>;
 export declare function runOnce(deps?: Partial<RunOnceDeps>, options?: {