This yak is now shaved!

me

I’ve been working on two submissions I want to put into the CFP for installfest.cz and had them at a “man it’d be nice to have someone else read and comment on this” level of done. Normally when this happens I have to psych myself up for it, both because receiving feedback can be hard and because I have to do a format conversion. I tend to write in markdown in “all the places” and sharing a document for edits has typically meant pasting it into something like Google Docs or Office 365, where even if it still looks like markdown … it isn’t.

And that’s when the yak walked into the room. Instead of just pasting my drafts into Google Docs and getting on with the reviews, I decided I needed to delay getting feedback and build the markdown collaborative editing system of my dreams. Classic yak shaving - solving a problem you don’t actually need to solve in order to eventually do the thing you originally set out to do. What is Yak Shaving - a video by Matthew Miller if you’re unfamiliar.

When I am done, I then have to take this text back to where it was originally going, often in good clean markdown (this blog post is in markdown!). This rigmarole is tiring. I also dislike that the go to tools for this for me had turned into an exercise in ensuring guests could access a document or collecting someone’s login ids to yet another system.

I knew there had to be a better way. Then it hit me. When markdown started to take off we had a slew of markdown collaborative editing sites take off. They were often modeled on the older etherpad. Well, several are still around. I looked at online options as I tend to prefer using a service when I can so I don’t get more sysadmin work to do.

I hit three snags in picking one:

1. I don’t like being on a free tier when I don’t understand how it is supported. While I don’t know that anyone in this space is nefarious, the world is trending in a specific direction. I don’t mind paying, but this was also not going to generate enough value to warrant serious payments.
2. The project that first came to mind for markdown collaboration went open core back in 2019. Open source business models are hard, and doing open core well is even harder. As you’ll see below I had specific needs and I had a feeling I might run into the open core wall.
3. One of the CFPs would actually benefit from implementing this as my example … bonus!

After examining a bunch of options, I settled on building something out of Hedgedoc. This was not an easy choice and the likelihood of entering analysis paralysis was super high. So I decided to try to force this to fit on a free tier Google GCP instance I have been running for years. It is the tiny e2-micro burstable instance, a literal thimble of compute.

This ran off a lot of options. Privacy first options need more compute just to do encryption work. A bunch of options want a server database (Postgres and friends) and a single person instance should be fine on SQLite, in my opinion. All roads now ran to Hedgedoc. It was the only option that could run on SQLite, tolerate my tiny VM, still give me collaborative markdown, and seemed to have every feature required if I could make it work.

It wasn’t all sunshine and happiness though. Hedgedoc is in the middle of writing version 2.0, which means 1.0 is frozen for anything except critical fixes and all efforts are focused on the future. Therefore, the documentation being a bit rough in places was something I was going to have to live with.

My core requirements were:

1. Only I am allowed to create new notes
2. Anyone with the “unguessable” url can edit and should not require an account to do so
3. This should require next to zero system administration work and be easy to start and stop
4. When I need more features, I should be able to extend this with a plugin for tools like Obsidian or Visual Studio Code.

And while it took longer than I’d hoped, it works. Here’s how:

1. Write yourself a configuration file for Hedgedoc

config.json:

{
  "production": {
    "sourceURL": "https://github.com/bexelbie/hedgedoc",
    "domain": "<url>",
    "host": "localhost",
    "protocolUseSSL": true,
    "loglevel": "info",
    "db": {
      "dialect": "sqlite",
      "storage": "/data/db/hedgedoc.sqlite"
    },
    "email": true,
    "allowEmailRegister": false,
    "allowAnonymous": false,
    "allowAnonymousEdits": true,
    "requireFreeURLAuthentication": true,
    "disableNoteCreation": false,
    "allowFreeURL": false,
    "enableStatsApi": false,
    "defaultPermission": "limited",
    "imageUploadType": "filesystem",
    "hsts": {
      "enable": true,
      "maxAgeSeconds": 31536000,
      "includeSubdomains": true,
      "preload": true
    }
  }
}

This sets a custom source URL for the fork I have made (more below), enables SSL, disables new account registration, and allows edits via unguessable URLs without requiring logins.

1. Decide how you want to launch the container, I am using a quadlet, and provide some environment variables:

CMD_SESSION_SECRET="<secret>"
CMD_CONFIG_FILE=/hedgedoc/config.json
NODE_ENV=production

These just put it in Production mode, point it at the config and provide the only secret required.

1. You’re basically done. I happen to have put mine behind a Cloudflare tunnel and updated the main page of the site, but those are pretty straight forward.

More Yak Shaving

Naturally I planned to launch it, create my user id via the cli, and share my CFP submissions with the folks I wanted reviews from. Narrator: Naturally, that’s not what happened.

