Resources
BetterSign combines self-certifying VLAD identities, append-only provenance logs, programmable lock/unlock authorization, and VLAD-aware DHT discovery.
Resources › Architecture
The protocol. This page describes the BetterSign protocol and its open-source core. For what the BetterSign app and products do today, see Products.
A VLAD is a Verifiable Long-lived Address. It is the stable public name for an identity, while the current operational keys live inside that identity’s provenance log.
The important distinction is that the VLAD is not the current key. It is a durable address that commits to the first authorization rules for the identity. After genesis, authority moves into the plog state, where keys can rotate without changing the VLAD.
That makes a VLAD suitable for people, services, servers, subsystems, and long-lived infrastructure identities that need to survive key replacement.
VLAD (stable public address)
Genesis provenance log entry
Current verified plog state
The verified state branches into paths such as /keys/primary, /keys/recovery, /keys/encrypt, /data/ssh/..., /data/tls/..., and application-specific paths.
At creation time, BetterSign generates the initial primary, recovery, and encryption material, then creates a first-lock WebAssembly script that commits to the initial primary and recovery public-key fingerprints.
An ephemeral creation key signs the first-lock WASM to create the VLAD. That ephemeral secret is discarded. Day-to-day authority comes from the genesis plog entry and the lock/unlock rules, not from the one-time creation key.
The genesis entry publishes the real identity state, including the stable VLAD bytes and the initial core key paths.
Generate primary, recovery, and encryption keys
Build first-lock WASM with primary and recovery key fingerprints
Sign first-lock WASM with an ephemeral creation key
Derive VLAD bytes
Discard ephemeral creation secret
Publish genesis entry with /keys/primary, /keys/recovery, /keys/encrypt, and /vlad/data
A BetterSign identity is self-certifying because each layer gives the verifier enough information to validate the next layer without asking a central certificate authority.
A verifier starts with the VLAD, checks the signed first-lock WASM, verifies that genesis satisfies the committed first-lock key fingerprints and proofs, then replays later entries through the lock/unlock authorization rules.
If any byte in an entry changes, its CID changes. If any link in the chain is missing or invalid, verification fails. If a key rotates, that rotation is accepted only because a previously authorized key or recovery rule authorized the entry that performed the rotation.
Start from a known VLAD
Verify the signed first-lock WASM
Verify genesis proofs and committed key hashes
Replay entries by CID and prev links
Run previous locks with the current unlock and proofs
Derive the current trusted key-value state
A BetterSign genesis entry publishes a small set of core key paths that every identity can rely on. These paths are not special files outside the log. They are ordinary plog state with well-known meanings.
/keys/primary is the normal signing authority for day-to-day updates. It signs ordinary plog mutations such as publishing SSH keys, changing service metadata, rotating TLS material, or updating application paths.
/keys/recovery is the emergency authority. The standard lock checks recovery before primary, so a valid recovery-signed entry can rotate a compromised or lost primary key and win contested update resolution.
/keys/encrypt is the long-lived encryption or KEM public key used to receive sealed BetterSign messages and encrypted command envelopes. It lets other peers encrypt to the identity by resolving current key material from the verified plog.
These paths bootstrap stable identity, recovery, and encrypted communication.
/keys/primary | Daily signing authority for normal plog updates and default identity signatures. |
/keys/recovery | Higher-precedence recovery authority for replacing lost or compromised operational keys. |
/keys/encrypt | KEM/encryption public key used to receive sealed messages and encrypted envelopes. |
The primary key is used often and is more exposed
The primary key is lost or compromised
The recovery key signs an entry replacing /keys/primary
The standard lock checks /keys/recovery before /keys/primary
Peers accept the recovery-authorized rotation
Every BetterSign identity has one provenance log, or plog. It is an append-only, content-addressed sequence of entries. The current identity state is derived by replaying verified operations from genesis to the latest accepted head.
Each entry contains the owning VLAD, a sequence number, the previous entry CID, a Lipmaa skip link for faster historical traversal, operations, lock scripts, an unlock script, and proofs such as signatures.
The plog is both PKI state and a protected data stream. Key paths, SSH keys, TLS material, WireGuard metadata, admin policy, and application data are all ordinary paths in the derived state.
Entry CID = hash(serialized entry).
vlad | Owning identity |
seqno | Monotonic sequence number |
prev | CID of the previous entry |
lipmaa | Deterministic historical skip link |
ops | Update, Delete, or Noop path mutations |
locks | Authorization policy for future entries |
unlock | Proof-preparation script for previous locks |
proofs | Signatures or other cryptographic evidence |
Verification is deterministic. A peer fetches entries by CID, checks that each entry hashes to its claimed CID, verifies sequence and prev links, executes authorization, and applies operations only after the entry is accepted.
Because CIDs are content-derived, peers can retrieve entries from untrusted storage or other peers. The fetch source is not trusted. The bytes are trusted only after local verification.
Lipmaa links are an acceleration structure. They help a verifier or sync process jump through long histories, but they do not replace the hash-linked prev chain or authorization checks.
Watch verification replay a log page by page: content re-hashed, prev links re-checked, lock scripts re-run, arriving at the verified current state with no authority and no server trusted.
Compute the CID from the serialized bytes
Require the computed CID to match the advertised CID
Require entry.prev to match the accepted head CID
Replay the previous state
Run the current unlock script
Run the previous lock scripts
Verify signatures and proofs
Apply ops to derive the new state
Accept the new head
Plog authorization is programmable. The current accepted entry carries lock scripts that define what the next entry must prove. The proposed next entry carries an unlock script and proofs that attempt to satisfy those previous locks.
In the standard identity flow, the normal lock checks recovery authority before primary authority. That gives the recovery key higher precedence for emergency rotation or contested updates.
This split lets authorization evolve with the log. An accepted entry can rotate keys, add delegation, narrow a subtree, or change future policy. The next entry must satisfy the policy that was already committed by the previous state.
Accepted entry N carries locks for entry N+1
Proposed entry N+1 carries an unlock script and proofs
The verifier runs state(N), unlock(N+1), locks(N), and proofs(N+1)
| Success | Accept N+1 and apply its ops. |
| Failure | Reject N+1. |
Previous normal lock
Check the /keys/recovery proof first
A valid recovery proof authorizes a recovery-grade update
Otherwise check the /keys/primary proof
A valid primary proof authorizes a normal update
Because those lock and unlock scripts are small WebAssembly programs, authorization in BetterSign is genuinely programmable. The rule for who may make the next change is not a fixed setting buried in a server. It is code committed into the log, and every verifier runs the exact same code to reach the same verdict.
That means a plog can express almost any policy you can describe: a single signer for a personal identity, several parties who must jointly approve a change, a recovery key that outranks the everyday key, a delegated branch that a service may manage but not escape, or a rule that only accepts an update that also clears an extra guard. When requirements change, a new entry installs a new policy for everything that follows.
The policy is enforced by verification, not by trust. Anyone replaying the log runs the committed program, and either the supplied proof satisfies it or it does not. No central service decides, and no one can quietly weaken the rules without leaving a signed, visible record in the history.
Each rule is committed into the log as code and enforced identically by every verifier.
| Single authority | One key authorizes each change. The simplest personal identity. |
| Multi-party approval | Several parties must jointly authorize a change before it is accepted. |
| Recovery precedence | A stronger, better-protected key can override the everyday key in an emergency. |
| Delegation | A service or teammate may manage one branch of the log without touching the rest. |
| Custom guards | Extra conditions a valid update must also satisfy, layered on top of the signature check. |
One of the most important things programmable authorization unlocks is threshold control: requiring more than one holder to cooperate before an identity can change. Instead of a single secret that one stolen laptop can misuse, signing authority is split into shares, and only a chosen number of them together, say three of five, can authorize an update.
Threshold signing produces a single, ordinary signature that anyone can verify, yet no individual shareholder ever holds the whole key or can act alone. The plog simply records that the threshold policy was satisfied, and followers verify it like any other change.
Distributed key generation, or DKG, takes this a step further: a group can create a shared key together so that the complete private key never exists in any one place, not even for a moment during setup. There is no trusted dealer to compromise. This is how a team, a board, or a fleet of servers can jointly own an identity, with the same permanent VLAD and the same verifiable history as a single-person one.
The specific curves and threshold schemes are listed on the Cryptography page. The idea to take away here is that ownership of an identity can be shared, enforced by math, without ever assembling the whole secret in one dangerous place.
Signing authority is split into shares held by different people or machines
A change is proposed as a new entry in the log
Enough shareholders (the threshold) each contribute a partial approval
The partials combine into one ordinary signature, with no full key ever assembled
Followers verify the signed change exactly as they would any other update
BetterSign can define reusable templates for identity state, expected plog paths, subsystem keys, capability grants, and local integration behavior. A template gives teams a repeatable shape for a server, service, agent, user, WireGuard peer, TLS identity, or SSH account without hand-crafting every path from scratch.
Templates can be imported and exported as TOML or JSON, stored locally, and managed by the daemon or desktop UI. They can include default key layouts, categories such as ssh, tls, sign, and encrypt, default paths, and optional guard definitions that new plogs inherit at creation time.
Guards are the policy boundary around those templates. A guard can require that an update is signed by the right authority, uses an approved algorithm, writes only approved paths, keeps CA and TLS signing keys separate, preserves recovery authority, enforces a maximum rotation age, requires a CA-signed certificate, or refuses a dangerous downgrade.
Audit rules use the same kind of condition shape, but they are observer-owned. Use guards for plogs this daemon owns or treats as self-declared guarded state. Use audit rules when following someone else’s VLAD and checking it against local requirements.
Monitoring runs after the tracking loop has fetched and cryptographically verified the plog. It evaluates guards and audit rules against verified state, not against untrusted DHT data, raw files, or claims from another peer.
Rules can check whether a required key exists, whether a value matches an expected format or digest, whether a certificate is near expiration, whether an agent has an unexpected capability, whether an SSH account is missing a managed key, or whether a monitored path changed outside the expected lifecycle. Hashed guard values allow equality checks without putting the original plaintext in audit configuration.
Monitoring turns those rules into operations. Events can be published to files, databases, or Web API endpoints, including JSONL logs, rendered file output, SQLite/Postgres/MySQL tables, and generic HTTP receivers. Instead of waiting for a broken login, expired certificate, stale WireGuard PSK, or suspicious agent capability to become an incident, BetterSign can surface drift as a verified state problem with provenance behind it.
bs import-template /path/to/service-template.toml
bs export-template builtin-ssh-pq --output /tmp/ssh-pq-template.toml
bs logs template list
bs logs template create
bs logs template edit <TEMPLATE_ID>
bs logs template delete <TEMPLATE_ID>
Templates define the expected shape. Guards decide what may change. Audit and monitoring detect whether reality still matches policy.
| Templates | Importable identity layouts, plog paths, key categories, subsystem profiles, and integration defaults. |
| Guards | Owner-side expectations for algorithms, key age, required paths, formats, certificates, and safe key purpose. |
| Audit rules | Observer-owned checks over followed VLADs controlled by other people, teams, services, or agents. |
| Monitoring | Verified-state evaluation with file, database, and Web API event destinations. |
| Privacy | Hashed expected values can prove content matches without storing plaintext in rule config. |
| Impact | Fewer one-off scripts, clearer authority, faster incident response, safer automation, and stronger compliance evidence. |
Choose a template for the identity or subsystem
Publish initial plog state under the template paths
Attach guards that constrain future updates
Followers verify lifecycle events and derive current state
Audit rules evaluate the verified state
Monitoring alerts or reacts when policy and state diverge
| Ad hoc credential ops | BetterSign managed policy |
|---|---|
| Every service invents its own key layout | Templates make identity and subsystem layouts consistent |
| Policy lives in scripts, runbooks, and tribal memory | Guards reject unauthorized or unsafe lifecycle changes |
| Audits reconstruct authority after the fact | Audit rules evaluate verified state directly |
| Monitoring sees symptoms before it sees provenance | Monitoring reports drift with the plog history that explains it |
VLADemlia is the BetterSign DHT layer for finding identity records. It uses Kademlia-style routing behavior, but the records are about VLAD identities and content-addressed plog heads rather than arbitrary mutable key-value records.
A node publishes lookup records for the VLADs it owns or serves. A lookup record gives peers enough information to find the genesis entry, the latest known head, and synchronization hints. Missing entries are fetched by CID and verified locally.
The DHT is deliberately not the root of trust. Kademlia-style routing helps locate records. BetterSign verification decides whether the returned records are acceptable.
A follower knows a VLAD
Query VLADemlia for the lookup record
Receive the genesis CID, latest head CID, and peer hints
Fetch missing plog entries by CID
Verify CIDs, prev links, locks, unlocks, and proofs
Derive current state and update local integrations
| Kademlia | VLADemlia |
|---|---|
| Routes by key distance | Uses Kademlia-style peer routing |
| Stores and finds records | Keys records by VLAD-oriented identity data |
| Does not know BetterSign identity semantics | Advertises plog genesis/head synchronization state |
| Treats DHT answers as untrusted hints | |
| Requires local plog verification before trust |
Every distributed system needs an initial way to find peers, records, or public keys. BetterSign treats discovery as a reachability problem, not as the root of trust.
A peer may learn candidate records from VLADemlia, bootstrap peers, IPFS-like public infrastructure, AggLayer-style publication, or another available service. Those sources help locate bytes and peers. They do not make the bytes trustworthy.
Authenticity is established after discovery by verifying the VLAD, plog entries, CIDs, links, lock scripts, unlock scripts, and proofs.
Find a candidate peer or record
Fetch genesis and latest head hints
Retrieve missing plog entries by CID
Verify locally from the VLAD and plog history
Trust only verified derived state
Discovery answers where to find a candidate identity. Introduction answers whether that identity is the one the user or organization intends to trust.
BetterSign can support pseudonymous identities, organization-controlled identities, or identities introduced through existing systems such as Web PKI, enrollment flows, administrator policy, or other verification methods.
The important distinction is that introduction can be flexible while ongoing key lifecycle trust remains cryptographic. Once a VLAD is accepted, followers can track its verified state without rediscovering a new identity every time keys rotate.
| Introduction | Lifecycle trust |
|---|---|
| How a relying party first decides which VLAD to trust | How the accepted VLAD proves current state |
| May use out-of-band, enterprise, PKI, or social workflows | Uses plog verification, locks, unlocks, and proofs |
| Can be pseudonymous or tied to a real-world entity | Survives routine key rotation under the same identity |
Peers go offline, addresses change, and relying parties may miss many key events. BetterSign preserves coherence by letting peers synchronize to current state while still validating the chain of lifecycle changes.
A follower can discover the latest head, fetch only the missing entries it needs, verify the intermediate history, and derive the current state. Lipmaa links and content addressing make long histories more practical without turning discovery into trust.
This matters for rotation and revocation: a server that missed several updates can catch up and still know which key is current.
A follower reconnects after missing updates
It discovers the latest advertised plog head
It fetches missing entries and skip-link targets
It validates the intermediate lifecycle events
It applies the current verified state