fullstackgtm 0.26.0 → 0.28.0

package/src/bulkUpdate.ts

@@ -18,8 +18,21 @@
  *   field=value     case-insensitive equality
  *   field!=value    case-insensitive inequality
  *   field~value     case-insensitive substring
+ *   field!~value    case-insensitive not-substring
  *   field:empty     unset or empty string
  *   field:notempty  set and non-empty
+ *   field<value     type-aware less-than (date or numeric)
+ *   field>value     type-aware greater-than
+ *   field<=value    type-aware less-than-or-equal
+ *   field>=value    type-aware greater-than-or-equal
+ *
+ * Comparison operators (`<` `>` `<=` `>=`) are type-aware, unlike the string
+ * operators above: if both the field value and the RHS parse as finite dates
+ * they compare as dates; else if both parse as finite numbers they compare
+ * numerically; otherwise the clause does not match (never throws at match
+ * time). The bare literal `today` on the RHS resolves to the policy/today date
+ * (`--today`, defaulting to the system date) and forces a date comparison —
+ * so `closeDate<today` is the canonical "past close date" filter.
  *
  * Fields are canonical (ownerId, stage, closeDate, amount, domain, name,
  * email, isClosed, accountId, …). Relational pseudo-fields are available in
@@ -72,40 +85,176 @@ export type BulkUpdateOptions = {
   reason?: string;
   /** refuse to build plans larger than this (default 500 operations) */
   maxOperations?: number;
+  /**
+   * Date the comparison `today` literal resolves to (ISO yyyy-mm-dd). Set from
+   * the policy/--today date at the CLI; defaults to the system date. Stored on
+   * plan.filter so apply-time filter re-verification resolves `today`
+   * identically to plan time.
+   */
+  today?: string;
 };
 
 type WhereClause = {
   field: string;
-  op: "eq" | "neq" | "contains" | "notcontains" | "empty" | "notempty";
+  op: "eq" | "neq" | "contains" | "notcontains" | "empty" | "notempty" | "lt" | "gt" | "lte" | "gte";
   value?: string;
   raw: string;
 };
 
 const FIELD_PATTERN = "[a-zA-Z][a-zA-Z0-9_]*(?:\\.[a-zA-Z][a-zA-Z0-9_]*)?";
 
