Provenance Chain

A Provenance Chain binds three attestations - the publisher's release, the registry's retrieval, and the agent's install - into one tamper-evident object linked to the package artifact by content hash.

The chain answers four narrow questions: who published this artifact, what the registry served, what the agent installed, and whether anyone has rewritten any of those records in the gap. At v0.1 the first three answers are stubs (no enrolled identities); the fourth is real (prev_hash + payload_sha256 catch in-chain tampering).

A canonical chain has three steps. Partial chains are valid; a publish-only chain (no retrieval, no install) verifies fine and is just less useful. The schema allows up to 16 steps per chain so additional install steps can be appended by different agents (see section 7).

• publish - the publisher attests to the build (SLSA-style materials + invocation). Signed by the publisher key. At v0.1 the publisher key is a placeholder.
• retrieval - the registry attests to what it served and to whom. Signed by the registry key. Catches a registry that serves different bytes than the publisher signed.
• install - the agent attests to what it actually installed. Links back to the install receipt (rcpt_ ULID). Signed by the agent key. Catches an agent that loaded a different artifact than what was served. A chain MAY contain more than one install step when the same artifact is installed by multiple agents (see section 7).

{
  "schema": "apai.provenance.v0.1",
  "chain_id": "prov_G0VBD42JEV47C8Z8CZ8Y2TWTTH",
  "package": "coding-safe-mode",
  "package_version": "0.1.0",
  "package_sha256": "aaaaaaaa...64-hex...",
  "trustRoot": "stub-v0.1-no-trust-root",
  "steps": [
    {
      "step_type": "publish",
      "actor": { "id": "apai-official", "kind": "publisher", "key_id": "stub-key-pub-1" },
      "timestamp": "2026-05-14T01:00:00Z",
      "payload_sha256": "<sha256 of canonical payload JSON>",
      "prev_hash": "GENESIS",
      "signature": "stub-ed25519:<hex>",
      "payload": {
        "builder": "github-actions",
        "build_type": "https://github.com/...",
        "reproducible": true
      }
    },
    {
      "step_type": "retrieval",
      "actor": { "id": "apai.run", "kind": "registry" },
      "timestamp": "2026-05-14T01:05:00Z",
      "payload_sha256": "<...>",
      "prev_hash": "<sha256 of canonical(payload_sha256+signature) of publish step>",
      "signature": "stub-ed25519:<hex>"
    },
    {
      "step_type": "install",
      "actor": { "id": "demo-agent", "kind": "agent" },
      "timestamp": "2026-05-14T01:10:00Z",
      "payload_sha256": "<...>",
      "prev_hash": "<sha256 of retrieval step>",
      "signature": "stub-ed25519:<hex>",
      "payload": {
        "install_id": "rcpt_01HXY7G8K9M2P3Q4R5S6T7V8W9",
        "install_mode": "local-tool",
        "target_platform": "claude_code",
        "approval_state": "granted_by_operator_at_install"
      }
    }
  ]
}

Full schema: /schemas/apai.provenance.schema.json.

For each step, two hashes are computed and one is recorded:

• payload_sha256 = sha256( canonicalJson(payload) ). Recorded on the step. Recomputed at verification time; mismatch means the payload was edited after signing.
• prev_hash= sha256( canonicalJson({ payload_sha256, signature }) ) of the PRIOR step, or the literal GENESIS on step 0. Recorded on the CURRENT step. Mismatch means a prior step was rewritten or removed.

canonicalJson sorts object keys recursively before serializing so two independent implementations reach the same hash.

POST to /api/provenance/verify with a chain JSON in the body:

POST https://apai.run/api/provenance/verify
Content-Type: application/json

{ "chain": { ... full provenance chain ... } }

Response (clean 3-step chain):

{
  "schema": "apai.provenance-verify.v0.1",
  "chainIntegrity": "verified",
  "signatures": "stub-v0.1-no-trust-root",
  "trustRoot": "stub-v0.1-no-trust-root",
  "stepsPresent": ["publish", "retrieval", "install"],
  "stepsVerified": [
    "publish:chain-link", "publish:payload-hash",
    "retrieval:chain-link", "retrieval:payload-hash",
    "install:chain-link", "install:payload-hash"
  ],
  "warnings": []
}

