Warranties

You claim something about a set of files: origin, licence, consent, who received it, what it leaves out. Permafrost records the claim, signs what it saw itself, and updates the warranty when a file is withdrawn. Anyone can check it.

The issuer warrants issuer-claimed. Permafrost witnesses witnessed.

• Training data. A vendor shows the lab origin, licence, consent, delivery, honoured withdrawals and excluded evaluation items, as a record that updates when a contributor withdraws.
• Agents. In an agent space: “the referee decided over exactly these sealed bids, all on time.” After the space is gone, each bidder can still show its bid was in the decided set.

Issuing one

Prepare, then issue within two minutes:

POST /v1/warranties/prepare
Authorization: Bearer <your key, a configured sign-in, or a delegated token>

POST /v1/warranties

• Prepare resolves the set as you (only what your credential can read) and returns the unsigned document and the files it covers.
• Issue carries your signature over that exact document. The signature is the credential, as for a revocation.
• 409 if a file changed or moved in between (“a member moved since prepare; prepare again” for a move). Prepare again.
• Lost the answer? Repeat the prepare. An issued warranty comes back as issued: true; issuing again returns the same warranty, never a second.
• Who issues: a bucket’s owner, an agent space’s referee, or an author over its own files. A delegate can prepare; only the issuer’s key signs.

A set is a list of files, or, in an agent space, a selector: current items matching a key pattern (*/bid/3: any author’s bid/3) last modified within a window. At most 10,000 files and 400 days.

What you can claim

Claim	You say issuer-claimed	Permafrost witnesses witnessed
license	the set is under this licence	only that your evidence documents are on record
consent	the basis on which you hold it	the same
region	the data is held in this region	the declared region, and every copy of every file in it: on the deployment or an archive backend declared there. Any Walrus copy, or a backend declared elsewhere, refuses the claim
excluded-from	no file is in a set E (e.g. an evaluation set)	each comparable file (one with a plain fingerprint) is not an exact copy of an item of E
delivered-to	this buyer received the set	files the buyer read in full at the warranted version. HEAD and partial reads don’t count
outcome	this decision was made over exactly this set	completeness: every on-time item, none missing
derived-from	derived from these warranties (id and digest each)	each was issued here, unchanged, not retracted, not expired, and how many of its files remained

Licence, consent and outcome are your word, recorded against exactly these files with the evidence you named. issuer-claimed

What Permafrost witnesses

A statement signed with the deployment’s ledger key: files held; Walrus copies; archive backend copies and which backends (declared region, ours or yours); the declared region; full reads by the buyer; files compared against the excluded set; and, for a selector, completeness for its window. The ledger key is ours, so this is our word about what we saw witnessed. The warranty becomes a public ledger entry.

Nothing public is guessable. The set root is a Merkle root over the files’ ledger entries, which carry random nonces, not over contents. A short item such as a bid can’t be confirmed by guessing.

Checking one

Anyone holding the id (long, random) can read it. The answer includes a bundle: signed warranty, witness statement, ledger proofs, every change. Save it and check offline:

GET /v1/warranties/<id>

pf-verify warranty bundle.json --signer-pk <the ledger key> --sui-log <the Log id> --rpc <a Sui gRPC url> --gateway <your deployment>

Prints VALID, INVALID or RETRACTED (exit code 4), plus the claims, the witness and the change history. verifiable

Membership. A file’s holder can ask whether it is in the set, using the fingerprint only a reader has. A member gets its place and its ledger entry with proof; a non-member gets the two neighbouring entries, proving its absence. verifiable

GET /v1/warranties/<id>/membership?bucket=<b>&key=<k>&fp=<fingerprint>

Supply-chain tooling. pf-verify warranty export bundle.json --format in-toto --members members.json writes an in-toto Statement whose subjects are the set’s files (give every member’s membership answer). It adds no signature and isn’t a COSE-encoded SCITT statement.

When the set changes

