fullstackgtm 0.48.0 → 0.49.0

package/dist/cli/market.js

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createFilePlanStore } from "../planStore.js";
-import { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, loadCaptureTexts, loadMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans } from "../market.js";
+import { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, loadCaptureTexts, loadMarketConfig, observationId, starterMarketConfig, validateObservationSet, verifyEvidenceSpans } from "../market.js";
 import { assessAxes, axesReportToText } from "../marketAxes.js";
 import { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown } from "../marketOverlay.js";
 import { computeScaleIndex, scaleReportToText } from "../marketScale.js";
@@ -24,6 +24,7 @@ import { unknownSubcommandError } from "./suggest.js";
  */
 const MARKET_SUBCOMMANDS = [
     "init", "capture", "classify", "worksheet", "observe", "fronts", "axes", "overlay", "scale", "report", "refresh",
+    "schema", "hints", "observe-template", "review",
 ];
 export async function marketCommand(args) {
     const [subcommand, ...rest] = args;
@@ -35,9 +36,13 @@ export async function marketCommand(args) {
 market init --category <name> [--out <path>]   write a starter market.config.json
 market init --category <name> --auto --vendor <url> [--vendor <url>...] [--anchor <url>] [--max-claims n]
                                                LLM-propose vendors + claim taxonomy from seed pages (needs an API key)
+market schema                                  print exact MarketConfig + ObservationSet shapes and a tiny example
 market capture [--config <path>] [--run <label>]
 market classify [--run <label>] [--capture-run <label>] [--vendor <id>] [--model m] [--out <path>]
 market worksheet --vendor <id> [--capture-run <label>] [--out <path>]
+market hints [--vendor <id>] [--capture-run <label>] [--json]
+market observe-template [--run <label>] [--out <path>]
+market review --from <observations.json> [--json]
 market observe --from <observations.json|sets.jsonl|spool-dir> [--unverified]
 market fronts [--config <path>] [--run <label>] [--diff <prior-run>] [--json]
 market axes [--config <path>] [--run <label>] [--json]
@@ -78,6 +83,63 @@ one client's category intel never bleeds into another's). Front states are
 recomputed deterministically on every invocation — never stored.`);
         return;
     }
+    if (subcommand === "schema") {
+        console.log(`MarketConfig shape:
+{
+  "category": "string",
+  "anchorVendor": "optional vendor id",
+  "vendors": [{
+    "id": "stable-vendor-id",
+    "name": "Vendor Name",
+    "urls": { "home": "https://...", "pricing": null, "product": ["https://..."] },
+    "aliases": ["optional alternate names"]
+  }],
+  "claims": [{
+    "id": "stable-claim-id",
+    "capability": "Specific differentiating capability",
+    "icp": "buyer/segment this claim matters to",
+    "pricingStructure": "pricing motion implied by the claim, or unknown",
+    "definition": "How to judge LOUD vs QUIET vs ABSENT from page text",
+    "terms": ["buyer/search terms for deterministic mention matching"]
+  }],
+  "surfaceRule": "LOUD = hero/primary positioning; QUIET = supported but secondary; ABSENT = no support; UNOBSERVABLE = no usable capture."
+}
+
+ObservationSet shape:
+{
+  "id": "set_run1",
+  "category": "same category as config",
+  "runLabel": "run-1",
+  "runAt": "2026-06-11T00:00:00.000Z",
+  "extractor": "manual|agent:<model>|llm:<provider>:<model>",
+  "observations": [{
+    "id": "stable observation id (any unique string is accepted)",
+    "vendorId": "vendor id from config",
+    "claimId": "claim id from config",
+    "observedAt": "2026-06-11",
+    "intensity": "loud|quiet|absent|unobservable",
+    "confidence": "high|medium|low",
+    "reason": "one reviewer-facing sentence",
+    "evidence": [{
+      "id": "ev1",
+      "sourceSystem": "web",
+      "sourceObjectType": "page",
+      "sourceObjectId": "source URL",
+      "text": "VERBATIM quote from captured page text",
+      "metadata": { "url": "source URL", "captureHash": "hash from worksheet" }
+    }]
+  }]
+}
+
+Rules:
+- exactly one observation per vendor × claim cell
+- loud/quiet require ≥1 verbatim evidence quote
+- absent/unobservable use [] evidence
+- unobservable means no usable captured page exists for the vendor; if pages were captured but the claim is unsupported, use absent
+- submit with: fullstackgtm market observe --from observations.json
+- derive outputs with: fullstackgtm market fronts --json; fullstackgtm market report --format md --out market-report.md`);
+        return;
+    }
     if (subcommand === "init") {
         const category = option(rest, "--category");
         if (!category)
@@ -148,7 +210,20 @@ recomputed deterministically on every invocation — never stored.`);
                 return;
             }
             if (!rest.includes("--unverified")) {
-                const { textByHash } = loadCaptureTexts(config.category);
+                const { entries, textByHash } = loadCaptureTexts(config.category);
+                const usableVendorIds = new Set(entries
+                    .filter((entry) => entry.runLabel === set.runLabel && entry.captureHash && textByHash.has(entry.captureHash))
+                    .map((entry) => entry.vendorId));
+                const unsupportedUnobservable = set.observations.filter((obs) => obs.intensity === "unobservable" && usableVendorIds.has(obs.vendorId));
+                if (unsupportedUnobservable.length > 0) {
+                    console.error(`Rejected: ${unsupportedUnobservable.length} unobservable reading(s) for vendors with usable captures`);
+                    for (const obs of unsupportedUnobservable.slice(0, 20)) {
+                        console.error(`  - ${obs.vendorId} × ${obs.claimId}: vendor has captured page text; unsupported claims should be absent, not unobservable`);
+                    }
+                    console.error("Use unobservable only when no usable captured page exists for that vendor/run. (--unverified skips this gate when captures genuinely live elsewhere.)");
+                    process.exitCode = 1;
+                    return;
+                }
                 const failures = verifyEvidenceSpans(set.observations, textByHash);
                 if (failures.length > 0) {
                     console.error(`Rejected: ${failures.length} evidence span(s) failed verification against the stored captures`);
@@ -181,6 +256,109 @@ recomputed deterministically on every invocation — never stored.`);
         }
         return;
     }
+    if (subcommand === "hints") {
+        const vendorFilter = option(rest, "--vendor");
+        const vendorIds = vendorFilter ? [vendorFilter] : config.vendors.map((vendor) => vendor.id);
+        const worksheets = vendorIds.map((vendorId) => buildWorksheet(config, vendorId, { captureRun: option(rest, "--capture-run") ?? undefined }));
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify({
+                category: config.category,
+                captureRun: worksheets[0]?.captureRun ?? null,
+                vendors: worksheets.map((worksheet) => ({ vendor: worksheet.vendor, claimHints: worksheet.claimHints })),
+            }, null, 2));
+            return;
+        }
+        for (const worksheet of worksheets) {
+            console.log(`\n## ${worksheet.vendor.id} — ${worksheet.vendor.name}`);
+            if (worksheet.pages.length === 0) {
+                console.log("No usable captures: classify every claim as unobservable.");
+                continue;
+            }
+            for (const hint of worksheet.claimHints) {
+                console.log(`\n${hint.claimId}`);
+                if (hint.matches.length === 0) {
+                    console.log("  no lexical matches in captured text (usually absent; still inspect pages for synonyms)");
+                    continue;
+                }
+                for (const match of hint.matches)
+                    console.log(`  - ${match.term} @ ${match.url}: ${match.quote}`);
+            }
+        }
+        return;
+    }
+    if (subcommand === "observe-template") {
+        const runLabel = option(rest, "--run") ?? "run-1";
+        const now = new Date().toISOString();
+        const observations = config.vendors.flatMap((vendor) => {
+            const worksheet = buildWorksheet(config, vendor.id, { captureRun: runLabel });
+            const noPages = worksheet.pages.length === 0;
+            return config.claims.map((claim) => ({
+                id: observationId(config.category, runLabel, vendor.id, claim.id),
+                vendorId: vendor.id,
+                claimId: claim.id,
+                observedAt: now.slice(0, 10),
+                intensity: noPages ? "unobservable" : "absent",
+                confidence: "low",
+                reason: noPages ? `No usable captures for ${vendor.name}; cannot judge.` : "TODO: inspect worksheet/hints and classify this cell.",
+                evidence: [],
+                _claimHints: worksheet.claimHints.find((hint) => hint.claimId === claim.id)?.matches ?? [],
+            }));
+        });
+        const set = { id: `set_${runLabel}`, category: config.category, runLabel, runAt: now, extractor: "manual-template", observations };
+        const payload = `${JSON.stringify(set, null, 2)}\n`;
+        const outPath = option(rest, "--out");
+        if (outPath) {
+            writeFileSync(resolve(process.cwd(), outPath), payload);
+            console.log(`Wrote ${outPath}: ${observations.length} template observations. Fill TODO cells, then run market review --from ${outPath}`);
+        }
+        else {
+            console.log(payload);
+        }
+        return;
+    }
+    if (subcommand === "review") {
+        const fromPath = option(rest, "--from");
+        if (!fromPath)
+            throw new Error("market review requires --from <observations.json>");
+        const set = JSON.parse(readFileSync(resolve(process.cwd(), fromPath), "utf8"));
+        const errors = validateObservationSet(config, set).map((detail) => ({ code: "invalid_observation_set", detail }));
+        const warnings = [];
+        const { entries, textByHash } = loadCaptureTexts(config.category);
+        const usableVendorIds = new Set(entries
+            .filter((entry) => entry.runLabel === set.runLabel && entry.captureHash && textByHash.has(entry.captureHash))
+            .map((entry) => entry.vendorId));
+        for (const obs of set.observations) {
+            if (obs.intensity === "unobservable" && usableVendorIds.has(obs.vendorId)) {
+                errors.push({ code: "unobservable_with_captures", detail: `${obs.vendorId} × ${obs.claimId}: vendor has captured page text; use absent when unsupported.` });
+            }
+            if ((obs.intensity === "absent" || obs.intensity === "unobservable") && usableVendorIds.has(obs.vendorId)) {
+                const hints = buildWorksheet(config, obs.vendorId, { captureRun: set.runLabel }).claimHints.find((hint) => hint.claimId === obs.claimId)?.matches ?? [];
+                if (hints.length > 0) {
+                    warnings.push({
+                        code: "support_candidate_marked_absent",
+                        detail: `${obs.vendorId} × ${obs.claimId}: ${hints.length} candidate snippet(s) matched terms but cell is ${obs.intensity}; verify absent vs quiet. Example: ${hints[0].quote}`,
+                    });
+                }
+            }
+        }
+        for (const failure of verifyEvidenceSpans(set.observations, textByHash)) {
+            errors.push({ code: "bad_evidence", detail: `${failure.vendorId} × ${failure.claimId}: ${failure.problem}` });
+        }
+        const summary = { ok: errors.length === 0, errors, warnings };
+        if (rest.includes("--json")) {
+            console.log(JSON.stringify(summary, null, 2));
+        }
+        else {
+            console.log(`${summary.ok ? "OK" : "FAILED"}: ${errors.length} error(s), ${warnings.length} warning(s)`);
+            for (const err of errors.slice(0, 20))
+                console.log(`ERROR ${err.code}: ${err.detail}`);
+            for (const warn of warnings.slice(0, 20))
+                console.log(`WARN  ${warn.code}: ${warn.detail}`);
+        }
+        if (errors.length > 0)
+            process.exitCode = 1;
+        return;
+    }
     if (subcommand === "classify") {
         const credential = await requireLlmCredential("market classify");
         const vendorFilter = option(rest, "--vendor");

package/dist/cli/plans.js

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { auditSnapshot, defaultPolicy } from "../audit.js";
-import { loadConfig, mergePolicy, resolveConfiguredRules } from "../config.js";
+import { loadConfig, mergePolicy, resolveConfiguredRules, rulePackageTrustFromCli } from "../config.js";
 import { applyPatchPlan } from "../connector.js";
 import { diffFindings, diffSnapshots, diffToMarkdown } from "../diff.js";
 import { createChannelConnector } from "../connectors/outboxChannel.js";
@@ -210,6 +210,19 @@ export async function apply(args) {
     // A channel (e.g. outbox) renders approved ops to a local artifact and
     // transmits nothing; a CRM provider writes records. Same governed apply path.
     const connector = channel ? createChannelConnector(channel) : await connectorFor(provider, args);
+    let applyClaimId;
+    if (planId && store) {
+        const claimed = await store.claimApply(planId, { provider: provider ?? `channel:${channel}`, source: "cli" });
+        applyClaimId = claimed.claimId;
+        const claimedVerification = verifyApprovalDigests(claimed.stored.plan.operations, claimed.stored.approvedOperationIds, claimed.stored.valueOverrides, claimed.stored.approvalDigests);
+        if (!claimedVerification.ok) {
+            await store.abortApplyPreflight(planId, claimed.claimId, "Approval integrity verification failed after the claim and before provider I/O.");
+            throw new Error(`Refusing to apply plan ${planId}: approval changed while acquiring the apply claim.`);
+        }
+        plan = claimed.stored.plan;
+        approvedOperationIds = claimed.stored.approvedOperationIds;
+        valueOverrides = claimed.stored.valueOverrides;
+    }
     // Interactive terminals get a live apply board on stderr while the run
     // executes (preflight → operations → results, with a per-op safety ticker);
     // piped runs render nothing. Either way the emitter streams heartbeats to
@@ -224,11 +237,18 @@ export async function apply(args) {
             progress,
         });
     }
