Skip to content

capsulectl v0.1.0-rc17

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 20 Oct 20:13
· 203 commits to main since this release
318d5f1

capsulectl 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 tick on 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 gave deal 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 --materiality or keys moved with profile 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.yaml
    

    Then 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 $HOME down to ~/.local/lib/capsulectl/plugins. On stock Ubuntu (umask 002) a hand-installed plugin under a group-writable ~/.local stops running until chmod 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 named opening.* (#242). A deal terms-result Result 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; domain and provenance must be strings; Producer Envelopes must be strictly encoded CBOR.
    • Witness receipts:
      • one with a rekor or scrapi binding 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.
    • 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_progress is 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_differs finding names its legs differently in two cases.
    • result build: it admits x- members on the document and on a claim, and an optional coverage_report. Every other member stays closed, including X-….

Behaviour and wire changes

  • The book and the deals are plugins (#236, #263). The core builds without evidencebook, and capsulectl-book and capsulectl-deal ship as separate assets of the same release. Book commands are now capsulectl book …, and the old names run as deprecated aliases until v0.2.0.

  • Only capsulectl deal writes a deal profile (#242). Core publish, cll append, cll checkpoint, store init and generic disclose are 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 reconcile is now deal 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 --request takes the draft's request map. The subject is a map with one member ({"full_history":null}, {"record":"<digest>"}, {"range":[a,b]}, {"correlation":"<id>"}), expected_pin is an anchor digest, and min_freshness is a log size or an RFC 3339 time. The old subject.kind, {root, mmr_size} and {size, time} shapes are refused.
    • The reply: respond --output writes 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 signed not_authorized.
    • Pending requests recorded before the upgrade can't be read back.
    • request --witness-directory is refused on a book profile.

    New book records with links get different ids from before. Deal profiles are unchanged.

  • Book profiles (#236):

    • a profile declares who keeps its log (log: cll or log: book);
    • publish seals 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 --response is kept, so deal compose --member takes the request record id alone.
  • Plugins receive --profile: a --profile given before a plugin's name reaches the plugin as CAPSULECTL_PROFILE. A deal profile's request, respond and compose are now capsulectl deal request, deal respond and deal compose, and the old names stay as aliases until v0.2.0.

  • result build refuses a claim under ec:deal-reconcile@1, and result open lists such claims as not recomputed.

  • deal tick retries every pending witness delivery, whether or not a tick is due.

  • deal sale close reports 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 seals deal_step (#264).

New

  • capsulectl plugin install book|deal|./FILE and plugin remove. Installing by name (book or deal) fetches the plugin from the core's own release, then checks it against SHA256SUMS and, when gh is installed, against its build provenance. A local ./FILE gets neither check.
  • deal terms-result reconciles both parties' closes of a deal, under ec:deal-reconcile@1, and seals the Result on the deal's own results book (#242, #278). --check re-checks a Result, and a third party both parties name can check one from files alone.
  • capsulectl verify --history checks 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 close ends a sale (#271). A closed sale leaves the cadence once a witnessed tick holds its last checkpoint; a later deal sale bundle brings it back until the next one.
  • deal note --kind evidence --object FILE seals an object the user holds on a buyer's deal, and deal verify-object checks 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:
    • a plugin gets CAPSULECTL_BIN (#234);
    • a plugin's exit code is capsulectl's;
    • plugin presentation manifests follow presentation contract revision 1 (#293).
  • 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"
done

The 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.