gatefit 0.0.0-stage → 0.5.0

package/src/chaos.ts

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import type { AccessSnapshot, BillingEvent } from "./access-adapter.ts";
+import { loadAdapter } from "./access-adapter.ts";
+import { listGoldens, loadGolden } from "./fixture-driver.ts";
+import type { GoldenSuite } from "./fixture-driver.ts";
+import { registerProPack } from "./packs.ts";
+import { goldenDir, resolveUserOrPackage } from "./paths.ts";
+
+export const CHAOS_DEFAULT_SEED = "1";
+
+const PERTURBATIONS = [
+  "duplicate",
+  "reorder",
+  "stale",
+  "late",
+  "dropped_replay",
+  "checkout_return",
+] as const;
+
+type Perturbation = (typeof PERTURBATIONS)[number];
+
+export function resolveChaosSeed(flag: string | undefined, envValue: string | undefined): string {
+  const raw = flag !== undefined ? flag : envValue;
+  const trimmed = (raw ?? "").trim();
+  return trimmed.length > 0 ? trimmed : CHAOS_DEFAULT_SEED;
+}
+
+function pickIndex(seed: string, goldenId: string, kind: string, salt: string, n: number): number {
+  const digest = createHash("sha256").update(`${seed}\0${goldenId}\0${kind}\0${salt}`).digest();
+  return digest.readUInt32BE(0) % n;
+}
+
+function cloneEvents(events: BillingEvent[]): BillingEvent[] {
+  return events.map((event) => ({ ...event }));
+}
+
+function stamp(suite: GoldenSuite): BillingEvent[] {
+  return suite.steps.map((step, index) => ({ ...step.event, created: index }));
+}
+
+function duplicate(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "duplicate", "i", next.length);
+  next.push({ ...next[index]! });
+  return next;
+}
+
+function reorder(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  if (next.length < 2) return next;
+  const left = pickIndex(seed, goldenId, "reorder", "a", next.length);
+  let right = pickIndex(seed, goldenId, "reorder", "b", next.length);
+  if (left === right) right = (right + 1) % next.length;
+  const swap = next[left]!;
+  next[left] = next[right]!;
+  next[right] = swap;
+  return next;
+}
+
+function moveToEnd(events: BillingEvent[], index: number): BillingEvent[] {
+  const next = cloneEvents(events);
+  const [picked] = next.splice(index, 1);
+  next.push(picked!);
+  return next;
+}
+
+function stale(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  if (events.length < 2) return cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "stale", "i", events.length - 1);
+  return moveToEnd(events, index);
+}
+
+function late(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  if (events.length < 2) return cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "late", "i", events.length);
+  return moveToEnd(events, index);
+}
+
+function droppedReplay(seed: string, goldenId: string, events: BillingEvent[]): BillingEvent[] {
+  const next = cloneEvents(events);
+  const index = pickIndex(seed, goldenId, "dropped_replay", "i", next.length);
+  next.splice(index, 1);
+  return [...next, ...cloneEvents(events)];
+}
+
+function checkoutReturn(suite: GoldenSuite, events: BillingEvent[]): BillingEvent[] {
+  const page: BillingEvent = {
+    id: `evt_chaos_checkout_${suite.id}`,
+    type: "checkout.session.completed",
+    customerId: suite.subject,
+    httpStatus: 200,
+    stripeHttpStatus: 200,
+    created: -1,
+  };
+  return [page, ...cloneEvents(events)];
+}
+
+function perturb(kind: Perturbation, seed: string, suite: GoldenSuite, events: BillingEvent[]): BillingEvent[] {
+  if (kind === "duplicate") return duplicate(seed, suite.id, events);
+  if (kind === "reorder") return reorder(seed, suite.id, events);
+  if (kind === "stale") return stale(seed, suite.id, events);
+  if (kind === "late") return late(seed, suite.id, events);
+  if (kind === "dropped_replay") return droppedReplay(seed, suite.id, events);
+  return checkoutReturn(suite, events);
+}
+
+function stableSnapshot(snapshot: AccessSnapshot): string {
+  const keys = (Object.keys(snapshot) as (keyof AccessSnapshot)[])
+    .filter((key) => snapshot[key] !== undefined)
+    .sort();
+  const ordered: Record<string, unknown> = {};
+  for (const key of keys) ordered[key] = snapshot[key];
+  return JSON.stringify(ordered);
+}
+
+async function replay(
+  adapter: { apply: (event: BillingEvent) => void | Promise<void>; snapshot: (id: string) => AccessSnapshot | Promise<AccessSnapshot>; reset?: () => void | Promise<void> },
+  subject: string,
+  events: BillingEvent[],
+): Promise<AccessSnapshot> {
+  if (adapter.reset) await adapter.reset();
+  for (const event of events) await adapter.apply(event);
+  return adapter.snapshot(subject);
+}
+
+function fail(seed: string, goldenId: string, kind: Perturbation, events: BillingEvent[], expected: string, actual: string): void {
+  console.error(`gatefit: FAIL chaos ${goldenId} perturbation ${kind}`);
+  console.error(`seed: ${seed}`);
+  console.error("repro:");
+  for (const event of events) console.error(JSON.stringify(event));
+  console.error(`access: expected ${expected} got ${actual}`);
+}
+
+export async function runChaos(adapterPath: string, seed: string): Promise<number> {
+  console.error(`gatefit chaos: seed ${seed}`);
+  if (process.env.GATEFIT_LIVE_CLOCK) {
+    console.error("gatefit chaos: refuses GATEFIT_LIVE_CLOCK; fixture order only");
+    return 1;
+  }
+  const adapter = await loadAdapter(resolveUserOrPackage(adapterPath));
+  if (typeof adapter.reset !== "function") {
+    console.error("gatefit chaos: adapter.reset is required");
+    return 1;
+  }
+  const files = listGoldens(goldenDir());
+  for (const file of files) {
+    const suite = loadGolden(file);
+    const ordered = stamp(suite);
+    const expected = stableSnapshot(await replay(adapter, suite.subject, ordered));
+    for (const kind of PERTURBATIONS) {
+      const events = perturb(kind, seed, suite, ordered);
+      const actual = stableSnapshot(await replay(adapter, suite.subject, events));
+      if (actual !== expected) {
+        fail(seed, suite.id, kind, events, expected, actual);
+        return 1;
+      }
+    }
+    console.error(`gatefit: PASS chaos ${suite.id}`);
+  }
+  console.error("gatefit: PASS chaos");
+  return 0;
+}
+
+registerProPack({
+  id: "chaos",
+  run({ adapterPath, seed }) {
+    return runChaos(adapterPath, seed);
+  },
+});