+    catch (error) {
+        // Once applyPatchPlan starts, an exception cannot prove that the provider
+        // performed no write. Keep the claim fail-closed for operator reconciliation.
+        if (planId && store && applyClaimId)
+            await store.markApplyUncertain(planId, applyClaimId);
+        throw error;
+    }
     finally {
         renderer.done();
     }
     if (planId && store) {
-        await store.recordRun(planId, run);
+        await store.recordRun(planId, run, applyClaimId);
     }
     // Charge the acquire meter for the creates that actually landed.
     if (createOps.length > 0) {
@@ -272,8 +292,9 @@ export async function diffCommand(args) {
     }
     const before = JSON.parse(readFileSync(resolve(process.cwd(), beforePath), "utf8"));
     const after = JSON.parse(readFileSync(resolve(process.cwd(), afterPath), "utf8"));
-    const loaded = loadConfig(option(args, "--config") ?? undefined);
-    const rules = selectedRules(args, await resolveConfiguredRules(loaded));
+    const explicitConfig = option(args, "--config") ?? undefined;
+    const loaded = loadConfig(explicitConfig);
+    const rules = selectedRules(args, await resolveConfiguredRules(loaded, undefined, rulePackageTrustFromCli(args, explicitConfig)));
     const policy = mergePolicy(defaultPolicy(), loaded?.config);
     const today = option(args, "--today");
     if (today)
@@ -397,6 +418,14 @@ export async function plansCommand(args) {
         console.log(`Status: ${planStatusWord(stored.status, showPaint)}`);
         console.log(`Approved operations: ${stored.approvedOperationIds.join(", ") || "none"}`);
         console.log(`Runs: ${stored.runs.length}`);
+        if (stored.applyAttempts?.length) {
+            console.log("Apply attempts:");
+            for (const attempt of stored.applyAttempts) {
+                console.log(`  ${attempt.id}  ${attempt.status}  ${attempt.provider} via ${attempt.source}  ${attempt.claimedAt}`);
+                if (attempt.note)
+                    console.log(`    ${attempt.note}`);
+            }
+        }
         console.log("");
         console.log(stylizePlanMarkdown(patchPlanToMarkdown(stored.plan), showPaint));
         return;
@@ -452,5 +481,27 @@ export async function plansCommand(args) {
         console.log(`Rejected ${planId}.`);
         return;
     }
-    throw unknownSubcommandError("plans", subcommand, ["list", "show", "approve", "reject"]);
+    if (subcommand === "recover") {
+        const planId = rest.find((arg) => !arg.startsWith("--"));
+        if (!planId) {
+            throw new Error("Usage: fullstackgtm plans recover <planId> --acknowledge-uncertain-writes");
+        }
+        const stored = await store.get(planId);
+        if (!stored)
+            throw new Error(`No stored plan with id ${planId}.`);
+        if (stored.status !== "applying" || !stored.applyClaim) {
+            throw new Error(`Plan ${planId} has no unresolved apply attempt.`);
+        }
+        const attempt = stored.applyAttempts?.find((entry) => entry.id === stored.applyClaim?.id);
+        if (!rest.includes("--acknowledge-uncertain-writes")) {
+            throw new Error(`Plan ${planId} has an unresolved ${attempt?.provider ?? "provider"} apply attempt (${stored.applyClaim.id}). ` +
+                "Inspect the affected records in the provider; do not replay automatically. If you accept that some writes may already have landed, " +
+                `run \`fullstackgtm plans recover ${planId} --acknowledge-uncertain-writes\`. This clears every approval and requires a fresh review and approval before retrying.`);
+        }
+        await store.recoverApply(planId);
+        console.log(`Released ${planId} to needs_approval after acknowledging uncertain provider state. ` +
+            `No writes were replayed. Re-audit provider state, review the plan, then approve operations again before any apply.`);
+        return;
+    }
+    throw unknownSubcommandError("plans", subcommand, ["list", "show", "approve", "reject", "recover"]);
 }

package/dist/cli/ui.js

@@ -374,6 +374,8 @@ export function planStatusWord(status, p) {
         return p.yellow(status);
     if (status === "approved" || status === "applied")
         return p.green(status);
+    if (status === "applying")
+        return p.yellow(status);
     if (status === "rejected")
         return p.red(status);
     return status;

package/dist/cli.js

@@ -88,7 +88,7 @@ export async function runCli(argv) {
     }
     // Commands without bespoke help get focused per-command help on --help
     // instead of executing (audit used to silently run the sample audit) or
-    // dumping the whole surface. call/market/enrich/bulk-update/schedule print
+    // dumping the whole surface. call/market/enrich/schedule print
     // their own richer help. `--full` always escapes to the complete reference.
     if (!BESPOKE_HELP.includes(command) && (args.includes("--help") || args.includes("-h"))) {
         console.log(args.includes("--full") ? usage() : commandHelp(command));

package/dist/config.d.ts

@@ -26,6 +26,18 @@ export type LoadedConfig = {
     config: FullstackgtmConfig;
     path: string;
 };
+export type RulePackageTrust = {
+    /** Execute rule-package modules. Only set after an explicit trust decision. */
+    allowRulePackages?: boolean;
+    /** Deliberately ignore rule packages while still applying declarative config. */
+    disableRulePackages?: boolean;
+};
+/**
+ * Translate the CLI's explicit trust flags into the library trust contract.
+ * Plugin execution requires both an explicit config path and --allow-plugins;
+ * discovering a config in the current directory is never a trust decision.
+ */
+export declare function rulePackageTrustFromCli(args: string[], explicitConfigPath?: string): RulePackageTrust;
 export declare function loadConfig(explicitPath?: string, cwd?: string): LoadedConfig | null;
 /** Overlay config policy values onto a base policy; defined values win. */
 export declare function mergePolicy(base: GtmPolicy, config?: FullstackgtmConfig): GtmPolicy;
@@ -33,4 +45,4 @@ export declare function mergePolicy(base: GtmPolicy, config?: FullstackgtmConfig
  * Build the effective rule set: built-ins plus rule-package exports, then
  * `enabled` (allow-list) and `disabled` filters.
  */
-export declare function resolveConfiguredRules(loaded?: LoadedConfig | null, baseRules?: GtmAuditRule[]): Promise<GtmAuditRule[]>;
+export declare function resolveConfiguredRules(loaded?: LoadedConfig | null, baseRules?: GtmAuditRule[], trust?: RulePackageTrust): Promise<GtmAuditRule[]>;

package/dist/config.js

@@ -18,6 +18,22 @@ import { builtinAuditRules } from "./rules.js";
  * in version control.
  */
 export const CONFIG_FILE_NAME = "fullstackgtm.config.json";
+/**
+ * Translate the CLI's explicit trust flags into the library trust contract.
+ * Plugin execution requires both an explicit config path and --allow-plugins;
+ * discovering a config in the current directory is never a trust decision.
+ */
+export function rulePackageTrustFromCli(args, explicitConfigPath) {
+    const allow = args.includes("--allow-plugins");
+    const disable = args.includes("--no-plugins");
+    if (allow && disable) {
+        throw new Error("--allow-plugins and --no-plugins cannot be used together.");
+    }
+    if (allow && !explicitConfigPath) {
+        throw new Error("--allow-plugins requires --config <path>. Plugin code is never trusted from an implicitly discovered config.");
+    }
+    return { allowRulePackages: allow, disableRulePackages: disable };
+}
 export function loadConfig(explicitPath, cwd = process.cwd()) {
     const path = explicitPath ? resolve(cwd, explicitPath) : resolve(cwd, CONFIG_FILE_NAME);
     let raw;
@@ -51,9 +67,14 @@ export function mergePolicy(base, config) {
  * Build the effective rule set: built-ins plus rule-package exports, then
  * `enabled` (allow-list) and `disabled` filters.
  */
-export async function resolveConfiguredRules(loaded, baseRules = builtinAuditRules) {
+export async function resolveConfiguredRules(loaded, baseRules = builtinAuditRules, trust = {}) {
     let rules = [...baseRules];
-    for (const specifier of loaded?.config.rulePackages ?? []) {
+    const packages = loaded?.config.rulePackages ?? [];
+    if (packages.length && !trust.allowRulePackages && !trust.disableRulePackages) {
+        throw new Error(`Config ${loaded.path} declares executable rulePackages. Refusing to load plugin code without explicit trust. ` +
+            "For the CLI, pass --config <path> --allow-plugins after reviewing the modules, or pass --no-plugins to use only declarative policy and built-in rules.");
+    }
+    for (const specifier of trust.disableRulePackages ? [] : packages) {
         const resolvedSpecifier = specifier.startsWith(".") || isAbsolute(specifier)
             ? pathToFileURL(resolve(dirname(loaded.path), specifier)).href
             : specifier;

package/dist/connectors/prospectSources.js

@@ -1,3 +1,4 @@
+import { ProviderHttpError } from "../providerError.js";
 function splitName(full) {
     if (!full)
         return {};
@@ -26,7 +27,7 @@ export async function fetchExploriumProspects(opts) {
         body: JSON.stringify({ mode: "full", size, page_size: size, page: 1, filters: opts.filters }),
     });
     if (!response.ok) {
-        throw new Error(`Explorium /v1/prospects failed: HTTP ${response.status} ${await safeText(response)}`);
+        throw new ProviderHttpError("Explorium", "prospect search", response.status);
     }
     const data = (await response.json());
     return (data.data ?? []).map((row) => ({
@@ -58,7 +59,7 @@ export async function fetchPipe0CrustdataProspects(opts) {
         }),
     });
     if (!response.ok) {
-        throw new Error(`pipe0 /v1/searches/run/sync failed: HTTP ${response.status} ${await safeText(response)}`);
+        throw new ProviderHttpError("pipe0", "prospect search", response.status);
     }
     const body = (await response.json());
     // Surface upstream provider errors (e.g. CreditBalanceInsufficient) instead of
@@ -119,7 +120,7 @@ export async function probeExploriumBusinessCount(opts) {
         body: JSON.stringify({ mode: "full", page_size: 1, page: 1, filters: opts.filters }),
     });
     if (!response.ok) {
-        throw new Error(`Explorium /v1/businesses count failed: HTTP ${response.status} ${await safeText(response)}`);
+        throw new ProviderHttpError("Explorium", "business count", response.status);
     }
     const body = (await response.json());
     const total = body.total_results;
@@ -293,14 +294,6 @@ function fieldValue(field) {
     const v = field?.value;
     return typeof v === "string" && v.trim() ? v : undefined;
 }
-async function safeText(response) {
-    try {
-        return (await response.text()).slice(0, 300);
-    }
-    catch {
-        return "";
-    }
-}
 // ---------------------------------------------------------------------------
 // Pre-email dedup: identity keys shared between prospects and CRM contacts, so
 // we can drop already-in-CRM / already-seen people BEFORE paying for emails.

package/dist/connectors/salesforce.js

@@ -1,4 +1,5 @@
 import { SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, readMappedValue, } from "../mappings.js";
+import { validateSalesforceOrigin } from "./salesforceAuth.js";
 import { SNAPSHOT_PULL_STAGES } from "../progress.js";
 const DEFAULT_API_VERSION = "v59.0";
 const SOBJECT_TYPES = {
@@ -97,13 +98,17 @@ export function createSalesforceConnector(options) {
     }
     async function request(path, init = {}) {
         const connection = await options.getConnection();
-        const url = path.startsWith("http")
-            ? path
-            : `${connection.instanceUrl.replace(/\/$/, "")}${path}`;
+        const instanceUrl = validateSalesforceOrigin(connection.instanceUrl, "Salesforce connection instance URL");
+        const resolved = new URL(path, `${instanceUrl}/`);
+        if (resolved.origin !== instanceUrl) {
+            throw new Error("Salesforce response attempted to send credentials to a different origin.");
+        }
+        const url = resolved.href;
         let response;
         try {
             response = await fetchImpl(url, {
                 ...init,
+                redirect: "manual",
                 headers: {
                     Authorization: `Bearer ${connection.accessToken}`,
                     "Content-Type": "application/json",
@@ -113,7 +118,7 @@ export function createSalesforceConnector(options) {
         }
         catch (error) {
             const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
-            throw new Error(`Cannot reach Salesforce at ${connection.instanceUrl}${cause}. Check SALESFORCE_INSTANCE_URL (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`);
+            throw new Error(`Cannot reach Salesforce at ${instanceUrl}${cause}. Check SALESFORCE_INSTANCE_URL (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`);
         }
         if (!response.ok) {
             // Status line only — the body echoes submitted field values and the
@@ -526,8 +531,9 @@ export function createSalesforceConnector(options) {
      */
     async function soapMerge(sobjectType, masterId, loserIds) {
         const connection = await options.getConnection();
+        const instanceUrl = validateSalesforceOrigin(connection.instanceUrl, "Salesforce connection instance URL");
         const version = apiVersion.replace(/^v/, ""); // SOAP path uses "59.0", not "v59.0"
-        const url = `${connection.instanceUrl.replace(/\/$/, "")}/services/Soap/u/${version}`;
+        const url = `${instanceUrl}/services/Soap/u/${version}`;
         const toMerge = loserIds.map((id) => `<urn:recordToMergeIds>${escapeXml(id)}</urn:recordToMergeIds>`).join("");
         const envelope = `<?xml version="1.0" encoding="UTF-8"?>` +
             `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com" xmlns:urn1="urn:sobject.partner.soap.sforce.com">` +
@@ -540,6 +546,7 @@ export function createSalesforceConnector(options) {
         try {
             response = await fetchImpl(url, {
                 method: "POST",
+                redirect: "manual",
                 headers: { "Content-Type": "text/xml; charset=UTF-8", SOAPAction: '""' },
                 body: envelope,
             });

package/dist/connectors/salesforceAuth.d.ts

@@ -6,6 +6,15 @@
  * user confirms on any device. Requires a Connected App with device flow
  * enabled; only its consumer key (client id) is needed.
  */
+/**
+ * Normalize and validate a Salesforce credential-bearing origin.
+ *
+ * Salesforce API hosts are either the standard login/sandbox hosts or a
+ * Salesforce-owned instance/My Domain below salesforce.com.  Deliberately
+ * return an origin (not the input URL) so callers cannot accidentally retain
+ * paths, queries, credentials, or fragments from configuration.
+ */
+export declare function validateSalesforceOrigin(value: string, label?: string): string;
 export type SalesforceTokenSet = {
     accessToken: string;
     refreshToken?: string;

package/dist/connectors/salesforceAuth.js

@@ -7,9 +7,46 @@
  * enabled; only its consumer key (client id) is needed.
  */
 const DEFAULT_LOGIN_URL = "https://login.salesforce.com";
+/**
+ * Normalize and validate a Salesforce credential-bearing origin.
+ *
+ * Salesforce API hosts are either the standard login/sandbox hosts or a
+ * Salesforce-owned instance/My Domain below salesforce.com.  Deliberately
+ * return an origin (not the input URL) so callers cannot accidentally retain
+ * paths, queries, credentials, or fragments from configuration.
+ */
+export function validateSalesforceOrigin(value, label = "Salesforce URL") {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} must be a valid HTTPS Salesforce URL.`);
+    }
+    if (url.protocol !== "https:")
+        throw new Error(`${label} must use HTTPS.`);
+    if (url.username || url.password)
+        throw new Error(`${label} must not contain user information.`);
+    if (url.hash)
+        throw new Error(`${label} must not contain a fragment.`);
+    if (url.search)
+        throw new Error(`${label} must not contain a query string.`);
+    if (url.pathname !== "/" && url.pathname !== "")
+        throw new Error(`${label} must be an origin without a path.`);
+    if (url.port && url.port !== "443")
+        throw new Error(`${label} must use the standard HTTPS port.`);
+    const hostname = url.hostname.toLowerCase();
+    const trusted = hostname === "login.salesforce.com" ||
+        hostname === "test.salesforce.com" ||
+        (hostname.endsWith(".salesforce.com") && hostname.length > ".salesforce.com".length);
+    if (!trusted) {
+        throw new Error(`${label} must use login.salesforce.com, test.salesforce.com, or a Salesforce instance/My Domain host.`);
+    }
+    return url.origin;
+}
 const SESSION_TTL_MS = 2 * 60 * 60 * 1000;
 function tokenUrl(loginUrl) {
-    return `${loginUrl.replace(/\/$/, "")}/services/oauth2/token`;
+    return `${validateSalesforceOrigin(loginUrl, "Salesforce login URL")}/services/oauth2/token`;
 }
 /**
  * OAuth error responses can echo request parameters. Surface only the
@@ -32,6 +69,7 @@ export async function startSalesforceDeviceLogin(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const response = await fetchImpl(tokenUrl(options.loginUrl ?? DEFAULT_LOGIN_URL), {
         method: "POST",
+        redirect: "manual",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({
             response_type: "device_code",
@@ -59,6 +97,7 @@ export async function pollSalesforceDeviceLogin(options) {
         await new Promise((resolveSleep) => setTimeout(resolveSleep, intervalMs));
         const response = await fetchImpl(url, {
             method: "POST",
+            redirect: "manual",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body: new URLSearchParams({
                 grant_type: "device",
@@ -68,10 +107,11 @@ export async function pollSalesforceDeviceLogin(options) {
         });
         const data = await response.json().catch(() => ({}));
         if (response.ok && data.access_token && data.instance_url) {
+            const instanceUrl = validateSalesforceOrigin(String(data.instance_url), "Salesforce token instance_url");
             return {
                 accessToken: data.access_token,
                 refreshToken: data.refresh_token,
-                instanceUrl: data.instance_url,
+                instanceUrl,
                 expiresAt: Date.now() + SESSION_TTL_MS,
             };
         }
@@ -89,6 +129,7 @@ export async function refreshSalesforceToken(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const response = await fetchImpl(tokenUrl(options.loginUrl ?? DEFAULT_LOGIN_URL), {
         method: "POST",
+        redirect: "manual",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({
             grant_type: "refresh_token",
@@ -106,20 +147,21 @@ export async function refreshSalesforceToken(options) {
     return {
         accessToken: data.access_token,
         refreshToken: data.refresh_token ?? options.refreshToken,
-        instanceUrl: data.instance_url,
+        instanceUrl: validateSalesforceOrigin(String(data.instance_url), "Salesforce token instance_url"),
         expiresAt: Date.now() + SESSION_TTL_MS,
     };
 }
 export async function validateSalesforceToken(accessToken, instanceUrl, fetchImpl = fetch) {
+    const trustedInstanceUrl = validateSalesforceOrigin(instanceUrl, "Salesforce instance URL");
     let response;
     try {
-        response = await fetchImpl(`${instanceUrl.replace(/\/$/, "")}/services/oauth2/userinfo`, { headers: { Authorization: `Bearer ${accessToken}` } });
+        response = await fetchImpl(`${trustedInstanceUrl}/services/oauth2/userinfo`, { redirect: "manual", headers: { Authorization: `Bearer ${accessToken}` } });
     }
     catch (error) {
         const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
         return {
             ok: false,
-            detail: `Cannot reach Salesforce at ${instanceUrl}${cause}. Check the --instance-url (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`,
+            detail: `Cannot reach Salesforce at ${trustedInstanceUrl}${cause}. Check the --instance-url (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`,
         };
     }
     if (response.ok) {