Response (tampered retrieval step):

{
  "schema": "apai.provenance-verify.v0.1",
  "chainIntegrity": "broken",
  "signatures": "stub-v0.1-no-trust-root",
  "trustRoot": "stub-v0.1-no-trust-root",
  "stepsPresent": ["publish", "retrieval", "install"],
  "stepsVerified": [
    "publish:chain-link", "publish:payload-hash",
    "install:chain-link", "install:payload-hash"
  ],
  "warnings": [
    "step 1 (retrieval): prev_hash mismatch. expected ..., got ..."
  ]
}

The response shape is enumerated, never binary. Each field tells the caller what kind of "verified" was performed and what was not.

• In-chain rewrites. A chain step edited after assembly fails its prev_hash check on the next step, or its payload_sha256 check on itself.
• Step removal or insertion. Removing a step breaks the prev_hash chain of the next step; inserting a step requires either rehashing everything downstream (visible because the published chain_id no longer matches what verifiers expect) or accepting that the chain immediately fails.
• Payload tampering without re-hashing. An attacker who edits a payload but does not recompute payload_sha256 is caught by the payload-hash check.

The same artifact may be installed by more than one agent in an operator's fleet: Claude Code on one workstation, Codex on a different machine, Gemini CLI on a third. Each install produces its own receipt, but the chain accepts multiple install steps appended after the single publish and retrieval. This is cross-agent attestation.

Ordering rules (v0.1):

• Step 0 is publish. Required for any non-partial chain.
• Step 1 (if present) is retrieval. The registry attests to what was served and to whom.
• Steps 2 through 15 may be any number of install steps. Each install step references its own rcpt_ ULID, its own agent slug, and its own placeholder key_id. Install timestamps SHOULD be monotonically non-decreasing as a chain-author convention, but the chain-link math does not depend on time. At v0.1 /api/provenance/verify does NOT check timestamp ordering; external verifiers MAY add that check.
• prev_hash on each install step links to the step before it, NOT to the retrieval step. The chain is a single linked list, not a tree.
• Chain length cap is maxItems: 16 at v0.1.

Example: one mcp-audit artifact installed by three fleet agents.

{
  "schema": "apai.provenance.v0.1",
  "chain_id": "prov_J3XEF65MGZ7AEBVBE2B2A4XVVH",
  "package": "mcp-audit",
  "package_version": "0.1.0",
  "trustRoot": "stub-v0.1-no-trust-root",
  "steps": [
    { "step_type": "publish",   "actor": { "id": "apai-official",       "kind": "publisher" }, ... },
    { "step_type": "retrieval", "actor": { "id": "apai.run",            "kind": "registry"  }, ... },
    { "step_type": "install",   "actor": { "id": "agent-claude-code",   "kind": "agent",
      "key_id": "stub-key-agent-claude-code-1" }, "payload": { "install_id": "rcpt_01HXY8K2L3..." } },
    { "step_type": "install",   "actor": { "id": "agent-codex-jwgh02",  "kind": "agent",
      "key_id": "stub-key-agent-codex-jwgh02-1" }, "payload": { "install_id": "rcpt_01HXY8M3N4..." } },
    { "step_type": "install",   "actor": { "id": "agent-codex-griffin", "kind": "agent",
      "key_id": "stub-key-agent-codex-griffin-1" }, "payload": { "install_id": "rcpt_01HXY8N4P5..." } }
  ]
}

POST this chain to /api/provenance/verify and the response returns chainIntegrity: "verified" with 10 stepsVerified entries (2 per step: chain-link and payload-hash). One linked list, three attestations from three agents, one publish, one retrieval.

What cross-agent attestation does NOT prove at v0.1: that the three agent identities are distinct humans, distinct keys enrolled in any authority, or distinct machines. The actor.id and actor.key_id are opaque strings; a single attacker who controls a registry can mint a chain with any three key_id values they want and the chain will verify. Cross-agent attestation in v0.1 proves that three install records were assembled into one chain in one order and have not been rewritten since. Distinct verified signers land in v0.2 along with the trust root.