@preventive/triage 1.0.0-alpha.0

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "@preventive/triage",
+  "version": "1.0.0-alpha.0",
+  "description": "Client & relay server for triaging of automated reports",
+  "license": "MIT",
+  "author": {
+    "name": "Nikita Skovoroda",
+    "email": "chalkerx@gmail.com",
+    "url": "https://github.com/ChALkeR"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PreventiveMeasures/triage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PreventiveMeasures/triage/issues"
+  },
+  "homepage": "https://github.com/PreventiveMeasures/triage",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "imports": {
+    "#client/index.js": "./client/index.js",
+    "#client/sync.js": "./client/sync.js",
+    "#client/sync-host.js": "./client/sync-host.js"
+  },
+  "bin": {
+    "triage-server": "server/index.ts"
+  },
+  "files": [
+    "server/auth.ts",
+    "server/config.ts",
+    "server/db-neon.ts",
+    "server/db-revision-sql.ts",
+    "server/db-stmt.ts",
+    "server/db.ts",
+    "server/http.ts",
+    "server/hub.ts",
+    "server/index.ts",
+    "server/lifecycle.ts",
+    "server/neon-driver.ts",
+    "server/objstore/blob-fs.ts",
+    "server/objstore/blob-vercel.ts",
+    "server/objstore/blob.ts",
+    "server/objstore/fs.ts",
+    "server/objstore/handlers.ts",
+    "server/objstore/init.ts",
+    "server/objstore/reaper.ts",
+    "server/objstore/rest.ts",
+    "server/objstore/sign.ts",
+    "server/objstore/store-neon.ts",
+    "server/objstore/store.ts",
+    "server/objstore/tokens.ts",
+    "server/origin.ts",
+    "server/peer.ts",
+    "server/sign.ts",
+    "server/static.ts",
+    "server/sync-handlers.ts",
+    "server/util.ts",
+    "server/validation.ts",
+    "server/ws-server.ts",
+    "server/config.example.json",
+    "common/save-error-reason.ts",
+    "common/utf8.d.ts",
+    "common/utf8.js",
+    "out/brotli-fallback.js",
+    "out/client-sync.js",
+    "out/graph.js",
+    "out/icon-maskable.svg",
+    "out/icon.svg",
+    "out/index.html",
+    "out/manifest.webmanifest",
+    "out/prism.js",
+    "out/terminal.js",
+    "out/view.css",
+    "out/view.html",
+    "out/view.js"
+  ],
+  "scripts": {
+    "lint": "node --run lint:js && node --run lint:css && node --run lint:ts",
+    "lint:js": "oxlint -c .oxlintrc.json --ignore-pattern=ui/logs.js ./tests/ ./common/ ./server/ ./client/ ./ui/",
+    "lint:css": "stylelint 'ui/**/*.css'",
+    "lint:ts": "tsc --noEmit",
+    "prepack": "node --run build",
+    "build": "node build.js build",
+    "serve": "node build.js serve",
+    "server": "node server/index.ts",
+    "test": "node --js-base-64 --experimental-test-module-mocks --test ./tests/*.test.js"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.4.5",
+    "@exodus/stasis": "^1.0.0-alpha.1",
+    "@noble/ciphers": "^2.2.0",
+    "@preventive/terminal": "^1.2.2",
+    "@rray/frontend": "^1.0.0",
+    "@stylistic/stylelint-plugin": "^5.1.0",
+    "@types/node": "^25.6.2",
+    "@types/ws": "^8.18.1",
+    "brotli": "^1.3.3",
+    "esbuild": "^0.27.4",
+    "lit": "^3.3.2",
+    "minify-html-literals": "^1.3.5",
+    "oxlint": "^1.63.0",
+    "prismjs": "^1.30.0",
+    "stylelint": "^17.11.0",
+    "stylelint-config-recommended": "^18.0.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "ws": "^8.20.1"
+  },
+  "peerDependencies": {
+    "@neondatabase/serverless": "^1.0.2",
+    "@vercel/blob": "^2.3.3"
+  },
+  "peerDependenciesMeta": {
+    "@neondatabase/serverless": {
+      "optional": true
+    },
+    "@vercel/blob": {
+      "optional": true
+    }
+  },
+  "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800"
+}

package/server/auth.ts

