fullstackgtm 0.48.0 → 0.50.0

package/src/connectors/salesforceAuth.ts

@@ -9,6 +9,41 @@
 
 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: string, label = "Salesforce URL"): string {
+  let url: 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;
+}
+
 export type SalesforceTokenSet = {
   accessToken: string;
   refreshToken?: string;
@@ -27,7 +62,7 @@ export type SalesforceDeviceAuthorization = {
 const SESSION_TTL_MS = 2 * 60 * 60 * 1000;
 
 function tokenUrl(loginUrl: string) {
-  return `${loginUrl.replace(/\/$/, "")}/services/oauth2/token`;
+  return `${validateSalesforceOrigin(loginUrl, "Salesforce login URL")}/services/oauth2/token`;
 }
 
 /**
@@ -55,6 +90,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",
@@ -91,6 +127,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",
@@ -100,10 +137,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,
       };
     }
@@ -128,6 +166,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",
@@ -145,7 +184,7 @@ 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,
   };
 }
@@ -155,17 +194,18 @@ export async function validateSalesforceToken(
   instanceUrl: string,
   fetchImpl: typeof fetch = fetch,
 ): Promise<{ ok: boolean; detail: string }> {
+  const trustedInstanceUrl = validateSalesforceOrigin(instanceUrl, "Salesforce instance URL");
   let response: Response;
   try {
     response = await fetchImpl(
-      `${instanceUrl.replace(/\/$/, "")}/services/oauth2/userinfo`,
-      { headers: { Authorization: `Bearer ${accessToken}` } },
+      `${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) {

package/src/connectors/theirstack.ts

@@ -17,6 +17,7 @@
  * `metadata.total_results` with include_total_results:true; limit must be ≥ 1
  * (limit:0 → 422, the count gotcha — cf. Explorium's `size`-caps-the-total).
  */
+import { ProviderHttpError } from "../providerError.ts";
 
 type FetchImpl = typeof fetch;
 
@@ -44,14 +45,6 @@ export function theirStackPullCost(companies: number, usdPerCredit?: number): Th
   };
 }
 
-async function safeText(res: { text(): Promise<string> }): Promise<string> {
-  try {
-    return (await res.text()).slice(0, 300);
-  } catch {
-    return "";
-  }
-}
-
 /** Firmographic + technographic filter for TheirStack company search. */
 export type TheirStackFilters = {
   /** technology slugs, OR-matched — e.g. ["salesforce","hubspot","pipedrive"]. */
@@ -136,7 +129,7 @@ export async function theirStackCountCompanies(opts: {
     body: buildBody(opts.filters, 1, 0, true),
   });
   if (!res.ok) {
-    throw new Error(`TheirStack count failed: HTTP ${res.status} ${await safeText(res)}`);
+    throw new ProviderHttpError("TheirStack", "count", res.status);
   }
   return readTheirStackTotal(await res.json());
 }
@@ -162,7 +155,7 @@ export async function theirStackSearchCompanies(opts: {
     body: buildBody(opts.filters, limit, opts.page ?? 0, true),
   });
   if (!res.ok) {
-    throw new Error(`TheirStack search failed: HTTP ${res.status} ${await safeText(res)}`);
+    throw new ProviderHttpError("TheirStack", "search", res.status);
   }
   const body = (await res.json()) as { data?: Array<Record<string, unknown>>; results?: Array<Record<string, unknown>> };
   const rows = body.data ?? body.results ?? [];

package/src/credentials.ts

@@ -3,17 +3,20 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
-  readFileSync,
-  statSync,
   unlinkSync,
-  writeFileSync,
 } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { refreshHubspotToken } from "./connectors/hubspotAuth.ts";
-import { refreshSalesforceToken } from "./connectors/salesforceAuth.ts";
+import { refreshSalesforceToken, validateSalesforceOrigin } from "./connectors/salesforceAuth.ts";
 import { detectKeychainBackend } from "./keychain.ts";
