Sealed secrets for codellm role notes

TL;DR

A code role that needs a secret (the live case: KRISP_TOKEN in
docs/fleet/krisp/roles/transcript-ingest.md) can only get it today by the operator putting
the value in codellm's own environment and naming it in CODELLM_EXPOSE_ENV. Adding a secret
means editing docker-compose and redeploying, and the allowlist is flat — every code role on
that codellm sees every exposed value.

The chosen design puts the ciphertext in the role note's frontmatter and keeps the master
key in codellm alone. The note declares which frontmatter fields are sealed; codellm decrypts
exactly those, substitutes the plaintext into the delivery bag for that one run, and the role's
code reads them like any other frontmatter field. fleet never holds the key and never sees
plaintext; trip2g stores the ciphertext as ordinary note content and knows nothing about it.

---
description: Krisp meetings → transcript notes (cron ingest, deterministic)
fleet_id: codellm
mode: cron
cron_schedule: "* * * * *"
write_patterns:
  - transcripts/**
unseal: [krisp_token]
unseal_env_key: SEAL_KEY          # optional; SEAL_KEY is the default
krisp_token: sealed:v1:9nR2v0QkX8tWc1pE...
krisp_base_url: https://api.krisp.ai
---

cfg = fleetkit.frontmatter()      # the role's own frontmatter, ciphertext included
sec = fleetkit.secrets()          # what codellm unsealed for this run

base_url = cfg.krisp_base_url.rstrip('/')
token = sec.krisp_token

There is no unseal() call in the role, no env var mapping, and no master key inside the
sandbox.

Decided: unsealed values go in their own secrets section, not inline in the frontmatter.
Inline would read more uniformly — cfg.krisp_token beside cfg.krisp_base_url — and that
uniformity is why this design beat the alternatives in the first place. It loses to one thing:
the bag is what a role dumps while debugging, and print(cfg) or emit(answer=json.dumps(bag))
would publish the token into vault content, which is the store this whole feature exists to keep
clean. A separate section costs one asymmetry in the role's source and takes the secret out of
the object most likely to be dumped whole. The asymmetry is also honest: those two values are not
the same kind of thing.

Note what it does not buy: dumping the whole bag still carries the secrets. This narrows the
accident, it does not remove it.

The pivotal fact

The instance operator is also the owner of the secrets. There is no multi-tenant hosted
fleet where several vault owners each hold their own credentials.

This single fact decides the design, so it is recorded here rather than left implicit:

• It makes a symmetric master key coherent. The standard objection to a Rails-style
  credentials.yml.enc in a product is that the party doing the encrypting is a user who must
  not hold a key that decrypts everyone's secrets. With operator == secret owner that objection
  is void — this is exactly Rails' trust structure, where the encrypters are the team who
  legitimately hold master.key.
• It removes the need for a per-vault-owner scoping mechanism, which is the one thing an
  embedded ciphertext gives for free and a shared secrets table does not.
• It makes "the operator can read the secret at run time" a tautology rather than a leak.

If that fact ever changes, most of the reasoning below has to be redone.

State it precisely, because the useful form is narrower than "single operator": what the design
relies on is single role authorship — that whoever can create a note under the watched
--agents-folder glob is trusted with the secrets sealed anywhere in the vault. Operator and vault
writer are not automatically the same set; the system already has delegated-admin sessions and
note-writing agents such as the telegram inbox. Everything below scales with who can author a role
note, not with who owns the deployment.

What this does and does not protect

codellm hands the plaintext to the code it executes, so whoever operates the codellm host can
always read it — /proc/<pid>/environ, the bag file, a patched binary, or simply a print()
added to the role. No storage scheme changes that; it is a deploy-time property.

What sealing buys is that the secret is not in the vault in cleartext while the vault travels
through Obsidian sync, git, backups, and note sharing, and is not in cleartext in trip2g's DB or
its dumps. Note that today's env approach has the same property by a different route (the secret
is in no vault at all), so sealing is not competing against a plaintext baseline. What it
actually adds over today is:

• Provisioning without redeploy. A secret is added by editing a note, not by editing
  docker-compose and restarting codellm.
• Scoping — of accidents, not of access. CODELLM_EXPOSE_ENV is flat: every code role on that
  codellm gets every exposed value. A sealed blob is decrypted only for the role that carries it,
  which contains the blast radius of a careless role. It is not access control: the ciphertext is
  ordinary vault content, so anyone who can author a role note can copy another role's blob into
  their own frontmatter, declare it in unseal, and print it. AAD binding would close the copy
  (see Open questions); git history would not.
• Per-role key separation. unseal_env_key lets different roles seal against different
  master keys, so compromising one key does not open the others, and a key can be rotated by
  migrating roles one at a time instead of re-sealing everything at once.

Options considered

Chosen design

Option F's key handling with the bag as the delivery surface.

Costs, honestly

• Rotation of a leaked upstream token: re-seal, edit the note, sync. Cheap at this scale, but
  it is note editing rather than a single row update.
• Rotation of a master key: re-seal every blob sealed against it. unseal_env_key softens
  this — roles migrate to a new key one at a time — but it never becomes a one-liner.
• Vault history: old ciphertext lives in the vault's git history forever, and a later leak of
  the master key decrypts it retroactively. This is the property Rails has and everyone accepts,
  but it should be named.
• No instant revocation: there is no deleteSecret equivalent. Killing a secret means editing
  the note.
• The plaintext lands in the bag, and the bag is a file (FLEET_INPUT=, coderun.go:479).
  Two consequences: the value is on disk inside the sandbox for the run, and — more likely to
  bite — the bag is the natural thing to dump while debugging. print(fm) or
  emit(answer=json.dumps(bag)) publishes the token into vault content. Leaking through env
  requires deliberately reaching for os.environ; here the secret rides inside the object most
  likely to be dumped wholesale.
• codellm learns the seal format. Its "no vault, no KB, no auth, no secrets" invariant becomes
  "holds one master key". Weighed against N plaintext values in its env today, this is still a
  reduction.
• Roles not on codellm silently do not work. An executor: llm role's bag goes to a real LLM,
  where nothing unseals it. Safe — the model sees ciphertext — but quietly non-functional.
• The chat endpoint is a decryption oracle for anyone holding a channel credential. codellm
  trusts the bag: whoever can POST /v1/chat/completions — fleet with its api key, or any
  delegated-admin cookie — can submit a synthetic bag carrying any blob ever sealed under a key
  codellm holds, including ciphertext rotated away long ago and recovered from vault git history,
  together with a body that prints it. Putting the seal endpoint behind cfg.Auth does not touch
  this; the execution endpoint is the oracle. So "fleet never sees plaintext and never holds the
  key" describes the honest dataflow only — fleet's credential is sufficient to obtain any
  plaintext on demand. Acceptable under the pivotal fact, but this is the design's real trust
  boundary and should not be left implied intact.
• The friction being removed was also the authorization gate. Today, granting a role a secret
  requires editing docker-compose and redeploying — an out-of-band act that doubles as "the
  operator specifically approved this role getting this value". Under sealing, unseal: [krisp_token] committed into a note is sufficient on its own: the next run has the plaintext,
  with no separate infrastructure step. That is precisely the ergonomics being bought, and the
  authorization checkpoint is what it is bought with. It holds only while vault-edit rights and
  infra-deploy rights belong to the same person. A collaborator with Obsidian sync access but no
  docker-compose access would, under sealing, be able to grant secret access; today they could not.
  This is a narrower form of the pivotal fact, and it deserves its own line because it can stop
  being true earlier: the operator may still run role code they did not author line by line — a
  shared recipe, a generated script — and sealing removes the manual step that would have made them
  look at it.

What this deliberately does not solve: exfiltration

Once a role holds a secret, nothing stops it from writing that secret into a note. Scope
enforcement checks the path, never the content (ScopedKB / write_patterns), so a role with
a legitimate secret and a legitimate write scope can publish the secret into the vault, and from
there onto the site. This is not a regression introduced by sealing — it is equally true of
today's CODELLM_EXPOSE_ENV path — but sealing does not improve it either.

One escalation path this design depends on is closed separately: a role that can
write note content could otherwise write a new role note declaring unseal
for any blob plus its own unrestricted write_patterns. ScopedKB now refuses
to let an agent author or edit a note carrying fleet_id — see
fleet_write_validation.md, "Built: agents may not
author role notes".

A stronger shape was considered and deferred: a separate request-building block type
(saferequest) taking a declarative request spec — jsonnet or JSON/YAML; internal/jsonneteval
already exists — where secrets are substituted only while constructing the outgoing request and
are never handed to general-purpose code at all. The role would describe which requests it may
send, not hold the credential.

It does not confine the secret on its own. If the spec can also choose the destination, a role
points its base URL at a service the author controls, that service echoes the credential back in
the response body, and ordinary code reads it out of the response — the secret is back in hand
having never been "held". Confinement requires pinning the destination, not just the shape of
the request. The templating is the easy half.

Scanning outgoing writes for the secret value is not an answer either. It catches an accidental
dump — print(fm), emit(answer=json.dumps(bag)), which is the realistic failure here — and
codellm can do that precisely, since it knows exactly which plaintexts it unsealed for the run.
But base64, XOR, or splitting the value across notes defeats it trivially, and the network channel
bypasses it entirely. It is a safety net, in the same category as a linter. It is not a control.

Where real confinement lives — and why it is not this mechanism

If the goal is for the executing code to be genuinely unable to leak a credential, the answer is
not a better way to store it. It is to cut the code off from the network and route all egress
through a proxy that holds the credentials and injects them into outgoing requests. Then the
code never holds the secret at all, and write(secret), output scanning, and encoding tricks all
stop mattering — there is nothing in the sandbox to encode. The destination pinning that the
saferequest idea above was missing comes for free, because the proxy decides where traffic may
go.

Half of it already exists: codellm's sandbox has a network switch (SandboxNetwork), so "no
direct internet" is a knob, not a new mechanism.

Two shapes, with very different cost:

• Intercepting proxy. The role speaks HTTPS to the real host; the proxy terminates TLS with
  its own CA installed in the sandbox trust store, injects auth, and re-originates. mitmproxy
  with a script addon or Envoy with a Lua/WASM filter does this. TLS interception — not the
  allowlist — is where the complexity is.
• Proxy as upstream. The role speaks plain HTTP to a pinned route (http://proxy/krisp/...);
  the proxy adds authentication and originates TLS outward. No CA, no interception, and the
  destination is pinned by proxy config rather than by anything the note says. Substantially
  cheaper, and sufficient for a known set of upstreams.

Off-the-shelf tooling splits along the same seam and is usually assembled rather than bought
whole: egress allowlisting (smokescreen, Squid ACLs, Envoy as an egress gateway) on one side,
enrichment and audit (mitmproxy addons, Envoy Lua/WASM, API gateways with upstream-auth plugins)
on the other.

This is deliberately out of scope. Confinement is a property of the execution environment —
network policy and egress control — not of a secret-storage format, and building it is not this
mechanism's job. Sealing makes no attempt at it.

What unseal is, stated plainly: a trade of confinement for provisioning ergonomics. It buys
"add a secret by editing a note, scoped to that role, with no redeploy" and buys nothing at all
against a role that decides to publish the value it was given. That trade is acceptable here for
one reason — the pivotal fact above: the person authoring the roles is the person who owns the
secrets, so the role is not an adversary. Under any other trust structure the trade would be
wrong, and the proxy would be the requirement rather than the alternative.

The two are complementary rather than competing. If the proxy is ever built, secrets move into its
configuration and sealing becomes optional — at the price of a configured route per upstream,
which is exactly the provisioning ergonomics sealing exists to provide.

Open questions

• Whether unseal should also be honoured on attached notes. Answer: no, and the code
  already enforces it. buildAttachedNotes (internal/webhookutil/attached_notes.go) constructs
  Meta explicitly from tags and layout only — arbitrary frontmatter never travels that path —
  and codellm unseals only the role's own frontmatter, so cross-role unsealing is impossible by
  construction rather than by omission.

  Recorded as a standing invariant, because the convenient answer is dangerous: SEAL_KEY is
  the default unseal_env_key for every role, so in the common case all roles share one key.
  Extending unsealing to attached-note frontmatter would let any role decrypt any other role's
  sealed fields by merely attach_notes-referencing it — reopening exactly the cross-role leak
  option E was rejected for, by a different route.

  Caveat: AttachedNote.Content carries the full note text, so another role's ciphertext is
  still readable. That is what makes the AAD question below matter, and it is why option E's
  rejection stands.

• Standing invariant: the exec tool must never receive the bag. makeExecInvoker
  deliberately sends no fleet_input message (cmd/fleet/internal/agentruntime/runtime.go:683,
  "No fleet_input message: exec runs inline"), so an LLM role's mid-run exec never sees unsealed
  values. If anyone later adds the bag to exec calls, plaintext flows into a real model
  conversation and out to the provider.

• Whether to bind the ciphertext to its location with AAD. Decided: no AAD. dataencryption passes nil additional
  data, so nothing ties a blob to the note and field it belongs to: anyone who can read a blob can
  paste it into their own role under the same key and have it decrypt — relocation, not a crypto
  break. The obvious binding is the note path, and it has a real cost: renaming or moving a role
  note would break every blob in it, silently, at the next tick — and moving notes around is a
  routine Obsidian operation. Binding only the field name does not prevent relocation, so the
  half-measure buys nothing. Note also that EncryptData/DecryptData take no AAD parameter and
  are shared with the secrets table and cmd/tge2e, so this means a new method beside them, not
  a change to them.

  Rejected because the cost lands on an everyday operation and the benefit does not. Moving a note
  between folders is routine in Obsidian, and binding to the path would break every blob in it
  silently, at the next tick. What binding buys is preventing one role from copying another's
  ciphertext — and under the pivotal fact the roles are written by the same person who owns the
  secrets, so that is not an adversary. Revisit only if role authorship ever spreads beyond one
  trusted party, which is the same condition that reopens the rest of this design.

• What the --dry-run reconcile report should say about a role whose unseal field cannot be
  opened — a startup-time validation would catch a bad blob before its first cron tick.