I decided to push YAGNI¹ out of the way and NEED IT! Specifically I forked the v1 code into a repository to add some features. The upstream is unlikely to want any of these so I will have to carry these patches. What I did:

1. Hedgedoc will do color highlighting and gutter indicators so you can see which author added what text. Unfortunately it wasn’t seeming to be working. I was getting weak indicators (underlines instead of highlighting) and often nothing. So I fixed that.
2. The colors for authorship are chosen randomly. I am a bit past my prime in the seeing department and it was hard to see the colors against the dark editor background, so I restricted color choices to those that are contrasting. It isn’t perfect, but it is better.
3. My particular set up involves a lot of guest editors. Normally I share to just a few folks, but sometimes to many. They’ll all be anonymous. Hedgedoc doesn’t track authorship colors for guests, so I patched in a system to generate color markings for anonymous editors.
4. A feature I always loved in Etherpad was that you could temporarily hide the authorship colors when you just wanted to “read the document.” So I added a button for that. While I was doing that I discovered that there is a separate toggle to switch the editor into light mode, but I couldn’t see it because the status bar was black and it was set to .2 opacity!! I fixed that too. Also, now the status bar switches when the editor switches.
5. Comments, it turns out are needed. So I coded in rudimentary support for critic markup comments.

I have other ideas, but instead I am going to stop and let YAGNI win for a while. Besides, hopefully 2.0 will ship soon and render all of this unneeded.

So there you go, now if you want to offer your assistance to help me write something, I’ll send you a link and you can go to town on our shared work. If you want to see more about this, well, let’s see if Installfest.cz thinks you should or not :D — and whether this yak decides to grow its hair back.

Getting secrets from 1Password to applications running on Linux keeps forcing a choice I don’t want to make. Manual retrieval works until you get more than a couple of things … then you need something more. There are lots of options, but they all felt awkward or heavy, so I wrote op-secret-manager to fill the gap: a single-binary tool that fetches secrets from 1Password and writes them to per-user directories. No daemon, no persistent state, no ceremony.

The Problem: Secret Zero on Multi-User Systems

The “secret zero” problem is fundamental: you need a first credential to unlock everything else. On a multi-user Linux system, this creates friction. Different users (application accounts like postgres, redis, or human operators) need different secrets. You want to centralize management (1Password) but local distribution without exposing credentials across user boundaries. You also don’t want to solve the “secret zero” problem multiple times or have a bunch of first credentials saved in random places all over the disk.

Existing approaches each carry costs:

• Manual copying: Unscalable and leaves secret material in shell history or temporary files.
• 1Password CLI directly: Requires each user to authenticate or have API key access, which recreates the distribution problem and litters the disk with API keys.
• Persistent agents (Connect, Vault): Add services to monitor, restart policies to configure, and failure modes to handle.
• Cloud provider integrations: Generally unavailable on bare metal or hybrid environments where half your infrastructure isn’t in AWS/Azure/GCP.

What I wanted: the postgres user runs a command, secrets appear in /run/user/1001/secrets/, done.

How It Works

The tool uses a mapfile to define which secrets go where:

postgres   op://vault/db/password         db_password
postgres   op://vault/db/connection       connection_string
redis      op://vault/redis/auth          redis_password

Each line maps a username, a 1Password secret reference, and an output path. Relative paths expand to /run/user/<uid>/secrets/. Absolute paths work if the user has write permission.

The “secret zero” challenge is now centralized through the use of a single API key file that all users can access. But the API key needs protection from unprivileged reads and ideally from the users themselves. This is where SUID comes in … carefully.

Privilege Separation Design

The security model uses SUID elevation to a service account (not root), reads protected configuration, then immediately drops privileges before touching the network or filesystem.

This has not been independently security audited. Treat it as you would any custom SUID program: read the source, understand the threat model, and test it in your environment before deploying broadly.

The flow:

1. Binary is SUID+SGID to op:op (an unprivileged service account)
2. Process starts with elevated privileges, reads:
   • API key from /etc/op-secret-manager/api (mode 600, owned by op)
   • Mapfile from /etc/op-secret-manager/mapfile (typically mode 640, owned by op:op or root:op)
3. Drops all privileges to the real calling user
4. Validates that the calling user appears in the mapfile
5. Fetches secrets from 1Password
6. Writes secrets as the real user to /run/user/<uid>/secrets/

Because the network calls and writes happen after the privilege drop, the filesystem automatically enforces isolation. User postgres cannot write to redis’s directory. The secrets land with the correct ownership without additional chown operations.

Why SUID to a Service Account?

