Skip to content

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.

ConstraintAccepts
~1.2.0Patches only, that is 1.2.x
^1.2From 1.2.0 up to but not including 2.0.0
=1.2.0 or 1.2.0Exactly one version
>=1.0 <2.0, ^1.0 || ^2.0A 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.

json
{
  "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.

bash
ph tara install

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

bash
ph tara keys

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

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

Chain of trust for digital signatures. When an approver clicks Duyệt (Approve), Tara signs the package manifest. When a version is yanked, Tara re-signs the revocation list. Phillip, Bandum and Ryoma verify the signature with the trust key the administrator distributed, check revocation, and compare the sha256 in phillip.lock before loading. A valid package loads; a bad signature or a yanked version is rejected.TaraApprove and signEd25519 key,at approvalYank and re-signsigns the list,rising serialPackage, manifestname, version, sha256Revocation listsigned, serialBefore loadingPhillip, Bandum andRyoma check thesignature, revocationand that sha256matches phillip.lockLoadvalidRejectinvalidor yankedTrust keypublic key, issued by admin,not fetched from Taraphillip.locklocked version and sha256of each resource

Swipe sideways to see the whole diagram.

Verifiers hold the public key in advance and never fetch it from Tara at check time. So even if the package store or the Tara database is tampered with, an attacker cannot forge a signature.

Which statuses does a version go through? ​

StatusMeaningInstallable
submitted, checkingJust submitted, automated checks runningNo
checks_failedAutomated checks found errors; submit a new versionNo
awaiting_reviewWaiting for platform staff (official store only)No
changes_requestedReturned with a reasonNo
publishedPassed the checks (and the review, in the official store), signed, and releasedYes
deprecatedDeprecated, hidden from the latest channel; existing locks still workYes, with a warning
yankedYanked for a serious defect and added to the revocation listDownloadable, but a verifier with a key refuses to load it
rejected, removedMalicious code found, package deletedNo

Next steps ​