ftown-bridge 0.19.19 → 0.19.21

package/dist/solo/contract.js

@@ -0,0 +1,248 @@
+/**
+ * ftown Solo — frozen contract v2 for the single-port LAN deployment mode.
+ * REVISION 2 — gauntlet round 1 findings applied (see SOLO_CONTRACT_REVISION).
+ *
+ * PRODUCT DEFINITION (do not renegotiate in module code):
+ * `ftown-bridge --solo` binds ONE HTTP port on the LAN and serves:
+ *   - /api/solo/*  → solo bootstrap/token endpoints (bridge-owned)
+ *   - /api/*       → the existing local API (unchanged)
+ *   - /healthz     → liveness of front + hub + panel
+ *   - /hub/*       → managed Centrifugo child, proxied, WS UPGRADES ONLY
+ *   - anything else → the panel: a managed Next.js STANDALONE child process
+ *
+ * The panel is NOT a static export: the ui app is output:'standalone' with an
+ * auth()-gated server page, so static export is impossible without re-
+ * architecting it. Solo instead fetches the published standalone bundle,
+ * spawns it on a private port like the hub, and the front reverse-proxies
+ * everything not bridge-owned to it. UI auth is dual-mode: hosted builds use
+ * NextAuth; solo builds authenticate with the access key against /api/solo/*.
+ *
+ * No external account service, no docker, no second public port. A tunnel
+ * provider may point at this SAME port; nothing may assume loopback-only
+ * access. This file is TYPES + CONSTANTS + TABLES ONLY — no logic. Every
+ * cross-module value must appear here; a name absent from this file does not
+ * exist.
+ */
+/** Contract revision — bump on any material change (re-gauntlet required). */
+export const SOLO_CONTRACT_REVISION = 4;
+// ---------- Ports ----------
+/** Default public LAN port (--port overrides). Children NEVER use fixed
+ * ports: hub and panel bind 127.0.0.1:0 (OS-assigned ephemeral), eliminating
+ * child port collisions entirely. */
+export const DEFAULT_SOLO_PORT = 8040;
+// ---------- Health probes (pinned) ----------
+//
+// hub:   GET http://127.0.0.1:<hubPort>/health    (native centrifugo endpoint)
+// panel: HEAD http://127.0.0.1:<panelPort>/        (any status <500 = up)
+// Poll interval 5s, probe timeout 1s; 'up' requires one success, 'down' after
+// one failure following a prior success or after grace period (10s) at boot.
+// ---------- Lifecycle (integrator, frozen) ----------
+//
+// L1. Boot: parse args → rotate-key short-circuit (S11) → create SoloConfig
+//     (children get port 0) → front.listen(port) → print URLs/banner → async
+//     ensure(hub) + ensure(panel).
+// L2. Shutdown (SIGINT/SIGTERM identical): front.stopListening() (stop accept,
+//     destroy open WS upgrades after 5s grace) → panel.kill() → hub.kill()
+//     (children get SIGTERM then SIGKILL after 3s) → flush config files.
+//     Orphaned children must be detectable+reaped on next boot (stale pidfile
+//     under dataDir/solo/ checked before spawn).
+// L3. EADDRINUSE on the front port: fail fast with a clear error naming the
+//     port. Never auto-retry, never pick another port silently.
+// L4. --rotate-key alone: regenerate key, persist hash (0600), print new
+//     banner, exit 0 WITHOUT starting any listener. With --solo: rotate, then
+//     continue normal boot. Bundles/dataDir untouched either way.
+// ---------- Identity & crypto constants ----------
+/** Access key entropy: 32 random bytes, hex-encoded (64 chars). */
+export const ACCESS_KEY_BYTES = 32;
+/** Hub JWT time-to-live, seconds. Refresh via POST /api/solo/token. */
+export const HUB_JWT_TTL_SECONDS = 12 * 60 * 60;
+/** Fixed solo subject. Solo mode is single-user by definition. */
+export const SOLO_USER_ID = 'solo';
+/**
+ * Audience claim REQUIRED in every hub JWT and configured as token_audience
+ * in the hub config. Minting without aud, or configuring a different value,
+ * makes every WS handshake fail with an audience mismatch.
+ */
+export const HUB_JWT_AUDIENCE = 'ftown:centrifugo';
+/** Centrifugo release to download (pinned; checksums embedded below). */
+export const CENTRIFUGO_VERSION = 'v5.4.9';
+/**
+ * Embedded sha256 digests for the pinned centrifugo release assets, sourced
+ * from the release's official checksums.txt at prep time (never fetched at
+ * install time). Keyed by platform triple derived from process.platform/arch:
+ * darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.
+ */
+export const CENTRIFUGO_SHA256 = {
+    'darwin-arm64': 'b0bef645acffe29ae9eb07fd98e93ac14d9c1cdd26b568b6cf9b8f20c6f653f4',
+    'darwin-amd64': 'ab221e476f8e9abd69f9943c2d3e7fefc232b90c5c23ccff60b89cae82f3fd50',
+    'linux-amd64': '75d2fac2dcea005bb3cb1b4636b3825d98c97709c94d10755c892dbe1c9956c2',
+    'linux-arm64': 'ba6df455ee0064399dd13652575fbbefa3d00bbe647d0555cb3669c1060821e5',
+};
+/**
+ * Panel (UI standalone) bundle source. Published as a GitHub release asset of
+ * THIS repository named `ftown-ui-standalone-<version>.tar.gz`, where version
+ * matches the ui package version. Integrity: the release workflow publishes a
+ * `<asset>.sha256` sidecar fetched over HTTPS from the same release — TLS to
+ * github.com is the trust root for first-party artifacts (third-party
+ * centrifugo gets EMBEDDED digests above instead).
+ */
+export const PANEL_BUNDLE_URL_TEMPLATE = 'https://github.com/fmktech/ftown/releases/download/ui-v<version>/ftown-ui-standalone-<version>.tar.gz';
+// ---------- Endpoint & routing table ----------
+//
+// | Method | Path                          | Auth            | Body/Result        |
+// |--------|-------------------------------|-----------------|--------------------|
+// | GET    | /api/solo/bootstrap           | Bearer key      | SoloBootstrap      |
+// | POST   | /api/solo/token               | Bearer key      | SoloTokenResponse  |
+// | GET    | /healthz                      | none            | SoloHealth         |
+// | GET    | /hub/connection/websocket     | upgrade ONLY    | proxied to hub     |
+// | *      | /hub/* (anything else)        | rejected        | 404                |
+// | *      | /api/* (all other)            | per local API   | existing bridge API|
+// |        |   — SOLO GUARD SUB: see S18   |                 |                    |
+// | *      | /* (everything else)          | none            | proxied to panel   |
+// | *      | /* (everything else)          | none            | proxied to panel   |
+//
+// ROUTING PRECEDENCE (exact match first, then longest-prefix): solo endpoints
+// → /hub allowlist → /api/* to the EXISTING local API handler (the front and
+// local-api-server compose; the bridge API is never shadowed by the panel) →
+// everything else to the panel child.
+//
+// Errors: {"error": string} with 401 (bad key), 429 (rate limited), 404, 502
+// (private child down) — matching local-api-server conventions.
+//
+// Pre-panel placeholder: while the panel child is not yet healthy, GET /
+// (and only /) is served by the FRONT itself as a minimal inline HTML page
+// ("Starting ftown Solo…", auto-refresh meta tag). This is the only HTML the
+// front ever generates.
+// ---------- Hub config keys (written by hub-manager, frozen values) ----------
+//
+// token_hmac_secret_key   = hubSecret
+// token_audience          = HUB_JWT_AUDIENCE
+// allowed_origins         = []            // allow all — bearer+JWT gated; the
+//                                         // panel is served from arbitrary
+//                                         // LAN IPs/tunnel domains by design
+// websocket_compression   = false         // proxy must not negotiate deflate
+// client.allowed          = false         // no anonymous connections
+// health                  = true
+// Admin API, server API: disabled. Hub listens on 127.0.0.1:hubPort with its
+// DEFAULT paths (/connection/websocket) — the proxy strips the /hub prefix,
+// so no centrifugo path options are needed.
+// ---------- Proxy rules (ws-proxy.ts, frozen) ----------
+//
+// P1. Only ^/hub/connection/websocket$ (after stripping the /hub prefix) is
+//     forwarded; plain HTTP under /hub/* never reaches the hub (404 at front).
+// P2. Target hardcoded to 127.0.0.1:<hubPort>. Never configurable.
+// P3. Strip inbound hop-by-hop headers: connection, keep-alive, proxy-authenticate,
+//     proxy-authorization, te, trailer, transfer-encoding, upgrade (re-set for
+//     upgrades), sec-websocket-* (let the 'ws' upstream handshake recompute
+//     Sec-WebSocket-Accept), permessage-deflate extension offer dropped.
+// P4. Rewrite Host to 127.0.0.1:<hubPort>; set X-Forwarded-Proto from rule S-scheme.
+// P5. Forward protocol-level ping/pong untouched (centrifugo ping 10s/pong 5s).
+// ---------- Security invariants (implementation + tests enforce) ----------
+//
+// S1.  Access key comparison constant-time; raw key never persisted and never
+//      written by the bridge to any file/log EXCEPT the one-time startup
+//      banner (deliberate UX delivery; documented exception).
+// S2.  /api/solo/* require Bearer key before any handler logic. /hub/* serves
+//      upgrades only (P1). The panel child is unauthenticated BY THE FRONT —
+//      the panel itself redirects to its /local key screen when bootstrap has
+//      not run (dual-mode auth); this is accepted and covered by the UI brief.
+// S3.  Rate limiting (solo-server-owned, NO XFF parsing in v1):
+//        - key failures: >=10 failures/60s per source IP → 429 + Retry-After: 60
+//        - global per-IP backstop on /api/solo/*: >240 req/min → 429
+//      Source IP = socket peer address via an INJECTED peerAddress(req) seam
+//      (default: socket.remoteAddress) so offline tests can simulate distinct
+//      peers. 256-bit key space makes online guessing non-viable; per-IP is
+//      acceptable behind tunnels (shared loopback source) because the UI
+//      caches the key — self-lockout requires repeated genuine auth failures.
+// S4.  Archive extraction rejects absolute entry paths, ".." segments, and
+//      symlink/hardlink entries (zip-slip); extraction target must resolve
+//      inside its dataDir subdirectory (realpath containment).
+// S5.  See proxy rules P1-P5 (hardcoded target, header policy, prefix allowlist).
+// S6.  Centrifugo downloads verified against CENTRIFUGO_SHA256 (embedded).
+//      Panel bundle verified against its published .sha256 sidecar over HTTPS.
+//      Digest mismatch aborts install with a clear error; nothing executes.
+// S7.  accessKeyHash + hubSecret persist 0600 under dataDir.
+// S8.  No cookies for solo auth anywhere (Bearer + fragment only) → CSRF-immune.
+//      The panel build must not mount SessionProvider (see UI module brief).
+// S9.  Plain HTTP on LAN is an accepted residual risk: a passive LAN observer
+//      captures the Bearer key from any authenticated call, and an active MITM
+//      additionally controls the unauthenticated panel HTML (key harvesting) —
+//      this MUST be stated prominently in the solo README. Tunnel providers
+//      terminate TLS. Front logs one console warning when binding a
+//      non-loopback interface.
+// S10. Hub JWTs: alg fixed HS256, claims sub=SOLO_USER_ID, aud=HUB_JWT_AUDIENCE,
+//      iat, exp. Nothing parses or accepts other algorithms/claims shapes.
+// S11. Key rotation is OUT OF HTTP SCOPE in v1: `ftown-bridge --solo --rotate-key`
+//      regenerates offline (new banner print). No rotation endpoint exists.
+// S12. Boot sequence (frozen): front LISTENS FIRST → prints URLs immediately →
+//      async ensure(hub binary→config→spawn→health) and ensure(panel bundle→
+//      spawn→health). /healthz reflects live state; pre-panel GET / gets the
+//      placeholder page. URLs never depend on children being ready.
+// S13. Inbound X-Forwarded-* are consumed only for scheme derivation (loopback
+//      peer required) and never relayed to children except that single field.
+// S14. Every /api/solo/* response sets Cache-Control: no-store (live 12h JWTs
+//      in bodies). The pre-panel placeholder page is BYTE-STATIC — zero
+//      request-derived bytes — and also no-store. Panel-proxy responses that
+//      arrive without cache headers get a no-store passthrough guard.
+// S15. No secret (raw key, accessKeyHash, hubSecret, JWT) ever appears in any
+//      process argv or environment variable: hubSecret reaches centrifugo
+//      EXCLUSIVELY via its 0600 config file path; children get only -c <path>.
+// S16. The front and all managers never log: Authorization headers, presented
+//      keys, JWTs, or /hub request URLs including query strings.
+// S17. Extraction hardening beyond S4: only regular-file and directory entries
+//      are extracted (explicit type allowlist); per-entry uncompressed cap,
+//      total uncompressed cap, and entry-count cap abort the install on
+//      exceed (decompression-bomb defense).
+// S18. SOLO VS HOSTED API GUARDS: in solo mode the local API's loopback-Host
+//      guard is substituted by the injected peerAddress seam (any source is
+//      fine — Bearer is mandatory) and its Origin check is DROPPED (Bearer-
+//      only, no cookies → CSRF-immune). Hosted mode keeps both guards
+//      byte-for-byte unchanged. Constant-time Bearer verification is
+//      mandatory in both modes.
+// S19. centrifugoUrl host derivation validates the request Host against the
+//      socket's local address:port (injectable allowlist seam for tunnels);
+//      absolute-form request lines are rejected 400. Host reflection into the
+//      bootstrap body must not be steerable by a third party.
+// S20. Routing and ws-prefix stripping consume ONE parsed representation of
+//      req.url; golden tests pin //hub, percent-encoded slashes, case
+//      variation, trailing segments, and unicode against the allowlist.
+// S21. PANEL_SOLO build-surface minimization: the solo panel build contains NO
+//      mutating server endpoints (route handlers/server actions) and performs
+//      no request-derived outbound fetches; the build asserts absence of
+//      middleware and /api/auth artifacts from the standalone output. Next.js
+//      stays current on security patches — post-tunnel this surface faces the
+//      internet directly.
+// ---------- Module ownership (disjoint files; integrator touches index.ts) --
+//
+// solo/solo-auth.ts(+test)   — key gen/hash/constant-time verify (S1);
+//                              hub JWT mint/verify (S10)
+// solo/hub-manager.ts(+test) — binary ensure (S6), config write (frozen keys),
+//                              spawn/health/stop lifecycle
+// solo/panel-manager.ts(+test)— bundle fetch/verify/extract (S4,S6), standalone
+//                              spawn/health/stop lifecycle
+// solo/ws-proxy.ts(+test)    — P1-P5 HTTP + upgrade proxying
+// solo/solo-server.ts(+test) — front server: routing table, auth gate (S2,S3),
+//                              scheme derivation, placeholder page (S12),
+//                              composition of the three managers + proxy
+// ui/src/lib/auth-mode.tsx   — dual-mode auth context (NextAuth | solo key):
+//                              signInState, signOut, tokenRefresher callbacks
+// ui/src/hooks/useCentrifugo.ts — EXTEND (owned file this build): optional
+//                              tokenRefresher param replacing hardcoded
+//                              /api/auth/token; onUnauthorized callback
+//                              replacing '/login' redirect
+// ui/src/app/local/page.tsx (+ ui/src/components/local/*) — #k fragment
+//                              capture → localStorage, bootstrap call, states:
+//                              no-key form / bad-key / starting(healthz poll) /
+//                              ready(renders Dashboard) 
+// ui/src/components/DashboardClient.tsx — EXTEND: signOut via auth-mode ctx;
+//                              providers.tsx — conditional SessionProvider
+// ui solo build flag        — PANEL_SOLO=1 at build time: root app/page.tsx
+//                              becomes a redirect to /local (marketing landing
+//                              and middleware are hosted-only); NextAuth pages
+//                              (/login etc.) excluded from the solo build; nav
+//                              links to /dashboard|/devices hidden in solo mode
+//                              (their hosted APIs are unreachable through the
+//                              proxy — accepted, documented in the UI brief)
+// integrator (index.ts)      — --solo/--port/--rotate-key flags, lifecycle L1-L4,
+//                              console URL banner (S1 exception)
+//# sourceMappingURL=contract.js.map