package/src/cli.ts

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { loadAdapter } from "./access-adapter.ts";
+import { listGoldens, loadGolden, requireReset, runGolden } from "./fixture-driver.ts";
+import { LIVE_SCENARIO_IDS, runLiveLane, type LiveScenarioId } from "./live-scenarios.ts";
+import { resolveChaosSeed } from "./chaos.ts";
+import { ensureProLicense } from "./license.ts";
+import { getProPack, isProPack } from "./packs.ts";
+import { goldenDir, packageRoot, readPackageVersion, resolveUserOrPackage, userCwd } from "./paths.ts";
+import {
+  createStripeClockClient,
+  requireLiveClockEnabled,
+  requireTestModeSecret,
+} from "./stripe-clock.ts";
+
+const S1 = () => path.join(goldenDir(), "paid_grants_access.yaml");
+const NAIVE = () => path.join(packageRoot(), "src/adapters/naive.ts");
+const HARDENED = () => path.join(packageRoot(), "src/adapters/hardened.ts");
+
+function usage(): string {
+  return [
+    "Usage:",
+    "  gatefit run --suite <dir|file|id> --adapter <path>",
+    "  gatefit run --suite chaos --adapter <path> [--seed <value>]",
+    "  gatefit adapter-check",
+    "  gatefit live --adapter <path> [--scenario <id>]",
+    "  gatefit --version",
+  ].join("\n");
+}
+
+function resolveSuiteFiles(suite: string): string[] {
+  const candidates = [
+    path.resolve(userCwd(), suite),
+    path.resolve(packageRoot(), suite),
+    path.join(goldenDir(), `${suite}.yaml`),
+  ];
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) continue;
+    const files = listGoldens(candidate);
+    if (files.length > 0) return files;
+  }
+  throw new Error(`suite not found: ${suite}`);
+}
+
+async function cmdRun(suite: string, adapterPath: string, seed: string): Promise<number> {
+  if (isProPack(suite)) {
+    const gate = await ensureProLicense();
+    if (!gate.ok) {
+      console.error(gate.message);
+      return 1;
+    }
+    if (gate.warning) console.error(gate.warning);
+    const pack = getProPack(suite);
+    if (pack?.run) return pack.run({ adapterPath, seed });
+    console.error(`gatefit: PASS ${suite}`);
+    return 0;
+  }
+  const adapter = await loadAdapter(resolveUserOrPackage(adapterPath));
+  const files = resolveSuiteFiles(suite);
+  if (files.length === 0) {
+    throw new Error(`suite not found: ${suite}`);
+  }
+  requireReset(adapter, files.length);
+  let failed = 0;
+  for (const file of files) {
+    const golden = loadGolden(file);
+    const result = await runGolden(adapter, golden);
+    if (result.ok) {
+      console.error(`gatefit: PASS ${golden.id}`);
+    } else {
+      failed += 1;
+      console.error(`gatefit: FAIL ${golden.id}`);
+      for (const step of result.results.filter((s) => !s.ok)) {
+        console.error(`  step ${step.stepIndex}: ${step.mismatches.join("; ")}`);
+      }
+    }
+  }
+  return failed === 0 ? 0 : 1;
+}
+
+async function cmdAdapterCheck(): Promise<number> {
+  const suite = loadGolden(S1());
+  const naive = await runGolden(await loadAdapter(NAIVE()), suite);
+  const hardened = await runGolden(await loadAdapter(HARDENED()), suite);
+  const naiveFailed = !naive.ok;
+  const hardenedPassed = hardened.ok;
+  if (naiveFailed) console.error("gatefit adapter-check: naive failed S1 (expected)");
+  else console.error("gatefit adapter-check: naive unexpectedly passed S1");
+  if (hardenedPassed) console.error("gatefit adapter-check: hardened passed S1 (expected)");
+  else console.error("gatefit adapter-check: hardened failed S1");
+  return naiveFailed && hardenedPassed ? 0 : 1;
+}
+
+function isVersionFlag(arg: string | undefined): boolean {
+  return arg === "--version" || arg === "-v";
+}
+
+async function main(argv: string[]): Promise<number> {
+  if (isVersionFlag(argv[0])) {
+    console.log(`gatefit ${readPackageVersion()}`);
+    return 0;
+  }
+  const command = argv[0];
+  if (command === "adapter-check") {
+    return cmdAdapterCheck();
+  }
+  if (command === "run") {
+    const { values } = parseArgs({
+      args: argv.slice(1),
+      options: {
+        suite: { type: "string" },
+        adapter: { type: "string" },
+        seed: { type: "string" },
+      },
+    });
+    if (!values.suite || !values.adapter) {
+      console.error(usage());
+      return 1;
+    }
+    return cmdRun(values.suite, values.adapter, resolveChaosSeed(values.seed, process.env.GATEFIT_CHAOS_SEED));
+  }
+  if (command === "live") {
+    const { values } = parseArgs({
+      args: argv.slice(1),
+      options: {
+        adapter: { type: "string" },
+        scenario: { type: "string" },
+      },
+    });
+    if (!values.adapter) {
+      console.error(usage());
+      return 1;
+    }
+    requireLiveClockEnabled();
+    const secret = requireTestModeSecret();
+    const adapter = await loadAdapter(resolveUserOrPackage(values.adapter));
+    const client = createStripeClockClient({ secret });
+    let scenarios: LiveScenarioId[] | undefined;
+    if (values.scenario) {
+      if (!(LIVE_SCENARIO_IDS as readonly string[]).includes(values.scenario)) {
+        throw new Error(`unknown live scenario: ${values.scenario}`);
+      }
+      scenarios = [values.scenario as LiveScenarioId];
+    }
+    const result = await runLiveLane(adapter, client, { scenarios });
+    for (const row of result.results) {
+      if (row.ok) console.error(`gatefit live: PASS ${row.id}`);
+      else {
+        console.error(`gatefit live: FAIL ${row.id}`);
+        for (const mismatch of row.mismatches) console.error(`  ${mismatch}`);
+      }
+    }
+    return result.ok ? 0 : 1;
+  }
+  console.error(usage());
+  return 1;
+}
+
+try {
+  const code = await main(process.argv.slice(2));
+  process.exit(code);
+} catch (err) {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+}

