ef3d39c · 5a108bb · 50abbf2 · 6c52325 · 81add7c · 66231de
@@ -93,6 +93,7 @@
Machine routes are not pages and have no entry: `/audit.csv`,
- `/forges/new` — `pages/new-forge.ts` · send a new forge · none · colour 1.
- `/family` — `pages/family.ts` · parent, this forge and children as a tree · `/forges` (the same children) · colour 1.
- `/claim` — `pages/claim.ts` · claim a forge that was sent to me · none · colour 1.
- `/privacy` — `pages/privacy.ts` · what the forge keeps about a visitor, three plain lines, open to anyone · none · none seen.
- `/first-admin` — `pages/first-admin.ts` · the first person becomes admin · none · none seen.
- `/fleet/graph` — `pages/fleet-graph.ts` · the fleet as a graph · `/family`, `/forges` · none seen.
- `/fleet` — `pages/fleet.ts` · the rows a fleet query line selects, as a table · `/fleet/graph` · none seen.
@@ -0,0 +1,23 @@
# Returning visitors
Who comes back, how often, and what they did before they started or bought a forge (#11265).
Settings → Traffic ("Who comes back"), the Billing page ("What led to a forge") and
`GET /api/v1/admin/traffic/visitors?days=30` (admin token) answer the same; the API's `probe` counts the stored rows again.
- **Setting `traffic.returning`.** **Off on every forge** until its owner turns it on (nothing stored reads as off), on
  Settings → Traffic or in the terminal ("Who comes back", `t`). Nothing a child collects reaches its host.
- **Cookie id (primary).** The page-view beacon's answer sets `forge_visitor`: random 128 bits signed with an HMAC of the forge's key (a value this forge did not sign is ignored, so a client cannot invent ids), `HttpOnly`, `Secure`
  (when the forge is https), `SameSite=Lax`, 13 months, no `Domain` (this host only).
- **Probable id (fallback).** Without the cookie: a salted hash of browser family+major, OS, language and the /24 (v4) or
  /48 (v6) prefix; the salt lives in `visitor_salt` and rotates every 30 days. Shown as "guessed", never merged with a
  cookie id. A cookie-keeping browser's very first view is recorded as probable (the cookie does not exist yet); later
  views are the cookie id's. No client probing.
- **Bounded.** A day takes at most 5000 new visitor rows (`NEW_PER_DAY`); past it nothing is kept and no cookie is set.
- **Respect.** `Sec-GPC: 1`: no cookie, no visitor row (the view still counts in the anonymous daily total). `DNT: 1` counts nothing, as before.
  Scrapers get no id. The `forge_measure=off` cookie stores nothing at all.
- **Kept.** Per visitor: first/last seen, days seen, visits, first and latest entry referrer, furthest step, and each
  visit's ordered paths (no query string; a gap over 30 minutes starts a new visit). No IP, no user agent. Rows not seen
  for 13 months are deleted by the `visitor-retention` maintenance duty.
- **Becoming someone.** Spawning a forge (`POST /api/v1/forges`) links the request's cookie id to the forge name
  (`started a forge`; `paid` when a gift/plan code was redeemed). Stripe-paid checkouts are not linked yet.
- `/privacy` says it in three lines.
@@ -0,0 +1,11 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "get",
  path: "/api/v1/admin/traffic/visitors",
  summary:
    "Read who comes back (a person admin's token, any scope); query: days (1-90, default 30); answers { as_of, enabled, days, per_day: [{ day, new_cookie, returning_cookie, new_probable, returning_probable }], new_visitors, returning_visitors, returning: [{ id (shortened), probable, visits, days_seen, first_seen, last_seen, first_ref, last_ref, step, forge }], led: [{ forge, id, probable, step, first_ref, visits: [{ day, ref, pages }] }], probe: { new, returning, agrees } } where probe counts the stored visitor rows again; a probable id is a salted hash of coarse request facts, never merged with a cookie id",
  auth: true,
  role: "admin",
  refusals: { not_found: "the token is not a person who administers the forge" },
};
@@ -55,6 +55,7 @@
export { route as getApiV1AdminShield } from "./getApiV1AdminShield.ts";
export { route as getApiV1AdminSubscriptions } from "./getApiV1AdminSubscriptions.ts";
export { route as getApiV1AdminTeams } from "./getApiV1AdminTeams.ts";
export { route as getApiV1AdminTrafficProbe } from "./getApiV1AdminTrafficProbe.ts";
export { route as getApiV1AdminTrafficVisitors } from "./getApiV1AdminTrafficVisitors.ts";
export { route as getApiV1Agents } from "./getApiV1Agents.ts";
export { route as getApiV1AgentsUsername } from "./getApiV1AgentsUsername.ts";
export { route as getApiV1AppTemplates } from "./getApiV1AppTemplates.ts";
@@ -0,0 +1,1 @@
cd373a08768e6497adfdde27984576d2abaeff0d96def19ff06c0673dc8f1f1a
@@ -0,0 +1,35 @@
// Who comes back (#11265): one row per visitor id (a first-party cookie id, or
// a "probable" salted hash of coarse request facts), and one per visit with the
// ordered paths. No address, no full user agent. Additive.
export default `
  CREATE TABLE visitor (
    id         TEXT    PRIMARY KEY,
    kind       TEXT    NOT NULL,
    first_seen INTEGER NOT NULL,
    last_seen  INTEGER NOT NULL,
    days_seen  INTEGER NOT NULL,
    visits     INTEGER NOT NULL,
    first_ref  TEXT    NOT NULL,
    last_ref   TEXT    NOT NULL,
    step       INTEGER NOT NULL DEFAULT 0,
    forge      TEXT    NOT NULL DEFAULT '',
    linked_at  INTEGER NOT NULL DEFAULT 0
  ) WITHOUT ROWID;
  CREATE INDEX visitor_last_seen ON visitor (last_seen);
  CREATE INDEX visitor_forge ON visitor (forge) WHERE forge <> '';
  CREATE TABLE visitor_visit (
    id        INTEGER PRIMARY KEY,
    visitor   TEXT    NOT NULL,
    day       TEXT    NOT NULL,
    started   INTEGER NOT NULL,
    last      INTEGER NOT NULL,
    entry_ref TEXT    NOT NULL,
    pages     TEXT    NOT NULL
  );
  CREATE INDEX visitor_visit_visitor ON visitor_visit (visitor, id);
  CREATE INDEX visitor_visit_day ON visitor_visit (day);
  CREATE TABLE visitor_salt (
    period INTEGER PRIMARY KEY,
    salt   TEXT    NOT NULL
  );
`;
@@ -35,6 +35,7 @@
export const SYSTEM_NAMES: readonly string[] = [
  "crew",
  "agent",
  "agents",
  "privacy",
  "bot",
  "steward",
  "anonymous",
@@ -10,6 +10,8 @@
import { crawlReport } from "../../perf/crawlers.ts";
import { getAppById } from "../../core/apps.ts";
import { FUNNEL_SCOPE, daysOf, funnelReport } from "../../perf/funnel.ts";
import { probeViews } from "../../perf/views_probe.ts";
import { daysOf as visitorDaysOf, probeVisitors, visitorsReport } from "../../perf/visitor_report.ts";
import { getReturning } from "../../settings/returning.ts";
import { kpiProbe } from "../../web/studio/kpi_probe.ts";
import { MAX_SECONDS, sampleStacks } from "../../perf/sample.ts";
import { listAccounts, removeAccount, retireAndRemoveAccount, retirementPlan, suspendAccount, unsuspendAccount, verifyAccount } from "../../actions/accounts.ts";
@@ -179,6 +181,44 @@
export function adminRoutes(router: Router<Handler>): void {
    return json(only === null ? probed : { ...probed, numbers: probed.numbers.filter((n) => n.id === only) });
  });
  // Who comes back (`perf/visitor_report.ts`, #11265): the same figures as the Traffic page.
  router.add("GET", "/api/v1/admin/traffic/visitors", (ctx) => {
    notePhase(ctx.request, "session", takeSessionTime(ctx.request));
    const denied = accountAdmin(ctx, "ro");
    if (denied) return denied;
    const now = Date.now();
    const days = visitorDaysOf(ctx.url.searchParams.get("days"));
    const r = visitorsReport(ctx.app.db, days, now);
    return json({
      as_of: new Date(now).toISOString(),
      enabled: getReturning(ctx.app.db),
      days: r.days,
      per_day: r.perDay.map((d) => ({
        day: d.day,
        new_cookie: d.newCookie,
        returning_cookie: d.returningCookie,
        new_probable: d.newProbable,
        returning_probable: d.returningProbable,
      })),
      new_visitors: r.newVisitors,
      returning_visitors: r.returningVisitors,
      returning: r.returning.map((v) => ({
        id: v.id,
        probable: v.probable,
        visits: v.visits,
        days_seen: v.daysSeen,
        first_seen: v.firstSeen,
        last_seen: v.lastSeen,
        first_ref: v.firstRef,
        last_ref: v.lastRef,
        step: v.step,
        forge: v.forge,
      })),
      led: r.led.map((l) => ({ forge: l.forge, id: l.id, probable: l.probable, step: l.step, first_ref: l.firstRef, visits: l.visits })),
      probe: probeVisitors(ctx.app.db, days, now, r),
    });
  });
  // The forge's capacity (`core/capacity.ts`): read and changed live by an
  // admin, never by an agent; anyone else is told the door is not there.
  router.add("GET", "/api/v1/admin/capacity", (ctx) => {
@@ -17,6 +17,7 @@
import { readBounded } from "./limits.ts";
import { clientAddress, clientBucket } from "./peer.ts";
import { originOf } from "../perf/sources.ts";
import { noteView } from "../perf/views_store.ts";
import { trackVisitor } from "./visitor.ts";
const PER_CLIENT = 30;
const PER_FORGE = 1200;
@@ -65,13 +66,15 @@
export async function measureSubmit(ctx: Ctx, routeOf: RouteOf): Promise<Respons
    clientAddress(request),
    request.headers.get("user-agent") ?? "",
  );
  const origin = originOf(report.ref, report.q, ctx.url.host, report.out);
  noteView(app.db, {
    scope: "forge",
    // The route pattern, never the path: a path can name a private repository.
    path: route,
    origin: originOf(report.ref, report.q, ctx.url.host, report.out),
    origin,
    client: clientAddress(request),
    agent: request.headers.get("user-agent") ?? "",
  });
  return refuse(204);
  const cookie = trackVisitor(app, request, ctx.url, { route, search: report.q, ref: origin.refHost || origin.source });
  return refuse(204, cookie === undefined ? undefined : { "set-cookie": cookie });
}
@@ -17,6 +17,7 @@
import {
import { secureFor } from "./cookie_secure.ts";
import { refusedByDatabase, shownRefusal } from "./refusal.ts";
import { NOT_A_MEMBER } from "../core/roles.ts";
import { privacyPage } from "../web/pages/privacy.ts";
import { startClaimAccountSubmit, startClaimPage, startClaimSubmit } from "../web/pages/start_claim.ts";
import { signupOptions, signupPasskey } from "../web/pages/signup-passkey.ts";
import { toolbarComment, toolbarPage } from "../web/studio/toolbar.ts";
@@ -939,6 +940,7 @@
export function buildRouter(): Router<Handler> {
  router.add("GET", "/audit", auditPage);
  router.add("GET", "/releases", releasesPage);
  // The forge's own documentation: a redirect built from configuration only.
  router.add("GET", "/privacy", privacyPage);
  router.add("GET", "/docs", docsFolder);
  router.add("GET", "/docs/:file", docsFile);
  router.add("GET", "/changelog", changelogPage);
@@ -26,6 +26,7 @@
import { spendPage } from "../web/pages/spend-tab.ts";
import { securityControlsPage } from "../web/pages/security_controls.ts";
import { securityPage, securityShieldSet } from "../web/pages/security.ts";
import { trafficPage } from "../web/pages/traffic.ts";
import { returningSet } from "../web/pages/visitors.ts";
import { sourcesPage } from "../web/pages/sources.ts";
import { requestAct } from "../web/requests_card.ts";
import { captureStart, captureStop, networksImport, scrapesExport, scrapesPage } from "../web/pages/scrapes.ts";
@@ -235,6 +236,7 @@
export function settingsRoutes(router: Router<Handler>, knownPatterns: () => rea
  router.add("GET", "/settings/usage", (ctx) => usagePage(ctx, knownPatterns));
  router.add("GET", "/settings/spend", spendPage);
  router.add("GET", "/settings/traffic", trafficPage);
  router.add("POST", "/settings/traffic/returning", returningSet);
  router.add("GET", "/settings/traffic/sources", sourcesPage);
  router.add("GET", "/settings/traffic/scrapes", scrapesPage);
  router.add("GET", "/settings/traffic/scrapes/export", scrapesExport);
@@ -0,0 +1,46 @@
/**
 * The returning-visitor step of the page-view beacon (#11265): decide who the
 * request is, store one view, and say whether a cookie is to be set.
 *
 * Nothing is kept when the forge's `traffic.returning` is off, when the
 * request carries `Sec-GPC: 1` or `DNT: 1`, or when the agent is a scraper
 * (`isScraperAgent`: counted apart, never given an id). A signed cookie id is the
 * primary signal; without one the visitor is a "probable" salted hash, and the
 * cookie is set so the next view is exact.
 */
import type { App } from "../app.ts";
import { getReturning } from "../settings/returning.ts";
import { isScraperAgent } from "../perf/sources.ts";
import { loadKey } from "../kernel/secret.ts";
import { cookieId, cookieLine, mintId, probableId, refusesTracking, stepOf } from "../perf/visitor_id.ts";
import { noteVisitor, visitorSalt } from "../perf/visitor_store.ts";
import { clientAddress } from "./peer.ts";
import { secureFor } from "./cookie_secure.ts";
/** Returns the Set-Cookie line to add to the answer, or undefined. */
export function trackVisitor(
  app: App,
  request: Request,
  url: URL,
  view: { route: string; search: string | undefined; ref: string },
  at: number = Date.now(),
): string | undefined {
  if (!getReturning(app.db)) return undefined;
  if (refusesTracking(request.headers)) return undefined;
  if (isScraperAgent(request.headers.get("user-agent") ?? "")) return undefined;
  const key = loadKey(app.config.dataDir);
  const held = cookieId(request.headers.get("cookie"), key);
  const minted = held === undefined ? mintId(key) : undefined;
  const id = held ?? probableId(visitorSalt(app.db, at), request.headers, clientAddress(request));
  const kept = noteVisitor(app.db, {
    id,
    kind: held === undefined ? "probable" : "cookie",
    path: view.route,
    ref: view.ref,
    step: stepOf(view.route, view.search),
    at,
  });
  // Past today's cap on new visitors nothing is kept, so no cookie is given either.
  return minted === undefined || !kept ? undefined : cookieLine(minted.value, secureFor(url, app.config.url));
}
@@ -0,0 +1,13 @@
/** Visitor rows not seen for 13 months are deleted (#11265); see `perf/visitor_store.ts`. */
import type { Duty } from "../duty.ts";
import { purgeVisitors } from "../../perf/visitor_store.ts";
export const duty: Duty = {
  name: "visitor-retention",
  intervalMs: 86_400_000,
  run({ db, now }) {
    const removed = purgeVisitors(db, now.getTime());
    return { findings: [], actions: removed === 0 ? [] : [`deleted ${removed} visitor rows older than 13 months`] };
  },
};
@@ -5,5 +5,6 @@
import { duty as pullsWaiting } from "./duties/stale_pulls.ts";
import { duty as ruleWatcher } from "./duties/rule_watcher.ts";
import { duty as efficiencyWatcher } from "./duties/efficiency_watcher.ts";
import { duty as flowKeeper } from "./duties/flow_keeper.ts";
import { duty as visitorRetention } from "./duties/visitor_retention.ts";
export const duties: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper];
export const duties: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention];
@@ -0,0 +1,115 @@
/**
 * Who a request is, for the returning-visitor view (#11265). Plain data in,
 * plain data out; no SQL here.
 *
 * The primary signal is a random id in a first-party cookie (`forge_visitor`):
 * exact, signed so only this forge's own ids are accepted, and it carries nothing about the person. Without it the fallback is a
 * salted hash of coarse facts the server already sees (browser family and
 * major version, OS, language, the network prefix: /24 for v4, /48 for v6),
 * marked "probable" wherever it is shown and never merged with a cookie id.
 * The salt rotates every 30 days (`visitor_store.ts`). Nothing is probed on the
 * client: no canvas, fonts, audio or WebGL.
 */
import { createHmac, timingSafeEqual } from "node:crypto";
import { sha256 } from "../kernel/hash.ts";
import { addressBytes } from "../kernel/cidr.ts";
export const COOKIE = "forge_visitor";
/** 13 months, in seconds. */
export const COOKIE_MAX_AGE = 396 * 86_400;
export const SALT_MS = 30 * 86_400_000;
const COOKIE_ID = /^c[0-9a-f]{32}\.[0-9a-f]{32}$/;
export type VisitorKind = "cookie" | "probable";
const macOf = (key: Uint8Array, id: string): string => createHmac("sha256", key).update(`visitor-cookie\0${id}`).digest("hex").slice(0, 32);
/**
 * A new random id and the cookie value that carries it: `c<128 random bits>.<32 hex of an HMAC of the id>`.
 * Only a value this forge signed is accepted back (`cookieId`), so a client cannot invent ids to fill the table.
 */
export function mintId(key: Uint8Array): { readonly id: string; readonly value: string } {
  const bytes = crypto.getRandomValues(new Uint8Array(16));
  const id = `c${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
  return { id, value: `${id}.${macOf(key, id)}` };
}
/** The id in a cookie header, only if its signature is one this forge made. */
export function cookieId(header: string | null, key: Uint8Array): string | undefined {
  if (header === null) return undefined;
  for (const pair of header.split(";")) {
    const eq = pair.indexOf("=");
    if (eq === -1 || pair.slice(0, eq).trim() !== COOKIE) continue;
    const value = pair.slice(eq + 1).trim();
    if (!COOKIE_ID.test(value)) return undefined;
    const [id, mac] = value.split(".") as [string, string];
    return timingSafeEqual(Buffer.from(mac), Buffer.from(macOf(key, id))) ? id : undefined;
  }
  return undefined;
}
/** `Sec-GPC: 1` or `DNT: 1`: no cookie and no stored visitor. */
export const refusesTracking = (headers: Headers): boolean =>
  headers.get("sec-gpc") === "1" || headers.get("dnt") === "1";
/** Browser family and major version: "chrome/120". Order matters: Edge and Opera also say Chrome. */
export function browserOf(agent: string): string {
  const a = agent.slice(0, 300);
  const pick = (name: string, re: RegExp): string | undefined => {
    const m = re.exec(a);
    return m === null ? undefined : `${name}/${m[1]}`;
  };
  return (
    pick("edge", /\bEdg(?:e|A|iOS)?\/(\d+)/) ??
    pick("opera", /\bOPR\/(\d+)/) ??
    pick("firefox", /\b(?:Firefox|FxiOS)\/(\d+)/) ??
    pick("chrome", /\b(?:Chrome|CriOS)\/(\d+)/) ??
    pick("safari", /\bVersion\/(\d+)[\d.]* (?:Mobile\/\S+ )?Safari\//) ??
    "other"
  );
}
export function osOf(agent: string): string {
  const a = agent.slice(0, 300);
  if (/Windows/.test(a)) return "windows";
  if (/Android/.test(a)) return "android";
  if (/iPhone|iPad|iPod/.test(a)) return "ios";
  if (/Mac OS X|Macintosh/.test(a)) return "macos";
  if (/CrOS/.test(a)) return "chromeos";
  if (/Linux|X11/.test(a)) return "linux";
  return "other";
}
/** The first language tag, lowercase, at most 8 characters. */
export const languageOf = (header: string | null): string =>
  (header ?? "").split(",")[0]?.split(";")[0]?.trim().toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 8) ?? "";
/** The network prefix: /24 of a v4 address, /48 of a v6 one; "" when the address is unknown. */
export function prefixOf(address: string): string {
  const bytes = addressBytes(address);
  if (bytes === undefined) return "";
  if (bytes.length === 4) return `${bytes[0]}.${bytes[1]}.${bytes[2]}/24`;
  return `${((bytes[0]! << 8) | bytes[1]!).toString(16)}:${((bytes[2]! << 8) | bytes[3]!).toString(16)}:${((bytes[4]! << 8) | bytes[5]!).toString(16)}/48`;
}
/** The probable id: "p" and a salted hash of the coarse facts. The salt is the 30-day one. */
export function probableId(salt: string, headers: Headers, address: string): string {
  const agent = headers.get("user-agent") ?? "";
  const facts = [browserOf(agent), osOf(agent), languageOf(headers.get("accept-language")), prefixOf(address)].join("\0");
  return `p${sha256(`${salt}\0visitor\0${facts}`).slice(0, 32)}`;
}
/** The Set-Cookie line for a new id: HttpOnly, Secure when the forge is https, SameSite=Lax, 13 months, this host only (no Domain). */
export const cookieLine = (value: string, secure: boolean): string =>
  `${COOKIE}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${COOKIE_MAX_AGE}${secure ? "; Secure" : ""}`;
/** How far a visitor got; the highest step seen is kept. */
export const STEPS = ["none", "saw plans", "clicked a plan", "started a forge", "paid"] as const;
/** The step a page view shows: the front page and /agents show the plans; a plan chosen is a spawn or a code. */
export function stepOf(route: string, search: string | undefined): number {
  if (route.startsWith("/spawn") || route.startsWith("/signup") || /(?:^|[?&])(?:code|plan)=/.test(search ?? "")) return 2;
  if (route === "/" || route === "/agents" || route === "/plans") return 1;
  return 0;
}
@@ -0,0 +1,17 @@
/**
 * Linking a request's visitor to the forge it started (#11265). Kept apart from
 * the http layer so the spawn door can call it without importing from it.
 */
import type { App } from "../app.ts";
import { loadKey } from "../kernel/secret.ts";
import { getReturning } from "../settings/returning.ts";
import { cookieId, refusesTracking } from "./visitor_id.ts";
import { linkVisitor } from "./visitor_store.ts";
/** Link the request's cookie visitor to a forge it started. Quiet when there is no signed cookie, or tracking is off or declined. */
export function linkRequestVisitor(app: App, request: Request, forge: string, step: "started" | "paid"): void {
  if (!getReturning(app.db) || refusesTracking(request.headers)) return;
  const id = cookieId(request.headers.get("cookie"), loadKey(app.config.dataDir));
  if (id !== undefined) linkVisitor(app.db, id, forge, step, Date.now());
}
@@ -0,0 +1,183 @@
/**
 * The returning-visitor figures (#11265), read from `visitor` and
 * `visitor_visit`: new versus returning per day, the returning list, and for a
 * forge that was started or paid, the visits that led to it. Cookie ids and
 * probable ids are always counted apart: a probable visitor is never merged
 * with a cookie one. Plain data out.
 *
 * Counts: a day's visitor is a distinct visitor id with a visit that day; it is
 * new when its first_seen is that day, returning otherwise. In the totals a
 * returning visitor is one with two visits or more, last seen in the window.
 */
import type { Database } from "bun:sqlite";
import { dayOf } from "../web/measure.ts";
import { STEPS, type VisitorKind } from "./visitor_id.ts";
const DAY_MS = 86_400_000;
export const DAYS_MAX = 90;
export const LIST_MAX = 50;
export const daysOf = (raw: string | null): number => {
  const n = Number(raw);
  return Number.isInteger(n) && n >= 1 && n <= DAYS_MAX ? n : 30;
};
export interface DayCount {
  readonly day: string;
  readonly newCookie: number;
  readonly returningCookie: number;
  readonly newProbable: number;
  readonly returningProbable: number;
}
export interface Visitor {
  /** Shortened: the first 8 characters. */
  readonly id: string;
  readonly kind: VisitorKind;
  /** True for a probable id: shown as "probable" wherever it appears. */
  readonly probable: boolean;
  readonly visits: number;
  readonly daysSeen: number;
  readonly firstSeen: string;
  readonly lastSeen: string;
  readonly firstRef: string;
  readonly lastRef: string;
  readonly step: string;
  readonly forge: string;
}
export interface Led {
  readonly forge: string;
  readonly id: string;
  readonly probable: boolean;
  readonly step: string;
  readonly firstSeen: string;
  readonly firstRef: string;
  readonly visits: readonly { readonly day: string; readonly ref: string; readonly pages: readonly string[] }[];
}
export interface VisitorsReport {
  readonly days: number;
  readonly perDay: readonly DayCount[];
  readonly newVisitors: number;
  readonly returningVisitors: number;
  readonly returning: readonly Visitor[];
  readonly led: readonly Led[];
}
const iso = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
const shortId = (id: string): string => id.slice(0, 9);
interface Row {
  id: string;
  kind: VisitorKind;
  first_seen: number;
  last_seen: number;
  days_seen: number;
  visits: number;
  first_ref: string;
  last_ref: string;
  step: number;
  forge: string;
}
const asVisitor = (r: Row): Visitor => ({
  id: shortId(r.id),
  kind: r.kind,
  probable: r.kind === "probable",
  visits: r.visits,
  daysSeen: r.days_seen,
  firstSeen: iso(r.first_seen),
  lastSeen: iso(r.last_seen),
  firstRef: r.first_ref === "" ? "(direct)" : r.first_ref,
  lastRef: r.last_ref === "" ? "(direct)" : r.last_ref,
  step: STEPS[r.step] ?? "none",
  forge: r.forge,
});
/** The forges a visitor started or paid, with the visits that led to each: two queries however many forges. */
export function ledReport(db: Database): readonly Led[] {
  const forged = db.query<Row, []>("SELECT * FROM visitor WHERE forge <> '' ORDER BY linked_at DESC LIMIT 20").all();
  if (forged.length === 0) return [];
  const marks = forged.map(() => "?").join(",");
  const visits = new Map<string, { day: string; ref: string; pages: string[] }[]>();
  for (const v of db
    .query<{ visitor: string; day: string; entry_ref: string; pages: string }, string[]>(
      `SELECT visitor, day, entry_ref, pages FROM visitor_visit WHERE visitor IN (${marks}) ORDER BY id`,
    )
    .all(...forged.map((r) => r.id))) {
    const list = visits.get(v.visitor) ?? [];
    if (list.length < 20) list.push({ day: v.day, ref: v.entry_ref === "" ? "(direct)" : v.entry_ref, pages: JSON.parse(v.pages) as string[] });
    visits.set(v.visitor, list);
  }
  return forged.map((r) => ({
    forge: r.forge,
    id: shortId(r.id),
    probable: r.kind === "probable",
    step: STEPS[r.step] ?? "none",
    firstSeen: iso(r.first_seen),
    firstRef: r.first_ref === "" ? "(direct)" : r.first_ref,
    visits: visits.get(r.id) ?? [],
  }));
}
export function visitorsReport(db: Database, days: number, now: number): VisitorsReport {
  const since = dayOf(now - (days - 1) * DAY_MS);
  const per = db
    .query<{ day: string; kind: VisitorKind; fresh: number; n: number }, [string]>(
      `SELECT v.day AS day, w.kind AS kind, (strftime('%Y-%m-%d', w.first_seen / 1000, 'unixepoch') = v.day) AS fresh,
              COUNT(DISTINCT v.visitor) AS n
         FROM visitor_visit v JOIN visitor w ON w.id = v.visitor
        WHERE v.day >= ?1 GROUP BY v.day, w.kind, fresh`,
    )
    .all(since);
  const byDay = new Map<string, { nc: number; rc: number; np: number; rp: number }>();
  for (const r of per) {
    const d = byDay.get(r.day) ?? { nc: 0, rc: 0, np: 0, rp: 0 };
    if (r.kind === "cookie") r.fresh === 1 ? (d.nc += r.n) : (d.rc += r.n);
    else r.fresh === 1 ? (d.np += r.n) : (d.rp += r.n);
    byDay.set(r.day, d);
  }
  const perDay: DayCount[] = Array.from({ length: days }, (_, i) => {
    const day = iso(now - (days - 1 - i) * DAY_MS);
    const d = byDay.get(day) ?? { nc: 0, rc: 0, np: 0, rp: 0 };
    return { day, newCookie: d.nc, returningCookie: d.rc, newProbable: d.np, returningProbable: d.rp };
  });
  const cut = now - days * DAY_MS;
  const counts = db
    .query<{ fresh: number; n: number }, [number]>(
      "SELECT (visits = 1) AS fresh, COUNT(*) AS n FROM visitor WHERE last_seen >= ?1 GROUP BY fresh",
    )
    .all(cut);
  const returning = db
    .query<Row, [number]>(
      `SELECT * FROM visitor WHERE visits >= 2 AND last_seen >= ?1 ORDER BY visits DESC, last_seen DESC LIMIT ${LIST_MAX}`,
    )
    .all(cut)
    .map(asVisitor);
  const led = ledReport(db);
  return {
    days,
    perDay,
    newVisitors: counts.find((c) => c.fresh === 1)?.n ?? 0,
    returningVisitors: counts.find((c) => c.fresh === 0)?.n ?? 0,
    returning,
    led,
  };
}
/** The same counts by a different route: the probe proves a report's numbers against their rows, without building the report again. */
export function probeVisitors(
  db: Database,
  days: number,
  now: number,
  against: { readonly newVisitors: number; readonly returningVisitors: number },
): { readonly new: number; readonly returning: number; readonly agrees: boolean } {
  const cut = now - days * DAY_MS;
  const n = (where: string): number =>
    db.query<{ n: number }, [number]>(`SELECT COUNT(*) AS n FROM visitor WHERE last_seen >= ?1 AND ${where}`).get(cut)?.n ?? 0;
  const fresh = n("visits = 1");
  const back = n("visits >= 2");
  return { new: fresh, returning: back, agrees: fresh === against.newVisitors && back === against.returningVisitors };
}
@@ -0,0 +1,109 @@
/**
 * What is kept of a returning visitor (#11265): per visitor id, first and last
 * seen, days seen, visit count, the entry referrer of the first and latest
 * visit, the furthest step reached, and the ordered paths of each visit (path
 * only, no query string). Never an address or a user agent: the probable id is
 * a salted hash and the salt (30 days) is the only thing that could undo it.
 *
 * A visit is a run of views with no gap over 30 minutes. A row untouched for
 * 13 months is deleted (`purgeVisitors`, run by the maintenance duty).
 */
import type { Database } from "bun:sqlite";
import { dayOf } from "../web/measure.ts";
import { SALT_MS, STEPS, type VisitorKind } from "./visitor_id.ts";
export const VISIT_GAP_MS = 30 * 60_000;
export const PAGES_MAX = 40;
export const KEEP_MS = 396 * 86_400_000;
const REF_MAX = 100;
/** New visitor rows a forge takes in one day; a beacon past it keeps nothing and sets no cookie. */
export const NEW_PER_DAY = 5000;
/** The 30-day salt: made on first use, the one before kept so a reading near the turn is not blind, older ones deleted. */
export function visitorSalt(db: Database, at: number): string {
  const period = Math.floor(at / SALT_MS);
  const found = db.query<{ salt: string }, [number]>("SELECT salt FROM visitor_salt WHERE period = ?1").get(period);
  if (found !== null) return found.salt;
  const salt = Array.from(crypto.getRandomValues(new Uint8Array(24)), (b) => b.toString(16).padStart(2, "0")).join("");
  db.transaction(() => {
    db.query("INSERT OR IGNORE INTO visitor_salt (period, salt) VALUES (?1, ?2)").run(period, salt);
    db.query("DELETE FROM visitor_salt WHERE period < ?1").run(period - 1);
  })();
  return db.query<{ salt: string }, [number]>("SELECT salt FROM visitor_salt WHERE period = ?1").get(period)!.salt;
}
export interface Seen {
  readonly id: string;
  readonly kind: VisitorKind;
  readonly path: string;
  readonly ref: string;
  readonly step: number;
  readonly at: number;
}
/** Record one page view of a visitor. False when the visitor is new and today's cap on new visitors is spent: nothing is kept. */
export function noteVisitor(db: Database, v: Seen, cap: number = NEW_PER_DAY): boolean {
  const ref = v.ref.slice(0, REF_MAX);
  const path = (v.path.split(/[?#]/)[0] ?? "/").slice(0, 200);
  return db.transaction(() => {
    const known = db.query<{ last_seen: number }, [string]>("SELECT last_seen FROM visitor WHERE id = ?1").get(v.id);
    if (known === null) {
      const today = db
          .query<{ n: number }, [string, number]>(
            "SELECT COUNT(DISTINCT v.visitor) AS n FROM visitor_visit v JOIN visitor w ON w.id = v.visitor WHERE v.day = ?1 AND w.first_seen >= ?2",
          )
          .get(dayOf(v.at), Math.floor(v.at / 86_400_000) * 86_400_000)?.n ?? 0;
      if (today >= cap) return false;
    }
    const last = db
      .query<{ id: number; last: number; pages: string }, [string]>("SELECT id, last, pages FROM visitor_visit WHERE visitor = ?1 ORDER BY id DESC LIMIT 1")
      .get(v.id);
    const continues = last !== null && v.at - last.last <= VISIT_GAP_MS;
    if (known === null) {
      db.query(
        `INSERT INTO visitor (id, kind, first_seen, last_seen, days_seen, visits, first_ref, last_ref, step)
         VALUES (?1, ?2, ?3, ?3, 1, 1, ?4, ?4, ?5)`,
      ).run(v.id, v.kind, v.at, ref, v.step);
    } else {
      db.query(
        `UPDATE visitor SET last_seen = ?2, step = MAX(step, ?3),
           days_seen = days_seen + ?4, visits = visits + ?5, last_ref = CASE WHEN ?5 = 1 THEN ?6 ELSE last_ref END
         WHERE id = ?1`,
      ).run(v.id, Math.max(known.last_seen, v.at), v.step, dayOf(known.last_seen) === dayOf(v.at) ? 0 : 1, continues ? 0 : 1, ref);
    }
    if (continues && last !== null) {
      const pages = JSON.parse(last.pages) as string[];
      if (pages.length < PAGES_MAX) pages.push(path);
      db.query("UPDATE visitor_visit SET last = ?2, pages = ?3 WHERE id = ?1").run(last.id, v.at, JSON.stringify(pages));
    } else {
      db.query("INSERT INTO visitor_visit (visitor, day, started, last, entry_ref, pages) VALUES (?1, ?2, ?3, ?3, ?4, ?5)").run(
        v.id,
        dayOf(v.at),
        v.at,
        ref,
        JSON.stringify([path]),
      );
    }
    return true;
  })();
}
/** Starting or buying a forge makes the visitor someone: its id is linked to the forge's name, on the host's side only. */
export function linkVisitor(db: Database, id: string, forge: string, step: "started" | "paid", at: number): boolean {
  const n = STEPS.indexOf(step === "paid" ? "paid" : "started a forge");
  const done = db
    .query("UPDATE visitor SET forge = ?2, linked_at = ?3, step = MAX(step, ?4) WHERE id = ?1 AND (forge = '' OR forge = ?2)")
    .run(id, forge.slice(0, 100), at, n);
  return done.changes === 1;
}
/** Rows not seen for 13 months, and their visits. Returns the visitors removed. */
export function purgeVisitors(db: Database, now: number): number {
  const cut = now - KEEP_MS;
  return db.transaction(() => {
    db.query("DELETE FROM visitor_visit WHERE visitor IN (SELECT id FROM visitor WHERE last_seen < ?1)").run(cut);
    db.query("DELETE FROM visitor_visit WHERE last < ?1").run(cut);
    return db.query("DELETE FROM visitor WHERE last_seen < ?1").run(cut).changes;
  })();
}
@@ -0,0 +1,22 @@
/**
 * `traffic.returning` (#11265): whether this forge keeps a visitor id for its
 * own visitors. Stored in `forge_setting` under `traffic.returning`, every
 * change kept in `forge_setting_change`. Nothing stored reads as `off`, on every
 * forge: the owner chooses it for their own visitors, on Settings → Traffic. A
 * child's visitors are its own: nothing it collects reaches its host.
 */
import type { Database } from "bun:sqlite";
import { writeSetting } from "./limits.ts";
const STORE_KEY = "traffic.returning";
export function getReturning(db: Database): boolean {
  const row = db.query<{ value: string }, [string]>("SELECT value FROM forge_setting WHERE key = ?1").get(STORE_KEY);
  return row !== null && row.value === "on";
}
export function setReturning(db: Database, on: boolean, actorId: string): void {
  const from = getReturning(db);
  if (from === on) return;
  writeSetting(db, STORE_KEY, on ? "on" : "off", from ? "on" : "off", on ? "on" : "off", actorId);
}
@@ -6,6 +6,7 @@
 * the caller says `false` — returns the plan and changes nothing.
 */
import { linkRequestVisitor } from "../perf/visitor_link.ts";
import { startWatch, probeOf, type Probe } from "./live.ts";
import { firstProof, reachWords, settleChild } from "./reach.ts";
import { reissueClaim, spawnForge, type SpawnError } from "../actions/spawn.ts";
@@ -364,6 +365,8 @@
export async function spawnDoor(
  }
  if (!made.ok) return spawnWords(made.error);
  if (anon && !made.value.existed) noteAnonSpawn(ctx.app.db, ctx.request);
  // The visitor who started (or was given) this forge becomes someone, on the host's side (#11265).
  if (!made.value.existed) linkRequestVisitor(ctx.app, ctx.request, made.value.name, gift === undefined ? "started" : "paid");
  // Its apps come up now, so the first visit after a claim finds them awake.
  if (!made.value.existed) {
    void bootHostedChild(ctx.app, made.value.name);
@@ -79,6 +79,7 @@
import { entry as scorecard } from "./scorecard.ts";
import { entry as weekcard } from "./weekcard.ts";
import { entry as scrapes } from "./scrapes.ts";
import { entry as trafficScreenEntry } from "./traffic.ts";
import { entry as returningEntry } from "./returning.ts";
import { entry as securityControls } from "./controls.ts";
import { entry as secrets } from "./secrets.ts";
import { entry as sentinel } from "./sentinel.ts";
@@ -151,6 +152,7 @@
export const ENTRIES: readonly PaletteEntry[] = [
  flowsAll,
  scrapes,
  trafficScreenEntry,
  returningEntry,
  teams,
  orgTeams,
  orgGrants,
@@ -0,0 +1,68 @@
/**
 * Who comes back, in the terminal (#11265): the same figures as the block on
 * Settings → Traffic (`perf/visitor_report.ts`), for a forge admin only, and
 * `t` turns the setting `traffic.returning` on or off. The setting is the one
 * row the web page reads on every request, so a change here is seen there at once.
 */
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import { ledReport, visitorsReport } from "../../perf/visitor_report.ts";
import { getReturning, setReturning } from "../../settings/returning.ts";
import type { Session } from "../session.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import { fill, len, split } from "../ui/layout.ts";
import { ListState, drawList, type ListRow } from "./common.ts";
import type { PaletteEntry } from "./entries.ts";
const DAYS = 30;
const may = (f: Session): boolean => f.user?.isAdmin === true && f.user.kind !== "agent";
export function returningLines(f: Session, now = Date.now()): ListRow[] {
  if (!may(f)) return [];
  if (!getReturning(f.db)) return [{ title: "Off: no visitor id is kept for this forge's visitors", meta: "t turns it on" }];
  const r = visitorsReport(f.db, DAYS, now);
  const rows: ListRow[] = [{ title: `${r.newVisitors} new and ${r.returningVisitors} returning visitors in the last ${r.days} days`, meta: "returning is two visits or more" }];
  for (const v of r.returning)
    rows.push({
      title: `${v.id}${v.probable ? " (guessed)" : ""}: ${v.visits} visits`,
      meta: `first ${v.firstSeen} from ${v.firstRef} · last ${v.lastSeen} · got as far as ${v.step}`,
    });
  for (const l of ledReport(f.db))
    rows.push({ title: `Forge ${l.forge}: ${l.step}`, meta: `first came from ${l.firstRef} on ${l.firstSeen} · ${l.visits.map((v) => `${v.day} ${v.pages.join(" → ")}`).join("; ")}` });
  return rows;
}
export function returningScreen(f: Session, ctx: Ctx): Screen {
  const state = new ListState();
  return {
    title: "Who comes back",
    keys: [binding(["j", "k"], "move cursor"), binding(["t"], "turn on or off")],
    render(area, s) {
      const c = ctx.theme.c;
      const [head, list] = split(area, "v", [len(1), fill(1)]);
      s.text(head!.x, head!.y, truncate(`visitor ids for this forge: ${getReturning(f.db) ? "on" : "off"}; a visitor with no cookie is guessed`, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
      drawList(s, list!, c, state, returningLines(f));
    },
    key(e) {
      if (!may(f)) return false;
      if (e.key === "t") {
        const to = !getReturning(f.db);
        setReturning(f.db, to, f.user!.id);
        ctx.toast(to ? "Returning visitors are on." : "Returning visitors are off.", "success");
        return true;
      }
      return state.key(e, returningLines(f).length);
    },
  };
}
export const entry: PaletteEntry = {
  id: "returning-visitors",
  title: "Who comes back",
  hint: "new and returning visitors, and the setting that keeps them",
  after: ["traffic"],
  offered: may,
  run: (session, ctx) => ctx.push(returningScreen(session, ctx)),
};
@@ -5,6 +5,7 @@
 * Anyone else gets the not-found page.
 */
import { ledBlock } from "./visitors.ts";
import { BILLING_WORDS, STRIPE_WORDS, connectStripe, disconnectStripe, grantPlan, readBilling, saveSigningSecret, type BillingError, type StripeWords } from "../../actions/billing.ts";
import { CODE_ERRORS, makeCode, readCodes, revoke, type CodeError } from "../../actions/codes.ts";
import { publicOrigin } from "../../core/public_origin.ts";
@@ -186,6 +187,7 @@
function billingView(ctx: Ctx, shown?: Shown, values: Record<string, string> = {
        ? html`<p class="muted">No forge has been sent from here.</p>`
        : html`<ul class="list setting-list">${rows}</ul>`}
    </section>
    ${ledBlock(ctx)}
    ${funnelRow(funnelReport(ctx.app.db, 7))}
    ${linksSection(ctx, links)}
    ${codesSection(ctx, shown, values, error)}`;
@@ -0,0 +1,34 @@
/**
 * GET /privacy: what the forge keeps about a visitor, in three plain lines
 * (#11265). Public, static, server-rendered.
 */
import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
import type { Ctx } from "../../http/context.ts";
import { html } from "../html.ts";
import { page } from "../layout.ts";
export function privacyPage(ctx: Ctx): Response {
  notePhase(ctx.request, "session", takeSessionTime(ctx.request));
  return timePhase(ctx.request, "render", () =>
    page({
      ctx,
      title: "Privacy",
      body: html`<div class="page-head"><h1>Privacy</h1></div>
        <ul class="list">
          <li>
            Kept: a random visitor id in a first-party cookie (or, without it, a salted hash of your browser family, OS,
            language and network prefix), when you came, the page paths you opened (no query string) and the site you
            came from. Never your address or your full browser string.
          </li>
          <li>
            For how long: 13 months after you were last seen, then deleted. The hash's salt changes every 30 days.
          </li>
          <li>
            It never leaves this forge: it is shared with no one. A request with Global Privacy Control or Do Not Track
            gets no cookie and no visitor record, and the owner can turn this off.
          </li>
        </ul>`,
      }),
  );
}
@@ -32,6 +32,7 @@
import { page } from "../layout.ts";
import { TRAFFIC_TONES, trafficColumns } from "../studio/kpi_row.ts";
import { row, seg } from "../ui.ts";
import { accountSections } from "./origins.ts";
import { visitorsBlock } from "./visitors.ts";
const CHART_W = 600;
const CHART_H = 96;
@@ -192,7 +193,7 @@
export function trafficPage(ctx: Ctx): Response {
              })),
            )}
          </div>
          ${body}`,
          ${body}${visitorsBlock(ctx, now)}`,
        "Account settings",
      )}`,
  });
@@ -0,0 +1,119 @@
/**
 * Who comes back (#11265), on Settings → Traffic and the billing page: new
 * versus returning visitors per day (drawn here as SVG, no chart library), the
 * returning-visitor list, and for a forge started the visits that led
 * to it. A visitor with no cookie (a salted hash of coarse request facts)
 * says "guessed" on every row and is never merged with a cookie id. Admin only
 * by the pages that render it. The setting `traffic.returning` is changed here.
 */
import type { Ctx } from "../../http/context.ts";
import { daysOf, ledReport, visitorsReport, type DayCount, type Led, type Visitor } from "../../perf/visitor_report.ts";
import { getReturning, setReturning } from "../../settings/returning.ts";
import { notFoundPage } from "../chrome.ts";
import { field, readForm } from "../form.ts";
import { html, type Html } from "../html.ts";
import { flashTo } from "../layout.ts";
import { TRAFFIC_TONES } from "../studio/kpi_row.ts";
import { btn, row } from "../ui.ts";
const W = 600;
const H = 72;
/** The chart's tones are the Traffic chart's own: the lightest for new, the darkest for returning. */
const toneOf = (cls: "people" | "deep"): string => TRAFFIC_TONES.find(([c]) => c === cls)![1];
/** Two series per day, returning over new; a visitor without a cookie counts in the series it belongs to. */
function bars(perDay: readonly DayCount[]): Html {
  const back = (d: DayCount): number => d.returningCookie + d.returningProbable;
  const fresh = (d: DayCount): number => d.newCookie + d.newProbable;
  const peak = Math.max(1, ...perDay.map((d) => back(d) + fresh(d)));
  const step = W / Math.max(1, perDay.length);
  const rects: Html[] = [];
  perDay.forEach((d, i) => {
    let y = H;
    for (const [n, tone] of [
      [back(d), toneOf("deep")],
      [fresh(d), toneOf("people")],
    ] as const) {
      const h = (n / peak) * (H - 2);
      if (h === 0) continue;
      y -= h;
      rects.push(html`<rect x="${(i * step + 0.5).toFixed(1)}" y="${y.toFixed(1)}" width="${Math.max(1, step - 1).toFixed(1)}" height="${h.toFixed(1)}" fill="currentColor" fill-opacity="${tone}"></rect>`);
    }
  });
  return html`<svg viewBox="0 0 ${W} ${H}" width="100%" height="${H}" role="img" aria-label="Visitors per day, returning and new">${rects}</svg>`;
}
const GUESSED = html` <span class="muted small">guessed</span>`;
function returningRow(v: Visitor): Html {
  return row({
    title: html`<span class="mono">${v.id}</span>${v.probable ? GUESSED : null}`,
    meta: html`first came from ${v.firstRef}`,
    data: { visitor: v.id },
    facts: [
      { label: "Visits", value: String(v.visits) },
      { label: "First seen", value: v.firstSeen },
      { label: "Last seen", value: v.lastSeen },
      { label: "Got as far as", value: v.step },
    ],
  });
}
function led(l: Led): Html {
  return row({
    title: html`<span class="mono">${l.forge}</span>${l.probable ? GUESSED : null}`,
    meta: html`${l.step}`,
    data: { forge: l.forge },
    facts: [
      { label: "First came from", value: l.firstRef },
      { label: "First seen", value: l.firstSeen },
      ...l.visits.map((v, i) => ({ label: `Visit ${i + 1}, ${v.day}`, value: v.pages.join(" → ") })),
    ],
  });
}
/** The forges a visitor started, and the visits that led to each. */
export function ledBlock(ctx: Ctx): Html {
  const forges = ledReport(ctx.app.db);
  return html`<section class="settings-block">
    <h2>What led to a forge</h2>
    ${forges.length === 0
      ? html`<p class="muted small">No forge has been linked to a visitor yet. Forges started from a plan or a code are; a Stripe checkout is not yet.</p>`
      : html`<ul class="list setting-list">${forges.map(led)}</ul>`}
  </section>`;
}
/** The whole block for Settings → Traffic. */
export function visitorsBlock(ctx: Ctx, now: number): Html {
  const on = getReturning(ctx.app.db);
  const r = on ? visitorsReport(ctx.app.db, daysOf(ctx.url.searchParams.get("days")), now) : undefined;
  return html`<section class="settings-block" id="returning">
    <h2>Who comes back</h2>
    <form class="row-fields" method="post" action="/settings/traffic/returning">
      <input type="hidden" name="returning" value="${on ? "off" : "on"}" />
      <span class="small">${on ? "Keeping a visitor id for this forge's visitors." : "Off: no visitor id is kept for this forge's visitors."}</span>
      ${btn(on ? "Turn off" : "Turn on", { size: "sm", label: on ? "Turn off returning visitors" : "Turn on returning visitors" })}
    </form>
    ${r === undefined
      ? null
      : html`<p class="small muted">${r.newVisitors} new and ${r.returningVisitors} returning visitors in the last ${r.days} days; the darker bars are the ones who came back.</p>
          <div class="muted">${bars(r.perDay)}</div>
          ${r.returning.length === 0
            ? html`<p class="muted small" data-empty>No visitor has come back in the window.</p>`
            : html`<ul class="list setting-list">${r.returning.map(returningRow)}</ul>`}
          <p class="small muted">A visitor with no cookie is guessed from the browser, system, language and network, and marked guessed. <a href="/privacy">What is kept</a>.</p>`}
  </section>`;
}
/** POST /settings/traffic/returning: an admin turns the setting on or off. */
export async function returningSet(ctx: Ctx): Promise<Response> {
  if (ctx.auth.user?.isAdmin !== true || ctx.auth.user.kind === "agent") return notFoundPage(ctx);
  const form = await readForm(ctx, "admin");
  if (form instanceof Response) return form;
  const value = field(form, "returning");
  if (value !== "on" && value !== "off") return flashTo(ctx, "/settings/traffic", { tone: "danger", message: "Returning visitors are on or off." });
  setReturning(ctx.app.db, value === "on", ctx.auth.user.id);
  return flashTo(ctx, "/settings/traffic", { message: value === "on" ? "Returning visitors are on." : "Returning visitors are off." });
}
@@ -49,6 +49,9 @@
const UNREACHED: Record<string, { sites: number; why: string }> = {
  "src/web/pages/start_claim.ts": { sites: 1, why: "the claim of an agent's start needs a one-time token; same sessionCookie() as the walked doors; covered by test/start.test.ts" },
  "src/web/pages/signup-passkey.ts": { sites: 2, why: "sign-up by passkey needs an invite; same sessionCookie() as the walked doors" },
  "src/web/pages/map.ts": { sites: 1, why: "the map's last-looked cookie holds two timestamps, HttpOnly and Lax, and grants nothing; covered by test/roadmap.test.ts (name, HttpOnly, SameSite, no Secure over http)" },
  "src/http/measure.ts": { sites: 1, why: "the page-view beacon answers with the visitor cookie line from src/http/visitor.ts; HttpOnly, Lax, Secure over https from cookieLine; covered by test/visitors.test.ts" },
  "src/http/visitor.ts": { sites: 1, why: "the doc comment's mention of the Set-Cookie line it returns; covered by test/visitors.test.ts" },
  "src/perf/visitor_id.ts": { sites: 1, why: "cookieLine itself, the Set-Cookie line for forge_visitor: HttpOnly, SameSite=Lax, Secure over https; covered by test/visitors.test.ts" },
  "src/web/gift_cookie.ts": { sites: 1, why: "the gift code rides an HttpOnly, Lax cookie (Secure over https) and grants nothing by itself; covered by the gift code tests" },
  "src/web/pages/new-forge.ts": { sites: 1, why: "appends dropGift(), the gift cookie's clearing line from src/web/gift_cookie.ts" },
  "src/web/pages/everyday.ts": { sites: 2, why: "the admin/everyday switch needs a paired account; same sessionCookie() as the walked doors" },
@@ -234,6 +237,7 @@
const BUILDERS: Record<string, string> = {
  "cookie(": "src/apps/scaffold.ts, the scaffolded app's own `cookie`",
  clear: "src/http/rp.ts, `cookieHeader` with Max-Age 0",
  value: "src/apps/scaffold.ts, `redirectTo`'s cookies, each from `cookie`",
  cookie: "src/http/measure.ts, the line `trackVisitor` returns, built by `cookieLine` in src/perf/visitor_id.ts",
  "dropGift(": "src/web/gift_cookie.ts, the gift cookie cleared with Max-Age 0",
  "o.cookie": "src/web/layout.ts, a page's cookie (the theme literal in src/web/pages/site.ts)",
};
@@ -26,6 +26,7 @@
const AUDITED_CLEAR: string[] = [
  "app_feature_setting.value",
  "comment.body",
  "degraded_span.sentence",
  "efficiency_sample.value",
  "feed_chip.value",
  "fleet_operation.value",
  "gift_redeem.code_id",
@@ -73,6 +73,7 @@
const NOT_A_PAGE: Record<string, string> = {
  "/displays": "a list of displays behind sign-in; its slot is not pictured; covered by test/displays-list.test.ts",
  "/search": "a search box; its slot went to the preview seed's /next as its owner (#8866)",
  "/contribute": "a static page about how to help; its slot went to the preview seed's /bets as its owner (#8866)",
  "/privacy": "three static lines on what the forge keeps about a visitor (#11265); covered by test/visitors.test.ts",
  "/migrate": "an import form, nothing to picture until a job runs; the look slot went to /repos",
};
@@ -122,6 +122,7 @@
test("a site-admin person is offered the whole roster", () => {
    ["crawlers", "Crawlers", "their share of answering time, and who was refused"],
    ["scrapes", "Scrapes", "what was read by repository, and groups in a running capture"],
    ["traffic", "Traffic", "who is using the forge's answering time, and the top readers"],
    ["returning-visitors", "Who comes back", "new and returning visitors, and the setting that keeps them"],
    ["api", "API", "the forge's endpoints; run a GET"],
    ["docs", "Docs", "the forge's documentation; Enter reads one"],
    ["changelog", "Changelog", "the last 30 releases and their pulls"],
@@ -0,0 +1,274 @@
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { browserOf, cookieId, mintId, osOf, prefixOf, probableId } from "../src/perf/visitor_id.ts";
import { linkVisitor, noteVisitor, purgeVisitors, KEEP_MS } from "../src/perf/visitor_store.ts";
import { visitorsReport, probeVisitors } from "../src/perf/visitor_report.ts";
import { getReturning, setReturning } from "../src/settings/returning.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser } from "../src/core/users.ts";
import { linkRequestVisitor } from "../src/perf/visitor_link.ts";
import { loadKey } from "../src/kernel/secret.ts";
import { returningLines } from "../src/tui/screens/returning.ts";
import type { Session } from "../src/tui/session.ts";
let dir: string;
let app: App;
let servers: Servers;
let base: string;
let key: Buffer;
beforeAll(async () => {
  dir = await mkdtemp(join(tmpdir(), "visitors-"));
  app = createApp({ dataDir: dir, port: 0 });
  servers = await serve(app);
  base = `http://127.0.0.1:${servers.port}`;
  key = loadKey(dir);
});
afterAll(async () => {
  await servers.stop();
  await rm(dir, { recursive: true, force: true });
});
const CHROME = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
const DAY = 86_400_000;
const T0 = Date.parse("2026-11-01T10:00:00Z");
const beacon = (headers: Record<string, string> = {}) =>
  fetch(`${base}/_measure`, {
    method: "POST",
    headers: { origin: base, "user-agent": CHROME, "accept-language": "en-GB,en;q=0.8", ...headers },
    body: JSON.stringify({ path: "/", ttfb: 40, load: 300, lcp: 250, inp: 80, cls: 0.02 }),
  });
