Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 pack builds a pack and vulpine tool verify checks 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\0 00, 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]

  1. It reads pack.toml.
  2. It walks the folder. Hidden files are skipped and listed in skipped. A symlink (symlink_in_source), a pack.json, or a path outside the layout (layout_invalid) is refused.
  3. A tool pack runs vulpine tool check and is refused on any finding (check_failed, naming the rules and goldens). Its handler must be cli, with exec inside the pack and listed with handler.digest’s sha256 (manifest_mismatch).
  4. It hashes every file, writes pack.json, and checks it with the same validator verify uses.
  5. It writes the archive to a hidden sibling, reads it back through the verifier’s archive layer, and renames it into place.
  6. It prints vulpine.tool-pack.v1: the archive’s name, sha256 and size, the pack.json, and the index_entry CI 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 packs array lists first-party extension packs, each pointing at its extension-pack.json record. 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.json writes tools-index.v1.json.sig. The key lives on the operator’s hardware: a 1Password SSH key behind biometrics, or a YubiKey sk-ssh-ed25519 key. 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 are crates/vulpine_cli/pins/tools-index.allowed_signers, embedded in the CLI: the 1Password key as release-primary@vulpine and the YubiKey as release-backup@vulpine. vulpine tool verify uses them when --allowed-signers is not given.
  • Verifying. /usr/bin/ssh-keygen -Y find-principals names 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 are skipped and 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 .app bundle 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.

Was this page helpful?