package/src/clock-driver.ts

@@ -0,0 +1,52 @@
+import {
+  assertAdvanceWithinTwoIntervals,
+  MONTH_SECONDS,
+  type StripeClockClient,
+  type TestClock,
+} from "./stripe-clock.ts";
+
+export type ClockWaitOpts = {
+  sleep?: (ms: number) => Promise<void>;
+  timeoutMs?: number;
+  intervalMs?: number;
+};
+
+export async function withTestClock<T>(
+  client: StripeClockClient,
+  input: { frozenTime: number; name?: string },
+  fn: (clock: TestClock) => Promise<T>,
+): Promise<T> {
+  const clock = await client.createClock(input);
+  try {
+    return await fn(clock);
+  } finally {
+    const deleted = await client.deleteClock(clock.id);
+    if (!deleted?.deleted) {
+      throw new Error(`clock leak: failed to delete ${clock.id}`);
+    }
+  }
+}
+
+export async function advanceUntilReady(
+  client: StripeClockClient,
+  clockId: string,
+  frozenTime: number,
+  opts: ClockWaitOpts = {},
+): Promise<TestClock> {
+  const current = await client.retrieveClock(clockId);
+  assertAdvanceWithinTwoIntervals(current.frozen_time, frozenTime, MONTH_SECONDS);
+  await client.advanceClock(clockId, frozenTime);
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const timeoutMs = opts.timeoutMs ?? 120_000;
+  const intervalMs = opts.intervalMs ?? 500;
+  const deadline = Date.now() + timeoutMs;
+  let clock = await client.retrieveClock(clockId);
+  while (clock.status !== "ready") {
+    if (Date.now() > deadline) {
+      throw new Error(`clock ${clockId} did not become ready before timeout`);
+    }
+    await sleep(intervalMs);
+    clock = await client.retrieveClock(clockId);
+  }
+  return clock;
+}