• A file leaves (deleted, overwritten, revoked, or destroyed with its space): every warranty naming it records a change, e.g. “3 withdrawn (revocation, certificate rc_…), 9 remain”, each checked against its own ledger entry. witnessed
• A file moves against the witness (a Walrus copy where none was counted, a copy outside a claimed region, an unnamed archive backend): a placement change records where its copies are now. Nothing is withdrawn.
• An agent space ends: proof outlives it, never content.

Follow changes by number, passing the last one you hold:

GET  /v1/warranties/<id>/changes?after=<n>
POST /v1/warranties/changes        {"after": {"<id>": "<n>", …}}   (up to 100 warranties)

No webhooks. A buyer honours a withdrawal only if it learns of it, so poll on a schedule you can defend.

When a warranty ends

• Expiry. After the end date a final expired change is recorded; the verifier prints “tracked until ; later changes are not recorded”. No expired entry means still tracked.
• Retract with POST /v1/warranties/<id>/retract, e.g. when a named licence proves wrong. The body is the issuer’s signed statement (id, reason, time), same key and method as the warranty issuer-claimed. It becomes the last change; the verifier prints RETRACTED, time and reason, and exits 4.
• End a key that leaked or was replaced: sign an end statement with it and send it to POST /v1/warranties/key-end. The deployment records the end at its own time, so it can’t be backdated, and refuses the key afterwards. Earlier warranties still check, marked “issuer key ended at ”. The statement names no deployment; send it to every one you use.

Building on another warranty

derived-from chains vendor → lab → fine-tune, at most eight links. The deployment states only that each upstream warranty existed here, unchanged, not retracted and not expired, at witness time witnessed. GET /v1/warranties/<id> includes the upstream bundles, and the verifier checks each link. A later upstream retraction still checks downstream and is shown.

What you are trusting

Checking needs no call to Permafrost, but some claims rest on the deployment’s word. A dishonest operator:

Could:

• Hold back a change: suppress a deletion or overwrite before the ledger records it, so the file still reads as in the set.
• Delay publishing. Records reach Sui when there is something to record. If no record reaches Sui after an entry’s time once one was due, pf-verify leaf reports it as withheld. Only a holder of the entry can tell: to anyone else a quiet deployment and one holding records back look the same.
• Stop answering. A saved bundle still checks.

Could not, and you can check each verifiable:

• Forge a member’s entry. Its hash sits in a root on Sui; a changed entry fails its proof (--sui-log).
• Alter a signed warranty. One changed byte fails the issuer’s signature.
• Change what it witnessed. The statement is signed and its entry is in a published root. Pin the key with --signer-pk.
• Fake “not in the set”. The two neighbours must each prove a path to the signed root, be adjacent, and bracket the entry; the verifier checks all three.
• Backdate a key end. The end is the deployment’s own ledger entry in a published root, compared with the witness time.
• Rewrite a published record. Each names the previous record’s hash; the Sui log checks that link itself and accepts only the next record in sequence, so every older record checks against the newest one.

Limits

• Delivery counts full reads of the warranted version only.
• Exclusion is exact match, and only for unsalted fingerprints. A re-encoded, cropped or paraphrased copy passes. An encrypted file’s fingerprint is salted by default, so an exclusion doesn’t compare it: upload the files an exclusion must cover with x-amz-meta-permafrost-fingerprint-kind: plaintext.
• The count is visible to every id holder. In an auction, that’s how many bids arrived on time.
• Issuer claims aren’t verified, only bound to the files issuer-claimed.
• Authorship is witnessed. Which tenant wrote a file is what the deployment saw at the write, not a signature of yours witnessed.
• A signature counts for whoever holds the key. Where we hold an issuer’s key, as for a demo deployment’s demo tenant, its warranties are our statement, not the issuer’s.
• Witnessed facts are as of the witness time. A storage lease that runs out isn’t recorded as a change; renewal keeps it witnessed.
• As complete as the ledger. A change the ledger never records reaches no warranty.
• Backups can hold a withdrawn or destroyed file until they age out.