+/**
+ * Is a comparison RHS (a single `|`-alternative) authorable for comparison?
+ * Accept `today`, OR a plain number, OR a date-SHAPED string — using the exact
+ * same `isPlainNumber`/`isDateLike` predicates the match-time branch uses, so
+ * the parse-time authoring check and the runtime branch cannot diverge. The
+ * intentional asymmetry: parse-time validates one literal in isolation (EITHER
+ * number OR date is fine), whereas match-time's `compareValues` additionally
+ * requires the FIELD and the RHS to agree on type (BOTH number, or BOTH date).
+ * Requiring a date *shape* here (not bare `Date.parse`-finite) means a prose
+ * typo like `July 4` or a stray `<5` fails loudly at parse instead of silently
+ * matching nothing. `isDateLike`/`isPlainNumber` are hoisted function decls.
+ */
+function isComparableValue(rhs: string): boolean {
+  const trimmed = rhs.trim();
+  if (trimmed === "today") return true;
+  if (isPlainNumber(trimmed)) return true;
+  if (isDateLike(trimmed)) return true;
+  return false;
+}
+
+/**
+ * Catch the "multiple conditions crammed into one --where" footgun: a weak
+ * agent writes `--where 'stage!=closedwon AND stage!=closedlost'`, which the
+ * grammar would otherwise parse as a single neq clause whose VALUE is the
+ * literal string `closedwon AND stage!=closedlost` — matching almost nothing
+ * (or, with `!=`, almost EVERYTHING), so the gate faithfully applies a
+ * wildly-wrong-but-authorized plan.
+ *
+ * Fire only when a connector ` AND `/` OR ` is followed by a clause-LIKE
+ * structure (a field name + an operator), so incidental prose in a value —
+ * `name~Procter AND Gamble`, `name~research and development` — is NOT
+ * rejected (the word after the connector has no operator). Case-insensitive.
+ */
+const INLINE_CONJUNCTION = new RegExp(
+  `\\s(and|or)\\s+${FIELD_PATTERN}\\s*(!=|<=|>=|!~|=|<|>|~|:(empty|notempty)\\b)`,
+  "i",
+);
+
 export function parseWhere(expr: string): WhereClause {
+  if (INLINE_CONJUNCTION.test(expr)) {
+    throw new Error(
+      `Cannot parse "${expr}": looks like multiple conditions in one clause. ` +
+        `AND is implicit — use a SEPARATE --where for each condition ` +
+        `(e.g. --where stage!=closedwon --where stage!=closedlost). ` +
+        `For OR within one field, use value1|value2 (e.g. --where stage=closedwon|closedlost).`,
+    );
+  }
   const empty = expr.match(new RegExp(`^(${FIELD_PATTERN}):(empty|notempty)$`));
   if (empty) return { field: empty[1], op: empty[2] as "empty" | "notempty", raw: expr };
   const neq = expr.match(new RegExp(`^(${FIELD_PATTERN})!=(.*)$`));
   if (neq) return { field: neq[1], op: "neq", value: neq[2], raw: expr };
   const notContains = expr.match(new RegExp(`^(${FIELD_PATTERN})!~(.*)$`));
   if (notContains) return { field: notContains[1], op: "notcontains", value: notContains[2], raw: expr };
+  // Comparison operators: two-char tokens (`<=`/`>=`) MUST be tried before the
+  // one-char ones (`<`/`>`) so a prefix isn't stolen (`field<=5` → lte, not
+  // lt + stray `=`). They slot in after `!=`/`!~` and before `~`/`=` (different
+  // lead chars, no collision). The RHS is validated at parse time: an
+  // un-comparable literal (neither today, number, nor date) is a static
+  // authoring error and throws here, so a typo never silently matches nothing.
+  const lte = expr.match(new RegExp(`^(${FIELD_PATTERN})<=(.*)$`));
+  if (lte) return assertComparable({ field: lte[1], op: "lte", value: lte[2], raw: expr });
+  const gte = expr.match(new RegExp(`^(${FIELD_PATTERN})>=(.*)$`));
+  if (gte) return assertComparable({ field: gte[1], op: "gte", value: gte[2], raw: expr });
+  const lt = expr.match(new RegExp(`^(${FIELD_PATTERN})<(.*)$`));
+  if (lt) return assertComparable({ field: lt[1], op: "lt", value: lt[2], raw: expr });
+  const gt = expr.match(new RegExp(`^(${FIELD_PATTERN})>(.*)$`));
+  if (gt) return assertComparable({ field: gt[1], op: "gt", value: gt[2], raw: expr });
   const contains = expr.match(new RegExp(`^(${FIELD_PATTERN})~(.*)$`));
   if (contains) return { field: contains[1], op: "contains", value: contains[2], raw: expr };
   const eq = expr.match(new RegExp(`^(${FIELD_PATTERN})=(.*)$`));
   if (eq) return { field: eq[1], op: "eq", value: eq[2], raw: expr };
   throw new Error(
-    `Cannot parse --where "${expr}". Use field=value, field!=value, field~substring, field!~substring, field:empty, or field:notempty.`,
+    `Cannot parse --where "${expr}". Use field=value, field!=value, field~substring, field!~substring, field:empty, field:notempty, field<value, field>value, field<=value, or field>=value.`,
   );
 }
 
+/**
+ * Parse-time validity for a comparison clause: every `|`-alternative of the
+ * RHS must be a comparable literal (today / number / date). An un-comparable
+ * value (e.g. `amount>`, `closeDate<garbage`) throws here — a comparison that
+ * can never coerce is an authoring error, not a silent empty match.
+ */
+function assertComparable(clause: WhereClause): WhereClause {
+  const alternatives = (clause.value ?? "").split("|");
+  if (alternatives.some((a) => !isComparableValue(a))) {
+    throw new Error(
+      `Cannot parse --where "${clause.raw}": the comparison value must be a number, an ISO date, or "today" (got "${clause.value ?? ""}").`,
+    );
+  }
+  return clause;
+}
+
 function fieldValue(view: Record<string, unknown>, field: string): string {
   const value = view[field];
   if (value === undefined || value === null) return "";
   return String(value);
 }
 
