diff --git a/.gitignore b/.gitignore index 616f512f..498d9576 100644 --- a/.gitignore +++ b/.gitignore @@ -105,5 +105,7 @@ src/databases/officer_db/migrations/ # deliberate act, so keeping this list by hand is the right amount of friction — an unlisted plugin # directory is an install, not a source file. /plugins/*/ +# `example` is the only exception left, and only until it has a repository of its own. It is the +# reference implementation EXTRACTING-A-PLUGIN.md sends people to read, and it has no remote — the +# platform repo is its single copy, so untracking it would delete it from everywhere but this disk. !/plugins/example/ -!/plugins/offscale/ diff --git a/plugins/offscale/PLUGIN.md b/plugins/offscale/PLUGIN.md deleted file mode 100644 index 969f5d9c..00000000 --- a/plugins/offscale/PLUGIN.md +++ /dev/null @@ -1,733 +0,0 @@ -# Offscale — the first real plugin - -**Status: LIVE DOCUMENT, opened 2026-08-14, offscale extracted 2026-08-15.** Decisions and findings from -the session that built the plugin system. Correct it in place; it is meant to be edited, not archived. - -It lives HERE, in the plugin, rather than in the platform's `docs/`. Most of it is about the plugin -system generally rather than about offscale, and that is deliberate: this is the worked example, and the -reasoning is most useful next to the code it produced. The platform's own docs should not carry the -history of something it no longer knows exists. - -Offscale is Headscale extracted into a plugin. It is the pilot: chosen because it is a genuine vertical -slice (schema + backend router + sidecar + frontend screen + permissions) without being pathological. - -**The name is not a rename.** Offscale is Headscale _plus the Companion_ — an API and UI that ship beside -the Headscale server and add what Headscale itself does not do, the invite flow being the first of them. -Calling it Headscale would undersell it and calling it a fork would be wrong: the server underneath is -stock. The distinct name marks a distinct product, not a badge on someone else's. - -Related, and older: `sidecar-app-store.md` is the origin design and is largely implemented despite its -"Nothing implemented" header. `sidecar-topology.md` is where the runtime shape was going. - ---- - -## The reframe - -**Core is `officer` and nothing else. Everything else is a plugin** — `officer-pty`, `officer-opencode`, -`officer-claude-code`, offscale. `officer-anthropic-proxy` is a known exception to think about later; the -intuition is that it is one plugin requiring two sidecars. - -The old baseline was six PM2 processes. Headscale was removed from it on 2026-08-14 (`services.sh`, -the local ecosystem file, `catalogue.test.ts`'s `CORE[]` mirror, and PM2 itself), so the machine this was -written on runs five. - -### Two words, because "core" was doing two jobs - -- **baseline** — what a fresh install actually runs -- **first-party** — what Officer Dev publishes - -They come apart immediately: offscale is first-party and no longer baseline. Saying "core" for both makes -"is X core?" a question with two answers. - ---- - -## What a plugin is made of - -Combined per plugin as needed. **Only `meta` and the ID are always required.** - -- a **meta** object — id, name, dock item, backend/frontend mount, etc. -- an **ID** (see below) -- a **sidecar** -- a **backend router** and its routes -- a **db schema** -- **default permissions per user group** -- what it stores in the **secret store**, and whether that is per-user or plugin-global -- a **frontend router**, its routes, and the frontend code -- how it **mounts into the file browser context menu** -- a set of **permissions added to officer-items** -- **plugin settings page** definitions -- an accompanying **mobile app** - -A plugin is completely self-contained. The platform's installed/enabled state decides whether its routers -mount, whether its sidecar is in the ecosystem file, and so on. - -### What offscale needs - -db schema · backend router + routes · frontend router + routes · sidecar. - -**Not** a context menu, **not** officer-items permissions, and (probably) **not** a settings page. - ---- - -## Identity and routing - -**The app-name is the ID.** One identifier, not two — it names the plugin, prefixes its tables, and is its -route. A random ID plus a separate app-name was considered and dropped: splitting the uniqueness guarantee -across two namespaces means whichever is weaker becomes the real attack surface. - -**Uniqueness comes from two mechanisms**, because one is not enough: - -- **globally** — the marketplace owns the namespace for published names, with human review. A name as - generic as `notes` gets refused: it is a name Officer Dev may want later. -- **locally** — the platform refuses to install a plugin whose app-name is already taken on this machine. - Needed because a private plugin never asks the marketplace anything. - -The marketplace works like the Chrome extension store. Anyone may write plugins for their own use with no -restrictions; publishing is what invites review. - -### Mount prefixes - -``` -first-party /api/ e.g. /api/offscale -third-party /api/p// e.g. /api/p/alice/notes -``` - -`p` is a literal segment meaning "plugin". First-party plugins sit at the root because Officer Dev owns -that namespace anyway, and because provenance is then legible at a glance in a log or a route table. - -**The prefix must be derived by exactly one function from the manifest.** Nothing about a first-party -plugin's code may know it is first-party. If that difference ever leaks past the one derivation — a -special case in the router, a bypassed check, a different install branch — first-party and third-party -become two systems, and only one of them gets tested. - -`/p/` does **not** solve plugin-vs-plugin collisions; the marketplace and the local check do. What it -guarantees is that a plugin can never shadow a **core** route, which also means the platform can keep -adding core routes forever without breaking installs. - ---- - -## The database - -**Tables live in `public`, prefixed with the app-name** — `offscale_servers`, exactly as the codebase -already does (`headscale_servers`, `music_favorites`, `vault_tokens`). No new machinery. - -### A Postgres schema per plugin was tested and rejected - -Not rejected on suspicion — it was built and proven to work, then dropped as more complexity than it -earns. Recorded so nobody re-runs the experiment: - -| Property | Result | -| ----------------------------------------------------------------- | ------------------------- | -| `pgSchema('offscale')` + `drizzle-kit push` creates the namespace | works | -| Cross-schema FK to `public.users` | works | -| Partial unique index preserved | works | -| Push is idempotent, no spurious re-creation | works | -| Cascade delete across the schema boundary | works | -| `DROP SCHEMA offscale CASCADE` as uninstall | works, `public` untouched | - -**The finding worth keeping: `schemaFilter` is mandatory, and the docs are wrong.** Drizzle's config -documentation states that push "will by default manage all schemas". On drizzle-kit **0.31.8** that is -false. A push with the table verifiably exported reported `No changes detected` and created nothing; -naming the schema in `schemaFilter` made the identical push work. - -If per-plugin schemas are ever revisited, that is the trap: **a plugin install would report success and -silently create no tables.** Same failure shape as several bugs found the same day — a refusal wearing the -costume of a normal result. - ---- - -## Mounting — rebuild and swap, at runtime - -**Runtime mounting, no restart.** This went round twice — C, then B on the belief that Hono could not -mount at runtime, then back — so the reasoning is recorded rather than the conclusion alone. - -### What was actually tested - -| Router | `app.route()` after serving has begun | -| -------------------------------- | --------------------------------------------------------------------- | -| `SmartRouter` _(Hono's default)_ | **throws** — `Can not add a route since the matcher is already built` | -| `RegExpRouter` | **throws**, same reason | -| `TrieRouter` | works | -| `PatternRouter` | works | - -So adding at runtime is possible, but only by giving up the fast matcher — and Hono has **no API to -remove a route**, which uninstall needs. - -### The approach that solves both - -Rebuild the whole app from the current plugin set and **reassign the variable**: - -```ts -let app = buildApp(installedPlugins()); // core routes + one .route() per plugin -serve({ fetch: (req, server) => app.fetch(req, server) }); // closure, NOT app.fetch - -// install: app = buildApp([...installed, 'offscale']) -// uninstall: app = buildApp(installed.filter(p => p !== 'offscale')) -``` - -The `fetch` closure reads `app` on every request, so reassigning it **is** the swap. Verified end to end: - -``` -no plugins /offscale/x -> 404 | /core -> 200 -installed /offscale/x -> 200 | /core -> 200 -uninstalled /offscale/x -> 404 | /core -> 200 -``` - -Better than the TrieRouter route on both counts: the default `SmartRouter` is kept, so the fast -`RegExpRouter` path survives — and **uninstall works**, which an add-only API cannot express. - -### The one line that has to change - -`server.tsx:322` is `'/api/*': honoServer.fetch` — a **bound method**, evaluated once at `serve()`. It has -to become `(req, server) => honoServer.fetch(req, server)`, or reassigning the app has no effect at all. -This is the whole mechanical cost. - -### Websockets are a separate table, and they reload - -Six providers are declared in **Bun's route table**, not Hono's: `/api/tasks/run/ws`, -`/api/tasks/pipeline/ws`, `/api/terminal/ws`, `/api/chat/ws`, `/api/cliamp/ws`, `/api/cliamp/audio/ws`. -The Hono swap does not reach them — but `server.reload({ routes })` does, in both directions: - -``` -before reload /api/offscale/ws -> refused | /core -> 200 -after reload /api/offscale/ws -> CONNECTED | /core -> 200 -after remove /api/offscale/ws -> refused | /core -> 200 -``` - -So **nothing needs a restart, for either table.** A plugin owning a socket is possible from the start. -`reload` wants the whole option set, so `fetch` is passed alongside `routes`. - -`[open]` Whether connections already open across a `reload` survive it was not tested. Worth knowing -before a plugin install can interrupt somebody's terminal. - -The two tables remain two lists, which is the same seam as the totality bug below. - -### What this means for `assertPermissionTotality` - -It can no longer be only a boot check, because the mount set changes after boot. The question moves to -**per rebuild**: `buildApp()` is the one place routes are mounted, so it is the one place to assert that -every mounted route has a permission — and to refuse the swap if one does not. Same invariant, asserted -where mounting actually happens instead of once at start-up. - -Two things it must survive, both live today: - -- The premise in `sidecar-app-store.md` that "every API route stays mounted regardless" is **retired**. An - uninstalled plugin's routes are not mounted, so nothing can reach them. -- The check is currently **fed the wrong list** — `Object.keys(handlers)` from `server.tsx`, while Bun - serves the _route table_, and the two diverged when plugins were switched off. Moving the assertion into - `buildApp()` fixes this by construction for Hono routes, and leaves the websocket table as the part that - still needs pointing at reality. - ---- - -## Permissions - -A plugin declares permissions. **A plugin may declare `app`, and nothing else.** - -`PermissionKind` is `core | app | confined | execution | admin`. `core` means _every account, not -deniable_, so a third-party manifest naming its own kind is a privilege-escalation surface: "malicious -plugin declares itself core" is an ungated grant to every user. `core`, `execution` and `admin` stay the -platform's to assign. - -### The platform grants read or write. Everything richer is the plugin's own job - -The platform's contract is exactly what it already has and no more: **a role holds `read` or `write` on a -permission**, stored in `role_permissions`, enforced by the gate. `read` permits safe methods anywhere in -the surface; `write` permits everything. - -Anything beyond that — who may see whose rows, per-user isolation, ownership of individual records, -visibility rules of any kind — is **implemented inside the plugin**, by the plugin's author. It is not the -platform's responsibility and the platform should not grow machinery for it. A plugin knows what its data -means; the platform only knows whether this account got through the door. - -### Offscale v1 uses that model exactly, with nothing added - -One shared resource, role-gated: - -- **read** — sees what the owner sees: the owner's registered servers, nodes, users, keys, policy -- **write** — can change them, including deleting a server the owner registered - -The second is genuinely dangerous, and deliberately allowed. The stored credential is a Headscale **admin** -key that can delete every node on a tailnet, and there is no read-only version of it. So `write` on -offscale is close to full control of the tailnet — which is the owner's decision to make, and the expected -use is read for most roles. Say Developers get `read` and nobody gets `write`. - -Two implementation consequences, both inside the plugin: - -1. **The queries stop scoping by the caller.** Every one takes the caller's `userId` today — - `listHeadscaleServers(userId)`, `getActiveHeadscaleCredentials(userId)` — and the schema is per-user - because of it. Under this model a member sees the **owner's** rows, so those resolve to the owner's id - always. The per-user shape stays in the table, unused, and becomes the seam if isolation is ever wanted. - -2. **Two POSTs are really reads, and must be declared `readOnlyWrites`:** - - `POST /ssh-test` — a reachability probe that mutates nothing - - `POST /policy/assist` — proposes a document and, emphatically, never saves one - - Without them a read-level account cannot test a connection or draft a policy, which reads as a broken - feature rather than a withheld permission. Everything else — activate, rename, tags, routes, expire, - delete, policy `PUT` — is a genuine write. - -### Music is where the richer model gets designed - -Offscale is deliberately the simple case. **The next plugin extracted is most likely music, and that is -the right place to develop the in-plugin visibility system** — it has genuinely per-user data (favourites, -playlists, now-playing) sitting on top of a genuinely shared one (a single global library index, noted in -`TODO.md` as one household, one library). So "whose is this row" has a real and non-uniform answer there, -where offscale's is just "the owner's". - -Not designed yet, and deliberately not designed here. Recorded so the intent survives. - -### Several different things were called "capability" here - -A manifest needs three names, not one: - -1. `permissions/registry.ts` — **permissions** (`headscale`, `vpn`) -2. `$OFFICER_ROOT/capabilities/` — the **file-based item store** (skills, tools, tasks) -3. `sidecar-registry` `handles: ['music']` — **routing keys** for `sendCommand`, renamed from - `capabilities` on 2026-08-15 - -Offscale needs (1) and (3), and not (2). - ---- - -## Secrets - -Two stores, and a plugin author will reach for the wrong one unless told: - -- **plugin-global keys** → the secret store (`officer_db/src/secret-store.ts`, real: `getKey(purpose)`, - `hasKey`, `retiredKeys`). Purpose-keyed encryption and signing keys, not arbitrary values. -- **per-user credentials** → `service_connections`, which already does the hard part: the row is keyed - `(userId, service)` and **a NULL `url` means "inherit the instance"**, so a member structurally cannot - see or supply the URL. `service` is free text with no namespacing yet — that needs solving before third - parties touch it. - -Offscale's own coupling is small and instructive. `headscale/queries.ts` imports exactly two things from -the host: - -```ts -import { db } from '../db'; // the connection -import { encryptSecret, decryptSecret } from '../crypto'; // at-rest encryption, 10 uses -``` - -A plugin cannot carry its own `db` (it must share the connection to reference `users.id`) and should not -carry its own crypto (the key lives in the platform's store). **So those two are provided to a plugin -rather than imported by it.** That is the first concrete piece of the plugin↔host API, and it fell out of -the pilot rather than being invented. - ---- - -## `/api/vpn` is being deleted - -Officer had two headscale surfaces: - -| | `/api/vpn` | `/api/headscale` | -| ---------- | ---------------------------------------- | -------------------------------------- | -| permission | `vpn`, kind `app` — grantable to members | `headscale`, kind `admin` — owner only | -| purpose | enrol your own device | the tailnet: machines, routes, ACLs | -| surface | one route, `POST /enroll` | the whole admin API | - -`POST /api/vpn/enroll` was one-tap enrollment for a phone already signed into Officer. **It has no caller -anywhere.** Verified against the mobile monorepo: - -1. `enrollVpn()` has one call site, `useVpnScreen.ts:617`, inside `enroll()` -2. `enroll()` is reached only via `if (embedded) await enroll()` -3. `embedded` is optional and defaults to `false` -4. `VpnScreen` is rendered in exactly one place — `apps/offscale/src/App.tsx` — which never passes it - -`apps/mobile` and `apps/headscale` have zero references to `enrollVpn`, `VpnScreen` or `api/vpn`. Neither -does the Officer web app. The live database holds no `vpn` grants. - -**And it will never come back.** Offscale is permanently standalone: no login, no backend calls, no -dependency on Officer or the platform. The reasoning is the app's own and it is sound — _the thing that -gets you to the platform cannot itself need the platform_, or a broken tailnet locks you out of both. - -### Everything collapses to one namespace - -`/api/offscale/*`. The comment in `vpn/router.ts` claiming "the path is a contract" no longer binds: the -contract has no counterparty. - -**The invite flow stays and does not need the mobile app changed.** `claimInvite` calls -`${invite.base}/api/v1/enroll/claim` — the **Companion** on the server, at a base URL carried in the -invite link. `/api/v1/` is Headscale's own namespace. The phone never talks to Officer for invites. - -- **phone → Companion** — untouched by anything here -- **web admin → Officer → sidecar** — ours to rename freely - -### There are THREE components, not two - -Easy to miss, and worth stating because two of them contain the word "enroll": - -| Component | Repo | Enrolment surface | -| ---------------- | ---------------------------- | ------------------------------------------------ | -| Officer platform | `officerdev/platform` | `/api/offscale/*` — web admin only | -| Mobile suite | `officerdev/monorepo-mobile` | calls the Companion, never Officer | -| **Companion** | `officerdev/offscale-server` | `/api/v1/enroll/*` under basePath `/officer-api` | - -The Companion ships beside each Headscale server. Confirmed against its source on 2026-08-14: zero -references to `/api/vpn/*`, and its only outbound calls are the docker socket and its sibling headscale's -`/health`. It never calls Officer and does not use `/api/offscale/*` either. - -**`/api/v1/enroll/*` is the Companion's and is not ours to collapse.** The phone claims at -`${invite.base}/api/v1/enroll/claim`, where `invite.base` is the `sidecarOrigin` the Companion itself put -in the invite (`https:///officer-api`). - -**Trap when deleting:** do not delete the sidecar's `enroll.ts`. Line 71 dispatches -`/enroll/invites` to `handleInvitesRoute`, so it is the invite flow's entry point. Only the bare -`POST /_officer/enroll` handler below it is dead. - -**A public route is possible if ever needed.** `/api/vault` is already exempt from platform auth -(`EXEMPT_API_PREFIXES`) because Bitwarden clients carry a Vaultwarden bearer rather than a platform JWT. -The exemption must be declared with a reason or the boot check refuses. Not needed today. - -**Not an open question — decided.** Removing `vpn` leaves no member-grantable headscale surface, and that -is correct. The invite flow supersedes it completely: - -1. the Officer headscale app holds an admin API key for the Headscale server -2. from it the owner mints an **invite** — a URL pointing at the Companion -3. the Companion turns that into the redirect the phone app claims -4. the device joins - -That path needs no per-member permission on Officer at all, and it is the one that exists and works. -`/api/vpn/enroll` was the design it replaced, not a permission still waiting for a UI — there never was -one. Do not reintroduce a member-facing enrolment route on the assumption something is missing. - ---- - -## What headscale actually is — the inventory - -Read end to end on 2026-08-14. This is what has to move. - -### Backend — 2,406 lines - -`/api/headscale` is **18 lines**: a pure `createSidecarProxy`, no Headscale knowledge, "must never grow app -logic". Everything is in the sidecar under `/_officer/*`, dispatched by `routes.ts` to eight handlers — -`servers · nodes · users · keys · policy · enroll · ssh-test · companion`. - -Three things worth knowing before touching it: - -- **Every domain route acts on the _active_ server**, stored in Postgres behind a partial unique index and - never passed as a parameter — so no client can act on a server the owner is not currently looking at. -- **`client.ts` is a quirk-absorption layer, and that is the good part.** The quirks are Headscale's: - uint64 ids arrive as JSON _strings_ (never round-trip through `Number` — it breaks above 2^53), 401/403 - bodies are plain text while every other error is JSON, and the gateway uses `DiscardUnknown` so a - misspelled request field makes the call **succeed and do nothing** — which is why mutations read the - object back. One file containing all of it is the model for a plugin's client layer, not something to - undo. -- **The Companion is optional per server** and answers `{available:false, reason}` at HTTP 200. The trick - is distinguishing nginx's HTML 502 (no companion) from the companion's JSON 502 (docker op failed): it - branches on whether the body parses. - -Host dependencies: `officerdb` (db + crypto), `DATA_PATH`, `officer-url.mjs`, `createSidecarConnector`, -`createSidecarProxy`, the anthropic proxy's state file, and the `ssh` binary. - -### Frontend — 29 files, 27 endpoints - -Three registered panels (`headscale-servers`, `headscale-nav`, `headscale-view`, all -`availableOnPanel: false`) inside a locked `WorkspaceView`, with `headscale-view` dispatching on -`useHeadscaleSection()` to eight section views: Servers · Nodes · Users · Keys · Invites · Policy · -Diagnostics · Console. - -It **follows the navigation conventions** — no `usePanelChannel` anywhere, no opaque clicks, the section -lives in `:section` and nowhere else. The one exception is documented and correct: choosing the active -server is a DB write that re-scopes every query, so it stays a button rather than a URL. - -The whole frontend↔host coupling, which becomes the plugin API: - -| Import | Why it matters | -| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `hooks/useClient` → `useClient`, `getHeaders` | both, not just the client — `useCompanionLogStream` needs raw headers because `EventSource` cannot send `Authorization` | -| `helpers/clipboard` → `copyToClipboard` | carries the non-secure-context fallback; re-implementing it would silently regress | -| `AppRegistryMeta` | the panel-contribution contract | -| `officerdev` → `WorkspaceView`, `LayoutNode` | needs `appTypes: {allowed, fallback}` and `locked` | -| `state/useDashboardState` | per-user layout, backed by `/api/dashboards`, a `core` permission — stays host-provided | -| `../Terminal/Terminal` → `TerminalView` | **the awkward one** — a code dependency on another panel app | - -### `assist.ts` travels, but stays unwired - -The ACL-drafting assistant was written and never tested. **Carry it into the plugin, do not delete it, and -do not wire it up** — it is there as a marker that the idea exists, to be finished or removed deliberately -later. Do not tidy it away as unused code. - ---- - -## The manifest — proposal - -Written against offscale rather than invented in the abstract, on the principle that a field list designed -from nothing includes what nothing needs and misses what is awkward. The field set grows per plugin; this -is the floor, not the ceiling. - -```ts -// plugins/offscale/manifest.ts -export const manifest = { - /** Constant today. The one input to `mountPrefix()`, and the seam third parties hang off later. */ - publisher: 'officerdev', - /** The plugin's own semver. Updates compare against this. */ - version: '1.0.0', - /** Which platforms this build is good for. Refused at install when it does not match. */ - platform: '>=1.0.0 <2.0.0', - - label: 'Offscale', - summary: 'Your tailnet — machines, users, pre-auth keys and access policy', - icon: 'Network', - color: '#818cf8', - - // Named `permissions`, NOT `capabilities`. That word meant several different things here — the - // permission registry, the officer-items store, and the sidecar's routing keys — and a fourth would be - // one too many. `permissions` is accurate and free: the old table of that name went in 044aacf4. - permissions: [ - { - key: 'offscale', - label: 'Offscale', - description: 'The tailnet: machines, routes and ACLs', - /** Owner-only, or grantable to members. The whole distinction a plugin needs. */ - ownerOnly: true, - }, - ], -} as const; -``` - -### THE RULE: every plugin route renders a Workspace with at least one panel - -Exclusionary, and enforced by shape rather than by review. A plugin **does not render a screen.** It -contributes panels and says how they are arranged; the shell renders `WorkspaceView` around them. - -``` -web/panels.ts exports appRegistryMetas — at least one panel -web/layout.ts exports defaultLayout — how they are arranged -``` - -Both are required the moment `web/` exists. Missing either and the plugin is **refused at discovery**, by -name and with the reason: - -``` -probeplug: has a web/ directory but is missing web/layout.ts. -Every plugin route renders a Workspace: contribute panels and a layout, not a screen. -``` - -There is deliberately no way to export a component. A plugin that could would be free to render a bare -div, a full-page form, its own navigation — and the platform would become a shell hosting strangers' -layouts rather than one application. Non-compliance is not refused so much as **unrepresentable**: there -is nowhere to put a screen. - -The shell registers the pair `` and `/:section`, exactly as the core screens do -(`/headscale/:section`), so a plugin's sections stay addressable, linkable and cmd-clickable. Panels read -`useParams` independently — nothing is passed between them, so they cannot disagree. `appTypes.allowed` -is pinned to that plugin's own panel keys, so a persisted layout naming something else falls back rather -than rendering another plugin's panel inside this one. - -### Everything the tree can say, the tree says - -The manifest holds only what a directory listing genuinely cannot tell you: an identity fact, or something -a human chose. Everything structural is convention, and **presence is the declaration**: - -| Path | Means | -| -------------------- | --------------------------------------------------------------------------------------------- | -| _the directory name_ | `appName` — `plugins/offscale/` **is** the id, so it cannot disagree with where the code sits | -| `sidecar/index.ts` | there is a sidecar; PM2 gets an entry. `.mjs` instead means node — see below | -| `api/router.ts` | there is a backend router, mounted at `mountPrefix(manifest)` | -| `db/schema.ts` | there are tables; pushed on install, every name prefixed `offscale_` | -| `web/Router.tsx` | there is a frontend; its default export mounts at `/*` | -| `web/panels.ts` | it contributes panels; exports `appRegistryMetas` | - -The dock tile and the page title need no fields either — the tile is `{ label, icon, color, to: -mountPrefix(manifest) }` and the title is `label`, all of which are already above. Writing them again was -duplication that could only ever drift. - -**The runtime is the file extension.** `sidecar/index.mjs` runs under node, `sidecar/index.ts` under bun. -Implicit, but it is the rule this repo already follows — `officer-pty` is `pty/index.mjs` under node -because node-pty is a native module built against Node's ABI, and everything else is bun. Better than a -field that can contradict the file it describes. - -### Install asks nothing, and that is the default - -Offscale needs **none** of the install fields the current app-store catalogue carries — no `modes`, no -`existingFields`, no `configFields`, no `composeTemplate`, no `members`. There is no Docker to provision -and no external service to point at. - -Its install is the whole of it: put the code there, push the schema, start the sidecar, swap the routes. -Available immediately. Everything else is configuration the user does **afterwards, inside the app** — a -Headscale server is registered at `/offscale/servers` and lands in `offscale_servers`, which is already -how it works today. - -So the rule is **a plugin installs with no questions unless it says otherwise**, and the prompting -machinery (the three install shapes in `sidecar-app-store.md`) gets designed against the first extracted -plugin that actually needs Docker or a remote instance. That was part of why offscale is the right pilot: -it exercises the mounting, the schema and the sidecar without the install flow being a variable too. - -### Dropped from the first draft - -- **`dependsOn`** — nothing read it and nothing enforced it. Both of offscale's dependencies already - explain themselves where it matters (`assistant_unavailable`; "no SSH host configured"). A field whose - only job is to be displayed, that nothing displays, is stale the first time anyone looks at it. Add it - when something consumes it. -- **`kind`** — see below. -- **`sidecar` / `schema` / `frontend` objects** — all convention now. - -`[open]` A plugin with a frontend that should NOT get a dock tile has no way to say so: `web/` present -means a tile. Fine for offscale; add a flag the first time something needs it. - -### `admin` has to be allowed, and the pilot proved it immediately - -The earlier rule here was "a plugin may declare `app`, and nothing else". **That is wrong, and offscale is -the counterexample**: its permission is `kind: 'admin'` — owner-only — and it should stay that way. - -The distinction is direction. `core` means _every account, undeniable_, so a plugin claiming it grants -itself to everyone: escalation. `admin` means _owner only_, which is a plugin **restricting** itself, and -nothing is gained by forbidding it. - -Corrected rule: - -| Kind | May a plugin declare it? | Why | -| ----------- | ------------------------ | ---------------------------------------------------------- | -| `app` | yes | the ordinary grantable surface | -| `admin` | yes | self-restriction, never an escalation | -| `core` | **no** | every account, not deniable — an ungated grant to everyone | -| `execution` | **no** | runs as the owner's OS user; the platform's to assign | -| `confined` | **no** | implies a Linux identity the platform provisions | - -### One function decides the prefix - -`publisher` is the only input, so first-party and third-party cannot become two code paths: - -```ts -const mountPrefix = (m: Manifest) => - m.publisher === 'officerdev' ? `/${m.appName}` : `/p/${m.publisher}/${m.appName}`; -``` - -Used for both `/api/...` and the frontend route. Nothing else in the codebase may branch on provenance. - -### Notes on the fields - -- **`sidecar.runtime`** exists because `officer-pty` runs under node for node-pty's native ABI while - everything else is bun. One plugin already needs it, so it is not speculative generality. -- **`platform`** is the compat range, and it presumes the platform gains a version. It has none today; - 1.0 is expected before anyone outside Officer Dev writes a plugin. -- **`dependsOn`** is deliberately not enforced. Code dependencies need no declaration — a plugin builds - inside the workspace, so `import { TerminalView }` simply resolves — and service dependencies already - degrade. This is for the human reading the store. -- **No `health`.** Deferred; process-online is what the store knows and that is enough for now. -- **No `migrations`.** Deferred; a field can be added without redesign. -- **No permission list.** A plugin calls the API with the user's token and the user's permissions. - ---- - -## What is built — complete, as of 2026-08-15 - -**Offscale is a plugin, and nothing in the system is a stub.** Validated by the owner against the live -server across repeated install / enable / disable / uninstall cycles, checking PM2 and the frontend each -time. - -| Piece | Where | -| --------------------------------------- | -------------------------------------------------- | -| Manifest, `mountPrefix`, validation | `servers/plugins/manifest.ts` | -| Discovery by convention | `servers/plugins/discover.ts` | -| Disk ⋈ database, mounts, dock manifests | `servers/plugins/mount.ts` | -| Install runner, four verbs, streamed | `servers/plugins/install.ts` | -| PM2 ecosystem entry | `servers/plugins/ecosystem.ts` | -| Schema barrel + `db:push` | `servers/plugins/schema.ts` | -| `Plugins.gen.tsx` + `Bun.build` | `servers/plugins/generate.ts` | -| `buildHonoApp` / `rebuildHonoApp` | `servers/hono.ts` | -| Permission registration | `permissions/registry.ts` → `setPluginPermissions` | -| Install state | `plugin_installs` | -| The screen | `/plugins`, two panels, SSE log | -| The reference plugin | `plugins/example/` | -| **The first real plugin** | `plugins/offscale/` — 45 files | - -Nothing needs a restart. Routes swap by rebuilding the Hono app, the sidecar gets a PM2 entry, the -frontend is regenerated and rebuilt in ~3s, permissions are registered before routes mount, and the -whole thing survives a restart because boot regenerates and mounts before `serve()`. - -### Three bugs the extraction found - -Worth recording because none were visible from reading: - -1. **Install started the sidecar before mounting.** `createSidecarProxy` learns its port from a one-shot - `:server` event and subscribes when the plugin's router is first imported — at mount. So the - announcement fired into a void: process online, routes mounted, every request `503 sidecar not -available`. It would have hit every plugin with an HTTP sidecar; `example` never caught it because it - has no listener to announce. Install and enable now mount first. -2. **The built SPA had no Tailwind.** `bunfig.toml` declares the plugin under `[serve.static]`, which - applies to Bun's static serving and not to a programmatic `Bun.build()`. -3. **The build could destroy itself.** Clearing `build/` before building meant a failed build left - nothing, and two overlapping builds could delete each other's shell. It now stages and swaps. - -### Still open - -- **Websocket providers.** `server.reload({ routes })` is proven but not called; Bun's route table is - still the hardcoded providers. No plugin owns a socket yet. -- **Totality across plugin routes.** `PROTECTED_API_PREFIXES` is still the core list, and the check reads - `Object.keys(handlers)` while Bun serves the route table. The assertion wants moving into - `buildHonoApp`, which is now the single place routes are mounted. -- **Two dock sources.** The app store keeps its own catalogue, so tiles come from there and from the - plugin system. One when the app store is rebuilt on this. -- **Members.** Offscale is `ownerOnly` — read/write for members needs its queries resolving to the - OWNER's rows rather than the caller's, which is a change inside the plugin. - ---- - -## The state of the app store, as found - -It **is** the plugin system, roughly 90% built, with one structural hole. - -`ecosystem.config.cjs` is generated once at setup and **nothing appends to it on install**, so the -installer's final step runs `pm2 start ecosystem.config.cjs --only officer-jellyfin`, matches no app, and -silently does nothing. Acknowledged in `app-store/pm2.ts:23-29`: - -> _"Installing a plugin has to append its entry here before starting it — that is the plugin system's job -> and it is not built."_ - -Net: **nothing in the catalogue installs end-to-end today.** Containers come up, `service_connections` is -written, assets publish, the dock tile appears — and the sidecar never starts. - -Also found: - -- The `schema` install step is a **logged no-op** (`effects.ts:117-124`). Every table still ships via - `bun db:push`. -- Of 8 entries declaring a compose template, **only 2 exist on disk** (`transmission`, `vaultwarden`). - `slskd` has an icon and nothing else. `catalogue.test.ts` asserts a template _name_ is declared but never - that the directory exists. -- `hono.ts` has **28 routers mounted and 15 commented out**; `officer_db/src/schema.ts` has **11 commented - schema exports** under "uncomment when the plugin is installed". Today, installing a plugin literally - means editing two files and rebuilding. -- `catalogue.test.ts` asserts every entry's process has a matching `src/servers/sidecar/`. A plugin in - its own repository has no such directory, so that test inverts — as `sidecar-app-store.md` predicted. -- A **dead, unrelated** plugin system still exists: `GET /server-settings/plugins` scans - `src/workspaces/plugins/`, which does not exist, so it always returns `[]`. `PluginsSection.tsx` still - renders against it. Not to be confused with any of the above. - ---- - -## Where the code lives - -`plugins/offscale` on `gitea.officer.dev` — private, default branch `main`, topic `officer-plugin`. - -The `plugins` org exists because Gitea has **no nested organizations** (verified: no `parent` field on the -org object), so `/` is the only real namespace it has. Topics work and are searchable, and are -used in addition rather than instead — they span orgs, which matters because browser extensions under -`extensions/` may become plugins later. - ---- - -## Open questions - -1. ~~**Frontend code is the hard one.**~~ **Answered** — see "How the frontend ships". Build to `build/`, - rebuild on install, one generated `Plugins.tsx`, same origin. No federation, no import maps, no iframe: - everything compiles together and a plugin changes what "everything" is. The developer builds inside a - platform checkout, so dev-time and build-time are the same mechanism. -2. **Migrations and versioning.** A plugin needs a version and a platform-compatibility range, and - something has to apply schema changes over time. Cheap now, miserable to retrofit. -3. ~~**Health, distinct from enabled.**~~ **Deferred, deliberately.** A sidecar can be online while the - thing it exists to talk to is unreachable — offscale's own `/servers/:id/health` is exactly that - question. But process-online covers the common failure, every plugin that needs more surfaces it in its - own UI, and this is a manifest field that can be added later without redesign. Revisit in a distant - future, not before. -4. ~~**No inter-plugin dependencies.**~~ **Overtaken by evidence.** That measurement was of _schemas_ and is - still true there; at runtime the pilot has two — `assist` → anthropic-proxy (service) and `ConsoleView` - → `TerminalView` (code). The rule became "may depend, must degrade" — see "Dependencies between - plugins". What is still open is the **code** kind: either `TerminalView` becomes host API, or the - Console section does not travel with the plugin. -5. **`service_connections.service` namespacing** before third parties touch it. -6. **`officer-anthropic-proxy`** — one plugin, two sidecars. -7. **Gitea is installed but invisible.** Containers `gitea` and `gitea-postgres` run, `officer-gitea` is - not in PM2, and there is no `sidecar_installs` row — it predates the store. "Already there, but not by - us" needs an answer, and the store deliberately refuses to adopt directories it did not create. diff --git a/plugins/offscale/api/router.ts b/plugins/offscale/api/router.ts deleted file mode 100644 index 3d3a09a3..00000000 --- a/plugins/offscale/api/router.ts +++ /dev/null @@ -1,18 +0,0 @@ -import { createSidecarProxy } from '@@/sidecar/create-proxy'; - -// /api/headscale/* — auth, then forward to officer-headscale. No routes of its own and no headscale knowledge: -// this file must never grow app logic. -// -// The sidecar exposes only Officer-owned routes under `/_officer/` — Headscale's REST shape differs -// across releases, and version handling belongs in the sidecar. It holds the admin API key; the platform -// does not know Headscale's URL. - -const proxy = createSidecarProxy({ - name: 'headscale', - prefix: '/api/offscale', -}); - -export const router = proxy.router; - -/** Base URL of the sidecar's HTTP server, or null if it hasn't reported in yet. */ -export const getHeadscaleServerUrl = proxy.getHttpUrl; diff --git a/plugins/offscale/db/queries.ts b/plugins/offscale/db/queries.ts deleted file mode 100644 index ba3b1558..00000000 --- a/plugins/offscale/db/queries.ts +++ /dev/null @@ -1,186 +0,0 @@ -import { eq, and, desc } from 'drizzle-orm'; -import { db } from 'officerdb/db'; -import { headscaleServers } from './schema'; -import { encryptSecret, decryptSecret } from 'officerdb/crypto'; - -// Headscale server registry access for the officer-headscale sidecar. Callers deal in PLAINTEXT — -// encryption to/from at-rest ciphertext happens here, so the sidecar's route handlers never touch crypto. -// See ../crypto.ts and ../schema/headscale.ts. -// -// Two return types on purpose: -// HeadscaleServer — safe to serialize to the browser. Has NO api key field at all. -// HeadscaleServerCredentials — url + decrypted key, for the sidecar's own upstream calls. Never returned -// by a route handler. -// The `serverCols` projection is what enforces that: `select()` without it would leak the ciphertext column -// into every list response the moment someone forgot to strip it. - -export type HeadscaleServer = { - id: number; - name: string; - url: string; - version: string | null; - sshHost: string | null; - isActive: boolean; - lastSeenAt: Date | null; - createdAt: Date; -}; - -export type HeadscaleServerCredentials = { id: number; name: string; url: string; apiKey: string }; - -const serverCols = { - id: headscaleServers.id, - name: headscaleServers.name, - url: headscaleServers.url, - version: headscaleServers.version, - sshHost: headscaleServers.sshHost, - isActive: headscaleServers.isActive, - lastSeenAt: headscaleServers.lastSeenAt, - createdAt: headscaleServers.createdAt, -}; - -/** Every server the owner has registered, active first then newest. Never includes the API key. */ -export async function listHeadscaleServers(userId: number): Promise { - return db - .select(serverCols) - .from(headscaleServers) - .where(eq(headscaleServers.userId, userId)) - .orderBy(desc(headscaleServers.isActive), desc(headscaleServers.createdAt)); -} - -/** The currently selected server with its key decrypted, or null when none is registered/active. */ -export async function getActiveHeadscaleCredentials(userId: number): Promise { - const [row] = await db - .select() - .from(headscaleServers) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.isActive, true))); - if (!row) return null; - return { id: row.id, name: row.name, url: row.url, apiKey: decryptSecret('headscale', row.apiKey) }; -} - -/** One server's credentials by id — for probing a specific server rather than the active one. */ -export async function getHeadscaleCredentials(userId: number, id: number): Promise { - const [row] = await db - .select() - .from(headscaleServers) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.id, id))); - if (!row) return null; - return { id: row.id, name: row.name, url: row.url, apiKey: decryptSecret('headscale', row.apiKey) }; -} - -type CreateHeadscaleServerParams = { - userId: number; - name: string; - url: string; - apiKey: string; - version: string | null; - /** Optional SSH target for the console. Null when the owner hasn't set one. */ - sshHost: string | null; - /** Make it the active server. True for the first registration, so the UI is never left with none selected. */ - activate: boolean; -}; - -/** Register a server. The key is encrypted before write; the returned row carries no key. */ -export async function createHeadscaleServer(params: CreateHeadscaleServerParams): Promise { - const { userId, name, url, apiKey, version, sshHost, activate } = params; - return db.transaction(async (tx) => { - if (activate) { - await tx - .update(headscaleServers) - .set({ isActive: false, updatedAt: new Date() }) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.isActive, true))); - } - const [row] = await tx - .insert(headscaleServers) - .values({ - userId, - name, - url, - apiKey: encryptSecret('headscale', apiKey), - version, - sshHost, - isActive: activate, - lastSeenAt: version ? new Date() : null, - }) - .returning(serverCols); - return row!; - }); -} - -// `sshHost: null` clears the console target; omitting the field leaves it alone. The two must stay -// distinguishable, which is why this is `string | null` and not `string`. -type UpdateHeadscaleServerParams = { name?: string; url?: string; apiKey?: string; sshHost?: string | null }; - -/** Edit a registration. Omitted fields are left alone; a supplied key is re-encrypted. */ -export async function updateHeadscaleServer( - userId: number, - id: number, - params: UpdateHeadscaleServerParams, -): Promise { - const set: Record = { updatedAt: new Date() }; - if (params.name !== undefined) set.name = params.name; - if (params.url !== undefined) set.url = params.url; - if (params.apiKey !== undefined) set.apiKey = encryptSecret('headscale', params.apiKey); - if (params.sshHost !== undefined) set.sshHost = params.sshHost; - - const [row] = await db - .update(headscaleServers) - .set(set) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.id, id))) - .returning(serverCols); - return row ?? null; -} - -/** Select a server. Clearing the others first keeps the one-active partial index satisfied. */ -export async function setActiveHeadscaleServer(userId: number, id: number): Promise { - return db.transaction(async (tx) => { - await tx - .update(headscaleServers) - .set({ isActive: false, updatedAt: new Date() }) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.isActive, true))); - const [row] = await tx - .update(headscaleServers) - .set({ isActive: true, updatedAt: new Date() }) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.id, id))) - .returning(serverCols); - return row ?? null; - }); -} - -/** - * Drop a registration. If it was the active one, the newest survivor is promoted — otherwise deleting the - * active server would leave the UI with servers registered but none selected, which reads as "not - * configured" and is a confusing place to land. - */ -export async function deleteHeadscaleServer(userId: number, id: number): Promise { - return db.transaction(async (tx) => { - const [deleted] = await tx - .delete(headscaleServers) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.id, id))) - .returning({ id: headscaleServers.id, wasActive: headscaleServers.isActive }); - if (!deleted) return false; - - if (deleted.wasActive) { - const [next] = await tx - .select({ id: headscaleServers.id }) - .from(headscaleServers) - .where(eq(headscaleServers.userId, userId)) - .orderBy(desc(headscaleServers.createdAt)) - .limit(1); - if (next) { - await tx - .update(headscaleServers) - .set({ isActive: true, updatedAt: new Date() }) - .where(eq(headscaleServers.id, next.id)); - } - } - return true; - }); -} - -/** Record a successful reachability probe: the version observed and when we last reached the server. */ -export async function recordHeadscaleProbe(userId: number, id: number, version: string | null): Promise { - await db - .update(headscaleServers) - .set({ version, lastSeenAt: new Date(), updatedAt: new Date() }) - .where(and(eq(headscaleServers.userId, userId), eq(headscaleServers.id, id))); -} diff --git a/plugins/offscale/db/schema.ts b/plugins/offscale/db/schema.ts deleted file mode 100644 index 08376bb7..00000000 --- a/plugins/offscale/db/schema.ts +++ /dev/null @@ -1,55 +0,0 @@ -import { pgTable, serial, integer, text, boolean, timestamp, uniqueIndex } from 'drizzle-orm/pg-core'; -import { sql } from 'drizzle-orm'; -import { users } from 'officerdb/auth/schema'; - -// The Headscale servers the owner manages, for the officer-headscale sidecar. Officer targets no single -// Headscale: the owner registers one or more servers (URL + an admin API key generated on that server) and -// toggles between them, so this is configuration the user creates at runtime rather than env vars. -// -// `api_key` is a Headscale *admin* credential — it can delete every node on a tailnet — so it is encrypted -// at rest via ../crypto.ts, exactly like the vault token set. Encryption/decryption is confined to -// queries/headscale.ts; nothing outside that file ever sees ciphertext, and list callers never see the key -// at all. SECURITY_AUDIT.md L2 records plaintext credential storage as an open finding, so the plaintext -// email/integrations tables are debt to avoid copying, not a precedent to follow. -// -// Every table here is `headscale_`-prefixed and this file holds nothing else: when sidecars own their own -// schema it moves wholesale into src/servers/sidecar/headscale/ with no untangling. Only the -// officer-headscale sidecar reads or writes these tables. - -export const headscaleServers = pgTable( - 'headscale_servers', - { - id: serial('id').primaryKey(), - userId: integer('user_id') - .notNull() - .references(() => users.id, { onDelete: 'cascade' }), - name: text('name').notNull(), - // Normalized without a trailing slash before write, so `${url}/api/v1/...` never doubles the separator. - url: text('url').notNull(), - apiKey: text('api_key').notNull(), // encrypted - // Last version seen from the server's unauthenticated GET /version. Null until first probed; the - // literal 'dev' when the server was built without VCS info, which is unknown rather than too-old. - version: text('version'), - // Where to SSH for a shell on the box running this Headscale — the last-resort escape hatch for when the - // API cannot answer (headscale is down, the tailnet is down, the logs are the only evidence). Deliberately - // NOT derived from `url`: the whole point is to reach the machine when the control plane's own hostname - // stops resolving, so this is usually a raw IP on a different path. No port, user or key material — the - // connection uses whatever ~/.ssh already knows, so there is no credential here to protect. - sshHost: text('ssh_host'), - isActive: boolean('is_active').notNull().default(false), - // Last successful probe, so the UI can distinguish "never reached" from "was reachable, now isn't". - lastSeenAt: timestamp('last_seen_at', { withTimezone: true }), - createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(), - updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(), - }, - (t) => [ - // One registration per URL — re-registering the same server should be an edit, not a duplicate. - uniqueIndex('uq_headscale_servers_user_url').on(t.userId, t.url), - // At most one active server per owner, enforced by the DB rather than by convention: a partial unique - // index over the active rows only. setActiveHeadscaleServer still clears the others in a transaction, - // but a bug there fails loudly here instead of silently leaving two servers active. - uniqueIndex('uq_headscale_servers_one_active') - .on(t.userId) - .where(sql`${t.isActive}`), - ], -); diff --git a/plugins/offscale/manifest.ts b/plugins/offscale/manifest.ts deleted file mode 100644 index 2a01d9ad..00000000 --- a/plugins/offscale/manifest.ts +++ /dev/null @@ -1,47 +0,0 @@ -import type { PluginManifest } from '@@/plugins/manifest'; - -// Offscale — Headscale, plus the Companion that ships beside it. -// -// Not a rename of Headscale and not a fork: the server underneath is stock, and the Companion adds what -// Headscale itself does not do — the invite flow being the first of them. The distinct name marks a -// distinct product rather than a badge on someone else's. -// -// The first real plugin, extracted from the platform on 2026-08-15. Everything it needs is here: -// -// api/router.ts a thin auth-gated proxy — no Headscale knowledge, and it must never grow any -// sidecar/ the whole Headscale contract, holding the admin API keys -// db/ offscale_servers, and the only table this plugin owns -// web/ panels and a layout; the shell renders the Workspace -export const manifest: PluginManifest = { - publisher: 'officerdev', - version: '1.0.0', - platform: '>=1.0.0', - - label: 'Offscale', - summary: 'Your tailnet — machines, users, pre-auth keys, access policy and device invites', - icon: 'Network', - color: '#818cf8', - - // One permission gating the whole surface, grantable per role at read or write like every other. - // - // `[open]` What a member's grant MEANS here is this plugin's own job and is not finished. The queries - // still scope by the caller (`listHeadscaleServers(userId)`), so a granted member would see their own - // empty server list rather than the owner's, and could register a Headscale of their own. The model in - // ./PLUGIN.md is one shared resource: read sees what the owner sees, write can change it. - // That is a change inside these queries, not a flag on the manifest. - // - // Worth knowing while it is unfinished: the stored credential is a Headscale ADMIN api key that can - // delete every node on a tailnet, and there is no read-only version of it — so `write` here is close to - // full control of the tailnet, which is the owner's decision to make deliberately. - permissions: [ - { - key: 'offscale', - label: 'Offscale', - description: 'The tailnet: machines, routes, keys and ACLs', - // Two POSTs that are really reads — a reachability probe and a policy DRAFT that never saves. - // Without declaring them a read-level account meets a broken feature where a withheld permission - // should be. Inert while ownerOnly, and correct the moment that changes. - readOnlyWrites: ['/ssh-test', '/policy/assist'], - }, - ], -}; diff --git a/plugins/offscale/sidecar/active.ts b/plugins/offscale/sidecar/active.ts deleted file mode 100644 index d41e7816..00000000 --- a/plugins/offscale/sidecar/active.ts +++ /dev/null @@ -1,20 +0,0 @@ -import { getActiveHeadscaleCredentials } from '../db/queries'; -import { createClient, type HeadscaleClient } from './client'; - -// Every domain route acts on the ACTIVE server — the one the owner selected in the servers section. That -// choice lives in Postgres (one row, enforced by a partial unique index), not in a request parameter, so -// no client can act on a server the owner isn't currently looking at by guessing an id. - -/** - * The client for the active server, or a ready-to-send 409 when there isn't one. - * - * 409 rather than 404: the route exists and the request was well-formed, the account just has no server - * selected yet. The UI maps it to "pick a server", which is a different message from "that node is gone". - */ -export async function activeClient(userId: number): Promise { - const creds = await getActiveHeadscaleCredentials(userId); - if (!creds) { - return Response.json({ error: 'no active Headscale server', code: 'no_active_server' }, { status: 409 }); - } - return createClient(creds); -} diff --git a/plugins/offscale/sidecar/assist.ts b/plugins/offscale/sidecar/assist.ts deleted file mode 100644 index c2d220fc..00000000 --- a/plugins/offscale/sidecar/assist.ts +++ /dev/null @@ -1,153 +0,0 @@ -import type { OfficerContext } from './routes'; -import { badRequest, methodNotAllowed, readJson } from './routes'; -import { activeClient } from './active'; -import { arrayField, toNode, toUser } from './normalize'; -import { askClaude, ProxyUnavailable } from './claude-proxy'; - -// `POST /_officer/policy/assist` — describe a change in English, get a complete revised policy back. -// -// The ACL is the one document in this app that nobody can write from memory: HuJSON, Tailscale's grammar, -// and every rule keyed to user, tag and host names that only this server knows. The gap this closes is not -// "typing is slow", it is "I do not know what the file is supposed to look like". -// -// THREE THINGS THIS DELIBERATELY DOES NOT DO. -// -// 1. **It never saves.** The proposal comes back as text and lands in the editor as a draft. Headscale is -// written to by exactly one thing, the Save button, and it is pressed by a person who has read the diff. -// A model that could write the ACL directly is a model that can partition the network the owner is -// connected through — including the SSH route back in to fix it. -// 2. **It never validates.** Same argument as policy.ts: Headscale owns the only parser that counts, and a -// proposal that looks fine here and is refused on save is a normal, visible outcome. -// 3. **It sends no credentials.** The prompt carries user names, node names and tags — the vocabulary the -// rules must reference — and nothing else. No API keys, no pre-auth keys, no node addresses. -// -// The current document is sent in full and the reply must be the full replacement, not a patch. Patches -// against a hand-formatted HuJSON file are where comments and alignment get silently destroyed, and this -// file's whole premise is that those are worth keeping. - -const MODEL = 'claude-sonnet-5'; -const MAX_TOKENS = 8_000; -/** A prompt long enough to be an essay is a prompt that should be a conversation. Cheap guard, not a limit. */ -const MAX_PROMPT_CHARS = 2_000; -/** Enough context to write rules against without pasting an entire large tailnet into the request. */ -const MAX_NODES = 60; - -const SYSTEM = `You are helping the owner of a self-hosted Headscale server edit their tailnet's ACL policy. - -The policy is a HuJSON document (JSON with // comments and trailing commas) in Tailscale's ACL format: -groups, tagOwners, hosts, acls, ssh, autoApprovers. Headscale implements a subset — it has no Tailscale SaaS -features such as nodeAttrs postures, and grants are supported only in recent versions, so prefer classic -"acls" entries unless the existing document already uses grants. - -Rules for your reply, in this order: - -1. First, one short paragraph of plain English: what you changed and, where it matters, what it now allows or - denies. No preamble, no restating the request. -2. Then the COMPLETE new policy document inside a single fenced code block tagged hujson. Not a patch, not an - excerpt — the whole file, ready to replace what is there. - -Preserve the existing document's comments, key order and indentation wherever your change does not touch -them; they are hand-maintained and the owner reads this file. Only reference users, tags and hosts that exist -in the context given to you, or that you also define in the same document. If the request is ambiguous enough -that you would have to guess at something consequential, say so in the paragraph and make the narrower, -safer choice rather than asking a question — the owner reviews a diff before anything is saved. - -If the request cannot be expressed in this policy at all, say why in the paragraph and return the document -unchanged in the code block.`; - -type TailnetContext = { users: string[]; tags: string[]; nodes: string[] }; - -/** - * The vocabulary a usable rule has to be written in: who exists, what tags are in use, what the machines are - * called. Best-effort — a server that will not answer these still gets an assistant, just a less informed - * one, which beats failing the request over context that is an optimisation. - */ -async function readContext(userId: number): Promise { - const client = await activeClient(userId); - if (client instanceof Response) return { users: [], tags: [], nodes: [] }; - - try { - const [userBody, nodeBody] = await Promise.all([client.call('/api/v1/user'), client.call('/api/v1/node')]); - - const users = arrayField(userBody, 'users') - .map((raw) => toUser(raw)?.name) - .filter((name): name is string => !!name); - - const nodes = arrayField(nodeBody, 'nodes').map(toNode); - const tags = [...new Set(nodes.flatMap((node) => node.tags))].sort(); - const named = nodes.slice(0, MAX_NODES).map((node) => { - const owner = node.user?.name ?? 'unknown'; - const tagged = node.tags.length ? ` [${node.tags.join(' ')}]` : ''; - return `${node.name} (user: ${owner})${tagged}`; - }); - - return { users, tags, nodes: named }; - } catch { - return { users: [], tags: [], nodes: [] }; - } -} - -function buildPrompt(policy: string, request: string, context: TailnetContext): string { - const lines = [ - 'Current policy document:', - '```hujson', - policy.trim() || '// (this server has no policy yet)', - '```', - '', - 'This tailnet:', - `- users: ${context.users.length ? context.users.join(', ') : '(none)'}`, - `- tags in use: ${context.tags.length ? context.tags.join(', ') : '(none)'}`, - `- machines: ${context.nodes.length ? context.nodes.join('; ') : '(none)'}`, - ]; - if (context.nodes.length === MAX_NODES) lines.push(` (first ${MAX_NODES} shown)`); - lines.push('', 'Requested change:', request.trim()); - return lines.join('\n'); -} - -/** - * Split the reply into the explanation and the document. - * - * The fence is the contract, so a reply without one is a failure to report rather than something to salvage: - * feeding half an answer into the editor as if it were a policy is worse than saying the model didn't comply. - */ -function splitReply(text: string): { explanation: string; policy: string } | null { - const match = text.match(/```(?:hujson|json|jsonc)?\s*\n([\s\S]*?)```/); - if (!match || !match[1]?.trim()) return null; - return { explanation: text.slice(0, match.index).trim(), policy: match[1].replace(/\s+$/, '') }; -} - -/** `POST /_officer/policy/assist {prompt, policy}` → `{explanation, policy}`. Nothing is written upstream. */ -export async function handlePolicyAssistRoute(ctx: OfficerContext, rest: string[]): Promise { - if (rest.length > 0) return badRequest('unexpected path'); - if (ctx.req.method !== 'POST') return methodNotAllowed(); - - const body = await readJson(ctx.req); - const request = typeof body?.prompt === 'string' ? body.prompt.trim() : ''; - if (!request) return badRequest('prompt is required'); - if (request.length > MAX_PROMPT_CHARS) return badRequest(`prompt must be under ${MAX_PROMPT_CHARS} characters`); - // The draft on screen, not the saved document: the owner may have edited it, and a proposal built against - // a version they cannot see would come back as a diff full of changes they never asked for. - const policy = typeof body?.policy === 'string' ? body.policy : ''; - - const context = await readContext(ctx.userId); - - try { - const reply = await askClaude({ - model: MODEL, - maxTokens: MAX_TOKENS, - system: SYSTEM, - prompt: buildPrompt(policy, request, context), - }); - - const split = splitReply(reply); - if (!split) { - return Response.json({ error: 'the model did not return a policy document — try rephrasing' }, { status: 502 }); - } - return Response.json({ explanation: split.explanation, policy: split.policy }); - } catch (err) { - if (err instanceof ProxyUnavailable) { - return Response.json({ error: err.message, code: 'assistant_unavailable' }, { status: 503 }); - } - throw err; - } -} diff --git a/plugins/offscale/sidecar/claude-proxy.ts b/plugins/offscale/sidecar/claude-proxy.ts deleted file mode 100644 index c0472954..00000000 --- a/plugins/offscale/sidecar/claude-proxy.ts +++ /dev/null @@ -1,97 +0,0 @@ -import { existsSync, readFileSync } from 'node:fs'; -import { join } from 'node:path'; -import { DATA_PATH } from '@@/data-path'; -import { ANTHROPIC_PROXY_URL } from '@@/officer-url.mjs'; - -// One-shot model calls, for sidecar features that need a sentence of reasoning rather than an agent. -// -// The target is `officer-anthropic-proxy` on loopback — the same process Claude Code itself talks to. It -// holds the owner's OAuth credential and refreshes it; callers hold nothing. Its `x-api-key` is a locally -// generated secret it writes to its own state file, so authenticating is a file read, not a credential this -// sidecar is given. That file is written by the proxy and read by everyone else; see claude/state.ts -// (`readProxySecretFromDisk`), which does the same thing for the agent. -// -// Not imported from claude/state.ts on purpose: that module initialises paths and a lock for a sidecar this -// one is not. Twenty lines of file read is a better dependency than another sidecar's lifecycle. -// -// This is a REQUEST-SCOPED call with a timeout, not a session. Anything conversational belongs in the chat -// surface, which already exists and already persists. - -const DEFAULT_TIMEOUT_MS = 120_000; - -/** The proxy is not running, has no token, or refused us. Distinct from the model declining to answer. */ -export class ProxyUnavailable extends Error {} - -/** - * The proxy's own generated secret. Empty means "not on disk yet" — it persists on a debounce, so a - * freshly installed machine has a window where the file exists without it. - */ -function readProxySecret(): string { - try { - const file = join(DATA_PATH, 'sidecar', 'claude-state.json'); - if (!existsSync(file)) return ''; - const parsed = JSON.parse(readFileSync(file, 'utf-8')) as { proxySecret?: unknown }; - return typeof parsed.proxySecret === 'string' ? parsed.proxySecret : ''; - } catch { - return ''; - } -} - -type AskParams = { model: string; system: string; prompt: string; maxTokens: number; timeoutMs?: number }; - -type MessagesResponse = { content?: { type?: string; text?: string }[]; error?: { message?: string } }; - -/** - * One user turn, one reply, as plain text. - * - * The system prompt is sent as two blocks with Claude Code's own identity first. The proxy authenticates - * with a Claude Pro/Max OAuth token, and that credential is issued to the CLI — asking it to be something - * else is a request the upstream is entitled to refuse. (Measured 2026-08-06: a plain assistant prompt is - * currently accepted too. Keeping the block costs ~14 tokens and removes the question.) - */ -export async function askClaude({ model, system, prompt, maxTokens, timeoutMs }: AskParams): Promise { - const secret = readProxySecret(); - if (!secret) throw new ProxyUnavailable('the Claude proxy has not started yet — try again in a moment'); - - let res: Response; - try { - res = await fetch(`${ANTHROPIC_PROXY_URL}/v1/messages`, { - method: 'POST', - headers: { 'x-api-key': secret, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' }, - body: JSON.stringify({ - model, - max_tokens: maxTokens, - system: [ - { type: 'text', text: "You are Claude Code, Anthropic's official CLI for Claude." }, - { type: 'text', text: system }, - ], - messages: [{ role: 'user', content: prompt }], - }), - signal: AbortSignal.timeout(timeoutMs ?? DEFAULT_TIMEOUT_MS), - }); - } catch (err) { - if (err instanceof Error && err.name === 'TimeoutError') throw new ProxyUnavailable('the model took too long'); - throw new ProxyUnavailable('the Claude proxy is not reachable'); - } - - const body = (await res.json().catch(() => null)) as MessagesResponse | null; - - if (!res.ok) { - const detail = body?.error?.message; - // 401/429 are the proxy's own credential problems and read as "unavailable"; anything else is upstream - // saying something specific about this request, which is worth passing through. - if (res.status === 401 || res.status === 429) { - throw new ProxyUnavailable(detail ?? `the Claude proxy returned ${res.status}`); - } - throw new Error(detail ?? `the model returned ${res.status}`); - } - - const text = (body?.content ?? []) - .filter((block) => block.type === 'text' && typeof block.text === 'string') - .map((block) => block.text) - .join('') - .trim(); - - if (!text) throw new Error('the model returned an empty reply'); - return text; -} diff --git a/plugins/offscale/sidecar/client.ts b/plugins/offscale/sidecar/client.ts deleted file mode 100644 index 5e51fb35..00000000 --- a/plugins/offscale/sidecar/client.ts +++ /dev/null @@ -1,113 +0,0 @@ -import type { HeadscaleServerCredentials } from '../db/queries'; - -// The Headscale admin API call layer. Every upstream request in this sidecar goes through here, so the -// wire-level quirks are handled once: -// -// • Auth is `Authorization: Bearer `. Headscale's swagger declares no securityDefinitions at all, -// so a generated client would omit it entirely. -// • 401/403 bodies are PLAIN TEXT ("Unauthorized"), with no content-type — every other error is -// grpc-gateway `{code,message,details}` JSON. Blindly .json()-ing an error body throws on exactly the -// auth failure you most want to report clearly. -// • Every uint64 is serialized as a JSON STRING, not a number: `node.id` arrives as "7". We keep ids as -// strings end to end and never round-trip them through Number, which would silently break above 2^53. -// • The gateway marshals with EmitUnpopulated, so absent values come back as [] / null / "" / false rather -// than being omitted. You cannot distinguish "unset" from "empty" — don't try. -// • It also marshals with DiscardUnknown, so a misspelled request field is IGNORED rather than rejected. -// Silent no-ops are the failure mode; mutations here read the object back where the API returns it. - -const DEFAULT_TIMEOUT_MS = 15_000; - -/** An upstream failure carrying the HTTP status to surface, mapped to a response at the route boundary. */ -export class HeadscaleError extends Error { - constructor( - readonly status: number, - message: string, - /** - * Headscale's own words, kept even when `message` generalizes them. - * - * A 5xx is normally not safe to relay — it leaks internals and rarely helps. The policy endpoints are - * the exception: Headscale answers "policy is read from a file" and reports a HuJSON syntax error's - * line and column with the same 500, and there the message IS the feature. Callers that know their - * endpoint's 5xx is a real answer read this; everyone else keeps getting "headscale error". - */ - readonly detail?: string, - ) { - super(message); - this.name = 'HeadscaleError'; - } -} - -type CallOptions = { method?: string; body?: unknown; timeoutMs?: number }; - -/** - * Extract a human-usable message from a Headscale error response, tolerating both of its formats. - * Never returned verbatim to the browser for auth failures — see callers. - */ -async function errorMessage(res: Response): Promise { - const text = await res.text().catch(() => ''); - if (!text) return `upstream returned ${res.status}`; - try { - const parsed = JSON.parse(text) as { message?: unknown }; - if (typeof parsed.message === 'string' && parsed.message) return parsed.message; - } catch { - /* plain text — the 401 case */ - } - return text.slice(0, 300); -} - -export type HeadscaleClient = { - readonly serverId: number; - /** Call an admin API path (e.g. `/api/v1/node`). Throws HeadscaleError on any non-2xx. */ - call: (path: string, opts?: CallOptions) => Promise; -}; - -/** Build a client bound to one registered server's credentials. */ -export function createClient(creds: HeadscaleServerCredentials): HeadscaleClient { - async function call(path: string, opts: CallOptions = {}): Promise { - const { method = 'GET', body, timeoutMs = DEFAULT_TIMEOUT_MS } = opts; - - const headers: Record = { - authorization: `Bearer ${creds.apiKey}`, - accept: 'application/json', - }; - if (body !== undefined) headers['content-type'] = 'application/json'; - - let res: Response; - try { - res = await fetch(`${creds.url}${path}`, { - method, - headers, - body: body === undefined ? undefined : JSON.stringify(body), - signal: AbortSignal.timeout(timeoutMs), - }); - } catch (err) { - const timedOut = err instanceof Error && err.name === 'TimeoutError'; - throw new HeadscaleError(504, timedOut ? 'headscale timed out' : 'headscale unreachable'); - } - - if (res.status === 401 || res.status === 403) { - // The stored key is wrong, expired, or was revoked on the server. Actionable, and distinct from an - // Officer-side auth problem — the UI should point the owner at re-entering the key. - throw new HeadscaleError(502, 'headscale rejected the stored API key'); - } - - if (!res.ok) { - const message = await errorMessage(res); - console.error(`[headscale] ${method} ${path} -> ${res.status}: ${message}`); - // 4xx from the admin API is usually a bad argument and safe to relay; 5xx is not, so it's generalized. - const serverSide = res.status >= 500; - throw new HeadscaleError(serverSide ? 502 : res.status, serverSide ? 'headscale error' : message, message); - } - - // 204 and empty 200s are legitimate: several mutations return `{}` or nothing at all. - const text = await res.text(); - if (!text) return {} as T; - try { - return JSON.parse(text) as T; - } catch { - throw new HeadscaleError(502, 'headscale returned a non-JSON body'); - } - } - - return { serverId: creds.id, call }; -} diff --git a/plugins/offscale/sidecar/companion.ts b/plugins/offscale/sidecar/companion.ts deleted file mode 100644 index c44a21c7..00000000 --- a/plugins/offscale/sidecar/companion.ts +++ /dev/null @@ -1,204 +0,0 @@ -import { getActiveHeadscaleCredentials, type HeadscaleServerCredentials } from '../db/queries'; -import { badRequest, methodNotAllowed, notFound, type OfficerContext } from './routes'; - -// The Officer Companion API — a small service deployed NEXT TO each Headscale server that answers what the -// admin API structurally cannot: is the container up, what do its logs say, and start/stop/restart it. -// Contract: COMMS/HEADSCALE_COMPANION_API.md. -// -// Three facts shape everything here. -// -// 1. It lives at `${server.url}/officer-api` and authenticates with the SAME admin API key we already -// store, validated locally against Headscale's own key store — so auth keeps working while Headscale -// is down, which is exactly when `/restart` matters. Nothing new to register, and the key still never -// leaves this sidecar. -// -// 2. It is OPTIONAL and per-server. Of the four servers registered here today, one has it deployed. So -// "no companion" is a normal state, not an error: every route below answers 200 with -// `{available: false, reason}` rather than failing, and the UI degrades to what the admin API can do. -// Distinguishing the two 502s is the whole trick — nginx returns HTML when the companion is down, -// the companion returns JSON when a docker op fails. Branch on whether the body parses. -// -// 3. `GET /health` is ALWAYS 200, at every verdict. Never key anything off its HTTP status; read -// `verdict`. That inversion is deliberate on their side and is preserved on ours. - -/** - * Every route answers `{available: true, ...}` or `{available: false, reason}` at HTTP 200. Not having a - * companion is a state to render, not a request that failed — the admin API on the same domain is - * independent and may still be working, so this must not surface as an error the UI swallows. - */ -export const unavailable = (reason: string) => ({ available: false as const, reason }); - -const DEFAULT_TIMEOUT_MS = 20_000; - -type CompanionCall = { path: string; method?: string; body?: unknown; timeoutMs?: number; signal?: AbortSignal }; - -/** - * One request to a server's companion. Returns the raw Response, or a reason string when the companion - * itself could not be reached — the caller decides how to present that, because for this feature - * "unreachable" is information rather than a failure. - */ -export async function callCompanion( - creds: HeadscaleServerCredentials, - { path, method = 'GET', body, timeoutMs = DEFAULT_TIMEOUT_MS, signal }: CompanionCall, -): Promise { - let res: Response; - try { - res = await fetch(`${creds.url}/officer-api${path}`, { - method, - headers: { - authorization: `Bearer ${creds.apiKey}`, - accept: 'application/json', - ...(body === undefined ? {} : { 'content-type': 'application/json' }), - }, - body: body === undefined ? undefined : JSON.stringify(body), - signal: signal ?? AbortSignal.timeout(timeoutMs), - }); - } catch (err) { - if (err instanceof Error && err.name === 'TimeoutError') return 'the companion timed out'; - // A TLS failure or DNS miss on the server's own domain: the whole host is unreachable, not just this. - return 'could not reach the server'; - } - - if (res.status === 401) return 'the companion rejected the stored API key'; - - // Both 404 and 502 are ambiguous, and the same test settles both: a JSON body means the companion - // answered (no such container / the docker op failed) and that answer belongs to the caller; a - // non-JSON body means we never reached it — nginx's own 502 page, or a route that isn't there at all. - const isJson = (res.headers.get('content-type') ?? '').includes('json'); - if (res.status === 404 && !isJson) return 'this server has no companion at /officer-api'; - if (res.status === 502 && !isJson) return 'the companion is not deployed on this server'; - if (res.status >= 500 && !isJson) return `the companion returned ${res.status}`; - return res; -} - -/** Parse a companion JSON body, or a reason when it isn't JSON after all. */ -export async function readBody(res: Response): Promise | string> { - const text = await res.text().catch(() => ''); - if (!text) return 'the companion returned an empty body'; - try { - const parsed = JSON.parse(text) as unknown; - if (!parsed || typeof parsed !== 'object') return 'the companion returned an unexpected body'; - return parsed as Record; - } catch { - return 'the companion returned a non-JSON body'; - } -} - -/** The active server's credentials, or a 409 the UI already knows how to render. */ -export async function activeCreds(userId: number): Promise { - const creds = await getActiveHeadscaleCredentials(userId); - if (!creds) { - return Response.json({ error: 'no active Headscale server', code: 'no_active_server' }, { status: 409 }); - } - return creds; -} - -/** `GET /_officer/companion/health` — verdict, container state and, when unhappy, its own diagnosis. */ -async function health(creds: HeadscaleServerCredentials): Promise { - const res = await callCompanion(creds, { path: '/health' }); - if (typeof res === 'string') return Response.json(unavailable(res)); - - const body = await readBody(res); - if (typeof body === 'string') return Response.json(unavailable(body)); - // Passed through as-is. The companion owns this vocabulary and versions it; re-shaping it here would mean - // a new verdict or a new likely-cause silently disappearing on the way to the screen. - return Response.json({ available: true, health: body }); -} - -/** `GET /_officer/companion/logs?tail=N` — a snapshot of the last N lines. */ -async function logs(creds: HeadscaleServerCredentials, url: URL): Promise { - const tail = Number(url.searchParams.get('tail') ?? 200); - if (!Number.isInteger(tail) || tail < 1 || tail > 2000) return badRequest('tail must be 1–2000'); - - const res = await callCompanion(creds, { path: `/logs?tail=${tail}` }); - if (typeof res === 'string') return Response.json(unavailable(res)); - - const body = await readBody(res); - if (typeof body === 'string') return Response.json(unavailable(body)); - const lines = Array.isArray(body.lines) ? body.lines.filter((l): l is string => typeof l === 'string') : []; - return Response.json({ available: true, lines }); -} - -/** - * `GET /_officer/companion/logs/stream?tail=N` — the live tail, relayed frame for frame. - * - * The browser cannot open this itself: EventSource sends no Authorization header, and the key it would need - * is one this sidecar exists to keep. So the stream is proxied, and the body is returned UNTOUCHED — a - * ReadableStream that Bun cancels when the client disconnects, which aborts the upstream fetch in turn. - * Buffering it into frames here would break that, and would also mean a log line waiting on our own flush. - */ -async function logStream(creds: HeadscaleServerCredentials, ctx: OfficerContext): Promise { - const tail = Number(ctx.url.searchParams.get('tail') ?? 200); - if (!Number.isInteger(tail) || tail < 1 || tail > 2000) return badRequest('tail must be 1–2000'); - - // No timeout: a quiet log is the normal case and must not look like a dropped connection. The request's - // own signal is the lifetime — when the panel closes, this closes. - const res = await callCompanion(creds, { - path: `/logs?tail=${tail}&follow=1`, - signal: ctx.req.signal, - }); - - // An unavailable companion still answers in the stream's own vocabulary, so the client has one parser and - // one place to show a problem rather than a second, JSON-shaped failure mode. - if (typeof res === 'string') { - return new Response(`event: error\ndata: ${res}\n\n`, { - headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' }, - }); - } - - return new Response(res.body, { - status: 200, - headers: { - 'content-type': 'text/event-stream', - 'cache-control': 'no-cache', - // Belt and braces through our own proxy chain, matching what the companion already sets. - 'x-accel-buffering': 'no', - }, - }); -} - -const ACTIONS = new Set(['restart', 'stop', 'start']); - -/** - * `POST /_officer/companion/:action` — restart / stop / start the Headscale container. - * - * Every one of these drops every node's control-plane connection for the duration. That is the intended - * "kill it" behaviour and the reason the UI asks twice; it is not something to retry automatically. - */ -async function action(creds: HeadscaleServerCredentials, name: string): Promise { - // 60s: docker restart on a busy container is not fast, and a timeout here reads as "did it work?" — the - // one question this feature exists to answer. - const res = await callCompanion(creds, { path: `/${name}`, method: 'POST', timeoutMs: 60_000 }); - if (typeof res === 'string') return Response.json(unavailable(res)); - - const body = await readBody(res); - if (typeof body === 'string') return Response.json(unavailable(body)); - return Response.json({ available: true, ...body }); -} - -/** Dispatch `/_officer/companion/...`. Always acts on the ACTIVE server, like every other domain route. */ -export async function handleCompanionRoute(ctx: OfficerContext, rest: string[]): Promise { - const creds = await activeCreds(ctx.userId); - if (creds instanceof Response) return creds; - - const [head, tail] = rest; - - if (head === 'health' && !tail) { - if (ctx.req.method !== 'GET') return methodNotAllowed(); - return health(creds); - } - - if (head === 'logs') { - if (ctx.req.method !== 'GET') return methodNotAllowed(); - if (!tail) return logs(creds, ctx.url); - if (tail === 'stream') return logStream(creds, ctx); - return notFound(); - } - - if (head && ACTIONS.has(head) && !tail) { - if (ctx.req.method !== 'POST') return methodNotAllowed(); - return action(creds, head); - } - - return notFound(); -} diff --git a/plugins/offscale/sidecar/enroll.ts b/plugins/offscale/sidecar/enroll.ts deleted file mode 100644 index eed8195d..00000000 --- a/plugins/offscale/sidecar/enroll.ts +++ /dev/null @@ -1,103 +0,0 @@ -import type { OfficerContext } from './routes'; -import type { OfficerUser } from './normalize'; -import { getActiveHeadscaleCredentials } from '../db/queries'; -import { badRequest, methodNotAllowed, readJson } from './routes'; -import { createClient, type HeadscaleClient } from './client'; -import { arrayField, toUser } from './normalize'; -import { handleInvitesRoute } from './invites'; - -// Device enrolment — POST /_officer/enroll. The mobile app's one-tap join: it turns an authenticated -// Officer session into a short-lived, single-use pre-auth key, so nobody pastes a key by hand. -// -// THIS USED TO LIVE IN THE PLATFORM. `src/servers/api/vpn/router.ts` (deleted 2026-08-14) read -// HEADSCALE_URL, HEADSCALE_API_KEY -// and HEADSCALE_USER straight from the host env — three globals that could only ever describe ONE server, -// while this sidecar already kept a registry of many. Worse, the two credential vars were removed at some -// point and nobody noticed: the route had been answering 503 to every enrolment attempt, because it checks -// those two before it gets anywhere near the user name. Enrolment acts on the ACTIVE registered server now, -// like every other domain route here, and the platform holds no Headscale credentials at all. -// -// The response shape `{controlUrl, authKey}` is a CONTRACT: enrollVpn() in the mobile core -// (monorepo-mobile/packages/core/src/services/officer-net.ts) destructures exactly those two fields and -// feeds them to configure()/loginWithAuthKey(). Extra fields are safe; renaming those two is not. - -/** Short by design: the key is redeemed seconds after it is issued, and a leaked one should die quickly. */ -const KEY_TTL_MS = 10 * 60_000; - -/** - * Which Headscale user the joining device is filed under. - * - * An explicit `userId` wins. Otherwise the choice is only made when it is UNAMBIGUOUS — one user on the - * server means there is nothing to choose. Several means the caller has to say, because picking silently - * files someone's phone under the wrong owner and the mistake stays invisible until somebody audits the - * tailnet. The old env var picked one name for every server at once, which is precisely that bug. - */ -async function resolveOwner(client: HeadscaleClient, ctx: OfficerContext): Promise { - const body = await readJson(ctx.req); - const requested = typeof body?.userId === 'string' ? body.userId.trim() : ''; - - const listed = await client.call('/api/v1/user'); - const users = arrayField(listed, 'users') - .map(toUser) - .filter((u): u is OfficerUser => !!u); - - if (requested) { - const match = users.find((u) => u.id === requested); - return match ?? badRequest(`no Headscale user with id ${requested} on the active server`); - } - - if (users.length === 1) return users[0]!; - - if (users.length === 0) { - return Response.json( - { error: 'the active Headscale server has no users — create one before enrolling a device', code: 'no_users' }, - { status: 409 }, - ); - } - - return Response.json( - { - error: 'the active Headscale server has several users — pass userId to say which one owns this device', - code: 'ambiguous_user', - users: users.map((u) => ({ id: u.id, name: u.name })), - }, - { status: 409 }, - ); -} - -export async function handleEnrollRoute(ctx: OfficerContext, segments: string[]): Promise { - // `/enroll/invites…` is the admin invite surface — a different flow entirely (see invites.ts): the device - // is not here and there is no Officer session on it. Same prefix because it is the same feature to the - // person using it, and because the spec names it that way. - if (segments[0] === 'invites') return handleInvitesRoute(ctx, segments.slice(1)); - - if (segments.length > 0) return null; - if (ctx.req.method !== 'POST') return methodNotAllowed(); - - // Not activeClient(): the control URL goes back to the device, and only the credentials carry it. - const creds = await getActiveHeadscaleCredentials(ctx.userId); - if (!creds) { - return Response.json({ error: 'no active Headscale server', code: 'no_active_server' }, { status: 409 }); - } - - const client = createClient(creds); - - const owner = await resolveOwner(client, ctx); - if (owner instanceof Response) return owner; - - const created = await client.call<{ preAuthKey?: { key?: string } }>('/api/v1/preauthkey', { - method: 'POST', - body: { - user: owner.id, - reusable: false, // one key, one device - ephemeral: false, // the node stays registered after it disconnects - expiration: new Date(Date.now() + KEY_TTL_MS).toISOString(), // RFC3339 - }, - }); - - const authKey = created.preAuthKey?.key; - if (!authKey) return Response.json({ error: 'headscale returned no key' }, { status: 502 }); - - // `server` and `user` are advisory — for a UI that wants to say what the device just joined. - return Response.json({ controlUrl: creds.url, authKey, server: creds.name, user: owner.name }); -} diff --git a/plugins/offscale/sidecar/index.ts b/plugins/offscale/sidecar/index.ts deleted file mode 100644 index ebb5ff53..00000000 --- a/plugins/offscale/sidecar/index.ts +++ /dev/null @@ -1,149 +0,0 @@ -import type { SidecarCommand, SidecarEvent } from '@@/sidecar/protocol'; -import { createSidecarConnector } from '@@/sidecar/connect'; -import { handleOfficerRoute } from './routes'; -import { MIN_VERSION_LABEL } from './version'; -import { API_URL } from '@@/officer-url.mjs'; - -// The officer-headscale sidecar. Owns the whole Headscale contract for Officer: the registered servers and -// their admin API keys, the >=0.29 version floor, and every multi-call composition the UI needs. The platform -// API is a thin auth-gated forwarder (src/servers/api/headscale/router.ts) holding no Headscale credentials. -// -// Officer manages MANY Headscale servers, not one. The owner registers each with a URL and an API key -// generated on that server, and switches between them; one is active at a time. So configuration lives in -// Postgres (headscale_servers, keys encrypted at rest), NOT in env vars — this sidecar deliberately reads -// neither HEADSCALE_URL nor HEADSCALE_API_KEY, so a registered server can never be shadowed by host env. -// Device enrollment used to be the exception, minting keys in the platform from those two vars plus -// HEADSCALE_USER; it moved here (enroll.ts) and now acts on the active server like everything else. -// -// ───────────────────────────────────────────────────────────────────────────────────────────────── -// HTTP CONTRACT — the platform strips its /api/headscale mount prefix before forwarding. -// -// GET /_health ours. Sidecar liveness only. Per-server reachability is a -// different question and needs an owner, so it lives below. -// GET /_officer/servers registered servers (never includes API keys) -// POST /_officer/servers register {name?,url,apiKey} — validated before it is saved -// PATCH /_officer/servers/:id edit; re-validated when url or apiKey changes -// DELETE /_officer/servers/:id deregister; promotes the newest survivor if it was active -// POST /_officer/servers/:id/activate switch the active server -// GET /_officer/servers/:id/health probe: reachable? version? key still accepted? -// -// Everything below acts on the ACTIVE server. 409 when none is selected — see active.ts. -// -// GET /_officer/nodes nodes, normalized; ?user= filters -// GET /_officer/nodes/:id one node -// DELETE /_officer/nodes/:id remove it from the tailnet -// POST /_officer/nodes/:id/rename {name} -// POST /_officer/nodes/:id/tags {tags} — 'tag:' prefix added if missing -// POST /_officer/nodes/:id/routes {routes} whole set, or {route,approved} single toggle (RMW here) -// POST /_officer/nodes/:id/expire expire its key, forcing re-auth (not a delete) -// GET /_officer/users users, each with a node count the admin API doesn't provide -// POST /_officer/users {name, displayName?, email?} -// POST /_officer/users/:id/rename {name} -// DELETE /_officer/users/:id refused upstream while the user still owns nodes -// GET /_officer/keys pre-auth keys, secrets masked, with a derived status -// POST /_officer/keys {userId, reusable?, ephemeral?, expirationDays?, aclTags?} -// → the ONLY response carrying the real secret -// POST /_officer/keys/:id/expire expire without deleting -// DELETE /_officer/keys/:id delete outright -// POST /_officer/enroll {userId?} → {controlUrl, authKey} — a single-use 10-minute key -// for a joining device. userId is only required when the server -// has more than one user. -// NO CALLER since 2026-08-14: its only door was /api/vpn/enroll, -// which is deleted. Kept because it is the handler a route under -// /api/offscale would reuse, and because `/enroll/invites` — which -// IS live — dispatches through the same function. -// anything else 404 -// -// There is deliberately NO transparent /api/v1/* passthrough. Headscale's REST shape changed repeatedly -// below 0.29 and its ids are uint64-as-JSON-string, so proxying raw would push all of that into the browser -// — the mistake the Soulseek panels made with 37 raw upstream calls. Every quirk is absorbed here. -// ───────────────────────────────────────────────────────────────────────────────────────────────── - -/** Grab an ephemeral free port by briefly binding one and releasing it. */ -function getFreePort(): number { - const probe = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') }); - const p = probe.port; - probe.stop(true); - if (p == null) throw new Error('failed to acquire a free port'); - return p; -} - -const port = getFreePort(); - -const server = Bun.serve({ - port, - hostname: '127.0.0.1', - async fetch(req) { - const url = new URL(req.url); - - // Liveness, not upstream health: with many registered servers there is no single upstream to probe, and - // choosing one would need an authenticated owner. See /_officer/servers/:id/health for that. - if (url.pathname === '/_health') { - return Response.json({ ok: true, minHeadscaleVersion: MIN_VERSION_LABEL }); - } - - if (url.pathname.startsWith('/_officer/')) { - try { - const res = await handleOfficerRoute(req, url); - return res ?? new Response('not found', { status: 404 }); - } catch (err) { - console.error(`[headscale] ${req.method} ${url.pathname} failed`, err); - return Response.json({ error: 'internal error' }, { status: 500 }); - } - } - - return new Response('not found', { status: 404 }); - }, -}); - -console.log(`[headscale] listening on 127.0.0.1:${port} (Headscale >=${MIN_VERSION_LABEL})`); - -// ── Command handlers ── - -type ReplyFn = (msg: SidecarEvent) => void; - -function handleCommand(cmd: SidecarCommand, reply: ReplyFn) { - switch (cmd.type) { - case 'ping': - reply({ type: 'pong', id: cmd.id }); - break; - default: - reply({ - type: 'error', - id: (cmd as SidecarCommand).id, - error: `Unknown command type: ${(cmd as Record).type}`, - }); - } -} - -// ── Connect to API server ── - -const connection = createSidecarConnector({ - apiUrl: `${API_URL}/api/sidecar/register`, - name: 'headscale', - handles: ['headscale'], - onCommand(cmd, reply) { - handleCommand(cmd as SidecarCommand, reply as ReplyFn); - }, - onConnected() { - // Tell the API where we're listening, so it can forward /api/headscale/* here. - connection.send({ type: 'headscale:server', port }); - console.log(`[headscale] reported port ${port} to API`); - }, -}); - -// ── Graceful shutdown ── - -function shutdown(signal: string) { - console.log(`[headscale] ${signal} received, shutting down...`); - try { - server.stop(true); - } catch { - /* already stopped */ - } - connection.destroy(); - process.exit(0); -} - -process.on('SIGTERM', () => shutdown('SIGTERM')); -process.on('SIGINT', () => shutdown('SIGINT')); diff --git a/plugins/offscale/sidecar/invites.ts b/plugins/offscale/sidecar/invites.ts deleted file mode 100644 index 37fed1db..00000000 --- a/plugins/offscale/sidecar/invites.ts +++ /dev/null @@ -1,183 +0,0 @@ -import type { HeadscaleServerCredentials } from '../db/queries'; -import { badRequest, methodNotAllowed, notFound, readJson, type OfficerContext } from './routes'; -import { activeCreds, callCompanion, readBody, unavailable } from './companion'; - -// Enrolment invites — the admin half of COMMS/OFFSCALE_INVITE_ENROLLMENT.md. An admin mints a single-use -// invite, sends the link to whoever needs to join, and their phone exchanges the claim token for a pre-auth -// key it never had to be told. -// -// WHY THESE PROXY THE COMPANION RATHER THAN LIVING HERE. The invite store has to sit somewhere the joining -// phone can reach without an Officer account, and this sidecar is not that: it binds loopback on an -// ephemeral port behind Officer's auth. The spec's own argument settles it — an invite must still work when -// the platform is down, because the tailnet is often how you reach the platform. So the invite records, the -// token hashing and the claim endpoint belong next to Headscale, on its public origin, which is exactly what -// the Officer Companion already is. Officer is the admin surface and nothing more: create, list, revoke. -// -// Officer therefore stores no invite and no token. §5: "Never display, log or store the claim token beyond -// the moment it is handed to the admin." The create response passes through this process once, in memory, -// on its way to the browser — that is the whole of its life here. -// -// A server without the enrolment API answers `{available: false, reason}` at HTTP 200, like every other -// companion route: most registered servers have no companion at all, and that is a state to render rather -// than a request that failed. - -/** - * Where the invite API sits on the companion, under its own `/officer-api` mount — so the full URL is - * `${server.url}/officer-api/api/v1/enroll/invites`. Versioned separately from the companion's container - * routes (`/health`, `/logs`, `/restart`), which are unversioned; one constant so the two cannot drift. - */ -const INVITES_PATH = '/api/v1/enroll/invites'; - -/** Spec §4.1: default 900, max 86400. The floor is ours — a sub-minute invite cannot be sent to anyone. */ -const DEFAULT_TTL_SECONDS = 900; -const MIN_TTL_SECONDS = 60; -const MAX_TTL_SECONDS = 86_400; - -type CreateInput = { - user: string; - ttlSeconds: number; - ephemeral: boolean; - tags: string[]; - note?: string; -}; - -/** Validate the admin's form into the companion's request body, or a 400 saying which field was wrong. */ -function parseCreate(body: Record | null): CreateInput | Response { - const user = typeof body?.user === 'string' ? body.user.trim() : ''; - if (!user) return badRequest('user is required — an invite files the joining device under one Headscale user'); - - const raw = body?.ttlSeconds; - const ttlSeconds = raw === undefined || raw === null ? DEFAULT_TTL_SECONDS : Number(raw); - if (!Number.isInteger(ttlSeconds) || ttlSeconds < MIN_TTL_SECONDS || ttlSeconds > MAX_TTL_SECONDS) { - return badRequest(`ttlSeconds must be an integer between ${MIN_TTL_SECONDS} and ${MAX_TTL_SECONDS}`); - } - - // Tags are admin-set and passed through opaquely (spec §9.2). The `tag:` prefix is Headscale's, and - // adding it here means the admin can type either form without minting a key that silently has no tag. - const tags = Array.isArray(body?.tags) - ? [ - ...new Set( - body.tags - .filter((t): t is string => typeof t === 'string') - .map((t) => t.trim()) - .filter(Boolean) - .map((t) => (t.startsWith('tag:') ? t : `tag:${t}`)), - ), - ] - : []; - - const note = typeof body?.note === 'string' ? body.note.trim().slice(0, 200) : ''; - - return { user, ttlSeconds, ephemeral: body?.ephemeral === true, tags, ...(note ? { note } : {}) }; -} - -/** - * Turn a companion answer into ours. - * - * The three cases are distinct and the UI needs them to stay that way: unreachable is `available: false` - * (render an explanation), a companion refusal keeps its own status and message (the admin typed something - * the server rejected), and success is the body with `available: true` on it. - */ -async function relay(res: Response | string, wrap: (body: Record) => unknown): Promise { - if (typeof res === 'string') return Response.json(unavailable(res)); - - const body = await readBody(res); - if (typeof body === 'string') return Response.json(unavailable(body)); - - if (!res.ok) { - const error = typeof body.error === 'string' ? body.error : `the companion returned ${res.status}`; - return Response.json( - { error, code: typeof body.code === 'string' ? body.code : undefined }, - { status: res.status }, - ); - } - - return Response.json(wrap(body)); -} - -/** - * Carry the admin's device name in the link's fragment, as `n=`. - * - * The companion already knows the name — it stores the note and hands it back as `suggestedHostname` on - * claim — but a claim only happens when the person taps Join, which is one step AFTER the screen that asks - * them to name the device. So the name has to arrive with the link if the field is to be prefilled, and the - * link is the last thing that passes through here. - * - * Safe at every hop: the fragment is never sent to a server, the companion's /join page copies it verbatim - * into the `officer-offscale://` deep link, and a build of the app that predates this ignores an unknown - * parameter and still gets the name from `suggestedHostname` at claim time. Percent-encoded rather than - * base64url (which `s` uses) because the app's fragment parser already decodeURIComponent()s every value, - * and because base64url of a non-ASCII name would decode to mojibake on Hermes. - */ -function withNameHint(url: unknown, name: string | undefined): unknown { - if (typeof url !== 'string' || !name || !url.includes('#')) return url; - return `${url}&n=${encodeURIComponent(name)}`; -} - -/** - * `POST /_officer/enroll/invites` — mint an invite. The response carries the link, and only this once. - * - * `url` is an ordinary HTTPS link to a page on the server's own domain, which bounces into the app; the - * companion also returns `deepLink`, the `officer-offscale://` scheme that page redirects to. That one is - * dropped here rather than passed on: it carries the same claim token in its fragment, and a second copy of - * a single-use credential in the browser is a second chance to leak it. Nothing on our side opens it. - */ -async function create(creds: HeadscaleServerCredentials, ctx: OfficerContext): Promise { - const input = parseCreate(await readJson(ctx.req)); - if (input instanceof Response) return input; - - const res = await callCompanion(creds, { path: INVITES_PATH, method: 'POST', body: input }); - return relay(res, (body) => { - const raw = body.invite ?? body; - const invite = raw && typeof raw === 'object' ? (raw as Record) : {}; - const { deepLink: _deepLink, ...rest } = invite; - return { available: true, invite: { ...rest, url: withNameHint(rest.url, input.note) } }; - }); -} - -/** - * Pull the invite array out of whatever envelope the companion used. - * - * §4.3 specifies the fields but not the wrapper, and the create response came back flat (no `invite` key), - * so the list may equally be a bare array or sit under `invites`/`items`/`data`. Taking the first - * array-valued property is shape-agnostic without being credulous: the body has exactly one array in it. - */ -function pickInvites(body: Record): unknown[] { - if (Array.isArray(body)) return body; - for (const key of ['invites', 'items', 'data', 'results']) { - const value = body[key]; - if (Array.isArray(value)) return value; - } - const found = Object.values(body).find(Array.isArray); - return Array.isArray(found) ? found : []; -} - -/** `GET /_officer/enroll/invites` — the admin's audit list. Never carries a token or a key. */ -async function list(creds: HeadscaleServerCredentials): Promise { - const res = await callCompanion(creds, { path: INVITES_PATH }); - return relay(res, (body) => ({ available: true, invites: pickInvites(body) })); -} - -/** `DELETE /_officer/enroll/invites/:id` — revoke an unclaimed invite. A no-op on a claimed one. */ -async function revoke(creds: HeadscaleServerCredentials, id: string): Promise { - const res = await callCompanion(creds, { path: `${INVITES_PATH}/${encodeURIComponent(id)}`, method: 'DELETE' }); - return relay(res, (body) => ({ available: true, ...body })); -} - -/** Dispatch `/_officer/enroll/invites...`. Acts on the ACTIVE server, like every other domain route. */ -export async function handleInvitesRoute(ctx: OfficerContext, rest: string[]): Promise { - const creds = await activeCreds(ctx.userId); - if (creds instanceof Response) return creds; - - const [id, extra] = rest; - if (extra) return notFound(); - - if (!id) { - if (ctx.req.method === 'POST') return create(creds, ctx); - if (ctx.req.method === 'GET') return list(creds); - return methodNotAllowed(); - } - - if (ctx.req.method !== 'DELETE') return methodNotAllowed(); - return revoke(creds, id); -} diff --git a/plugins/offscale/sidecar/keys.ts b/plugins/offscale/sidecar/keys.ts deleted file mode 100644 index dbf3e6d5..00000000 --- a/plugins/offscale/sidecar/keys.ts +++ /dev/null @@ -1,119 +0,0 @@ -import type { OfficerContext } from './routes'; -import { badRequest, notFound, methodNotAllowed, readJson } from './routes'; -import { activeClient } from './active'; -import { toPreAuthKey, arrayField } from './normalize'; - -// Pre-auth key routes — /_officer/keys/*. These are the tokens a machine uses to join the tailnet. -// -// The one thing that matters here: since 0.28 Headscale stores pre-auth keys HASHED and returns the real -// secret ONLY in the create response. Every later list returns it masked as `hskey-auth--***`. A -// creation response that the UI drops is a key the owner can never recover — it has to be shown once, with -// a copy affordance, and the API has to make the difference legible. `key` is non-null exactly once. -// -// That "exactly once" is enforced by call path, not by inspecting the value: keys created before 0.28 are -// still plaintext upstream and Headscale hands them back in full from the LIST endpoint for backwards -// compatibility. So listing passes reveal:false and drops the secret unconditionally; only createKey -// reveals. A server with history in it would otherwise leak live keys into the browser's query cache. -// -// Also note the shape of the delete/expire pair: expire takes the id in a POST BODY, delete takes it in a -// query STRING, and neither is a REST-shaped path. Both are hidden behind ordinary Officer routes. - -/** Default lifetime when the caller doesn't pick one; matches Headscale's own CLI default. */ -const DEFAULT_EXPIRY_DAYS = 90; -const MAX_EXPIRY_DAYS = 3650; - -async function listKeys(ctx: OfficerContext): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - // 0.29 lists every user's keys in one call (pre-0.29 required a ?user= filter and one call per user). - const body = await client.call('/api/v1/preauthkey'); - const keys = arrayField(body, 'preAuthKeys').map((raw) => toPreAuthKey(raw, { reveal: false })); - - // Usable keys first, then by newest — a spent key is history, an active one is the thing you came for. - const rank = { active: 0, used: 1, expired: 2 } as const; - keys.sort((a, b) => rank[a.status] - rank[b.status] || (b.createdAt ?? '').localeCompare(a.createdAt ?? '')); - - return Response.json({ keys }); -} - -async function createKey(ctx: OfficerContext): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - const body = await readJson(ctx.req); - if (!body) return badRequest('expected a JSON body'); - - // CreatePreAuthKey takes a numeric user ID — unlike the node list filter, which takes a username. The - // two are easy to confuse and the failure is a confusing upstream error, so it's validated here. - const userId = typeof body.userId === 'string' ? body.userId.trim() : ''; - if (!/^\d+$/.test(userId)) return badRequest('userId must be the numeric id of a Headscale user'); - - const days = body.expirationDays === undefined ? DEFAULT_EXPIRY_DAYS : Number(body.expirationDays); - if (!Number.isFinite(days) || days <= 0 || days > MAX_EXPIRY_DAYS) { - return badRequest(`expirationDays must be between 1 and ${MAX_EXPIRY_DAYS}`); - } - - const aclTags = Array.isArray(body.aclTags) - ? body.aclTags - .filter((t): t is string => typeof t === 'string') - .map((t) => t.trim()) - .filter(Boolean) - .map((t) => (t.startsWith('tag:') ? t : `tag:${t}`)) - : []; - - const created = await client.call<{ preAuthKey?: Record }>('/api/v1/preauthkey', { - method: 'POST', - body: { - user: userId, - reusable: body.reusable === true, - ephemeral: body.ephemeral === true, - expiration: new Date(Date.now() + days * 86_400_000).toISOString(), - aclTags, - }, - }); - - if (!created.preAuthKey) return Response.json({ error: 'headscale returned no key' }, { status: 502 }); - - const key = toPreAuthKey(created.preAuthKey, { reveal: true }); - // Stated explicitly rather than left for the client to infer from `key !== null`: this response is the - // only time the secret exists anywhere outside the joining machine. - return Response.json({ key, secretShownOnce: true }, { status: 201 }); -} - -type KeyActionParams = { ctx: OfficerContext; id: string; action: string | undefined }; - -async function handleKeyAction({ ctx, id, action }: KeyActionParams): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - if (action === 'expire') { - if (ctx.req.method !== 'POST') return methodNotAllowed(); - await client.call('/api/v1/preauthkey/expire', { method: 'POST', body: { id } }); - return new Response(null, { status: 204 }); - } - - if (action !== undefined) return notFound(); - - if (ctx.req.method === 'DELETE') { - await client.call(`/api/v1/preauthkey?id=${encodeURIComponent(id)}`, { method: 'DELETE' }); - return new Response(null, { status: 204 }); - } - - return methodNotAllowed(); -} - -/** Dispatch `/_officer/keys/...`. `rest` is the path after `keys`. */ -export async function handleKeysRoute(ctx: OfficerContext, rest: string[]): Promise { - if (rest.length === 0) { - if (ctx.req.method === 'GET') return listKeys(ctx); - if (ctx.req.method === 'POST') return createKey(ctx); - return methodNotAllowed(); - } - if (rest.length > 2) return notFound(); - - const id = rest[0]; - if (!id || !/^\d+$/.test(id)) return badRequest('key id must be numeric'); - - return handleKeyAction({ ctx, id, action: rest[1] }); -} diff --git a/plugins/offscale/sidecar/nodes.ts b/plugins/offscale/sidecar/nodes.ts deleted file mode 100644 index dc34a2c9..00000000 --- a/plugins/offscale/sidecar/nodes.ts +++ /dev/null @@ -1,142 +0,0 @@ -import type { OfficerContext } from './routes'; -import { badRequest, notFound, methodNotAllowed, readJson } from './routes'; -import type { HeadscaleClient } from './client'; -import { activeClient } from './active'; -import { toNode, arrayField, type OfficerNode } from './normalize'; - -// Node routes — /_officer/nodes/*. A "node" is a machine in the tailnet. -// -// Two upstream shapes are worth knowing before reading this: -// -// • Renaming takes the new name in the PATH (`/node/{id}/rename/{newName}`), not a body. It must be -// encodeURIComponent'd or a name with a slash silently becomes a 404 on a different route. -// • Route approval is a whole-SET write (`approve_routes` replaces the approved list), not an -// add/remove. Approving one route means sending every route that should remain approved, so those -// operations are read-modify-write here rather than in the browser — see rule 5 in -// SIDECAR_ARCHITECTURE.md. Doing it client-side would make two admins racing lose each other's edits; -// doing it here still races, but over milliseconds instead of however long a form sits open. - -/** Nodes on the active server, newest-registered first within each user. */ -async function listNodes(ctx: OfficerContext): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - // The upstream `user` filter takes a USERNAME, not an id — a trap worth keeping out of the browser. - const user = ctx.url.searchParams.get('user'); - const path = user ? `/api/v1/node?user=${encodeURIComponent(user)}` : '/api/v1/node'; - - const body = await client.call(path); - const nodes = arrayField(body, 'nodes').map(toNode); - nodes.sort((a, b) => Number(b.online) - Number(a.online) || a.name.localeCompare(b.name)); - return Response.json({ nodes }); -} - -/** Re-read one node after a mutation. Headscale's mutation responses are inconsistent; a GET never is. */ -async function getNode(client: HeadscaleClient, id: string): Promise { - const body = await client.call<{ node?: Record }>(`/api/v1/node/${encodeURIComponent(id)}`); - return body.node ? toNode(body.node) : null; -} - -type NodeActionParams = { ctx: OfficerContext; id: string; action: string | undefined }; - -async function handleNodeAction({ ctx, id, action }: NodeActionParams): Promise { - const { req } = ctx; - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - if (action === undefined) { - if (req.method === 'GET') { - const node = await getNode(client, id); - return node ? Response.json({ node }) : notFound('no such node'); - } - if (req.method === 'DELETE') { - await client.call(`/api/v1/node/${encodeURIComponent(id)}`, { method: 'DELETE' }); - return new Response(null, { status: 204 }); - } - return methodNotAllowed(); - } - - if (req.method !== 'POST') return methodNotAllowed(); - - if (action === 'rename') { - const body = await readJson(req); - if (!body) return badRequest('expected a JSON body'); - const name = typeof body.name === 'string' ? body.name.trim() : ''; - if (!name) return badRequest('name is required'); - await client.call(`/api/v1/node/${encodeURIComponent(id)}/rename/${encodeURIComponent(name)}`, { method: 'POST' }); - return Response.json({ node: await getNode(client, id) }); - } - - if (action === 'tags') { - const body = await readJson(req); - if (!body) return badRequest('expected a JSON body'); - if (!Array.isArray(body.tags)) return badRequest('tags must be an array of strings'); - const tags = body.tags.filter((t): t is string => typeof t === 'string').map((t) => t.trim()); - if (tags.some((t) => !t)) return badRequest('tags cannot be empty strings'); - // Headscale requires the `tag:` prefix and rejects anything else with a 500, which we'd surface as a - // useless "headscale error". Normalizing here means the UI can accept either form. - const prefixed = tags.map((t) => (t.startsWith('tag:') ? t : `tag:${t}`)); - await client.call(`/api/v1/node/${encodeURIComponent(id)}/tags`, { method: 'POST', body: { tags: prefixed } }); - return Response.json({ node: await getNode(client, id) }); - } - - if (action === 'routes') { - const body = await readJson(req); - if (!body) return badRequest('expected a JSON body'); - - let routes: string[]; - if (Array.isArray(body.routes)) { - // Whole-set write: the caller states the complete approved list. - routes = body.routes.filter((r): r is string => typeof r === 'string'); - } else if (typeof body.route === 'string' && typeof body.approved === 'boolean') { - // Single-toggle: read the current set, apply one change, write it back. - const current = await getNode(client, id); - if (!current) return notFound('no such node'); - const set = new Set(current.approvedRoutes); - if (body.approved) set.add(body.route); - else set.delete(body.route); - routes = [...set]; - } else { - return badRequest('expected {routes: string[]} or {route: string, approved: boolean}'); - } - - await client.call(`/api/v1/node/${encodeURIComponent(id)}/approve_routes`, { method: 'POST', body: { routes } }); - return Response.json({ node: await getNode(client, id) }); - } - - if (action === 'user') { - const body = await readJson(req); - if (!body) return badRequest('expected a JSON body'); - // Upstream takes the target user's numeric id, not its name — and uint64-as-string, so it is validated - // by shape and passed through as a string rather than parsed. - const userId = typeof body.userId === 'string' ? body.userId.trim() : ''; - if (!/^\d+$/.test(userId)) return badRequest('userId must be numeric'); - // Moving a node changes which ACL rules and tag ownership apply to it — the routes it advertises and - // the tags it carries stay put, but what they now MEAN can differ. The UI says so before asking. - await client.call(`/api/v1/node/${encodeURIComponent(id)}/user`, { method: 'POST', body: { user: userId } }); - return Response.json({ node: await getNode(client, id) }); - } - - if (action === 'expire') { - // Expires the node's key, forcing it to re-authenticate. Not a delete: the node stays registered. - await client.call(`/api/v1/node/${encodeURIComponent(id)}/expire`, { method: 'POST' }); - return Response.json({ node: await getNode(client, id) }); - } - - return notFound(); -} - -/** Dispatch `/_officer/nodes/...`. `rest` is the path after `nodes`. */ -export async function handleNodesRoute(ctx: OfficerContext, rest: string[]): Promise { - if (rest.length === 0) { - if (ctx.req.method !== 'GET') return methodNotAllowed(); - return listNodes(ctx); - } - if (rest.length > 2) return notFound(); - - const id = rest[0]; - // Upstream ids are uint64-as-string. Validate the shape without parsing — Number() would lose precision. - if (!id || !/^\d+$/.test(id)) return badRequest('node id must be numeric'); - - return handleNodeAction({ ctx, id, action: rest[1] }); -} diff --git a/plugins/offscale/sidecar/normalize.ts b/plugins/offscale/sidecar/normalize.ts deleted file mode 100644 index fc96f8ab..00000000 --- a/plugins/offscale/sidecar/normalize.ts +++ /dev/null @@ -1,187 +0,0 @@ -// Officer-shaped views of Headscale's admin API objects, and the quirk handling that gets us there. -// -// Headscale's REST layer is a gRPC gateway marshalling protobuf, which leaks in three ways we normalize -// here so nothing downstream has to know: -// -// 1. Every uint64 is a JSON STRING. Ids stay strings end to end — never Number() them, that breaks -// silently above 2^53 and Headscale's ids are database-assigned, not small by contract. -// 2. Unset timestamps are the protobuf zero value, serialized as '0001-01-01T00:00:00Z' rather than -// omitted. Rendered naively that reads as the year 1 — it means "never", so it becomes null. -// 3. EmitUnpopulated means absent repeated fields arrive as [] and absent messages as null; there is no -// way to distinguish "unset" from "empty", so every accessor tolerates both. - -/** Protobuf's zero timestamp. Headscale sends this for "never expires", "never seen", and friends. */ -const ZERO_TIME = '0001-01-01T00:00:00Z'; - -/** An upstream timestamp as an ISO string, or null when it is unset/the protobuf zero value. */ -export function isoOrNull(raw: unknown): string | null { - if (typeof raw !== 'string' || !raw || raw === ZERO_TIME) return null; - const ms = Date.parse(raw); - if (Number.isNaN(ms)) return null; - // Some builds emit years far outside anything meaningful; treat pre-1971 as the sentinel too. - return ms < 31_536_000_000 ? null : new Date(ms).toISOString(); -} - -const str = (raw: unknown): string => (typeof raw === 'string' ? raw : ''); -const strArray = (raw: unknown): string[] => - Array.isArray(raw) ? raw.filter((v): v is string => typeof v === 'string') : []; - -export type UpstreamUser = Record; -export type UpstreamNode = Record; -export type UpstreamPreAuthKey = Record; - -export type OfficerUser = { - id: string; - name: string; - displayName: string | null; - email: string | null; - /** The OIDC provider, when the user came from one. Null for CLI/API-created users. */ - provider: string | null; - profilePicUrl: string | null; - createdAt: string | null; -}; - -export function toUser(raw: UpstreamUser | null | undefined): OfficerUser | null { - if (!raw || typeof raw !== 'object') return null; - const id = str(raw.id); - if (!id) return null; - return { - id, - name: str(raw.name), - displayName: str(raw.displayName) || null, - email: str(raw.email) || null, - provider: str(raw.provider) || null, - profilePicUrl: str(raw.profilePicUrl) || null, - createdAt: isoOrNull(raw.createdAt), - }; -} - -export type OfficerNode = { - id: string; - /** The name Headscale actually uses in the tailnet — givenName when set, otherwise the reported hostname. */ - name: string; - hostname: string; - user: OfficerUser | null; - ipAddresses: string[]; - online: boolean; - lastSeen: string | null; - /** When the node's key expires and it must re-authenticate. Null means it never expires. */ - expiry: string | null; - createdAt: string | null; - /** How the node joined: 'authkey' | 'cli' | 'oidc' | 'unknown'. */ - registerMethod: string; - tags: string[]; - /** Routes the node advertises. */ - availableRoutes: string[]; - /** The subset the admin has approved — the writable one. */ - approvedRoutes: string[]; - /** Routes actually in effect (approved ∩ available, as Headscale computes it). */ - subnetRoutes: string[]; - /** True when the node advertises an exit node route. Purely derived, for the UI's badge. */ - isExitNode: boolean; -}; - -const EXIT_ROUTES = new Set(['0.0.0.0/0', '::/0']); - -const REGISTER_METHODS: Record = { - REGISTER_METHOD_AUTH_KEY: 'authkey', - REGISTER_METHOD_CLI: 'cli', - REGISTER_METHOD_OIDC: 'oidc', -}; - -export function toNode(raw: UpstreamNode): OfficerNode { - const givenName = str(raw.givenName); - const hostname = str(raw.name); - const availableRoutes = strArray(raw.availableRoutes); - return { - id: str(raw.id), - name: givenName || hostname, - hostname, - user: toUser(raw.user as UpstreamUser), - ipAddresses: strArray(raw.ipAddresses), - online: raw.online === true, - lastSeen: isoOrNull(raw.lastSeen), - expiry: isoOrNull(raw.expiry), - createdAt: isoOrNull(raw.createdAt), - registerMethod: REGISTER_METHODS[str(raw.registerMethod)] ?? 'unknown', - tags: strArray(raw.tags), - availableRoutes, - approvedRoutes: strArray(raw.approvedRoutes), - subnetRoutes: strArray(raw.subnetRoutes), - isExitNode: availableRoutes.some((r) => EXIT_ROUTES.has(r)), - }; -} - -export type OfficerPreAuthKey = { - id: string; - /** - * The usable secret. Non-null ONLY on the creation response — the list path nulls it unconditionally, - * so a secret can never reach the browser except at the moment it is created and must be shown once. - */ - key: string | null; - /** A never-usable label for identifying a key in a list, e.g. `hskey-auth-a1b2c3-***`. */ - keyDisplay: string; - user: OfficerUser | null; - reusable: boolean; - ephemeral: boolean; - used: boolean; - expiration: string | null; - createdAt: string | null; - aclTags: string[]; - /** Derived lifecycle, so every surface agrees on what "spent" means. */ - status: 'active' | 'used' | 'expired'; -}; - -/** - * A display label that is never a usable secret. - * - * Headscale 0.28+ stores keys bcrypt-hashed and lists them already masked as `hskey-auth--***`. - * But keys created BEFORE 0.28 are still plaintext in its database, and `PreAuthKey.Proto()` returns those - * in full from the list endpoint "for backwards compatibility" — its own source carries a TODO about - * hiding them. So a list response on a server with history in it really does contain live secrets. We mask - * anything that isn't already masked rather than trusting the upstream to have done it. - */ -function displayLabel(key: string): string { - if (!key) return '(no key)'; - if (key.endsWith('***')) return key; - return `${key.slice(0, 6)}…-***`; -} - -type ToPreAuthKeyOptions = { - /** - * True only on the creation response, where the secret is the entire point and exists nowhere else. - * Everywhere else this is false and the secret is dropped before it can reach a cache or a browser. - */ - reveal: boolean; -}; - -export function toPreAuthKey(raw: UpstreamPreAuthKey, { reveal }: ToPreAuthKeyOptions): OfficerPreAuthKey { - const expiration = isoOrNull(raw.expiration); - const reusable = raw.reusable === true; - const used = raw.used === true; - const key = str(raw.key); - - // A reusable key stays usable after a node has claimed it, so `used` alone doesn't mean spent. - const expired = !!expiration && Date.parse(expiration) < Date.now(); - const status: OfficerPreAuthKey['status'] = expired ? 'expired' : used && !reusable ? 'used' : 'active'; - - return { - id: str(raw.id), - key: reveal ? key || null : null, - keyDisplay: displayLabel(key), - user: toUser(raw.user as UpstreamUser), - reusable, - ephemeral: raw.ephemeral === true, - used, - expiration, - createdAt: isoOrNull(raw.createdAt), - aclTags: strArray(raw.aclTags), - status, - }; -} - -/** Read an array field out of a gateway response, tolerating the null/absent forms. */ -export function arrayField(body: unknown, field: string): Record[] { - const value = (body as Record | null)?.[field]; - return Array.isArray(value) ? (value.filter((v) => v && typeof v === 'object') as Record[]) : []; -} diff --git a/plugins/offscale/sidecar/policy.ts b/plugins/offscale/sidecar/policy.ts deleted file mode 100644 index 8a5a3bd2..00000000 --- a/plugins/offscale/sidecar/policy.ts +++ /dev/null @@ -1,115 +0,0 @@ -import type { OfficerContext } from './routes'; -import { badRequest, methodNotAllowed, readJson } from './routes'; -import { HeadscaleError } from './client'; -import { activeClient } from './active'; -import { handlePolicyAssistRoute } from './assist'; - -// The ACL policy — /_officer/policy. One HuJSON document that decides which node may reach which, so it is -// the highest-consequence thing this app can write and the only place a typo silently partitions a network. -// -// Three upstream behaviours drive the shape of this file. -// -// 1. **Readable always, writable sometimes.** Headscale can keep its policy in a file (`policy.mode: file`) -// instead of the database, and then the API still SERVES it — a GET returns the file's contents quite -// happily — but a PUT is refused with "update is disabled for modes other than 'database'". Verified -// against a live server, and it means the mode CANNOT be inferred from a read. There is no endpoint -// that reports it either. So this route makes no claim about writability up front; the first save is -// what finds out, and a refusal is a 409 the UI turns into a persistent read-only banner. -// -// 2. **Validation happens on PUT, in Headscale, and its message is the whole value.** It parses the -// HuJSON, resolves every group and tag reference, and rejects the write with a line and column or a -// "group not defined" naming the offender. Officer must not pre-validate: a second, weaker parser here -// would reject documents Headscale accepts and — worse — accept ones it rejects, and its opinion would -// be the one shown. So the text goes up untouched and Headscale's verdict comes back verbatim. -// -// 3. **Both of those arrive as HTTP 500** from grpc-gateway, which the client layer normally generalizes -// to "headscale error". `HeadscaleError.detail` is how the real message survives that; see client.ts. - -/** - * Does this failure mean "writing is turned off here", as opposed to "your document is wrong"? - * - * Matched on the message because Headscale gives no code to match on. Deliberately broad: a false positive - * costs a slightly-wrong banner over a message the owner can still read, while a false negative would tell - * someone their perfectly good ACL was rejected and send them hunting for a syntax error that isn't there. - */ -function isWriteDisabled(detail: string): boolean { - const text = detail.toLowerCase(); - if (text.includes('disabled')) return true; - return text.includes('file') && (text.includes('policy') || text.includes('mode')); -} - -type PolicyBody = { policy?: unknown; updatedAt?: unknown }; - -const asText = (value: unknown) => (typeof value === 'string' ? value : ''); -const asDate = (value: unknown) => (typeof value === 'string' && value && !value.startsWith('0001-') ? value : null); - -/** - * `GET /_officer/policy`. - * - * Answers 200 for every state a running server can be in, including "there is no policy yet" — a fresh - * Headscale has none, and an empty editor is both the honest rendering of that and the thing the owner - * needs to start typing into. Only an unreachable server is an error, because only that leaves nothing - * to say. Note there is no `mode` here on purpose: see the header. - */ -async function getPolicy(ctx: OfficerContext): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - try { - const body = await client.call('/api/v1/policy'); - return Response.json({ policy: asText(body.policy), updatedAt: asDate(body.updatedAt) }); - } catch (err) { - if (!(err instanceof HeadscaleError)) throw err; - const detail = err.detail ?? err.message; - if (err.status === 404 || detail.toLowerCase().includes('not found')) { - return Response.json({ policy: '', updatedAt: null }); - } - throw err; - } -} - -/** - * `PUT /_officer/policy {policy}`. - * - * The body is sent up byte for byte — no trimming, no reformatting, no parse. Comments and layout are load - * bearing in a hand-maintained ACL, and re-serializing would destroy both. - */ -async function putPolicy(ctx: OfficerContext): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - const body = await readJson(ctx.req); - if (!body) return badRequest('expected a JSON body'); - if (typeof body.policy !== 'string') return badRequest('policy must be a string'); - // An empty document would be accepted by some Headscale versions and lock every node out of every other - // one. Deleting a policy is not something to do by leaving a textarea blank and pressing save. - if (!body.policy.trim()) return badRequest('the policy is empty — that would deny every connection'); - - try { - const saved = await client.call('/api/v1/policy', { method: 'PUT', body: { policy: body.policy } }); - // Headscale echoes what it stored; fall back to what we sent if it echoes nothing, so a successful save - // never blanks the editor. - return Response.json({ policy: asText(saved.policy) || body.policy, updatedAt: asDate(saved.updatedAt) }); - } catch (err) { - if (!(err instanceof HeadscaleError)) throw err; - const detail = err.detail ?? err.message; - - if (isWriteDisabled(detail)) { - return Response.json({ error: detail, code: 'policy_read_only' }, { status: 409 }); - } - // Everything else on a PUT is Headscale rejecting this document: a syntax error with a position, an - // unresolvable group, an unknown tag owner. 422 rather than 502 — the request is the problem, and the - // message is the one thing that will fix it. - return Response.json({ error: detail, code: 'policy_rejected' }, { status: 422 }); - } -} - -/** Dispatch `/_officer/policy`. One policy per server, plus the drafting assistant beside it. */ -export async function handlePolicyRoute(ctx: OfficerContext, rest: string[]): Promise { - // `/policy/assist` proposes a document; it never writes one. See assist.ts. - if (rest[0] === 'assist') return handlePolicyAssistRoute(ctx, rest.slice(1)); - if (rest.length > 0) return badRequest('unexpected path'); - if (ctx.req.method === 'GET') return getPolicy(ctx); - if (ctx.req.method === 'PUT') return putPolicy(ctx); - return methodNotAllowed(); -} diff --git a/plugins/offscale/sidecar/routes.ts b/plugins/offscale/sidecar/routes.ts deleted file mode 100644 index c939de7f..00000000 --- a/plugins/offscale/sidecar/routes.ts +++ /dev/null @@ -1,80 +0,0 @@ -import { HeadscaleError } from './client'; -import { handleServersRoute } from './servers'; -import { handleNodesRoute } from './nodes'; -import { handleUsersRoute } from './users'; -import { handleKeysRoute } from './keys'; -import { handlePolicyRoute } from './policy'; -import { handleEnrollRoute } from './enroll'; -import { handleSshTestRoute } from './ssh'; -import { handleCompanionRoute } from './companion'; - -// Officer-owned routes for the headscale sidecar — the entire feature surface lives under /_officer/. -// -// Nothing here is a passthrough. The shapes the UI receives are stable and Officer-shaped, ids stay strings, -// dates are normalized, and anything needing more than one upstream call (device counts per user, pre-auth -// keys grouped by user, read-modify-write of a node's approved route set) resolves here rather than in the -// browser. That is the whole reason the sidecar exists: see rule 5 in SIDECAR_ARCHITECTURE.md. - -export type OfficerContext = { req: Request; url: URL; userId: number }; - -/** 400 with a machine-readable reason. */ -export const badRequest = (error: string) => Response.json({ error }, { status: 400 }); -/** 404 for an unknown /_officer/ path or a missing object. */ -export const notFound = (error = 'not found') => Response.json({ error }, { status: 404 }); -/** 405 when the path exists but the verb doesn't. */ -export const methodNotAllowed = () => Response.json({ error: 'method not allowed' }, { status: 405 }); - -/** Parse a JSON request body, or null when there isn't one / it isn't an object. */ -export async function readJson(req: Request): Promise | null> { - const body = await req.json().catch(() => null); - return body && typeof body === 'object' && !Array.isArray(body) ? (body as Record) : null; -} - -/** - * Dispatch an /_officer/* request. Returns null when nothing matches, which the caller turns into a 404. - * - * The platform injects X-Officer-User after authenticating the owner. We bind loopback only, so its presence - * is the trust signal — a request without it did not come through the platform. - */ -export async function handleOfficerRoute(req: Request, url: URL): Promise { - const officerUser = req.headers.get('X-Officer-User'); - if (!officerUser) return Response.json({ error: 'missing X-Officer-User' }, { status: 401 }); - - const userId = Number(officerUser); - if (!Number.isInteger(userId) || userId <= 0) return badRequest('invalid X-Officer-User'); - - const segments = url.pathname.slice('/_officer/'.length).split('/').filter(Boolean); - if (segments.length === 0) return null; - - const ctx: OfficerContext = { req, url, userId }; - - try { - switch (segments[0]) { - case 'servers': - return await handleServersRoute(ctx, segments.slice(1)); - // The domain routes below all act on the ACTIVE server — see active.ts for why that isn't a param. - case 'nodes': - return await handleNodesRoute(ctx, segments.slice(1)); - case 'users': - return await handleUsersRoute(ctx, segments.slice(1)); - case 'keys': - return await handleKeysRoute(ctx, segments.slice(1)); - case 'policy': - return await handlePolicyRoute(ctx, segments.slice(1)); - case 'enroll': - return await handleEnrollRoute(ctx, segments.slice(1)); - // Not a Headscale call at all — a local `ssh` reachability probe for the console. See ssh.ts. - case 'ssh-test': - return await handleSshTestRoute(ctx, segments.slice(1)); - // The active server's Officer Companion: container health, logs and lifecycle. See companion.ts. - case 'companion': - return await handleCompanionRoute(ctx, segments.slice(1)); - default: - return null; - } - } catch (err) { - // Upstream failures carry their own status; everything else is ours and is a 500 the caller logs. - if (err instanceof HeadscaleError) return Response.json({ error: err.message }, { status: err.status }); - throw err; - } -} diff --git a/plugins/offscale/sidecar/servers.ts b/plugins/offscale/sidecar/servers.ts deleted file mode 100644 index 6d9c780c..00000000 --- a/plugins/offscale/sidecar/servers.ts +++ /dev/null @@ -1,201 +0,0 @@ -import type { OfficerContext } from './routes'; -import { - listHeadscaleServers, - createHeadscaleServer, - updateHeadscaleServer, - setActiveHeadscaleServer, - deleteHeadscaleServer, - getHeadscaleCredentials, - recordHeadscaleProbe, -} from '../db/queries'; -import { createClient, HeadscaleError } from './client'; -import { probeVersion, MIN_VERSION_LABEL } from './version'; -import { badRequest, notFound, methodNotAllowed } from './routes'; -import { normalizeSshHost } from './ssh'; - -// Server registry routes — /_officer/servers/*. Officer manages any number of Headscale servers; the owner -// registers each with a URL and an admin API key generated on that server, and one is active at a time. -// -// Registration VALIDATES before it saves, in two steps, because a bad registration is otherwise only -// discovered later as a confusing failure on some unrelated screen: -// 1. unauthenticated GET /version — proves something Headscale-shaped is there and enforces the >=0.29 floor -// 2. an authenticated call — proves the key actually works -// Neither step is skippable, and a rejected registration is never written. - -/** Normalize a user-supplied base URL, or null if it isn't a usable http(s) origin. */ -function normalizeUrl(raw: unknown): string | null { - if (typeof raw !== 'string' || !raw.trim()) return null; - let candidate = raw.trim(); - // Bare host/port is the most common paste; assume https rather than rejecting it. - if (!/^https?:\/\//i.test(candidate)) candidate = `https://${candidate}`; - let parsed: URL; - try { - parsed = new URL(candidate); - } catch { - return null; - } - if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null; - // Trailing slash would produce `//api/v1/...`; query/hash are meaningless on a base URL. - return `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}`; -} - -function requireString(value: unknown, field: string): string | Response { - if (typeof value !== 'string' || !value.trim()) return badRequest(`${field} is required`); - return value.trim(); -} - -/** - * Confirm a URL+key pair is a supported, reachable Headscale we can authenticate against. - * Returns the observed version on success, or a ready-to-send error Response. - */ -async function validateServer(url: string, apiKey: string): Promise { - const probe = await probeVersion(url); - if (!probe.ok) return badRequest(probe.error); - if (probe.supported === false) { - return badRequest(`Headscale ${probe.version} is not supported — Officer requires ${MIN_VERSION_LABEL} or newer`); - } - - // Cheapest authenticated GET whose path is stable across releases, and the same call Headscale's own - // clients use to test a key. A wrong key surfaces here as HeadscaleError(502, 'rejected the stored key'). - const client = createClient({ id: 0, name: 'probe', url, apiKey }); - try { - await client.call('/api/v1/apikey'); - } catch (err) { - if (err instanceof HeadscaleError) { - return badRequest(err.status === 502 ? 'the API key was rejected by that server' : err.message); - } - throw err; - } - return probe.version; -} - -async function handleCollection(ctx: OfficerContext): Promise { - const { req, userId } = ctx; - - if (req.method === 'GET') { - return Response.json({ servers: await listHeadscaleServers(userId) }); - } - - if (req.method === 'POST') { - const body = (await req.json().catch(() => null)) as Record | null; - if (!body) return badRequest('expected a JSON body'); - - const url = normalizeUrl(body.url); - if (!url) return badRequest('url must be a valid http(s) URL'); - const apiKey = requireString(body.apiKey, 'apiKey'); - if (apiKey instanceof Response) return apiKey; - // The name is a label only; default it to the host so registration needs just a URL and a key. - const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim() : new URL(url).host; - // Optional, and never validated by connecting: registration should not fail because a box is rebooting. - const sshHost = normalizeSshHost(body.sshHost); - if (sshHost instanceof Response) return sshHost; - - const validated = await validateServer(url, apiKey); - if (validated instanceof Response) return validated; - - // First registration becomes active, so the owner is never left with servers but none selected. - const existing = await listHeadscaleServers(userId); - const server = await createHeadscaleServer({ - userId, - name, - url, - apiKey, - version: validated, - sshHost, - activate: existing.length === 0, - }); - return Response.json({ server }, { status: 201 }); - } - - return methodNotAllowed(); -} - -async function handleOne(ctx: OfficerContext, id: number, action: string | undefined): Promise { - const { req, userId } = ctx; - - if (action === 'activate') { - if (req.method !== 'POST') return methodNotAllowed(); - const server = await setActiveHeadscaleServer(userId, id); - return server ? Response.json({ server }) : notFound('no such server'); - } - - if (action === 'health') { - if (req.method !== 'GET') return methodNotAllowed(); - const creds = await getHeadscaleCredentials(userId, id); - if (!creds) return notFound('no such server'); - - const started = Date.now(); - const probe = await probeVersion(creds.url); - if (!probe.ok) return Response.json({ ok: false, error: probe.error, ms: Date.now() - started }); - - // Reachable — confirm the key too, so "healthy" means "we can actually use this server". - try { - await createClient(creds).call('/api/v1/apikey'); - } catch (err) { - const message = err instanceof HeadscaleError ? err.message : 'upstream error'; - return Response.json({ ok: false, version: probe.version, error: message, ms: Date.now() - started }); - } - - await recordHeadscaleProbe(userId, id, probe.version); - return Response.json({ ok: true, version: probe.version, supported: probe.supported, ms: Date.now() - started }); - } - - if (action !== undefined) return notFound(); - - if (req.method === 'PATCH') { - const body = (await req.json().catch(() => null)) as Record | null; - if (!body) return badRequest('expected a JSON body'); - - const current = await getHeadscaleCredentials(userId, id); - if (!current) return notFound('no such server'); - - let url: string | undefined; - if (body.url !== undefined) { - const normalized = normalizeUrl(body.url); - if (!normalized) return badRequest('url must be a valid http(s) URL'); - url = normalized; - } - let apiKey: string | undefined; - if (body.apiKey !== undefined) { - const parsed = requireString(body.apiKey, 'apiKey'); - if (parsed instanceof Response) return parsed; - apiKey = parsed; - } - const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim() : undefined; - // Absent = leave it; '' or null = clear the console target. normalizeSshHost collapses both to null. - let sshHost: string | null | undefined; - if (body.sshHost !== undefined) { - const parsed = normalizeSshHost(body.sshHost); - if (parsed instanceof Response) return parsed; - sshHost = parsed; - } - - // Re-validate whenever either half of the credentials moves — a saved-but-broken server is the exact - // state registration works hard to prevent, and an edit can reintroduce it. - if (url !== undefined || apiKey !== undefined) { - const validated = await validateServer(url ?? current.url, apiKey ?? current.apiKey); - if (validated instanceof Response) return validated; - } - - const server = await updateHeadscaleServer(userId, id, { name, url, apiKey, sshHost }); - return server ? Response.json({ server }) : notFound('no such server'); - } - - if (req.method === 'DELETE') { - const deleted = await deleteHeadscaleServer(userId, id); - return deleted ? new Response(null, { status: 204 }) : notFound('no such server'); - } - - return methodNotAllowed(); -} - -/** Dispatch `/_officer/servers/...`. `rest` is the path after `servers`. */ -export async function handleServersRoute(ctx: OfficerContext, rest: string[]): Promise { - if (rest.length === 0) return handleCollection(ctx); - - const id = Number(rest[0]); - if (!Number.isInteger(id) || id <= 0) return badRequest('server id must be a positive integer'); - if (rest.length > 2) return notFound(); - - return handleOne(ctx, id, rest[1]); -} diff --git a/plugins/offscale/sidecar/ssh.ts b/plugins/offscale/sidecar/ssh.ts deleted file mode 100644 index 7765a7d0..00000000 --- a/plugins/offscale/sidecar/ssh.ts +++ /dev/null @@ -1,86 +0,0 @@ -import { badRequest, methodNotAllowed, readJson, type OfficerContext } from './routes'; - -// SSH console support — the escape hatch for when the Headscale API cannot answer. -// -// Officer never handles a password, a key or a port here. The console runs `ssh ` in the owner's own -// shell, so it authenticates with whatever `~/.ssh` already knows; the only thing stored is where to point it. -// That is why this file has no credential handling at all, and why it must never grow any: the moment Officer -// starts holding a private key or a password, this stops being "run the command you would have run yourself". -// -// The host string is typed into an interactive shell, so it is validated to a conservative charset rather than -// quoted. Quoting would let a plausible-looking value survive to the shell and be someone else's problem; -// rejecting it says which character is wrong while the form is still open. - -/** `user@` plus a hostname or IP. Deliberately no spaces, no flags, no shell metacharacters. */ -const SSH_HOST_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*)?(?:@[A-Za-z0-9](?:[A-Za-z0-9._:-]*)?)?$/; - -/** - * Validate a console target. Returns the trimmed host, null when the field was blank (meaning "no console"), - * or an error Response. - */ -export function normalizeSshHost(raw: unknown): string | null | Response { - if (raw === null) return null; - if (typeof raw !== 'string') return badRequest('sshHost must be a string'); - const host = raw.trim(); - if (!host) return null; - if (host.length > 255) return badRequest('sshHost is too long'); - if (!SSH_HOST_RE.test(host)) { - return badRequest('sshHost must be a plain host, IP or user@host — no ports, flags or spaces'); - } - return host; -} - -type SshProbe = { ok: boolean; error?: string; ms: number }; - -/** - * Prove the machine is reachable with the keys already on this box, without opening a session. - * - * `BatchMode=yes` is what makes this a test rather than a hang: ssh fails instead of prompting for a password - * or a passphrase, which is exactly the outcome the owner needs to see. `accept-new` records an unknown host - * key here rather than leaving the console to open on an interactive "are you sure" prompt the first time — - * it still refuses a CHANGED key, which is the check worth keeping. - */ -export async function probeSsh(host: string): Promise { - const started = Date.now(); - const proc = Bun.spawn( - ['ssh', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', '-o', 'StrictHostKeyChecking=accept-new', host, 'true'], - { stdout: 'ignore', stderr: 'pipe' }, - ); - - // ConnectTimeout only bounds the TCP connect; a server that accepts and then stalls would hang forever. - const timer = setTimeout(() => proc.kill(), 15_000); - let stderr = ''; - try { - [stderr] = await Promise.all([new Response(proc.stderr).text(), proc.exited]); - } finally { - clearTimeout(timer); - } - - const ms = Date.now() - started; - if (proc.exitCode === 0) return { ok: true, ms }; - - // ssh's own first line is the useful one ("Permission denied", "Connection timed out"); the rest is noise. - const first = stderr - .split('\n') - .map((line) => line.trim()) - .find((line) => line && !line.startsWith('Warning: Permanently added')); - return { ok: false, error: first || `ssh exited ${proc.exitCode ?? 'on a signal'}`, ms }; -} - -/** - * `POST /_officer/ssh-test {host}`. Takes the host in the body rather than a server id on purpose: the form - * needs to test a value the owner has typed but not yet saved, which is the case where a typo is still cheap. - */ -export async function handleSshTestRoute(ctx: OfficerContext, rest: string[]): Promise { - if (rest.length > 0) return badRequest('unexpected path'); - if (ctx.req.method !== 'POST') return methodNotAllowed(); - - const body = await readJson(ctx.req); - if (!body) return badRequest('expected a JSON body'); - - const host = normalizeSshHost(body.host); - if (host instanceof Response) return host; - if (!host) return badRequest('host is required'); - - return Response.json(await probeSsh(host)); -} diff --git a/plugins/offscale/sidecar/users.ts b/plugins/offscale/sidecar/users.ts deleted file mode 100644 index 95a9a525..00000000 --- a/plugins/offscale/sidecar/users.ts +++ /dev/null @@ -1,104 +0,0 @@ -import type { OfficerContext } from './routes'; -import { badRequest, notFound, methodNotAllowed, readJson } from './routes'; -import { activeClient } from './active'; -import { toUser, toNode, arrayField, type OfficerUser } from './normalize'; - -// User routes — /_officer/users/*. A Headscale "user" is a namespace that owns nodes and pre-auth keys. -// -// The list is enriched with a node count, which the admin API does not provide: deleting a user takes its -// nodes with it, so "3 nodes" next to the delete button is the difference between an informed action and a -// surprise. That is one extra upstream call for the whole list, not one per user. - -export type UserWithCounts = OfficerUser & { nodeCount: number; onlineCount: number }; - -async function listUsers(ctx: OfficerContext): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - const [userBody, nodeBody] = await Promise.all([client.call('/api/v1/user'), client.call('/api/v1/node')]); - - const nodes = arrayField(nodeBody, 'nodes').map(toNode); - const counts = new Map(); - for (const node of nodes) { - const id = node.user?.id; - if (!id) continue; - const entry = counts.get(id) ?? { total: 0, online: 0 }; - entry.total += 1; - if (node.online) entry.online += 1; - counts.set(id, entry); - } - - const users: UserWithCounts[] = arrayField(userBody, 'users') - .map(toUser) - .filter((u): u is OfficerUser => !!u) - .map((u) => ({ ...u, nodeCount: counts.get(u.id)?.total ?? 0, onlineCount: counts.get(u.id)?.online ?? 0 })) - .sort((a, b) => a.name.localeCompare(b.name)); - - return Response.json({ users }); -} - -async function createUser(ctx: OfficerContext): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - const body = await readJson(ctx.req); - if (!body) return badRequest('expected a JSON body'); - const name = typeof body.name === 'string' ? body.name.trim() : ''; - if (!name) return badRequest('name is required'); - - const created = await client.call<{ user?: Record }>('/api/v1/user', { - method: 'POST', - body: { - name, - displayName: typeof body.displayName === 'string' ? body.displayName.trim() : undefined, - email: typeof body.email === 'string' ? body.email.trim() : undefined, - }, - }); - return Response.json({ user: toUser(created.user) }, { status: 201 }); -} - -type UserActionParams = { ctx: OfficerContext; id: string; action: string | undefined }; - -async function handleUserAction({ ctx, id, action }: UserActionParams): Promise { - const client = await activeClient(ctx.userId); - if (client instanceof Response) return client; - - if (action === 'rename') { - if (ctx.req.method !== 'POST') return methodNotAllowed(); - const body = await readJson(ctx.req); - if (!body) return badRequest('expected a JSON body'); - const name = typeof body.name === 'string' ? body.name.trim() : ''; - if (!name) return badRequest('name is required'); - // Rename takes both the id and the new name in the path — encode or a '/' becomes a routing accident. - const renamed = await client.call<{ user?: Record }>( - `/api/v1/user/${encodeURIComponent(id)}/rename/${encodeURIComponent(name)}`, - { method: 'POST' }, - ); - return Response.json({ user: toUser(renamed.user) }); - } - - if (action !== undefined) return notFound(); - - if (ctx.req.method === 'DELETE') { - // Headscale refuses to delete a user that still owns nodes, with a message the UI relays verbatim. - await client.call(`/api/v1/user/${encodeURIComponent(id)}`, { method: 'DELETE' }); - return new Response(null, { status: 204 }); - } - - return methodNotAllowed(); -} - -/** Dispatch `/_officer/users/...`. `rest` is the path after `users`. */ -export async function handleUsersRoute(ctx: OfficerContext, rest: string[]): Promise { - if (rest.length === 0) { - if (ctx.req.method === 'GET') return listUsers(ctx); - if (ctx.req.method === 'POST') return createUser(ctx); - return methodNotAllowed(); - } - if (rest.length > 2) return notFound(); - - const id = rest[0]; - if (!id || !/^\d+$/.test(id)) return badRequest('user id must be numeric'); - - return handleUserAction({ ctx, id, action: rest[1] }); -} diff --git a/plugins/offscale/sidecar/version.ts b/plugins/offscale/sidecar/version.ts deleted file mode 100644 index cd902153..00000000 --- a/plugins/offscale/sidecar/version.ts +++ /dev/null @@ -1,79 +0,0 @@ -// Headscale version detection and the supported floor. -// -// Officer targets Headscale >= 0.29 and nothing older. That is a deliberate, narrow floor: the admin API -// changed shape repeatedly below it — identifiers went name→numeric at 0.26, `/api/v1/routes` was removed at -// 0.26 in favour of node-owned route sets, `forcedTags`/`validTags` collapsed into `tags` at 0.28, pre-auth -// key expiry became id-based at 0.28, and MoveNode was removed at 0.28. Supporting 0.23–0.28 would mean -// carrying several incompatible data models; refusing them at registration time costs one probe. -// -// Detection uses the server's own unauthenticated `GET /version`, which exists in 0.28 and 0.29 and sits at -// the root — NOT under /api/v1, and not behind the bearer middleware. Do not confuse it with the three -// other similarly-named endpoints: `GET /health` (root, unauthenticated, `{status:'pass'}`) and -// `GET /api/v1/health` (authenticated, `{databaseConnectivity:true}`) carry no version at all. - -export const MIN_MAJOR = 0; -export const MIN_MINOR = 29; -export const MIN_VERSION_LABEL = '0.29'; - -const PROBE_TIMEOUT_MS = 8000; - -export type VersionProbe = - | { ok: true; version: string; supported: true } - /** Reached the server but can't judge the version — self-built images report the literal 'dev'. */ - | { ok: true; version: string; supported: 'unknown' } - | { ok: true; version: string; supported: false } - | { ok: false; error: string }; - -/** `major.minor` from a Headscale version string, or null when it isn't semver (e.g. the literal 'dev'). */ -export function parseVersion(raw: string): { major: number; minor: number } | null { - const m = raw - .trim() - .replace(/^v/, '') - .match(/^(\d+)\.(\d+)/); - if (!m) return null; - return { major: Number(m[1]), minor: Number(m[2]) }; -} - -/** Whether a parsed version is at or above the supported floor. */ -export function meetsFloor(v: { major: number; minor: number }): boolean { - if (v.major !== MIN_MAJOR) return v.major > MIN_MAJOR; - return v.minor >= MIN_MINOR; -} - -/** - * Probe a base URL's `GET /version`. Unauthenticated, so this also doubles as the reachability check during - * registration — it tells us "is there a Headscale here at all" before we bother validating a key. - * - * An unparseable version is reported as `supported: 'unknown'` rather than rejected: a server built without - * VCS build info reports 'dev', and refusing those would lock out legitimately self-built deployments. - */ -export async function probeVersion(baseUrl: string): Promise { - let res: Response; - try { - res = await fetch(`${baseUrl}/version`, { - headers: { accept: 'application/json' }, - signal: AbortSignal.timeout(PROBE_TIMEOUT_MS), - }); - } catch { - return { ok: false, error: 'server unreachable' }; - } - - if (!res.ok) { - // A Headscale that answers /version with a non-2xx isn't one we can identify. Most often this is a URL - // pointing at a reverse proxy or an unrelated service rather than at Headscale itself. - return { ok: false, error: `GET /version returned ${res.status} — is this a Headscale server?` }; - } - - let version: string; - try { - const body = (await res.json()) as { version?: unknown }; - if (typeof body.version !== 'string' || !body.version) return { ok: false, error: 'no version in response' }; - version = body.version; - } catch { - return { ok: false, error: 'GET /version did not return JSON' }; - } - - const parsed = parseVersion(version); - if (!parsed) return { ok: true, version, supported: 'unknown' }; - return { ok: true, version, supported: meetsFloor(parsed) }; -} diff --git a/plugins/offscale/web/Cards.tsx b/plugins/offscale/web/Cards.tsx deleted file mode 100644 index a9f9fe52..00000000 --- a/plugins/offscale/web/Cards.tsx +++ /dev/null @@ -1,103 +0,0 @@ -import type { ReactNode } from 'react'; - -// Shared visual language for the /headscale panels, matching the /soulseek grouped views: almost-black -// cards on hairline white borders. Kept local to the app so the look changes in one place. - -export const Card = ({ children }: { children: ReactNode }) => ( -
{children}
-); - -export const SectionHeader = ({ - title, - subtitle, - action, -}: { - title: string; - subtitle?: string; - action?: ReactNode; -}) => ( -
-
-

{title}

- {subtitle &&

{subtitle}

} -
- {action &&
{action}
} -
-); - -type ButtonProps = { - children: ReactNode; - onClick?: () => void; - type?: 'button' | 'submit'; - variant?: 'primary' | 'ghost' | 'danger'; - disabled?: boolean; - title?: string; -}; - -const VARIANTS: Record, string> = { - primary: 'border-primary/40 bg-primary/15 text-primary hover:bg-primary/25', - ghost: 'border-white/10 bg-white/[0.02] text-zinc-300 hover:bg-white/10 hover:text-zinc-100', - danger: 'border-red-500/30 bg-red-500/10 text-red-300 hover:bg-red-500/20', -}; - -export const Button = ({ children, onClick, type = 'button', variant = 'ghost', disabled, title }: ButtonProps) => ( - -); - -type FieldProps = { - label: string; - value: string; - onChange: (value: string) => void; - placeholder?: string; - hint?: string; - type?: 'text' | 'password'; - autoFocus?: boolean; -}; - -export const Field = ({ label, value, onChange, placeholder, hint, type = 'text', autoFocus }: FieldProps) => ( - -); - -/** Tiny status light: green healthy, amber unknown/unverified, red failing. */ -export const Dot = ({ tone }: { tone: 'ok' | 'warn' | 'bad' | 'idle' }) => { - const color = - tone === 'ok' ? 'bg-emerald-400' : tone === 'warn' ? 'bg-amber-400' : tone === 'bad' ? 'bg-red-400' : 'bg-zinc-600'; - return ; -}; - -export const Badge = ({ children, tone = 'neutral' }: { children: ReactNode; tone?: 'neutral' | 'active' }) => ( - - {children} - -); - -export const ErrorNote = ({ children }: { children: ReactNode }) => ( -
- {children} -
-); diff --git a/plugins/offscale/web/ConsoleView.tsx b/plugins/offscale/web/ConsoleView.tsx deleted file mode 100644 index fe932b9d..00000000 --- a/plugins/offscale/web/ConsoleView.tsx +++ /dev/null @@ -1,96 +0,0 @@ -import { useCallback } from 'react'; -import { Link } from 'react-router'; -import { Loader2, TerminalSquare } from 'lucide-react'; -import { headscaleSectionPath } from './shared'; -import { useHeadscaleServers } from './useHeadscaleServers'; -import { TerminalView } from 'officerdev'; -import { Button } from './Cards'; - -// A shell on the machine behind the active Headscale server — the escape hatch for everything the API cannot -// answer (why headscale won't start, what the logs say, whether the disk is full). -// -// It is deliberately the SAME terminal every other panel uses, driven by nothing more than `ssh ` typed -// into a login shell. Officer holds no key, no password and no port: whatever `ssh` on this box can already -// reach, this can reach, and nothing more. If the connection needs a jump host or an odd port, that belongs in -// `~/.ssh/config` as a Host alias — which this field accepts by name. -// -// The session id is derived from the server id rather than minted per panel, so re-opening the Console lands -// back in the shell that is already running and mid-command, and switching servers is a different shell rather -// than the same one re-purposed. TerminalView suppresses its initial input when the sidecar replays a buffer, -// which is what stops a re-attach from typing a second `ssh` inside the first. - -const consoleSessionId = (serverId: number) => `headscale-console-${serverId}`; - -const Centred = ({ children }: { children: React.ReactNode }) => ( -
-
- -
- {children} -
-); - -export const ConsoleView = () => { - const { active, isLoading } = useHeadscaleServers(); - - // The terminal reports its connection state; nothing in this section acts on it yet, but TerminalView wants - // a stable callback and an inline arrow would remount its effect on every render. - const onConnectionChange = useCallback(() => {}, []); - - if (isLoading) { - return ( -
- - Loading servers… -
- ); - } - - if (!active) { - return ( - -
-
No server selected
-

Pick one in the Servers section to open its console.

-
-
- ); - } - - if (!active.sshHost) { - return ( - -
-
No SSH address for {active.name}
-

- Add one on the server to open a shell on the machine behind it. Use the machine's own address rather than - the Headscale hostname — the console is most useful exactly when that name has stopped answering. -

-
- - - -
- ); - } - - return ( -
-
- - - ssh {active.sshHost} · {active.name} - -
- -
- ); -}; diff --git a/plugins/offscale/web/DiagnosticsView.tsx b/plugins/offscale/web/DiagnosticsView.tsx deleted file mode 100644 index 9595d8ce..00000000 --- a/plugins/offscale/web/DiagnosticsView.tsx +++ /dev/null @@ -1,326 +0,0 @@ -import { useEffect, useRef, useState } from 'react'; -import { - Activity, - AlertTriangle, - Loader2, - Play, - PlugZap, - RotateCw, - ScrollText, - Square, - Trash2, - Unplug, -} from 'lucide-react'; -import type { CompanionAction, CompanionContainer, CompanionHealthBody, CompanionVerdict } from './shared'; -import { timeAgo } from './format'; -import { useHeadscaleServers } from './useHeadscaleServers'; -import { - useCompanionAction, - useCompanionHealth, - useCompanionLogStream, - useCompanionLogs, -} from './useHeadscaleCompanion'; -import { Card, SectionHeader, Button, Dot, ErrorNote } from './Cards'; -import { ViewShell } from './ViewShell'; - -// What the admin API structurally cannot tell you: is the container running, what did it log on the way -// down, and can we bring it back. All of it comes from the Officer Companion deployed alongside the server. -// -// The companion is optional and per-server, so "not deployed" is the ordinary case for a server that has -// never had one, and is rendered as an explanation rather than an error. Note the two inversions this -// section is built around: the companion's /health is ALWAYS HTTP 200 (read `verdict`, never the status), -// and an unavailable companion says nothing about Headscale itself — the admin API on the same domain is -// independent and the other sections may be working perfectly. - -const VERDICTS: Record = { - ok: { tone: 'ok', label: 'Healthy', blurb: 'The container is running and Headscale is answering.' }, - degraded: { - tone: 'warn', - label: 'Degraded', - blurb: 'The container is running, but Headscale is not answering properly.', - }, - down: { tone: 'bad', label: 'Down', blurb: 'The container is not running.' }, - unknown: { tone: 'idle', label: 'Unknown', blurb: 'Docker does not know this container.' }, -}; - -const ACTIONS: { id: CompanionAction; label: string; icon: typeof RotateCw; confirm: string }[] = [ - { - id: 'restart', - label: 'Restart', - icon: RotateCw, - confirm: 'Restart the Headscale container? Every node loses its control-plane connection until it is back.', - }, - { - id: 'stop', - label: 'Stop', - icon: Square, - confirm: 'Stop the Headscale container? Every node stays disconnected until you start it again.', - }, - { id: 'start', label: 'Start', icon: Play, confirm: 'Start the Headscale container?' }, -]; - -/** The RFC3339 zero date the companion passes through from docker for a container that never finished. */ -const isZeroDate = (iso: string) => iso.startsWith('0001-'); - -const Row = ({ label, value }: { label: string; value: React.ReactNode }) => ( -
- {label} - {value} -
-); - -const ContainerFacts = ({ container }: { container: CompanionContainer }) => ( -
- - - - {!container.running && !isZeroDate(container.finishedAt) && ( - - )} - -
-); - -/** Evidence, shown only when the verdict is not ok — likely causes first, then the raw tail behind them. */ -const Evidence = ({ health }: { health: CompanionHealthBody }) => { - const causes = health.likelyCauses ?? []; - const recent = health.recentLogs ?? []; - if (causes.length === 0 && recent.length === 0 && !health.healthcheckOutput) return null; - - return ( -
- {causes.length > 0 && ( -
-
- - Likely causes -
-
    - {causes.map((cause) => ( -
  • - {cause} -
  • - ))} -
- {/* The companion reads these out of the logs heuristically. Saying so is the difference between a - hint the owner checks and a diagnosis they trust and then chase down the wrong hole. */} -

Guessed from the logs — treat them as leads, not answers.

-
- )} - - {health.healthcheckOutput && ( -
-
Healthcheck output
-
-            {health.healthcheckOutput}
-          
-
- )} - - {recent.length > 0 && ( -
-
Last lines before now
-
-            {recent.join('\n')}
-          
-
- )} -
- ); -}; - -const TAILS = [100, 500, 2000]; - -const LogViewer = () => { - const [tail, setTail] = useState(200); - const [follow, setFollow] = useState(false); - const snapshot = useCompanionLogs(tail, !follow); - const stream = useCompanionLogStream(follow, tail); - const boxRef = useRef(null); - - const lines = follow ? stream.lines : snapshot.data?.available ? snapshot.data.lines : []; - - // Pin to the bottom while following. Only while following: scrolling a snapshot back to the top and having - // it yanked down again would be the viewer fighting the reader. - useEffect(() => { - if (follow && boxRef.current) boxRef.current.scrollTop = boxRef.current.scrollHeight; - }, [follow, lines.length]); - - const unavailable = !follow && snapshot.data && !snapshot.data.available ? snapshot.data.reason : null; - - return ( - -
-
- - Logs - {follow && ( - - - {stream.live ? 'live' : 'stopped'} - - )} -
- -
- {TAILS.map((n) => ( - - ))} -
- - {follow ? ( - - ) : ( - - )} -
- - {stream.error && ( -
{stream.error}
- )} - {unavailable &&
{unavailable}
} - -
-        {lines.length > 0
-          ? lines.join('\n')
-          : snapshot.isLoading
-            ? 'Loading…'
-            : follow
-              ? 'Waiting for output…'
-              : 'No log lines.'}
-      
-
- ); -}; - -const Lifecycle = ({ running }: { running: boolean | null }) => { - const action = useCompanionAction(); - const [pending, setPending] = useState(null); - - const run = async (id: CompanionAction, confirm: string) => { - if (!window.confirm(confirm)) return; - setPending(id); - try { - await action.mutateAsync(id); - } catch { - /* surfaced from action.error below */ - } finally { - setPending(null); - } - }; - - const result = action.data; - - return ( -
-
- {ACTIONS.map(({ id, label, icon: Icon, confirm }) => ( - - ))} - Acts on the container, not on Officer. -
- - {action.error != null && The action could not be sent.} - {result && !result.available && {result.reason}} - {result && result.available && !result.ok && ( - {result.error ?? 'Docker refused the action.'} - )} - {result && result.available && result.ok && ( -
- {result.action}: {result.result} -
- )} -
- ); -}; - -export const DiagnosticsView = () => { - const { active } = useHeadscaleServers(); - const query = useCompanionHealth(); - const result = query.data; - - return ( - -
- : undefined} - /> - - {result && !result.available ? ( - -
-
- - No companion on this server -
-

- {result.reason}. The Officer Companion is a small service deployed next to Headscale that can see its - container — it is what makes health, logs and restart possible from here. -

-

- This says nothing about Headscale itself: it is served by the same domain but a different process, so - the other sections may be working normally. When the companion is missing, the Console section is the - way in. -

-
-
- ) : result ? ( - <> - -
-
- -
-
-
{VERDICTS[result.health.verdict].label}
-

- {result.health.reason ?? VERDICTS[result.health.verdict].blurb} -

-
-
- -
- - {result.health.probe && } - {result.health.container && } -
- - - -
- - - - ) : null} -
-
- ); -}; diff --git a/plugins/offscale/web/HeadscaleNav.tsx b/plugins/offscale/web/HeadscaleNav.tsx deleted file mode 100644 index 2e14b31d..00000000 --- a/plugins/offscale/web/HeadscaleNav.tsx +++ /dev/null @@ -1,75 +0,0 @@ -import type { LucideIcon } from 'lucide-react'; -import { NavLink } from 'react-router'; -import { Server, Laptop, Users, KeyRound, Smartphone, ShieldCheck, Activity, TerminalSquare } from 'lucide-react'; -import { HEADSCALE_SECTIONS, headscaleSectionPath, type HeadscaleSectionId } from './shared'; -import { useHeadscaleServers } from './useHeadscaleServers'; - -// Lower-left panel of the /headscale workspace: the section list. Which server it all acts on is the panel -// above (HeadscaleServerPicker) — that one mutates, this one navigates, which is why they are separate. -// -// Sections are real links to /headscale/
, not channel writes — so they cmd-click into a new tab, -// survive a reload, and answer the back button. Active state comes from react-router's NavLink rather than -// being derived in JS, per the navigation audit's Phase 4. - -const ICONS: Record = { - servers: Server, - nodes: Laptop, - users: Users, - keys: KeyRound, - invites: Smartphone, - policy: ShieldCheck, - diagnostics: Activity, - console: TerminalSquare, -}; - -const ROW = 'group relative flex items-center gap-3 rounded-lg px-3 py-2 text-left text-sm transition-colors'; - -type SectionBodyProps = { icon: LucideIcon; label: string; selected: boolean }; - -const SectionBody = ({ icon: Icon, label, selected }: SectionBodyProps) => ( - <> - {selected && } - - {label} - -); - -export const HeadscaleNav = () => { - const { active } = useHeadscaleServers(); - - return ( - - ); -}; diff --git a/plugins/offscale/web/HeadscaleServerPicker.tsx b/plugins/offscale/web/HeadscaleServerPicker.tsx deleted file mode 100644 index 9ab54c90..00000000 --- a/plugins/offscale/web/HeadscaleServerPicker.tsx +++ /dev/null @@ -1,60 +0,0 @@ -import { Check, Network, Plus } from 'lucide-react'; -import { Link } from 'react-router'; -import { headscaleSectionPath } from './shared'; -import { useHeadscaleServers } from './useHeadscaleServers'; - -// Top-left panel of the /headscale workspace: which server everything else acts on. -// -// It is its own panel rather than a block inside HeadscaleNav because the two answer different questions — -// "which server" and "which section" — and only one of them is navigation. Activating a server is a mutation -// (a DB write that re-scopes every other query), so these stay buttons with no URL of their own, while the -// section list below is real links. -// -// Every registered server is listed, including when there is only one: the panel's whole job is to say what -// the rest of the screen is talking to, and a picker that hides itself at one server makes that invisible. - -export const HeadscaleServerPicker = () => { - const { servers, active, activate, isLoading } = useHeadscaleServers(); - - return ( -
-
-
- -
-
-
Headscale
-
{active ? active.name : 'no server'}
-
-
- -
- {servers.map((server) => ( - - ))} - - {servers.length === 0 && !isLoading && ( - - - Register a server - - )} -
-
- ); -}; diff --git a/plugins/offscale/web/HeadscaleView.tsx b/plugins/offscale/web/HeadscaleView.tsx deleted file mode 100644 index f1d35bfe..00000000 --- a/plugins/offscale/web/HeadscaleView.tsx +++ /dev/null @@ -1,37 +0,0 @@ -import { useHeadscaleSection } from './useHeadscaleSection'; -import { ServersView } from './ServersView'; -import { NodesView } from './NodesView'; -import { UsersView } from './UsersView'; -import { KeysView } from './KeysView'; -import { InvitesView } from './InvitesView'; -import { PolicyView } from './PolicyView'; -import { DiagnosticsView } from './DiagnosticsView'; -import { ConsoleView } from './ConsoleView'; - -// Right panel of the /headscale workspace — renders the section named by the URL. -// -// Every section except `servers` acts on whichever server is active; each handles the "none selected" case -// itself through ViewShell, so there is no gating to do here. - -export const HeadscaleView = () => { - const section = useHeadscaleSection(); - - switch (section) { - case 'nodes': - return ; - case 'users': - return ; - case 'keys': - return ; - case 'invites': - return ; - case 'policy': - return ; - case 'diagnostics': - return ; - case 'console': - return ; - default: - return ; - } -}; diff --git a/plugins/offscale/web/HeadscaleViewHeader.tsx b/plugins/offscale/web/HeadscaleViewHeader.tsx deleted file mode 100644 index 0a03c196..00000000 --- a/plugins/offscale/web/HeadscaleViewHeader.tsx +++ /dev/null @@ -1,23 +0,0 @@ -import { Network } from 'lucide-react'; -import { useHeadscaleServers } from './useHeadscaleServers'; -import { HEADSCALE_SECTIONS } from './shared'; -import { useHeadscaleSection } from './useHeadscaleSection'; - -// Panel header for the right (headscale-view) panel. Shows the section and, crucially, which server it is -// acting on — with several registered, "delete this node" is only safe if the target is unambiguous. - -export const HeadscaleViewHeader = () => { - const section = useHeadscaleSection(); - const { active } = useHeadscaleServers(); - const label = HEADSCALE_SECTIONS.find((s) => s.id === section)?.label ?? 'Headscale'; - - return ( - <> - - - {label} - {active && · {active.name}} - - - ); -}; diff --git a/plugins/offscale/web/InvitesView.tsx b/plugins/offscale/web/InvitesView.tsx deleted file mode 100644 index 81ca3f58..00000000 --- a/plugins/offscale/web/InvitesView.tsx +++ /dev/null @@ -1,394 +0,0 @@ -import { useEffect, useRef, useState } from 'react'; -import QRCode from 'qrcode'; -import { Check, Copy, Loader2, Plus, QrCode, Share2, Smartphone, Trash2 } from 'lucide-react'; -import type { HeadscaleInvite, HeadscaleInviteCreated, InviteStatus } from './shared'; -import { INVITE_TTL_DEFAULT_SECONDS } from './shared'; -import { useHeadscaleInvites } from './useHeadscaleInvites'; -import { useHeadscaleUsers } from './useHeadscaleData'; -import { headscaleErrorMessage } from './useHeadscaleServers'; -import { fullDate, timeAgo, timeUntil } from './format'; -import { Badge, Button, Card, Dot, ErrorNote, Field } from './Cards'; -import { EmptyBody, ViewShell } from './ViewShell'; -import { copyToClipboard } from 'helpers/clipboard'; - -// Device invites — the admin surface of COMMS/OFFSCALE_INVITE_ENROLLMENT.md §5. -// -// The point of the feature is that the person joining does nothing but tap a link and press Join: no app -// store hunt, no control-server URL typed by hand, no pre-auth key they have no way to generate. The admin -// does all of it here and sends one link. -// -// TWO RULES SHAPE THIS FILE. -// -// 1. The link exists exactly once. Its fragment carries the claim token, and §5 is explicit: never display, -// log or store it beyond the moment it is handed to the admin. So the created invite lives in component -// state only — never in the query cache, never in a URL, never in a toast that outlives the panel — and -// the panel drops it on dismiss. Refreshing the page is meant to lose it; the admin mints another. -// 2. The token is not the key. Nothing here can join a machine to the tailnet: the pre-auth key is minted -// by the server at claim time. A leaked link before it is claimed is revocable, which is the whole -// reason the credential is not in the URL. - -const STATUS_TONE: Record = { - pending: 'warn', - claimed: 'ok', - expired: 'idle', - revoked: 'bad', -}; - -/** Presets rather than a free number: every one is inside the spec's 60s–24h range by construction. */ -const TTL_OPTIONS = [ - { seconds: 300, label: '5 minutes' }, - { seconds: INVITE_TTL_DEFAULT_SECONDS, label: '15 minutes' }, - { seconds: 3600, label: '1 hour' }, - { seconds: 86_400, label: '24 hours' }, -] as const; - -const CopyButton = ({ value, label }: { value: string; label: string }) => { - const [done, setDone] = useState(false); - const copy = () => { - void copyToClipboard(value); - setDone(true); - window.setTimeout(() => setDone(false), 1500); - }; - return ( - - ); -}; - -/** - * The QR, rendered client-side into a canvas. - * - * It never leaves the browser — an image endpoint would put the claim token in a request line and therefore - * in a server log, which is the exact thing the fragment-only link format exists to prevent. Error - * correction stays low so the modules stay large: this is scanned from a phone held next to the screen, not - * printed and posted. - */ -const InviteQr = ({ url }: { url: string }) => { - const canvas = useRef(null); - - useEffect(() => { - if (!canvas.current) return; - void QRCode.toCanvas(canvas.current, url, { errorCorrectionLevel: 'L', margin: 2, width: 220 }); - }, [url]); - - return ; -}; - -type InviteLinkPanelProps = { invite: HeadscaleInviteCreated; onDismiss: () => void }; - -const InviteLinkPanel = ({ invite, onDismiss }: InviteLinkPanelProps) => { - const [showQr, setShowQr] = useState(true); - - // Plain https now — the link lands on a page the companion serves, which bounces into the app. It goes in - // `url` rather than `text` so share targets treat it as a link and preserve the fragment. A cancelled sheet - // rejects — nothing to report there, the link is still on screen. - const share = () => { - void navigator - .share?.({ title: 'Join the tailnet', text: `Tap to join as ${invite.user}`, url: invite.url }) - .catch(() => {}); - }; - - return ( -
-
- -
-
Send this link to the device
-

