Skip to content
Python
6.3 KB
Raw Blame
// What a hosted Freefield allows: a passcode at the door and a cap on runs. Off unless configured.
//   FREEFIELD_PASSCODE          every request needs it: once as ?key=… (it becomes a cookie), or the form at /
//   FREEFIELD_MAX_RUNS_PER_DAY  runs started per UTC day across all visitors (counted in <out>/limits.json)
//   FREEFIELD_MAX_ACTIVE        runs going at the same time
// Running locally with none of these set, nothing changes.
import { createHmac, timingSafeEqual } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";

export type GuardOptions = {
  passcode?: string;
  maxRunsPerDay?: number;
  maxActive?: number;
  stateFile?: string;
  now?: () => Date;
};

const COOKIE = "ff_key";

export class Guard {
  readonly passcode?: string;
  readonly maxRunsPerDay?: number;
  readonly maxActive?: number;
  private readonly stateFile?: string;
  private readonly now: () => Date;
  private readonly cookieValue?: string;
  private state: { day: string; runs: number };

  constructor(opts: GuardOptions = {}) {
    this.passcode = opts.passcode || undefined;
    this.maxRunsPerDay = opts.maxRunsPerDay && opts.maxRunsPerDay > 0 ? opts.maxRunsPerDay : undefined;
    this.maxActive = opts.maxActive && opts.maxActive > 0 ? opts.maxActive : undefined;
    this.stateFile = opts.stateFile;
    this.now = opts.now ?? (() => new Date());
    // the cookie holds a keyed hash of the passcode, never the passcode itself
    this.cookieValue = this.passcode ? createHmac("sha256", this.passcode).update("freefield-visitor").digest("hex") : undefined;
    this.state = this.load();
  }

  static fromEnv(stateFile: string, env: NodeJS.ProcessEnv = process.env): Guard {
    const num = (v?: string) => (v && /^\d+$/.test(v) ? Number(v) : undefined);
    return new Guard({ passcode: env.FREEFIELD_PASSCODE, maxRunsPerDay: num(env.FREEFIELD_MAX_RUNS_PER_DAY),
      maxActive: num(env.FREEFIELD_MAX_ACTIVE), stateFile });
  }

  get hosted(): boolean {
    return Boolean(this.passcode || this.maxRunsPerDay || this.maxActive);
  }

  /** Does this request carry the passcode (as the cookie)? Always true without a passcode. */
  admits(cookieHeader: string | undefined): boolean {
    if (!this.cookieValue) return true;
    const got = parseCookies(cookieHeader)[COOKIE];
    return Boolean(got) && same(got, this.cookieValue);
  }

  /** A correct ?key= becomes the cookie; the caller redirects to the same URL without it. */
  login(key: string | null): string | null {
    if (!this.passcode || !key || !same(key, this.passcode)) return null;
    return `${COOKIE}=${this.cookieValue}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${60 * 60 * 24 * 30}`;
  }

  /** Why a new run may not start now, or null when it may. `active` = runs still going. */
  refuse(active: number): string | null {
    this.roll();
    if (this.maxActive && active >= this.maxActive) {
      return `${active} run(s) are still going on this demo (it allows ${this.maxActive} at a time); try again when one finishes`;
    }
    if (this.maxRunsPerDay && this.state.runs >= this.maxRunsPerDay) {
      return `this demo's ${this.maxRunsPerDay} runs for today (UTC) are used up; it resets at 00:00 UTC`;
    }
    return null;
  }

  /** Count one run that was accepted. */
  record(): void {
    this.roll();
    this.state.runs += 1;
    this.save();
  }

  status(active: number) {
    this.roll();
    return {
      runs_today: this.state.runs, max_runs_per_day: this.maxRunsPerDay ?? null, max_active: this.maxActive ?? null,
      runs_left: this.maxRunsPerDay ? Math.max(0, this.maxRunsPerDay - this.state.runs) : null, active,
    };
  }

  private today(): string {
    return this.now().toISOString().slice(0, 10);
  }

  private roll(): void {
    if (this.state.day !== this.today()) this.state = { day: this.today(), runs: 0 };
  }

  private load(): { day: string; runs: number } {
    try {
      if (this.stateFile && existsSync(this.stateFile)) {
        const s = JSON.parse(readFileSync(this.stateFile, "utf-8"));
        if (typeof s.day === "string" && Number.isInteger(s.runs)) return { day: s.day, runs: s.runs };
      }
    } catch { /* a damaged file starts the count again */ }
    return { day: this.today(), runs: 0 };
  }

  private save(): void {
    if (!this.stateFile) return;
    mkdirSync(dirname(this.stateFile), { recursive: true });
    const tmp = `${this.stateFile}.tmp`;
    writeFileSync(tmp, JSON.stringify(this.state) + "\n");
    renameSync(tmp, this.stateFile);
  }
}

export function parseCookies(header: string | undefined): Record<string, string> {
  const out: Record<string, string> = {};
  for (const part of (header ?? "").split(";")) {
    const i = part.indexOf("=");
    if (i > 0) out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
  }
  return out;
}

function same(a: string, b: string): boolean {
  const x = Buffer.from(a);
  const y = Buffer.from(b);
  return x.length === y.length && timingSafeEqual(x, y);
}

/** The page a visitor without the cookie gets: one field for the passcode. */
export const DOOR_HTML = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<title>Freefield</title>
<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect x='1' y='1' width='30' height='30' rx='9' fill='%23e8ff5a'/%3E%3Cpath d='M8 11.5h16M8 16.5h9M8 21.5h12' stroke='%2311140a' stroke-width='3' stroke-linecap='round'/%3E%3Ccircle cx='22.5' cy='16.5' r='1.9' fill='%2311140a'/%3E%3C/svg%3E">
<style>
:root{color-scheme:dark}body{margin:0;min-height:100vh;display:grid;place-items:center;background:#09090a;color:#f4f4f2;font:15px/1.5 system-ui,sans-serif}
form{display:grid;gap:12px;width:min(320px,calc(100vw - 32px))}h1{margin:0;font-size:22px}p{margin:0;color:#9b9ba3}
input,button{font:inherit;padding:10px 12px;border-radius:8px;border:1px solid #2e2e33;background:#151517;color:inherit}
button{background:#e8ff5a;color:#11140a;border:0;font-weight:600;cursor:pointer}</style></head>
<body><form method="get" action="/"><h1>Freefield</h1><p>This demo is private. Enter the passcode you were given.</p>
<input name="key" type="password" autocomplete="current-password" aria-label="Passcode" required autofocus><button>Open</button></form></body></html>`;