Documents Want to Become Secret Stores
Every internal documentation system eventually becomes an unofficial secrets system. Not because anyone planned it. Because documentation is where urgency lives. The deployment failed. The vendor webhook stopped signing requests. The staging database needs a one-time credential. The person writing the fix wants the next engineer to be faster, so they paste the value into the page.
At first this looks kind. The runbook is complete. The next incident is shorter. Then the token rotates, the old value stays in the page, and a new teammate copies the stale credential because the document sounds authoritative. Or worse, the page is shared with someone who should understand the procedure but should never reveal the secret value.
Vault's editor was designed around that failure mode. A page can contain a structured secret_ref
node instead of plaintext. The stored document keeps durable attributes such as secretId and
a display name. Access state, share capability, key hash, visibility, and hide-name behavior are ephemeral. The backend
removes those fields before persistence and re-annotates the document for each viewer.
The Insert Secret Flow
The editor has to meet people where the mess already is. In a clean workflow, an author inserts an existing active secret
from the current workspace or creates a new secret while writing the page. In a real workflow, someone pastes a Vault key
or a 64-character SHA-256 hash that came from an older note. The editor detects that shape and can convert it into a
secret_ref.
The editor needed to handle the messy workflows teams already had. Sometimes an engineer inserts an existing secret correctly. Sometimes they paste an old key from Slack, an outdated note, or a previous incident document. Vault tries to convert those patterns into structured references instead of leaving secrets buried inside prose.
That distinction matters operationally. A pasted secret becomes invisible to rotation and audit workflows. A structured reference can be tracked, updated, restricted, and reviewed later. The goal was never to make the editor smart. The goal was to make the safer workflow easier than the dangerous one.
Reveal, Copy, Rotate
A rendered reference should feel practical, not ceremonial. If the viewer has access, reveal and copy can call the secret value endpoint. The call carries intent. A reveal and a copy return the same sensitive value, but they are different operator actions and deserve different audit metadata. During a review, "copied during deploy" tells a different story than "revealed while investigating access."
If the viewer does not have access, the UI can still be honest. It can show that a secret exists, hide the name when the secret is configured that way, or indicate that access is restricted. A pending or denied request is not a permission. It is state attached to a workflow.
Owners can rotate from the reference and inspect usage. After rotation, old references can become outdated instead of silently remaining wrong. That is a much better failure mode than a wiki page that confidently contains last year's credential.
Collaboration Needs Predictability
Operational runbooks are usually edited during stress. Two people open the same document. One updates the deploy steps. Another removes outdated instructions. The last save silently wins.
Vault intentionally uses a simple editing lock instead of pretending operational documentation behaves like Google Docs. That tradeoff is deliberate. For incident procedures and deployment runbooks, predictable ownership of edits is often more valuable than real-time collaborative merging.
The system chooses a boring lock over a surprising merge.
Why Tiptap Fits This Shape
Tiptap worked well because it allowed secrets to behave like structured application objects rather than formatting conventions inside text. People still write headings, tables, lists, blockquotes, and ordinary operational prose. But the secret is not just another string in the page.
The important part was not rich text itself. It was giving the system enough structure to understand where secrets were referenced, who could interact with them, and when operational knowledge had become stale.
The lesson is simple: if documentation is where engineers work during pressure, the secret system has to live there too. But it has to arrive as a reference, not as another copy of the value. The page should explain the operation. The secret store should decide access. The editor's job is to keep those responsibilities visible while everyone is trying to ship.