@zerotal/core 1.13.2 → 1.13.3

package/src/gate/Gate.ts

@@ -0,0 +1,130 @@
+/**
+ * The site gate: maintenance, and private preview.
+ *
+ * The primitive is here and the button is yours. An app that wants a toggle in
+ * its own console builds it against this; `zt down` / `zt preview` / `zt up` are
+ * the same three calls with a terminal in front of them.
+ *
+ * @example
+ * ```ts
+ * import { Gate } from "@zerotal/core/gate";
+ *
+ * await Gate.preview({ token, until: "2026-09-30", by: user.name });
+ * await Gate.maintenance({ retryAfter: 120, by: user.name });
+ * await Gate.open();
+ * Gate.status(); // { mode: "preview", since, until, by } — never the token
+ * ```
+ *
+ * @module
+ */
+import { clearGate, gateExpired, hashToken, readGate, writeGate, type GateState } from "./state.ts";
+
+/** Options for {@link Gate.maintenance}. */
+export interface MaintenanceOptions {
+  /**
+   * Seconds to put in `Retry-After`. Defaults to 60.
+   *
+   * Worth setting honestly: a crawler that is told 60 and finds the site still
+   * down an hour later treats the next number with less patience.
+   */
+  retryAfter?: number | undefined;
+  /** Who raised it. Shown by `Gate.status()` and `zt doctor`. */
+  by?: string | undefined;
+}
+
+/** Options for {@link Gate.preview}. */
+export interface PreviewOptions {
+  /**
+   * The secret that admits a visitor, via `?preview=<token>`.
+   *
+   * Stored as a hash, so this value cannot be read back out — keep the copy you
+   * hand to testers. Passing a new one rotates: every cookie issued under the
+   * old token stops working, which is the point, because the way a preview
+   * leaks is a tester forwarding the link to somebody who has left.
+   */
+  token: string;
+  /** ISO date the preview lifts itself on, e.g. `"2026-09-30"`. */
+  until?: string | undefined;
+  /** Who raised it. */
+  by?: string | undefined;
+}
+
+/** What {@link Gate.status} reports. Deliberately never includes the token. */
+export interface GateStatus {
+  mode: GateState["mode"] | "open";
+  since?: string | undefined;
+  until?: string | undefined;
+  by?: string | undefined;
+  retryAfter?: number | undefined;
+  /** Whether `until` has passed — the gate is still up and should not be. */
+  expired?: boolean | undefined;
+}
+
+/**
+ * Read and write the site gate.
+ *
+ * Synchronous underneath — the state is one small file — but the methods that
+ * change it are `async` so an app's own console handler can `await` them without
+ * caring, and so a future driver (shared storage, for a multi-instance deploy)
+ * does not change the signature.
+ */
+export const Gate = {
+  /**
+   * Take the site down. Everyone is refused, staff included.
+   *
+   * Answered `503` with `Retry-After`, never `200`. A maintenance page served at
+   * `200` tells a search engine that "we will be back shortly" is the content of
+   * your homepage, and it will index it as such.
+   */
+  async maintenance(options: MaintenanceOptions = {}): Promise<void> {
+    writeGate({
+      mode: "maintenance",
+      since: new Date().toISOString(),
+      retryAfter: options.retryAfter ?? 60,
+      ...(options.by ? { by: options.by } : {}),
+    });
+  },
+
+  /**
+   * Put the site behind a private preview. Invited visitors get the real site.
+   *
+   * @throws When the token is shorter than 16 characters. A preview token is a
+   *   password on the whole site with no rate limit in front of it, and a short
+   *   one chosen by hand is the failure this refuses rather than documents.
+   */
+  async preview(options: PreviewOptions): Promise<void> {
+    if (options.token.length < 16) {
+      throw new Error(
+        "[Zerotal] A preview token must be at least 16 characters. It is the only thing " +
+          "between the public and an unlaunched site, and nothing rate-limits guesses at it. " +
+          "Generate one with `zt preview` and no --token.",
+      );
+    }
+    writeGate({
+      mode: "preview",
+      since: new Date().toISOString(),
+      tokenHash: hashToken(options.token),
+      ...(options.until ? { until: options.until } : {}),
+      ...(options.by ? { by: options.by } : {}),
+    });
+  },
+
+  /** Open the site. Opening an already-open site is not an error. */
+  async open(): Promise<void> {
+    clearGate();
+  },
+
+  /** What the gate is doing, for a console or a health page. Never the token. */
+  status(): GateStatus {
+    const state = readGate();
+    if (!state) return { mode: "open" };
+    return {
+      mode: state.mode,
+      since: state.since,
+      until: state.until,
+      by: state.by,
+      retryAfter: state.retryAfter,
+      expired: gateExpired(state),
+    };
+  },
+};