- It opens OffScale, shows one confirmation screen and joins as{' '} - {invite.user}. Single use, and it stops working{' '} - {timeUntil(invite.expiresAt ?? null)}. Officer does not keep a copy — dismiss this and it is gone. -

-
-
- -
-
- {invite.url} -
- - {showQr && ( -
- -
- )} - -
- - {/* Only where the OS actually has a share sheet — a button that silently does nothing is worse - than no button, and on desktop Chrome/Firefox navigator.share is simply absent. */} - {typeof navigator.share === 'function' && ( - - )} - - -
-
-
- ); -}; - -type CreateInviteFormProps = { onCreated: (invite: HeadscaleInviteCreated) => void; onClose: () => void }; - -const CreateInviteForm = ({ onCreated, onClose }: CreateInviteFormProps) => { - const { users } = useHeadscaleUsers(); - const { create } = useHeadscaleInvites(); - const [user, setUser] = useState(''); - const [note, setNote] = useState(''); - const [ttl, setTtl] = useState(INVITE_TTL_DEFAULT_SECONDS); - const [ephemeral, setEphemeral] = useState(false); - const [tags, setTags] = useState(''); - const [error, setError] = useState(null); - - const submit = async () => { - setError(null); - // The invite API names the Headscale USER, not its uint64 id — the server it is sent to may not be the - // one this list came from by the time it is claimed. - const chosen = user || users[0]?.name; - if (!chosen) return setError('Create a user first — an invite files the joining device under one.'); - - try { - const invite = await create.mutateAsync({ - user: chosen, - ttlSeconds: ttl, - ephemeral, - note: note.trim(), - tags: tags - .split(/[\s,]+/) - .map((t) => t.trim()) - .filter(Boolean), - }); - onCreated(invite); - onClose(); - } catch (err) { - setError(headscaleErrorMessage(err)); - } - }; - - return ( - -
{ - ev.preventDefault(); - void submit(); - }} - className="flex flex-col gap-3 p-4" - > -
Authorize a new device
- - - - - - - - - - - - {error && {error}} - -
- - -
- -
- ); -}; - -type InviteRowProps = { invite: HeadscaleInvite; onError: (message: string) => void }; - -const InviteRow = ({ invite, onError }: InviteRowProps) => { - const { revoke } = useHeadscaleInvites(); - const [confirming, setConfirming] = useState(false); - - const run = async () => { - try { - await revoke.mutateAsync(invite.id); - } catch (err) { - onError(headscaleErrorMessage(err)); - } - }; - - return ( - -
- -
-
- {invite.note || 'Untitled invite'} - {invite.user} - {invite.ephemeral && ephemeral} - {invite.tags?.map((tag) => ( - - {tag} - - ))} -
-
- {invite.status} - {invite.status === 'pending' && ( - · expires {timeUntil(invite.expiresAt ?? null)} - )} - {invite.status === 'claimed' && ( - - · claimed {timeAgo(invite.claimedAt ?? null)} - {invite.claimedFromIp ? ` from ${invite.claimedFromIp}` : ''} - - )} - · created {timeAgo(invite.createdAt ?? null)} -
-
- - {/* Revoking a claimed invite does nothing to the node that used it — that is a separate removal in - Nodes, and conflating the two here would make "revoke" mean two different things. */} - {invite.status === 'pending' && ( -
- {confirming ? ( - <> - - - - ) : ( - - )} -
- )} -
-
- ); -}; - -export const InvitesView = () => { - const { invites, unavailable, isLoading, error } = useHeadscaleInvites(); - const [creating, setCreating] = useState(false); - const [created, setCreated] = useState(null); - const [actionError, setActionError] = useState(null); - - const pending = invites.filter((i) => i.status === 'pending').length; - - return ( - -
-
-
-

Device invites

-

- {unavailable ? 'Not available on this server' : `${pending} pending of ${invites.length}`} -

-
- {!creating && !unavailable && ( - - )} -
- - {/* Most registered servers have no enrolment API, and that is a normal state — the rest of the - Headscale sections work regardless, so this must not read as a broken screen. */} - {unavailable && ( - } - title="This server cannot mint invites" - hint={`${unavailable}. Invites are served by the Officer Companion next to Headscale, because the joining phone has to reach it without an Officer account. Until it is deployed, use a pre-auth key.`} - /> - )} - - {created && setCreated(null)} />} - {creating && setCreating(false)} />} - {actionError && {actionError}} - - {!unavailable && invites.length === 0 && !creating && ( - } - title="No invites yet" - hint="An invite is a link you send to whoever needs to join. They tap it, confirm once, and they are on the tailnet — no key to paste and nothing to configure." - /> - )} - - {invites.map((invite) => ( - - ))} -
-
- ); -}; diff --git a/plugins/offscale/web/KeysView.tsx b/plugins/offscale/web/KeysView.tsx deleted file mode 100644 index e3b25d28..00000000 --- a/plugins/offscale/web/KeysView.tsx +++ /dev/null @@ -1,341 +0,0 @@ -import { useState } from 'react'; -import { KeyRound, Plus, Trash2, TimerOff, Copy, Check, Loader2, ShieldAlert } from 'lucide-react'; -import type { HeadscalePreAuthKey } from './shared'; -import { useHeadscaleKeys, useHeadscaleUsers } from './useHeadscaleData'; -import { useHeadscaleServers, headscaleErrorMessage } from './useHeadscaleServers'; -import { timeAgo, timeUntil, fullDate } from './format'; -import { Card, Button, Field, Badge, Dot, ErrorNote } from './Cards'; -import { ViewShell, EmptyBody } from './ViewShell'; -import { copyToClipboard } from 'helpers/clipboard'; - -// Pre-auth keys — the tokens a machine presents to join the tailnet. -// -// The whole screen is shaped by one fact: Headscale hashes keys, so the secret exists exactly once, in the -// create response. If this view renders it into a list, or lets a re-render drop it, the key is gone and the -// owner has to make another. Hence the show-once panel: it holds the secret in local state, offers the copy -// and the ready-to-paste join command, and only clears on an explicit dismiss. -// -// The list defaults to active keys because a long-lived server accumulates hundreds of spent ones. - -const STATUS_FILTERS = [ - { id: 'active', label: 'Active' }, - { id: 'all', label: 'All' }, -] as const; - -type StatusFilter = (typeof STATUS_FILTERS)[number]['id']; - -const STATUS_TONE = { active: 'ok', used: 'idle', expired: 'bad' } as const; - -const CopyButton = ({ value, label }: { value: string; label: string }) => { - const [done, setDone] = useState(false); - const copy = () => { - void copyToClipboard(value); - setDone(true); - window.setTimeout(() => setDone(false), 1500); - }; - return ( - - ); -}; - -type SecretPanelProps = { secret: string; loginServer: string; onDismiss: () => void }; - -const SecretPanel = ({ secret, loginServer, onDismiss }: SecretPanelProps) => { - const command = `tailscale up --login-server ${loginServer} --authkey ${secret}`; - return ( -
-
- -
-
Copy this key now
-

