@agent-finops/core 0.5.5 → 0.5.6

package/dist/planMath.js

@@ -11,10 +11,9 @@ const localLogCostType = "local_agent_logs";
  * from local agent logs participate (billing-API records already have real
  * prices and a real plan behind them).
  *
- * When `detectedPlans` carries a locally detected plan (or --plan override)
- * for an agent, the check speaks in facts ("you're on Claude Max 5x") instead
- * of guesses ("Max 20x likely covers this") — and warns when projected usage
- * exceeds what the detected tier typically covers.
+ * When `detectedPlans` carries a locally detected plan label (or --plan
+ * override), the result identifies that provenance and keeps comparison math
+ * separate from provider-reported limits.
  */
 export function computePlanChecks(records, detectedPlans = []) {
     const localRecords = records.filter((record) => record.providerCostType === localLogCostType &&
@@ -49,35 +48,36 @@ export function computePlanChecks(records, detectedPlans = []) {
         let upgradeHint;
         let effectiveSavings;
         if (detectedKnown) {
-            // FACT mode: we know the user's actual plan from local agent config.
+            // The label comes from local metadata or an explicit override. It is not
+            // independently verified against the provider account.
             valueMultiple = Math.round((monthly / detectedKnown.monthlyUsd) * 10) / 10;
             const savingsVsApi = roundMoney(monthly - detectedKnown.monthlyUsd);
             effectiveSavings = savingsVsApi > 0 ? savingsVsApi : undefined;
             headline =
-                `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — you're on ${detectedKnown.name} ` +
-                    `($${detectedKnown.monthlyUsd}/mo, detected locally): ~${valueMultiple}× the plan price in usage` +
-                    (effectiveSavings ? `, ~$${effectiveSavings.toFixed(2)}/mo cheaper than paying per token.` : `.`);
+                `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — compared with ${detectedKnown.name} ` +
+                    `($${detectedKnown.monthlyUsd}/mo; label detected locally): ~${valueMultiple}× the plan price in API-equivalent usage` +
+                    (effectiveSavings ? `, a ~$${effectiveSavings.toFixed(2)}/mo value difference to investigate.` : `.`);
             if (monthly > detectedKnown.coversUpToUsd) {
                 const nextTier = subscriptionPlans.find((plan) => plan.agent === agent && plan.coversUpToUsd > detectedKnown.coversUpToUsd);
                 // A local limit signal upgrades "might hit limits" to hard evidence.
                 const evidence = detected?.limitSignal
-                    ? `your local config shows ${detected.limitSignal} — you ARE hitting your plan's limits`
-                    : `if you're hitting rate limits`;
+                    ? `local metadata reports ${detected.limitSignal}`
+                    : `if the provider reports active rate limits`;
                 upgradeHint = nextTier
-                    ? `usage runs past what ${detectedKnown.name} typically covers (~$${detectedKnown.coversUpToUsd}/mo); ${evidence}: ${nextTier.name} ($${nextTier.monthlyUsd}/mo) is the next tier; trimming context (below) buys headroom without upgrading.`
-                    : `usage runs past what ${detectedKnown.name} typically covers (~$${detectedKnown.coversUpToUsd}/mo) — trimming context (below) is the main headroom lever.`;
+                    ? `API-equivalent projection exceeds the rough ${detectedKnown.name} comparison threshold (~$${detectedKnown.coversUpToUsd}/mo); ${evidence}. ${nextTier.name} ($${nextTier.monthlyUsd}/mo) is the next listed tier, but verify account limits before changing plans; trimming context (below) may buy headroom.`
+                    : `API-equivalent projection exceeds the rough ${detectedKnown.name} comparison threshold (~$${detectedKnown.coversUpToUsd}/mo); verify account limits before changing plans. Trimming context (below) may buy headroom.`;
             }
             else if (detected?.limitSignal) {
-                upgradeHint = `your local config shows ${detected.limitSignal} — you're hitting your plan's limits; trimming context (below) buys headroom without upgrading.`;
+                upgradeHint = `local metadata reports ${detected.limitSignal}; verify the live provider window. Trimming context (below) may buy headroom.`;
             }
         }
         else if (detected) {
             // Detected a plan we can't price (e.g. an unrecognized tier): state the
             // fact, then fall back to suggestion math without pretending certainty.
             headline =
-                `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — you're on ${detected.planLabel} ` +
-                    `(detected locally; price not in our table)` +
-                    (suggested ? `; closest known plan: ${suggested.name} ($${suggested.monthlyUsd}/mo).` : `.`);
+                `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — compared with ${detected.planLabel} ` +
+                    `(label detected locally; price not in our table)` +
+                    (suggested ? `; reference listed plan: ${suggested.name} ($${suggested.monthlyUsd}/mo).` : `.`);
         }
         else {
             const covered = suggested && typeof savings === "number" && savings > 0;
@@ -87,10 +87,10 @@ export function computePlanChecks(records, detectedPlans = []) {
                 headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}).`;
             }
             else if (covered) {
-                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — ${suggested.name} ($${suggested.monthlyUsd}/mo) likely covers this. You're getting ~${valueMultiple}× the plan price in usage, ~$${savings.toFixed(2)}/mo cheaper than paying per token.`;
+                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — ${suggested.name} is a $${suggested.monthlyUsd}/mo reference point. That is ~${valueMultiple}× the plan price in API-equivalent usage, a ~$${savings.toFixed(2)}/mo value difference to investigate; it does not prove plan coverage.`;
             }
             else {
-                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — within ${suggested.name} ($${suggested.monthlyUsd}/mo); pay-as-you-go API could be cheaper if you drop the subscription.`;
+                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — below the $${suggested.monthlyUsd}/mo price of ${suggested.name}; compare account benefits and provider-reported charges before changing plans.`;
             }
         }
         checks.push({

package/dist/providerConnectors.d.ts

@@ -12,12 +12,20 @@ type ProviderResponse = {
 export type ProviderQaPagination = {
     label: string;
     pagesFetched: number;
-    stoppedBecause: "complete" | "missing_cursor" | "max_pages" | "fetch_error";
+    stoppedBecause: "complete" | "missing_cursor" | "max_pages" | "max_range_days" | "fetch_error" | "unsafe_next_link";
     maxPages: number;
     limitPerPage?: number;
     /** Present when stoppedBecause is "fetch_error": the sanitized reason the fetch stopped early. */
     note?: string;
 };
+export type ProviderCoverageStatus = "complete" | "partial";
+export type ProviderFinancialSummary = {
+    providerReportedBilledUsd: number | null;
+    apiEquivalentEstimatedUsd: number | null;
+    providerEstimatedUsd: number | null;
+    headlineUsd: number | null;
+    headlineBasis: "provider_reported_billed_cost" | "api_equivalent_estimate" | "provider_estimated_cost" | "unavailable";
+};
 export type ProviderQaRateLimit = {
     label: string;
     remainingRequests?: number;
@@ -30,6 +38,7 @@ export type ProviderQaDriftIssue = {
 };
 export type ProviderQaSummary = {
     provider: string;
+    coverage?: ProviderCoverageStatus;
     requestedEndpoints: string[];
     pagination: ProviderQaPagination[];
     rateLimits: ProviderQaRateLimit[];
@@ -54,6 +63,8 @@ export type ProviderConnectorResult = {
     source: ApprovedSource;
     records: UsageRecord[];
     fetchedAt: string;
+    coverage: ProviderCoverageStatus;
+    financials: ProviderFinancialSummary;
     completeness: "verified" | "estimated" | "detected_unverified" | "missing";
     qa: ProviderQaSummary;
 };
@@ -86,6 +97,13 @@ export declare function normalizeAnthropicCostResponse(response: unknown, option
 export declare function normalizeGitHubCopilotMetricsResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
 export declare function normalizeCursorSpendResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
 export declare function fetchProviderUsageRecords(input: ProviderConnectorInput): Promise<ProviderConnectorResult>;
+export declare function summarizeProviderFinancials(records: UsageRecord[]): ProviderFinancialSummary;
+/**
+ * Keep evidence records available to callers, but never add estimates to a
+ * provider's official billed total. This selection is intended for aggregate
+ * spend headlines; callers should retain the original records for attribution.
+ */
+export declare function selectProviderFinancialHeadlineRecords(records: UsageRecord[]): UsageRecord[];
 export declare function createProviderConnection(input: CreateProviderConnectionInput): ApprovedSource;
 export declare function resolveTokenReference(reference: string, env?: Record<string, string | undefined>): string;
 export {};

package/dist/providerConnectors.js

@@ -387,10 +387,20 @@ async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label)
             rateLimits.push(response.rateLimit);
         responseDrift.push(...detectResponseDrift(page, provider, label));
         const nextPage = nextPageFromPayload(page);
-        const nextLink = nextUrlFromHeaders(response.headers);
-        const hasMore = isRecord(page) && (page.has_more === true || page.hasMore === true || Boolean(nextPage) || Boolean(nextLink));
-        if (nextLink) {
-            nextUrl = nextLink;
+        const rawNextLink = nextUrlFromHeaders(response.headers);
+        const safeNextLink = rawNextLink ? validatePaginationUrl(initialUrl, rawNextLink) : undefined;
+        const hasMore = isRecord(page) && (page.has_more === true || page.hasMore === true || Boolean(nextPage) || Boolean(rawNextLink));
+        if (rawNextLink && !safeNextLink) {
+            stoppedBecause = "unsafe_next_link";
+            responseDrift.push({
+                label,
+                field: "headers.link",
+                issue: "rejected pagination URL because it was not HTTPS and same-origin with the provider endpoint"
+            });
+            nextUrl = undefined;
+        }
+        else if (safeNextLink) {
+            nextUrl = safeNextLink;
         }
         else if (hasMore && nextPage) {
             nextUrl = appendPageCursor(initialUrl, nextPage);
@@ -412,11 +422,25 @@ async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label)
         responseDrift
     };
 }
+function validatePaginationUrl(initialUrl, candidate) {
+    try {
+        const initial = new URL(initialUrl);
+        const next = new URL(candidate, initial);
+        if (initial.protocol !== "https:" || next.protocol !== "https:" || next.origin !== initial.origin) {
+            return undefined;
+        }
+        return next.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
 async function fetchDateRangeJson(fetcher, buildUrl, startTime, endTime, request, provider, label) {
     const results = [];
     const daySeconds = 24 * 60 * 60;
     const finalTime = endTime ?? startTime;
-    for (let cursor = startTime, count = 0; cursor <= finalTime && count < 370; cursor += daySeconds, count += 1) {
+    const maxRangeDays = 370;
+    for (let cursor = startTime, count = 0; cursor <= finalTime && count < maxRangeDays; cursor += daySeconds, count += 1) {
         try {
             results.push(await fetchPaginatedJson(fetcher, buildUrl(cursor), request, provider, label));
         }
@@ -441,6 +465,21 @@ async function fetchDateRangeJson(fetcher, buildUrl, startTime, endTime, request
             break;
         }
     }
+    const lastCoveredTime = startTime + (maxRangeDays - 1) * daySeconds;
+    if (finalTime > lastCoveredTime && results.every((result) => result.pagination.stoppedBecause !== "fetch_error")) {
+        results.push({
+            pages: [],
+            pagination: {
+                label,
+                pagesFetched: 0,
+                stoppedBecause: "max_range_days",
+                maxPages: 50,
+                note: `Requested range exceeds the ${maxRangeDays}-day connector limit; narrow the range or run multiple syncs.`
+            },
+            rateLimits: [],
+            responseDrift: []
+        });
+    }
     return results;
 }
 /** Retries per request on 429/5xx before giving up (initial try + retries). */
@@ -519,6 +558,8 @@ function headerNumber(headers, name) {
     if (!headers)
         return undefined;
     const value = hasHeaderGetter(headers) ? headers.get(name) : headers[name] ?? headers[name.toLowerCase()];
+    if (value === null || value === undefined || value.trim() === "")
+        return undefined;
     const numeric = Number(value);
     return Number.isFinite(numeric) ? numeric : undefined;
 }
@@ -554,13 +595,13 @@ function knownProviderFields(provider, label) {
     // as drift, burying real drift signals in thousands of false positives.
     const common = ["data", "data[]", "has_more", "hasMore", "next_page", "nextPage", "object", "links", "links.next"];
     if (provider === "openai" && label.includes("costs")) {
-        return new Set([...common, "data[].object", "data[].start_time", "data[].end_time", "data[].results", "data[].results[]", "data[].results[].object", "data[].results[].amount", "data[].results[].amount.value", "data[].results[].amount.currency", "data[].results[].line_item", "data[].results[].project_id", "data[].results[].api_key_id", "data[].results[].quantity"]);
+        return new Set([...common, "data[].object", "data[].start_time", "data[].start_time_iso", "data[].end_time", "data[].end_time_iso", "data[].results", "data[].results[]", "data[].results[].object", "data[].results[].amount", "data[].results[].amount.value", "data[].results[].amount.currency", "data[].results[].line_item", "data[].results[].organization_id", "data[].results[].organization_name", "data[].results[].project_id", "data[].results[].project_name", "data[].results[].user_id", "data[].results[].user_email", "data[].results[].api_key_id", "data[].results[].quantity"]);
     }
     if (provider === "openai" && label.includes("usage")) {
-        return new Set([...common, "data[].object", "data[].start_time", "data[].end_time", "data[].results", "data[].results[]", "data[].results[].object", "data[].results[].input_tokens", "data[].results[].output_tokens", "data[].results[].input_cached_tokens", "data[].results[].input_audio_tokens", "data[].results[].output_audio_tokens", "data[].results[].num_model_requests", "data[].results[].project_id", "data[].results[].user_id", "data[].results[].api_key_id", "data[].results[].model"]);
+        return new Set([...common, "data[].object", "data[].start_time", "data[].start_time_iso", "data[].end_time", "data[].end_time_iso", "data[].results", "data[].results[]", "data[].results[].object", "data[].results[].input_tokens", "data[].results[].input_uncached_tokens", "data[].results[].input_cache_write_tokens", "data[].results[].input_cached_tokens", "data[].results[].input_text_tokens", "data[].results[].input_image_tokens", "data[].results[].input_audio_tokens", "data[].results[].input_cached_text_tokens", "data[].results[].input_cached_image_tokens", "data[].results[].input_cached_audio_tokens", "data[].results[].output_tokens", "data[].results[].output_text_tokens", "data[].results[].output_image_tokens", "data[].results[].output_audio_tokens", "data[].results[].num_model_requests", "data[].results[].project_id", "data[].results[].user_id", "data[].results[].api_key_id", "data[].results[].model", "data[].results[].batch", "data[].results[].service_tier"]);
     }
     if (provider === "anthropic" && label.toLowerCase().includes("cost")) {
-        return new Set([...common, "data[].starting_at", "data[].ending_at", "data[].results", "data[].results[]", "data[].results[].amount", "data[].results[].currency", "data[].results[].cost_type", "data[].results[].description", "data[].results[].model", "data[].results[].workspace_id", "data[].results[].token_type", "data[].results[].service_tier", "data[].results[].context_window"]);
+        return new Set([...common, "data[].starting_at", "data[].ending_at", "data[].results", "data[].results[]", "data[].results[].amount", "data[].results[].currency", "data[].results[].cost_type", "data[].results[].description", "data[].results[].model", "data[].results[].workspace_id", "data[].results[].token_type", "data[].results[].service_tier", "data[].results[].context_window", "data[].results[].inference_geo"]);
     }
     if (provider === "anthropic" && label.toLowerCase().includes("claude code")) {
         return new Set([...common, "data[].date", "data[].actor", "data[].actor.email_address", "data[].actor.api_key_name", "data[].actor.id", "data[].actor.type", "data[].organization_id", "data[].customer_type", "data[].terminal_type", "data[].subscription_type", "data[].core_metrics", "data[].core_metrics.num_sessions", "data[].core_metrics.lines_of_code", "data[].core_metrics.lines_of_code.added", "data[].core_metrics.lines_of_code.removed", "data[].core_metrics.commits_by_claude_code", "data[].core_metrics.pull_requests_by_claude_code", "data[].model_breakdown", "data[].model_breakdown[]", "data[].model_breakdown[].model", "data[].model_breakdown[].tokens", "data[].model_breakdown[].tokens.input", "data[].model_breakdown[].tokens.output", "data[].model_breakdown[].tokens.cache_read", "data[].model_breakdown[].tokens.cache_creation", "data[].model_breakdown[].estimated_cost", "data[].model_breakdown[].estimated_cost.currency", "data[].model_breakdown[].estimated_cost.amount", "data[].tool_actions", "data[].tool_actions[]"]);
@@ -579,6 +620,7 @@ function knownProviderFields(provider, label) {
 function qaSummary(provider, fetches) {
     return {
         provider,
+        coverage: fetches.every((fetchResult) => fetchResult.pagination.stoppedBecause === "complete") ? "complete" : "partial",
         requestedEndpoints: Array.from(new Set(fetches.map((fetchResult) => fetchResult.pagination.label))),
         pagination: fetches.map((fetchResult) => fetchResult.pagination),
         rateLimits: fetches.flatMap((fetchResult) => fetchResult.rateLimits),
@@ -642,32 +684,68 @@ function sanitizeProviderMessage(message) {
     // One redaction implementation for the whole product (discovery.ts owns it).
     return redactSecrets(message).replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]").replace(/gh[pousr]_[A-Za-z0-9_]+/g, "[REDACTED]");
 }
+export function summarizeProviderFinancials(records) {
+    const providerReportedBilledUsd = sumAmounts(records.filter((record) => record.costConfidence === "verified"));
+    const apiEquivalentEstimatedUsd = sumAmounts(records.filter((record) => record.providerCostType === "anthropic_claude_code_usage" && record.costConfidence === "estimated"));
+    const providerEstimatedUsd = sumAmounts(records.filter((record) => record.costConfidence === "estimated" && record.providerCostType !== "anthropic_claude_code_usage"));
+    if (providerReportedBilledUsd !== null) {
+        return { providerReportedBilledUsd, apiEquivalentEstimatedUsd, providerEstimatedUsd, headlineUsd: providerReportedBilledUsd, headlineBasis: "provider_reported_billed_cost" };
+    }
+    if (apiEquivalentEstimatedUsd !== null) {
+        return { providerReportedBilledUsd, apiEquivalentEstimatedUsd, providerEstimatedUsd, headlineUsd: apiEquivalentEstimatedUsd, headlineBasis: "api_equivalent_estimate" };
+    }
+    if (providerEstimatedUsd !== null) {
+        return { providerReportedBilledUsd, apiEquivalentEstimatedUsd, providerEstimatedUsd, headlineUsd: providerEstimatedUsd, headlineBasis: "provider_estimated_cost" };
+    }
+    return { providerReportedBilledUsd, apiEquivalentEstimatedUsd, providerEstimatedUsd, headlineUsd: null, headlineBasis: "unavailable" };
+}
 /**
- * Result-level completeness is DERIVED from record-level confidence, never
- * hardcoded: the label on the whole pull is the weakest confidence among the
- * records that actually carry dollars (worst-wins, matching analyze.ts).
- * Copilot seats and Cursor spend are estimated, so their results say so.
+ * Keep evidence records available to callers, but never add estimates to a
+ * provider's official billed total. This selection is intended for aggregate
+ * spend headlines; callers should retain the original records for attribution.
  */
-function completenessFromRecords(records) {
-    const rank = { verified: 0, estimated: 1, detected_unverified: 2, missing: 3 };
-    const costBearing = records.filter((record) => typeof record.amountUsd === "number");
-    if (costBearing.length === 0) {
-        return "missing";
-    }
-    return costBearing
-        .map((record) => record.costConfidence)
-        .reduce((worst, current) => (rank[current] > rank[worst] ? current : worst));
+export function selectProviderFinancialHeadlineRecords(records) {
+    const byProvider = new Map();
+    for (const record of records) {
+        const providerRecords = byProvider.get(record.source.provider) ?? [];
+        providerRecords.push(record);
+        byProvider.set(record.source.provider, providerRecords);
+    }
+    return Array.from(byProvider.values()).flatMap((providerRecords) => {
+        const hasProviderBilledCost = providerRecords.some((record) => record.costConfidence === "verified" && typeof record.amountUsd === "number");
+        return hasProviderBilledCost
+            ? providerRecords.filter((record) => record.costConfidence === "verified" || record.amountUsd === null)
+            : providerRecords;
+    });
+}
+function sumAmounts(records) {
+    const amounts = records
+        .map((record) => record.amountUsd)
+        .filter((amount) => typeof amount === "number");
+    return amounts.length > 0 ? amounts.reduce((sum, amount) => sum + amount, 0) : null;
 }
 function providerResult(provider, sourceId, authReference, records, qa) {
-    const totalUsd = records.reduce((sum, record) => sum + (record.amountUsd ?? 0), 0);
-    const completeness = completenessFromRecords(records);
+    const resolvedQa = qa ?? qaSummary(provider, []);
+    const coverage = resolvedQa.coverage
+        ?? (resolvedQa.pagination.every((pagination) => pagination.stoppedBecause === "complete") ? "complete" : "partial");
+    const financials = summarizeProviderFinancials(records);
+    const headlineConfidence = financials.headlineBasis === "provider_reported_billed_cost"
+        ? "verified"
+        : financials.headlineBasis === "unavailable"
+            ? "missing"
+            : "estimated";
+    const completeness = coverage === "partial" && headlineConfidence !== "missing"
+        ? "detected_unverified"
+        : headlineConfidence;
     return {
         provider,
-        source: createProviderConnection({ provider, sourceId, authReference, verifiedRecordCount: records.length, totalUsd, completeness }),
+        source: createProviderConnection({ provider, sourceId, authReference, verifiedRecordCount: records.length, totalUsd: financials.headlineUsd ?? 0, completeness }),
         records,
         fetchedAt: new Date().toISOString(),
+        coverage,
+        financials,
         completeness,
-        qa: qa ?? qaSummary(provider, [])
+        qa: resolvedQa
     };
 }
 export function createProviderConnection(input) {
@@ -752,7 +830,9 @@ function defaultTokenResolver(reference) {
     return resolveTokenReference(reference);
 }
 async function defaultFetcher(url, init) {
-    return fetch(url, init);
+    // Never let the runtime automatically replay provider credentials to a
+    // redirect target. Provider endpoint changes must be explicit code changes.
+    return fetch(url, { ...init, redirect: "manual" });
 }
 function parseMinorUsd(value) {
     const numeric = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;

package/dist/scanGuard.d.ts

@@ -2,7 +2,42 @@ export declare class UnsafeScanRootError extends Error {
     readonly rootPath: string;
     constructor(rootPath: string, reason: string);
 }
+export declare class UnsafeStateDirectoryError extends Error {
+    readonly statePath: string;
+    constructor(statePath: string, reason: string);
+}
+export declare class UnsafeStateFileError extends Error {
+    readonly filePath: string;
+    constructor(filePath: string, reason: string);
+}
 export declare function unsafeScanRootReason(rootPath: string, home?: string): string | undefined;
 /** Throws a typed error when the root is unsafe; callers map it to their UX. */
 export declare function assertSafeScanRoot(rootPath: string, home?: string): void;
+/**
+ * Resolves an approved root through the filesystem before applying the broad-
+ * root policy. This prevents a harmless-looking symlink such as
+ * `/tmp/project` from approving a scan of `$HOME` or a system directory.
+ * Callers should persist and use the returned canonical path.
+ */
+export declare function resolveSafeScanRoot(rootPath: string, home?: string): Promise<string>;
+/**
+ * Returns a validated local state directory, creating it only when requested.
+ * The state path must be a real directory directly under the canonical scan
+ * root; symbolic links are refused for both reads and writes.
+ */
+export declare function resolveSafeStateDirectory(rootPath: string, options?: {
+    create?: boolean;
+}): Promise<string>;
+/**
+ * Read one regular child file without following a symbolic link. State can sit
+ * inside a cloned repository, so validating only the parent directory is not
+ * enough: a committed child symlink must never expose an arbitrary local file.
+ */
+export declare function readSafeStateText(stateDir: string, fileName: string): Promise<string>;
+/**
+ * Atomically replace one regular child file. The temporary file is created
+ * exclusively with mode 0600, and rename replaces a last-moment symlink
+ * itself rather than writing through to its target.
+ */
+export declare function writeSafeStateText(stateDir: string, fileName: string, contents: string): Promise<void>;
 //# sourceMappingURL=scanGuard.d.ts.map

package/dist/scanGuard.js

@@ -1,5 +1,8 @@
 import { homedir } from "node:os";
-import { resolve, sep } from "node:path";
+import { constants, realpathSync } from "node:fs";
+import { chmod, lstat, mkdir, open, realpath, rename, stat, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename, join, resolve, sep } from "node:path";
 /**
  * Shared unsafe-scan-root policy for EVERY scan entrypoint (CLI `scan`, MCP
  * `scan_ai_spend`, and any future surface). Scanning the home directory, the
@@ -34,19 +37,39 @@ export class UnsafeScanRootError extends Error {
         this.rootPath = rootPath;
     }
 }
+export class UnsafeStateDirectoryError extends Error {
+    statePath;
+    constructor(statePath, reason) {
+        super(`Refusing to use ${statePath}: ${reason}. Remove the link or choose another approved folder.`);
+        this.name = "UnsafeStateDirectoryError";
+        this.statePath = statePath;
+    }
+}
+export class UnsafeStateFileError extends Error {
+    filePath;
+    constructor(filePath, reason) {
+        super(`Refusing to use ${filePath}: ${reason}. Recreate the local aibill state instead of following repository-provided links.`);
+        this.name = "UnsafeStateFileError";
+        this.filePath = filePath;
+    }
+}
 export function unsafeScanRootReason(rootPath, home = homedir()) {
-    const resolved = resolve(rootPath);
-    const resolvedHome = resolve(home);
-    if (resolved === "/" || /^[A-Za-z]:[\\/]?$/.test(resolved)) {
+    const requested = resolve(rootPath);
+    const resolved = bestEffortRealpathSync(requested);
+    const requestedHome = resolve(home);
+    const resolvedHome = bestEffortRealpathSync(requestedHome);
+    const rootCandidates = new Set([requested, resolved]);
+    const homeCandidates = new Set([requestedHome, resolvedHome]);
+    if (Array.from(rootCandidates).some((candidate) => candidate === "/" || /^[A-Za-z]:[\\/]?$/.test(candidate))) {
         return "the filesystem root is too broad for approved-source scanning";
     }
-    if (resolved === resolvedHome) {
+    if (Array.from(rootCandidates).some((candidate) => homeCandidates.has(candidate))) {
         return "the home directory is too broad for approved-source scanning";
     }
-    if (isAncestorPath(resolved, resolvedHome)) {
+    if (Array.from(rootCandidates).some((candidate) => Array.from(homeCandidates).some((candidateHome) => isAncestorPath(candidate, candidateHome)))) {
         return "this directory contains your home directory and is too broad for approved-source scanning";
     }
-    if (systemRootDirectories.has(resolved)) {
+    if (Array.from(rootCandidates).some((candidate) => systemRootDirectories.has(candidate))) {
         return "system directories are not valid approved-source scan targets";
     }
     return undefined;
@@ -55,8 +78,173 @@ export function unsafeScanRootReason(rootPath, home = homedir()) {
 export function assertSafeScanRoot(rootPath, home = homedir()) {
     const reason = unsafeScanRootReason(rootPath, home);
     if (reason) {
-        throw new UnsafeScanRootError(resolve(rootPath), reason);
+        throw new UnsafeScanRootError(bestEffortRealpathSync(resolve(rootPath)), reason);
+    }
+}
+/**
+ * Resolves an approved root through the filesystem before applying the broad-
+ * root policy. This prevents a harmless-looking symlink such as
+ * `/tmp/project` from approving a scan of `$HOME` or a system directory.
+ * Callers should persist and use the returned canonical path.
+ */
+export async function resolveSafeScanRoot(rootPath, home = homedir()) {
+    const requested = resolve(rootPath);
+    let canonicalRoot;
+    try {
+        canonicalRoot = await realpath(requested);
+    }
+    catch {
+        throw new UnsafeScanRootError(requested, "the approved scan root does not resolve to an existing directory");
+    }
+    let canonicalHome = resolve(home);
+    try {
+        canonicalHome = await realpath(canonicalHome);
+    }
+    catch {
+        // A synthetic/nonexistent home is useful in tests. The lexical path still
+        // preserves the same policy when there is nothing to canonicalize.
+    }
+    const reason = unsafeScanRootReason(canonicalRoot, canonicalHome);
+    if (reason) {
+        throw new UnsafeScanRootError(canonicalRoot, reason);
+    }
+    const rootInfo = await stat(canonicalRoot);
+    if (!rootInfo.isDirectory()) {
+        throw new UnsafeScanRootError(canonicalRoot, "the approved scan root is not a directory");
+    }
+    return canonicalRoot;
+}
+/**
+ * Returns a validated local state directory, creating it only when requested.
+ * The state path must be a real directory directly under the canonical scan
+ * root; symbolic links are refused for both reads and writes.
+ */
+export async function resolveSafeStateDirectory(rootPath, options = {}) {
+    const canonicalRoot = await resolveSafeScanRoot(rootPath);
+    const statePath = join(canonicalRoot, ".ai-spend-agent");
+    let stateInfo = await lstat(statePath).catch((error) => {
+        if (isNodeError(error, "ENOENT"))
+            return undefined;
+        throw error;
+    });
+    if (!stateInfo && options.create) {
+        try {
+            await mkdir(statePath, { mode: 0o700 });
+        }
+        catch (error) {
+            // A concurrent creator is safe only after the same lstat checks below.
+            if (!isNodeError(error, "EEXIST"))
+                throw error;
+        }
+        stateInfo = await lstat(statePath);
+    }
+    if (!stateInfo) {
+        const error = new Error(`State directory does not exist: ${statePath}`);
+        error.code = "ENOENT";
+        throw error;
+    }
+    if (stateInfo.isSymbolicLink()) {
+        throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent is a symbolic link");
+    }
+    if (!stateInfo.isDirectory()) {
+        throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent is not a directory");
+    }
+    const canonicalState = await realpath(statePath);
+    if (canonicalState !== statePath) {
+        throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent does not resolve directly inside the approved root");
     }
+    if (options.create) {
+        await chmod(statePath, 0o700);
+    }
+    return statePath;
+}
+/**
+ * Read one regular child file without following a symbolic link. State can sit
+ * inside a cloned repository, so validating only the parent directory is not
+ * enough: a committed child symlink must never expose an arbitrary local file.
+ */
+export async function readSafeStateText(stateDir, fileName) {
+    const filePath = await resolveSafeStateChild(stateDir, fileName, false);
+    let handle;
+    try {
+        handle = await open(filePath, constants.O_RDONLY | noFollowFlag());
+        const info = await handle.stat();
+        if (!info.isFile()) {
+            throw new UnsafeStateFileError(filePath, "the state entry is not a regular file");
+        }
+        return await handle.readFile("utf8");
+    }
+    catch (error) {
+        if (isNodeError(error, "ELOOP")) {
+            throw new UnsafeStateFileError(filePath, "the state entry is a symbolic link");
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/**
+ * Atomically replace one regular child file. The temporary file is created
+ * exclusively with mode 0600, and rename replaces a last-moment symlink
+ * itself rather than writing through to its target.
+ */
+export async function writeSafeStateText(stateDir, fileName, contents) {
+    const filePath = await resolveSafeStateChild(stateDir, fileName, true);
+    const temporaryName = `.${fileName}.${process.pid}.${randomUUID()}.tmp`;
+    const temporaryPath = join(stateDir, temporaryName);
+    let handle;
+    try {
+        handle = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), 0o600);
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporaryPath, filePath);
+        await chmod(filePath, 0o600);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+async function resolveSafeStateChild(stateDir, fileName, allowMissing) {
+    if (!fileName || basename(fileName) !== fileName || fileName === "." || fileName === "..") {
+        throw new UnsafeStateFileError(join(stateDir, fileName), "state filenames must be one direct child name");
+    }
+    const requestedState = resolve(stateDir);
+    const stateInfo = await lstat(requestedState);
+    if (stateInfo.isSymbolicLink() || !stateInfo.isDirectory()) {
+        throw new UnsafeStateDirectoryError(requestedState, "the state path is not a real directory");
+    }
+    const filePath = join(requestedState, fileName);
+    const childInfo = await lstat(filePath).catch((error) => {
+        if (allowMissing && isNodeError(error, "ENOENT"))
+            return undefined;
+        throw error;
+    });
+    if (childInfo?.isSymbolicLink()) {
+        throw new UnsafeStateFileError(filePath, "the state entry is a symbolic link");
+    }
+    if (childInfo && !childInfo.isFile()) {
+        throw new UnsafeStateFileError(filePath, "the state entry is not a regular file");
+    }
+    return filePath;
+}
+function noFollowFlag() {
+    return typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+}
+function bestEffortRealpathSync(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function isNodeError(error, code) {
+    return error instanceof Error && error.code === code;
 }
 function isAncestorPath(candidateAncestor, path) {
     const normalizedAncestor = candidateAncestor.endsWith(sep) ? candidateAncestor : candidateAncestor + sep;