package/dist/solo/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/solo/contract.ts"],"names":[],"mappings":"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"}

package/dist/solo/hub-manager.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Solo hub manager — downloads, verifies, configures, spawns and stops the
+ * managed Centrifugo child (contract ownership: solo/hub-manager.ts(+test)).
+ *
+ * Dependency policy (deliberate): node builtins + node:child_process + the
+ * SYSTEM `tar` binary only — no new npm deps. tar(1) ships with macOS and
+ * Linux, the only platforms resolvePlatformTriple() supports, so archive
+ * listing/extraction needs no bundled extraction library.
+ *
+ * Invariants owned here: S6 (embedded CENTRIFUGO_SHA256 verification before
+ * anything is extracted), S7 (0600 config + pidfile), S15 (child argv is
+ * exactly [binPath, '-c', configPath]; no secrets in argv/env), S16 (logs
+ * never echo secrets — stderr tails are sanitized), L2 (stale pidfile reap
+ * under dataDir/solo/ on boot).
+ */
+import type { SpawnOptions } from 'node:child_process';
+export type PlatformTriple = 'darwin-arm64' | 'darwin-amd64' | 'linux-amd64' | 'linux-arm64';
+/** Minimal fetch seam so downloads and health probes run offline in tests. */
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+/** Structural view of the child we spawn (satisfied by node's ChildProcess). */
+export interface HubChildProcess {
+    pid: number | undefined;
+    stdout: NodeJS.ReadableStream | null;
+    stderr: NodeJS.ReadableStream | null;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+}
+export type SpawnLike = (command: string, args: readonly string[], options: SpawnOptions) => HubChildProcess;
+export declare class UnsupportedPlatformError extends Error {
+    constructor(message: string);
+}
+export declare class ChecksumError extends Error {
+    constructor(message: string);
+}
+export declare class ArchiveSafetyError extends Error {
+    constructor(message: string);
+}
+export declare class HubStartError extends Error {
+    constructor(message: string);
+}
+export declare function resolvePlatformTriple(platform?: string, arch?: string): PlatformTriple;
+export declare function assetUrl(version: string, triple: PlatformTriple): string;
+export interface EnsureHubBinaryOptions {
+    dataDir: string;
+    version?: string;
+    fetchImpl?: FetchLike;
+    /**
+     * Test seam overriding the embedded digest map. Production callers MUST
+     * leave it unset so verification stays pinned to contract CENTRIFUGO_SHA256.
+     */
+    digests?: Readonly<Record<string, string>>;
+}
+/**
+ * Validates tar entries against the extraction allowlist (S4/S17):
+ * names must be relative without '..' segments; entry types must be regular
+ * file ('-') or directory ('d') — symlinks, hardlinks, devices are refused.
+ */
+export declare function assertSafeTarEntries(names: readonly string[], verboseLines: readonly string[]): void;
+export declare function ensureHubBinary(opts: EnsureHubBinaryOptions): Promise<string>;
+export declare function writeHubConfig(configPath: string, opts: {
+    port: number;
+    secret: string;
+}): Promise<void>;
+export interface StartHubOptions {
+    configPath: string;
+    binPath: string;
+    dataDir: string;
+    fetchImpl?: FetchLike;
+    spawnImpl?: SpawnLike;
+    /** Overrides http://127.0.0.1:<port> as the base for /health probes (tests). */
+    healthBaseUrl?: string;
+    healthIntervalMs?: number;
+    healthTryTimeoutMs?: number;
+    healthDeadlineMs?: number;
+}
+export interface RunningHub {
+    child: HubChildProcess;
+    pid: number | undefined;
+    port: number;
+}
+export declare function hubPidFilePath(dataDir: string): string;
+export declare function startHub(opts: StartHubOptions): Promise<RunningHub>;
+/** SIGTERM → 3s grace → SIGKILL; always unlinks the pidfile. Returns whether a live process was stopped. */
+export declare function stopHub(dataDir: string): Promise<boolean>;