package/src/gate/GateMiddleware.ts

@@ -0,0 +1,260 @@
+/**
+ * The gate itself: what happens to a request while the site is closed.
+ *
+ * Runs in the kernel layer, before routing, before the session is resolved and
+ * before anything touches the database — because in maintenance mode the
+ * database may be the thing that is unavailable, and a gate that needs it cannot
+ * report that it is down.
+ *
+ * @module
+ */
+import type { NextFn } from "../pipeline/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { BaseMiddleware } from "../middleware/BaseMiddleware.ts";
+import { config } from "../helpers/config.ts";
+import { hmacHex, safeEqual } from "../support/crypto.ts";
+import { deployEnv, isProdLike } from "../support/env.ts";
+import { gateExpired, hashToken, readGate, type GateState } from "./state.ts";
+
+/** The cookie the gate issues once a token has been accepted. */
+export const GATE_COOKIE = "zerotal_preview";
+
+/** The query parameter that carries a preview token. */
+export const GATE_QUERY = "preview";
+
+/**
+ * Paths that stay reachable while the gate is up, whatever mode it is in.
+ *
+ * Every entry is something a naive gate breaks:
+ *
+ * - **The health endpoint**, or the uptime monitor pages the on-call about a
+ *   planned window, and a deploy gate that polls health fails its own release.
+ * - **Static assets**, or the maintenance page 503s its own stylesheet and the
+ *   apology arrives unstyled.
+ *
+ * Webhooks are deliberately *not* here — see `gate.allow` in config, and the
+ * warning next to it.
+ */
+const ALWAYS_ALLOWED = ["/__zerotal/", "/css/", "/js/", "/assets/", "/favicon.ico"];
+
+/** Shape read from `config/gate.ts`, all optional. */
+interface GateConfig {
+  /**
+   * Extra path prefixes that stay reachable while the gate is up.
+   *
+   * **Put your webhook paths here.** This is the item on the list that costs
+   * money: a payment provider posting a settlement into a maintenance window
+   * gets a 503, and depending on the provider that is a retry, a dropped
+   * callback, or a payment your books never learn about. Nothing can infer which
+   * of your routes a third party calls, so it has to be declared.
+   */
+  allow?: string[];
+  /**
+   * What the public gets during a **preview** — not maintenance, which is always
+   * 503.
+   *
+   * `"holding"` (default) serves the holding view at `200`, which is right for a
+   * pre-launch site collecting an email address. `"notFound"` serves `404`, which
+   * is right when the site's existence is itself not public. Both are legitimate
+   * and the framework does not pick.
+   */
+  publicResponse?: "holding" | "notFound";
+}
+
+/**
+ * Middleware that answers for a closed site.
+ *
+ * @category Middleware
+ */
+/**
+ * The gate's decision for one request, or `null` to let it through.
+ *
+ * A plain function over `Request` rather than a method on the middleware,
+ * because the middleware is not the only place this has to run.
+ * {@link Router.raw} handlers bypass the pipeline by design, and a gate that
+ * covers the pipeline alone is the worst kind: it gates the homepage, so it
+ * looks like it works, while every raw route stays public. This framework's own
+ * documentation site serves all of `/docs/*` from raw routes, which is how that
+ * was found — the front page said "coming soon" and every page of content was
+ * open.
+ *
+ * @param request - The incoming request.
+ * @param staff - Whether the caller has already established this is a staff
+ *   user. Raw routes have no session resolved, so they pass `false`.
+ * @returns The response to send, or `null` when the request may proceed.
+ * @internal
+ */
+export function _gateResponse(request: Request, staff: boolean): Response | null {
+  const state = readGate();
+  if (!state) return null;
+
+  // A preview whose `until` has passed lifts itself. The alternative is a gate
+  // that outlives its purpose because the person who set it moved on, which is
+  // the ordinary way pre-launch gates end.
+  if (state.mode === "preview" && gateExpired(state)) return null;
+
+  const url = new URL(request.url);
+  if (_allowed(url.pathname)) return null;
+
+  if (state.mode === "maintenance") return _maintenance(state);
+
+  const offered = url.searchParams.get(GATE_QUERY);
+  if (offered && state.tokenHash && safeEqual(hashToken(offered), state.tokenHash)) {
+    // Redirect with the parameter removed, and not for tidiness. A token left in
+    // the address bar travels into `Referer` on every outbound link, into
+    // analytics, into screenshots, and into the message where somebody shares
+    // "the page I was looking at". Strip it on first use and the secret lives
+    // only in a cookie.
+    url.searchParams.delete(GATE_QUERY);
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: `${url.pathname}${url.search}${url.hash}`,
+        "Set-Cookie": _cookie(state),
+        "Cache-Control": "no-store",
+      },
+    });
+  }
+
+  if (_hasValidCookie(request, state)) return null;
+  if (staff) return null;
+
+  return config.safe<GateConfig>("gate", {}).publicResponse === "notFound"
+    ? new Response(_notFoundHtml(), {
+        status: 404,
+        headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" },
+      })
+    : new Response(_holdingHtml(), {
+        status: 200,
+        headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" },
+      });
+}
+
+/**
+ * Whether this path stays reachable while the gate is up.
+ *
+ * Read through `config.safe`, not `config`: this has to answer on a request
+ * where the application may not be resolvable at all. A gate that throws because
+ * the container is unavailable is a gate that cannot report the app is down,
+ * which is the one job it has.
+ */
+function _allowed(pathname: string): boolean {
+  const extra = config.safe<GateConfig>("gate", {}).allow ?? [];
+  return [...ALWAYS_ALLOWED, ...extra].some((prefix) => pathname.startsWith(prefix));
+}
+
+/** Whether the request carries a cookie this gate issued. */
+function _hasValidCookie(request: Request, state: GateState): boolean {
+  const raw = _readCookie(request.headers.get("cookie"), GATE_COOKIE);
+  if (!raw || !state.tokenHash) return false;
+  // Signed over the token hash, so rotating the token invalidates every cookie
+  // issued under the previous one without tracking who holds what.
+  return safeEqual(raw, _signature(state.tokenHash));
+}
+
+/**
+ * 503 with `Retry-After`, and never anything else.
+ *
+ * The status is not cosmetic. Sites have lost their search rankings to a
+ * two-hour window served at 200, because a crawler that gets 200 believes the
+ * apology *is* the page. 503 tells it to come back and keep what it had.
+ */
+function _maintenance(state: GateState): Response {
+  return new Response(_maintenanceHtml(), {
+    status: 503,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "Retry-After": String(state.retryAfter ?? 60),
+      // Nothing about a maintenance response should be cached: the next request
+      // after the window is a different answer at the same URL.
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+export class GateMiddleware extends BaseMiddleware<GateConfig> {
+  /**
+   * Read per-request rather than captured here, because the gate is changed
+   * while the process is running — that is the entire point of it — and options
+   * frozen at construction would need a restart to take effect.
+   */
+  protected options: GateConfig = {};
+
+  async handle(ctx: HttpContext, next: NextFn): Promise<Response | void> {
+    const answer = _gateResponse(ctx.request, _isStaff(ctx));
+    return answer ?? next();
+  }
+}
+
+/**
+ * Whether the request is already an authenticated non-customer.
+ *
+ * An app that has staff accounts should not need a second secret for the people
+ * who already sign in. Read defensively: this runs before the session middleware
+ * on a request that may have no session at all, so anything unexpected means
+ * "not staff" rather than an exception from the gate.
+ */
+function _isStaff(ctx: HttpContext): boolean {
+  // `in` rather than a cast: `user` is attached by the auth package at runtime
+  // and is not on `HttpContext`, so narrowing is the honest way to read it.
+  if (!("user" in ctx)) return false;
+  const user = ctx.user;
+  if (typeof user !== "object" || user === null || !("role" in user)) return false;
+  const role = user.role;
+  return typeof role === "string" && role !== "customer";
+}
+
+/** HMAC of the token hash under the app key, so the cookie cannot be forged. */
+function _signature(tokenHash: string): string {
+  const key = String(Bun.env["APP_KEY"] ?? "");
+  return hmacHex(`gate:${tokenHash}`, key);
+}
+
+/** The `Set-Cookie` value admitting this visitor. */
+function _cookie(state: GateState): string {
+  const parts = [
+    `${GATE_COOKIE}=${_signature(state.tokenHash ?? "")}`,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Lax",
+    // Days, not months. A preview cookie with no lifetime means an ex-tester
+    // keeps access to a site that has since gone live with real customer data.
+    `Max-Age=${7 * 24 * 60 * 60}`,
+  ];
+  // `deployEnv()`, not the raw variable: after `setAppEnv()` the latter holds the
+  // runtime mode rather than the deployment name.
+  if (isProdLike(deployEnv())) parts.push("Secure");
+  return parts.join("; ");
+}
+
+/** Read one cookie out of a `Cookie` header. */
+function _readCookie(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  for (const pair of header.split(";")) {
+    const index = pair.indexOf("=");
+    if (index === -1) continue;
+    if (pair.slice(0, index).trim() === name) return pair.slice(index + 1).trim();
+  }
+  return undefined;
+}
+
+/** Deliberately plain. Nobody wants a framework's opinion about their apology. */
+function _maintenanceHtml(): string {
+  return _page("Back shortly", "We are carrying out planned maintenance. Please try again soon.");
+}
+
+function _holdingHtml(): string {
+  return _page("Coming soon", "This site is not open to the public yet.");
+}
+
+function _notFoundHtml(): string {
+  return _page("Not found", "");
+}
+
+function _page(heading: string, body: string): string {
+  return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${heading}</title>
+<style>body{font:16px/1.6 system-ui,sans-serif;max-width:32rem;margin:20vh auto;padding:0 1.5rem;color:#111}h1{font-size:1.5rem;margin:0 0 .5rem}p{margin:0;color:#555}</style>
+</head><body><h1>${heading}</h1>${body ? `<p>${body}</p>` : ""}</body></html>`;
+}

package/src/gate/doctor.ts

@@ -0,0 +1,72 @@
+/**
+ * The doctor check for a gate that is still up.
+ *
+ * A site gate is the most reversible thing in the framework and the easiest to
+ * forget, because when it is working nothing complains: the people who would
+ * notice are the ones being kept out, and they have no way to tell you. Trekly's
+ * report describes the same shape from the other side — a `basic_auth` block
+ * held out of version control precisely so it could not be forgotten into
+ * production, which is a workaround for the absence of this check.
+ *
+ * @module
+ */
+import type { Application } from "../application/Application.ts";
+import { deployEnv, isProdLike } from "../support/env.ts";
+import type { DoctorCheck, DoctorCheckResult } from "../doctor/AppDoctor.ts";
+import { gateExpired, readGate } from "./state.ts";
+
+/**
+ * Report a site that is not open, and say how long it has been that way.
+ *
+ * Severity is by mode and environment, because the same state means different
+ * things. Maintenance in production is an outage and is reported as a failure.
+ * A preview in production is usually deliberate — a pre-launch site — so it is a
+ * warning that names the date rather than an error. A gate in development is
+ * neither, and saying nothing there is what keeps the check worth reading.
+ */
+export const siteGateCheck: DoctorCheck = {
+  id: "site-gate",
+  label: "Site gate",
+  run(_app: Application): DoctorCheckResult {
+    const state = readGate();
+    if (!state) return { status: "ok", message: "site is open" };
+
+    // The deployment environment, not the boot mode — `app._env` is web/worker/
+    // console and would never equal "production".
+    const production = isProdLike(deployEnv());
+    const since = state.since.slice(0, 10);
+    const who = state.by ? `, set by ${state.by}` : "";
+
+    if (state.mode === "preview" && gateExpired(state)) {
+      // Worth its own finding: the file says the site is gated and the gate is
+      // no longer gating, so what a reader believes and what visitors get have
+      // come apart.
+      return {
+        status: "warn",
+        message:
+          `A private preview's window closed on ${state.until} — the site has been public ` +
+          `since then, while the gate file still says otherwise.`,
+        fix: "Run `bun zt up` to clear it, or `bun zt preview --until=<date>` to extend it.",
+      };
+    }
+
+    if (state.mode === "maintenance") {
+      return {
+        status: production ? "fail" : "warn",
+        message:
+          `The site is in maintenance mode${who}, since ${since}. Every request is answered ` +
+          `503${production ? " — in production, this is an outage" : ""}.`,
+        fix: "Run `bun zt up` when the work is finished.",
+      };
+    }
+
+    return {
+      status: production ? "warn" : "ok",
+      message:
+        `The site is in private preview${who}, since ${since}` +
+        `${state.until ? `, until ${state.until}` : " with no end date"}. The public cannot see it.` +
+        `${state.until ? "" : " A preview with no end date is the kind that outlives its purpose."}`,
+      fix: "Run `bun zt up` to make it public, or `bun zt gate:status` to see the details.",
+    };
+  },
+};

package/src/gate/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The site gate — maintenance, and private preview.
+ *
+ * Published as `@zerotal/core/gate`. See {@link Gate} for the API and
+ * {@link GateMiddleware} for what happens to a request while the gate is up.
+ *
+ * @packageDocumentation
+ */
+export { Gate } from "./Gate.ts";
+export type { GateStatus, MaintenanceOptions, PreviewOptions } from "./Gate.ts";
+export { GateMiddleware, GATE_COOKIE, GATE_QUERY } from "./GateMiddleware.ts";
+export { readGate, gateExpired, GATE_FILE } from "./state.ts";
+export type { GateState, GateMode } from "./state.ts";

package/src/gate/state.ts

@@ -0,0 +1,127 @@
+/**
+ * The site gate's state, and where it is kept.
+ *
+ * Two modes that look alike and behave differently, which is why building one
+ * and calling it both goes wrong:
+ *
+ * - **`maintenance`** — the site is *down*. Nobody may use it, staff included,
+ *   because the usual reason it is down is that the database is being migrated
+ *   underneath it. Minutes, not weeks. A request is answered `503` with
+ *   `Retry-After`.
+ * - **`preview`** — the site is *up and working perfectly*, for the people
+ *   invited to it. Not down, not broken, not public yet. Weeks. An invited
+ *   visitor gets the real site at `200` and can transact on it.
+ *
+ * ## Why a file, and not the database
+ *
+ * A flag in the database is unreadable exactly when the database is the thing
+ * you are working on, so a maintenance mode kept there is one that works only on
+ * the days you did not need it. A file is also why the gate survives a restart —
+ * an in-memory flag would be lifted by the very deploy that was supposed to run
+ * behind it.
+ *
+ * ## Why the token is stored as a hash
+ *
+ * The state file sits on disk, readable by anything on the box and copied by
+ * every backup. Storing the preview token there would put a live credential in
+ * a file whose whole job is to be easy to read — the same mistake as a
+ * `.env.example` carrying a working key. Only `sha256Hex(token)` is written, so
+ * the file can verify a token and cannot leak one, and rotating means writing a
+ * new hash.
+ *
+ * @module
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sha256Hex } from "../support/crypto.ts";
+
+/** Which of the two states the site is in. */
+export type GateMode = "maintenance" | "preview";
+
+/** What the gate records about itself. */
+export interface GateState {
+  mode: GateMode;
+  /** ISO timestamp the gate was raised. */
+  since: string;
+  /**
+   * ISO date the gate lifts itself on, when one was set.
+   *
+   * A pre-launch gate outlives its purpose more often than it is taken down on
+   * time, so the deadline is worth recording even when nothing enforces it.
+   */
+  until?: string | undefined;
+  /** Who raised it, for a console that can say more than "on". */
+  by?: string | undefined;
+  /** `sha256Hex` of the preview token. Never the token. `preview` only. */
+  tokenHash?: string | undefined;
+  /** Seconds for the `Retry-After` header. `maintenance` only. */
+  retryAfter?: number | undefined;
+}
+
+/** Where the state file lives, relative to the project root. */
+export const GATE_FILE = join("storage", "framework", "gate.json");
+
+function _path(root: string): string {
+  return join(root, GATE_FILE);
+}
+
+/**
+ * Read the gate's state, or `null` when the site is open.
+ *
+ * Never throws. A corrupt or unreadable file reads as **open**, deliberately: a
+ * gate that fails closed would take a site down because a JSON file lost a
+ * brace, and "the site is up" is the safer error for a mechanism whose whole
+ * purpose is to be turned off again.
+ *
+ * @param root - Project root. Defaults to the working directory.
+ */
+export function readGate(root: string = process.cwd()): GateState | null {
+  try {
+    const raw = readFileSync(_path(root), "utf8");
+    const state = JSON.parse(raw) as GateState;
+    if (state.mode !== "maintenance" && state.mode !== "preview") return null;
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the gate's state, creating `storage/framework/` if it is not there.
+ *
+ * @param state - The state to record.
+ * @param root - Project root. Defaults to the working directory.
+ */
+export function writeGate(state: GateState, root: string = process.cwd()): void {
+  const file = _path(root);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+/** Remove the state file. Opening an already-open site is not an error. */
+export function clearGate(root: string = process.cwd()): void {
+  rmSync(_path(root), { force: true });
+}
+
+/** Whether a state file exists at all, without parsing it. */
+export function gateFileExists(root: string = process.cwd()): boolean {
+  return existsSync(_path(root));
+}
+
+/**
+ * Whether a `until` date has passed.
+ *
+ * Compared as a date rather than an instant: `until: "2026-09-30"` means "through
+ * the 30th", which is what someone typing a date means.
+ */
+export function gateExpired(state: GateState, now: Date = new Date()): boolean {
+  if (!state.until) return false;
+  const end = new Date(`${state.until.slice(0, 10)}T23:59:59.999Z`);
+  if (Number.isNaN(end.getTime())) return false;
+  return now.getTime() > end.getTime();
+}
+
+/** Hash a preview token for storage. Exported so the CLI and the API agree. */
+export function hashToken(token: string): string {
+  return sha256Hex(token);
+}