Skip to content

Placeholder secrets

A workspace need never hold a real secret. Instead, it may hold a placeholder: a sentinel token the operator mints once and pastes into the workspace. The secrets page in the TUI and the msks secret command are how you interact with secrets.

The daemon swaps the sentinel for the real secret on the wire. The real secret is the operator's own value, supplied at mint: a file or stdin on the CLI, or a masked field on the TUI form.

The actual secret lives in msksd's secret store (the database's per-recipient age-encrypted blobs) and in the daemon's unlock cache during its window. The secret store is encrypted using the ssh identity.

A mint covers workspaces. With no target it is the daemon-wide placeholder valid on every workspace's tap. An operator running several workspaces against one daemon mints the credential once and distributes the same sentinel everywhere. A workspace target scopes the row to only those workspaces.

The in-flight swap itself is the egress interceptor; the next section documents it. If you don't care much about how this works, you can safely skip it.

The interceptor (the swap on the wire)

A workspace covered by at least one live placeholder is armed. A live placeholder is minted, unrevoked, and unexpired; the coverage is the workspace's own scoped placeholders, or any daemon-wide placeholder while the workspace accepts one.

When armed, the daemon redirects that workspace's TCP flows toward ports 80 and 443 into an in-process HTTPS/HTTP proxy, and the swap happens there. The proxy is mitmproxy, embedded in msksd. Mitmproxy runs one process serving every armed workspace, one listener per workspace's tap, so a guest that spoofs another workspace's source address still lands on its own tap's placeholders.

What each request gets:

  • The swap. The sentinel is exchanged for the real secret in every request header and every query-string pair (duplicate keys included) when the destination matches the placeholder's allowlist (exact host or label-anchored suffix, as minted). Request bodies are not scanned: the sentinel travels headers and URLs, and an operator pasting it into a body payload sends it nowhere the placeholder covers. The origin sees the real secret; the workspace never holds it. On HTTPS, the connection's TLS handshake (its SNI) gives the destination, and the request's Host header is pinned to that same name: a guest cannot claim one name in the handshake and route by another in the header (domain fronting). On plain HTTP the request is dialed by the Host header's name, for the same binding.
  • The splice. An HTTPS destination no placeholder of this workspace covers is relayed undecrypted: the origin's real certificate reaches the workspace, pinned clients keep working, and the sentinel travels raw.
  • The sighting. A sentinel seen toward a destination its own allowlist misses (while another placeholder decrypts the flow) passes through unrewritten and publishes a secret.sighting event on the events channel. The same is true for a sentinel a workspace holds no covering row for. A daemon-wide sentinel used from a workspace scoped against it, or another workspace's scoped sentinel, reads as an off-allowlist sighting: the cross-workspace leak is announced, never serviced. A revoked or expired sentinel passes through the same way; its placeholder is gone, so there is nothing to swap and nothing to report.
  • QUIC stays down while armed. The workspace's UDP flows toward port 443 are dropped, so browsers fall back to the TCP flow the redirect owns: nothing routes around the interceptor.

While a workspace is armed, the redirect takes its web egress (TCP 80 and 443) before the kernel's consent queue, so the interceptor runs the consent gate for exactly those flows. Every web connection is decided on the name the wire carries: the TLS handshake's SNI on HTTPS, the Host header on plain HTTP. The verdict is bound to the address the naming memory holds for the connection. A name claiming an address it never resolved to keys by the address.

A static workspace's allowlist gates its web traffic by that name. An interactive workspace's web connections hold through the same decider endpoints, rows, durations, and session memory every other port uses; msks egress watch and the TUI answer them like any other hold.

An allowed web connection takes the splice or swap path above. A denied one is answered locally with an HTTP 403 giving consent as the reason: the handshake completes against the daemon's interception CA, the request refuses, and nothing forwards. A client that pins the origin's real certificate fails its handshake instead; it is refused closed either way.

Each swap publishes a secret.swap event; mint, revoke, expiry, and unlock publish their own (secret.mint, secret.revoke, secret.expiry, secret.unlock). All six travel the events websocket beside the workspace lifecycle events.

Each gives the placeholder's row id, its workspace and name, and a timestamp. The row id is the durable handle, because the row itself retires on revoke and expiry. A swap or sighting also gives the destination the wire saw; a mint gives the allowlist it was minted with; revoke, expiry, and unlock carry the identity alone.

