Stable identity
A VLAD remains stable while its keys and protected metadata rotate.
React to verified change
Plog Watchers
Purpose
BetterSign is not only a place to store key history. It can also watch trusted VLADs and react when verified plog state changes.
This is the operational bridge: identity owners publish signed updates, followers verify the plog, and local integrations update files, registries, in-memory indexes, or service configuration from the derived state.
The reaction is intentionally downstream of verification. A watcher should never apply a local change just because a peer returned bytes; it applies change only after the plog chain, CIDs, locks, unlocks, and proofs pass.
Watch and React
Follow configured VLAD ↓
Fetch or receive candidate plog update ↓
Verify chain and authorization ↓
Derive current state or verified entries ↓
Detect whether relevant state changed ↓
Run integration-specific handler
Watcher Patterns
The codebase has two watcher patterns. Pattern A is a polled pull loop: a verified source produces a typed snapshot plus a change token, and a handler runs only when the token changes.
Pattern B is a push from the central tracking loop. bs-server already verifies every followed plog end to end, then hands already-verified entries to registered handlers that maintain derived indexes.
The split matters because some integrations own their own cadence, while others should react exactly when the daemon tracking loop finishes verification.
Two Plog Watcher Shapes
Pattern A: Snapshot Watcher
- Polls on a configured interval or manual trigger
- Compares change tokens for idempotency
- Retries same snapshot if handler work fails
- Useful for file rewrites and lifecycle jobs
Pattern B: Entry Handler
- Receives already-verified plog entries
- Runs from bs-server tracking loop
- Rebuilds derived state or swaps registries
- Useful for SSH, TLS, and vlad-svid indexes
TLS and VLAD-SVID
TLS watchers let a server maintain local TLS identity state from verified plogs. A handler can inspect paths such as /data/tls/sign, update a registry, and make the next connection use current verified material.
VLAD-SVID workflows can consume verified entries to enforce policy, issue or rotate service identity material, and reject unsafe key reuse. The important rule is the same: the plog tracking loop verifies before the TLS or SVID handler acts.
This lets certificates and service identities rotate through BetterSign state without making a central CA database the only source of truth.
TLS Reaction
Tracked service VLAD publishes TLS path update ↓
Daemon verifies plog history and current authorization ↓
TLS handler reads verified key or certificate paths ↓
Registry swaps to current identity material ↓
Service reload or next handshake observes current state
WireGuard Identities
WireGuard has fixed identity primitives, so BetterSign does not replace the WireGuard key format. Instead, BetterSign can verify which peers should exist, coordinate metadata, and rotate preshared keys through authenticated BetterSign message exchange.
The server code can track configured peer VLADs, project VLADs into WireGuard peer tags, run a PSK exchange using plog-resolved signing and encryption keys, and call wg syncconf after a PSK rotation.
That gives WireGuard deployments a stronger control plane: peer membership and rotation policy can follow VLADs while WireGuard continues to run with its native kernel interface.
WireGuard PSK Refresh
Configure tracked peer VLADs ↓
Resolve own /keys/primary and /keys/encrypt ↓
Exchange authenticated BetterSign PSK messages ↓
Write rotated PSK material ↓
Run WireGuard sync to apply current state
Developer Hooks
Developers can use the same watcher shape for new integrations. Define a verified source that returns a typed snapshot and a change token, then define a handler that makes the local change idempotently.
For central bs-server integrations, implement a handler that consumes already-verified entries and rebuilds derived state from the provided slice. Do not re-trust disk, DHT records, or RPC responses inside the handler; the trust boundary is the verified entry stream.
Handlers should be re-entrant. They may receive overlapping or repeated entries, and a failed snapshot handler should be able to retry the same state on the next tick.
bs follow <VLAD_HEX>bs followingbs admin tracking add-vlad <VLAD_HEX>bs admin ssh add-user --authorized-keys-path /home/alice/.ssh/authorized_keys --vlad <VLAD_HEX>bs admin tls list-servicesbs admin wireguard add-peer --interface wg0 --vlad <PEER_VLAD_HEX>Access Query Gate
The access-query gate answers one question for an external access controller such as FreeRADIUS: given an identity and a requested access, allow or deny? It fuses three existing surfaces into a single boolean — the admin ACL, preventive guards, and audit rules — so a network gateway can reuse BetterSign policy without re-implementing any of it.
A request is allowed only when the ACL permits the action on the resource, every applicable guard's condition chain is satisfied, and no enforcing audit rule trips. The decision is fail-closed at every step: an unknown or untracked VLAD, stale verified state, a tripped rule, or any internal error all deny. The gate never fetches a log to answer a query — it evaluates only against state the tracking loop has already verified, scoped to the configured tracked set.
Decisions are exposed over an HTTP route, POST /access/query, designed for the FreeRADIUS rlm_rest module. Access-query resources live under a dedicated /access/<service>/ namespace that is provably disjoint from the admin /config tree, so a server-management grant can never bleed into a network-access allow.
# FreeRADIUS-style query — returns {"allow": true|false, "message": ...}curl -sS -X POST http://127.0.0.1:<port>/access/query \ -H "Content-Type: application/json" \ -d '{"vlad":"<hex>","service":"vpn","action":"connect","resource":"gw-1"}'# [monitoring] config knobs that drive the gateenforcing_audit_rules = [] # empty = every audit rule enforcesrevocation_paths = ["/revoked"] # presence in state = immediate denyverbose_access_reasons = true # full reason text to the callerAccess Decision Pipeline
Receive vlad, service, action, resource ↓
ACL check — short-circuits on deny before any state read ↓
Look up currently-known verified state: present, absent, or stale ↓
Immediate revocation check on configured revocation paths ↓
All guards must pass and no enforcing audit rule may trip ↓
Return allow plus a reason message