- Headscale stores it hashed. Once you dismiss this, nothing — not Officer, not the server — can show it - again. -

-
-
-
-
-
Key
-
- {secret} -
-
-
-
Join command
-
- {command} -
-
-
- - - -
-
-
- ); -}; - -type ToggleProps = { checked: boolean; onChange: (value: boolean) => void; label: string; hint: string }; - -const Toggle = ({ checked, onChange, label, hint }: ToggleProps) => ( - -); - -type CreateKeyFormProps = { onCreated: (secret: string) => void; onClose: () => void }; - -const CreateKeyForm = ({ onCreated, onClose }: CreateKeyFormProps) => { - const { users } = useHeadscaleUsers(); - const { create } = useHeadscaleKeys(); - const [userId, setUserId] = useState(''); - const [reusable, setReusable] = useState(false); - const [ephemeral, setEphemeral] = useState(false); - const [days, setDays] = useState('90'); - const [tags, setTags] = useState(''); - const [error, setError] = useState(null); - - const submit = async () => { - setError(null); - const chosen = userId || users[0]?.id; - if (!chosen) return setError('Create a user first — every key belongs to one.'); - const expirationDays = Number(days); - if (!Number.isFinite(expirationDays) || expirationDays <= 0) - return setError('Expiry must be a positive number of days'); - - try { - const result = await create.mutateAsync({ - userId: chosen, - reusable, - ephemeral, - expirationDays, - aclTags: tags - .split(',') - .map((t) => t.trim()) - .filter(Boolean), - }); - if (result.key.key) onCreated(result.key.key); - onClose(); - } catch (err) { - setError(headscaleErrorMessage(err)); - } - }; - - return ( - -
{ - ev.preventDefault(); - void submit(); - }} - className="flex flex-col gap-3 p-4" - > -
New pre-auth key
- - - -
- - -
- - - - - {error && {error}} - -
- - -
- -
- ); -}; - -type KeyRowProps = { entry: HeadscalePreAuthKey; onError: (message: string) => void }; - -const KeyRow = ({ entry, onError }: KeyRowProps) => { - const { expire, remove } = useHeadscaleKeys(); - const [confirming, setConfirming] = useState(false); - const busy = expire.isPending || remove.isPending; - - const run = async (fn: () => Promise) => { - try { - await fn(); - } catch (err) { - onError(headscaleErrorMessage(err)); - } - }; - - return ( - -
- -
-
- {entry.keyDisplay} - {entry.user && {entry.user.name}} - {entry.reusable && reusable} - {entry.ephemeral && ephemeral} - {entry.aclTags.map((tag) => ( - - {tag} - - ))} -
-
- {entry.status} - · expires {timeUntil(entry.expiration)} - · created {timeAgo(entry.createdAt)} -
-
- -
- {entry.status === 'active' && ( - - )} - {confirming ? ( - <> - - - - ) : ( - - )} -
-
-
- ); -}; - -export const KeysView = () => { - const { keys, isLoading, error } = useHeadscaleKeys(); - const { active } = useHeadscaleServers(); - const [creating, setCreating] = useState(false); - const [secret, setSecret] = useState(null); - const [filter, setFilter] = useState('active'); - const [actionError, setActionError] = useState(null); - - const visible = filter === 'all' ? keys : keys.filter((k) => k.status === 'active'); - const activeCount = keys.filter((k) => k.status === 'active').length; - - return ( - -
-
-
-

Pre-auth keys

-

- {activeCount} active of {keys.length} -

-
-
-
- {STATUS_FILTERS.map((option) => ( - - ))} -
- {!creating && ( - - )} -
-
- - {secret && setSecret(null)} />} - {creating && setCreating(false)} />} - {actionError && {actionError}} - - {keys.length === 0 && !creating && ( - } - title="No pre-auth keys" - hint="A key lets a machine join without an interactive login. Create one, then run the join command it gives you." - /> - )} - {keys.length > 0 && visible.length === 0 && ( -
- No active keys. Switch to “All” to see spent and expired ones. -
- )} - - {visible.map((entry) => ( - - ))} -
-
- ); -}; diff --git a/plugins/offscale/web/NodesView.tsx b/plugins/offscale/web/NodesView.tsx deleted file mode 100644 index bdbc4795..00000000 --- a/plugins/offscale/web/NodesView.tsx +++ /dev/null @@ -1,436 +0,0 @@ -import { useState } from 'react'; -import { - Laptop, - Globe, - Trash2, - Pencil, - TimerReset, - Check, - X, - Search, - Copy, - ChevronRight, - UserRound, - ArrowRightLeft, - Tag as TagIcon, -} from 'lucide-react'; -import type { HeadscaleNode } from './shared'; -import { useHeadscaleNodes, useHeadscaleUsers } from './useHeadscaleData'; -import { headscaleErrorMessage } from './useHeadscaleServers'; -import { timeAgo, timeUntil, fullDate } from './format'; -import { Card, Button, Dot, Badge, ErrorNote } from './Cards'; -import { ViewShell, EmptyBody } from './ViewShell'; -import { copyToClipboard } from 'helpers/clipboard'; - -// The nodes section — the machines in the tailnet. -// -// Route approval is the only genuinely dangerous control here, so it is explicit: every route the node -// ADVERTISES is listed, each with its own approve/revoke toggle, and an exit node is called what it is -// rather than shown as the bare 0.0.0.0/0 that it advertises. Approving one route sends the whole approved -// set upstream; the sidecar does that read-modify-write so two panels can't clobber each other's sets. - -const copy = (text: string) => void copyToClipboard(text); - -type RouteRowProps = { route: string; approved: boolean; busy: boolean; onToggle: (approved: boolean) => void }; - -const RouteRow = ({ route, approved, busy, onToggle }: RouteRowProps) => { - const isExit = route === '0.0.0.0/0' || route === '::/0'; - return ( -
- {isExit ? : } - {route} - {isExit && exit node} - -
- ); -}; - -/** - * Tags as Headscale stores them: every one prefixed `tag:`. Typing the prefix every time is noise, so the - * editor accepts either form and normalizes here — which is also how the dirty check stays honest, since - * `web` and `tag:web` are the same tag and neither should look like an edit. - */ -const parseTags = (text: string): string[] => { - const parts = text - .split(/[\s,]+/) - .map((t) => t.trim()) - .filter(Boolean); - return [...new Set(parts.map((t) => (t.startsWith('tag:') ? t : `tag:${t}`)))]; -}; - -/** Set comparison, not sequence: Headscale is free to store the tags in an order the owner didn't type. */ -const sameTags = (a: string[], b: string[]) => a.length === b.length && a.every((t) => b.includes(t)); - -type OwnershipProps = { node: HeadscaleNode; busy: boolean; onError: (message: string) => void }; - -/** - * Owner and tags — the two things that decide which ACL rules apply to a node, which is why they sit - * together behind the disclosure rather than next to Rename. - * - * Mounted only while the card is expanded: it needs the user list, and fetching every user to render a - * collapsed row would be a request per screenful for a control nobody is looking at. The query key is - * shared with the Users section, so an expanded card is usually a cache hit anyway. - */ -const Ownership = ({ node, busy, onError }: OwnershipProps) => { - const { setTags, moveToUser } = useHeadscaleNodes(); - const { users } = useHeadscaleUsers(); - - const [owner, setOwner] = useState(node.user?.id ?? ''); - const [draftTags, setDraftTags] = useState(node.tags.join(' ')); - - const pending = setTags.isPending || moveToUser.isPending; - const nextTags = parseTags(draftTags); - const tagsDirty = !sameTags(nextTags, node.tags); - const ownerDirty = !!owner && owner !== node.user?.id; - const target = users.find((u) => u.id === owner); - - const run = async (fn: () => Promise) => { - try { - await fn(); - } catch (err) { - onError(headscaleErrorMessage(err)); - } - }; - - return ( -
-
Owner and tags
- -
- - - {ownerDirty && ( - <> - - - - )} -
- - {/* Said before the move, not after: the node keeps its address and its tags, but the rules that let - anything reach it are written per user, so it can go dark to everything that used to see it. */} - {ownerDirty && ( -

- Moving this node to {target?.name ?? 'another user'} changes which policy - rules apply to it. Its addresses and tags stay, but anything reaching it through a rule written for{' '} - {node.user?.name ?? 'its current owner'} will stop. -

- )} - -
- - setDraftTags(ev.target.value)} - onKeyDown={(ev) => { - if (ev.key === 'Enter' && tagsDirty) void run(() => setTags.mutateAsync({ id: node.id, tags: nextTags })); - if (ev.key === 'Escape') setDraftTags(node.tags.join(' ')); - }} - placeholder="tag:server tag:eu — space separated" - spellCheck={false} - autoComplete="off" - className="min-w-0 flex-1 rounded-md border border-white/10 bg-black/40 px-2 py-1 font-mono text-[11px] text-zinc-200 outline-none placeholder:text-zinc-600 focus:border-primary/50" - /> - {tagsDirty && ( - <> - - - - )} -
-

- Tags are what the access policy targets. A tag no rule mentions does nothing; removing one a rule depends on - cuts the node off from it. The tag: prefix is added for you. -

-
- ); -}; - -type NodeCardProps = { node: HeadscaleNode; onError: (message: string) => void }; - -const NodeCard = ({ node, onError }: NodeCardProps) => { - const { rename, toggleRoute, expire, remove } = useHeadscaleNodes(); - const [open, setOpen] = useState(false); - const [renaming, setRenaming] = useState(false); - const [draftName, setDraftName] = useState(node.name); - const [confirming, setConfirming] = useState(false); - - const busy = rename.isPending || toggleRoute.isPending || expire.isPending || remove.isPending; - - const run = async (fn: () => Promise) => { - try { - await fn(); - } catch (err) { - onError(headscaleErrorMessage(err)); - } - }; - - const submitRename = async () => { - const name = draftName.trim(); - setRenaming(false); - if (!name || name === node.name) return; - await run(() => rename.mutateAsync({ id: node.id, name })); - }; - - return ( - -
-
- -
- {renaming ? ( -
- setDraftName(ev.target.value)} - onKeyDown={(ev) => { - if (ev.key === 'Enter') void submitRename(); - if (ev.key === 'Escape') setRenaming(false); - }} - autoFocus - spellCheck={false} - className="min-w-0 flex-1 rounded-md border border-white/10 bg-black/40 px-2 py-1 text-sm text-zinc-100 outline-none focus:border-primary/50" - /> - - -
- ) : ( -
- - {node.id}: {node.hostname}{' '} - ({node.name}) - - {node.user && {node.user.name}} - {node.isExitNode && exit} - {node.tags.map((tag) => ( - - {tag} - - ))} -
- )} -
- {node.ipAddresses[0] ?? 'no address'} - · {node.online ? 'online' : `seen ${timeAgo(node.lastSeen)}`} - {node.subnetRoutes.length > 0 && · {node.subnetRoutes.length} route(s) active} -
-
- -
- - {open && ( -
-
-
Addresses
-
- {node.ipAddresses.map((ip) => ( - - ))} -
-
Hostname
-
{node.hostname}
-
Registered
-
- {timeAgo(node.createdAt)} · {node.registerMethod} -
-
Key expires
-
- {timeUntil(node.expiry)} -
-
Last seen
-
- {node.online ? 'now' : timeAgo(node.lastSeen)} -
-
- -
-
- Advertised routes -
- {node.availableRoutes.length === 0 ? ( -
This node advertises no routes.
- ) : ( -
- {node.availableRoutes.map((route) => ( - void run(() => toggleRoute.mutateAsync({ id: node.id, route, approved }))} - /> - ))} -
- )} -
- - - -
- - - {confirming ? ( - <> - - - - ) : ( - - )} -
-
- )} -
-
- ); -}; - -export const NodesView = () => { - const { nodes, isLoading, error } = useHeadscaleNodes(); - const [filter, setFilter] = useState(''); - const [actionError, setActionError] = useState(null); - - const needle = filter.trim().toLowerCase(); - const visible = needle - ? nodes.filter( - (n) => - n.id === needle || - n.name.toLowerCase().includes(needle) || - n.hostname.toLowerCase().includes(needle) || - n.user?.name.toLowerCase().includes(needle) || - n.ipAddresses.some((ip) => ip.includes(needle)) || - n.tags.some((t) => t.toLowerCase().includes(needle)), - ) - : nodes; - - const online = nodes.filter((n) => n.online).length; - - return ( - -
-
-
-

Nodes

-

- {nodes.length} registered · {online} online -

-
-
- - setFilter(ev.target.value)} - placeholder="Filter by id, name, user, IP, tag" - spellCheck={false} - className="w-full rounded-lg border border-white/10 bg-black/40 py-1.5 pl-8 pr-2.5 text-xs text-zinc-100 outline-none placeholder:text-zinc-600 focus:border-primary/50" - /> -
-
- - {actionError && {actionError}} - - {nodes.length === 0 && ( - } - title="No nodes yet" - hint="Create a pre-auth key and run `tailscale up --login-server --authkey ` on a machine to join it." - /> - )} - {nodes.length > 0 && visible.length === 0 && ( -
Nothing matches “{filter}”.
- )} - - {visible.map((node) => ( - - ))} -
-
- ); -}; diff --git a/plugins/offscale/web/PolicyAssistant.tsx b/plugins/offscale/web/PolicyAssistant.tsx deleted file mode 100644 index 4bfed3f9..00000000 --- a/plugins/offscale/web/PolicyAssistant.tsx +++ /dev/null @@ -1,177 +0,0 @@ -import { useMemo, useState } from 'react'; -import { Check, Loader2, Sparkles, Wand2, X } from 'lucide-react'; -import { useHeadscalePolicyAssist, assistFailure } from './useHeadscalePolicy'; -import { collapseUnchanged, diffCounts, diffLines } from './diff'; -import { Button, Card, ErrorNote } from './Cards'; - -// Ask for a policy change in English; read the diff; decide. -// -// The whole point of this panel is the middle step. The model is good at the grammar — HuJSON, tagOwners, -// the src/dst shapes — and has no idea which of the owner's machines matter, so its proposal is a draft to -// be read, not an answer to be trusted. Nothing here writes to Headscale: Apply puts the text in the editor -// above and the existing Save button is still the only thing that leaves the browser. -// -// The diff is against what is CURRENTLY in the editor, which is also what was sent up, so it always shows -// exactly what accepting would change on screen — including edits the owner made and hasn't saved. - -const EXAMPLES = [ - 'let everyone reach the machines tagged tag:server on port 22', - 'stop the phones from reaching anything except the DNS server', - 'add a group for family with just my own user in it', -]; - -const DiffBody = ({ before, after }: { before: string; after: string }) => { - const lines = useMemo(() => diffLines(before, after), [before, after]); - const rows = useMemo(() => collapseUnchanged(lines), [lines]); - const { added, removed } = useMemo(() => diffCounts(lines), [lines]); - - if (!added && !removed) { - return

