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.sightingevent 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. --workspacescopes the mint:--workspace myws(exactly today's single-workspace placeholder), or a comma list (--workspace ci,deploy) for several: one row, onemskssec1_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.--destrepeats: 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 SECONDSgives the placeholder a lifetime; without it the placeholder lives until revoked.msks secret renewextends 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 lsnever shows one). The daemon serves the row's sentinel back on demand over the token-authenticated API, through themsks tuisecrets 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
uaction 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) andmsks 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 givesidentity_fileand 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.