@aixle/insights 0.2.0 → 0.2.1

package/dist/health.d.ts

@@ -26,6 +26,6 @@ export interface HealthSnapshot {
 /** Pick the freshest persisted operator block by `last_sync_at` lexicographic (ISO-safe). */
 export declare function mergePersistedOperators(snapshots: McpOperatorState[]): McpOperatorState | null;
 export declare function buildHealthSnapshot(): Promise<HealthSnapshot>;
-/** MCP `db90_status` JSON — single source shared with CLI health. */
+/** MCP `aixle_insights_status` JSON — single source shared with CLI health. */
 export declare function healthSnapshotToStatusPayload(snapshot: HealthSnapshot): Record<string, unknown>;
 export declare function formatHealthForCli(snapshot: HealthSnapshot): string;

package/dist/health.js

@@ -133,7 +133,7 @@ export async function buildHealthSnapshot() {
         };
     }
 }
-/** MCP `db90_status` JSON — single source shared with CLI health. */
+/** MCP `aixle_insights_status` JSON — single source shared with CLI health. */
 export function healthSnapshotToStatusPayload(snapshot) {
     const proc = snapshot.process;
     const pers = snapshot.persisted;

package/dist/hooks/cursor-hooks-reader.d.ts

@@ -8,6 +8,8 @@ export interface ProcessHooksQueueParams {
     state: State;
     host: string;
     token: string;
+    /** Mirrors StoredCredentials.insecureHttpAllowed — set when `init --insecure` was used for this host. */
+    allowInsecureHttp?: boolean;
     /** Called when a 429 is received. */
     on429: (retryAfter: number, quotaExceeded: boolean) => void;
     /** If true, skip events already in state.sessions. */

package/dist/hooks/cursor-hooks-reader.js

@@ -6,9 +6,16 @@ import { markSessionSent } from "../state.js";
 import { postEvent } from "../client.js";
 import { mcpLog } from "../log.js";
 import { shouldIngestHookEvent, mapHookEventToPayload, hookDedupeKey, warnOnCursorVersion, CURSOR_HOOK_STATE_PREFIX, } from "./cursor-hooks-mapper.js";
+import { isRepoPathWithinRoot, normalizeRepoPathCandidate } from "../lib/repo-path-safety.js";
 export { CURSOR_HOOK_STATE_PREFIX };
+/**
+ * `workspace` is `workspace_roots[0]` from the on-disk hooks queue — an
+ * arbitrary JSON string. A plain prefix match would accept
+ * `<scopeDir>/../../elsewhere` (DB90DV-547).
+ */
 function isUnderScopeDir(workspace, scopeDir) {
-    return workspace === scopeDir || workspace.startsWith(scopeDir + "/");
+    const normalized = normalizeRepoPathCandidate(workspace);
+    return normalized !== null && isRepoPathWithinRoot(normalized, scopeDir);
 }
 /**
  * The forwarder redacts the home directory to "~" in workspace_roots for
@@ -47,7 +54,7 @@ function rewriteQueueKeepingLines(queuePath, allLines, keepIndices) {
  * Partial failure: lines that succeeded are removed; lines that failed stay.
  */
 export async function processHooksQueue(params) {
-    const { queuePath, scopeDir, host, token, on429, skipSeen = true, resolveProjectId, verbose = false, } = params;
+    const { queuePath, scopeDir, host, token, allowInsecureHttp = false, on429, skipSeen = true, resolveProjectId, verbose = false, } = params;
     if (!existsSync(queuePath)) {
         return { sent: 0, failed: 0, skipped: 0, state: params.state };
     }
@@ -97,7 +104,7 @@ export async function processHooksQueue(params) {
             projectId = await resolveProjectId(workspace);
         }
         const payload = mapHookEventToPayload(event, projectId);
-        const ok = await postEvent(payload, host, token, { on429 });
+        const ok = await postEvent(payload, host, token, { on429, allowInsecureHttp });
         if (ok) {
             totalSent++;
             stateMut = markSessionSent(stateMut, dedupeKey, 0);

package/dist/lib/client.d.ts

@@ -8,6 +8,13 @@ export interface IngestPayload {
     [key: string]: unknown;
 }
 export interface PostEventOptions {
+    /**
+     * Skip the HTTPS-or-loopback gate for this host. Only ever set this to
+     * `true` when the caller has independently confirmed the user explicitly
+     * consented via `init --insecure` for this exact credential (see
+     * `StoredCredentials.insecureHttpAllowed`). Defaults to `false`.
+     */
+    allowInsecureHttp?: boolean;
     /** Override default console.error on non-ok HTTP response. */
     onHttpError?: (status: number, statusText: string, body: string) => void;
     /** Override default console.error on network-level failure. */

package/dist/lib/client.js

@@ -1,3 +1,4 @@
+import { evaluateTransportSecurity } from "./transport-security.js";
 /**
  * POST a single event payload to the db90 ingest endpoint.
  *
@@ -10,6 +11,22 @@
  * Never throws — callers can rely on Promise.allSettled-style aggregation.
  */
 export async function postEvent(payload, host, token, options = {}) {
+    const transportSecurity = evaluateTransportSecurity(host, {
+        allowInsecureHttp: options.allowInsecureHttp === true,
+        label: "DB90 ingest host",
+    });
+    if (!transportSecurity.ok) {
+        // Deliberately does NOT call options.onNetworkError/onHttpError: the retry
+        // wrapper in src/client.ts treats those as transient and retries with
+        // backoff. A scheme rejection is permanent — retrying wastes ~21s per
+        // event for nothing. Bare console.error mirrors this file's existing
+        // unrecoverable-failure logging style.
+        console.error(`Blocked event send — ${transportSecurity.error}`);
+        return false;
+    }
+    if (transportSecurity.warning) {
+        console.error(`Warning: ${transportSecurity.warning}`);
+    }
     const url = `${host.replace(/\/$/, "")}/api/v1/ingest/events`;
     const headers = {
         "Content-Type": "application/json",

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,11 +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.
@@ -15,25 +17,36 @@ import { join } from "node:path";
  */
 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 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 {};
     }
-    catch {
-        // missing or invalid config — fall through
+    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/lib/project-resolver.d.ts

@@ -6,8 +6,8 @@ export interface LookupResult {
     project_id: string;
     name: string;
 }
-export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
-export declare function resolveProjectIdForRepoPath(repoPath: string, host: string, token: string, verbose: boolean): Promise<ProjectResolution>;
+export declare function resolveProjectId(flagValue: string | undefined, configValue: string | undefined, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<ProjectResolution>;
+export declare function resolveProjectIdForRepoPath(repoPath: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<ProjectResolution>;
 export declare function getGitRemote(verbose: boolean): string | null;
 export declare function getGitRemoteForPath(repoPath: string, verbose: boolean): string | null;
 /**
@@ -24,7 +24,7 @@ export declare function canonicalizeGitRemote(remote: string, verbose: boolean):
  * git remote. Expand to remotes the API lookup understands (`Project.normalize_git_remote`).
  */
 export declare function repoNameToGitRemoteCandidates(repoName: string): string[];
-export declare function lookupProjectByRepoName(repoName: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;
+export declare function lookupProjectByRepoName(repoName: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<LookupResult | "not-found" | null>;
 /** Payload shape shared by db90-cursor and telemetry-mcp commit mappers. */
 export interface CommitAttributionPayload {
     event_type?: string;
@@ -44,5 +44,6 @@ export declare function enrichCommitProjectAttribution(payloads: CommitAttributi
     host: string;
     token: string;
     verbose?: boolean;
+    allowInsecureHttp?: boolean;
 }): Promise<void>;
-export declare function lookupProjectByRemote(gitRemote: string, host: string, token: string, verbose: boolean): Promise<LookupResult | "not-found" | null>;
+export declare function lookupProjectByRemote(gitRemote: string, host: string, token: string, verbose: boolean, allowInsecureHttp?: boolean): Promise<LookupResult | "not-found" | null>;

package/dist/lib/project-resolver.js

@@ -1,9 +1,12 @@
 import { execFileSync } from "node:child_process";
+import { isSafeSshHost } from "./spawn-arg-safety.js";
+import { safeGitRepoPath } from "./repo-path-safety.js";
+import { evaluateTransportSecurity } from "./transport-security.js";
 /** Coerce empty string to undefined so "" is treated as "not set" */
 function coerce(val) {
     return val === "" ? undefined : val;
 }
-export async function resolveProjectId(flagValue, configValue, host, token, verbose) {
+export async function resolveProjectId(flagValue, configValue, host, token, verbose, allowInsecureHttp = false) {
     const flag = coerce(flagValue);
     const config = coerce(configValue);
     if (flag !== undefined)
@@ -13,18 +16,18 @@ export async function resolveProjectId(flagValue, configValue, host, token, verb
     const gitRemote = getGitRemote(verbose);
     if (gitRemote === null)
         return { projectId: null, source: "none" };
-    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
         return { projectId: null, source: "auto-detect-not-found" };
     if (result !== null)
         return { projectId: result.project_id, source: "auto-detect" };
     return { projectId: null, source: "none" };
 }
-export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose) {
+export async function resolveProjectIdForRepoPath(repoPath, host, token, verbose, allowInsecureHttp = false) {
     const gitRemote = getGitRemoteForPath(repoPath, verbose);
     if (gitRemote === null)
         return { projectId: null, source: "none" };
-    const result = await lookupProjectByRemote(gitRemote, host, token, verbose);
+    const result = await lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp);
     if (result === "not-found")
         return { projectId: null, source: "auto-detect-not-found" };
     if (result !== null)
@@ -47,8 +50,19 @@ export function getGitRemote(verbose) {
     }
 }
 export function getGitRemoteForPath(repoPath, verbose) {
+    // The spawn boundary. `repoPath` is untrusted (Cursor workspace.json, a
+    // composer uri.fsPath, a hook workspace_root, or a Claude transcript cwd), so
+    // it must resolve to a real directory before git reads its .git/config.
+    // Supersedes the isSafeSpawnPathArg check from DB90DV-546, which this
+    // subsumes. See DB90DV-547.
+    const safePath = safeGitRepoPath(repoPath);
+    if (safePath === null) {
+        if (verbose)
+            console.log(`[verbose] Refusing git for unsafe repo path: ${repoPath}`);
+        return null;
+    }
     try {
-        const out = execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], {
+        const out = execFileSync("git", ["-C", safePath, "remote", "get-url", "origin"], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
             timeout: 5000,
@@ -74,12 +88,21 @@ export function canonicalizeGitRemote(remote, verbose) {
     if (!trimmed)
         return remote;
     const scp = trimmed.match(/^([\w.-]+)@([^:/]+):(.+)$/);
+    /* eslint-disable-next-line security/detect-unsafe-regex -- Flagged only
+       because safe-regex counts `?` as a repetition. Every group is separated by
+       a literal delimiter (`@`, `:`, `/`) that its neighbours exclude, so there
+       is no backtracking ambiguity. Input is a git remote URL, bounded length. */
     const sshUrl = trimmed.match(/^ssh:\/\/(?:([\w.-]+)@)?([^:/]+)(?::\d+)?\/(.+)$/i);
     const host = scp?.[2] ?? sshUrl?.[2];
-    if (!host)
+    // An unvalidated host would be parsed by ssh as an option (DB90DV-546); an
+    // unvalidated `resolved` would be spliced back into the remote and sent to
+    // the lookup endpoint. Both fail open — the remote is returned unchanged.
+    if (!host || !isSafeSshHost(host))
         return trimmed;
     const resolved = resolveSshHostName(host, verbose);
-    if (!resolved || resolved.toLowerCase() === host.toLowerCase())
+    if (!resolved || !isSafeSshHost(resolved))
+        return trimmed;
+    if (resolved.toLowerCase() === host.toLowerCase())
         return trimmed;
     if (verbose)
         console.log(`[verbose] Resolved SSH host alias ${host} -> ${resolved}`);
@@ -89,6 +112,13 @@ export function canonicalizeGitRemote(remote, verbose) {
     return `ssh://${user}${resolved}/${sshUrl[3]}`;
 }
 function resolveSshHostName(host, verbose) {
+    // Defense in depth: the only caller already checks, but this function is the
+    // spawn boundary and must not depend on callers getting it right.
+    if (!isSafeSshHost(host)) {
+        if (verbose)
+            console.log(`[verbose] Refusing ssh -G for option-shaped host: ${host}`);
+        return null;
+    }
     try {
         const out = execFileSync("ssh", ["-G", host], {
             encoding: "utf-8",
@@ -128,12 +158,17 @@ export function repoNameToGitRemoteCandidates(repoName) {
     if (trimmed.includes("://") || trimmed.includes("@")) {
         return [trimmed];
     }
+    /* eslint-disable-next-line security/detect-unsafe-regex -- Star height 2
+       (`+` inside `(…)*`), but the inner group is prefixed by `/`, which is not
+       in [\w.-]. There is no ambiguous overlap, so matching stays linear. The
+       input is a short `owner/repo` slug that already failed the "://" and "@"
+       checks above. */
     if (/^[\w.-]+\/[\w.-]+(\/[\w.-]+)*$/.test(trimmed)) {
         return [`https://github.com/${trimmed}`, `git@github.com:${trimmed}.git`];
     }
     return [];
 }
-export async function lookupProjectByRepoName(repoName, host, token, verbose) {
+export async function lookupProjectByRepoName(repoName, host, token, verbose, allowInsecureHttp = false) {
     const candidates = repoNameToGitRemoteCandidates(repoName);
     if (candidates.length === 0) {
         if (verbose)
@@ -141,7 +176,7 @@ export async function lookupProjectByRepoName(repoName, host, token, verbose) {
         return "not-found";
     }
     for (const candidate of candidates) {
-        const result = await lookupProjectByRemote(candidate, host, token, verbose);
+        const result = await lookupProjectByRemote(candidate, host, token, verbose, allowInsecureHttp);
         if (result === "not-found")
             continue;
         return result;
@@ -164,7 +199,7 @@ export async function enrichCommitProjectAttribution(payloads, options) {
         const repoName = payload.metadata?.repo_name;
         if (!repoName)
             continue;
-        const result = await lookupProjectByRepoName(repoName, options.host, options.token, options.verbose ?? false);
+        const result = await lookupProjectByRepoName(repoName, options.host, options.token, options.verbose ?? false, options.allowInsecureHttp === true);
         if (result && typeof result === "object" && "project_id" in result) {
             payload.project_id = result.project_id;
             if (options.verbose) {
@@ -173,7 +208,18 @@ export async function enrichCommitProjectAttribution(payloads, options) {
         }
     }
 }
-export async function lookupProjectByRemote(gitRemote, host, token, verbose) {
+export async function lookupProjectByRemote(gitRemote, host, token, verbose, allowInsecureHttp = false) {
+    const transportSecurity = evaluateTransportSecurity(host, {
+        allowInsecureHttp,
+        label: "DB90 project-lookup host",
+    });
+    if (!transportSecurity.ok) {
+        console.error(`Blocked project lookup — ${transportSecurity.error}`);
+        return null;
+    }
+    if (transportSecurity.warning) {
+        console.error(`Warning: ${transportSecurity.warning}`);
+    }
     const url = `${host.replace(/\/$/, "")}/api/v1/projects/lookup?git_remote=${encodeURIComponent(gitRemote)}`;
     try {
         const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });

package/dist/lib/repo-path-safety.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Normalize an untrusted repo-path candidate. Pure — never touches the
+ * filesystem, so it is safe to call on every payload in a sync.
+ *
+ * Returns an absolute, `..`-collapsed path, or null when the value cannot be a
+ * legitimate workspace path. Rejecting relative values is deliberate: `git -C`
+ * would resolve a relative path against *this* process's cwd, which has nothing
+ * to do with where the value came from. It also rejects Cursor's literal
+ * `"unknown"` placeholder for global hook events.
+ */
+export declare function normalizeRepoPathCandidate(value: string | undefined | null): string | null;
+/**
+ * True when `candidate` is `root` itself or lives beneath it.
+ *
+ * Compares with a trailing `sep` so `/repos/project-evil` is not treated as
+ * inside `/repos/project`, and resolves symlinks so a link inside the root
+ * cannot point out of it.
+ *
+ * When either side does not exist, `realpathSync` throws and the normalized
+ * paths are compared instead. That loses nothing — a path that does not exist
+ * cannot be a symlink, and `resolve()` has already collapsed `..` — and it keeps
+ * containment usable for scope filtering, which legitimately runs against
+ * payload paths naming directories this machine no longer has.
+ */
+export declare function isRepoPathWithinRoot(candidate: string, root: string): boolean;
+/**
+ * The last check before `git -C <path>` runs. Requires the value to resolve to a
+ * real directory: a missing path, a dangling symlink, or a regular file is not a
+ * workspace. (Cursor's `metadata.workspace` is often the `state.vscdb` file
+ * itself, which git would only error on anyway.)
+ *
+ * Returns the canonical real path so `git` runs against exactly what was
+ * checked, narrowing the window between the check and the spawn.
+ */
+export declare function safeGitRepoPath(value: string | undefined | null): string | null;

package/dist/lib/repo-path-safety.js

@@ -0,0 +1,102 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { isSafeSpawnPathArg } from "./spawn-arg-safety.js";
+/**
+ * Containment for untrusted filesystem paths that end up in `git -C <path>`.
+ *
+ * Every repo path this package resolves is untrusted text: Cursor's
+ * `workspace.json` `folder`, a composer's `workspaceIdentifier.uri.fsPath`, a
+ * hook's `workspace_roots[0]`, or a Claude transcript's `cwd`. None is validated
+ * by its producer — `fileUriToPath` (`readers/cursor.ts:189`) even passes a
+ * non-`file://` value straight through.
+ *
+ * `execFileSync` stops shell injection, but not `git -C ../../../elsewhere`: git
+ * would read that directory's `.git/config` and this package would ship the
+ * remote it found to the DB90 API. See DB90DV-547.
+ *
+ * Semantics are ported from `validatedRealPathWithinRoot`
+ * (`readers/cursor-sqlite.ts:23`), which already guards the Cursor SQLite
+ * reader the same way.
+ */
+function realPathOrNull(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Normalize an untrusted repo-path candidate. Pure — never touches the
+ * filesystem, so it is safe to call on every payload in a sync.
+ *
+ * Returns an absolute, `..`-collapsed path, or null when the value cannot be a
+ * legitimate workspace path. Rejecting relative values is deliberate: `git -C`
+ * would resolve a relative path against *this* process's cwd, which has nothing
+ * to do with where the value came from. It also rejects Cursor's literal
+ * `"unknown"` placeholder for global hook events.
+ */
+export function normalizeRepoPathCandidate(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    // Rejects empty, NUL-containing, and option-shaped values (DB90DV-546).
+    if (!isSafeSpawnPathArg(trimmed))
+        return null;
+    if (!isAbsolute(trimmed))
+        return null;
+    return resolve(trimmed);
+}
+/**
+ * True when `candidate` is `root` itself or lives beneath it.
+ *
+ * Compares with a trailing `sep` so `/repos/project-evil` is not treated as
+ * inside `/repos/project`, and resolves symlinks so a link inside the root
+ * cannot point out of it.
+ *
+ * When either side does not exist, `realpathSync` throws and the normalized
+ * paths are compared instead. That loses nothing — a path that does not exist
+ * cannot be a symlink, and `resolve()` has already collapsed `..` — and it keeps
+ * containment usable for scope filtering, which legitimately runs against
+ * payload paths naming directories this machine no longer has.
+ */
+export function isRepoPathWithinRoot(candidate, root) {
+    const normalizedCandidate = resolve(candidate);
+    const normalizedRoot = resolve(root);
+    const realCandidate = realPathOrNull(normalizedCandidate);
+    const realRoot = realPathOrNull(normalizedRoot);
+    // Compare like with like: mixing a realpath against a normalized path would
+    // false-negative on macOS, where /var is a symlink to /private/var.
+    const bothResolve = realCandidate !== null && realRoot !== null;
+    const left = bothResolve ? realCandidate : normalizedCandidate;
+    const right = bothResolve ? realRoot : normalizedRoot;
+    if (left === right)
+        return true;
+    const rootWithSep = right.endsWith(sep) ? right : `${right}${sep}`;
+    return left.startsWith(rootWithSep);
+}
+/**
+ * The last check before `git -C <path>` runs. Requires the value to resolve to a
+ * real directory: a missing path, a dangling symlink, or a regular file is not a
+ * workspace. (Cursor's `metadata.workspace` is often the `state.vscdb` file
+ * itself, which git would only error on anyway.)
+ *
+ * Returns the canonical real path so `git` runs against exactly what was
+ * checked, narrowing the window between the check and the spawn.
+ */
+export function safeGitRepoPath(value) {
+    const normalized = normalizeRepoPathCandidate(value);
+    if (normalized === null)
+        return null;
+    const real = realPathOrNull(normalized);
+    if (real === null)
+        return null;
+    try {
+        if (!statSync(real).isDirectory())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return real;
+}

package/dist/lib/spawn-arg-safety.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Guards for untrusted values that end up in the argv of a spawned process.
+ *
+ * `execFileSync` prevents *shell* injection but not *argv-option* injection: a
+ * value beginning with `-` is parsed by the child as a command-line option. Git
+ * remotes and workspace paths are untrusted text — they come from a repo the
+ * developer cloned, from Cursor's `workspace.json`, or from a Claude transcript
+ * — so every value derived from them must be checked before it reaches `git`
+ * or `ssh`. See DB90DV-546.
+ */
+/**
+ * True when `host` is safe to pass as an argv element to `ssh`. Accepts real
+ * hostnames, IPv4 literals, and `~/.ssh/config` host aliases.
+ */
+export declare function isSafeSshHost(host: string): boolean;
+/**
+ * True when `value` is safe to pass as a filesystem-path argv element (e.g.
+ * after `git -C`). Deliberately permissive about path *content* — real
+ * workspace paths contain spaces, dashes and drive letters. It only rejects
+ * what makes the child misread the value as an option, plus embedded NUL.
+ *
+ * This is an argv guard, not a containment check: verifying the path points
+ * somewhere legitimate is DB90DV-547.
+ */
+export declare function isSafeSpawnPathArg(value: string): boolean;

package/dist/lib/spawn-arg-safety.js

@@ -0,0 +1,49 @@
+/**
+ * Guards for untrusted values that end up in the argv of a spawned process.
+ *
+ * `execFileSync` prevents *shell* injection but not *argv-option* injection: a
+ * value beginning with `-` is parsed by the child as a command-line option. Git
+ * remotes and workspace paths are untrusted text — they come from a repo the
+ * developer cloned, from Cursor's `workspace.json`, or from a Claude transcript
+ * — so every value derived from them must be checked before it reaches `git`
+ * or `ssh`. See DB90DV-546.
+ */
+/** Longest legal DNS name (253) with headroom for an ssh_config alias. */
+const MAX_HOST_LENGTH = 255;
+/**
+ * Dot-separated labels of alphanumerics, `-` and `_`. A label may not start or
+ * end with `-`, which is what blocks option injection (`-oProxyCommand=…`).
+ * Whitespace, `=`, quotes, backslashes, newlines and NUL are all excluded.
+ * Underscores are allowed because `~/.ssh/config` aliases commonly use them.
+ * IPv6 literals are not covered — the SCP/`ssh://` host capture in
+ * `project-resolver.ts` cannot produce one, since it excludes `:`.
+ */
+const HOST_LABEL = "[A-Za-z0-9_](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?";
+const HOST_PATTERN = new RegExp(`^${HOST_LABEL}(?:\\.${HOST_LABEL})*$`);
+/**
+ * True when `host` is safe to pass as an argv element to `ssh`. Accepts real
+ * hostnames, IPv4 literals, and `~/.ssh/config` host aliases.
+ */
+export function isSafeSshHost(host) {
+    if (host.length === 0 || host.length > MAX_HOST_LENGTH)
+        return false;
+    return HOST_PATTERN.test(host);
+}
+/**
+ * True when `value` is safe to pass as a filesystem-path argv element (e.g.
+ * after `git -C`). Deliberately permissive about path *content* — real
+ * workspace paths contain spaces, dashes and drive letters. It only rejects
+ * what makes the child misread the value as an option, plus embedded NUL.
+ *
+ * This is an argv guard, not a containment check: verifying the path points
+ * somewhere legitimate is DB90DV-547.
+ */
+export function isSafeSpawnPathArg(value) {
+    if (value.length === 0)
+        return false;
+    if (value.startsWith("-"))
+        return false;
+    if (value.includes("\0"))
+        return false;
+    return true;
+}