package/src/fixture-driver.ts

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import {
+  type AccessAdapter,
+  type AccessSnapshot,
+  type BillingEvent,
+  compareAccess,
+} from "./access-adapter.ts";
+
+export type GoldenStep = {
+  event: BillingEvent;
+  expect: AccessSnapshot;
+};
+
+export type GoldenSuite = {
+  id: string;
+  subject: string;
+  steps: GoldenStep[];
+};
+
+export type StepResult = {
+  stepIndex: number;
+  ok: boolean;
+  expected: AccessSnapshot;
+  actual: AccessSnapshot;
+  mismatches: string[];
+};
+
+export function loadGolden(filePath: string): GoldenSuite {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const data = parseYaml(raw) as GoldenSuite;
+  if (!data?.id || !data.subject || !Array.isArray(data.steps) || data.steps.length === 0) {
+    throw new Error(`invalid golden: ${filePath} (id, subject, and non-empty steps required)`);
+  }
+  return data;
+}
+
+export function requireReset(adapter: AccessAdapter, suiteCount: number): void {
+  if (suiteCount > 1 && typeof adapter.reset !== "function") {
+    throw new Error("adapter.reset is required when running more than one golden");
+  }
+}
+
+export function listGoldens(suitePath: string): string[] {
+  const resolved = path.resolve(suitePath);
+  const stat = fs.statSync(resolved);
+  if (stat.isDirectory()) {
+    return fs
+      .readdirSync(resolved)
+      .filter((name) => name.endsWith(".yaml") || name.endsWith(".yml"))
+      .map((name) => path.join(resolved, name))
+      .sort();
+  }
+  return [resolved];
+}
+
+export async function runGolden(
+  adapter: AccessAdapter,
+  suite: GoldenSuite,
+): Promise<{
+  ok: boolean;
+  results: StepResult[];
+}> {
+  if (process.env.GATEFIT_LIVE_CLOCK) {
+    throw new Error("fixture-first driver refuses GATEFIT_LIVE_CLOCK; use YAML step order only");
+  }
+  if (adapter.reset) await adapter.reset();
+  const results: StepResult[] = [];
+  for (let i = 0; i < suite.steps.length; i += 1) {
+    const step = suite.steps[i]!;
+    await adapter.apply(step.event);
+    const actual = await adapter.snapshot(step.event.customerId ?? suite.subject);
+    const cmp = compareAccess(actual, step.expect);
+    results.push({
+      stepIndex: i,
+      ok: cmp.ok,
+      expected: step.expect,
+      actual,
+      mismatches: cmp.mismatches,
+    });
+  }
+  return { ok: results.every((r) => r.ok), results };
+}