const count = (table = "visitor") => (app.db.query(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number }).n;
const wipe = () => {
  app.db.exec("DELETE FROM visitor; DELETE FROM visitor_visit");
};
describe("a returning visitor", () => {
  test("every forge reads the setting off until its owner turns it on, and an owner can change it", () => {
    expect(getReturning(app.db)).toBe(false);
    expect(app.db.query("SELECT COUNT(*) AS n FROM forge_setting WHERE key = 'traffic.returning'").get()).toEqual({ n: 0 });
    setReturning(app.db, true, "u");
    expect(getReturning(app.db)).toBe(true);
    app.db.exec("DELETE FROM forge_setting WHERE key = 'traffic.returning'");
    expect(getReturning(app.db)).toBe(false);
    setReturning(app.db, false, "u");
    expect(getReturning(app.db)).toBe(false);
  });
  test("with the setting off nothing is stored and no cookie is set", async () => {
    wipe();
    const res = await beacon();
    expect(res.status).toBe(204);
    expect(res.headers.get("set-cookie")).toBeNull();
    expect(count()).toBe(0);
  });
  test("the first view sets a first-party cookie with every attribute, and the same cookie on two days is one returning visitor with two visits", async () => {
    setReturning(app.db, true, "u");
    wipe();
    const first = await beacon();
    const line = first.headers.get("set-cookie")!;
    expect(line).toMatch(/^forge_visitor=c[0-9a-f]{32}\.[0-9a-f]{32}; /);
    for (const part of ["Path=/", "HttpOnly", "SameSite=Lax", `Max-Age=${396 * 86_400}`]) expect(line).toContain(part);
    expect(line).not.toContain("Domain");
    const id = cookieId(line, key)!;
    expect(id).toBeDefined();
    // The same cookie, on two different days.
    noteVisitor(app.db, { id, kind: "cookie", path: "/", ref: "news.example", step: 1, at: T0 });
    noteVisitor(app.db, { id, kind: "cookie", path: "/plans?x=1", ref: "", step: 2, at: T0 + 3 * DAY });
    const r = visitorsReport(app.db, 30, T0 + 4 * DAY);
    const mine = r.returning.find((v) => v.id === id.slice(0, 9))!;
    expect(mine).toMatchObject({ visits: 2, daysSeen: 2, probable: false, firstRef: "news.example", step: "clicked a plan" });
    expect(r.returningVisitors).toBe(1);
    const pages = app.db.query("SELECT pages FROM visitor_visit WHERE visitor = ? ORDER BY id").all(id) as { pages: string }[];
    expect(pages.map((p) => JSON.parse(p.pages))).toEqual([["/"], ["/plans"]]);
    expect(probeVisitors(app.db, 30, T0 + 4 * DAY, r).agrees).toBe(true);
  });
  test("a cookie-less repeat from the same network and browser is probable, and is not merged with a cookie id", async () => {
    wipe();
    await beacon();
    await beacon();
    const rows = app.db.query("SELECT id, kind, visits FROM visitor").all() as { id: string; kind: string; visits: number }[];
    expect(rows).toHaveLength(1);
    expect(rows[0]!.kind).toBe("probable");
    expect(rows[0]!.id.startsWith("p")).toBe(true);
    // Two views within 30 minutes are one visit; the probable row still reads "probable".
    const r = visitorsReport(app.db, 30, Date.now());
    expect(r.newVisitors).toBe(1);
    noteVisitor(app.db, { id: rows[0]!.id, kind: "probable", path: "/", ref: "", step: 0, at: Date.now() + 2 * DAY });
    expect(visitorsReport(app.db, 30, Date.now() + 2 * DAY).returning[0]).toMatchObject({ probable: true, visits: 2 });
    // A cookie arriving is a different visitor.
    await beacon({ cookie: `forge_visitor=${mintId(key).value}` });
    expect(count()).toBe(2);
  });
  test("only a cookie this forge signed is accepted: invented ids do not make rows", async () => {
    setReturning(app.db, true, "u");
    wipe();
    const real = mintId(key);
    expect(cookieId(`forge_visitor=${real.value}`, key)).toBe(real.id);
    expect(cookieId(`forge_visitor=${real.value}`, Buffer.from("another forge's key"))).toBeUndefined();
    expect(cookieId(`forge_visitor=${real.id}.${"0".repeat(32)}`, key)).toBeUndefined();
    expect(cookieId(`forge_visitor=${real.id}`, key)).toBeUndefined();
    for (let i = 0; i < 20; i++) {
      const invented = `c${i.toString(16).padStart(32, "0")}.${"a".repeat(32)}`;
      const res = await beacon({ cookie: `forge_visitor=${invented}` });
      expect(res.status).toBe(204);
    }
    // All twenty are one cookie-less probable visitor; none is a cookie row, and a fresh cookie is offered.
    const rows = app.db.query("SELECT kind FROM visitor").all() as { kind: string }[];
    expect(rows).toEqual([{ kind: "probable" }]);
  });
  test("a day takes at most the cap of new visitors; known visitors still count", () => {
    wipe();
    const at = T0;
    const first = mintId(key).id;
    expect(noteVisitor(app.db, { id: first, kind: "cookie", path: "/", ref: "", step: 0, at }, 2)).toBe(true);
    expect(noteVisitor(app.db, { id: mintId(key).id, kind: "cookie", path: "/", ref: "", step: 0, at }, 2)).toBe(true);
    expect(noteVisitor(app.db, { id: mintId(key).id, kind: "cookie", path: "/", ref: "", step: 0, at }, 2)).toBe(false);
    expect(count()).toBe(2);
    expect(noteVisitor(app.db, { id: first, kind: "cookie", path: "/x", ref: "", step: 0, at: at + 1000 }, 2)).toBe(true);
    // The next day has its own allowance.
    expect(noteVisitor(app.db, { id: mintId(key).id, kind: "cookie", path: "/", ref: "", step: 0, at: at + DAY }, 2)).toBe(true);
    expect(count()).toBe(3);
  });
  test("the terminal shows the same figures to an admin only, and its switch is the one the page reads", () => {
    wipe();
    setReturning(app.db, false, "u");
    const admin = { db: app.db, user: { id: "u", isAdmin: true, kind: "human" } } as unknown as Session;
    const other = { db: app.db, user: { id: "v", isAdmin: false, kind: "human" } } as unknown as Session;
    expect(returningLines(admin)[0]!.title).toContain("Off");
    setReturning(app.db, true, "u");
    const { id } = mintId(key);
    noteVisitor(app.db, { id, kind: "cookie", path: "/", ref: "news.example", step: 1, at: Date.now() - DAY });
    noteVisitor(app.db, { id, kind: "cookie", path: "/", ref: "", step: 1, at: Date.now() });
    const lines = returningLines(admin);
    expect(lines[0]!.title).toContain("1 returning");
    expect(lines.some((l) => l.title.startsWith(id.slice(0, 9)))).toBe(true);
    expect(returningLines(other)).toEqual([]);
  });
  test("a different browser or network is a different probable visitor, and a forged cookie is ignored", () => {
    const h = (ua: string) => new Headers({ "user-agent": ua, "accept-language": "en" });
    const a = probableId("s", h(CHROME), "203.0.113.5");
    expect(probableId("s", h(CHROME), "203.0.113.200")).toBe(a);
    expect(probableId("s", h(CHROME), "203.0.114.5")).not.toBe(a);
    expect(probableId("s", h(CHROME.replace("Chrome/120", "Chrome/121")), "203.0.113.5")).not.toBe(a);
    expect(probableId("t", h(CHROME), "203.0.113.5")).not.toBe(a);
    expect(cookieId("forge_visitor=../../etc", key)).toBeUndefined();
    expect(prefixOf("203.0.113.5")).toBe("203.0.113/24");
    expect(prefixOf("2001:db8:1:2:3:4:5:6")).toBe("2001:db8:1/48");
    expect(browserOf(CHROME)).toBe("chrome/120");
    expect(osOf(CHROME)).toBe("windows");
  });
  test("Sec-GPC and DNT get no cookie and no row, a scraper gets no id", async () => {
    wipe();
    for (const headers of [{ "sec-gpc": "1" }, { dnt: "1" }]) {
      const res = await beacon(headers);
      expect(res.status).toBe(204);
      expect(res.headers.get("set-cookie")).toBeNull();
    }
    const bot = await beacon({ "user-agent": "Googlebot/2.1 (+http://www.google.com/bot.html)" });
    expect(bot.headers.get("set-cookie")).toBeNull();
    const none = await beacon({ "user-agent": "" });
    expect(none.headers.get("set-cookie")).toBeNull();
    expect(count()).toBe(0);
    expect(count("visitor_visit")).toBe(0);
  });
  test("the visitor who starts a forge is linked to it, with the visits that led there", () => {
    wipe();
    const { id, value } = mintId(key);
    noteVisitor(app.db, { id, kind: "cookie", path: "/", ref: "news.example", step: 1, at: Date.now() - 6 * DAY });
    noteVisitor(app.db, { id, kind: "cookie", path: "/agents", ref: "", step: 1, at: Date.now() - 3 * DAY });
    noteVisitor(app.db, { id, kind: "cookie", path: "/spawn", ref: "", step: 2, at: Date.now() });
    linkRequestVisitor(app, new Request(base, { headers: { cookie: `forge_visitor=${value}` } }), "acme", "started");
    expect(linkVisitor(app.db, id, "other", "paid", Date.now())).toBe(false);
    const led = visitorsReport(app.db, 30, Date.now()).led[0]!;
    expect(led).toMatchObject({ forge: "acme", step: "started a forge", firstRef: "news.example" });
    expect(led.visits).toHaveLength(3);
    linkRequestVisitor(app, new Request(base, { headers: { cookie: `forge_visitor=${value}`, "sec-gpc": "1" } }), "acme", "paid");
    expect(visitorsReport(app.db, 30, Date.now()).led[0]!.step).toBe("started a forge");
    linkRequestVisitor(app, new Request(base, { headers: { cookie: `forge_visitor=${value}` } }), "acme", "paid");
    expect(visitorsReport(app.db, 30, Date.now()).led[0]!.step).toBe("paid");
  });
  test("rows past 13 months are removed, newer ones kept", () => {
    wipe();
    const now = Date.now();
    noteVisitor(app.db, { id: mintId(key).id, kind: "cookie", path: "/", ref: "", step: 0, at: now - KEEP_MS - DAY });
    noteVisitor(app.db, { id: mintId(key).id, kind: "cookie", path: "/", ref: "", step: 0, at: now - 30 * DAY });
    expect(purgeVisitors(app.db, now)).toBe(1);
    expect(count()).toBe(1);
    expect(count("visitor_visit")).toBe(1);
  });
  test("no raw address or full user agent is in the store", async () => {
    wipe();
    await fetch(`${base}/_measure`, {
      method: "POST",
      headers: { origin: base, "user-agent": `${CHROME} SecretMarker`, "x-forwarded-for": "198.51.100.77" },
      body: JSON.stringify({ path: "/", ttfb: 40, load: 300, lcp: 250, inp: 80, cls: 0.02 }),
    });
    expect(count()).toBe(1);
    const dump = JSON.stringify([
      app.db.query("SELECT * FROM visitor").all(),
      app.db.query("SELECT * FROM visitor_visit").all(),
      app.db.query("SELECT * FROM visitor_salt").all(),
    ]);
    for (const needle of ["SecretMarker", "Mozilla", "198.51.100", "127.0.0.1", "203.0.113"]) expect(dump).not.toContain(needle);
  });
  test("the privacy page says what is kept, and the visitors API is for admins only", async () => {
    const page = await (await fetch(`${base}/privacy`)).text();
    expect(page).toContain("13 months");
    expect(page).toContain("never leaves this forge");
    expect([401, 404]).toContain((await fetch(`${base}/api/v1/admin/traffic/visitors?days=30`)).status);
  });
  test("an admin reads the same figures from the API and the Traffic page, and flips the setting from it", async () => {
    const made = await createUser(app.db, { origin: "seed", trusted: true, username: "ada", email: "[email protected]", password: "correct-horse-battery", isAdmin: true });
    if (!made.ok) throw new Error(made.error);
    const cookie = `forge_session=${createSession(app.db, made.value.id).token}`;
    wipe();
    setReturning(app.db, true, "u");
    const { id } = mintId(key);
    noteVisitor(app.db, { id, kind: "cookie", path: "/", ref: "news.example", step: 1, at: Date.now() - DAY });
    noteVisitor(app.db, { id, kind: "cookie", path: "/", ref: "", step: 1, at: Date.now() });
    const api = (await (await fetch(`${base}/api/v1/admin/traffic/visitors?days=30`, { headers: { cookie } })).json()) as {
      returning: { id: string; visits: number }[];
      returning_visitors: number;
      probe: { agrees: boolean };
    };
    expect(api.returning_visitors).toBe(1);
    expect(api.returning[0]).toMatchObject({ id: id.slice(0, 9), visits: 2 });
    expect(api.probe.agrees).toBe(true);
    const page = await (await fetch(`${base}/settings/traffic`, { headers: { cookie } })).text();
    expect(page).toContain(id.slice(0, 9));
    expect(page).toContain("news.example");
    const off = await fetch(`${base}/settings/traffic/returning`, {
      method: "POST",
      redirect: "manual",
      headers: { cookie, origin: base, "content-type": "application/x-www-form-urlencoded" },
      body: "returning=off",
    });
    expect(off.status).toBe(303);
    expect(getReturning(app.db)).toBe(false);
    const cross = await fetch(`${base}/settings/traffic/returning`, {
      method: "POST",
      redirect: "manual",
      headers: { cookie, origin: "https://evil.example", "content-type": "application/x-www-form-urlencoded" },
      body: "returning=on",
    });
    expect(cross.status).not.toBe(303);
    expect(getReturning(app.db)).toBe(false);
  });
});
		@@ -93,6 +93,7 @@ Machine routes are not pages and have no entry: `/audit.csv`,
