emcli/docs/superpowers/specs/2026-06-22-two-key-privilege-design.md

# Two-key privilege separation — design

**Date:** 2026-06-22
**Status:** Approved (brainstorm), ready for implementation plan
**Author:** Steve + Claude

## Problem

Today `EMCLI_KEY` does double duty: it is both the AES-256 key that decrypts the
stored mail-account passwords *and* the only gate for every command. The agent
process is launched with `EMCLI_KEY` so it can read and send mail, but that same
key authorizes the admin commands (`account`, `whitelist`, `config`, `audit`,
`init`) too. SPEC §4's "trust boundary" — *the agent invokes only agent
commands* — is convention, not enforcement. A prompt-injected / "forced" agent
holding `EMCLI_KEY` can run `account add`, edit a whitelist, or flip `config`,
dismantling the very guardrails emcli exists to enforce.

## Goal

Split privilege into two environment keys so that the boundary is *enforced*,
not merely conventional:

- `EMCLI_ADMIN_KEY` — authorizes **all** commands.
- `EMCLI_KEY` — authorizes **agent** (non-admin) commands only.

The agent's launch environment is given **only** `EMCLI_KEY`. Because the admin
secret is simply absent from that environment, no instruction can make the agent
perform an admin action — the binary refuses, and there is no key present that
could authorize it.

## Constraints / decisions

These were settled during brainstorming:

1. **Two distinct env vars** (`EMCLI_ADMIN_KEY`, `EMCLI_KEY`) — role is named and
   readable in configs/skills, not inferred from a single value.
2. **Both keys must be able to decrypt account passwords.** The agent decrypts to
   talk to IMAP/SMTP; admin's `account add` / `doctor` need it too. So the keys
   differ in *authorization*, not in crypto capability. This forces envelope
   encryption (one data key, wrapped per role).
3. **Agent-key commands:** `list`, `get`, `search`, `ack`, `send`, `doctor`.
   **Admin-only:** `account`, `whitelist`, `config`, `audit`, `init`.
4. **No migration, no schema-version gate.** No third party uses this DB and the
   data is being scrapped anyway. `init` writes the new wrap slots into a fresh
   DB; existing DBs are simply re-created by re-running `init`.

## Approach: envelope encryption (one DEK, wrapped per role)

### Key model

- `EMCLI_ADMIN_KEY` and `EMCLI_KEY` are base64 32-byte **key-encryption keys
  (KEKs)**. Neither directly encrypts account secrets.
- `emcli init` generates a random 32-byte **data-encryption key (DEK)**. All
  account secrets (`enc_password`, `enc_oauth_client_id`,
  `enc_oauth_client_secret`, `enc_oauth_refresh_token`) are sealed under the DEK,
  exactly as they are sealed under the raw key today.
- The DEK is stored in the `settings` table, sealed twice:
  - `dek_wrap_admin = Seal(adminKey, DEK)`
  - `dek_wrap_agent = Seal(agentKey, DEK)`
- The DEK never touches disk in cleartext.

### Why this enforces the boundary

The store already isolates all secret crypto behind one `s.key` field
(`account.go` calls `crypto.Seal(s.key, …)` / `crypto.Open(s.key, …)`). In the
new model **`s.key` simply becomes the DEK** — `account.go`, `send.go`, etc. do
not change. The entire change lives in *how the DEK is obtained*:

- **Admin command** → require `EMCLI_ADMIN_KEY`; unwrap the DEK from
  `dek_wrap_admin` **only**. If the var is unset or fails to unwrap → hard error,
  **with no fallback to the agent slot.** This is the enforcement linchpin.
- **Agent command** → prefer `EMCLI_KEY`, unwrap from `dek_wrap_agent`. If
  `EMCLI_KEY` is unset but `EMCLI_ADMIN_KEY` is present, fall back to the admin
  slot (admin is a superset; a human holding only the admin key can still run
  `list` / `send`).

The agent process holds `EMCLI_KEY` only. Admin commands refuse to unwrap from
anything but `dek_wrap_admin`, which `EMCLI_KEY` cannot open. The agent cannot
hold a secret that authorizes config changes — it is absent from its
environment, not merely gated by a flag.

## Components

### `internal/crypto`

- Generalize `KeyFromEnv` to read a named variable; add `AdminKeyFromEnv()` and
  `AgentKeyFromEnv()` thin wrappers.
- DEK wrap/unwrap **reuses** the existing `Seal` / `Open` — no new primitive.
- A helper to generate a random 32-byte DEK.

### `internal/store`

Split *unlock* from *open* so the DEK can be read from a wrap slot after the DB
is open (settings rows are plaintext, so no key is needed to read them):