+import {
+  assertNoSymlinkComponents,
+  readSecureRegularFile,
+  UnsafeManagedPathError,
+  writeSecureFileAtomic,
+} from "./secureFile.ts";
 
 /**
  * Local CLI credential store: ~/.fullstackgtm/credentials.json (0600), or
@@ -126,7 +129,9 @@ export function ensureSecureHomeDir(): string {
   const levels =
     dir === baseHomeDir() ? [dir] : [baseHomeDir(), join(baseHomeDir(), "profiles"), dir];
   for (const level of levels) {
+    assertNoSymlinkComponents(level);
     mkdirSync(level, { recursive: true, mode: 0o700 });
+    assertNoSymlinkComponents(level);
     try {
       chmodSync(level, 0o700);
     } catch {
@@ -138,12 +143,7 @@ export function ensureSecureHomeDir(): string {
 
 /** Write a 0600 file under the home, enforcing the mode even on rewrite. */
 export function writeSecureFile(path: string, contents: string) {
-  writeFileSync(path, contents, { mode: 0o600 });
-  try {
-    chmodSync(path, 0o600);
-  } catch {
-    // Non-POSIX filesystems ignore chmod.
-  }
+  writeSecureFileAtomic(path, contents);
 }
 
 /**
@@ -153,19 +153,14 @@ export function writeSecureFile(path: string, contents: string) {
  * mode on read too — re-tighten to 0600 and warn once — so a world-readable
  * credential store can't sit there silently leaking the token to other users.
  */
