Architecture

Components

1. Launcher/CLI (vesper) reads a source, creates a temporary broker and provisions entries.
2. Broker owns an in-memory linked store and a private Unix socket.
3. Capability is 32 random bytes represented as 64 lowercase hexadecimal characters.
4. Client SDK maps a logical name to VESPER_CAP_<NAME>, connects to VESPER_SOCKET, and performs one GET.

vesper run lifecycle

1. Parse all secret specifications and the target command.
2. Read sources into protected mappings.
3. Erase copied env: values from the launcher’s environment and copied literal: bytes from parser storage.
4. Create a mode-0700 temporary directory and broker socket.
5. Fork a broker process.
6. Fork the target into a dedicated process group.
7. Provision each entry with TTL, use count, owner UID and the target process-group scope on Linux.
8. Send only socket path, names and capability tokens to the waiting target through a pipe.
9. exec the target; pre-exec memory is replaced.
10. Wait for target completion, terminate the broker, erase all remaining entries and remove the temporary directory.

Secret memory

Secret buffers are anonymous private mmap allocations rounded to page size. Vesper attempts:

• mlock to keep pages out of ordinary swap;
• MADV_DONTDUMP to omit them from compatible core dumps;
• MADV_DONTFORK on Linux to prevent launcher buffers from being inherited.

Every release path overwrites the complete mapping before munmap.

Store semantics

The broker is single-threaded, so validation, use-count decrement and removal are atomic with respect to other requests. Expired entries are removed during the poll loop and immediately when accessed. Tokens are compared exactly; collisions are regenerated.

A successful authorization creates a protected response copy, consumes one use, then sends the copy. This means network interruption cannot make a one-time capability replayable.

SDK contract

SDKs return binary data (unsigned char*, Ruby binary String, PHP binary string, Kotlin ByteArray, Swift Data). Text conversion is explicit. Native SDKs never spawn vesper; shell is the only client that delegates to the CLI.

Source