@@ -0,0 +1,99 @@
+// Operator-side password gate. Optionally gates the FIRST action
+// against a never-before-seen workspace tag behind a shared password
+// (config.json). Once a connection completes the `authenticate
+// { password }` handshake its Peer is marked authorized and every
+// subsequent first-action bypasses the gate; once a workspace exists
+// on the server the gate is off for it regardless of connection.
+//
+// Comparison is HMAC-SHA-256 under a per-process random key derived
+// here: the configured password is HMAC'd once at construction (the
+// raw bytes aren't retained), and each `authenticate` HMACs the
+// submitted password and compares with `timingSafeEqual`. Fixed
+// 32-byte digests mean no length-equal precondition (no length leak),
+// and any residual timing variance reveals only HMAC bytes useless
+// without the per-process key. `null` configured HMAC = no gate.
+
+import type { WebSocket } from 'ws'
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import type { PeerRegistry } from './peer.ts'
+
+// Server → Client `unauthorized` frame context. The explicit `kind`
+// discriminator is the wire contract: callers MUST switch on it rather
+// than infer from field presence. The client's wire dispatcher and the
+// objstore client's put-begin recv predicate both pin on `kind`.
+export type UnauthorizedContext =
+  | { kind: 'gated'; workspaceTag: string; base: string | null }       // workspace-save gated
+  | { kind: 'gated'; workspaceTag: string; resourceTag: string }       // objstore-put-begin gated
+  | { kind: 'auth-failed' }                                             // authenticate-failed
+
+export type AuthenticateMsg = { password?: unknown }
+
+export type Auth = {
+  // True iff the gate is configured AND this socket hasn't authenticated.
+  requiresAuth(socket: WebSocket): boolean
+  handleAuthenticate(socket: WebSocket, msg: AuthenticateMsg): void
+  sendUnauthorized(socket: WebSocket, ctx: UnauthorizedContext): void
+}
+
+// Pre-shape gate: a submitted password must be a non-empty string,
+// length-capped so a peer can't make us HMAC megabytes per frame
+// (this handler is fast-inlined outside the per-socket inflight cap).
+// 4096 is far above any real password, well below the 4 MiB frame cap.
+const MAX_AUTH_PASSWORD_LEN = 4096
+
+export function createAuth(deps: {
+  peers: PeerRegistry
+  password: string | null
+  send: (socket: WebSocket, msg: object) => void
+  debug: boolean
+}): Auth {
+  const { peers, password, send, debug } = deps
+  const PASSWORD_HMAC_KEY = new Uint8Array(randomBytes(32))
+  // `null` is the "no gate" sentinel every check reads (absent / empty).
+  const CONFIGURED_PASSWORD_HMAC: Uint8Array<ArrayBuffer> | null =
+    password == null || password === ''
+      ? null
+      : new Uint8Array(createHmac('sha256', PASSWORD_HMAC_KEY).update(password, 'utf8').digest())
+
+  function isAuthorized(socket: WebSocket): boolean {
+    return peers.get(socket)?.authorized === true
+  }
+  function markAuthorized(socket: WebSocket): void {
+    const peer = peers.get(socket)
+    if (peer) peer.authorized = true
+  }
+  function requiresAuth(socket: WebSocket): boolean {
+    if (CONFIGURED_PASSWORD_HMAC == null) return false
+    return !isAuthorized(socket)
+  }
+  function passwordMatches(submitted: string): boolean {
+    if (CONFIGURED_PASSWORD_HMAC == null) return false
+    const submittedHmac = new Uint8Array(createHmac('sha256', PASSWORD_HMAC_KEY).update(submitted, 'utf8').digest())
+    return timingSafeEqual(submittedHmac, CONFIGURED_PASSWORD_HMAC)
+  }
+  function sendUnauthorized(socket: WebSocket, ctx: UnauthorizedContext): void {
+    send(socket, { type: 'unauthorized', ...ctx })
+  }
+  function handleAuthenticate(socket: WebSocket, msg: AuthenticateMsg): void {
+    if (typeof msg.password !== 'string' || msg.password.length === 0 || msg.password.length > MAX_AUTH_PASSWORD_LEN) return
+    // No-config short-circuit: when not gating, treat any authenticate
+    // as success so a client can cache + replay its password on
+    // reconnect even against an un-gated server (wire shape stays
+    // consistent).
+    if (CONFIGURED_PASSWORD_HMAC == null) {
+      markAuthorized(socket)
+      send(socket, { type: 'authenticated' })
+      return
+    }
+    if (!passwordMatches(msg.password)) {
+      if (debug) console.warn('authenticate: wrong password')
+      sendUnauthorized(socket, { kind: 'auth-failed' })
+      return
+    }
+    markAuthorized(socket)
+    if (debug) console.log('authenticate: success')
+    send(socket, { type: 'authenticated' })
+  }
+
+  return { requiresAuth, handleAuthenticate, sendUnauthorized }
+}

package/server/config.example.json

@@ -0,0 +1,3 @@
+{
+  "password": null
+}

package/server/config.ts

