Slice 2: machine principal, create_workspace and start_workspace #159

Open
opened 2026-09-15 18:25:48 +02:00 by lz · 1 comment
Owner

The two tools that need a vault key, and the credential class that lets them have one. Deliberately held back from slice 1 so the privilege escalation gets its own design attention instead of competing with ten tools for it.

Depends on the whole of slice 1 (#154 at minimum).

Why these two are different

Verified: spawnWorker(db, docker, config, masterKey, input) decrypts the provider token to build the authenticated clone URL, and startWorker re-injects secrets. Both need the vault key. createSession, deleteSession, stopWorker and removeWorker do not.

The key by design exists only in the operator's unlocked web session, and a bearer credential deliberately never sets locals.masterKey (AGENTS.md fact #24). So an MCP credential cannot reach these without a new principal.

What the envelope vault already gives us

PR #146 shipped the seam. vault_keys(principal_kind, principal_id, kdf_salt, kdf_params, wrapped_dek) holds one row per principal; exactly one exists today, ('master','master'). auth/vault-envelope.ts exports newDek, unwrapDek, readPrincipal, insertPrincipal, upsertPrincipal. A machine principal is a row insert — that was the entire point.

Open questions this issue must answer

The vault spec deliberately deferred them: "Deciding a token's KDF (a 256-bit CSPRNG credential argues for HKDF over Argon2id, by the same reasoning AGENTS.md fact #24 gives for hashing tokens with SHA-256) belongs to whoever adds that principal."

  1. KDF. Argon2id defends a low-entropy human secret. A CSPRNG machine credential is not one, so HKDF is the likely answer — but say why in the spec, not in a commit message.
  2. Minting. The DEK exists only in an unlocked session, so the principal can only be created while the operator is unlocked. That is a real constraint on the UI flow.
  3. Rotation. rotateMasterPassphrase re-wraps the master's DEK and touches no data column. What happens to a machine principal's wrapper? Nothing, if it wraps the same DEK — confirm and state it.
  4. Revocation. Deleting the row must actually revoke, and insertPrincipal vs upsertPrincipal matters: only rotation may overwrite an existing wrapper, because replacing one with a DEK the rows were never sealed under destroys the vault silently.

The hard constraint

A vault-bearing credential must be a separate credential class from the GET-only nxs_ tokens, which must not silently acquire it. This is stated in both #140 and the vault design. It also means the consent screen changes: slice 1 shows "Create or start a workspace" as explicitly not granted, and that line has to become real rather than quietly disappearing.

Granting a machine principal a wrapped DEK gives that credential the full vault — every connection token, every sealed env var. That is a deliberate escalation and the UI must say so at the point of granting, not in a doc.

The open vault follow-ups from PR #146 — #141, #142, #143, #144, #145 — are worth resolving before adding a second principal, since several concern what happens when a vault_keys row is lost or unopenable, and a second row makes each of those situations more likely rather than less.

Done when

Claude can create a workspace from a phone; the credential granting that is visibly distinct from a read-only one; and losing or revoking it is a tested path rather than an assumed one.

The two tools that need a vault key, and the credential class that lets them have one. Deliberately held back from slice 1 so the privilege escalation gets its own design attention instead of competing with ten tools for it. Depends on the whole of slice 1 (#154 at minimum). ## Why these two are different Verified: `spawnWorker(db, docker, config, masterKey, input)` decrypts the provider token to build the authenticated clone URL, and `startWorker` re-injects secrets. Both need the vault key. `createSession`, `deleteSession`, `stopWorker` and `removeWorker` do not. The key by design exists only in the operator's unlocked web session, and a bearer credential deliberately never sets `locals.masterKey` (AGENTS.md fact #24). So an MCP credential cannot reach these without a new principal. ## What the envelope vault already gives us PR #146 shipped the seam. `vault_keys(principal_kind, principal_id, kdf_salt, kdf_params, wrapped_dek)` holds one row per principal; exactly one exists today, `('master','master')`. `auth/vault-envelope.ts` exports `newDek`, `unwrapDek`, `readPrincipal`, `insertPrincipal`, `upsertPrincipal`. **A machine principal is a row insert** — that was the entire point. ## Open questions this issue must answer The vault spec deliberately deferred them: *"Deciding a token's KDF (a 256-bit CSPRNG credential argues for HKDF over Argon2id, by the same reasoning AGENTS.md fact #24 gives for hashing tokens with SHA-256) belongs to whoever adds that principal."* 1. **KDF.** Argon2id defends a low-entropy human secret. A CSPRNG machine credential is not one, so HKDF is the likely answer — but say why in the spec, not in a commit message. 2. **Minting.** The DEK exists only in an unlocked session, so the principal can only be created *while the operator is unlocked*. That is a real constraint on the UI flow. 3. **Rotation.** `rotateMasterPassphrase` re-wraps the master's DEK and touches no data column. What happens to a machine principal's wrapper? Nothing, if it wraps the same DEK — confirm and state it. 4. **Revocation.** Deleting the row must actually revoke, and `insertPrincipal` vs `upsertPrincipal` matters: only rotation may overwrite an existing wrapper, because replacing one with a DEK the rows were never sealed under destroys the vault silently. ## The hard constraint **A vault-bearing credential must be a separate credential class** from the GET-only `nxs_` tokens, which must not silently acquire it. This is stated in both #140 and the vault design. It also means the consent screen changes: slice 1 shows "Create or start a workspace" as explicitly **not granted**, and that line has to become real rather than quietly disappearing. Granting a machine principal a wrapped DEK gives that credential the **full vault** — every connection token, every sealed env var. That is a deliberate escalation and the UI must say so at the point of granting, not in a doc. ## Related The open vault follow-ups from PR #146 — #141, #142, #143, #144, #145 — are worth resolving before adding a second principal, since several concern what happens when a `vault_keys` row is lost or unopenable, and a second row makes each of those situations more likely rather than less. ## Done when Claude can create a workspace from a phone; the credential granting that is visibly distinct from a read-only one; and losing or revoking it is a tested path rather than an assumed one.
lz added this to the MCP support (#140) milestone 2026-09-15 18:25:48 +02:00
Author
Owner

Designed in docs/superpowers/specs/2026-09-17-mcp-cold-start-design.md. The four open questions this issue raised now have answers, taken deliberately rather than by default.

1. KDF — HKDF, not Argon2id. deriveKey is Argon2id at 64 MiB, which exists to defend a low-entropy human passphrase. A 256-bit CSPRNG machine secret is not one — the same reasoning fact #24 gives for hashing nxs_ tokens with SHA-256. It also makes per-operation derivation cheap enough to be the default.

2. Minting — armed by the operator while unlocked, from configuration. The secret lives in NEXUS_MACHINE_KEY_FILE / NEXUS_MACHINE_KEY, following fact #38's rules exactly: two spellings sharing one decode path, both set refused at boot naming both, presence deciding rather than emptiness, _FILE preferred. The operator sets the variable, restarts, unlocks once, and arms it; Nexus derives the KEK from the configured secret and writes the wrapper, so the secret never transits the UI or a clipboard. DATA_DIR was rejected — same volume as the database, so a stolen /data yields both halves.

3. Rotation — nothing happens, since it wraps the same DEK. Gets a test rather than a sentence.

4. Revocation — a row delete, proven by a tool call failing afterwards, not by the row being absent.

Blast radius: the whole DEK. A narrower second envelope covering only connection tokens was considered and rejected — it doubles the key management and the re-seal paths to withhold repo env vars from a credential that would still hold a forge token with write:repository across every repo. The escalation is real and the spec says so out loud.

The credential class is nexus:provision, a third entry in SCOPES. SCOPE_LABELS is typed against SCOPES, so a new scope without consent wording is a compile error — which is the structural enforcement this issue asks for when it says the escalation must be visible at the point of granting.

Honest scope on "unwrapped per operation". For start_workspace that window is milliseconds. For create_workspace it is the whole of provisionWorker, because spawnWorker hands the key to a background provision that pulls and clones — tens of seconds to minutes.

One defect found in the design before it was built. mcp/handler.ts memoises with handler ??= createMcpHandler(...) and the factory closes over the first request's deps. So "absent key ⇒ provision tools unregistered" must be read by the factory from a singleton, not baked into deps — otherwise arming the principal does nothing until a restart while tools/list keeps describing a stale world. No test can catch it today, because _resetMcpHandler gives every test a fresh handler.

Before this ships, extract the two-spelling secret policy. routes/api/settings/mcp/status/+server.ts already hand-writes the _FILE-then-plain precedence, tied to oauth/jwks.ts's branch order by nothing but a comment. The machine key would make a third copy.

Blocked on #177.

Designed in `docs/superpowers/specs/2026-09-17-mcp-cold-start-design.md`. The four open questions this issue raised now have answers, taken deliberately rather than by default. **1. KDF — HKDF, not Argon2id.** `deriveKey` is Argon2id at 64 MiB, which exists to defend a low-entropy human passphrase. A 256-bit CSPRNG machine secret is not one — the same reasoning fact #24 gives for hashing `nxs_` tokens with SHA-256. It also makes per-operation derivation cheap enough to be the default. **2. Minting — armed by the operator while unlocked, from configuration.** The secret lives in `NEXUS_MACHINE_KEY_FILE` / `NEXUS_MACHINE_KEY`, following fact #38's rules exactly: two spellings sharing one decode path, both set refused at boot naming both, presence deciding rather than emptiness, `_FILE` preferred. The operator sets the variable, restarts, unlocks once, and arms it; Nexus derives the KEK from the configured secret and writes the wrapper, so the secret never transits the UI or a clipboard. `DATA_DIR` was rejected — same volume as the database, so a stolen `/data` yields both halves. **3. Rotation — nothing happens**, since it wraps the same DEK. Gets a test rather than a sentence. **4. Revocation — a row delete**, proven by a tool call failing afterwards, not by the row being absent. **Blast radius: the whole DEK.** A narrower second envelope covering only connection tokens was considered and rejected — it doubles the key management and the re-seal paths to withhold repo env vars from a credential that would still hold a forge token with `write:repository` across every repo. The escalation is real and the spec says so out loud. **The credential class is `nexus:provision`**, a third entry in `SCOPES`. `SCOPE_LABELS` is typed against `SCOPES`, so a new scope without consent wording is a compile error — which is the structural enforcement this issue asks for when it says the escalation must be visible at the point of granting. **Honest scope on "unwrapped per operation".** For `start_workspace` that window is milliseconds. For `create_workspace` it is the whole of `provisionWorker`, because `spawnWorker` hands the key to a background provision that pulls and clones — tens of seconds to minutes. **One defect found in the design before it was built.** `mcp/handler.ts` memoises with `handler ??= createMcpHandler(...)` and the factory closes over the *first* request's `deps`. So "absent key ⇒ provision tools unregistered" must be read by the factory from a singleton, not baked into `deps` — otherwise arming the principal does nothing until a restart while `tools/list` keeps describing a stale world. No test can catch it today, because `_resetMcpHandler` gives every test a fresh handler. **Before this ships, extract the two-spelling secret policy.** `routes/api/settings/mcp/status/+server.ts` already hand-writes the `_FILE`-then-plain precedence, tied to `oauth/jwks.ts`'s branch order by nothing but a comment. The machine key would make a third copy. Blocked on #177.
Sign in to join this conversation.
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
lz/agent-nexus#159
No description provided.