fullstackgtm 0.48.0 → 0.50.0

package/dist/credentials.js

@@ -1,10 +1,11 @@
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, unlinkSync, } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { refreshHubspotToken } from "./connectors/hubspotAuth.js";
-import { refreshSalesforceToken } from "./connectors/salesforceAuth.js";
+import { refreshSalesforceToken, validateSalesforceOrigin } from "./connectors/salesforceAuth.js";
 import { detectKeychainBackend } from "./keychain.js";
+import { assertNoSymlinkComponents, readSecureRegularFile, UnsafeManagedPathError, writeSecureFileAtomic, } from "./secureFile.js";
 /**
  * Local CLI credential store: ~/.fullstackgtm/credentials.json (0600), or
  * $FSGTM_HOME/credentials.json when set. Environment tokens always win over
@@ -80,7 +81,9 @@ export function ensureSecureHomeDir() {
     // umask) only to directories it creates, and never to pre-existing ones.
     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);
         }
@@ -92,13 +95,7 @@ export function ensureSecureHomeDir() {
 }
 /** Write a 0600 file under the home, enforcing the mode even on rewrite. */
 export function writeSecureFile(path, contents) {
-    writeFileSync(path, contents, { mode: 0o600 });
-    try {
-        chmodSync(path, 0o600);
-    }
-    catch {
-        // Non-POSIX filesystems ignore chmod.
-    }
+    writeSecureFileAtomic(path, contents);
 }
 /**
  * The 0600/0700 guarantee was write-only: a credentials.json inherited at
@@ -107,18 +104,12 @@ export function writeSecureFile(path, contents) {
  * 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) {
-    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) {
+    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)."),
+    });
 }
 /**
  * Persistence backend for the credential blob: the OS keychain when
@@ -144,7 +135,7 @@ function migratePlaintextToKeychain(keychain) {
     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 ?? {}) : {};
@@ -164,7 +155,7 @@ function readFile() {
     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) {
@@ -172,7 +163,9 @@ function readFile() {
             }
         }
     }
-    catch {
+    catch (error) {
+        if (error instanceof UnsafeManagedPathError)
+            throw error;
         // Missing or unreadable store falls through to an empty one.
     }
     return { version: 1, providers: {} };
@@ -192,6 +185,18 @@ export function getCredential(provider) {
     return readFile().providers[provider] ?? null;
 }
 export function storeCredential(provider, credential) {
+    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);
@@ -248,11 +253,15 @@ export async function resolveSalesforceConnection(options = {}) {
         if (!credential.instanceUrl) {
             throw new Error("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("Stored Salesforce token is expired and cannot be refreshed. Run `fullstackgtm login salesforce` again.");
@@ -279,9 +288,10 @@ export async function resolveSalesforceConnection(options = {}) {
     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/dist/enrich.d.ts

@@ -86,6 +86,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;
@@ -286,7 +288,46 @@ export declare function selectStaleWork(config: EnrichConfig, runs: EnrichRun[],
     now?: () => Date;
     staleDaysOverride?: number;
 }): EnrichWorkItem[];
-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;
     runLabel: string;
@@ -298,6 +339,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/dist/hostedAcquireCheckpoint.d.ts

@@ -0,0 +1,43 @@
+import type { AcquireDiscoveryCheckpoint } from "./enrich.ts";
+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;
+};
+/** Read a query/list checkpoint. Inert unless this profile is paired. */
+export declare function readHostedAcquireCheckpoint(key: string, options?: Options): Promise<HostedCheckpointReadResult>;
+/**
+ * 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 declare function writeHostedAcquireCheckpoint(key: string, checkpoint: AcquireDiscoveryCheckpoint, expectedVersion: number | null, options?: Options): Promise<HostedCheckpointWriteResult>;
+export {};

package/dist/hostedAcquireCheckpoint.js

@@ -0,0 +1,129 @@
+/**
+ * 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.js";
+const ENDPOINT = "/api/cli/acquisition-checkpoint";
+const DEFAULT_TIMEOUT_MS = 4000;
+const CHECKPOINT_KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+function validKey(key) {
+    if (!CHECKPOINT_KEY.test(key)) {
+        throw new Error("Acquisition checkpoint key must be 1-256 URL-safe characters.");
+    }
+    return key;
+}
+function broker() {
+    const credential = getCredential("broker");
+    if (!credential?.baseUrl || !credential.accessToken)
+        return null;
+    let 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) {
+    if (!value || typeof value !== "object")
+        return false;
+    const item = value;
+    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) {
+    if (!value || typeof value !== "object")
+        return null;
+    const body = value;
+    if (!isCheckpoint(body.checkpoint) || !Number.isSafeInteger(body.version) || body.version < 1)
+        return null;
+    if (!Number.isSafeInteger(body.updatedAt) || body.updatedAt < 0)
+        return null;
+    return {
+        checkpoint: body.checkpoint,
+        version: body.version,
+        updatedAt: body.updatedAt,
+    };
+}
+function reasonFor(status) {
+    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, options = {}) {
+    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, checkpoint, expectedVersion, options = {}) {
+    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 = await response.json().catch(() => null);
+            const current = body && typeof body === "object"
+                ? parseRecord(body.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" };
+    }
+}

package/dist/hostedPatchPlan.d.ts

@@ -0,0 +1,87 @@
+import type { PlanStore, StoredPlan } from "./planStore.ts";
+import type { PatchOperation, PatchPlan, PatchPlanRun } from "./types.ts";
+type Options = {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+export type HostedPlanState = {
+    patchPlanId: string;
+    externalPlanId: string;
+    documentSha256: string;
+    status: string;
+    approvedOperationIds: string[];
+    valueOverrides: Record<string, unknown>;
+    updatedAt: number;
+    runRecord?: PatchPlanRun;
+    url: string;
+};
+export type HostedPlanResult = {
+    status: "unpaired";
+} | {
+    status: "missing";
+} | {
+    status: "found" | "saved";
+    state: HostedPlanState;
+} | {
+    status: "conflict";
+    reason: string;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+/** Review document intentionally omits evidence/findings and all mutable store security state. */
+export declare function hostedReviewDocument(plan: PatchPlan): {
+    guards?: import("./types.ts").PlanGuard[] | undefined;
+    filter?: {
+        objectType: "account" | "contact" | "deal";
+        where: string[];
+        today?: string;
+    } | undefined;
+    id: string;
+    title: string;
+    createdAt: string;
+    status: string;
+    dryRun: boolean;
+    summary: string;
+    operations: PatchOperation[];
+};
+export declare function hostedPlanDigest(plan: PatchPlan): string;
+export declare function uploadHostedPatchPlan(stored: StoredPlan, options?: Options): Promise<HostedPlanResult>;
+export declare function readHostedPatchPlan(planId: string, options?: Options): Promise<HostedPlanResult>;
+export type HostedReconcileResult = {
+    status: "unchanged" | "unpaired" | "missing";
+} | {
+    status: "updated";
+    stored: StoredPlan;
+    remoteStatus: string;
+} | {
+    status: "conflict" | "unavailable";
+    reason: string;
+};
+/** Pull a peer's newer lifecycle into the local replica without weakening local integrity gates. */
+export declare function reconcileHostedPatchPlan(store: PlanStore, stored: StoredPlan, options?: Options): Promise<HostedReconcileResult>;
+export declare function reportHostedPlanLifecycle(stored: StoredPlan, options?: Options & {
+    claimId?: string;
+}): Promise<HostedPlanResult>;
+export type HostedApplyClaimResult = {
+    status: "unpaired";
+} | {
+    status: "claimed";
+    claimId: string;
+    expiresAt?: number;
+} | {
+    status: "applied";
+} | {
+    status: "conflict" | "unavailable";
+    reason: string;
+};
+/** Coordinate online replicas before provider I/O; provider idempotency remains the offline fallback. */
+export declare function claimHostedPlanApply(stored: StoredPlan, options?: Options): Promise<HostedApplyClaimResult>;
+/** Release a shared CLI claim only when preflight aborts before provider I/O. */
+export declare function releaseHostedPlanApply(stored: StoredPlan, claimId: string, reason: string, options?: Options): Promise<{
+    status: "released" | "unpaired";
+} | {
+    status: "conflict" | "unavailable";
+    reason: string;
+}>;
+export {};