93	93	- `/forges/new` — `pages/new-forge.ts` · send a new forge · none · colour 1.
94	94	- `/family` — `pages/family.ts` · parent, this forge and children as a tree · `/forges` (the same children) · colour 1.
95	95	- `/claim` — `pages/claim.ts` · claim a forge that was sent to me · none · colour 1.
	96	- `/privacy` — `pages/privacy.ts` · what the forge keeps about a visitor, three plain lines, open to anyone · none · none seen.
96	97	- `/first-admin` — `pages/first-admin.ts` · the first person becomes admin · none · none seen.
97	98	- `/fleet/graph` — `pages/fleet-graph.ts` · the fleet as a graph · `/family`, `/forges` · none seen.
98	99	- `/fleet` — `pages/fleet.ts` · the rows a fleet query line selects, as a table · `/fleet/graph` · none seen.
		@@ -0,0 +1,23 @@
	1	# Returning visitors
	2
	3	Who comes back, how often, and what they did before they started or bought a forge (#11265).
	4	Settings → Traffic ("Who comes back"), the Billing page ("What led to a forge") and
	5	`GET /api/v1/admin/traffic/visitors?days=30` (admin token) answer the same; the API's `probe` counts the stored rows again.
	6
	7	- Setting `traffic.returning`. Off on every forge until its owner turns it on (nothing stored reads as off), on
	8	Settings → Traffic or in the terminal ("Who comes back", `t`). Nothing a child collects reaches its host.
	9	- Cookie id (primary). The page-view beacon's answer sets `forge_visitor`: random 128 bits signed with an HMAC of the forge's key (a value this forge did not sign is ignored, so a client cannot invent ids), `HttpOnly`, `Secure`
	10	(when the forge is https), `SameSite=Lax`, 13 months, no `Domain` (this host only).
	11	- Probable id (fallback). Without the cookie: a salted hash of browser family+major, OS, language and the /24 (v4) or
	12	/48 (v6) prefix; the salt lives in `visitor_salt` and rotates every 30 days. Shown as "guessed", never merged with a
	13	cookie id. A cookie-keeping browser's very first view is recorded as probable (the cookie does not exist yet); later
	14	views are the cookie id's. No client probing.
	15	- Bounded. A day takes at most 5000 new visitor rows (`NEW_PER_DAY`); past it nothing is kept and no cookie is set.
	16	- Respect. `Sec-GPC: 1`: no cookie, no visitor row (the view still counts in the anonymous daily total). `DNT: 1` counts nothing, as before.
	17	Scrapers get no id. The `forge_measure=off` cookie stores nothing at all.
	18	- Kept. Per visitor: first/last seen, days seen, visits, first and latest entry referrer, furthest step, and each
	19	visit's ordered paths (no query string; a gap over 30 minutes starts a new visit). No IP, no user agent. Rows not seen
	20	for 13 months are deleted by the `visitor-retention` maintenance duty.
	21	- Becoming someone. Spawning a forge (`POST /api/v1/forges`) links the request's cookie id to the forge name
	22	(`started a forge`; `paid` when a gift/plan code was redeemed). Stripe-paid checkouts are not linked yet.
	23	- `/privacy` says it in three lines.
		@@ -0,0 +1,11 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "get",
	5	path: "/api/v1/admin/traffic/visitors",
	6	summary:
	7	"Read who comes back (a person admin's token, any scope); query: days (1-90, default 30); answers { as_of, enabled, days, per_day: [{ day, new_cookie, returning_cookie, new_probable, returning_probable }], new_visitors, returning_visitors, returning: [{ id (shortened), probable, visits, days_seen, first_seen, last_seen, first_ref, last_ref, step, forge }], led: [{ forge, id, probable, step, first_ref, visits: [{ day, ref, pages }] }], probe: { new, returning, agrees } } where probe counts the stored visitor rows again; a probable id is a salted hash of coarse request facts, never merged with a cookie id",
	8	auth: true,
	9	role: "admin",
	10	refusals: { not_found: "the token is not a person who administers the forge" },
	11	};
		@@ -55,6 +55,7 @@ export { route as getApiV1AdminShield } from "./getApiV1AdminShield.ts";
