@fiodos/bridge 0.1.0

package/Dockerfile

@@ -0,0 +1,20 @@
+# Fiodos bridge as a container: for a dashboard that lives on a server nobody
+# logs into. Pair once (interactive), then run forever with the same volume.
+#
+#   docker build -t fiodos/bridge packages/bridge
+#   docker run --rm -it --network host -v fiodos-bridge:/data fiodos/bridge \
+#       pair ABCD-EFGH --target http://localhost:3947 --no-run
+#   docker run -d --restart unless-stopped --network host -v fiodos-bridge:/data fiodos/bridge run
+#
+# `--network host` is what lets it reach `localhost:<port>` of the machine;
+# without it, point --target at the service's name on the compose network.
+FROM node:22-alpine
+ENV FIODOS_BRIDGE_HOME=/data
+WORKDIR /app
+COPY package.json README.md LICENSE ./
+COPY dist ./dist
+RUN mkdir -p /data && chown node:node /data
+USER node
+VOLUME ["/data"]
+ENTRYPOINT ["node", "dist/cli.js"]
+CMD ["run"]

package/LICENSE

@@ -0,0 +1,77 @@
+Fiodos SDK License Agreement
+
+Copyright (c) 2026 Fiodos / Rodrigo Martínez. All rights reserved.
+
+This is a proprietary, commercial software license. It is NOT an open-source
+license. Please read it carefully before installing or using the Software.
+
+1. Definitions.
+   "Software" means the Fiodos SDK packages (including, without limitation, the
+   @fiodos/* npm packages and the fiodos_flutter package) together with any
+   accompanying files, documentation, and updates provided by the Licensor.
+   "Service" means the hosted Fiodos backend, APIs, and related services
+   operated by the Licensor.
+   "Licensor" means Fiodos / Rodrigo Martínez (and, once incorporated, the
+   company that succeeds to these rights).
+   "You" means the individual or legal entity that installs or uses the
+   Software.
+
+2. Grant of License.
+   Subject to Your continued compliance with this Agreement, the Licensor grants
+   You a limited, non-exclusive, non-transferable, non-sublicensable, and
+   revocable license to install and use the Software solely for the purpose of
+   integrating with and accessing the Fiodos Service from within Your own
+   applications.
+
+3. Restrictions.
+   Except as expressly permitted in Section 2, You may NOT, in whole or in part:
+   (a) copy the Software, except for the copying strictly necessary to install
+       and run it for its intended purpose;
+   (b) modify, adapt, translate, or create derivative works of the Software;
+   (c) redistribute, publish, sublicense, sell, rent, lease, lend, or otherwise
+       make the Software available to any third party as a standalone item;
+   (d) reverse engineer, decompile, or disassemble the Software, or attempt to
+       derive its source code, except and only to the extent that this
+       restriction is expressly prohibited by applicable law;
+   (e) remove, obscure, or alter any copyright, trademark, or other proprietary
+       notices contained in the Software; or
+   (f) use the Software, or any portion of it, to develop, train, or assist in
+       developing a product or service that competes with Fiodos.
+
+4. Reservation of Rights.
+   The Software is licensed, not sold. All right, title, and interest in and to
+   the Software, including all related intellectual property rights, are and
+   shall remain the exclusive property of the Licensor. All rights not expressly
+   granted to You under this Agreement are reserved by the Licensor.
+
+5. Termination.
+   This license terminates automatically and immediately if You breach any term
+   of this Agreement. Upon termination, You must cease all use of the Software
+   and delete all copies in Your possession or control. Sections 3, 4, 6, and 7
+   survive termination.
+
+6. Disclaimer of Warranty.
+   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.
+
+7. Limitation of Liability.
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
+   LICENSOR 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.
+
+8. Contact.
+   For licensing inquiries, contact Rodrigo Martínez (Fiodos).
+
+--------------------------------------------------------------------------------
+
+Nota (ES) — Licencia propietaria:
+Se permite INSTALAR y USAR el SDK únicamente para integrar y acceder al servicio
+Fiodos desde tus propias aplicaciones. Quedan PROHIBIDOS: copiar el código (salvo
+la copia imprescindible para instalarlo y ejecutarlo), modificarlo, redistribuirlo,
+sublicenciarlo, venderlo, hacer ingeniería inversa o crear obras derivadas o un
+producto que compita con Fiodos. El software se licencia, no se vende; todos los
+derechos no concedidos expresamente quedan reservados al Licenciante. Este texto
+corresponde a la fase de pruebas y será revisado por un abogado al constituir la
+sociedad.

package/README.md

@@ -0,0 +1,64 @@
+# @fiodos/bridge
+
+Lets your Fiodos company agent reach a dashboard or API that lives **on your own
+network** (`localhost:3947`, an intranet host) without opening a port, without a
+third-party tunnel and without giving Fiodos your local key.
+
+How it works: the bridge is a small process on a machine that can see that
+dashboard. It opens **one outbound** connection to Fiodos and holds it. When the
+agent needs to call the dashboard, Fiodos sends the request down that
+connection, the bridge judges it against the allow-list you set, executes it
+locally with your local credentials, and returns the answer.
+
+```
+npx -y --loglevel=error @fiodos/bridge pair ABCD-EFGH --target http://localhost:3947
+```
+
+That is the whole install. The code comes from the Fiodos dashboard (internal
+orb → connections → "dashboard on my network") and is valid for 15 minutes,
+once.
+
+## What stays here, what travels
+
+| Kept on this machine (`~/.fiodos/bridge/config.json`, mode 0600) | Never leaves it |
+| --- | --- |
+| The pairing token (talks to Fiodos) | Your dashboard's key (`--header`) |
+| The target origin and allowed path prefixes | Any code, any copy of a response |
+| Header **names** you added (values are only in the file) | — |
+
+Fiodos keeps the API document of the dashboard (read once through the bridge,
+or uploaded as a file) so the agent knows what it can call — never the code.
+
+## Commands
+
+```
+pair <code> --target <url> [--header "Name: value"]... [--header-file path]
+                           [--allow </prefix>]... [--name <label>] [--api-url <url>] [--no-run]
+run                        serve every paired bridge (what the service runs)
+status                     what is paired, where it points; never prints a key
+unpair [--bridge <id>]
+service install|uninstall|show    launchd (macOS) / systemd --user (Linux); Windows prints instructions
+```
+
+- `--header "Authorization: Bearer …"` — how the bridge authenticates to **your**
+  dashboard. Use `--header-file` if the value must not appear in shell history.
+- `--allow /v1/owner` (repeatable) — restrict the bridge to those path prefixes.
+  Default is everything on the target origin, nothing off it.
+- The token is sent to Fiodos as the first WebSocket frame, never in the URL.
+
+## Run it always
+
+```
+fiodos-bridge service install        # starts with the machine, restarts if it dies
+```
+
+Or as a container (see `Dockerfile`): pair once with the volume, then `run`.
+
+## Requirements
+
+Node.js 22.5 or newer (uses the built-in WebSocket and fetch; no dependencies).
+
+## Revoking
+
+From the Fiodos dashboard, "revoke bridge" ends the pairing: the running bridge
+receives the notice, deletes its token and exits. A new code re-pairs.

package/dist/allowlist.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The allow-list: what the backend may ask this bridge to touch.
+ *
+ * A bridge compromised from our side must not be a door into the customer's
+ * network — only to the API they chose to expose. So every request is judged
+ * here, on the customer's machine, before anything is sent: one origin (the
+ * paired target), the path prefixes they allowed, the HTTP verbs an API uses.
+ */
+import type { BridgeTarget } from './config.js';
+export declare const ALLOWED_METHODS: Set<string>;
+export interface IncomingRequest {
+    method: string;
+    path: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: string | null;
+}
+export type Verdict = {
+    ok: true;
+    url: string;
+    method: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function normalizeOrigin(raw: string): string;
+export declare function normalizePrefix(raw: string): string;
+export declare function judge(target: BridgeTarget, request: IncomingRequest): Verdict;
+/** Headers that travel with the request: what the backend asked for (content
+ *  negotiation only), then the customer's own — theirs win. Hop-by-hop and
+ *  identity headers from the wire are dropped. */
+export declare function outboundHeaders(target: BridgeTarget, incoming: Record<string, string> | undefined): Record<string, string>;

package/dist/allowlist.js

@@ -0,0 +1,73 @@
+export const ALLOWED_METHODS = new Set(['GET', 'POST', 'PATCH', 'PUT', 'DELETE']);
+export function normalizeOrigin(raw) {
+    let text = String(raw || '').trim();
+    if (!text)
+        throw new Error('target is required (e.g. http://localhost:3947)');
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) {
+        if (!/^https?:\/\//i.test(text))
+            throw new Error('target must be http or https');
+    }
+    else {
+        text = `http://${text}`;
+    }
+    const url = new URL(text);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new Error('target must be http or https');
+    return `${url.protocol}//${url.host}`;
+}
+export function normalizePrefix(raw) {
+    let p = String(raw || '').trim();
+    if (!p)
+        return '/';
+    if (!p.startsWith('/'))
+        p = `/${p}`;
+    return p;
+}
+export function judge(target, request) {
+    const method = String(request.method || '').toUpperCase();
+    if (!ALLOWED_METHODS.has(method))
+        return { ok: false, reason: `method ${method || '(none)'} not allowed` };
+    const path = String(request.path || '');
+    if (!path.startsWith('/'))
+        return { ok: false, reason: 'path must be absolute' };
+    // A path that climbs (`/a/../admin`) is judged by where it lands, not by
+    // how it was written.
+    let resolved;
+    try {
+        resolved = new URL(path, target.origin);
+    }
+    catch {
+        return { ok: false, reason: 'path is not valid' };
+    }
+    if (`${resolved.protocol}//${resolved.host}` !== target.origin) {
+        return { ok: false, reason: 'request left the paired target' };
+    }
+    const allowed = target.allowPaths.length ? target.allowPaths : ['/'];
+    const landed = resolved.pathname;
+    const inside = allowed.some((prefix) => {
+        const p = normalizePrefix(prefix);
+        if (p === '/')
+            return true;
+        return landed === p || landed.startsWith(p.endsWith('/') ? p : `${p}/`);
+    });
+    if (!inside)
+        return { ok: false, reason: `path ${landed} is outside the allowed prefixes (${allowed.join(', ')})` };
+    const query = request.query && typeof request.query === 'object' ? request.query : {};
+    for (const [k, v] of Object.entries(query))
+        resolved.searchParams.set(k, String(v));
+    return { ok: true, url: resolved.toString(), method };
+}
+/** Headers that travel with the request: what the backend asked for (content
+ *  negotiation only), then the customer's own — theirs win. Hop-by-hop and
+ *  identity headers from the wire are dropped. */
+export function outboundHeaders(target, incoming) {
+    const out = {};
+    for (const [k, v] of Object.entries(incoming || {})) {
+        const key = k.toLowerCase();
+        if (key === 'accept' || key === 'content-type')
+            out[key] = String(v);
+    }
+    for (const [k, v] of Object.entries(target.headers || {}))
+        out[k] = v;
+    return out;
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+interface Flags {
+    positional: string[];
+    values: Record<string, string[]>;
+}
+export declare function parseArgs(argv: string[]): Flags;
+export {};

package/dist/cli.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * fiodos-bridge — the command the dashboard tells you to paste.
+ *
+ *   npx -y --loglevel=error @fiodos/bridge pair ABCD-EFGH --target http://localhost:3947
+ *   fiodos-bridge run
+ *   fiodos-bridge status
+ *   fiodos-bridge service install | uninstall | show
+ *   fiodos-bridge unpair [--bridge <id>]
+ */
+import { readFileSync } from 'node:fs';
+import { parseHeaderFlag, pair } from './pair.js';
+import { readConfig, redacted, removeBridge, upsertBridge, writeConfig, configPath } from './config.js';
+import { runBridge } from './runner.js';
+import { activityLogPath, dim, say } from './log.js';
+import * as service from './service.js';
+export function parseArgs(argv) {
+    const positional = [];
+    const values = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            const key = eq > 0 ? arg.slice(2, eq) : arg.slice(2);
+            let value = eq > 0 ? arg.slice(eq + 1) : '';
+            if (eq < 0 && i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+                value = argv[i + 1];
+                i += 1;
+            }
+            (values[key] ||= []).push(value);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, values };
+}
+function one(flags, key) {
+    const list = flags.values[key];
+    return list && list.length ? list[list.length - 1] : undefined;
+}
+function usage() {
+    process.stderr.write(`fiodos-bridge — reach a dashboard on your own network from your Fiodos company agent
+
+  pair <code> --target <http://host:port> [--header "Name: value"]... [--allow </prefix>]... [--name <label>] [--api-url <url>]
+      Spend the one-time code from the dashboard, keep the pairing here, and start serving.
+  run           Serve every paired bridge (what the service runs).
+  status        What is paired, where it points, last activity. Never prints a key.
+  unpair [--bridge <id>]
+  service install | uninstall | show
+
+  Config: ${configPath()}   Log: ${activityLogPath()}
+`);
+}
+async function runAll(bridges) {
+    if (!bridges.length) {
+        say('nothing is paired yet. Run the pair command your dashboard shows.', 'warn');
+        process.exitCode = 1;
+        return;
+    }
+    const runs = bridges.map((bridge) => runBridge(bridge, {
+        onRevoked: (b) => writeConfig(removeBridge(readConfig(), b.bridgeId)),
+    }));
+    await Promise.all(runs);
+    say('no bridge left to serve — exiting.', 'info');
+}
+async function main(argv) {
+    const flags = parseArgs(argv);
+    const [command, ...rest] = flags.positional;
+    switch (command) {
+        case 'pair': {
+            const code = rest[0] || one(flags, 'code');
+            const target = one(flags, 'target');
+            if (!code || !target) {
+                say('pair needs the code and --target, e.g.  pair ABCD-EFGH --target http://localhost:3947', 'error');
+                process.exitCode = 2;
+                return;
+            }
+            const headers = {};
+            for (const raw of flags.values.header || []) {
+                const [name, value] = parseHeaderFlag(raw);
+                headers[name] = value;
+            }
+            const headerFile = one(flags, 'header-file');
+            if (headerFile) {
+                // "Name: value" per line — for a key that must not appear in shell history.
+                for (const line of readFileSync(headerFile, 'utf8').split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    const [name, value] = parseHeaderFlag(line);
+                    headers[name] = value;
+                }
+            }
+            say(`pairing with Fiodos…`);
+            const paired = await pair({
+                code,
+                target,
+                apiUrl: one(flags, 'api-url'),
+                name: one(flags, 'name'),
+                headers,
+                allowPaths: flags.values.allow || [],
+            });
+            writeConfig(upsertBridge(readConfig(), paired));
+            say(`paired — ${paired.name || paired.bridgeId} → ${paired.target.origin}`, 'ok');
+            dim(`kept here: ${configPath()} (your local key never leaves this machine)`);
+            if (!Object.keys(headers).length)
+                dim('no --header given: calls to the local dashboard go without credentials. Add one with --header "Authorization: Bearer …" if it needs it.');
+            if (one(flags, 'no-run') !== undefined)
+                return;
+            await runAll([paired]);
+            return;
+        }
+        case undefined:
+        case 'run': {
+            await runAll(readConfig().bridges);
+            return;
+        }
+        case 'status': {
+            const config = readConfig();
+            if (!config.bridges.length) {
+                say('nothing paired.', 'warn');
+                return;
+            }
+            for (const b of config.bridges)
+                process.stdout.write(`${JSON.stringify(redacted(b), null, 2)}\n`);
+            dim(`activity: ${activityLogPath()}`);
+            return;
+        }
+        case 'unpair': {
+            const config = readConfig();
+            const id = one(flags, 'bridge');
+            const victims = id ? config.bridges.filter((b) => b.bridgeId === id) : config.bridges;
+            let next = config;
+            for (const v of victims)
+                next = removeBridge(next, v.bridgeId);
+            writeConfig(next);
+            say(`removed ${victims.length} pairing(s) from this machine. Revoke it in the dashboard too.`, 'ok');
+            return;
+        }
+        case 'service': {
+            const sub = rest[0] || 'show';
+            const p = sub === 'install' ? service.install() : sub === 'uninstall' ? service.uninstall() : service.plan();
+            if (p.path)
+                say(`${sub === 'uninstall' ? 'removed' : sub === 'install' ? 'installed' : 'would write'} ${p.path}`, 'ok');
+            if (sub === 'show' && p.contents)
+                process.stdout.write(p.contents);
+            for (const n of p.notes)
+                dim(n);
+            return;
+        }
+        default:
+            usage();
+            process.exitCode = 2;
+    }
+}
+const invokedDirectly = process.argv[1] && /cli\.(js|ts)$/.test(process.argv[1]);
+if (invokedDirectly) {
+    main(process.argv.slice(2)).catch((err) => {
+        say(err.message || String(err), 'error');
+        process.exitCode = 1;
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+export interface BridgeTarget {
+    /** `http://localhost:3947` — scheme, host and port only; paths come per request. */
+    origin: string;
+    /** Path prefixes the bridge may call on this origin. `['/']` means everything. */
+    allowPaths: string[];
+    /** Headers added to every call — how the local dashboard authenticates the bridge. */
+    headers: Record<string, string>;
+}
+export interface PairedBridge {
+    bridgeId: string;
+    name: string;
+    apiUrl: string;
+    wsUrl: string;
+    token: string;
+    target: BridgeTarget;
+    pairedAt: string;
+}
+export interface BridgeConfig {
+    version: 1;
+    bridges: PairedBridge[];
+}
+export declare function bridgeHome(): string;
+export declare function configPath(): string;
+export declare function emptyConfig(): BridgeConfig;
+export declare function readConfig(): BridgeConfig;
+export declare function writeConfig(config: BridgeConfig): void;
+export declare function upsertBridge(config: BridgeConfig, bridge: PairedBridge): BridgeConfig;
+export declare function removeBridge(config: BridgeConfig, bridgeId: string): BridgeConfig;
+/** What `status` prints: never the token, never a header value. */
+export declare function redacted(bridge: PairedBridge): Record<string, unknown>;

package/dist/config.js

@@ -0,0 +1,81 @@
+/**
+ * What the bridge keeps on the customer's machine — and nothing else.
+ *
+ * Per paired bridge: its pairing token (to talk to Fiodos), the local address
+ * it may call, the path prefixes it may touch there, and the header(s) that
+ * local service authenticates with. No code, no copies of responses, no
+ * document (DESIGN_AGENTE_INTERNO D11).
+ *
+ * Lives in `~/.fiodos/bridge/config.json` (or `$FIODOS_BRIDGE_HOME`), mode
+ * 0600: the local key is in it.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function bridgeHome() {
+    const fromEnv = (process.env.FIODOS_BRIDGE_HOME || '').trim();
+    return fromEnv || join(homedir(), '.fiodos', 'bridge');
+}
+export function configPath() {
+    return join(bridgeHome(), 'config.json');
+}
+export function emptyConfig() {
+    return { version: 1, bridges: [] };
+}
+export function readConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return emptyConfig();
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        const bridges = Array.isArray(parsed.bridges) ? parsed.bridges.filter(isPaired) : [];
+        return { version: 1, bridges };
+    }
+    catch {
+        return emptyConfig();
+    }
+}
+export function writeConfig(config) {
+    const dir = bridgeHome();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = configPath();
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows has no POSIX modes; the directory is the user's own.
+    }
+}
+export function upsertBridge(config, bridge) {
+    const others = config.bridges.filter((b) => b.bridgeId !== bridge.bridgeId);
+    return { version: 1, bridges: [...others, bridge] };
+}
+export function removeBridge(config, bridgeId) {
+    return { version: 1, bridges: config.bridges.filter((b) => b.bridgeId !== bridgeId) };
+}
+/** What `status` prints: never the token, never a header value. */
+export function redacted(bridge) {
+    return {
+        bridgeId: bridge.bridgeId,
+        name: bridge.name,
+        apiUrl: bridge.apiUrl,
+        target: bridge.target.origin,
+        allowPaths: bridge.target.allowPaths,
+        headers: Object.keys(bridge.target.headers),
+        pairedAt: bridge.pairedAt,
+    };
+}
+function isPaired(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const b = value;
+    const target = b.target;
+    return (typeof b.bridgeId === 'string' &&
+        typeof b.token === 'string' &&
+        typeof b.wsUrl === 'string' &&
+        !!target &&
+        typeof target.origin === 'string');
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { judge, normalizeOrigin, normalizePrefix, outboundHeaders, ALLOWED_METHODS } from './allowlist.js';
+export type { IncomingRequest, Verdict } from './allowlist.js';
+export { readConfig, writeConfig, upsertBridge, removeBridge, redacted, configPath, bridgeHome } from './config.js';
+export type { BridgeConfig, BridgeTarget, PairedBridge } from './config.js';
+export { pair, parseHeaderFlag, DEFAULT_API_URL } from './pair.js';
+export { runBridge, makeExecutor, SUBPROTOCOL, VERSION } from './runner.js';
+export type { Executor, RunnerEvents } from './runner.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { judge, normalizeOrigin, normalizePrefix, outboundHeaders, ALLOWED_METHODS } from './allowlist.js';
+export { readConfig, writeConfig, upsertBridge, removeBridge, redacted, configPath, bridgeHome } from './config.js';
+export { pair, parseHeaderFlag, DEFAULT_API_URL } from './pair.js';
+export { runBridge, makeExecutor, SUBPROTOCOL, VERSION } from './runner.js';

package/dist/log.d.ts

@@ -0,0 +1,5 @@
+export declare function activityLogPath(): string;
+export declare function logActivity(line: string): void;
+/** The same face as the rest of the Fiodos installers: orb, name, message. */
+export declare function say(message: string, tone?: 'info' | 'ok' | 'warn' | 'error'): void;
+export declare function dim(message: string): void;

package/dist/log.js

@@ -0,0 +1,47 @@
+/**
+ * A short, rotating local activity log: what Fiodos asked this bridge to do,
+ * so the administrator of the machine can see it. Never a body, never a
+ * header value — method, path, status, time.
+ */
+import { existsSync, mkdirSync, renameSync, statSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { bridgeHome } from './config.js';
+const MAX_BYTES = 512 * 1024;
+export function activityLogPath() {
+    return join(bridgeHome(), 'activity.log');
+}
+export function logActivity(line) {
+    try {
+        mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+        const path = activityLogPath();
+        if (existsSync(path) && statSync(path).size > MAX_BYTES) {
+            renameSync(path, `${path}.1`);
+        }
+        appendFileSync(path, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+    }
+    catch {
+        // The log is a courtesy to the administrator, never a reason to fail.
+    }
+}
+const colors = () => {
+    const on = Boolean(process.stderr.isTTY) && !process.env.NO_COLOR;
+    return {
+        blue: on ? '\x1b[34m' : '',
+        cyan: on ? '\x1b[36m' : '',
+        green: on ? '\x1b[32m' : '',
+        yellow: on ? '\x1b[33m' : '',
+        red: on ? '\x1b[31m' : '',
+        dim: on ? '\x1b[2m' : '',
+        reset: on ? '\x1b[0m' : '',
+    };
+};
+/** The same face as the rest of the Fiodos installers: orb, name, message. */
+export function say(message, tone = 'info') {
+    const c = colors();
+    const orb = tone === 'ok' ? `${c.green}◉` : tone === 'warn' ? `${c.yellow}◉` : tone === 'error' ? `${c.red}◉` : `${c.cyan}◉`;
+    process.stderr.write(`${orb}${c.reset} ${c.blue}Fiodos${c.reset}  ${message}\n`);
+}
+export function dim(message) {
+    const c = colors();
+    process.stderr.write(`   ${c.dim}${message}${c.reset}\n`);
+}

package/dist/pair.d.ts

@@ -0,0 +1,21 @@
+import type { PairedBridge } from './config.js';
+export declare const DEFAULT_API_URL = "https://api.fiodos.com";
+export interface PairOptions {
+    code: string;
+    target: string;
+    apiUrl?: string;
+    name?: string;
+    headers?: Record<string, string>;
+    allowPaths?: string[];
+    fetchImpl?: typeof fetch;
+}
+export interface PairAnswer {
+    bridgeId: string;
+    token: string;
+    name: string;
+    target: string;
+    wsUrl: string;
+}
+/** `"Authorization: Bearer x"` → `["Authorization", "Bearer x"]`. */
+export declare function parseHeaderFlag(raw: string): [string, string];
+export declare function pair(options: PairOptions): Promise<PairedBridge>;

package/dist/pair.js

@@ -0,0 +1,56 @@
+/**
+ * Spend the one-time code the dashboard showed and keep what comes back.
+ */
+import { normalizeOrigin, normalizePrefix } from './allowlist.js';
+import { VERSION } from './runner.js';
+export const DEFAULT_API_URL = 'https://api.fiodos.com';
+/** `"Authorization: Bearer x"` → `["Authorization", "Bearer x"]`. */
+export function parseHeaderFlag(raw) {
+    const idx = raw.indexOf(':');
+    if (idx <= 0)
+        throw new Error(`--header expects "Name: value", got ${JSON.stringify(raw)}`);
+    const name = raw.slice(0, idx).trim();
+    const value = raw.slice(idx + 1).trim();
+    if (!name || !value)
+        throw new Error(`--header expects "Name: value", got ${JSON.stringify(raw)}`);
+    return [name, value];
+}
+export async function pair(options) {
+    const apiUrl = (options.apiUrl || DEFAULT_API_URL).replace(/\/+$/, '');
+    const origin = normalizeOrigin(options.target);
+    const fetchImpl = options.fetchImpl || fetch;
+    const res = await fetchImpl(`${apiUrl}/v1/bridge/pair`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify({ code: options.code.trim(), target: origin, name: options.name || '', version: VERSION }),
+    });
+    const text = await res.text();
+    let data = {};
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        // Not JSON: the status carries the news.
+    }
+    if (!res.ok) {
+        const detail = data.detail || {};
+        const message = String(detail.message || detail.error || data.message || `HTTP ${res.status}`);
+        throw new Error(message);
+    }
+    const answer = data;
+    if (!answer.token || !answer.bridgeId || !answer.wsUrl)
+        throw new Error('Fiodos answered without a token — try a new code.');
+    return {
+        bridgeId: answer.bridgeId,
+        name: answer.name || options.name || '',
+        apiUrl,
+        wsUrl: answer.wsUrl,
+        token: answer.token,
+        target: {
+            origin,
+            allowPaths: (options.allowPaths && options.allowPaths.length ? options.allowPaths : ['/']).map(normalizePrefix),
+            headers: { ...(options.headers || {}) },
+        },
+        pairedAt: new Date().toISOString(),
+    };
+}

package/dist/runner.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The bridge at work: one outbound WebSocket to Fiodos, held open; every
+ * `request` frame judged by the allow-list and executed against the local
+ * target; the answer sent back under the same id.
+ *
+ * Frames (see backend/routes/bridge_routes.py):
+ *   us → Fiodos  {type:"hello", token, version, target} · {type:"ping"} ·
+ *                {type:"response", id, status, headers, body} | {type:"response", id, error}
+ *   Fiodos → us  {type:"welcome", bridgeId, name} · {type:"pong"} ·
+ *                {type:"request", id, method, path, query, headers, body} ·
+ *                {type:"revoked"} · {type:"close", reason}
+ *
+ * The token travels as the first frame, not in the URL (URLs end up in access
+ * logs) and not as a header (Node's browser-shaped WebSocket has none).
+ */
+import { type IncomingRequest } from './allowlist.js';
+import type { PairedBridge } from './config.js';
+export declare const VERSION = "0.1.0";
+export declare const SUBPROTOCOL = "fiodos-bridge";
+export interface RunnerEvents {
+    /** The server revoked this bridge: the caller removes it from the config. */
+    onRevoked?: (bridge: PairedBridge) => void;
+    /** Another process took this bridge's place. */
+    onReplaced?: (bridge: PairedBridge) => void;
+}
+export interface Executor {
+    (request: IncomingRequest): Promise<{
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    } | {
+        error: string;
+    }>;
+}
+/** Execute one judged request against the local target with fetch. */
+export declare function makeExecutor(bridge: PairedBridge, fetchImpl?: typeof fetch): Executor;
+/**
+ * Hold the socket for one bridge until it is revoked or replaced. Resolves
+ * with `'revoked' | 'replaced'`; a dropped connection reconnects with backoff
+ * and never resolves on its own.
+ */
+export declare function runBridge(bridge: PairedBridge, events?: RunnerEvents, executor?: Executor): Promise<'revoked' | 'replaced'>;

package/dist/runner.js

@@ -0,0 +1,206 @@
+/**
+ * The bridge at work: one outbound WebSocket to Fiodos, held open; every
+ * `request` frame judged by the allow-list and executed against the local
+ * target; the answer sent back under the same id.
+ *
+ * Frames (see backend/routes/bridge_routes.py):
+ *   us → Fiodos  {type:"hello", token, version, target} · {type:"ping"} ·
+ *                {type:"response", id, status, headers, body} | {type:"response", id, error}
+ *   Fiodos → us  {type:"welcome", bridgeId, name} · {type:"pong"} ·
+ *                {type:"request", id, method, path, query, headers, body} ·
+ *                {type:"revoked"} · {type:"close", reason}
+ *
+ * The token travels as the first frame, not in the URL (URLs end up in access
+ * logs) and not as a header (Node's browser-shaped WebSocket has none).
+ */
+import { judge, outboundHeaders } from './allowlist.js';
+import { logActivity, say, dim } from './log.js';
+export const VERSION = '0.1.0';
+export const SUBPROTOCOL = 'fiodos-bridge';
+const PING_MS = 20_000;
+const REQUEST_TIMEOUT_MS = 55_000;
+const MAX_BODY_CHARS = 2_000_000;
+const BACKOFF_MIN_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+/** Execute one judged request against the local target with fetch. */
+export function makeExecutor(bridge, fetchImpl = fetch) {
+    return async (request) => {
+        const verdict = judge(bridge.target, request);
+        if (!verdict.ok) {
+            logActivity(`REFUSED ${request.method} ${request.path} — ${verdict.reason}`);
+            return { error: verdict.reason };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        const started = Date.now();
+        try {
+            const hasBody = request.body != null && verdict.method !== 'GET';
+            const res = await fetchImpl(verdict.url, {
+                method: verdict.method,
+                headers: outboundHeaders(bridge.target, request.headers),
+                body: hasBody ? String(request.body) : undefined,
+                signal: controller.signal,
+                redirect: 'manual',
+            });
+            let body = await res.text();
+            if (body.length > MAX_BODY_CHARS)
+                body = body.slice(0, MAX_BODY_CHARS);
+            const headers = {};
+            const ct = res.headers.get('content-type');
+            if (ct)
+                headers['content-type'] = ct;
+            logActivity(`${verdict.method} ${request.path} → ${res.status} (${Date.now() - started}ms)`);
+            return { status: res.status, headers, body };
+        }
+        catch (err) {
+            const reason = controller.signal.aborted ? `local service did not answer in ${REQUEST_TIMEOUT_MS / 1000}s` : `local service unreachable: ${err.message}`;
+            logActivity(`${verdict.method} ${request.path} → ERROR ${reason}`);
+            return { error: reason };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+function backoff(attempt) {
+    const ms = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * 2 ** Math.min(attempt, 6));
+    return ms + Math.floor(Math.random() * 500);
+}
+/**
+ * Hold the socket for one bridge until it is revoked or replaced. Resolves
+ * with `'revoked' | 'replaced'`; a dropped connection reconnects with backoff
+ * and never resolves on its own.
+ */
+export function runBridge(bridge, events = {}, executor = makeExecutor(bridge)) {
+    const WebSocketCtor = globalThis.WebSocket;
+    if (!WebSocketCtor)
+        throw new Error('This Node.js has no WebSocket client. Node 22.5 or newer is required.');
+    return new Promise((resolve) => {
+        let attempt = 0;
+        let settled = false;
+        const finish = (why) => {
+            if (settled)
+                return;
+            settled = true;
+            if (why === 'revoked')
+                events.onRevoked?.(bridge);
+            else
+                events.onReplaced?.(bridge);
+            resolve(why);
+        };
+        const connect = () => {
+            if (settled)
+                return;
+            let ws;
+            try {
+                ws = new WebSocketCtor(bridge.wsUrl, [SUBPROTOCOL]);
+            }
+            catch (err) {
+                say(`could not open the connection: ${err.message}`, 'error');
+                setTimeout(connect, backoff(attempt++));
+                return;
+            }
+            let pingTimer = null;
+            let welcomed = false;
+            ws.addEventListener('open', () => {
+                ws.send(JSON.stringify({ type: 'hello', token: bridge.token, version: VERSION, target: bridge.target.origin }));
+                pingTimer = setInterval(() => {
+                    try {
+                        ws.send(JSON.stringify({ type: 'ping' }));
+                    }
+                    catch {
+                        // The close handler will reconnect.
+                    }
+                }, PING_MS);
+            });
+            ws.addEventListener('message', (event) => {
+                let frame;
+                try {
+                    frame = JSON.parse(String(event.data));
+                }
+                catch {
+                    return;
+                }
+                const type = String(frame.type || '');
+                if (type === 'welcome') {
+                    welcomed = true;
+                    attempt = 0;
+                    say(`connected — ${bridge.name || bridge.bridgeId} is reachable by your company agent`, 'ok');
+                    dim(`serving ${bridge.target.origin}  ·  Ctrl-C to stop`);
+                    logActivity(`CONNECTED ${bridge.wsUrl}`);
+                    return;
+                }
+                if (type === 'pong')
+                    return;
+                if (type === 'revoked') {
+                    say('this bridge was revoked from the Fiodos dashboard — stopping.', 'warn');
+                    logActivity('REVOKED by the dashboard');
+                    finish('revoked');
+                    try {
+                        ws.close(1000, 'revoked');
+                    }
+                    catch {
+                        // Already closing.
+                    }
+                    return;
+                }
+                if (type === 'close' && String(frame.reason || '') === 'replaced') {
+                    say('another bridge process connected with this pairing — this one exits.', 'warn');
+                    logActivity('REPLACED by another process');
+                    finish('replaced');
+                    try {
+                        ws.close(1000, 'replaced');
+                    }
+                    catch {
+                        // Already closing.
+                    }
+                    return;
+                }
+                if (type === 'request') {
+                    const id = String(frame.id || '');
+                    const request = {
+                        method: String(frame.method || 'GET'),
+                        path: String(frame.path || '/'),
+                        query: frame.query || {},
+                        headers: frame.headers || {},
+                        body: typeof frame.body === 'string' ? frame.body : null,
+                    };
+                    void executor(request).then((answer) => {
+                        try {
+                            ws.send(JSON.stringify({ type: 'response', id, ...answer }));
+                        }
+                        catch {
+                            // Socket gone; the server times the request out.
+                        }
+                    });
+                }
+            });
+            const onGone = (what) => {
+                if (pingTimer)
+                    clearInterval(pingTimer);
+                pingTimer = null;
+                if (settled)
+                    return;
+                const wait = backoff(attempt++);
+                if (welcomed)
+                    logActivity(`DISCONNECTED (${what})`);
+                say(`${what} — reconnecting in ${Math.round(wait / 1000)}s`, 'warn');
+                setTimeout(connect, wait);
+            };
+            ws.addEventListener('close', (raw) => {
+                const event = raw;
+                if (event.code === 4401) {
+                    say('Fiodos did not accept this bridge\u2019s token. Pair it again from the dashboard.', 'error');
+                    logActivity('REFUSED token (4401)');
+                    finish('revoked');
+                    return;
+                }
+                onGone(`connection closed (${event.code})`);
+            });
+            ws.addEventListener('error', () => {
+                // `close` follows an error; the message there is enough.
+            });
+        };
+        connect();
+    });
+}

package/dist/service.d.ts

@@ -0,0 +1,11 @@
+export declare const SERVICE_LABEL = "com.fiodos.bridge";
+export interface ServicePlan {
+    platform: string;
+    path: string | null;
+    contents: string | null;
+    commands: string[];
+    notes: string[];
+}
+export declare function plan(): ServicePlan;
+export declare function install(): ServicePlan;
+export declare function uninstall(): ServicePlan;

package/dist/service.js

@@ -0,0 +1,142 @@
+/**
+ * `fiodos-bridge service install` — start with the machine.
+ *
+ * macOS: a launchd agent in ~/Library/LaunchAgents (runs when the user is
+ * logged in — a headless server should use a LaunchDaemon, which needs root
+ * and is printed as instructions). Linux: a systemd --user unit, with the
+ * `loginctl enable-linger` reminder so it survives logout. Windows: printed
+ * instructions (Task Scheduler), because writing a service there needs tools
+ * this package does not ship.
+ *
+ * Every file written is shown, so the administrator can read what runs.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { bridgeHome } from './config.js';
+export const SERVICE_LABEL = 'com.fiodos.bridge';
+function nodeBinary() {
+    return process.execPath;
+}
+function bridgeEntry() {
+    // The compiled CLI of THIS installation, so the service runs the same code.
+    return new URL('./cli.js', import.meta.url).pathname;
+}
+export function plan() {
+    const os = platform();
+    const node = nodeBinary();
+    const entry = bridgeEntry();
+    const home = bridgeHome();
+    if (os === 'darwin') {
+        const path = join(homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+        const contents = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${node}</string>
+    <string>${entry}</string>
+    <string>run</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict><key>FIODOS_BRIDGE_HOME</key><string>${home}</string></dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${join(home, 'service.log')}</string>
+  <key>StandardErrorPath</key><string>${join(home, 'service.log')}</string>
+</dict>
+</plist>
+`;
+        return {
+            platform: os,
+            path,
+            contents,
+            commands: [`launchctl unload ${path} 2>/dev/null || true`, `launchctl load -w ${path}`],
+            notes: [
+                'Runs while this user is logged in. For a server nobody logs into, copy the plist to /Library/LaunchDaemons (as root) and load it there.',
+            ],
+        };
+    }
+    if (os === 'linux') {
+        const dir = join(homedir(), '.config', 'systemd', 'user');
+        const path = join(dir, 'fiodos-bridge.service');
+        const contents = `[Unit]
+Description=Fiodos bridge (reaches a dashboard on this network for the Fiodos company agent)
+After=network-online.target
+
+[Service]
+ExecStart=${node} ${entry} run
+Environment=FIODOS_BRIDGE_HOME=${home}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+        return {
+            platform: os,
+            path,
+            contents,
+            commands: ['systemctl --user daemon-reload', 'systemctl --user enable --now fiodos-bridge.service'],
+            notes: ['So it keeps running after you log out: sudo loginctl enable-linger $USER'],
+        };
+    }
+    return {
+        platform: os,
+        path: null,
+        contents: null,
+        commands: [],
+        notes: [
+            'Automatic service install is not available on this platform.',
+            `Run at start-up with your scheduler: "${node}" "${entry}" run`,
+            `Keep FIODOS_BRIDGE_HOME=${home} in its environment.`,
+            'Or run the container image: docker run -d --restart unless-stopped -v fiodos-bridge:/data --network host fiodos/bridge run',
+        ],
+    };
+}
+export function install() {
+    const p = plan();
+    if (!p.path || !p.contents)
+        return p;
+    mkdirSync(join(p.path, '..'), { recursive: true });
+    mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+    writeFileSync(p.path, p.contents, { mode: 0o644 });
+    for (const command of p.commands) {
+        const [bin, ...args] = command.replace(/ 2>\/dev\/null \|\| true$/, '').split(' ');
+        try {
+            execFileSync(bin, args, { stdio: 'ignore' });
+        }
+        catch {
+            // `unload` of a not-yet-loaded agent fails harmlessly; anything else is
+            // reported by `status`.
+        }
+    }
+    return p;
+}
+export function uninstall() {
+    const p = plan();
+    if (!p.path)
+        return p;
+    if (p.platform === 'darwin') {
+        try {
+            execFileSync('launchctl', ['unload', p.path], { stdio: 'ignore' });
+        }
+        catch {
+            // Not loaded.
+        }
+    }
+    else if (p.platform === 'linux') {
+        try {
+            execFileSync('systemctl', ['--user', 'disable', '--now', 'fiodos-bridge.service'], { stdio: 'ignore' });
+        }
+        catch {
+            // Not enabled.
+        }
+    }
+    if (existsSync(p.path))
+        unlinkSync(p.path);
+    return p;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@fiodos/bridge",
+  "version": "0.1.0",
+  "description": "The Fiodos bridge — a small process that runs beside a dashboard on your own network and lets your Fiodos company agent reach it. It calls Fiodos (one outbound WebSocket); nothing calls in. Pair it with the one-time code your dashboard shows: `npx -y --loglevel=error @fiodos/bridge pair <code> --target http://localhost:3947`.",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "fiodos-bridge": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "Dockerfile",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}