Skip to main content

Device approval (overview)

TL;DR

The device-approval flow lets a CLI request specific keys and requires a human to approve that request in a browser. Secrets are encrypted to the CLI public key and only the CLI can decrypt them.

Why this matters

  • Eliminates long-lived API tokens for fetching secrets.
  • Prevents accidental secret exfiltration from UIs or proxies.
  • Provides a clear consent step and audit trail.

How it works (summary)

  1. CLI generates ephemeral keypair and creates a request via the public BFF.
  2. CLI prints an approval URL and a QR code; user opens the URL and authenticates.
  3. User selects the bundle and keys to authorize and clicks Approve.
  4. Server decrypts stored bundle values (server-side) and encrypts them to the CLI public key using sealed boxes.
  5. CLI polls /wait until ciphertext is available, then decrypts locally and emits export lines.

Security notes

  • The server never learns the decrypted values after they are encrypted to the CLI.
  • Requests are single-use and have a short TTL.
  • At-rest encryption protects values stored in SQLite.

Developer checklist

  • Ensure time on server and client are synchronized to avoid TTL surprises.
  • Keep your local CLI binary secure; it's the only holder of the ephemeral private key for the request.

See the approval flow user guide for a more detailed sequence diagram: ./user-guide/approval-flow.md