Repository navigation
v0.52.0: a person arms with the vendor's ticket; the vendor's door answers on every product
What changed for an operator
The arm flow changed. A person no longer copies a write token into the served file: run proximo-core arm in a terminal of your own, type the password (and a second factor if the vendor asks), and the served file holds the vendor's ticket for two hours. proximo-core disarm is unchanged. A job with nobody at a keyboard keeps its token pair (PROXIMO_ARM_SOURCE) exactly as before. proximo mint pve now prints the pveum passwd line the ticket needs.
The release
A person arms with the vendor's ticket. A token is an identity (the vendor ships it with expire 0 and means a standing credential with an ACL); a ticket is a session (POST /access/ticket, the vendor's two hours, dead on its own). proximo-core arm now logs the operator in from a terminal of their own (a silent prompt for the password and, when the vendor asks, a second factor; sent once on the plane's own wire; an agent's shell passthrough has no terminal and is refused, nothing written) and serves the vendor's ticket at that plane's served path (--plane pve|pbs|pdm, each with its own served path, pair and login; --serve PATH names another file; --user names who logs in, default the served token's own user), 0600, with a ledger row naming the user and the hour it dies and never the ticket. The served file now holds a token or a ticket, read by one reader for the predicate and the wire: armed is this product's ticket, for this box, under two hours by the ticket's own signed issue time, failing closed on anything else; the wire sends a ticket as the vendor's cookie with its CSRF token on a mutation, and a dead ticket as the read-only token when one is configured. A job with nobody at a keyboard keeps the token pair (PROXIMO_ARM_SOURCE, served by configuration) unchanged, and disarm still refuses a read-only source byte-identical to it. Gone from the verb: copying a write token's bytes into the served file and reading GET /version with them first (the login is that check). A box that armed by copying a long-lived write token per session, with a reaper for sessions that ended armed, can retire both: nothing of ours needs reaping when the vendor's clock ends the arm (one such session on the author's box stayed armed four days behind two orphan tunnels). A served ticket goes only to the box and product that issued it: elsewhere, the read-only token rides or the call is refused before the wire. proximo mint pve prints pveum passwd <user> with the read token's recipe: a person arms as that user, a job needs no password. PBS and PDM tickets are the same shape under their own prefix; PMG keeps its password or credential file. A minor, on the digest lane's precedent of the vendor as the lock. Said in SECURITY (lab, 2026-11-05, under the credentials proximo mint installs): the vendor lets a user mint its own tokens, so a two-hour ticket can leave behind a standing token with the user's reach; the bound is the user's ACL, the vendor's, and Proximo adds nothing to it.
The vendor's door answers on every product. A plan's vendor_door (what the vendor's own permission check would answer the served credential, said beside Proximo's verdict, governing nothing) was PVE only. PBS and PDM are read now: their rule is proxmox-router's Permission (a check of path, privileges and partial, an or of checks and the self rule userParam, an and of checks), and what the credential holds is the caller's own GET /access/permissions, which those products answer as the whole tree of nodes the caller holds anything on, each privilege with its propagate flag: read once per credential; a listed node holds its privileges; a path the tree does not list is unknown, because the vendor's own walk (a NoAccess fence the tree cannot show, a node whose roles do not propagate) is not inferred from it; an empty tree is the vendor saying the caller holds nothing anywhere; a tree the evaluation cap cut (an Admin credential on a larger estate) is unknown whole. partial false needs every privilege, true any one. The self rule compares what the vendor compares, the whole auth id: MAY for a ticket's own user, NEVER for any token (the vendor's auth id for a token is the token id, which no user id equals), UNKNOWN when who is served could not be read. A rule of none is Permission::Superuser: MAY for the user root@pam itself (a root ticket; PMG's root credential), NEVER for every token, on every product. A rule slot the row's own path does not bind (POST /nodes/{node}/network on PBS and PDM carries {iface} in the body) is NEVER: the vendor fills it from the routed path only. PMG's rules are role lists; the served user's role is not read yet, so a PMG check answers in words naming the roles. Proved live on pbs-test under the credentials proximo mint pbs installs (a datastore create: never, Datastore.Allocate on /datastore; a comment on the granted datastore: may; the user's own token mint: may) and on pdm-test's minted pair (a notes write: never for the Auditor token, System.Modify on /system/notes; may for the Administrator token; the user's own token mint: may, by ticket). One whole-diff lens on 325b37e (0 BLOCKING, 4 MAJOR, 5 MINOR), each major a rule inferred past the vendor's words and folded by reading the vendor's source: the tree walk, the token's auth id, root on no rule, the body-bound slot. The door is still advice: a NEVER still sends and the vendor's 403 is the lock.
The vendor's digest is the write lock. Every config record Proxmox publishes carries a digest, and the write at that path accepts one: the vendor refuses a write whose digest is not the record's. A plan whose read shows a digest, on a call that publishes the parameter (197 served mutations across the four products: PVE 82, PBS 53, PDM 44, PMG 18), now carries it among its arguments, listed with the parameters given and shown whole to a model (a PBS or PDM digest is 64 characters, over the short-value cut), and the plan is judged on the consent id that covers those arguments, so an operator's grant binds to that version of the record; the call sends it, and a record that moved since the plan is the vendor's own refusal (400, "detected modified configuration file"), receipted as a wire error, nothing written. PBS and PDM hand a record's digest beside the record ({"data": record, "digest": hex}; read live on PBS: a datastore, a user, a token), where PVE puts it inside; the wire now keeps it with the record, so the lock holds on PBS and PDM as on PVE (PDM read live too: a user, a token, the realms); PMG publishes 18 such calls and is unverified. A record that is not a dict (PDM's /config/notes is a string) lends no lock. UNDO's delete-back (the reverse of a create whose record carries a digest, a PBS or PDM token) plans again at the act and sends the plan's own digest, so the grant an operator placed for its plan is the one the call spends. A call that sent no digest (consent inert, or a plan that could not read the record) writes under the digest its own read-back carried, when it took one (PROXIMO_UNDO=off takes none). The caller's own digest always wins. CANNOT: a record the plan could not show whole (over the cap, fenced, a collection, no GET twin) lends the plan no lock and current.why says so (the write still carries what its read-back took); a grant spent on a write the vendor then refused stays spent, and the operator approves the fresh plan. Before this, only UNDO's restore sent the digest; a consented write could land on a configuration that changed after the plan. A patch.
The vendor's permission rule rides every address. Each of the four api-viewers publishes, per call, the rule it checks before it answers (PVE: a headed check list; PMG: roles; PBS and PDM: a path, privileges and partial, or an or/and of them). proximo.json.gz now carries it verbatim as a permissions column on 1,729 of 1,799 vendor rows (the rest publish none; the shell lane's rows carry none). The build reads each rule against its product's grammar and refuses a form it does not know, with its words, so a new vendor shape stops the next refresh instead of riding in unread; the loader checks the column again, and a file nested past the parser's stack is refused like any unreadable file. It is the first step of the may/never map, below.
A PVE plan says what the vendor's own door would answer the token. A PVE plan now carries vendor_door: verdict (may, never, filtered, in words or unknown), why, and token, which token it answered for. It follows the plan's last word, needs: a plan refused for anything but the arm or consent (a held line, a lane not opted into, its arguments, its route, and on an armed box an untiered line, a taint wall or CONTAIN) carries none and asks nothing. On an unarmed box the arm is checked first and is the refusal named, so the door is asked even where a tier, a taint wall or CONTAIN would refuse the call too. An argument that does not read as its published type is named as the reason the door was not asked. The token is the one being served, as the arm read it at plan time, so on an unarmed box a write's answer is about the read-only token, and it says so. The answer is the address's rule evaluated in the vendor's own order (check_api2_permissions, exec_api2_perm_check) against what the token holds at each path the rule names, read from the vendor's own GET /access/permissions?path=, through the engine and receipted like any read. It governs nothing: allowed is still Proximo's verdict, a never is named and the call still goes when Proximo allows it, and the vendor stays the lock. It never says may where the vendor would refuse; where the map cannot be sure it says in words or unknown and why. On the lab, GET /pools/{poolid} for a pool the read token holds no Pool.Audit on answers never (Pool.Audit on /pool/<the pool>), which is the 403 the vendor sends. A plan now makes this read (one per path the rule names, and none after the first that is refused or cannot be reached) besides its own, so on a box that cannot be reached a plan waits for one more connection. vendor_door is said only in the room the plan has left under its cap: whole, or its verdict alone, or not at all; it never costs the plan, or an undo's plan, anything else. PBS, PDM and PMG plans carry none yet. This is door contract 4: this key, and proximo_read's description, which said "by path or words (no leading slash)" and now says "by /path, or by words with no slash" (a path keeps its slash; a door refused pools/x).
arm checks the write token before it serves it. It reads GET /version once with the write token (PVE). A token the vendor refuses (401: an expired lease, or a wrong or revoked secret; or any other status) is never served: arm says NOT ARMED and leaves the served token untouched. Before, arm said ARMED over a token that refused every call, reads included. A box it cannot reach is armed and says it was not checked. The bytes checked are the bytes served. The core.arm ledger row says check (the status, or null) and, when not checked, unchecked (unreachable, unconfigured, plane-unusable, refused-by-door); a refused arm's row is outcome refused. arm --json carries status and check on both outcomes.
Four read-door fixes. diagnose on a path with no battery says so, not "pve is not configured". fields= names the keys of ONE record too (a node's status), so a record over the cap is reachable by key. since= says when its newest snapshot is over an hour old. An undo read-back that fails names the vendor's status (401: the token was not accepted). A fields= refusal names no vendor key on an untrusted address, and on a trusted one every name is escaped and bounded in bytes, so the refusal fits the door's ceiling with its count.
A CLI call no longer reads the whole ledger. 0.51.0 made a receipt in a running door read only the ledger's tail, but each new process, as each proximo-core call is, still read the whole file once to learn the chain's mode. What a process scanned is now kept beside the ledger in audit.log.mode, signed with the ledger's own key, and the next process reads only the rows appended since. On a copy of a 46,236-row ledger, on one machine: the first process 421 ms, every one after it 0.6 ms. A sidecar the key did not sign, or one that no longer fits the file (another inode, a smaller file, a changed first or last 4 KiB of what it scanned), is ignored and the file read whole, as is anything else planted at that name (a FIFO, a directory, a link), and no sidecar is written in a ledger directory that is itself a link. Doctor passes no key to the mode check and reads the ledger whole, unless the same process already looked. What it cannot see, and says: a ledger changed on the same inode strictly between those two 4 KiB windows, at a size no smaller, keeps its old mode answer in every later process (each append carries it forward) until the sidecar is removed or stops verifying, the key changes, or the ledger is rotated. Proximo replaces a ledger only by rename; anything else is tampering, and audit_verify names it.
A plan no longer tells the operator to arm when arming cannot open the call. With taint tracking on, the consult's second look judged the call again and its answer replaced the plan's. A refusal only the plan makes, a PROXIMO_NODE it cannot use, is one that second judgment never sees, so a storage-content delete refused for a bad default node said needs: arm on an unarmed box, and needs: taint or needs: consent on an armed one in a marked session. The plan's own refusal now stands, with the taint wall said beside it in also_refused; the second look replaces a verdict only when it is allowed or refused for the arm or consent.
Where to read more
- CHANGELOG.md: every change, in full.
- SECURITY.md: what a ticket is, what a token is, and what each control honestly holds.
- docs/SETUP.md: the arm section, and
proximo mintfor the credentials. - docs/arena.md: every published address by verdict.