- `store.Open(path) (*Store, error)` — opens/creates the DB, applies the schema,
  key still **locked** (`s.key == nil`).
- `(*Store).Unlock(role Role, adminKey, agentKey []byte) error` — reads the slot
  for the role, unwraps the DEK, sets `s.key`. Missing slot or wrong key → clear
  error.
- `(*Store).InitKeys(adminKey, agentKey []byte) error` — generates a random DEK,
  seals it under both KEKs, writes `dek_wrap_admin` + `dek_wrap_agent`, sets
  `s.key`.

No table changes; two new rows in the existing `settings` table.
`account.go` / mail crypto is untouched (still `crypto.Seal(s.key, …)`).

### `internal/cli`

- One `commandRole(cmd string) Role` function in `run.go` — the single source of
  truth for the classification table above.
- `openStore` gains a `role` parameter and performs slot selection via
  `Open` + `Unlock`.
- Each `run*` helper passes its role. `init` uses the bootstrap path
  (`Open` + `InitKeys`, or `Unlock(admin)` if already initialized).

### Command classification

| Command                                   | Role      |
|-------------------------------------------|-----------|
| `list`, `get`, `search`, `ack`, `send`, `doctor` | agent     |
| `account`, `whitelist`, `config`, `audit` | admin     |
| `init`                                    | bootstrap (needs **both** keys) |
| `help` / no args                          | none (no DB access) |

## `init` & key generation UX

`init` requires **both** keys present (it writes both wrap slots). If either is
missing it errors with what's needed plus the generation hint.

Idempotency: if the wrap slots already exist, `init` does **not** regenerate the
DEK (that would orphan existing sealed passwords) — it unlocks via the admin slot
and keeps today's "already initialized; adding another account" behavior. Fresh
DB → generate DEK, then add the first account.

Documented flow (README + USER-MANUAL):

```bash
export EMCLI_ADMIN_KEY="$(head -c 32 /dev/urandom | base64)"   # human keeps this
export EMCLI_KEY="$(head -c 32 /dev/urandom | base64)"         # agent launcher gets only this
emcli init
```

The agent's orchestrator is configured with **only** `EMCLI_KEY`.

## Error handling

- Agent key on an admin command → exit non-zero, stderr:
  `emcli: this command requires EMCLI_ADMIN_KEY (admin privilege)`.
  (Admin commands print human-readable output, not JSON.)
- Admin command, neither key set → `EMCLI_ADMIN_KEY is not set`.
- Agent command, neither key set → existing `EMCLI_KEY is not set` JSON envelope
  (`CodeConfig`).
- Key present but does not unwrap its slot → `wrong key for this DB`, not a raw
  GCM auth-tag error.

## Testing

- **crypto:** wrap/unwrap round-trip; an admin-sealed DEK is *not* openable with
  the agent key.
- **store:** after `InitKeys`, both `Unlock(admin)` and `Unlock(agent)` recover
  the *same* DEK and decrypt an account password; `Unlock` with a wrong key fails
  cleanly.
- **routing:** table test for `commandRole`; agent key on an admin command →
  refused, non-zero, correct message; agent command works with the agent key;
  agent command works with the admin key (superset fallback); `init` refused
  unless both keys are set.
- **Headline security invariant:** initialize a DB, then with **only `EMCLI_KEY`**
  set, attempt every admin command (`account add/list`, `whitelist …`,
  `config set`, `audit`) and assert each is refused *and the DB is byte-for-byte
  unchanged*. This is the test that proves the bug is fixed.
- **Existing-test fallout:** the `adminEnv` / `b64Key` helpers in `admin_test.go`
  (and `run_test.go`) set `EMCLI_KEY` against a raw-key store — update them to
  provision both wrap slots via `InitKeys`. Audit all `t.Setenv("EMCLI_KEY", …)`
  sites.

## Documentation updates

- README "Getting started" — two-key generation flow.
- USER-MANUAL — key model, role/command table, agent-launcher configuration
  (only `EMCLI_KEY`), updated `init`.
- `skills/emcli` SKILL.md / AGENTIC-MANUAL.md — the agent is given only
  `EMCLI_KEY`; admin commands are not available to it.
- SPEC §4 (trust boundary) and §5 (secrets) — describe enforced two-key model.

## Out of scope (possible follow-ups)

- Key rotation commands (re-wrap the DEK under a new admin or agent key without
  re-encrypting passwords — the envelope design supports this cheaply, but it is
  not built now).
- A distinct read-only vs read-write *agent* tier (orthogonal; per-account
  RO/RW already exists).