Skip to content

feat: lox live, the unattended twin of lox run - #226

Merged
DavidGodefroid merged 15 commits into
mainfrom
feat/lox-live
Nov 18, 2026
Merged

DavidGodefroid merged 15 commits into
mainfrom
feat/lox-live

Conversation

@DavidGodefroid

Copy link
Copy Markdown
Owner

What

lox live serves the rule-based automatic decisions of a workspace without a terminal (systemd, no TTY, comes back alone after a reboot). It is for a host where an unattended service works through the locks. Everything a human decides today stays a human's.

  • lox live [--file] [--status-socket PATH] [--status-group GROUP] [-v]: starts the hub and the locks, serves decisions with the existing engine, plain log lines. Fail closed: when it stops, nothing is decided.
  • lox live enrol (at a terminal, once, after lox run reviewed and applied): records what was approved (files' digest, review fingerprint, verified image digests, production profiles). lox live starts only what matches; otherwise it applies nothing, reports needs_enrolment and waits. It never answers yes to a review.
  • lox live status [--json] and a read-only status socket for another Unix user: health, the state of a ticket, and the withdrawal of a pending ticket carrying a dutydesk: agent label. No route decides, reveals or renews.
  • New facade name live, so the audit tells a rule decision made unattended from a human's terminal.
  • lox run and lox live now read the per-profile auto rules of locksql and lockmq too (the missing half of locksql#185 / lockmq#49).
  • Docs: docs/lox-live.md, contrib/systemd/lox-live.service.

Safety rules

  • An unattended session sends an approval only when a written per-profile rule decides it (profile:*). Engine defaults never approve unattended; a lock whose rules cannot be read is reported needs_enrolment.
  • Production floor, in the engine and again in the hub: no rule approves a write on production, for any lock type. It is a whitelist read from the ticket's kind, risk and verb.
  • The hub refuses, from any rule approval: grants, policy loosening, never-auto, retype, typed inputs, version-1 tickets. Reveal and renew are refused to live.
  • The enrolment is compared before the first Docker call. Every applying command (lox add, remove, up, init, run) is excluded while lox live serves.
  • Console questions: only the Vault token of a vault_token: cli lock is answered (Vault Agent with an AppRole sink to ~/.vault-token gives a fully unattended start). Passwords, passphrases, host-key trust and a loosened policy are never answered.
  • The status socket's directory must be the service user's and closed to others; group and mode are set through the directory's descriptor.

For lox run users

  • The first lox run after upgrade asks one review: locksql/lockmq rule lines enter the fingerprint.
  • locksql/lockmq per-profile auto rules are now honoured off production: a question asked before may no longer be asked.
  • The production floor is stricter.

Review

An independent security review of the branch found no way to make live approve a human-only ticket or a production write, and 1 high / 5 medium / 8 low defects, all fixed here with tests (approval on engine defaults, blacklist floor, no hub-side floor, managed caps read once, re-apply under a serving lox live, containers run before the enrolment compare, and smaller ones).

Open point to confirm: a production connect is exempt from the floor, because lockkit classes every production connect as prod-write; the lock still signs it never-auto unless its own connect rule is auto, and every later write is floored on its own.

Not tested

Draft because nothing ran against a real engine: the unattended start, the rules-<instance> services in the locksql/lockmq images and the systemd unit are covered by fakes and compose goldens only. A hub image containing the live facade is required; lox live refuses an older hub (hub_too_old).

Tests

go build ./... && go vet ./... && go test -count=1 ./... pass (umask 022), -race on the new packages.

🤖 Generated with Claude Code

DavidGodefroid and others added 15 commits November 18, 2026 12:10
The hub takes decisions under a facade name of its own, live: an approval
only by an auto rule, routed where the terminal is, never for a never-auto
ticket, a typed name, typed values or a version-1 ticket (unchanged), and
never a reveal or a renewal. A withdrawal by facade live is made in
"lox live" (its status socket). GET /v1/hub says the hub takes it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
lox run read the profiles' auto rules of locklog and lockssh only. It now
runs `locksql profile rules --json` and `lockmq profile rules --json` the
same way (rules-<instance>, in the lock's image, as its agent account, on
the reviewed copy, no network), shows them in the review, keeps them in
its state directory and applies them in its engine: locksql's connect,
read, write and ddl; lockmq's connect and each action by its ticket's
verb. Rules it cannot read leave the engine's defaults for these two
locks, as before. The consoles keep enforcing their own side.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The per-profile rules of locksql and lockmq could set write, ddl, get,
publish, purge or delete to auto on a production profile, and the engine
would approve them. A floor now holds for every lock type, in one place:
a rule's auto on a ticket of risk prod-write, or on a write action of a
production ticket, is asked (a human decides; lox live leaves it
pending). Reads keep their rule, and so does a production profile's
connect, which lockkit classes prod-write but which writes nothing.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Session.Unattended serves the engine's rule decisions under Session.Facade
(live) with no human: a ticket the engine would ask is left pending at the
hub for a human's facade (EvLeft), no card is drawn, and no console
question is answered but the Vault token's of a vault_token: cli lock,
again each time it is asked and retried when the host's token is not
usable. A connect a rule approves whose lock asks its Vault token again
gets the host's token sealed with the rule's approval. Every other
console question is reported (EvConsole: missing_secret, needs_enrolment,
refused). lox audit shows a rule's facade, so lox live's decisions are
told from the terminal's.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Up.Probe reports what is applied (Reviewed: the review's fingerprint, the
images cosign verified, the production profiles); an Enrolment records it
in the state directory (0600). Up.Enrolled is lox live's start: the
runtime directory is made again and the stack brought up as enrolled, with
no question, no upgrade and no online cosign for the enrolled images.
Anything that differs is not applied (nothing started, stopped nor asked):
a NeedsEnrolmentError says why.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
lox live [--file] [--status-socket PATH] [--status-group GROUP] [-v] needs
no terminal: it starts the stack as enrolled (lox live enrol, at a
terminal after lox run), serves the rule decisions as facade live in an
unattended session, and logs plain lines. Not enrolled, or anything
changed: it applies nothing, says needs_enrolment and keeps running,
checking again when the enrolment changes, on SIGHUP and now and then.
lox run and lox live refuse to serve one workspace together (a flock in
its state directory); lox approve works next to lox live. A read-only
status socket (0660, --status-group) serves the health, a ticket's state
and the withdrawal of a pending ticket raised by a dutydesk: agent; lox
live status prints the same health (exit 0: serving).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
docs/lox-live.md: the enrolment, what stays a human's, Vault Agent with
AppRole and a ~/.vault-token sink, the auto rules, the production floor,
the status socket's contract and the security model (its own Unix user).
contrib/systemd/lox-live.service: a system unit under a dedicated user.
The serve loop joins its watcher before it starts over.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
On a production ticket, or one of risk prod-write, the auto mode (a rule
or a default) approves only a connect, a read of a read risk, or an action
of a read risk whose ticket verb its lock is known to only read with
(lockmq list/read/peek, lockssh run). The ticket's own kind, risk and verb
decide, not the rule action they map to: a lockmq delete claiming a read
risk, a get, a lockfile put, an unknown verb, a kind read of risk write
and an endpoint are asked.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
HIGH: an unattended session approved on the engine's defaults
(default:read, default:action) when a lock's rules were unknown, the
ticket was for another profile, or its lock type has no rules. Only an
approval named profile:* is sent now; every other one is left pending for
a human, for all lock types. A pending ticket names its agent only when
verified under its pinned lock key. A Vault token the lock refused is
typed again after a delay that doubles up to VaultRetryMax, and at once
when the host's token changes (Session.VaultStamp).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Whatever the lock flagged and the deciding client concluded, a rule's
approval is refused (needs_human) for a grant, a policy loosening, a
policy ticket, and on production (the flag or risk prod-write) for
anything but a connect, a read or an action of a read risk, and, at the
terminal only, an endpoint. Tests no longer lean on never-auto, and the
facade socket's reveal and renew are tested to refuse facade live.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The enrolment records a digest of the files the configuration is read
from (lockfamily.yaml's bytes, each profile, the Vault CA, the paired
devices). Up.Enrolled compares it, and the images, before it runs one
command or makes one directory: a configuration that is not the enrolled
one costs no docker call. What only the engine tells is still compared
with the review's fingerprint afterwards. A profile rules command that
fails once falls back on the applied rules instead of undoing the
enrolment. Up returns the configuration it started (Config). Every
applying Up takes the workspace's lock (internal/servelock, shared), so
nothing is applied under a serving lox live; the holder is told by
probing the flock, not from the file's text. ReadAppliedRules says why a
lock's applied rules cannot be read.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…managed file

The status socket's health detail is one fixed word (no configuration
diff, console prompt or command error: those go to the journal); instance
and id are validated before anything reaches the hub; its directory must
be the service user's and closed to writes by others, the socket is
created 0660 and its group set with lchown. lox live reads the managed
file again at each start and watches it, the enrolment and applied.json:
a change starts it over. It serves the configuration the start returned,
never the workspace's file read again. A lock whose applied rules cannot
be read is needs_enrolment, not serving. A hub without facade live is
reported hub_too_old, said once and asked again once a minute. The host
token file's change resets the Vault retry delay.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The profile-rule-only approvals, the whitelist floor and the hub's own,
the early comparison of the files, the paired phones and the enrolment,
what the status socket's withdrawal does and does not prove, its fixed
detail words, the Vault retry delay. CHANGELOG: what changes for lox run
users (one review, locksql/lockmq auto rules honoured, a stricter
production floor).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Created 0660 at once, the socket was open to the service user's primary
group between bind and chown. It is now created 0600, chowned to the
status group, then set 0660; its directory is already checked not to be
writable by anyone else.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YF8fKrK1XFPoTRMpemksuX
…scriptor

A chmod by path follows a parent swapped for a link. The group and the
mode are now set relative to a descriptor of the checked directory,
opened without following a link, after checking that the entry is the
socket lox live made.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YF8fKrK1XFPoTRMpemksuX
@DavidGodefroid
DavidGodefroid marked this pull request as ready for review November 18, 2026 15:15
@DavidGodefroid
DavidGodefroid merged commit bb4f5a6 into main Nov 18, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant