analytics-platform 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 steviec87
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# analytics-platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One package for your Node server, run from your analytics dashboard: a
+**firewall**, **error monitoring** and **server analytics** (payments,
+sign-ups, leads). Turn modules on or off; the ones you turn off aren't loaded.
+No dependencies; Node 18 or later.
+
+```bash
+npm install analytics-platform
+```
+
+```js
+const { createPlatform } = require("analytics-platform");
+
+const platform = createPlatform({
+  siteId: "YOUR_SITE_ID",
+  secret: process.env.ANALYTICS_SITE_SECRET, // site settings; keep it on the server
+  endpoint: "https://YOUR_COLLECTOR_URL",
+  // trustProxy: 1,            // behind Nginx or a load balancer
+  // trustProxy: "cloudflare", // every request through Cloudflare
+});
+
+app.use(platform.middleware());   // before your routes
+
+// ...your routes...
+
+app.use(platform.errorHandler()); // after your routes
+```
+
+## Modules
+
+| Module | What it does | Default |
+|---|---|---|
+| `firewall` | Blocks addresses, known criminal networks, shared blocks and floods (Security → Firewall) | on |
+| `firewall`'s attack patterns | Rules that match the *request* (its path, query string and user agent), not just the address, so an attack is turned away before your code runs — a package with a known hole stays safe until you update it. They come with the firewall's rules and are managed on the Security page (Firewall → Attack patterns); a pattern a real visitor might trip only watches until you promote it. Nothing to configure (protocol: `sdk/protocols/firewall.md`) | with the firewall |
+| `proxy` | Serves the tracker and takes visits under your own domain, so ad blockers can't hide those visitors | on |
+| `errors` | Sends your server's errors to the Errors report | on |
+| `analytics` | `track()`, `identify()` and `lead()` from your server | on |
+| `performance` | Response times and errors of every route (Health → Server speed) | on |
+| `crawlers` | Which search engines and AI bots fetch your pages (Health → Crawlers). Your tracker can't see them: crawlers don't run JavaScript | on |
+| `audit` | `platform.audit("user.role_changed", { actor, target, details, req })` (Security → Audit log) | on |
+| `flags` | `platform.isEnabled("new-checkout", { user: user.id })`: features on or off from the dashboard | on |
+| `maintenance` | A "back soon" page while maintenance mode is on in the dashboard | on |
+| `headers` | Adds the security headers you pick on the Security page; your own headers win | on |
+| `forms` | Checks forms before you accept them: `platform.protectForm()` / `platform.checkForm(req)` | on |
+| `inventory` | Your production packages (`package-lock.json`) and Node version, once a day, so the Security check can flag known security holes (`{ dir }`: the folder with the lock file) | on |
+| `posture` | How the server is set up, once a day, for the Security check: `NODE_ENV`, whether the app runs as root, code anyone on the machine can write, and files in the folders you serve to the web that shouldn't be public (a dump, a `.env`, a `.bak`). The dashboard then asks your site for each of those files and tells you whether it really is downloadable. Reads only, and sends no file's contents. `{ roots: ["public", { dir: "uploads", prefix: "files" }] }` (default: `./public` and `./static` when they exist; `prefix` is where the web serves the folder), `{ checks }` for checks of your own (protocol: `sdk/protocols/posture.md`) | on |
+
+Each takes `true`, `false` or its options:
+
+```js
+createPlatform({
+  siteId, secret, endpoint,
+  firewall: { mode: "monitor", cacheFile: "./firewall-rules.json" },
+  errors: { captureUncaught: false },
+  analytics: false,
+});
+```
+
+**Switch modules off in the dashboard** (Security → Settings → Server package) without a
+deploy: the package checks about once a minute. A module turned off in your
+code isn't loaded at all, so the dashboard can't turn it on.
+
+Modules are independent: one failing to start, or the collector being down,
+never stops the others, and never slows your requests. The firewall checks
+requests against rules it keeps in memory; everything is sent in the
+background, in batches.
+
+## Firewall
+
+Rules, monitor or block mode and reports are in the dashboard (Security →
+Firewall). New sites start in monitor mode: nothing is blocked until you switch.
+
+| Option | |
+|---|---|
+| `mode` | `"monitor"` or `"block"`; overrides the dashboard |
+| `skip(req)` | return `true` to leave a request unchecked (health checks) |
+| `onBlock(req, res, decision)` | send your own response |
+| `cacheFile` | keep the last rules between restarts |
+| `trustProxy` | overrides the platform's |
+
+**The visitor's address:** behind a proxy, every request comes from the proxy
+unless you set `trustProxy`:
+
+| Setup | Option |
+|---|---|
+| Express with `app.set("trust proxy", ...)` | nothing (uses `req.ip`) |
+| One proxy (Nginx, a load balancer) | `trustProxy: 1` |
+| Cloudflare → load balancer | `trustProxy: 2` |
+| Every request through Cloudflare | `trustProxy: "cloudflare"` |
+
+**Bot protection:** call `platform.loginFailed(req)` when a login fails. Past
+the site's limit the address is banned here straight away and on your other
+servers within a minute or two. Floods (over the rate limit) are banned the
+same way, and the dashboard can ban visits the tracker scores high risk.
+
+Other frameworks: `platform.firewall.check({ ip, method, path, userAgent })`
+returns the decision.
+
+```js
+// Fastify
+fastify.addHook("onRequest", async (req, reply) => {
+  const d = platform.firewall.check({ ip: req.ip, method: req.method, path: req.url, userAgent: req.headers["user-agent"] });
+  if (d.action === "block") return reply.code(d.status).send("Forbidden");
+});
+```
+
+
+**Probes.** Requests for files no visitor ever asks for (`/.env`, `/.git/…`,
+backups: the list comes with the rules) are rule `probe`; in block mode the
+address is also banned on this server, and the collector bans it on the
+site's other servers.
+## Error monitoring
+
+Uncaught exceptions and unhandled rejections are sent on their own; your
+process still exits as it would. `errorHandler()` sends 5xx errors from your
+routes. Errors you catch:
+
+```js
+try {
+  await chargeCard(order);
+} catch (error) {
+  platform.captureException(error, { req, status: 502 });
+  throw error;
+}
+```
+
+Options: `serverName`, `root` (stack paths relative to it), `captureUncaught`,
+`beforeSend(event, error)` (change an error, or return `null` to drop it).
+
+## Server analytics
+
+For what only your server knows for sure. Not pageviews: the tracker counts
+those.
+
+```js
+// A payment
+platform.track("purchase", { numeric_value: "49.90", currency: "EUR", event_uid: `order-${order.id}` }, { req });
+
+// Link the visit to your user
+await platform.identify(user.id, { req });
+
+// Add or update a lead
+await platform.lead({ email: "ana@example.com", name: "Ana", status: "qualified" });
+```
+
+**Link to the visit:** send the tracker's session ID with your site's requests,
+and pass `{ req }`:
+
+```js
+fetch("/api/orders", { headers: { "x-analytics-session": window.analyticsSession?.getId() || "" }, ... });
+```
+
+## Next.js and Vercel
+
+The firewall in Next.js's proxy (`proxy.ts`, or `middleware.ts` before Next.js
+16), which runs on the edge too, and server errors from `instrumentation.ts`:
+
+```ts
+// proxy.ts
+import { createNextFirewall } from "analytics-platform/next";
+export const proxy = createNextFirewall({ siteId, secret: process.env.ANALYTICS_SITE_SECRET!, endpoint });
+export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
+
+// instrumentation.ts
+import { createOnRequestError } from "analytics-platform/next";
+export const onRequestError = createOnRequestError({ siteId, secret: process.env.ANALYTICS_SITE_SECRET!, endpoint });
+```
+
+On Vercel the visitor's address is found for you; elsewhere set `trustProxy`.
+Each instance keeps the rules in memory and counts the rate limit on its own:
+pass `counter: async (key, ttl) => hits` (e.g. Upstash Redis) for one count.
+For events from route handlers and server actions, use `createPlatform` there.
+
+## Crawlers and AI bots
+
+`platform.middleware()` counts every request from a crawler — `GPTBot`,
+`ClaudeBot`, `ChatGPT-User`, `PerplexityBot`, `Googlebot`, `bingbot`, the SEO
+tools, the link previews — and sends one small summary a minute per bot, page
+and status. See it under Health → Crawlers.
+
+Your browser tracker cannot see any of this: crawlers don't run JavaScript. So
+this is the only place you learn that an AI fetched a page because someone
+asked it about you, that Googlebot has been asking for a page you deleted, or
+that something calling itself Googlebot isn't.
+
+Nothing about your visitors is counted or sent: a request is counted only when
+its user agent names a crawler. Requests the firewall turned away are counted
+too, with the status the crawler got.
+
+```js
+createPlatform({
+  siteId, secret, endpoint,
+  crawlers: { serverName: "web-1" },  // or false to leave them uncounted
+});
+```
+
+Crawler addresses go with each batch so the collector can check a crawler is
+itself (Google, Bing, Yandex, Baidu and Apple publish a reverse-DNS
+convention; for the rest the network is shown). No address is stored. The
+protocol is `sdk/protocols/crawlers.md`.
+
+Other frameworks: `platform.crawlers.record({ bot, path, status, bytes, ms, ip })`,
+with `platform.crawlers.detect(userAgent)` for the bot's name (`""` when the
+request isn't from one).
+
+## Performance & API monitoring
+
+`platform.middleware()` times every request it lets through and sends one
+small summary a minute per route (Express route patterns like `/users/:id`;
+elsewhere numbers and IDs in the path become `:id`). See it under Health →
+Server speed. Name routes yourself with `performance: { route: (req) => "..." }`.
+
+## Ad blockers
+
+Many visitors use an ad blocker, and most blockers stop analytics. They
+recognise **the address a script comes from** and **what it is called**, so a
+tracker loaded from us is simply never counted.
+
+This package already runs on your own domain, so it serves the tracker and
+takes the visits itself. Nothing to set up: use the two addresses it gives you
+in your page's script tag.
+
+```js
+app.use(platform.middleware());        // the proxy answers before anything else
+
+// in your template
+`<script async src="${platform.proxy.scriptUrl()}"
+         data-siteid="${siteId}" data-domain="example.com"
+         data-collect="${platform.proxy.collectUrl()}"></script>`
+```
+
+- The path comes from your secret (`/3f9a2c1b/...`), so it isn't in the page
+  and isn't a name any blocker lists. Pick your own with `proxy: { prefix }`.
+- Tracker files are fetched once and then served from memory; if we can't be
+  reached, the copy already held is served rather than nothing.
+- The visitor's address goes on as `X-Forwarded-For` (your collector needs it
+  for the country, the daily visitor ID and the rate limit) and cookies never
+  leave your server.
+- Beacons are answered before the firewall, the crawler count and the timing,
+  so your own analytics traffic doesn't appear as pages of your site.
+- Switch it off with `proxy: false`, or in the dashboard (Site settings →
+  Server). Then load the tracker from us as before.
+
+## Shutting down and serverless
+
+`await platform.flush()` sends everything waiting (on Vercel or Lambda, before
+returning). `await platform.close()` also stops fetching rules.