-function enforceCredentialFileMode(path: string): void {
-  try {
-    const mode = statSync(path).mode & 0o777;
-    if ((mode & 0o077) !== 0) {
-      chmodSync(path, 0o600);
-      console.error(
-        `fullstackgtm: tightened ${path} from ${mode.toString(8).padStart(3, "0")} to 600 ` +
-          "(it was readable or writable by other users).",
-      );
-    }
-  } catch {
-    // Missing file or non-POSIX filesystem: nothing to enforce.
-  }
+function readCredentialFile(path: string): string {
+  return readSecureRegularFile(path, {
+    tightenMode: 0o600,
+    onModeTightened: (mode) => console.error(
+      `fullstackgtm: tightened ${path} from ${mode.toString(8).padStart(3, "0")} to 600 ` +
+        "(it was readable or writable by other users).",
+    ),
+  });
 }
 
 /**
@@ -190,7 +185,7 @@ function activeKeychain(): { account: string; backend: NonNullable<ReturnType<ty
 function migratePlaintextToKeychain(keychain: NonNullable<ReturnType<typeof activeKeychain>>): void {
   if (!existsSync(credentialsPath())) return;
   try {
-    const fileParsed = JSON.parse(readFileSync(credentialsPath(), "utf8"));
+    const fileParsed = JSON.parse(readCredentialFile(credentialsPath()));
     if (fileParsed && fileParsed.version === 1 && fileParsed.providers) {
       const current = keychain.backend.get(keychain.account);
       const existing = current ? (JSON.parse(current).providers ?? {}) : {};
@@ -209,14 +204,15 @@ function readFile(): CredentialsFile {
   const keychain = activeKeychain();
   if (keychain) migratePlaintextToKeychain(keychain);
   try {
-    const raw = keychain ? keychain.backend.get(keychain.account) : (enforceCredentialFileMode(credentialsPath()), readFileSync(credentialsPath(), "utf8"));
+    const raw = keychain ? keychain.backend.get(keychain.account) : readCredentialFile(credentialsPath());
     if (raw) {
       const parsed = JSON.parse(raw);
       if (parsed && typeof parsed === "object" && parsed.version === 1 && parsed.providers) {
         return parsed as CredentialsFile;
       }
     }
-  } catch {
+  } catch (error) {
+    if (error instanceof UnsafeManagedPathError) throw error;
     // Missing or unreadable store falls through to an empty one.
   }
   return { version: 1, providers: {} };
@@ -238,6 +234,18 @@ export function getCredential(provider: string): StoredCredential | null {
 }
 
 export function storeCredential(provider: string, credential: StoredCredential) {
+  if (provider === "salesforce") {
+    if (!credential.instanceUrl) {
+      throw new Error("Salesforce credentials require an instance URL.");
+    }
+    credential = {
+      ...credential,
+      instanceUrl: validateSalesforceOrigin(credential.instanceUrl, "Salesforce credential instance URL"),
+      ...(credential.loginUrl
+        ? { loginUrl: validateSalesforceOrigin(credential.loginUrl, "Salesforce credential login URL") }
+        : {}),
+    };
+  }
   const file = readFile();
   file.providers[provider] = credential;
   persist(file);
@@ -315,12 +323,19 @@ export async function resolveSalesforceConnection(
         "Stored Salesforce credential has no instance URL. Run `fullstackgtm login salesforce` again.",
       );
     }
+    const instanceUrl = validateSalesforceOrigin(
+      credential.instanceUrl,
+      "Stored Salesforce credential instance URL",
+    );
+    if (credential.loginUrl) {
+      validateSalesforceOrigin(credential.loginUrl, "Stored Salesforce credential login URL");
+    }
     const needsRefresh =
       credential.kind === "oauth" &&
       credential.expiresAt !== undefined &&
       Date.now() > credential.expiresAt - REFRESH_SKEW_MS;
     if (!needsRefresh) {
-      return { accessToken: credential.accessToken, instanceUrl: credential.instanceUrl };
+      return { accessToken: credential.accessToken, instanceUrl };
     }
     if (!credential.refreshToken || !credential.clientId) {
       throw new Error(
@@ -349,9 +364,13 @@ export async function resolveSalesforceConnection(
   if (!minted.instanceUrl) {
     throw new Error("The hosted deployment returned no Salesforce instance URL.");
   }
+  const instanceUrl = validateSalesforceOrigin(
+    minted.instanceUrl,
+    "Hosted Salesforce credential instance URL",
+  );
   return {
     accessToken: minted.accessToken,
-    instanceUrl: minted.instanceUrl,
+    instanceUrl,
     fieldMappings: minted.fieldMappings,
   };
 }

package/src/enrich.ts

@@ -111,6 +111,8 @@ export type AcquireDiscoveryConfig = {
   provider: "explorium" | "pipe0" | "linkedin" | "heyreach";
   filters?: Record<string, unknown>;
   size?: number;
+  /** Maximum raw provider candidates scanned per run while seeking fresh leads. */
+  scanLimit?: number;
   resolveEmailsWith?: "pipe0";
   /** LinkedIn sources only: the provider-native list id to read (HeyReach lead-list id). */
   listId?: string;
@@ -1326,7 +1328,49 @@ export function selectStaleWork(
 // Checkpoint (cursor), staleness ledger (stamps), and observability surface
 // (enrich status) in one structure — mirrors the market observations store.
 
-export type EnrichRunMode = EnrichMode | "ingest";
+export type EnrichRunMode = EnrichMode | "ingest" | "acquire";
+
+/**
+ * Provider continuation state for an acquisition query. The fingerprint binds
+ * a cursor/offset to the ICP + provider filters that produced it, preventing a
+ * changed query from accidentally resuming in the middle of the old audience.
+ */
+export type AcquireDiscoveryCheckpoint = {
+  queryFingerprint: string;
+  /** Opaque provider cursor (Pipe0 and other cursor-based sources). */
+  cursor?: string | null;
+  /** Zero-based provider offset (LinkedIn/HeyReach and other offset sources). */
+  offset?: number | null;
+  /** True only when the provider has positively reported no next page. */
+  exhausted: boolean;
+};
+
+/**
+ * Truthful acquisition funnel for one run. Each field counts candidates, not
+ * provider requests, making duplicate saturation and resolution loss visible
+ * instead of reporting every run as zero.
+ */
+export type AcquireRunFunnel = {
+  /** Raw candidates returned across all discovery pages scanned this run. */
+  discovered: number;
+  /** Candidates that met the configured ICP threshold. */
+  qualified: number;
+  /** Qualified candidates removed by the CRM pre-email dedupe. */
+  skippedCrm: number;
+  /** Qualified candidates removed by the cross-run seen ledger. */
+  skippedSeen: number;
+  /** Fresh candidates carrying the configured resolve-first key. */
+  resolved: number;
+  /** Governed create operations emitted into the saved/dry-run plan. */
+  proposed: number;
+  /** Otherwise-proposable candidates held back by the acquire meter. */
+  withheldByMeter: number;
+};
+
+export type AcquireRunTelemetry = {
+  funnel: AcquireRunFunnel;
+  discovery: AcquireDiscoveryCheckpoint;
+};
 
 export type EnrichRun = {
   id: string;
@@ -1339,6 +1383,8 @@ export type EnrichRun = {
   /** Resume point for an interrupted pull (last processed pull key). */
   cursor: string | null;
   counts: EnrichCounts;
+  /** Acquisition-only funnel + provider continuation state (absent on legacy runs). */
+  acquireTelemetry?: AcquireRunTelemetry;
   planIds: string[];
   stamps: EnrichStamp[];
   /** Staged source rows (ingest mode only), consumed by append/refresh. */

package/src/hostedAcquireCheckpoint.ts

@@ -0,0 +1,156 @@
+/**
+ * Authenticated acquisition-checkpoint transport for paired CLI installs.
+ *
+ * The local checkpoint remains authoritative for running a job. This module
+ * only mirrors/query-scoped continuation state to the paired hosted app so a
+ * different authenticated worker can resume it. Writes use compare-and-swap:
+ * a stale client receives a conflict and must explicitly reconcile instead of
+ * silently moving a provider cursor backwards or overwriting another worker.
+ */
+import { getCredential } from "./credentials.ts";
+import type { AcquireDiscoveryCheckpoint } from "./enrich.ts";
+
+const ENDPOINT = "/api/cli/acquisition-checkpoint";
+const DEFAULT_TIMEOUT_MS = 4000;
+const CHECKPOINT_KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+
+export type HostedAcquireCheckpoint = {
+  checkpoint: AcquireDiscoveryCheckpoint;
+  /** Opaque server revision used only for compare-and-swap. */
+  version: number;
+  updatedAt: number;
+};
+
+export type HostedCheckpointReadResult =
+  | { status: "unpaired" }
+  | { status: "missing" }
+  | { status: "found"; record: HostedAcquireCheckpoint }
+  | { status: "unavailable"; reason: string };
+
+export type HostedCheckpointWriteResult =
+  | { status: "unpaired" }
+  | { status: "saved"; record: HostedAcquireCheckpoint }
+  | { status: "conflict"; current: HostedAcquireCheckpoint | null }
+  | { status: "unavailable"; reason: string };
+
+type Options = { fetchImpl?: typeof fetch; timeoutMs?: number };
+
+function validKey(key: string): string {
+  if (!CHECKPOINT_KEY.test(key)) {
+    throw new Error("Acquisition checkpoint key must be 1-256 URL-safe characters.");
+  }
+  return key;
+}
+
+function broker(): { baseUrl: string; accessToken: string } | null {
+  const credential = getCredential("broker");
+  if (!credential?.baseUrl || !credential.accessToken) return null;
+  let url: URL;
+  try {
+    url = new URL(credential.baseUrl);
+  } catch {
+    return null;
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) return null;
+  return { baseUrl: url.href.replace(/\/+$/, ""), accessToken: credential.accessToken };
+}
+
+function isCheckpoint(value: unknown): value is AcquireDiscoveryCheckpoint {
+  if (!value || typeof value !== "object") return false;
+  const item = value as Record<string, unknown>;
+  return (
+    typeof item.queryFingerprint === "string" &&
+    item.queryFingerprint.length > 0 &&
+    typeof item.exhausted === "boolean" &&
+    (item.cursor === undefined || item.cursor === null || typeof item.cursor === "string") &&
+    (item.offset === undefined || item.offset === null ||
+      (typeof item.offset === "number" && Number.isSafeInteger(item.offset) && item.offset >= 0))
+  );
+}
+
+function parseRecord(value: unknown): HostedAcquireCheckpoint | null {
+  if (!value || typeof value !== "object") return null;
+  const body = value as Record<string, unknown>;
+  if (!isCheckpoint(body.checkpoint) || !Number.isSafeInteger(body.version) || (body.version as number) < 1) return null;
+  if (!Number.isSafeInteger(body.updatedAt) || (body.updatedAt as number) < 0) return null;
+  return {
+    checkpoint: body.checkpoint,
+    version: body.version as number,
+    updatedAt: body.updatedAt as number,
+  };
+}
+
+function reasonFor(status: number): string {
+  if (status === 401 || status === 403) return "hosted authentication was rejected; pair the CLI again";
+  return `hosted checkpoint request failed (HTTP ${status})`;
+}
+
+/** Read a query/list checkpoint. Inert unless this profile is paired. */
+export async function readHostedAcquireCheckpoint(
+  key: string,
+  options: Options = {},
+): Promise<HostedCheckpointReadResult> {
+  validKey(key);
+  const paired = broker();
+  if (!paired) return { status: "unpaired" };
+  try {
+    const response = await (options.fetchImpl ?? fetch)(
+      `${paired.baseUrl}${ENDPOINT}?key=${encodeURIComponent(key)}`,
+      {
+        headers: { Authorization: `Bearer ${paired.accessToken}`, Accept: "application/json" },
+        signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      },
+    );
+    if (response.status === 404) return { status: "missing" };
+    if (!response.ok) return { status: "unavailable", reason: reasonFor(response.status) };
+    const record = parseRecord(await response.json());
+    return record
+      ? { status: "found", record }
+      : { status: "unavailable", reason: "hosted checkpoint response was invalid" };
+  } catch {
+    return { status: "unavailable", reason: "hosted checkpoint request was unavailable" };
+  }
+}
+
+/**
+ * Mirror a local checkpoint using compare-and-swap. Pass null only when the
+ * caller observed no hosted record (sent as version zero); pass the exact
+ * positive version returned by read for an update.
+ */
+export async function writeHostedAcquireCheckpoint(
+  key: string,
+  checkpoint: AcquireDiscoveryCheckpoint,
+  expectedVersion: number | null,
+  options: Options = {},
+): Promise<HostedCheckpointWriteResult> {
+  validKey(key);
+  if (!isCheckpoint(checkpoint)) throw new Error("Refusing to sync an invalid acquisition checkpoint.");
+  if (expectedVersion !== null && (!Number.isSafeInteger(expectedVersion) || expectedVersion < 1)) {
+    throw new Error("expectedVersion must be null or a positive integer.");
+  }
+  const paired = broker();
+  if (!paired) return { status: "unpaired" };
+  try {
+    const response = await (options.fetchImpl ?? fetch)(`${paired.baseUrl}${ENDPOINT}`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${paired.accessToken}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ key, checkpoint, expectedVersion: expectedVersion ?? 0 }),
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+    if (response.status === 409) {
+      const body: unknown = await response.json().catch(() => null);
+      const current = body && typeof body === "object"
+        ? parseRecord((body as Record<string, unknown>).current)
+        : null;
+      return { status: "conflict", current };
+    }
+    if (!response.ok) return { status: "unavailable", reason: reasonFor(response.status) };
+    const record = parseRecord(await response.json());
+    return record
+      ? { status: "saved", record }
+      : { status: "unavailable", reason: "hosted checkpoint response was invalid" };
+  } catch {
+    return { status: "unavailable", reason: "hosted checkpoint request was unavailable" };
+  }
+}