55	55	export { route as getApiV1AdminSubscriptions } from "./getApiV1AdminSubscriptions.ts";
56	56	export { route as getApiV1AdminTeams } from "./getApiV1AdminTeams.ts";
57	57	export { route as getApiV1AdminTrafficProbe } from "./getApiV1AdminTrafficProbe.ts";
	58	export { route as getApiV1AdminTrafficVisitors } from "./getApiV1AdminTrafficVisitors.ts";
58	59	export { route as getApiV1Agents } from "./getApiV1Agents.ts";
59	60	export { route as getApiV1AgentsUsername } from "./getApiV1AgentsUsername.ts";
60	61	export { route as getApiV1AppTemplates } from "./getApiV1AppTemplates.ts";
		@@ -0,0 +1,1 @@
	1	cd373a08768e6497adfdde27984576d2abaeff0d96def19ff06c0673dc8f1f1a
		@@ -0,0 +1,35 @@
	1	// Who comes back (#11265): one row per visitor id (a first-party cookie id, or
	2	// a "probable" salted hash of coarse request facts), and one per visit with the
	3	// ordered paths. No address, no full user agent. Additive.
	4	export default `
	5	CREATE TABLE visitor (
	6	id TEXT PRIMARY KEY,
	7	kind TEXT NOT NULL,
	8	first_seen INTEGER NOT NULL,
	9	last_seen INTEGER NOT NULL,
	10	days_seen INTEGER NOT NULL,
	11	visits INTEGER NOT NULL,
	12	first_ref TEXT NOT NULL,
	13	last_ref TEXT NOT NULL,
	14	step INTEGER NOT NULL DEFAULT 0,
	15	forge TEXT NOT NULL DEFAULT '',
	16	linked_at INTEGER NOT NULL DEFAULT 0
	17	) WITHOUT ROWID;
	18	CREATE INDEX visitor_last_seen ON visitor (last_seen);
	19	CREATE INDEX visitor_forge ON visitor (forge) WHERE forge <> '';
	20	CREATE TABLE visitor_visit (
	21	id INTEGER PRIMARY KEY,
	22	visitor TEXT NOT NULL,
	23	day TEXT NOT NULL,
	24	started INTEGER NOT NULL,
	25	last INTEGER NOT NULL,
	26	entry_ref TEXT NOT NULL,
	27	pages TEXT NOT NULL
	28	);
	29	CREATE INDEX visitor_visit_visitor ON visitor_visit (visitor, id);
	30	CREATE INDEX visitor_visit_day ON visitor_visit (day);
	31	CREATE TABLE visitor_salt (
	32	period INTEGER PRIMARY KEY,
	33	salt TEXT NOT NULL
	34	);
	35	`;
		@@ -35,6 +35,7 @@ export const SYSTEM_NAMES: readonly string[] = [
35	35	"crew",
36	36	"agent",
37	37	"agents",
	38	"privacy",
38	39	"bot",
39	40	"steward",
40	41	"anonymous",
		@@ -10,6 +10,8 @@ import { crawlReport } from "../../perf/crawlers.ts";
10	10	import { getAppById } from "../../core/apps.ts";
11	11	import { FUNNEL_SCOPE, daysOf, funnelReport } from "../../perf/funnel.ts";
12	12	import { probeViews } from "../../perf/views_probe.ts";
	13	import { daysOf as visitorDaysOf, probeVisitors, visitorsReport } from "../../perf/visitor_report.ts";
	14	import { getReturning } from "../../settings/returning.ts";
13	15	import { kpiProbe } from "../../web/studio/kpi_probe.ts";
14	16	import { MAX_SECONDS, sampleStacks } from "../../perf/sample.ts";
15	17	import { listAccounts, removeAccount, retireAndRemoveAccount, retirementPlan, suspendAccount, unsuspendAccount, verifyAccount } from "../../actions/accounts.ts";
		@@ -179,6 +181,44 @@ export function adminRoutes(router: Router<Handler>): void {
179	181	return json(only === null ? probed : { ...probed, numbers: probed.numbers.filter((n) => n.id === only) });
180	182	});
181	183
	184	// Who comes back (`perf/visitor_report.ts`, #11265): the same figures as the Traffic page.
	185	router.add("GET", "/api/v1/admin/traffic/visitors", (ctx) => {
	186	notePhase(ctx.request, "session", takeSessionTime(ctx.request));
	187	const denied = accountAdmin(ctx, "ro");
	188	if (denied) return denied;
	189	const now = Date.now();
	190	const days = visitorDaysOf(ctx.url.searchParams.get("days"));
	191	const r = visitorsReport(ctx.app.db, days, now);
	192	return json({
	193	as_of: new Date(now).toISOString(),
	194	enabled: getReturning(ctx.app.db),
	195	days: r.days,
	196	per_day: r.perDay.map((d) => ({
	197	day: d.day,
	198	new_cookie: d.newCookie,
	199	returning_cookie: d.returningCookie,
	200	new_probable: d.newProbable,
	201	returning_probable: d.returningProbable,
	202	})),
	203	new_visitors: r.newVisitors,
	204	returning_visitors: r.returningVisitors,
	205	returning: r.returning.map((v) => ({
	206	id: v.id,
	207	probable: v.probable,
	208	visits: v.visits,
	209	days_seen: v.daysSeen,
	210	first_seen: v.firstSeen,
	211	last_seen: v.lastSeen,
	212	first_ref: v.firstRef,
	213	last_ref: v.lastRef,
	214	step: v.step,
	215	forge: v.forge,
	216	})),
	217	led: r.led.map((l) => ({ forge: l.forge, id: l.id, probable: l.probable, step: l.step, first_ref: l.firstRef, visits: l.visits })),
	218	probe: probeVisitors(ctx.app.db, days, now, r),
	219	});
	220	});
	221