Elevating to root would be excessive. Elevating to a dedicated, unprivileged service account constrains the blast radius. If someone compromises the binary, they get the privileges of op (which can read one API key) rather than full system access.

Alternatives considered:

• Linux capabilities (CAP_DAC_READ_SEARCH): Still requires root ownership of the binary to assign capabilities, which increases risk.
• Group-readable API key: Forces all users into a shared group, allowing direct API key reads. This moves the problem rather than solving it.
• No privilege separation: Each user needs a copy of the API key, defeating centralized management.

The mapfile provides access control: it defines which users can request which secrets. The filesystem enforces it: even if you bypass the mapfile check, you can’t write to another user’s runtime directory. While you would theoretically be able to harvest a secret, you won’t be able to modify what the other user uses. This is key because a secret may not actually be “secret.” I have found it useful to centralize some configuration management, like API endpoint addresses, with this tool.

Root Execution

Allowing root to use the tool required special handling. The risk is mapfile poisoning: an attacker modifies the mapfile to make root write secrets to dangerous locations.

The mitigation: root execution is only permitted if the mapfile is owned by root:op with no group or world write bits. If you can create a root-owned, properly-permissioned file, you already have root access and don’t need this tool for privilege escalation. The SGID bit on the binary lets the service account, op, read the mapfile even though it is owned by root.

Practical Integration: Podman Quadlets

My primary use case is systemd-managed containers. Podman Quadlets make this concise. This example is of a rootless user Quadlet (managed via systemctl --user), not a system service.

[Unit]
Description=Application Container
After=network-online.target

[Container]
Image=docker.io/myapp:latest
Volume=/run/user/%U/secrets:/run/secrets:ro,Z
Environment=DB_PASSWORD_FILE=/run/secrets/db_password
ExecStartPre=/usr/local/bin/op-secret-manager
ExecStopPost=/usr/local/bin/op-secret-manager --cleanup

[Service]
Restart=always

[Install]
WantedBy=default.target

ExecStartPre fetches secrets before the container starts. The container sees them at /run/secrets/ (read-only). ExecStopPost removes them on shutdown. The application reads secrets from files (not environment variables), avoiding the “secrets in env” problem where env or a log dump leaks credentials.

The secrets directory is a tmpfs (memory-backed /run), so nothing touches disk. If lingering is enabled for the user (loginctl enable-linger), the directory persists across logins.

Trade-offs and Constraints

This design makes specific compromises for simplicity:

No automatic rotation. The tool runs, fetches, writes, exits. If a secret changes in 1Password, you need to re-run the tool (or restart the service). For scenarios requiring frequent rotation, a persistent agent might be better. For most use cases, rotation happens infrequently enough that ExecReload or a manual re-fetch works fine.

Filesystem permissions are the security boundary. If an attacker bypasses Unix file permissions (kernel exploit, root compromise), the API key is exposed. This is consistent with how /etc/shadow or SSH host keys are protected. File permissions are the Unix-standard mechanism. Encrypting the API key on disk would require storing the decryption key somewhere accessible to the SUID binary, recreating the same problem with added complexity.

Scope managed by 1Password service account. The shared API key is the critical boundary. If it’s compromised, every secret it can access is exposed. Proper 1Password service account scoping (separate vaults, least-privilege grants, regular audits) is essential.

Mapfile poisoning risk for non-root. If an attacker can modify the mapfile, they can make users write secrets to unintended locations. This is mitigated by restrictive mapfile permissions (typically root:op with mode 640). The filesystem still prevents writes to directories the user doesn’t own, but absolute paths could overwrite user-owned files.

No cross-machine coordination. This is a single-host tool. Distributing secrets to a cluster requires running the tool on each node or using a different solution.

Implementation Details Worth Noting

The Go implementation uses the 1Password SDK rather than shelling out to op CLI. This avoids parsing CLI output and handles authentication internally.

Path sanitization prevents directory traversal (.. is rejected). Absolute paths are allowed but subject to the user’s own filesystem permissions after privilege drop.

The cleanup mode (--cleanup) removes files based on the mapfile. It only deletes files, not directories, and only if they match entries for the current user. This prevents accidental removal of shared directories.

A verbose flag (-v) exists primarily for debugging integration issues. Most production usage doesn’t need it.

Availability

The project is on GitHub under GPLv3. Pre-built binaries for Linux amd64 and arm64 are available in releases.

This isn’t the right tool for every scenario. If you need dynamic rotation, audit trails beyond what 1Password provides, or distributed coordination, look at Vault or a cloud provider’s secret manager. If you’re running Kubernetes, use native secret integration.

But for the specific case of “I have a few Linux boxes, some containers, and a 1Password account; I want secrets distributed without adding persistent infrastructure,” this does the job.