From 2f12892d7187084946d2faa7a120b6c930bed3ec Mon Sep 17 00:00:00 2001 From: Angel Nieves Date: Mon, 26 Oct 2026 20:06:45 -0400 Subject: [PATCH] Prepare the repo for public use: security notes and token hardening The status service now refuses to start with an empty or short display token and compares tokens in constant time. SECURITY.md covers reporting problems as GitHub issues and how to run the service safely. Co-Authored-By: Claude Opus 5.5 --- README.md | 6 +++++- SECURITY.md | 21 +++++++++++++++++++++ service/agent-status.mjs | 8 +++++++- 3 files changed, 33 insertions(+), 2 deletions(-) create mode 100644 SECURITY.md diff --git a/README.md b/README.md index c7be7ce..248ac56 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ You need a Car Thing running bridgething, paired with the bridgething companion ```sh git clone https://github.com/snowopsdev/t3-things && cd t3-things -mkdir -p ~/.config/agent-status +mkdir -p ~/.config/agent-status && chmod 700 ~/.config/agent-status # The token the Car Thing sends. Any long random string works. openssl rand -hex 24 > ~/.config/agent-status/display.token @@ -128,6 +128,10 @@ Built on [bridgething](https://bridgething.com), which makes the Car Thing run w T3 Things isn't affiliated with Spotify, Anthropic, OpenAI, or the makers of T3 Code. Car Thing is a Spotify product, and the device frame in these docs is an original drawing. Claude's usage numbers come from an endpoint Claude Code uses that isn't publicly documented, so that part may break without notice. +## Security + +The service sits next to your Claude, Codex, and T3 Code credentials. See [SECURITY.md](SECURITY.md) for how to run it safely and how to report a problem. + ## License [MIT](LICENSE) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..5df6407 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,21 @@ +# Security + +The status service reads Claude Code's login, Codex session logs, and T3 Code session tokens on your computer, so a hole in it can expose more than this project's own data. + +## Reporting a problem + +Open a [GitHub issue](https://github.com/snowopsdev/t3-things/issues) with the steps to reproduce it. Leave out your own tokens, hostnames, and tailnet name. + +## What's in scope + +- `service/agent-status.mjs`: anything that gets around the bearer token, reads or writes outside what it documents, or leaks a credential into `status.json` or its logs. +- The Car Thing app and its settings page: anything that leaks the service URL or token beyond the device and the companion app. + +Claude, Codex, T3 Code, bridgething, and Tailscale belong to their own projects, so report problems in them there. + +## Running it safely + +- Keep the service on `127.0.0.1` and reach it only through `tailscale serve`. Don't publish it with `tailscale funnel` or open its port to the internet. +- Use a long random display token (`openssl rand -hex 24`). The service won't start with one shorter than 16 characters. +- Give each T3 Code host a session token with only the `orchestration:read` scope. +- Keep `~/.config/agent-status` readable only by you: `chmod 700 ~/.config/agent-status && chmod 600 ~/.config/agent-status/*`. diff --git a/service/agent-status.mjs b/service/agent-status.mjs index 0ea4c31..8ef6969 100644 --- a/service/agent-status.mjs +++ b/service/agent-status.mjs @@ -13,6 +13,7 @@ import { createServer } from 'node:http'; import { execFile } from 'node:child_process'; +import { timingSafeEqual } from 'node:crypto'; import { mkdir, open, readFile, readdir, stat, writeFile } from 'node:fs/promises'; import { homedir } from 'node:os'; import { join } from 'node:path'; @@ -40,6 +41,9 @@ const DEFAULTS = { const config = { ...DEFAULTS, ...(await readJson(join(CONFIG_DIR, 'config.json')).catch(() => ({}))) }; const displayToken = (await readFile(join(CONFIG_DIR, 'display.token'), 'utf8')).trim(); +// an empty token would let any `Authorization: Bearer ` request through. +if (displayToken.length < 16) throw new Error(`${join(CONFIG_DIR, 'display.token')} must hold at least 16 characters`); +const displayTokenBytes = Buffer.from(displayToken); const state = { t3: Object.fromEntries(config.t3Hosts.map(h => [h.name, { ok: false, error: 'not polled yet', threads: [] }])), @@ -493,7 +497,9 @@ function statusDocument() { function authorized(req, url) { const header = req.headers.authorization ?? ''; const given = header.startsWith('Bearer ') ? header.slice(7) : url.searchParams.get('token'); - return given === displayToken; + if (typeof given !== 'string') return false; + const bytes = Buffer.from(given); + return bytes.length === displayTokenBytes.length && timingSafeEqual(bytes, displayTokenBytes); } function handler(req, res) {