package/src/license.ts

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Public Polar customer-portal validate endpoint. No API token. */
+export const POLAR_LICENSE_VALIDATE_URL =
+  "https://api.polar.sh/v1/customer-portal/license-keys/validate";
+
+/** Gatefit organization id from the public Indie License checkout. */
+export const POLAR_ORGANIZATION_ID = "68556619-45ab-4a88-8ad8-08606c2b820e";
+
+/** Indie License benefit id. Scopes validation to that benefit. */
+export const POLAR_BENEFIT_ID = "4e8e6528-a979-4060-b675-7686c752a4a2";
+
+export const LICENSE_BUY_URL = "https://gatefit.io/#pricing";
+
+/** Fresh cache entries skip the network. Older entries still count when Polar is down. */
+export const LICENSE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+const KEY_PREFIX = "GATEFIT-";
+
+export type LicenseDecision =
+  | { ok: true; warning?: string }
+  | { ok: false; message: string };
+
+type CacheEntry = { granted: true; cachedAt: number };
+type CacheFile = { v: 1; entries: Record<string, CacheEntry> };
+
+function buy(reason: string): string {
+  return `gatefit: ${reason} Buy the Indie License: ${LICENSE_BUY_URL}`;
+}
+
+function cachePath(env: NodeJS.ProcessEnv): string {
+  return env.GATEFIT_LICENSE_CACHE ?? path.join(os.homedir(), ".gatefit", "license-cache.json");
+}
+
+function hashKey(key: string): string {
+  return createHash("sha256").update(key).digest("hex");
+}
+
+function emptyCache(): CacheFile {
+  return { v: 1, entries: {} };
+}
+
+function readCache(file: string): CacheFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as CacheFile;
+    if (parsed?.v !== 1 || !parsed.entries || typeof parsed.entries !== "object") return emptyCache();
+    return parsed;
+  } catch {
+    return emptyCache();
+  }
+}
+
+function writeCache(file: string, cache: CacheFile): void {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `.license-cache-${process.pid}.tmp`);
+  fs.writeFileSync(tmp, JSON.stringify(cache), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, 0o600);
+}
+
+function remember(file: string, key: string): void {
+  const cache = readCache(file);
+  cache.entries[hashKey(key)] = { granted: true, cachedAt: Date.now() };
+  writeCache(file, cache);
+}
+
+function forget(file: string, key: string): void {
+  const cache = readCache(file);
+  delete cache.entries[hashKey(key)];
+  try {
+    writeCache(file, cache);
+  } catch {
+    /* a failed delete must not print the key */
+  }
+}
+
+function cachedGrant(file: string, key: string): CacheEntry | undefined {
+  const entry = readCache(file).entries[hashKey(key)];
+  if (!entry || entry.granted !== true || typeof entry.cachedAt !== "number") return undefined;
+  return entry;
+}
+
+function validateUrl(env: NodeJS.ProcessEnv): string {
+  return env.GATEFIT_LICENSE_VALIDATE_URL || POLAR_LICENSE_VALIDATE_URL;
+}
+
+type PolarVerdict = "granted" | "revoked" | "invalid" | "unreachable";
+
+async function askPolar(key: string, env: NodeJS.ProcessEnv): Promise<PolarVerdict> {
+  try {
+    const response = await fetch(validateUrl(env), {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({
+        key,
+        organization_id: POLAR_ORGANIZATION_ID,
+        benefit_id: POLAR_BENEFIT_ID,
+      }),
+      signal: AbortSignal.timeout(4000),
+    });
+    const text = await response.text();
+    let payload: { status?: unknown; error?: unknown; detail?: unknown } = {};
+    try {
+      payload = JSON.parse(text) as typeof payload;
+    } catch {
+      return response.status >= 500 ? "unreachable" : "invalid";
+    }
+    const status = typeof payload.status === "string" ? payload.status : "";
+    const detail = `${payload.error ?? ""} ${payload.detail ?? ""}`;
+    if (response.status >= 500) return "unreachable";
+    if (status === "granted" && response.ok) return "granted";
+    if (status === "revoked" || /revok/i.test(detail)) return "revoked";
+    if (response.status === 404) return "invalid";
+    return "invalid";
+  } catch {
+    return "unreachable";
+  }
+}
+
+export async function ensureProLicense(env: NodeJS.ProcessEnv = process.env): Promise<LicenseDecision> {
+  const key = env.GATEFIT_LICENSE_KEY?.trim() ?? "";
+  if (!key) {
+    return { ok: false, message: buy("Pro pack requires GATEFIT_LICENSE_KEY.") };
+  }
+  if (!key.startsWith(KEY_PREFIX)) {
+    return { ok: false, message: buy("GATEFIT_LICENSE_KEY is not valid.") };
+  }
+
+  const file = cachePath(env);
+  const cached = cachedGrant(file, key);
+  if (cached && Date.now() - cached.cachedAt < LICENSE_CACHE_TTL_MS) {
+    return { ok: true };
+  }
+
+  const verdict = await askPolar(key, env);
+  if (verdict === "granted") {
+    try {
+      remember(file, key);
+    } catch {
+      /* running does not depend on writing the cache */
+    }
+    return { ok: true };
+  }
+  if (verdict === "revoked") {
+    forget(file, key);
+    return { ok: false, message: buy("GATEFIT_LICENSE_KEY is revoked.") };
+  }
+  if (verdict === "invalid") {
+    forget(file, key);
+    return { ok: false, message: buy("GATEFIT_LICENSE_KEY is not valid.") };
+  }
+  if (cached) {
+    return { ok: true, warning: "gatefit: Polar license check unreachable; using cached valid result" };
+  }
+  return { ok: true, warning: "gatefit: Polar license check unreachable; running without a cached license" };
+}