182	222	// The forge's capacity (`core/capacity.ts`): read and changed live by an
183	223	// admin, never by an agent; anyone else is told the door is not there.
184	224	router.add("GET", "/api/v1/admin/capacity", (ctx) => {
		@@ -17,6 +17,7 @@ import { readBounded } from "./limits.ts";
17	17	import { clientAddress, clientBucket } from "./peer.ts";
18	18	import { originOf } from "../perf/sources.ts";
19	19	import { noteView } from "../perf/views_store.ts";
	20	import { trackVisitor } from "./visitor.ts";
20	21
21	22	const PER_CLIENT = 30;
22	23	const PER_FORGE = 1200;
		@@ -65,13 +66,15 @@ export async function measureSubmit(ctx: Ctx, routeOf: RouteOf): Promise<Respons
65	66	clientAddress(request),
66	67	request.headers.get("user-agent") ?? "",
67	68	);
	69	const origin = originOf(report.ref, report.q, ctx.url.host, report.out);
68	70	noteView(app.db, {
69	71	scope: "forge",
70	72	// The route pattern, never the path: a path can name a private repository.
71	73	path: route,
72		origin: originOf(report.ref, report.q, ctx.url.host, report.out),
	74	origin,
73	75	client: clientAddress(request),
74	76	agent: request.headers.get("user-agent") ?? "",
75	77	});
76		return refuse(204);
	78	const cookie = trackVisitor(app, request, ctx.url, { route, search: report.q, ref: origin.refHost \|\| origin.source });
	79	return refuse(204, cookie === undefined ? undefined : { "set-cookie": cookie });
77	80	}
		@@ -17,6 +17,7 @@ import {
17	17	import { secureFor } from "./cookie_secure.ts";
18	18	import { refusedByDatabase, shownRefusal } from "./refusal.ts";
19	19	import { NOT_A_MEMBER } from "../core/roles.ts";
	20	import { privacyPage } from "../web/pages/privacy.ts";
20	21	import { startClaimAccountSubmit, startClaimPage, startClaimSubmit } from "../web/pages/start_claim.ts";
21	22	import { signupOptions, signupPasskey } from "../web/pages/signup-passkey.ts";
22	23	import { toolbarComment, toolbarPage } from "../web/studio/toolbar.ts";
		@@ -939,6 +940,7 @@ export function buildRouter(): Router<Handler> {
939	940	router.add("GET", "/audit", auditPage);
940	941	router.add("GET", "/releases", releasesPage);
941	942	// The forge's own documentation: a redirect built from configuration only.
	943	router.add("GET", "/privacy", privacyPage);
942	944	router.add("GET", "/docs", docsFolder);
943	945	router.add("GET", "/docs/:file", docsFile);
944	946	router.add("GET", "/changelog", changelogPage);