Tool packs
tool-pack.v1 (proposed, ADR 0064; built): the unit a user downloads, <name>-<version>-<os>-<arch>.tar.gz, a strict deterministic ustar holding pack.json (kind tool, helper or engine; os, arch, min_gateway, min_client, requires, team_id, entitlements, license, source commit, check report digest, sha256 per file) and its files; tools-index.v1.json lists packs and revoked versions and is signed with ssh-keygen -Y sign -n vulpine-tools-index by the operator's hardware key; vulpine tool pack builds only what vulpine tool check passes, and vulpine tool verify runs every install-time check in order (index signature, archive sha256, per-file sha256, revoked, os and arch, codesign Team ID, lint) with a typed reason per refusal, running nothing from the pack.
Living doc, checked against the code 2026-11-14
tool-pack.v1 — the unit a user downloads: one strict tar.gz, its pack.json, and the signed tools index
- Status: accepted with ADR 0064, version 1.0.
vulpine tool packbuilds a pack andvulpine tool verifychecks one (crates/vulpine_cli/src/pack.rs,pack_verify.rs,pack_verbs.rs,ustar.rs). The gateway’s pack manager installs a pack’s helper and engine archives, behind[packs] enabled = false(extension-pack.v1). The signed first-party index is not published yet. - Scope: what a pack holds, how its bytes are checked, and the index that says which packs exist. Who may call an installed tool is tool-index.v1 and its policy file. How a tool answers is tool.v1.
The archive
<name>-<version>-<os>-<arch>.tar.gz: gzip over a POSIX ustar.
| path | what |
|---|---|
pack.json |
the pack’s record (below) |
tool.toml |
a tool pack’s tool.v1 manifest: handler.kind = "cli", exec = "bin/<program>", handler.digest pinned |
bin/… |
the programs. A Mach-O is arm64, Developer ID signed by the pinned team, with the hardened runtime |
<Name>.app/… |
optional, when a privacy grant needs a bundle |
golden/… |
the tool’s golden calls |
LICENSE |
required |
*.md |
the guide and any other top-level notes |
runtime/… |
an engine pack’s runtime or payload |
What the reader refuses (archive_invalid):
- any entry that is not a regular file: a directory, a link, a device, or a pax or GNU header;
- a header that is not
ustar\000, or whose checksum is wrong; - a path that is absolute, has an empty,
.or..component, is not printable ASCII (or holds a space or\), or is longer than 256 bytes; - a path given twice;
- a mode other than 0644 or 0755;
- a file over 4 GiB, or more than 20,000 entries;
- non-zero padding, a missing end marker, or bytes after it.
A path outside the layout above is layout_invalid.
The writer sorts entries by path and writes uid and gid 0, no owner names, mtime 0 and a gzip header with mtime 0. The same folder always gives the same bytes.
pack.json
{
"schema": "vulpine.pack.v1",
"name": "plant_pack", "kind": "tool", "version": "1.2.0",
"os": "darwin", "arch": "arm64", "min_gateway": "0.1.0", "min_client": "0.1.0",
"requires": [], "team_id": "JJN98M2477", "entitlements": [], "license": "MIT",
"source_commit": "0123456789abcdef0123456789abcdef01234567",
"check_report_digest": "sha256:…",
"helper": null,
"files": { "LICENSE": "sha256:…", "bin/plantctl": "sha256:…", "golden/list_ok.json": "sha256:…", "tool.toml": "sha256:…" }
}
| field | rule |
|---|---|
kind |
tool, helper or engine |
name |
a tool pack: the tool’s name (^[a-z][a-z0-9_]{1,63}$). A helper or engine: its program (vulpine-ambient, - allowed) |
version, min_gateway, min_client |
semver x.y.z |
os, arch |
darwin or linux; arm64 or x86_64. The app installs darwin / arm64 only; the others exist for the fleet probe |
team_id |
ten upper-case letters or digits |
requires |
tokens such as gateway, tcc:<grant>, model:<id>, host:<name> |
entitlements |
the entitlement keys the programs are signed with |
source_commit |
40 lower-case hex, or null |
check_report_digest |
a tool pack’s: the sha256 of vulpine tool check --json’s report with every ms key removed. Null for a helper or engine |
helper |
a helper or engine’s {config_key, exec}: config_key is section.key and exec a listed file. Null for a tool |
files |
every other file in the archive, path: "sha256:<hex>". It must include LICENSE, and tool.toml for a tool pack. It never lists pack.json |
A v1 reader refuses an unknown field. A pack that needs a new field raises min_gateway with it.
pack.toml: what vulpine tool pack reads
schema = "vulpine.pack-source.v1" # optional
kind = "tool" # tool | helper | engine
os = "darwin"
arch = "arm64"
min_gateway = "0.1.0"
min_client = "0.1.0"
team_id = "JJN98M2477"
license = "MIT"
requires = []
entitlements = []
# a helper or engine only:
# name = "vulpine-ambient"
# version = "1.0.0"
# config_key = "ambient.worker_bin"
# exec = "bin/vulpine-ambient"
A tool pack takes its name and version from its tool.toml. A name or version in pack.toml must agree with them.
Unknown keys are refused.
vulpine tool pack <dir>
vulpine tool pack <dir> [--out <folder>] [--source-commit <sha>] [--url-base <url>] [--json]
- It reads pack.toml.
- It walks the folder. Hidden files are skipped and listed in
skipped. A symlink (symlink_in_source), apack.json, or a path outside the layout (layout_invalid) is refused. - A tool pack runs
vulpine tool checkand is refused on any finding (check_failed, naming the rules and goldens). Its handler must becli, withexecinside the pack and listed withhandler.digest’s sha256 (manifest_mismatch). - It hashes every file, writes pack.json, and checks it with the same validator verify uses.
- It writes the archive to a hidden sibling, reads it back through the verifier’s archive layer, and renames it into place.
- It prints
vulpine.tool-pack.v1: the archive’s name, sha256 and size, the pack.json, and theindex_entryCI adds to the index.
Exit codes: 0 built, 1 refused, 2 I/O, 64 usage.
tools-index.v1.json and its signature
{
"schema": "vulpine.tools-index.v1", "generated_at": "2026-11-02T21:00:00Z", "channel": "stable", "min_app": "1.0.0",
"tools": [ { "name": "plant_pack", "kind": "tool", "version": "1.2.0", "os": "darwin", "arch": "arm64",
"url": "https://…/plant_pack-1.2.0-darwin-arm64.tar.gz", "sha256": "sha256:…", "size": 1234,
"team_id": "JJN98M2477", "capabilities": [], "egress": [], "approval": "free", "requires": [],
"min_gateway": "0.1.0", "attestation": null } ],
"revoked": [ { "name": "plant_pack", "version": "1.1.0", "reason": "…" } ]
}
- Entries. An entry is found by the archive’s file name, which is the last segment of
url. A name, version, os and arch listed twice refuses the index. A reader ignores fields it does not know. - Packs. An optional
packsarray lists first-party extension packs, each pointing at itsextension-pack.jsonrecord. An older reader ignores it. Its entries and checks are extension-pack.v1’s. - Signing.
ssh-keygen -Y sign -n vulpine-tools-index -f <key> tools-index.v1.jsonwritestools-index.v1.json.sig. The key lives on the operator’s hardware: a 1Password SSH key behind biometrics, or a YubiKeysk-ssh-ed25519key. CI never holds it. - The allowed-signers file. The app pins it, one line per key:
release-primary@vulpine namespaces="vulpine-tools-index" ssh-ed25519 AAAA…. The pins arecrates/vulpine_cli/pins/tools-index.allowed_signers, embedded in the CLI: the 1Password key asrelease-primary@vulpineand the YubiKey asrelease-backup@vulpine.vulpine tool verifyuses them when--allowed-signersis not given. - Verifying.
/usr/bin/ssh-keygen -Y find-principalsnames the signer, then-Y verify -n vulpine-tools-index -I <principal>checks the bytes. The environment is cleared. The index’s bytes are read once and piped in, so the bytes verified are the bytes parsed.
vulpine tool verify <archive>
vulpine tool verify <archive> [--index <json> --sig <sig> [--allowed-signers <file>]] [--os darwin] [--arch arm64] [--team-id <id>] [--gateway-version <x.y.z>] [--json]
- Defaults. The host’s os and arch, and team
JJN98M2477. - Order. The checks run in the order below and stop at the first refusal. Later checks read
not_reached. - Without an index. Without
--index, checks 1, 2 and 4 areskippedand the report says so. The three index flags go together. - Exit codes. 0 verified, 1 refused, 2 the archive does not open, 64 usage.
| # | check | refuses with |
|---|---|---|
| 1 | index_signature |
index_unreadable, index_signature_invalid (an unlisted key, an edited index, the wrong namespace), index_invalid |
| 2 | archive_sha256 |
not_in_index, archive_sha256_mismatch (sha256 or size) |
| 3 | files |
archive_invalid, pack_json_invalid, layout_invalid, file_missing, file_unlisted, file_sha256_mismatch, index_mismatch (pack.json’s name, version, kind, os, arch or team is not the entry’s) |
| 4 | revoked |
revoked, with the index’s reason |
| 5 | platform |
os_mismatch, arch_mismatch (pack.json, or a Mach-O without the host’s cpu type, fat files read slice by slice), gateway_too_old |
| 6 | code_signature |
team_id_mismatch (pack.json or codesign’s TeamIdentifier), codesign_failed (codesign --verify --strict), hardened_runtime_missing, scratch_unwritable |
| 7 | lint |
lint_failed (the kit’s lint rules), manifest_mismatch (another name or version, a non-cli handler, or an exec that is not a listed 0755 file with handler.digest’s sha256) |
How the code signature is checked:
- Each Mach-O outside a bundle, and each
.appbundle holding one, is extracted to a 0700 scratch folder (under the system temp folder) and hashed again against pack.json. - Codesign then reads exactly the verified bytes. The scratch folder is removed before verify answers.
- A pack without a Mach-O passes this check on its pack.json alone, and the report says so.
Verify runs nothing from the pack. The golden calls run when the pack is built, and the tool manager reruns them as
its preflight. The report, vulpine.tool-verify.v1, has these fields:
- the archive’s file name, its sha256 and size;
- the pack’s identity;
- the signer’s principal;
- one line per check,
{check, status, detail}; refused {check, reason, detail}.
It names files by their pack paths and never by an absolute path.
Versions
A field added to the index is a minor revision. A field added to pack.json moves min_gateway. Any change to the
archive’s rules, to the signature namespace, or to the order of the checks is tool-pack.v2.