@@ -0,0 +1,196 @@
+// Boot configuration: parse + validate every external input (env
+// vars, the optional config.json) into one immutable `Config`, failing
+// loud on malformed values so a typo surfaces at startup rather than
+// deep in `node:net` / at the first token verification. Pure parsing —
+// no backends opened, no crypto keys derived, no side effects beyond
+// `--help` / fail-fast `process.exit`. index.ts destructures the
+// result and does the wiring (backend selection, password HMAC, …).
+
+import { Buffer } from 'node:buffer'
+import { readFileSync } from 'node:fs'
+import { argv, env } from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+export type Config = {
+  port: number
+  host: string
+  dbPath: string
+  objstoreDir: string
+  reapIntervalMs: number
+  maxInflightPerSocket: number
+  debug: boolean
+  neonUrl: string | null
+  blobToken: string | null
+  tokenSecret: Uint8Array<ArrayBuffer> | null
+  password: string | null
+  trustProxyEnv: string | undefined
+}
+
+// Parse + range-validate an integer env var, exiting with a clear
+// up-front message on a malformed value — a NaN from `Number("abc")`
+// otherwise surfaces as a confusing crash deep inside `node:net`
+// (`WebSocketServer({ port: NaN })`) or a 0-ms `setInterval` loop. An
+// absent var falls back to `def` (assumed in-range). One shape for
+// every integer env var so they validate + fail identically; `hint`
+// appends operator guidance (range meaning, default) to the error.
+function intEnv(name: string, def: number, min: number, max: number, hint = ''): number {
+  const raw = env[name]
+  const n = raw == null ? def : Number(raw)
+  if (!Number.isSafeInteger(n) || n < min || n > max) {
+    console.error(`Invalid ${name}: ${raw} — must be an integer in [${min}, ${max}].${hint ? ` ${hint}` : ''}`)
+    process.exit(1)
+  }
+  return n
+}
+
+const HELP = `Usage: node server/index.ts
+Environment:
+  PORT                       listen port (default 8765)
+  HOST                       bind host (default 127.0.0.1)
+  DB_PATH                    sqlite file (default: server/data/data.db);
+                             ignored when DATABASE_URL is set
+  DATABASE_URL               Neon Postgres connection string; if set,
+                             selects the Neon backend instead of
+                             SQLite. Requires the optional peer dep
+                             @neondatabase/serverless. The Neon
+                             pairing additionally requires
+                             BLOB_READ_WRITE_TOKEN (Vercel Blob
+                             Private Storage) for the byte plane —
+                             local-FS bytes cannot back a multi-
+                             replica DB plane.
+  BLOB_READ_WRITE_TOKEN      Vercel Blob R/W token (private store).
+                             Required when DATABASE_URL is set;
+                             ignored otherwise. Requires the optional
+                             peer dep @vercel/blob.
+  OBJSTORE_TOKEN_SECRET      Base64 (32 bytes) HMAC secret for REST
+                             bearer tokens. REQUIRED when DATABASE_URL
+                             is set (multi-replica deployments: a
+                             token minted on one replica's WS plane
+                             must validate on another replica's REST
+                             plane). Optional under SQLite (a fresh
+                             per-process secret is minted at boot).
+                             Generate one with:
+                               node -e 'console.log(crypto.randomBytes(32).toString("base64"))'
+  OBJSTORE_DIR               object store root (default: ./objstore
+                             next to DB_PATH). Used by the local-FS
+                             byte plane only; ignored when
+                             DATABASE_URL + BLOB_READ_WRITE_TOKEN
+                             are set (bytes live in Vercel Blob).
+  OBJSTORE_REAP_INTERVAL_MS  orphan reaper period (default 600000)
+  TRUST_PROXY                set '1' / 'true' to honour X-Forwarded-
+                             Host / X-Forwarded-Proto when computing
+                             the same-origin gate's expected origin.
+                             Default: ON when HOST is a loopback
+                             (127.0.0.1, ::1, localhost) — the typical
+                             "behind nginx on same host" deployment.
+                             OFF for public binds (HOST=0.0.0.0 etc.)
+                             where a bare X-Forwarded-* would
+                             otherwise let an attacker page bypass
+                             the gate.
+  MAX_INFLIGHT_PER_SOCKET    per-socket in-flight async-handler
+                             cap; saves dropped past this fire a
+                             typed 'busy' workspace-save-error
+                             NACK. Default 64. Lower for tests
+                             that need to deterministically
+                             exercise the cap.
+  CONFIG_PATH                operator config JSON path (default:
+                             server/config.json). Currently the
+                             only field is { "password": "..." }
+                             which gates first-action creation of
+                             a new workspace on the
+                             authenticate { password } handshake.
+                             Missing file / null password →
+                             no gating (default).
+  DEBUG=1                    log every message`
+
+type ServerConfigFile = { password?: string | null }
+
+// Optional operator-side config file. Absence is silently fine
+// (preserves the no-auth default). Parse errors fail loud so a typo
+// doesn't silently fall back to "no auth required".
+function readServerConfigFile(path: string): ServerConfigFile {
+  let raw: string
+  try { raw = readFileSync(path, 'utf8') } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return {}
+    console.error(`Failed to read ${path}:`, (err as Error)?.message ?? err); process.exit(1)
+  }
+  try { return JSON.parse(raw) as ServerConfigFile }
+  catch (err) {
+    console.error(`Failed to parse ${path} as JSON:`, (err as Error)?.message ?? err); process.exit(1)
+  }
+}
+
+// Decode + length-check the REST-token HMAC secret upfront so a
+// misconfigured secret fails at boot, not at the first verification.
+// `Buffer.from(s, 'base64')` does NOT throw on invalid input — it
+// silently strips non-alphabet chars, so a typo like `+→-` decodes to
+// a DIFFERENT secret. Detect by re-encoding and comparing (modulo `=`).
+function decodeTokenSecret(raw: string): Uint8Array<ArrayBuffer> {
+  // Trim whitespace — a copy-pasted env value often ends in `\n` and
+  // Buffer.from(..., 'base64') would silently strip it, then the
+  // typo-detector below would fail with a misleading message.
+  const trimmed = raw.trim()
+  if (trimmed.length === 0) {
+    console.error('OBJSTORE_TOKEN_SECRET is empty after trimming whitespace')
+    process.exit(1)
+  }
+  const decoded = Buffer.from(trimmed, 'base64')
+  const reencoded = decoded.toString('base64')
+  const norm = (s: string): string => s.replace(/=+$/u, '')
+  if (norm(reencoded) !== norm(trimmed)) {
+    console.error('OBJSTORE_TOKEN_SECRET contains non-base64 characters (likely a typo, e.g. base64url chars in a base64 secret).')
+    console.error('Regenerate with: node -e \'console.log(require("crypto").randomBytes(32).toString("base64"))\'')
+    process.exit(1)
+  }
+  if (decoded.byteLength !== 32) {
+    console.error(`OBJSTORE_TOKEN_SECRET must decode to 32 bytes (got ${decoded.byteLength})`)
+    process.exit(1)
+  }
+  // Copy into a fresh ArrayBuffer so the type matches
+  // `Uint8Array<ArrayBuffer>` (Buffer may be SharedArrayBuffer-backed).
+  return new Uint8Array(decoded)
+}
+
+export function loadConfig(): Config {
+  // 0 = OS-assigned ephemeral port (the test harness boots with PORT=0).
+  const port = intEnv('PORT', 8765, 0, 65535)
+  const host = env['HOST'] ?? '127.0.0.1'
+  // `fileURLToPath` decodes percent-escapes / non-ASCII path segments
+  // correctly (the older `new URL(...).pathname` left `%20` raw).
+  const dbPath = env['DB_PATH'] ?? fileURLToPath(new URL('./data/data.db', import.meta.url))
+  // `path.join` so a Windows DB_PATH doesn't get a mixed-separator child.
+  const objstoreDir = env['OBJSTORE_DIR'] ?? join(dirname(dbPath), 'objstore')
+  // No practical upper bound beyond the safe-integer range.
+  const reapIntervalMs = intEnv('OBJSTORE_REAP_INTERVAL_MS', 10 * 60 * 1000, 1, Number.MAX_SAFE_INTEGER)
+  const debug = env['DEBUG'] === '1'
+
+  const configPath = env['CONFIG_PATH'] ?? fileURLToPath(new URL('./config.json', import.meta.url))
+  const serverConfig = readServerConfigFile(configPath)
+  const rawPassword = serverConfig.password
+  if (rawPassword != null && typeof rawPassword !== 'string') {
+    console.error(`Invalid ${configPath}: "password" must be a string or null`); process.exit(1)
+  }
+  const password = rawPassword ?? null
+  // Upper bound 65_536 — bounds memory under hostile load; a deployer
+  // passing MAX_SAFE_INTEGER would silently defeat the cap. Validated
+  // here (after the config.json / password parse) to preserve the
+  // pre-split error-precedence order.
+  const maxInflightPerSocket = intEnv('MAX_INFLIGHT_PER_SOCKET', 64, 1, 65_536)
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(HELP)
+    process.exit(0)
+  }
+
+  const neonUrl = env['DATABASE_URL'] ?? null
+  const blobToken = env['BLOB_READ_WRITE_TOKEN'] ?? null
+  const tokenSecretB64 = env['OBJSTORE_TOKEN_SECRET'] ?? null
+  const tokenSecret = tokenSecretB64 ? decodeTokenSecret(tokenSecretB64) : null
+
+  return {
+    port, host, dbPath, objstoreDir, reapIntervalMs, maxInflightPerSocket,
+    debug, neonUrl, blobToken, tokenSecret, password,
+    trustProxyEnv: env['TRUST_PROXY'],
+  }
+}