Version locking and digital signatures
The whole team must install the same build of a resource, and Phillip must know that a package it downloads is the build that was approved. This page explains phillip.lock, digital signatures, and yanking, which guarantee both.
Four layers of assurance
The first layer is the version: phillip.lock in the repo keeps the whole team on the same build. The second is immutability: a package is stored once and is never edited or overwritten, so a published build doesn't change. The third is integrity: the sha256 recorded in the lock tells you whether the downloaded package is the one that was approved. The last is provenance: Tara signs the package with Ed25519, and your machine verifies the signature with a public key it already has.
Semver and version constraints
Every version has the form MAJOR.MINOR.PATCH. When you need another resource, you declare a constraint with the same syntax as npm and Claude Code.
| Constraint | Accepts |
|---|---|
~1.2.0 | Patches only, that is 1.2.x |
^1.2 | From 1.2.0 up to but not including 2.0.0 |
=1.2.0 or 1.2.0 | Exactly one version |
>=1.0 <2.0, ^1.0 || ^2.0 | A range, or a union of several ranges |
Harnesses usually use ~ for agents so your environment stays stable. To move to a new version of an agent, the harness owner releases a new version of the harness. For when to bump each number, see Versioning rules.
phillip.lock
A constraint only says which versions are acceptable. The lock records exactly which version is in use. When you run ph init or ph tara add, Tara resolves all dependencies and returns one exact set of versions, and Phillip writes it to phillip.lock.
{
"schema": 1,
"tara": "https://tara.phillipcli.cloud",
"lockId": "ba8972f4…",
"marketplace": "ai-forge-ba8972f4",
"requirements": [
{ "name": "harness-rnd-sdlc", "version": "^1.5.0" }
],
"resources": [
{
"name": "aiforge/agent-dev",
"pluginId": "agent-dev",
"version": "1.1.1",
"kind": "agent",
"sha256": "61b00027…",
"requiredBy": ["harness-rnd-sdlc"]
}
]
}requirements is what the project asks for directly. Names in the lock are full names (<org>/<name>), and a bare name you ask for resolves to aiforge first, then to your own organization, never to another organization. Claude Code needs a unique plugin name, so every entry has a pluginId: the plain name, or <org>-<name> when two entries share a name (aiforge packages always keep the plain name). resources is the resolved result, including indirect dependencies, and requiredBy shows which resource pulled each one in. lockId is computed from the contents, including names, versions, and sha256 values, so the same set of versions always produces the same lockId. marketplace is the lock's own marketplace name. Each lock needs its own name because Claude Code stores marketplace names globally for every project on the machine.
Commit phillip.lock. On another machine, clone the project and run this command.
ph tara installThis command installs the exact versions in the lock and doesn't resolve again. To move to newer versions within the constraints, run ph tara outdated and then ph tara upgrade. To loosen the constraints to the latest version, use ph tara upgrade --latest.
A published version can't change
The content of a published version never changes. To fix something, you submit a new version. A version number that has been used is never reused, even when the submission was returned.
When you "delete" a resource, Tara doesn't delete the package. It only hides it from the catalog. This way, projects that locked an older version can still install it.
Tara signs at release
When a version is released (approved in the official store, or passed by the scanner anywhere else), Tara signs a statement with an Ed25519 key, in the same transaction. If signing fails, the version isn't released. The statement (type tara.package/v2) records the name, version, type, org, the channel (official, org, user, or community), the package's sha256, the reviewer (the automated scanner outside the official store), and the release time, along with the sha256 of the documents shipped in the package. The name is the bare name; the owner is a separate field called org, which holds an organization slug or a user handle. Channel user means a private personal package: only its owner installs it, and Phillip checks that the owner matches the signed-in user. Channel community means a public package. Changing a resource between private or internal and public re-signs its versions, because the channel changes. A verifier that doesn't know a channel refuses the package, which is the safe default. Statements of the older tara.package/v1 form are still verified. They were written before centers were replaced by organizations: the legacy center field rnd maps to aiforge (official), any other value maps to that organization (channel org), and channel community stays community.
The private key lives outside the database and the package store. You can put it in a KMS so the key never leaves the KMS.
Verify the signature before loading
The side that consumes the package holds the public key in advance, in the form ed25519:<base64>. The administrator distributes this key through a trusted channel together with the environment configuration, and the verifier doesn't fetch the key from Tara at verification time. So even if Tara's package store or database is modified, an attacker can't forge a signature.
On Phillip, you configure the key with ph tara keys trust <key> or the PHILLIP_TARA_KEYS variable. Bandum and Ryoma run plugins on the server, so the administrator sets the matching configuration variable for them.
Once a trusted key exists, the verifier rejects unsigned packages, packages signed with an unknown key, and packages whose statement doesn't match the name, version, or sha256. If there's no key yet, it checks only the sha256 and warns. To see the keys you currently trust, run this command.
ph tara keysBefore you trust a new key, compare its fingerprint with your team lead. One limit to know about: if you install directly with claude plugin without going through Phillip, there is no signature check, and the only protection left is the automated scanner and, in the official store, the review.
The signed revocation list
When a version has a serious defect, platform staff, or an Admin or Owner of the owning organization, yanks it.
ph tara yank agent-dev@1.1.1 --reason "internal path exposed in the prompt"Tara then re-signs the entire list of yanked versions, which includes the org, name, version, sha256, and reason. The private store of an organization has its own list at GET /v1/orgs/{org}/revocations, readable by the organization's members only, because its yanks are not public (yanks of a personal store appear in the owner's own list). The list has a serial number that only increases. A verifier that has a trusted key keeps the copy with the highest serial it has seen and never goes back to an older one. If Tara doesn't respond, they use the stored copy. A package on the list is refused at load time, even if it is already in the cache and its signature is still valid.
Bandum and Ryoma check this list at startup (Bandum also checks the list of its own organization), and ph tara list warns you about yanked versions in your lock.
Swipe sideways to see the whole diagram.
Which statuses does a version go through?
| Status | Meaning | Installable |
|---|---|---|
submitted, checking | Just submitted, automated checks running | No |
checks_failed | Automated checks found errors; submit a new version | No |
awaiting_review | Waiting for platform staff (official store only) | No |
changes_requested | Returned with a reason | No |
published | Passed the checks (and the review, in the official store), signed, and released | Yes |
deprecated | Deprecated, hidden from the latest channel; existing locks still work | Yes, with a warning |
yanked | Yanked for a serious defect and added to the revocation list | Downloadable, but a verifier with a key refuses to load it |
rejected, removed | Malicious code found, package deleted | No |