An API key can only be given as a file path: let the operator paste it into Settings, kept write-only #160

Closed
opened 2026-10-08 23:47:35 -04:00 by cmoriarty · 1 comment
Owner

Settings take the backend's API key as the path of a file holding it (and the same for the planning backend). Using the Claude API after #155 meant creating the file by hand on the laptop, and in production with docker exec into the container. Most apps that talk to a model API take the key in their settings page.

The file path exists for a reason the change must keep: the settings spec says Braid never stores, returns, or writes the key into a run's configuration. Settings are saved as events in an append-only log, so a key saved there would live in every copy of the database forever.

What it needs

  • A password field for the key under each backend, write-only: after saving, the page shows only that a key is set and its last four characters, with Replace and Remove.
  • osfd writes a pasted key to an owner-only file in its state directory and points the backend's key-file setting at it. The settings event records that a key was set, never the key. Runs, the engine probe and Test connection keep reading the file as they do now.
  • No route returns the key.
  • The key-file path stays available for an operator who manages the file.
  • Production has no login; anyone on the LAN could already point the backend URL at their own server and have Braid send the key there. A saved key is forgotten when the backend URL moves to another host, so the key only ever goes where it was entered for.

Done when

A key pasted on the Settings page is used by the next run and by Test connection, is not in the database, the event log or any API response, and survives a restart; and changing the backend URL to another host clears it.

Settings take the backend's API key as the **path of a file** holding it (and the same for the planning backend). Using the Claude API after #155 meant creating the file by hand on the laptop, and in production with `docker exec` into the container. Most apps that talk to a model API take the key in their settings page. The file path exists for a reason the change must keep: the settings spec says Braid never stores, returns, or writes the key into a run's configuration. Settings are saved as events in an append-only log, so a key saved there would live in every copy of the database forever. ## What it needs - A password field for the key under each backend, write-only: after saving, the page shows only that a key is set and its last four characters, with Replace and Remove. - osfd writes a pasted key to an owner-only file in its state directory and points the backend's key-file setting at it. The settings event records that a key was set, never the key. Runs, the engine probe and Test connection keep reading the file as they do now. - No route returns the key. - The key-file path stays available for an operator who manages the file. - Production has no login; anyone on the LAN could already point the backend URL at their own server and have Braid send the key there. A saved key is forgotten when the backend URL moves to another host, so the key only ever goes where it was entered for. ## Done when A key pasted on the Settings page is used by the next run and by Test connection, is not in the database, the event log or any API response, and survives a restart; and changing the backend URL to another host clears it.
Author
Owner

Shipped in bac6790 (deployed; production serves it, new boot id). Change archived as openspec/changes/archive/2026-10-09-settings-api-key.

What shipped

  • Settings → Backend → API key, and the same for the planning backend: a password field. Once saved the page shows only Key set · ends in …, with Replace and Remove. Use a key file instead keeps the path field for a key you manage yourself.
  • osfd keeps a pasted key in an owner-only file under its state directory (/var/lib/openspecflow/keys/ in production, on the braid-state volume). The save takes the key out of the request before anything is validated or logged, so it is in no human.settings event, no API answer and no run's opencode.json (which references the file).
  • A pasted key is sent only to the scheme, host and port it was saved with: by the engine probe, Test connection and both providers in a run's config, so a planning backend elsewhere cannot borrow the main backend's key. Saving the URL on another host removes the key and the page says so. A key-file path into Braid's key store is refused.
  • Test connection can send a key typed but not saved, for that one request.

Checked: in a browser on a local stack against a server that answers only one x-api-key: tested before saving, saved, reloaded, restarted osfd, moved the URL to another host. A search of the whole state directory found the key only in keys/backend.key, and nowhere once it was removed. Full lane green (backend, 187 browser specs, 13 simulated runs).

Left to the operator: pasting the Anthropic key on production's Settings page. The hand-made /var/lib/openspecflow/anthropic.key from #155, if it was made, can then be deleted.

Shipped in bac6790 (deployed; production serves it, new boot id). Change archived as `openspec/changes/archive/2026-10-09-settings-api-key`. **What shipped** - Settings → Backend → **API key**, and the same for the planning backend: a password field. Once saved the page shows only `Key set · ends in …`, with Replace and Remove. `Use a key file instead` keeps the path field for a key you manage yourself. - osfd keeps a pasted key in an owner-only file under its state directory (`/var/lib/openspecflow/keys/` in production, on the `braid-state` volume). The save takes the key out of the request before anything is validated or logged, so it is in no `human.settings` event, no API answer and no run's `opencode.json` (which references the file). - A pasted key is sent only to the scheme, host and port it was saved with: by the engine probe, Test connection and both providers in a run's config, so a planning backend elsewhere cannot borrow the main backend's key. Saving the URL on another host removes the key and the page says so. A key-file path into Braid's key store is refused. - Test connection can send a key typed but not saved, for that one request. **Checked:** in a browser on a local stack against a server that answers only one `x-api-key`: tested before saving, saved, reloaded, restarted osfd, moved the URL to another host. A search of the whole state directory found the key only in `keys/backend.key`, and nowhere once it was removed. Full lane green (backend, 187 browser specs, 13 simulated runs). **Left to the operator:** pasting the Anthropic key on production's Settings page. The hand-made `/var/lib/openspecflow/anthropic.key` from #155, if it was made, can then be deleted.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#160
No description provided.