-function matches(view: Record<string, unknown>, clause: WhereClause): boolean {
+/** System date as ISO yyyy-mm-dd — the default `today` when none is threaded. */
+function systemToday(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/** A non-empty trimmed string that parses as a finite JS number. */
+function isPlainNumber(value: string): boolean {
+  const trimmed = value.trim();
+  return trimmed !== "" && Number.isFinite(Number(trimmed));
+}
+
+/**
+ * "Looks like a date": Date.parse-finite AND not a plain number. The guard
+ * against plain numbers is essential — `Date.parse("5000")` is finite (it reads
+ * as the YEAR 5000), so without it `closeDate<5000` and `amount>2026-04-30`
+ * would silently take the date branch and produce wrong, broad matches. Pure
+ * numbers are numbers; only date-SHAPED strings (with `-`/`/`/`T`, like the
+ * canonical ISO `2026-04-30`) are dates. Mirrors the ISO-date assumption the
+ * past-close-date rule already makes (rules.ts compareDate).
+ */
+function isDateLike(value: string): boolean {
+  // Require an ISO-ish date separator (`-`/`/`/`T`/`:`) in addition to a finite
+  // Date.parse: excludes plain numbers (`Date.parse("5000")` = year 5000) AND
+  // locale-fragile prose (`Date.parse("July 4")` is finite but is not a date we
+  // want to accept). Canonical dates are ISO (`2026-04-30`), so this never
+  // rejects real data; it only rejects authoring typos.
+  return !isPlainNumber(value) && /[-/T:]/.test(value) && Number.isFinite(Date.parse(value));
+}
+
+/**
+ * Type-aware comparison for a single (un-lowercased) field value against one
+ * resolved RHS alternative. Date-first, then numeric; any non-coercible side
+ * (including empty/unset, type mismatch) yields null (caller → no match). Never
+ * throws. `today` is already resolved to a date string by the caller.
+ * Returns a<0 / 0 / a>0 in the chosen type's space, or null when not comparable.
+ */
+function compareValues(rawField: string, rhs: string): number | null {
+  if (rawField.trim() === "") return null; // empty/unset is "not comparable", never epoch-0
+  // Date comparison when BOTH sides are date-shaped (mirrors compareDate in rules.ts).
+  if (isDateLike(rawField) && isDateLike(rhs)) {
+    return Date.parse(rawField) - Date.parse(rhs);
+  }
+  // Numeric comparison when BOTH sides are plain finite numbers.
+  if (isPlainNumber(rawField) && isPlainNumber(rhs)) {
+    return Number(rawField) - Number(rhs);
+  }
+  return null; // type mismatch / non-parseable → no match (caller returns false)
+}
+
+/**
+ * `today` is threaded from the policy/--today date (default: system date), so
+ * plan-time and apply-time re-verification resolve the literal identically.
+ */
+function matches(view: Record<string, unknown>, clause: WhereClause, today: string): boolean {
   const actual = fieldValue(view, clause.field).toLowerCase();
   // `|` alternation: eq/contains match ANY alternative; neq/notcontains
   // must hold against ALL alternatives.
@@ -123,6 +272,34 @@ function matches(view: Record<string, unknown>, clause: WhereClause): boolean {
       return actual === "";
     case "notempty":
       return actual !== "";
+    // Comparison ops are type-aware and use the RAW (un-lowercased) field
+    // value, not `actual` — lowercasing an ISO date still parses, but the
+    // helper must read from fieldValue() directly (see §6.3 risk 2). `today`
+    // resolves to the threaded policy date. Alternation is OR for all four
+    // (`some`): each alternative is coerced independently; one that fails
+    // coercion contributes false.
+    case "lt":
+    case "gt":
+    case "lte":
+    case "gte": {
+      const rawField = fieldValue(view, clause.field);
+      const rawAlternatives = (clause.value ?? "").split("|");
+      return rawAlternatives.some((a) => {
+        const rhs = a.trim() === "today" ? today : a;
+        const cmp = compareValues(rawField, rhs);
+        if (cmp === null) return false;
+        switch (clause.op) {
+          case "lt":
+            return cmp < 0;
+          case "gt":
+            return cmp > 0;
+          case "lte":
+            return cmp <= 0;
+          case "gte":
+            return cmp >= 0;
+        }
+      });
+    }
   }
 }
 
@@ -232,24 +409,30 @@ export function parseGuard(raw: string): PlanGuard {
   return { objectType: objectType as PlanGuard["objectType"], where, expect: expect as PlanGuard["expect"], description: raw };
 }
 
-/** Ids of records matching a filter — used for apply-time filter re-verification. */
+/**
+ * Ids of records matching a filter — used for apply-time filter
+ * re-verification. `today` resolves the comparison `today` literal; apply-time
+ * callers pass the value the plan was built with (stored on plan.filter.today)
+ * so re-verification uses the SAME today, defaulting to the system date.
+ */
 export function eligibleIds(
   snapshot: CanonicalGtmSnapshot,
   objectType: BulkUpdateOptions["objectType"],
   where: string[],
+  today: string = systemToday(),
 ): Set<string> {
   const clauses = where.map(parseWhere);
   const views = buildViews(snapshot, objectType);
   return new Set(
-    views.filter(({ view }) => clauses.every((c) => matches(view, c))).map(({ record }) => String(record.id)),
+    views.filter(({ view }) => clauses.every((c) => matches(view, c, today))).map(({ record }) => String(record.id)),
   );
 }
 
 /** Evaluate a plan guard against a snapshot. Returns null when satisfied, else a failure detail. */
-export function evaluateGuard(snapshot: CanonicalGtmSnapshot, guard: PlanGuard): string | null {
+export function evaluateGuard(snapshot: CanonicalGtmSnapshot, guard: PlanGuard, today: string = systemToday()): string | null {
   const clauses = guard.where.map(parseWhere);
   const views = buildViews(snapshot, guard.objectType);
-  const matchCount = views.filter(({ view }) => clauses.every((c) => matches(view, c))).length;
+  const matchCount = views.filter(({ view }) => clauses.every((c) => matches(view, c, today))).length;
   const ok = guard.expect === "none" ? matchCount === 0 : matchCount > 0;
   if (ok) return null;
   return `Guard failed: expected ${guard.expect === "none" ? "no" : "at least one"} ${guard.objectType}(s) matching [${guard.where.join(" AND ")}], found ${matchCount}.`;
@@ -260,6 +443,10 @@ export function buildBulkUpdatePlan(
   options: BulkUpdateOptions,
 ): PatchPlan {
   const maxOperations = options.maxOperations ?? 500;
+  // Resolve `today` once: the comparison `today` literal in both --where and
+  // --guard binds to this value at plan time, and it is stored on plan.filter
+  // so apply-time re-verification (eligibleIds) resolves it identically.
+  const today = options.today ?? systemToday();
   if (options.where.length === 0) {
     throw new Error(
       "bulk-update requires at least one --where filter — refusing to build an unscoped mass write.",
@@ -273,6 +460,12 @@ export function buildBulkUpdatePlan(
 
   const clauses = options.where.map(parseWhere);
   assertValidFields(options.objectType, clauses, "--where");
+  // Whether any comparison clause references the `today` literal — drives
+  // whether the resolved `today` is persisted on plan.filter (see below).
+  const isComparisonOp = (op: WhereClause["op"]) => op === "lt" || op === "gt" || op === "lte" || op === "gte";
+  const referencesToday = clauses.some(
+    (c) => isComparisonOp(c.op) && (c.value ?? "").split("|").some((a) => a.trim() === "today"),
+  );
   const WRITABLE_BLOCKLIST = new Set(["id", "crmId", "contactCount", "openDealCount", "openDealStages"]);
   // `from:<sourceField>` values resolve per record from the filter view —
   // the source is validated with the same strictness as filters (relational
@@ -295,7 +488,7 @@ export function buildBulkUpdatePlan(
     }
   }
   const views = buildViews(snapshot, options.objectType);
-  const matched = views.filter(({ view }) => clauses.every((c) => matches(view, c)));
+  const matched = views.filter(({ view }) => clauses.every((c) => matches(view, c, today)));
   if (matched.length > maxOperations) {
     throw new Error(
       `Filter matched ${matched.length} ${COLLECTIONS[options.objectType]} — above the ${maxOperations}-record safety cap. Narrow the --where filter or raise --max-operations explicitly.`,
@@ -461,9 +654,21 @@ export function buildBulkUpdatePlan(
   // guards must hold at plan time too — building a plan whose guard already
   // fails is a footgun, surface it immediately
   for (const guard of guards) {
-    const failure = evaluateGuard(snapshot, guard);
+    const failure = evaluateGuard(snapshot, guard, today);
     if (failure) throw new Error(`${failure} The guard already fails against the current snapshot — the plan would never apply.`);
   }
+  // A `today` literal inside a --guard (not just --where) must also pin
+  // plan.filter.today: connector.ts re-evaluates guards at apply time and,
+  // without the persisted date, would resolve `today` to the apply-day system
+  // date — silently drifting a fail-closed guard. Persist `today` if EITHER a
+  // --where or a --guard clause references the literal.
+  const guardReferencesToday = guards.some((g) =>
+    g.where.some((raw) => {
+      const c = parseWhere(raw);
+      return isComparisonOp(c.op) && (c.value ?? "").split("|").some((a) => a.trim() === "today");
+    }),
+  );
+  const persistToday = referencesToday || guardReferencesToday;
 
   const skippedText = [...skippedBySource.entries()]
     .map(([sourceField, count]) => ` ${count} skipped: empty ${sourceField}.`)
@@ -477,7 +682,18 @@ export function buildBulkUpdatePlan(
     summary: `${matched.length} ${COLLECTIONS[options.objectType]} matched (${whereText}); ${operations.length} proposed dry-run operations (${action}).${skippedText}${guards.length > 0 ? ` ${guards.length} apply-time guard(s).` : ""}`,
     findings: [],
     operations,
-    filter: { objectType: options.objectType, where: options.where },
+    // Persist the resolved `today` ONLY when a filter clause actually
+    // references the `today` literal, so apply-time re-verification (eligibleIds
+    // in connector.ts) resolves it to the same date the plan was built with —
+    // the apply command carries no --today of its own. Plans without `today`
+    // (the vast majority — equality filters, reassign, etc.) keep the original
+    // `{ objectType, where }` shape unchanged; eligibleIds defaults to the
+    // system date for them, which never affects a non-`today` filter.
+    filter: {
+      objectType: options.objectType,
+      where: options.where,
+      ...(persistToday ? { today } : {}),
+    },
     ...(guards.length > 0 ? { guards } : {}),
   };
 }

package/src/cli.ts

@@ -35,6 +35,7 @@ import { generateDemoSnapshot } from "./demo.ts";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 import { mergeSnapshots } from "./merge.ts";
 import { verifyApprovalDigests } from "./integrity.ts";
+import { buildAuditLog, verifyAuditLog } from "./auditLog.ts";
 import { createFilePlanStore } from "./planStore.ts";
 import { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 import { builtinAuditRules } from "./rules.ts";
@@ -254,6 +255,7 @@ Usage:
   fullstackgtm plans approve <id> --values-from <suggestions.json> [--min-confidence high|low] [--include-creates]
   fullstackgtm apply --plan-id <id> --provider <name>
   fullstackgtm apply --plan <path> --provider <name> --approve <ids|all> [options]
+  fullstackgtm audit-log export [--out <path>] | verify --in <path>   tamper-evident apply-run record
   fullstackgtm rules [--json]
   fullstackgtm profiles [--json]               list credential profiles
   fullstackgtm doctor [--json]                 check install, credentials, and next step
@@ -2280,6 +2282,9 @@ async function bulkUpdateCommand(args: string[]) {
     guard: repeatedOption(rest, "--guard"),
     reason: option(rest, "--reason") ?? undefined,
     maxOperations: numericOption(rest, "--max-operations"),
+    // --today resolves the comparison `today` literal (e.g. closeDate<today);
+    // defaults to the system date inside buildBulkUpdatePlan when omitted.
+    today: option(rest, "--today") ?? undefined,
   });
   await emitPlan(plan, rest);
 }
@@ -2558,6 +2563,50 @@ function readSuggestionValues(path: string, minConfidence: string, includeCreate
   return { overrides, skipped };
 }
 
+async function auditLogCommand(args: string[]) {
+  const [sub, ...rest] = args;
+  if (!sub || sub === "--help" || sub === "-h" || (sub !== "export" && sub !== "verify")) {
+    console.log(`Usage:
+audit-log export [--out <path>] [--json]   hash-chained, signed record of every apply run
+audit-log verify [--in <path>]             re-check an exported log's chain and signature
+
+export flattens every apply run across all stored plans (this profile) into a
+tamper-evident chain — each entry carries the prior entry's hash, and the chain
+head is HMAC-signed with this install's key — so a change-management process can
+archive one file and later prove it was not edited. verify recomputes the chain
+and (if the signing key is present) the signature.`);
+    return;
+  }
+
+  if (sub === "export") {
+    const plans = await createFilePlanStore().list();
+    const log = buildAuditLog(plans, new Date().toISOString());
+    const payload = `${JSON.stringify(log, null, 2)}\n`;
+    const outPath = option(rest, "--out");
+    if (outPath) {
+      writeFileSync(resolve(process.cwd(), outPath), payload);
+      console.log(`Wrote ${outPath}: ${log.entryCount} run(s), chain head ${log.chainHead.slice(0, 12)}${log.signature ? " (signed)" : " (unsigned — no signing key on this install)"}.`);
+    } else if (rest.includes("--json")) {
+      console.log(payload);
+    } else {
+      console.log(`${log.entryCount} apply run(s); chain head ${log.chainHead.slice(0, 12)}${log.signature ? ", signed" : ", unsigned"}. Pass --out <path> to archive, or --json to print.`);
+    }
+    return;
+  }
+
+  // verify
+  const inPath = option(rest, "--in");
+  if (!inPath) throw new Error("audit-log verify requires --in <exported-log.json>");
+  const log = JSON.parse(readFileSync(resolve(process.cwd(), inPath), "utf8")) as Parameters<typeof verifyAuditLog>[0];
+  const result = verifyAuditLog(log);
+  if (rest.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(result.ok ? `OK — ${result.detail}` : `TAMPERED — ${result.detail}`);
+  }
+  if (!result.ok) process.exitCode = 2;
+}
+
 async function apply(args: string[]) {
   const provider = option(args, "--provider");
   if (!provider) throw new Error("apply requires --provider <name>");
@@ -2899,7 +2948,31 @@ function rejectArgvSecret(args: string[], ...flags: string[]) {
   }
 }
 
+/**
+ * The broker channel carries a long-lived pairing bearer and receives freshly
+ * minted live-CRM tokens, so it must be TLS unless it's an explicit localhost
+ * dev target. Refuse http:// (and non-http schemes) otherwise — single-quote
+ * shell escaping does nothing for a token sent in cleartext.
+ */
+export function assertSecureBrokerUrl(raw: string): URL {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`--via must be a full URL (e.g. https://gtm.yourco.com), got "${raw}".`);
+  }
+  const isLocalhost =
+    url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
+  if (url.protocol === "https:") return url;
+  if (url.protocol === "http:" && isLocalhost) return url; // local dev only
+  throw new Error(
+    `Refusing to pair over ${url.protocol}//${url.host}: the broker exchanges a long-lived token and mints live CRM ` +
+      "credentials, so it must use https (http is allowed only for localhost dev).",
+  );
+}
+
 async function brokerLogin(baseUrl: string) {
+  const viaUrl = assertSecureBrokerUrl(baseUrl);
   const base = baseUrl.replace(/\/$/, "");
   const os = await import("node:os");
   // Self-reported, shown to the approver so they can recognize this request
@@ -2922,10 +2995,22 @@ async function brokerLogin(baseUrl: string) {
     );
   }
   const start = await startResponse.json();
+  // Only auto-open a verification URL that belongs to the --via origin the user
+  // typed — a malicious/typo'd deployment cannot redirect the browser elsewhere.
+  let sameOrigin = false;
+  try {
+    sameOrigin = new URL(start.verificationUrl).origin === viaUrl.origin;
+  } catch {
+    sameOrigin = false;
+  }
   console.error(
     `\nPairing code: ${start.userCode}\n\nApprove this CLI ("${requesterLabel}") in your dashboard:\n\n  ${start.verificationUrl}\n`,
   );
-  void openInBrowser(start.verificationUrl);
+  if (sameOrigin) {
+    void openInBrowser(start.verificationUrl);
+  } else {
+    console.error(`(Not auto-opening: the verification URL is not on ${viaUrl.origin}. Open it manually only if you trust it.)`);
+  }
 
   const deadline = Date.now() + (start.expiresInSeconds ?? 600) * 1000;
   const intervalMs = Math.max(0, (start.intervalSeconds ?? 3) * 1000);
@@ -3416,6 +3501,10 @@ export async function runCli(argv: string[]) {
     await plansCommand(args);
     return;
   }
+  if (command === "audit-log") {
+    await auditLogCommand(args);
+    return;
+  }
   if (command === "apply") {
     await apply(args);
     return;

package/src/connector.ts

@@ -170,7 +170,11 @@ export async function applyPatchPlan(
     const { evaluateGuard, eligibleIds } = await import("./bulkUpdate.ts");
     const liveSnapshot = await connector.fetchSnapshot!();
     if (plan.filter) {
-      const stillEligible = eligibleIds(liveSnapshot, plan.filter.objectType, plan.filter.where);
+      // Resolve the comparison `today` literal to the date the plan was built
+      // with (stored on plan.filter), so apply-time re-verification of a
+      // `closeDate<today`-style filter agrees with plan time. eligibleIds
+      // defaults to the system date when the plan predates comparison ops.
+      const stillEligible = eligibleIds(liveSnapshot, plan.filter.objectType, plan.filter.where, plan.filter.today);
       staleIds.clear();
       for (const operation of plan.operations) {
         if (!stillEligible.has(operation.objectId)) staleIds.add(operation.objectId);
@@ -185,7 +189,7 @@ export async function applyPatchPlan(
       }
     }
     for (const guard of plan.guards ?? []) {
-      const failure = evaluateGuard(liveSnapshot, guard);
+      const failure = evaluateGuard(liveSnapshot, guard, plan.filter?.today);
       if (failure) {
         guardFailure = failure;
         return;

package/src/credentials.ts

@@ -8,10 +8,12 @@ import {
   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 { detectKeychainBackend } from "./keychain.ts";
 
 /**
  * Local CLI credential store: ~/.fullstackgtm/credentials.json (0600), or
@@ -166,19 +168,71 @@ function enforceCredentialFileMode(path: string): void {
   }
 }
 
+/**
+ * Persistence backend for the credential blob: the OS keychain when
+ * FSGTM_KEYCHAIN=1 and one is available, otherwise the 0600 file. The keychain
+ * account is derived from the credential file path so distinct homes/profiles
+ * never collide in the machine-wide store.
+ */
+function activeKeychain(): { account: string; backend: NonNullable<ReturnType<typeof detectKeychainBackend>> } | null {
+  if (process.env.FSGTM_KEYCHAIN !== "1") return null;
+  const backend = detectKeychainBackend();
+  if (!backend) return null;
+  return { account: createHash("sha256").update(credentialsPath()).digest("hex").slice(0, 24), backend };
+}
+
+/**
+ * When keychain is enabled on an install that previously wrote a plaintext
+ * credentials.json, that file would otherwise sit on disk forever (readFile only
+ * looks at the keychain). Import it into the keychain and remove it — the whole
+ * point of keychain mode is that no plaintext credential remains at rest.
+ */
+function migratePlaintextToKeychain(keychain: NonNullable<ReturnType<typeof activeKeychain>>): void {
+  if (!existsSync(credentialsPath())) return;
+  try {
+    const fileParsed = JSON.parse(readFileSync(credentialsPath(), "utf8"));
+    if (fileParsed && fileParsed.version === 1 && fileParsed.providers) {
+      const current = keychain.backend.get(keychain.account);
+      const existing = current ? (JSON.parse(current).providers ?? {}) : {};
+      // Keychain entries win over the file on conflict (the file is the older copy).
+      const merged = { version: 1 as const, providers: { ...fileParsed.providers, ...existing } };
+      keychain.backend.set(keychain.account, `${JSON.stringify(merged, null, 2)}\n`);
+    }
+    unlinkSync(credentialsPath());
+    console.error("fullstackgtm: migrated credentials.json into the OS keychain and removed the plaintext file.");
+  } catch {
+    // Best effort: a malformed/locked file is left in place rather than lost.
+  }
+}
+
 function readFile(): CredentialsFile {
+  const keychain = activeKeychain();
+  if (keychain) migratePlaintextToKeychain(keychain);
   try {
-    enforceCredentialFileMode(credentialsPath());
-    const parsed = JSON.parse(readFileSync(credentialsPath(), "utf8"));
-    if (parsed && typeof parsed === "object" && parsed.version === 1 && parsed.providers) {
-      return parsed as CredentialsFile;
+    const raw = keychain ? keychain.backend.get(keychain.account) : (enforceCredentialFileMode(credentialsPath()), readFileSync(credentialsPath(), "utf8"));
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && parsed.version === 1 && parsed.providers) {
+        return parsed as CredentialsFile;
+      }
     }
   } catch {
-    // Missing or unreadable file falls through to an empty store.
+    // Missing or unreadable store falls through to an empty one.
   }
   return { version: 1, providers: {} };
 }
 
+function persist(file: CredentialsFile): void {
+  const keychain = activeKeychain();
+  const blob = `${JSON.stringify(file, null, 2)}\n`;
+  if (keychain) {
+    keychain.backend.set(keychain.account, blob);
+  } else {
+    ensureSecureHomeDir();
+    writeSecureFile(credentialsPath(), blob);
+  }
+}
+
 export function getCredential(provider: string): StoredCredential | null {
   return readFile().providers[provider] ?? null;
 }
@@ -186,19 +240,28 @@ export function getCredential(provider: string): StoredCredential | null {
 export function storeCredential(provider: string, credential: StoredCredential) {
   const file = readFile();
   file.providers[provider] = credential;
-  ensureSecureHomeDir();
-  writeSecureFile(credentialsPath(), `${JSON.stringify(file, null, 2)}\n`);
+  persist(file);
 }
 
 export function deleteCredential(provider: string): boolean {
   const file = readFile();
   if (!file.providers[provider]) return false;
   delete file.providers[provider];
-  if (Object.keys(file.providers).length === 0 && existsSync(credentialsPath())) {
-    unlinkSync(credentialsPath());
-    return true;
+  const keychain = activeKeychain();
+  if (Object.keys(file.providers).length === 0) {
+    if (keychain) {
+      keychain.backend.delete(keychain.account);
+      // Defensive: remove any leftover plaintext file too (migration normally
+      // already did, but never leave a credential blob on disk after logout).
+      if (existsSync(credentialsPath())) unlinkSync(credentialsPath());
+      return true;
+    }
+    if (existsSync(credentialsPath())) {
+      unlinkSync(credentialsPath());
+      return true;
+    }
   }
-  writeSecureFile(credentialsPath(), `${JSON.stringify(file, null, 2)}\n`);
+  persist(file);
   return true;
 }
 
@@ -299,6 +362,14 @@ async function brokerMint(
 ): Promise<{ accessToken: string; instanceUrl?: string; fieldMappings?: unknown } | null> {
   const broker = getCredential("broker");
   if (!broker?.baseUrl) return null;
+  // The mint replays the long-lived bearer and receives a live CRM token —
+  // refuse to do so over cleartext even if a tampered store points us at http.
+  const brokerUrl = new URL(broker.baseUrl);
+  const localhost =
+    brokerUrl.hostname === "localhost" || brokerUrl.hostname === "127.0.0.1" || brokerUrl.hostname === "::1" || brokerUrl.hostname === "[::1]";
+  if (brokerUrl.protocol !== "https:" && !(brokerUrl.protocol === "http:" && localhost)) {
+    throw new Error(`Refusing to mint a CRM token over ${brokerUrl.protocol}//${brokerUrl.host} — the broker must use https. Re-pair with an https deployment.`);
+  }
   const fetchImpl = options.fetchImpl ?? fetch;
   const response = await fetchImpl(`${broker.baseUrl.replace(/\/$/, "")}/api/cli/token`, {
     method: "POST",

package/src/index.ts

@@ -123,6 +123,13 @@ export {
   verifyApprovalDigests,
   type ApprovalVerification,
 } from "./integrity.ts";
+export {
+  buildAuditLog,
+  verifyAuditLog,
+  type AuditLogEntry,
+  type AuditLogExport,
+  type AuditLogVerification,
+} from "./auditLog.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export {