Repository navigation
capsulectl v0.1.0-rc17
Pre-releasecapsulectl v0.1.0-rc17, a pre-release, tagged at 318d5f1. The full list of changes is in the CHANGELOG. These notes start with the changes to what verification accepts and what a record shows.
Before you upgrade: there is no going back to an older version
After this version opens your deals, keep using this version or a newer one. An older capsulectl may refuse to open your deals, and copies it makes can show when a deal was shared.
-
Want the option to go back? Make a backup of your capsulectl data before you upgrade. First pause anything that runs
deal tickon a schedule (cron, launchd), and make sure no capsulectl command is running. For a deal profile set up the usual way, your data is two things: the folder you gavedeal init --dir(the deal skill uses~/.local/share/capsule-deal), and your profile file,~/.config/capsule/profiles/deal.yaml(named after your profile, under$XDG_CONFIG_HOME/capsule/if you set it). If your profile points at files outside that folder, such as a rules file given to--materialityor keys moved withprofile update, back those up too. For example:mkdir ~/capsulectl-backup cp -Rp ~/.local/share/capsule-deal ~/.config/capsule/profiles/deal.yaml ~/capsulectl-backup/To go back, with nothing running, move the upgraded folder aside rather than copying over it, then copy the backup in:
mv ~/.local/share/capsule-deal ~/.local/share/capsule-deal.after-upgrade cp -Rp ~/capsulectl-backup/capsule-deal ~/.local/share/ cp -p ~/capsulectl-backup/deal.yaml ~/.config/capsule/profiles/deal.yamlThen run the older version. Anything recorded after the backup is not in the restored copy; it stays in the folder you moved aside.
-
Sending receipts or deal copies? Ask the people you send them to to update too. An older capsulectl shows copies made by this version as INVALID, even though they are valid.
-
Using capsulectl through Muse? Nothing to do. Muse updates its own copy.
Book profiles: record the outcome of every pending evidence request before upgrading, or ask again after it. A request recorded before the upgrade can no longer be read back (see "Behaviour and wire changes").
Security and privacy
- Plugin dispatch runs the launcher it checked (#296). The trust walk now executes the resolved path it checked, and it also checks every directory a name is looked up in and the owner of every link it follows. A launcher reached through a directory or symlink another user controls is refused, with the fix named.
- The per-user plugin root's parents are checked (#270), from
$HOMEdown to~/.local/lib/capsulectl/plugins. On stock Ubuntu (umask 002) a hand-installed plugin under a group-writable~/.localstops running untilchmod go-w ~/.local ~/.local/lib ~/.local/lib/capsulectl.plugin ls, and running the plugin, print that fix, shell-quoted. - A deal's copies no longer show when it was shared (#294). A deal on the shelf seals each copy's report as a standalone signed record, carried in the copy and on no log. Its log, its copies and its History no longer show when or how often it was shared. A deal whose log already holds a report, and every legacy deal, keeps its reports in its log. The CHANGELOG lists the other limits.
- A shared copy keeps the private bounds back by field (#247, #286). The limit and the floor stay out of the copies they must not reach, and a close's amount openings travel even when the amount equals a bound. Free text is still matched by value, and the share gate reads a page's text and data, never its code.
- Field openings are never printed by
get(plain or--raw), and sealing refuses a request artifact namedopening.*(#242). Adeal terms-resultResult names the counterparty's long-lived key. - What verification accepts has changed (agent-action-capsule v0.8.0, v0.9.1 and v0.10.0):
- Encoding: bundle fragments must be strict base64url and valid UTF-8;
domainandprovenancemust be strings; Producer Envelopes must be strictly encoded CBOR. - Witness receipts:
- one with a
rekororscrapibinding is now checked, and can pass or fail, where it was withheld; - a stub receipt is withheld;
- COSE receipts must be strictly encoded and carry their payload detached, and may not mark an unknown header critical;
- a countersign or statement receipt may carry more than one inclusion proof.
- one with a
- Witness directories: a malformed witness-directory row, or a wrapped
receipt_b64, is now withheld or fails, where before it was checked or passed. - Settlement:
- a side with several observed legs is compared leg by leg;
- a supersedes link counts only under the superseded leg's key;
in_progressis no longer reported;- a delivered leg with an empty carrier is accepted;
- a wrapped entry of an unregistered type is
settlement_malformed; - a
fee_asset_differsfinding names its legs differently in two cases.
result build: it admitsx-members on the document and on a claim, and an optionalcoverage_report. Every other member stays closed, includingX-….
- Encoding: bundle fragments must be strict base64url and valid UTF-8;
Behaviour and wire changes
-
The book and the deals are plugins (#236, #263). The core builds without evidencebook, and
capsulectl-bookandcapsulectl-dealship as separate assets of the same release. Book commands are nowcapsulectl book …, and the old names run as deprecated aliases until v0.2.0. -
Only
capsulectl dealwrites a deal profile (#242). Corepublish,cll append,cll checkpoint,store initand genericdiscloseare refused on it. Every deal command needs the profile's checkpoint key. -
Deals on an evidencebook shelf (#242). The deal store is moved onto a shelf the first time a deal command writes, and new deals are books on it. A tick checkpoints only the live logs and always holds as many leaves as logs the profile ever had, plus one.
-
deal reconcileis nowdeal audit-host(#281). The old name runs it for one more release, with a warning. -
Book evidence requests follow
evidence-interop/0. These changes are breaking:- The request:
request --requesttakes the draft's request map. The subject is a map with one member ({"full_history":null},{"record":"<digest>"},{"range":[a,b]},{"correlation":"<id>"}),expected_pinis an anchor digest, andmin_freshnessis a log size or an RFC 3339 time. The oldsubject.kind,{root, mmr_size}and{size, time}shapes are refused. - The reply:
respond --outputwrites the profile's signed reply, an envelope or a refusal. An answer is the canonical Artifact the profile defines, never an Evidence Bundle. - The gate:
respond --requester ID, the identity you authenticated, is the only input to the relationship gate. Without it, only public subjects are answered, and every other request gets a signednot_authorized. - Pending requests recorded before the upgrade can't be read back.
request --witness-directoryis refused on a book profile.
New book records with links get different ids from before. Deal profiles are unchanged.
- The request:
-
Book profiles (#236):
- a profile declares who keeps its log (
log: cllorlog: book); publishseals the capsule as the record itself, and claims cite the record id;- a book's
book/payloads/moves into the artifact store the first time it opens; - a reply recorded with
request --responseis kept, sodeal compose --membertakes the request record id alone.
- a profile declares who keeps its log (
-
Plugins receive
--profile: a--profilegiven before a plugin's name reaches the plugin asCAPSULECTL_PROFILE. A deal profile'srequest,respondandcomposeare nowcapsulectl deal request,deal respondanddeal compose, and the old names stay as aliases until v0.2.0. -
result buildrefuses a claim underec:deal-reconcile@1, andresult openlists such claims as not recomputed. -
deal tickretries every pending witness delivery, whether or not a tick is due. -
deal sale closereports what is still open: "stops taking new buyers; N negotiations still open" (#271). -
History steps: readers admit deal steps sealed with the History profile's headers (
step_completed,step_failed). This build still sealsdeal_step(#264).
New
capsulectl plugin install book|deal|./FILEandplugin remove. Installing by name (bookordeal) fetches the plugin from the core's own release, then checks it againstSHA256SUMSand, whenghis installed, against its build provenance. A local./FILEgets neither check.deal terms-resultreconciles both parties' closes of a deal, underec:deal-reconcile@1, and seals the Result on the deal's own results book (#242, #278).--checkre-checks a Result, and a third party both parties name can check one from files alone.capsulectl verify --historychecks a Personal-Agent History at the Basic level (personal_history_basic/1) (#264). Without--holder-key, it exits 3 if nothing else failed.deal sale closeends a sale (#271). A closed sale leaves the cadence once a witnessed tick holds its last checkpoint; a laterdeal sale bundlebrings it back until the next one.deal note --kind evidence --object FILEseals an object the user holds on a buyer's deal, anddeal verify-objectchecks it (#250).
Fixes
- The merchant-email note claims only what the seal shows (#289, #306): this device held the bytes no later than the seal time. The DKIM signature and key are labelled as the signing domain's, which may be the merchant's mail provider.
- A refused plugin says why and how to fix it when you run it (#270). It used to say "operation failed" or "not installed".
- Plugins:
- Pages say what they checked and what they did not. The outcome report counts the criteria it judged (#147, #150).
- The deal profile checker reads its record types from its schema.
Dependencies
- agent-action-capsule/go
go/v0.11.0 - capsule-viewer/go
go/v0.1.1 - evidencebook
v0.6.0 - capsule-emit/go
v0.3.0 - checkpointed-local-log/go
v0.1.0
Verify this release
Assets: capsulectl-v0.1.0-rc17-{linux-amd64,linux-arm64,darwin-arm64}, the plugins capsulectl-v0.1.0-rc17-plugin-{deal,book}-<os>-<arch>, SHA256SUMS, the attestation bundle capsulectl-v0.1.0-rc17.sigstore.json and the release statement files.
In an empty directory:
V=v0.1.0-rc17; R=action-state-group/capsule-cli
gh release download "$V" --repo "$R"
shasum -a 256 -c SHA256SUMS
for f in capsulectl-"$V"-*-*; do
gh attestation verify "$f" --bundle "capsulectl-$V.sigstore.json" --repo "$R" \
--signer-workflow "$R/.github/workflows/release.yml"
doneThe tag is signed with the maintainer's SSH key. To check it, put that key in an allowed-signers file (RELEASE-TRANSPARENCY.md, section 5) and run git -c gpg.ssh.allowedSignersFile=FILE tag -v v0.1.0-rc17. Once the install page, actionstate.ai/install, names this release, it publishes the SHA-256 of the linux/amd64 binary and of the attestation bundle. Those values do not come from the release itself.