package/index.d.ts

@@ -0,0 +1,184 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export type TrustProxy = boolean | number | "cloudflare" | ((req: IncomingMessage) => string);
+
+export interface FirewallDecision {
+  action: "allow" | "block" | "monitor";
+  /** Empty when allowed. */
+  rule: "deny" | "ban" | "list" | "shared" | "rate" | "";
+  /** 403, or 429 for the rate limit. */
+  status: number;
+}
+
+export interface FirewallOptions {
+  /** Overrides the platform's trustProxy. */
+  trustProxy?: TrustProxy;
+  /** Overrides the mode set in the dashboard. */
+  mode?: "monitor" | "block";
+  /** Return true to leave a request unchecked. */
+  skip?: (req: IncomingMessage) => boolean;
+  /** Send your own response for blocked requests. */
+  onBlock?: (req: IncomingMessage, res: ServerResponse, decision: FirewallDecision) => void;
+  /** Keeps the last rules on disk, so they apply straight after a restart. */
+  cacheFile?: string;
+}
+
+export interface ErrorsOptions {
+  /** Default: the host name. */
+  serverName?: string;
+  /** Paths in stacks are made relative to it. Default: process.cwd(). */
+  root?: string;
+  /** Capture uncaught exceptions and unhandled rejections. Default true. */
+  captureUncaught?: boolean;
+  /** Change an error before it's sent, or return null to drop it. */
+  beforeSend?: (event: Record<string, unknown>, error: unknown) => Record<string, unknown> | null;
+}
+
+export interface PlatformOptions {
+  siteId: string;
+  /** The site secret (site settings). Keep it on the server. */
+  secret: string;
+  /** The collector's URL. */
+  endpoint: string;
+  /**
+   * How to find the visitor's address. Default: Express's req.ip, else the
+   * connection's address. A number trusts that many proxies in
+   * X-Forwarded-For (true = 1); "cloudflare" reads CF-Connecting-IP.
+   */
+  trustProxy?: TrustProxy;
+  /** Logs send problems. */
+  debug?: boolean;
+  /** On by default. */
+  firewall?: boolean | FirewallOptions;
+  /** On by default. */
+  errors?: boolean | ErrorsOptions;
+  /** On by default. */
+  analytics?: boolean;
+  /** Security headers picked on the dashboard. On by default (adds none until you pick some). */
+  headers?: boolean;
+  /** Feature flags. On by default. */
+  flags?: boolean;
+  /** Maintenance mode. On by default (does nothing until you turn it on in the dashboard). */
+  maintenance?: boolean | { skip?: (req: IncomingMessage) => boolean };
+  /** Audit log. On by default. */
+  audit?: boolean;
+  /** Form protection. On by default. */
+  forms?: boolean;
+  /**
+   * Software inventory: your production packages (package-lock.json) and Node
+   * version, sent once a day for the Security check. On by default.
+   */
+  inventory?: boolean | {
+    /** The folder with package-lock.json. Default: the working directory. */
+    dir?: string;
+    /** The server's name. Default: the host name. */
+    host?: string;
+  };
+  /**
+   * How the server is set up, sent once a day for the Security check: whether
+   * the app runs in production and as root, code anyone on the machine can
+   * write, and files in the folders you serve to the web that shouldn't be
+   * public (a dump, a .env, a backup copy). Reads only; no file's contents are
+   * sent. On by default; with no served folder, only the settings are reported.
+   */
+  posture?: boolean | {
+    /** The folders the web serves. Default: ./public and ./static when they exist. */
+    roots?: (string | { dir: string; prefix?: string })[];
+    /** The server's name. Default: the host name. */
+    host?: string;
+    /** More checks of your own: { id, state: "pass" | "fail" | "unknown", value? }. */
+    checks?: () => Promise<{ id: string; state: string; value?: string }[]> | { id: string; state: string; value?: string }[];
+  };
+  /**
+   * First-party proxy: serve the tracker and take visits under this site's
+   * own domain, so ad blockers have no address or filename of ours to
+   * recognise. On by default; the page's script tag uses proxy.scriptUrl()
+   * and proxy.collectUrl().
+   */
+  proxy?: boolean | {
+    /** The path it answers on. Default: eight characters from the secret. */
+    prefix?: string;
+  };
+  /** Performance & API monitoring. On by default. */
+  performance?: boolean | {
+    serverName?: string;
+    /** Your own route name for a request ("" to use the default). */
+    route?: (req: IncomingMessage) => string;
+  };
+}
+
+export interface EventFields {
+  value?: string;
+  numeric_value?: string | number;
+  currency?: string;
+  url?: string;
+  event_label?: string;
+  variant?: string;
+  id?: string;
+  session_id?: string;
+  timestamp?: string;
+  /** One occurrence: reuse it when sending the same occurrence again. */
+  event_uid?: string;
+  [key: string]: unknown;
+}
+
+export interface WithRequest {
+  /** The request, to link to the visit (x-analytics-session header). */
+  req?: IncomingMessage;
+}
+
+export interface Platform {
+  /** The modules that are on. */
+  modules: string[];
+  /** The firewall module, for check() in frameworks without middleware. */
+  firewall: {
+    check(input: { ip: string; method?: string; path?: string; userAgent?: string }): FirewallDecision;
+    clientIp(req: IncomingMessage): string;
+  } | null;
+  /**
+   * The first-party proxy's two addresses, on this site's own domain, for the
+   * script tag: <script src={scriptUrl()} data-collect={collectUrl()} ...>.
+   */
+  proxy: {
+    /** The path it answers on. */
+    prefix: string;
+    /** The tracker's address, e.g. "/3f9a2c1b/js/v1/s.js". */
+    scriptUrl(version?: string): string;
+    /** Where visits are sent, e.g. "/3f9a2c1b/api/e". */
+    collectUrl(): string;
+    /** Whether it is on (it can also be switched off in the dashboard). */
+    enabled(): boolean;
+  } | null;
+  /** Before your routes. */
+  middleware(): (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
+  /** After your routes. Captures 5xx errors and passes them on. */
+  errorHandler(options?: { shouldCapture?: (error: unknown, req: IncomingMessage) => boolean }):
+    (error: unknown, req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+  /** Checks a form before you accept it (form protection). Spam goes to Leads → Spam. */
+  checkForm(req: IncomingMessage | null, options?: { fields?: Record<string, unknown>; email?: string; name?: string; form?: string }):
+    Promise<{ ok: boolean; spam: boolean; reasons: string[]; checked: boolean }>;
+  /** Express middleware for a form route (after your body parser): spam gets a 422. */
+  protectForm(options?: { email?: string; name?: string; form?: string; onSpam?: (req: IncomingMessage, res: ServerResponse, result: { reasons: string[] }) => void }):
+    (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
+  /** A feature flag from the dashboard. user: for rollouts and user lists; default: until it's known (false). */
+  isEnabled(key: string, options?: { user?: string | number; default?: boolean }): boolean;
+  /** Records who did what (Security → Audit log). action: e.g. "user.role_changed". */
+  audit(action: string, options?: { actor?: string; target?: string; details?: unknown; req?: IncomingMessage }): void;
+  /** A failed login on your site (bot protection): the request, or the address. */
+  loginFailed(reqOrIp: IncomingMessage | string): void;
+  captureException(error: unknown, context?: { req?: IncomingMessage; status?: number; kind?: "handled" | "error" | "rejection" }): void;
+  /** Returns the event's event_uid ("" when not queued). */
+  track(name: string, fields?: EventFields, options?: WithRequest): string;
+  /** Links the visit to your user ID. */
+  identify(userId: string, options?: WithRequest & { session_id?: string }): Promise<boolean>;
+  /** Adds or updates a lead. */
+  lead(fields: Record<string, unknown>, options?: WithRequest): Promise<{ status: string; lead_id: string } | null>;
+  /** Resolves once each module that fetches something has tried once. */
+  ready: Promise<void>;
+  /** Sends everything waiting (serverless: before returning). */
+  flush(): Promise<void>;
+  /** Stops background work and sends what's waiting. */
+  close(): Promise<void>;
+}
+
+export function createPlatform(options: PlatformOptions): Platform;

package/index.js

@@ -0,0 +1,124 @@
+// One package for a site's Node server, run from the analytics dashboard.
+// Each module (lib/) is separate: only the ones turned on are loaded, and one
+// failing never stops the others; the firewall in particular never waits on
+// reporting. Every module shares the core's credentials and sending.
+//
+//   const platform = createPlatform({ siteId, secret, endpoint });
+//   app.use(platform.middleware());   // before your routes
+//   ...routes...
+//   app.use(platform.errorHandler()); // after your routes
+//
+// A module is on with `true` (or its options as an object) and off with
+// `false`; one that's loaded can also be switched off in the dashboard (Site
+// settings → Server). No dependencies; Node 18+ (global fetch).
+"use strict";
+
+const { createCore } = require("./lib/core.js");
+
+// Module name -> [loader, on by default].
+const MODULES = {
+  firewall: [(core, opts) => require("./lib/firewall.js").createFirewall(core, opts), true],
+  errors: [(core, opts) => require("./lib/errors.js").createErrors(core, opts), true],
+  analytics: [(core) => require("./lib/analytics.js").createAnalytics(core), true],
+  performance: [(core, opts) => require("./lib/performance.js").createPerformance(core, opts), true],
+  crawlers: [(core, opts) => require("./lib/crawlers.js").createCrawlers(core, opts), true],
+  forms: [(core, opts) => require("./lib/forms.js").createForms(core, opts), true],
+  headers: [(core) => require("./lib/headers.js").createHeaders(core), true],
+  audit: [(core, opts) => require("./lib/audit.js").createAudit(core, opts), true],
+  flags: [(core) => require("./lib/flags.js").createFlags(core), true],
+  maintenance: [(core, opts) => require("./lib/maintenance.js").createMaintenance(core, opts), true],
+  inventory: [(core, opts) => require("./lib/inventory.js").createInventory(core, opts), true],
+  posture: [(core, opts) => require("./lib/posture.js").createPosture(core, opts), true],
+  resources: [(core, opts) => require("./lib/resources.js").createResources(core, opts), true],
+  proxy: [(core, opts) => require("./lib/proxy.js").createProxy(core, opts), true],
+};
+
+// Options: siteId, secret (site settings; keep it on the server), endpoint
+// (the collector's URL); trustProxy (how to find the visitor's address, for
+// every module that needs it: see README); debug (log send problems); and
+// per module, true / false / { options }.
+function createPlatform(options = {}) {
+  const core = createCore(options);
+  if (!core.valid) console.warn("[analytics-platform] siteId, secret and endpoint are required; nothing is sent and every request passes");
+
+  const modules = {};
+  for (const [name, [load, onByDefault]] of Object.entries(MODULES)) {
+    const setting = options[name] === undefined ? onByDefault : options[name];
+    if (setting === false) continue;
+    const opts = { trustProxy: options.trustProxy, ...(setting && typeof setting === "object" ? setting : {}) };
+    // Form checks find the visitor's address the way the firewall does.
+    if (["forms", "audit", "maintenance", "crawlers", "proxy"].includes(name) && modules.firewall) opts.clientIp = modules.firewall.clientIp;
+    try {
+      modules[name] = load(core, opts);
+    } catch (error) {
+      console.warn(`[analytics-platform] the ${name} module could not start and is off:`, error?.message);
+    }
+  }
+
+  const switches = core.start(Object.keys(modules));
+  const off = (name) => () => core.log(name, "module is off");
+  const { firewall, errors, analytics, performance, crawlers, forms, headers, audit, flags, maintenance, proxy } = modules;
+
+  return {
+    // The modules that are on, by name.
+    modules: Object.keys(modules),
+    firewall: firewall || null,
+    // record({ bot, path, status, bytes, ms, ip }) and detect(userAgent), for
+    // frameworks that aren't Express.
+    crawlers: crawlers || null,
+    // The first-party proxy: scriptUrl(major) and collectUrl() are the two
+    // addresses the page's script tag needs, on this site's own domain.
+    proxy: proxy || null,
+
+    // Express / Connect / node:http middleware, before your routes: the
+    // tracker's own addresses are answered first (a visitor's beacon is our
+    // traffic, not a page of the site: it shouldn't be counted, timed or
+    // rate-limited), then crawlers are counted (a crawler the firewall turns
+    // away is still a crawler), then the firewall, then timing (blocked
+    // requests aren't timed).
+    middleware() {
+      const timed = (req, res, next) => (performance ? performance.middleware(req, res, next) : next());
+      const open = (req, res, next) => (maintenance ? maintenance.middleware(req, res, () => timed(req, res, next)) : timed(req, res, next));
+      const guarded = (req, res, next) => (firewall ? firewall.middleware(req, res, () => open(req, res, next)) : open(req, res, next));
+      const counted = (req, res, next) => (crawlers ? crawlers.middleware(req, res, () => guarded(req, res, next)) : guarded(req, res, next));
+      const withHeaders = (req, res, next) => (headers ? headers.middleware(req, res, () => counted(req, res, next)) : counted(req, res, next));
+      return function platformMiddleware(req, res, next = () => {}) {
+        if (!proxy) return withHeaders(req, res, next);
+        return proxy.middleware(req, res, () => withHeaders(req, res, next));
+      };
+    },
+
+    // Express error middleware, after your routes. Captures 5xx errors.
+    errorHandler(handlerOptions) {
+      return errors ? errors.errorHandler(handlerOptions) : (error, req, res, next) => next(error);
+    },
+
+    captureException: errors ? errors.captureException : off("errors"),
+    // A failed login (bot protection): pass the request, or the address.
+    loginFailed: firewall ? firewall.loginFailed : off("firewall"),
+    // Form protection: check a form before accepting it, or protect a route.
+    checkForm: forms ? forms.checkForm : async () => ({ ok: true, spam: false, reasons: [], checked: false }),
+    protectForm: forms ? forms.protectForm : () => (req, res, next) => next(),
+    // Feature flags: isEnabled("new-checkout", { user }) (false until known).
+    isEnabled: flags ? flags.isEnabled : (key, { default: fallback = false } = {}) => fallback,
+    // Audit log: audit("user.role_changed", { actor, target, details, req }).
+    audit: audit ? audit.audit : off("audit"),
+    track: analytics ? analytics.track : () => (off("analytics")(), ""),
+    identify: analytics ? analytics.identify : async () => (off("analytics")(), false),
+    lead: analytics ? analytics.lead : async () => (off("analytics")(), null),
+
+    // Resolves once each module that fetches something has tried once.
+    ready: Promise.all([switches, ...Object.values(modules).map((m) => m.ready).filter(Boolean)]).then(() => undefined),
+
+    // Sends everything waiting.
+    flush: () => Promise.all(Object.values(modules).map((m) => m.flush?.())).then(() => undefined),
+
+    // Stops background work and sends what's waiting (for a clean shutdown).
+    close: () => {
+      core.stop();
+      return Promise.all(Object.values(modules).map((m) => m.close?.())).then(() => undefined);
+    },
+  };
+}
+
+module.exports = { createPlatform };