The msks tui secrets page's audit view (e from the page) shows every workspace's events newest first, daemon-wide. The newest hundred recorded mints, revokes, expiries, and unlocks replay onto it when the view opens, and swaps and sightings stream in live. The off-allowlist sighting is highlighted as the exfil signal, with a header line stating the detection boundary above. Kind and workspace filters narrow the view; a daemon-wide row's events cover every workspace, a scoped row's its members.

We fail-closed on the swap path. A secret the store cannot serve, or a row the database cannot read answers the request locally with a 502 instead of forwarding it. A request that still carries the sentinel never leaves the host.

For TLS connections, the interceptor presents each connection a leaf certificate signed by the daemon's one interception CA. Every workspace's guest trusts the same certificate its seed staged: the identity seed writes /etc/msks/interceptor-ca.crt at first boot, and the trust-store exports and the NixOS fold register it. A workspace whose guest already trusts that CA sees HTTPS toward allowlisted destinations validate normally from the first placeholder. When the daemon's certificate changes under a workspace that already booted (the move from an earlier per-workspace CA, or a future CA rotation), the next boot renews the seed. The seed is rebuilt carrying the daemon's certificate with an instance-id suffix keyed to it. cloud-init re-provisions (the seed script is idempotent, and the operator's payload re-executes with it), and the fold re-registers the fresh certificate. The splice leg needs none of this: it presents the origin's own certificate.

The listeners bind one shared port on each armed tap address (interceptor_port, default 8643; see the key reference). Upstream connections are verified against the CA bundle mitmproxy ships (certifi's Mozilla list), not the platform's own store; pointing verification at the platform bundle is a setting the certification effort brings, never a code change.

The seeded probe placeholder

A fresh daemon seeds one placeholder itself at first-time startup: the daemon-wide row named probe, allowlisting secretprobe.msks, carrying the fixed credential blob bXNrczptc2tz as its secret. It exists so an operator can verify interception from inside a workspace with zero minting (the probe endpoint). Its sentinel never needs to be treated as a secret: the credential it swaps to is public and gates nothing beyond the probe's own ok page.

The probe endpoint

The daemon serves one deliberately ordinary HTTPS service every workspace can reach: https://secretprobe.msks/, an emulated external endpoint protected by HTTP basic auth (username msks, password msks). It exists so an operator can verify from inside a workspace that secret interception works end to end. The ok page can only exist when the whole chain ran: redirect, TLS splice, leaf mint, and the sentinel-to-secret swap.

The daemon seeds the machinery itself at first-time startup, and the interception CA is installed at first boot. The seeded placeholder is the daemon-wide row named probe, whose secret is the base64 of the whole credential bXNrczptc2tz. Nothing is left to do by hand. The verification:

# on the host: read the seeded sentinel (token-gated API)
curl -s -H "Authorization: Bearer $TOKEN" https://msksd/api/v1/probe

# inside the workspace: the sentinel rides as the raw Basic blob
curl -H "Authorization: Basic <sentinel>" https://secretprobe.msks/
ok

A request that reaches the service has already passed the nft redirect (guest TCP 80/443 to the per-tap interceptor listener), the splice tier (the SNI matched an allowlisted entry), and the daemon CA's leaf mint. The swap then rewrote the raw blob into a well-formed credential. The interceptor's upstream dial was repointed to the service's own per-tap port (probe_port, default 8644) and verified against the service CA the daemon mints. The guest's 443 is the redirect's port. The service listener binds the setting's unprivileged number, which a host wildcard cannot squat. The service validated the fixed pair. A broken link answers distinctly: a TLS failure points at the splice or the CA, a 401 points at the swap (or a wrong credential), a timeout points at the redirect.

The endpoint performs one action: it answers the fixed credential with ok. It reads no workspace state, accepts no commands, and returns no other data. The credentials are a fixed probe value shared by every deployment, and the endpoint gates nothing beyond its own ok page. That is also why the seeded row's sentinel is served back over the token-gated API (GET /api/v1/probe): a token holder already owns the daemon.

Two reachability notes. The probe answers only while the workspace is armed. A workspace scoped against daemon-wide placeholders (no covering row of its own) never arms. Its direct dial to secretprobe.msks:443 finds nothing admitted and times out. That posture is the documented way to opt a workspace out of interception entirely.

VM-specific CA configuration

The guest's trust in its own interception CA is installed at first boot on both images. Debian guests link it into the system trust store. Both guests export three variables for the CA. SSL_CERT_FILE points at a bundle of the platform's own roots with the CA appended. The variable replaces the default lookup, so the bundle must carry both. NODE_EXTRA_CA_CERTS serves node-based clients, and GIT_SSL_CAINFO points git at the same bundle. NixOS's /etc/profile reads no profile.d. Its sanctioned /etc/profile.local hook sources the same exports, which also brings the LLM proxy's environment alive there.

The mint flow

Uses msks secret mint to mint a new credential from the command line UI.

$ op read 'op://Vault/github/credential' \
    | msks secret mint --name github_api \
        --dest api.github.com --secret-file -
minted */github_api for api.github.com
sentinel: mskssec2_9Jm3...kQ
  • The value is the operator's own secret: a file's contents, or stdin for --secret-file - (the example pipes it from a password manager, so it never touches disk). It is whitespace-stripped at both ends and never accepted as a command-line argument, because argv lands in process lists and shell history. It is stored as ciphertext blobs and never echoed; the mint reply carries the sentinel, not the value. The client and the daemon may sit on different machines: the value travels the token-authenticated TLS API. The mint stores ciphertext only: one age-encrypted blob per covering workspace's identity key, and the plaintext travels the daemon's unlock cache until its window ends (below). A covering workspace whose key is outside the store's capable set (ssh-ed25519, ssh-rsa), or that carries no identity key at all, refuses the mint with the workspace named.
  • The mint above carries no workspace target: it is the daemon-wide mint: one row, one mskssec2_ sentinel, valid on every workspace's tap toward the minted destinations. A workspace created later is covered from its first boot; coverage acts as policy, not as a snapshot of the workspace set at mint time.
  • --workspace scopes the mint: --workspace myws (exactly today's single-workspace placeholder), or a comma list (--workspace ci,deploy) for several: one row, one mskssec1_ sentinel, one coverage set either way. A mint produces a single sentinel whether it targets every workspace or a set of one or several; the same label can live on the daemon-wide row and on scoped rows beside it, one row per label per coverage set.
  • --dest repeats: an exact host (api.github.com) binds the swap to that host; a suffix (.github.com) binds it to every host under that domain. A placeholder carries one coverage set, one allowlist, one secret; per-workspace destination scoping stays available by minting a scoped placeholder instead.
  • --ttl SECONDS gives the placeholder a lifetime; without it the placeholder lives until revoked. msks secret renew extends a lifetime in place: the sentinel never changes and nothing is re-delivered.
  • The CLI prints the sentinel at mint. The listing and the audit omit it (msks secret ls never shows one). The daemon serves the row's sentinel back on demand over the token-authenticated API, through the msks tui secrets page's Enter-on-a-row panel, so a sentinel that scrolled away reads back from the daemon. The operator's value alone is never echoed back.

TUI minting

The msks tui secrets page mints too. c opens the form: name, repeatable destinations, coverage (the daemon-wide row, or a multi-select of the workspaces the tree's own list offers), the lifetime (unbounded by default, an hour to thirty days beside it), and the value.

The submit checks the store (msks secret check's endpoint) before it mints. A refusal (a store that cannot answer writes, a name collision on the chosen coverage set, a blank value) gives itself on the form, with the fields kept for a retry.

A successful mint answers with the sentinel's panel. The sentinel opens masked, its prefix giving the reach and its body rendering as bullets. A Show action reveals and hides it again. An OSC 52 clipboard copy works over ssh too, where the terminal honors it, and needs no reveal. The display ends with the panel. Enter (or a click) on a listing row opens the same panel again. The page fetches the row's sentinel from the daemon and shows it, so the sentinel reads back on demand. The panel is one surface for the row, opened at mint and after. Closing the panel clears its text.

Revoking a mint

The TUI allows this via "x".

msks secret revoke --name github_api retires the daemon-wide row of that label everywhere at once. msks secret revoke --workspace myws --name github_api retires the scoped row whose coverage is exactly that set. The targeting mirrors the mint's, and msks secret renew selects its row the same way. msks secret ls lists every row with its coverage (* for the daemon-wide row, the workspace list scoped).

A workspace can exempt itself from daemon-wide placeholders: msks create --secret-coverage scoped (or msks secret coverage myws scoped later) means only placeholders minted directly at that workspace arm it. A daemon-wide sentinel used from a scoped workspace publishes an off-allowlist sighting and swaps nothing. Every new workspace accepts daemon-wide coverage unless its own setting says scoped, and flipping the setting back to all arms it with any live daemon-wide row.

The unlock window

The daemon holds no plaintext of its own: a mint leaves only the per-recipient ciphertext blobs, and the plaintext returns through an operator's unlock. The client decrypts the blobs with the workspace identity's private half and posts the values back over the token-authenticated API (POST /api/v1/secrets/unlock, after GET /api/v1/secrets/pending serves the ciphertext and opens the session window the unlock requires).

The client's half

The unlock reads the identity key file the client already uses for ssh: identity_file (the client config, ~/.config/msks/msks.yaml) or MSKSC_IDENTITY_FILE. It decrypts only the blobs that key opens. Possession of the private key is the authority for a value, proven by the unwrap itself. An operator without the key receives ciphertext, uploads nothing, and the daemon stays cold for those rows; two operators keyed to different workspaces each unlock their own.

An agent-held key cannot unlock: ssh-agent exposes signing, and the unwrap needs the private key material directly, so the unlock reads the file where it lives (ssh login still resolves through the agent). A passphrase-encrypted key file prompts once per session: the passphrase loads the identity and every row then decrypts through it.

Three surfaces run the flow:

  • The TUI at start. The tree's mount offers the unlock against the daemon's locked rows: a warm cache stays silent, a cold one with the key present unlocks itself, and the passphrase prompt (when the file is encrypted) is the modal the session opens with. The secrets page's u action runs the same flow on demand, so a window that lapsed mid-session heals the moment it is seen. The page's STATE column (locked / open) and msks secret ls's state column carry the lock state row by row.
  • msks secret unlock, the scripting surface: fetch pending, decrypt, upload, and print one line per unlocked row plus the rows the key could not open. Rows whose ciphertext failed to open give the re-mint they need; rows with no stanza for this key are another operator's and stay ciphertext. The command without a configured identity gives identity_file and exits nonzero.

The window is MSKSD_SECRET_STORE_UNLOCK_TIMEOUT_S (default 86400 seconds, one day). The timer resets on an unlock POST itself (an operator action carrying plaintext) and on nothing else: websocket traffic, keepalives, and scheduled tasks never extend it. Zero holds plaintext only while at least one operator websocket stays connected: the last disconnect drops it, and an unlock over HTTP alone holds nothing past the reply.

Until an unlock stands, the interceptor's swap path refuses a carried sentinel with a named locked error: HTTP 423, msks: locked: no operator session within the unlock window. The request never reaches the origin, and the sentinel never passes through as a value. An unlock also re-encrypts the row's blobs to its current recipient set, so a coverage edit or a workspace key rotation heals at the next operator session.

Where the real secret lives

A mint stores ciphertext blobs in the daemon's database: one age file per covering workspace identity key, wrapped to that workspace's ssh public half, the same file format the reference age tool writes. The daemon holds no key that opens them: only the workspace identity's private half (kept on the operator's client machine) unwraps a blob, which is the whole design: the client decrypts, the daemon swaps. Values exist in plaintext only in the operator's memory, the token-authenticated request, and the daemon's unlock cache for the window.

The per-recipient blobs are the store. The workspace identity keys decide who can read: back up the client machine's identity files alongside the daemon's database. A database copy alone carries ciphertext nobody can open, and a lost identity file means re-minting the values.

msksd.yaml examples

You can change the secret store unlock timeout.

# the unlock window: how long unlocked plaintext lives in the
# daemon after the unlock POST that supplied it
secret_store_unlock_timeout_s: 86400.0

The store itself needs no configuration: the blobs live in the daemon's database beside the placeholder rows, and the only secret-bearing setting is the window above.

At-rest encryption

Every minted value is ciphertext at rest (a per-recipient age blob in the database), and no configuration choice changes that posture. The ssh identities, the database, and the token hashes keep their own house postures; the blobs give the secrets' one, and the blob's recipient list is exactly the row's coverage.

The audit trail

Mint, revoke, expiry, and unlock append a row to the daemon database: the placeholder's coverage (the daemon-wide row, or the workspace list), name, destination allowlist, and a timestamp (msks secret ls lists placeholders; the audit view is /api/v1/secrets/audit).

Expiry fires from the status watcher's periodic sweep, which publishes a secret.expiry event and re-evaluates the covered workspaces' redirects in the same pass. The last placeholder's retirement stands the interception down, and one revoke or expiry retires the whole row everywhere at once. The secret value and the sentinel appear nowhere in the audit or the events. The value travels its mint request alone and is never echoed. The sentinel appears only in the mint reply and the on-demand row fetch, never in the audit or the event stream.