No change — the proposal matches what you have.

; - } - - return ( - <> -
- +{added} - −{removed} - unchanged lines collapsed -
-
- {rows.map((row, index) => - row === null ? ( -
- ⋯ -
- ) : ( -
- {row.kind === 'add' ? '+' : row.kind === 'remove' ? '−' : ' '} {row.text} -
- ), - )} -
- - ); -}; - -type PolicyAssistantProps = { - /** The text on screen right now. Sent up as the base, and diffed against. */ - policy: string; - /** Accepting a proposal — puts it in the editor's draft. Never saves. */ - onApply: (policy: string) => void; - disabled?: boolean; -}; - -export const PolicyAssistant = ({ policy, onApply, disabled }: PolicyAssistantProps) => { - const assist = useHeadscalePolicyAssist(); - const [prompt, setPrompt] = useState(''); - // The proposal lives here, not in the mutation's `data`, so that discarding it is a real state change and - // a second ask doesn't briefly show the previous answer against the new base. - const [proposal, setProposal] = useState<{ explanation: string; policy: string } | null>(null); - - const ask = async () => { - const request = prompt.trim(); - if (!request || assist.isPending) return; - setProposal(null); - try { - setProposal(await assist.mutateAsync({ prompt: request, policy })); - } catch { - // Rendered from `assist.error` below — mutateAsync rejecting is the same failure twice. - } - }; - - const apply = () => { - if (!proposal) return; - onApply(proposal.policy); - setProposal(null); - setPrompt(''); - assist.reset(); - }; - - return ( - -
- - Describe the change - Proposes a document — never saves it -
- -
-