@hadoku/service-kernel 0.0.0-stage → 0.1.0

package/dist/telemetry/telemetry.js

@@ -0,0 +1,221 @@
+/**
+ * Security telemetry: who got in, who was turned away, and who is spending the costly acts — the
+ * platform half. Knows no game: the service id, the deployment site and the refusal surface are
+ * all parameters, so an app that posts under `service: 'cardtable'` and one that posts under a
+ * second game's id read apart in the same monitoring store. See the app's own adapter (this
+ * wave's `apps/server/src/telemetry.ts`) for the one place those values get bound.
+ *
+ * Everything here is fire-and-forget. A post that fails is logged on stdout (pm2 keeps it), never
+ * retried, and never delays the request that caused it. One event per (name, caller, incident
+ * key) per window goes out; the rest are counted and ride on the next one as `suppressed`, so a
+ * scanner hammering the seal costs monitoring one row a minute, not one per request.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+/** What `report` does before boot installs a sink, and in every test that installs none. */
+const NOOP = () => { };
+let installed = NOOP;
+/** The process's reporter. The app's boot installs the monitoring sink once. */
+export function installTelemetry(sink) {
+    installed = sink;
+}
+/** Report one event. A no-op until a sink is installed. */
+export function report(event, context, level) {
+    installed(event, context, level);
+}
+/** An event's level when its reporter names none: a refusal or a rate limit is a warning, the rest is traffic. */
+function levelOf(event) {
+    return event.endsWith('-refused') || event === 'rate-limited' ? 'warn' : 'info';
+}
+/**
+ * Which deployment a base path is: `/<service>` is prod, `/<service>-<site>` that site (a PPE
+ * wrapper's prefix, e.g. `/<service>-ppe`). Any other prefix names itself.
+ */
+export function siteOf(basePrefix, service) {
+    const m = new RegExp(`^/${service}(?:-([^/]+))?/?$`).exec(basePrefix);
+    return m === null ? basePrefix : (m[1] ?? 'prod');
+}
+/**
+ * A hosting alert's level, from what it says: 🚨 is critical; a resolution (the alerts post one
+ * under `<key>:resolved`) or a ✅ is info; every other alert is a warning.
+ */
+function alertLevel(key, text) {
+    if (text.startsWith('🚨'))
+        return 'critical';
+    if (key.endsWith(':resolved') || text.startsWith('✅'))
+        return 'info';
+    return 'warn';
+}
+/**
+ * The hosting alerts (`play/placement/alerts.ts`) as service events, so the daily report lists
+ * each one beside the seal refusals. Wraps the log the alerts are given: every entry still goes
+ * to it, and each `alert` entry — one per message the alerts post to Discord — is also reported
+ * as `alert` with its key and text, at `alertLevel`. Every key is reported, so an alert kind
+ * added later needs nothing here.
+ */
+export function reportingAlerts(log, sink = report) {
+    return (entry) => {
+        log(entry);
+        if (entry.evt === 'alert' && typeof entry.key === 'string' && typeof entry.text === 'string') {
+            sink('alert', { key: entry.key, text: entry.text }, alertLevel(entry.key, entry.text));
+        }
+    };
+}
+/** The throttle forgets keys past this many, oldest first, so it cannot grow without bound. */
+const MAX_KEYS = 5000;
+/**
+ * A reporter that posts to monitoring-api. Without a service key it posts
+ * nothing and says so once, the way the stats reporter does.
+ */
+export function monitoringSink(opts) {
+    const { log } = opts;
+    if (opts.serviceKey === '') {
+        log({
+            evt: 'telemetry-disabled',
+            reason: `${opts.serviceKeyEnvVar} is not set`,
+        });
+        return NOOP;
+    }
+    const windowMs = opts.windowMs ?? 60_000;
+    const now = opts.now ?? Date.now;
+    const doFetch = opts.fetch ?? fetch;
+    const url = `${opts.baseUrl}/health/api/telemetry`;
+    const last = new Map();
+    return (event, context, explicit) => {
+        const key = `${event}\u0000${String(context.userId ?? '')}\u0000${String(context.key ?? '')}`;
+        const t = now();
+        const seen = last.get(key);
+        if (seen !== undefined && t - seen.at < windowMs) {
+            seen.suppressed += 1;
+            return;
+        }
+        const suppressed = seen?.suppressed ?? 0;
+        last.delete(key);
+        last.set(key, { at: t, suppressed: 0 });
+        if (last.size > MAX_KEYS)
+            last.delete(last.keys().next().value);
+        const level = explicit ?? levelOf(event);
+        const body = {
+            source: 'service',
+            level: level === 'critical' ? 'error' : level,
+            type: 'log',
+            message: `event=${event}`,
+            context: {
+                service: opts.service,
+                site: opts.site,
+                ...context,
+                ...(level === 'critical' ? { severity: level } : {}),
+                ...(suppressed > 0 ? { suppressed } : {}),
+            },
+        };
+        doFetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': `Mozilla/5.0 hadoku-${opts.service}`,
+                'X-User-Key': opts.serviceKey,
+            },
+            body: JSON.stringify(body),
+        })
+            .then((res) => {
+            if (!res.ok)
+                log({ evt: 'telemetry-post-failed', event, status: res.status });
+        })
+            .catch((err) => log({
+            evt: 'telemetry-post-failed',
+            event,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    };
+}
+function header(headers, name) {
+    const v = headers[name];
+    return typeof v === 'string' && v !== '' ? v : null;
+}
+/** The caller's user agent, cut short: enough to tell a browser from a script. */
+export function userAgentOf(headers) {
+    return header(headers, 'user-agent')?.slice(0, 160) ?? null;
+}
+/**
+ * Who a request or handshake says it is, from the edge's headers AFTER
+ * `sanitizeHeaders` — so a spoofed caller reports as public with a null userId,
+ * exactly what the handlers saw.
+ */
+export function callerContext(headers) {
+    return {
+        userId: header(headers, 'x-user-id'),
+        tier: header(headers, 'x-hadoku-tier') ?? 'public',
+        ua: userAgentOf(headers),
+    };
+}
+/**
+ * A seal below the edge refused a caller. With the edge in front this should
+ * never fire: one means a direct hit on the tunnel host, or an edge rule wider
+ * than this server's floor — both worth a look. `Surface` is an open string:
+ * this module knows no game's surface names, so the app's own adapter narrows
+ * it to a closed set.
+ */
+export function reportSealRefused(surface, headers, path) {
+    report('seal-refused', { surface, path, ...callerContext(headers) });
+}
+/**
+ * Middleware, mounted below the tier floor: the first request this server ever
+ * admits from a user id reports `caller-first-seen` with its tier and user
+ * agent — the "who is getting in" signal, once per account, not per visit.
+ * Callers the edge named nobody (a null userId) are not accounts and are skipped.
+ */
+export function firstSeen(opts) {
+    const seen = new Set(readSeen(opts.file, opts.log));
+    const middleware = (req, _res, next) => {
+        const userId = opts.userIdOf(req);
+        if (userId !== null && !seen.has(userId)) {
+            seen.add(userId);
+            writeSeen(opts.file, seen, opts.log);
+            report('caller-first-seen', {
+                userId,
+                tier: opts.tierOf(req),
+                ua: userAgentOf(req.headers),
+                path: req.path,
+            });
+        }
+        next();
+    };
+    return Object.assign(middleware, {
+        forget(userId) {
+            if (!seen.delete(userId))
+                return 0;
+            writeSeen(opts.file, seen, opts.log);
+            return 1;
+        },
+    });
+}
+function readSeen(file, log) {
+    if (!existsSync(file))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (Array.isArray(parsed) && parsed.every((x) => typeof x === 'string'))
+            return parsed;
+        log({ evt: 'first-seen-unreadable', file, reason: 'not a list of ids' });
+    }
+    catch (err) {
+        log({
+            evt: 'first-seen-unreadable',
+            file,
+            reason: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return [];
+}
+function writeSeen(file, seen, log) {
+    try {
+        writeFileSync(`${file}.tmp`, JSON.stringify([...seen]));
+        renameSync(`${file}.tmp`, file);
+    }
+    catch (err) {
+        log({
+            evt: 'first-seen-write-failed',
+            file,
+            reason: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@hadoku/service-kernel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "gitHead": "25eb5a7d584ce320a079bea1ff111790bb676520",
+  "type": "module",
+  "license": "MIT",
+  "description": "The server parts any game keeps: edge auth and the tier gate, base path and bundle check, health and the busy probe, lifecycle, the JSON logger, the state directory, telemetry and capacity, per-caller limits, the browser relays, the erase registry, and createGameServer, which boots a game from its config and plugins. Knows no game; the app binds its service id, prefix and env names. MIT; imports only node built-ins, express, socket.io and @wolffm/*.",
+  "exports": {
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./http": {
+      "types": "./dist/http/index.d.ts",
+      "import": "./dist/http/index.js"
+    },
+    "./health": {
+      "types": "./dist/health/index.d.ts",
+      "import": "./dist/health/index.js"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle/index.d.ts",
+      "import": "./dist/lifecycle/index.js"
+    },
+    "./log": {
+      "types": "./dist/log/index.d.ts",
+      "import": "./dist/log/index.js"
+    },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "import": "./dist/state/index.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "import": "./dist/telemetry/index.js"
+    },
+    "./capacity": {
+      "types": "./dist/capacity/index.d.ts",
+      "import": "./dist/capacity/index.js"
+    },
+    "./limits": {
+      "types": "./dist/limits/index.d.ts",
+      "import": "./dist/limits/index.js"
+    },
+    "./relays": {
+      "types": "./dist/relays/index.d.ts",
+      "import": "./dist/relays/index.js"
+    },
+    "./erase": {
+      "types": "./dist/erase/index.d.ts",
+      "import": "./dist/erase/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    }
+  },
+  "dependencies": {
+    "@wolffm/rooms-protocol": "npm:@hadoku/rooms-protocol@^0.45.60",
+    "@wolffm/rooms-server": "npm:@hadoku/rooms-server@^0.45.60",
+    "express": "^5.1.0",
+    "socket.io": "^4.8.3"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WolffM/hadoku-cardtable.git",
+    "directory": "packages/service-kernel"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.