@factiii/runner 0.27.0 → 0.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DISCLOSURE ADDED
@@ -0,0 +1,174 @@
1
+ @factiii/runner: dual-use disclosure
2
+
3
+ WHAT THIS PACKAGE IS
4
+
5
+ Factiii Runner lets a person run AI coding agents (Claude Code and similar)
6
+ on a computer they own, and drive them from the Factiii web, desktop and
7
+ mobile apps (https://factiii.com). The owner installs it on their own machine
8
+ and pairs it with their own Factiii account. It then accepts work only from
9
+ that account and from board members the owner has approved.
10
+
11
+ Doing that job means the runner can do things that malware also does. Each
12
+ one is listed below with why it is there and how the owner controls it.
13
+ Nothing here runs at install: the package has no install scripts.
14
+
15
+
16
+ CAPABILITIES THAT RESEMBLE MALWARE
17
+
18
+ 1. Remote shell and command execution
19
+ The runner starts terminal sessions (tmux) and agent processes on the
20
+ machine and streams them to the owner's Factiii app over WebRTC. That is
21
+ the product: the owner, or an approved board member, types into a
22
+ terminal on their own computer from a phone or browser. Some processes
23
+ are spawned detached so that a running agent survives a runner restart.
24
+
25
+ 2. iOS Simulator viewing and input (macOS)
26
+ native/simhid.m and native/simstream.m are built on the owner's Mac and
27
+ stream the iOS Simulator's video and send it touch input, for testing
28
+ mobile apps. They reach the Simulator only, never the Mac's own screen,
29
+ mouse or keyboard. The runner does not capture or control the Mac's
30
+ desktop; to see it remotely the owner uses macOS Screen Sharing (VNC)
31
+ over their own Tailscale network, which the runner neither installs nor
32
+ starts.
33
+
34
+ 3. Reverse tunnels (frpc, downloaded on first use)
35
+ The package does not contain the frp client (https://github.com/fatedier/frp).
36
+ The first time the owner or an agent shares a local dev server as a
37
+ preview link (`factiii-expose`), the runner downloads frp's official
38
+ release from GitHub, checks its SHA-256 against the value frp publishes
39
+ (pinned in the runner's source), and refuses it if they differ. A runner
40
+ that never shares a port never has frpc. Tunnels go only to Factiii's own
41
+ tunnel server, each with a tunnel-only credential (7 days, renewed daily
42
+ while the tunnel runs) that nothing else on the server accepts; the
43
+ runner's access token never reaches frpc. A tunnel keeps running after
44
+ the session that opened it ends, until it is stopped. Each tunnel is
45
+ listed in the app and can be stopped.
46
+
47
+ 4. Starting at login (persistence)
48
+ Off by default. Only the person at the machine turns it on, in its own
49
+ terminal: by answering yes to setup's "Start this runner at login? [y/N]"
50
+ (Enter alone means no), or by running `factiii-runner service install`.
51
+ Either installs one per-user login service (a LaunchAgent on macOS, a
52
+ systemd user unit on Linux, a scheduled task on Windows), so the runner is
53
+ available after a reboot. The app and the account can see it and turn it
54
+ off, never on: a request to install it from anywhere but that terminal is
55
+ refused. `factiii-runner service remove` deletes it.
56
+ The runner lists the LaunchAgents folder to find and manage its own
57
+ entries, and reads the owner's other agents there only to name the
58
+ services in item 10. It never adds, changes or removes another agent.
59
+
60
+ 5. Credentials and secrets
61
+ - The runner's connection token is stored encrypted, under a key kept in
62
+ the OS keychain (macOS Keychain via `security`, libsecret on Linux,
63
+ DPAPI on Windows).
64
+ - The owner can keep deploy secrets in a local, encrypted store. They are
65
+ handed to commands only through named jobs the owner defines, and each
66
+ use is recorded in an audit log the owner can read.
67
+ - The runner reads environment variables it is configured with (for
68
+ example FACTIII_* settings). It never reads `.env` files, SSH keys,
69
+ browser data, wallets or other programs' credentials. A test in this
70
+ package (src/packageContents.test.ts) fails if bundled code opens a
71
+ .env file.
72
+
73
+ 6. System and remote-access inspection
74
+ Runner > Status, and "Ready to be a server" in Factiii Desktop, show the
75
+ owner whether their machine can serve as an always-on host. To do this the
76
+ runner reads disk and memory use (/proc/meminfo on Linux), power settings
77
+ (`pmset -g`), screen-lock and FileVault state (`sysadminctl`, `ioreg`),
78
+ whether Screen Sharing is on (a local check of port 5900), and the
79
+ machine's Tailscale address (`ifconfig`, `tailscale status`). These
80
+ results go to the owner's own app.
81
+ - The runner never changes these settings itself. Where a setting needs
82
+ changing it shows the command, such as `sudo pmset ...`, for the owner
83
+ to run, or the owner runs it from Factiii Desktop with their password.
84
+ - "Keep awake" holds `caffeinate` while the owner asks for it.
85
+ - The runner never installs or starts Tailscale. It only reads its status.
86
+
87
+ 7. Heartbeat to a status page (opt-in)
88
+ If the owner runs `factiii-runner status-page set` with a token for their
89
+ own status page, the runner sends a periodic heartbeat to it: its name,
90
+ version and time, plus this machine's Tailscale name, address and user.
91
+ That page shows the Tailscale details only on its access-controlled admin
92
+ view, as the owner's way back in when Factiii itself is down. This is off
93
+ unless the owner turns it on.
94
+
95
+ 8. Updating itself
96
+ The runner checks npm and its GitHub Releases (github.com/factiii/runner)
97
+ for a newer @factiii/runner. By default it installs one by itself when
98
+ nothing is running, about every 6 hours; "factiii-runner update auto off"
99
+ turns that off, and then it installs only after a person clicks "Approve
100
+ update" in the Factiii app. It installs only a version newer than the one
101
+ running, only from the npm registry or a GitHub Release tarball that
102
+ matches its published SHA-256 and carries a valid signature (its .sig)
103
+ by Factiii's release key, an Ed25519 public key built into the runner
104
+ (src/releaseKey.ts). A GitHub Release with no signature, or one that
105
+ does not verify, is refused, so whoever can publish a release on that
106
+ repository still cannot make a runner install it without the key. From
107
+ npm it installs only what npm serves: each version is published from
108
+ Factiii's release workflow over npm's trusted publishing, and goes live
109
+ only when the owner approves it with two-factor authentication. Before
110
+ installing it keeps a copy of the
111
+ running version, and if the new one fails to start it puts that copy
112
+ back and does not install the failed version by itself again.
113
+
114
+ 9. Other downloads
115
+ On request, the runner installs developer tools the owner asks for: the
116
+ AI agent CLIs, Python packages for the local embedder (embedder/), and
117
+ Tart (a pinned release that the runner verifies is signed by Cirrus Labs
118
+ before installing it).
119
+
120
+
121
+ 10. Connections, running services and their logs (owner only)
122
+ Runner > Remote connections shows the runner's owner who is connected
123
+ (each link's account, transport, start time and open terminals) and what
124
+ the machine is serving: containers (`docker ps`), pm2 processes
125
+ (`pm2 jlist`), the user's LaunchAgents (`launchctl list`, and each one's
126
+ plist to see what it runs), listening ports (`lsof`) and the local
127
+ embedder's health. On request it shows the last lines of one of those
128
+ services' logs (`pm2 logs`, `docker logs`, or the log file a LaunchAgent
129
+ names), at most 2,000 lines. All of it is read-only, answered only to the
130
+ owner over their own link, and never sent to the Factiii server.
131
+
132
+ 11. Who can connect, how long access lasts, and how to stop it
133
+ Who: a link opens only for the owner and for board members the owner
134
+ gave an access level, on a board the owner has joined. The server names
135
+ who is connecting and their boards, and the runner checks its own grant
136
+ for that person; if either is missing, the link is refused. Lowering a
137
+ member's level closes their terminals and video at once. Setting them to
138
+ None on every board closes their link. A card AI session or a job they
139
+ already started keeps running until the owner ends it.
140
+ How long: the runner's access token expires after at most 30 days (7
141
+ for a current runner once it has renewed) and is renewed daily. Its refresh token changes on every use and stops working
142
+ after 90 days unused. If an old refresh token is reused, the server
143
+ ends the pairing, cuts live connections and alerts the owner. Terminal
144
+ sessions have no idle timeout: they run until someone ends them from
145
+ the app, or until the runner stops.
146
+ How to stop it:
147
+ - Stop the `factiii-runner start` process (Ctrl-C, or end the process).
148
+ Nothing restarts it unless the owner installed the login service
149
+ (item 4).
150
+ - `factiii-runner service remove` removes the login service.
151
+ - "Disconnect" under Settings > Runners in the Factiii app revokes the
152
+ runner on the server, which checks this at every connection. The
153
+ runner is told to stop its jobs and delete their containers.
154
+ - `factiii-runner nuke` erases everything the runner holds, secrets
155
+ included, and unpairs it.
156
+ - `npm uninstall -g @factiii/runner` removes the package.
157
+
158
+
159
+ WHAT IT DOES NOT DO
160
+
161
+ - No code runs at install time.
162
+ - It sends no data anywhere except the Factiii servers the owner paired
163
+ with, the owner's own opt-in status page, and the services the owner's
164
+ agents and jobs are told to reach.
165
+ - It does not hide itself. It shows up as `factiii-runner` in process lists
166
+ and as a named login item. `factiii-runner service remove` and
167
+ `npm uninstall -g @factiii/runner` remove it.
168
+ - Nothing in the published code is obfuscated. dist/cli.js is an esbuild
169
+ bundle of the TypeScript source, unminified.
170
+
171
+
172
+ CONTACT
173
+
174
+ Publisher: Factiii (https://factiii.com), support@factiii.com
package/README.md CHANGED
@@ -5,49 +5,69 @@ A headless daemon that runs Factiii's Board AI agents (Claude-driven coding sess
5
5
  ## Requirements
6
6
 
7
7
  - Node 20+
8
- - git, tmux, and redis-server on PATH (installed for you when a space first opens)
8
+ - git and tmux on PATH (installed for you when a space first opens); redis, OrbStack and Tailscale are optional extras
9
9
  - The agent CLIs: `claude` and `codex`
10
- - Optional, by feature: `sops` and `age` (Secrets), Xcode with a simulator (simulator panel, macOS), Screen Recording and Accessibility for "Factiii Screen" (desktop view, macOS)
10
+ - Optional, by feature: `sops` and `age` (Secrets), Xcode with a simulator (simulator panel, macOS)
11
11
  - A Factiii account
12
12
  - Outbound network access to the Factiii API server
13
13
 
14
14
  ## Install
15
15
 
16
16
  ```bash
17
- npm install -g @factiii/runner
17
+ curl -fsSL https://factiii.com/runner.sh | sh
18
18
  ```
19
19
 
20
- Or run without installing:
20
+ It installs the newest release from [github.com/factiii/runner](https://github.com/factiii/runner/releases) after checking its `.sha256`, brings its own Node when the machine has none (or one outside 20 to 24), then runs `factiii-runner setup`. Run it again to update. npm has blocked every release after 0.27.0, so `npm install -g @factiii/runner` installs that old version until npm unblocks the package.
21
+
22
+ Without the script:
21
23
 
22
24
  ```bash
23
- npx @factiii/runner setup
25
+ npm install -g https://github.com/factiii/runner/releases/download/v0.39.0/factiii-runner-0.39.0.tgz
26
+ factiii-runner setup
24
27
  ```
25
28
 
26
29
  ## Usage
27
30
 
28
31
  ```bash
29
- factiii-runner setup # pair this runner, then check the machine
32
+ factiii-runner setup # install and pair the connector, then list the parts
30
33
  factiii-runner connect # re-pair with a different account
31
34
  factiii-runner start # run the daemon (keep this process alive)
32
35
  factiii-runner status # show current config + credential storage state
36
+ factiii-runner parts list | add | remove | start | stop <part> # pick what this runner does
33
37
  factiii-runner doctor # check what this machine needs, and fix what the runner may fix
34
38
  factiii-runner service install | status | remove # start at login, restart after a crash
35
39
  factiii-runner password # enter an old connection password once, to remove it (see Security notes)
36
40
  ```
37
41
 
38
- `setup` walks you through the browser pairing flow. After it finishes, `factiii-runner start` runs the daemon. The host toolchain (git, tmux, redis, the agent CLIs) installs when you first open a space on the board, with progress shown there; `factiii-runner setup --tools` runs the same install from the terminal.
42
+ `setup` walks you through the browser pairing flow and installs nothing else: the runner starts as a **connector** (pairing plus the encrypted link to your devices). After it finishes, `factiii-runner start` runs the daemon. Everything else is a part you add (below). A board's own toolchain (git, tmux, node, the Claude CLI, and the board's provider CLI when it is Codex) also installs when you first open a space on the board, with progress shown there; `factiii-runner setup --tools` runs the same install from the terminal.
43
+
44
+ ### Parts
45
+
46
+ Each part says what it does, whether it is installed, and about how much disk and memory it costs. The same list is in the app under the runner's Status > Features, where one button adds, removes, starts or stops a part and installs run in the background.
47
+
48
+ | Part | Needs |
49
+ |---|---|
50
+ | `terminals` | git, tmux, script |
51
+ | `claude` / `codex` | node and that agent CLI |
52
+ | `secrets` | sops and age |
53
+ | `simulator` (macOS) | Xcode and an iOS simulator |
54
+ | `local-ai` | Ollama (start and stop run `ollama serve`) |
55
+ | `vault` | its database, PGlite (installed into the runner folder; removing the part keeps your files) |
56
+
57
+ - `add` runs the `doctor` fixes for that part's requirements only. What needs `sudo` or a settings pane is printed, never run.
58
+ - `remove` uninstalls only what `add` installed (kept in `parts.json` in the runner folder), never node, git or script, and never a tool another installed part uses.
59
+ - A part already on the machine reads as installed, so updating an existing runner changes nothing.
39
60
 
40
61
  `doctor` is the first thing to run when a board reports "Couldn't initialize the environment". It prints the resolved location of every tool the runner needs and the PATH it searched, which separates a tool that is genuinely absent from one that is installed somewhere the runner cannot see.
41
62
 
42
- ### The checklist (`setup` and `doctor`)
63
+ ### The checklist (`doctor`)
43
64
 
44
- `setup` ends with a checklist of the machine, and `doctor` prints it again at any time. Each item says which feature needs it and whether it is required, so nobody installs Xcode for a runner that never shows a simulator. An unmet item gets one of three things:
65
+ `doctor` prints a checklist of the machine at any time. Each item says which feature needs it and whether it is required, so nobody installs Xcode for a runner that never shows a simulator. Only the connector's items are required; every tool is optional, named by the part that needs it. An unmet item gets one of two things:
45
66
 
46
67
  - **"Fix it for me? [Y/n]"** when no administrator is needed: a tool Homebrew or npm installs (tmux, sops, age, the agent CLIs), or the runner's own folder. With a yes the runner installs tools and nothing else.
47
68
  - **The command to copy** when it needs `sudo` or is your decision to make: packages on Linux (apt, dnf, pacman), sleep and power settings, automatic login, lingering. The runner prints it and never runs it.
48
- - **The System Settings path**, and an offer to open that pane, when only a person can do it: Screen Recording and Accessibility for "Factiii Screen". The runner cannot tick the box.
49
69
 
50
- The tools of this checklist (git, redis-server, tmux, script, node, claude, codex, sops, age) also show in the app, item by item, under Runner Settings > Setup > Environment, with the same install command for each one that is missing.
70
+ The tools of this checklist (git, tmux, script, node, claude, codex, redis, sops, age, OrbStack, Tailscale) also show in the app, item by item, under the runner's Status > Features. Initialize installs the basics (git, tmux, script, node, claude); each extra (codex, redis for live agent status in terminals, sops and age, OrbStack for containers, Tailscale for remote access) has its own Install button, and Connect Codex installs codex itself. Tailscale's Install also starts tailscaled as a system service (your password, once), makes you its operator, and runs `tailscale up`: open the "Sign in to Tailscale" button it shows, or set `TAILSCALE_AUTH_KEY` (an auth key, or an OAuth client secret with `?preauthorized=true` and its tags) in the runner's environment to join with no sign-in. Screen Sharing then works at `vnc://<its tailnet IP>`, even when Factiii is down.
51
71
 
52
72
  `doctor` exits 1 while a required item is unmet and 0 otherwise. Without a terminal, or with `--no-fix`, it only reports: it asks nothing and changes nothing. `--json` prints the same report for a script.
53
73
 
@@ -71,7 +91,7 @@ factiii-runner service remove # stop it and delete what install wrote
71
91
 
72
92
  - The service runs `factiii-runner start` with the node and the runner that were installed when you ran `service install`, and the PATH of that terminal. If you move to another Node version or reinstall the runner somewhere else, run `service install` again: it rewrites its file and restarts the service.
73
93
  - It restarts the runner after a crash, not after a stop: a runner you disconnect from your account in Settings stays down.
74
- - Updates approved from the app work as before. The runner relaunches itself; the service is not involved.
94
+ - Updates approved from the app work as before, and the runner also updates itself when nothing is running (on by default; `factiii-runner update auto off`). It relaunches itself; the service is not involved. A new version that fails to start is rolled back to the one before (`factiii-runner update status`).
75
95
  - Output goes to `~/.factiii-runner/logs/runner.log`. When it passes 10 MB the runner copies it to `runner.log.1` (replacing the last one) and empties it, at start and once an hour, so the two files are all it ever keeps.
76
96
  - If a runner is already running when you install the service (started by hand, or under another process manager), the service is written but not started, so there are never two. Stop the old one and run `service install` again.
77
97
  - `install` refuses to overwrite a file of the same name that it did not write, and `remove` deletes only what `install` wrote.
@@ -94,16 +114,16 @@ factiii-runner service remove # stop it and delete what install wrote
94
114
 
95
115
  ## Security notes
96
116
 
97
- The credentials the runner itself stores in `~/.factiii-runner/` — each board's GitHub PAT and OneDrive refresh token (`<board>/.creds/`), and the pairing JWT (`config.json`) — are **encrypted at rest** with AES-256-GCM at permissions `0600`, all under the same machine keychain key. Existing plaintext files migrate automatically on the first read; no re-pairing. The Claude/Codex sign-ins are not in this list: see Provider sign-ins below.
117
+ The credentials the runner itself stores in `~/.factiii-runner/` — each board's GitHub PAT (`<board>/.creds/`), and the pairing JWT (`config.json`) — are **encrypted at rest** with AES-256-GCM at permissions `0600`, all under the same machine keychain key. Existing plaintext files migrate automatically on the first read; no re-pairing. A board's `onedrive.json`, left by the since-removed runner OneDrive index, is deleted on the first read: nothing uses it. The Claude/Codex sign-ins are not in this list: see Provider sign-ins below.
98
118
 
99
119
  **There is no plaintext fallback.** A host with no usable keychain (headless Linux without libsecret, a CI container, a locked login keyring) stores nothing at all: `setup` refuses, and a running daemon connects but fails every credential read and write. It tells you which tool is missing and how to install it, both on the console and in Runner Settings → Secrets. Fix the keyring, restart, and it picks up where it left off.
100
120
 
101
121
  ### The machine key, and the connection password that is gone
102
122
 
103
123
  1. **Machine key (always).** A 32-byte key in the OS keychain — macOS Keychain, libsecret on Linux, DPAPI on Windows. Bound to the logged-in OS user, so the daemon works unattended. The runner touches exactly one keychain item (`factiii-runner` / `config-encryption-key`) and never deletes anything; if that item exists but can't be read, it reports the problem rather than minting a replacement over the top of it.
104
- 2. **Connection password (removed).** Older versions let you put a password on top of the machine key. It sealed the GitHub and OneDrive connections under a data key (`vault-key.json`), so a password-protected runner came up locked after every restart (including auto-update) and could not clone, deploy, or even show which GitHub user was connected until someone typed it. That password can no longer be set or changed. The connections are sealed under the machine key alone, like the pairing config, and the runner reads them the moment it starts. Values that must stay behind a password belong in deploy secrets (below).
124
+ 2. **Connection password (removed).** Older versions let you put a password on top of the machine key. It sealed the GitHub connections (and the OneDrive ones of the since-removed runner OneDrive index) under a data key (`vault-key.json`), so a password-protected runner came up locked after every restart (including auto-update) and could not clone, deploy, or even show which GitHub user was connected until someone typed it. That password can no longer be set or changed. The connections are sealed under the machine key alone, like the pairing config, and the runner reads them the moment it starts. Values that must stay behind a password belong in deploy secrets (below).
105
125
 
106
- **Upgrading a runner that has a password set: one unlock, then never again.** Connection files written before this change are still in the old envelope. With no password set they are converted at the first start. With a password set, the runner needs it **one last time**: it starts, connects, and reports those files as locked (console, and Runner Settings → Secrets) rather than as "no repository". Enter the password once — in the app, at the terminal prompt `start` shows, or with `factiii-runner password` on a host with neither — and every board's files are rewritten under the machine key together. A file is rewritten only after it has been decrypted, through a temp file and a rename, so a failed conversion leaves the old file as it was. **An update approved from the app never waits at a terminal for this.** The relaunch after a self-update skips the terminal prompt even when the runner was started in a terminal — nobody is sitting at it — so the runner connects with those connections locked, prints the problem and the ways to unlock, and the app asks its owner for the password in the same banner that offered the update, on any page. A runner that is unlocked with `factiii-runner password` while it is running notices within a few seconds, tells its connected clients, and starts the OneDrive indexes that were waiting.
126
+ **Upgrading a runner that has a password set: one unlock, then never again.** Connection files written before this change are still in the old envelope. With no password set they are converted at the first start. With a password set, the runner needs it **one last time**: it starts, connects, and reports those files as locked (console, and Runner Settings → Secrets) rather than as "no repository". Enter the password once — in the app, at the terminal prompt `start` shows, or with `factiii-runner password` on a host with neither — and every board's files are rewritten under the machine key together. A file is rewritten only after it has been decrypted, through a temp file and a rename, so a failed conversion leaves the old file as it was. **An update approved from the app never waits at a terminal for this.** The relaunch after a self-update skips the terminal prompt even when the runner was started in a terminal — nobody is sitting at it — so the runner connects with those connections locked, prints the problem and the ways to unlock, and the app asks its owner for the password in the same banner that offered the update, on any page. A runner that is unlocked with `factiii-runner password` while it is running notices within a few seconds and tells its connected clients.
107
127
 
108
128
  **When the vault file goes.** As soon as no file is left in the old envelope — at start, or right after that unlock — `vault-key.json` is renamed to `vault-key.retired.json` and the password stops existing: no later restart asks for it. A runner that has a password set but nothing sealed under it loses the password at start without being asked. If a file will not decrypt even with the vault open, it is left in place and named on the console, and the vault stays until that board is reconnected (which replaces the file).
109
129
 
@@ -115,4 +135,4 @@ The Claude/Codex OAuth files are written by those CLIs into each board's state d
115
135
 
116
136
  What this protects is **offline** access to the files without the login keychain: a synced folder, a backup, a disk read on another machine. It does **not** protect against someone signed in as the runner's OS user, nor a compromised runner host — the daemon can always read what it can use. Only run a runner on a machine you trust, and only pair with accounts you own.
117
137
 
118
- The deploy **Secrets** panel is a separate store with a different model: sops/age, under a password supplied per operation and never cached. The two passwords are independent on purpose — deploy secrets never need to be read unattended, connection tokens do, which is why connection tokens no longer sit behind any password. See `.specs/deploy.md`.
138
+ The deploy **Secrets** panel is a separate store with a different model: sops/age, under a password supplied per operation and never cached. The two passwords are independent on purpose — deploy secrets never need to be read unattended, connection tokens do, which is why connection tokens no longer sit behind any password. See `.specs/runner-secrets-store.md`.