Skip to content

SPECIFICATION.md

Latest commit

 

History

History
158 lines (118 loc) · 7.26 KB

SPECIFICATION.md

File metadata and controls

158 lines (118 loc) · 7.26 KB
Raw

Proof Pack Specification

Version 0.1.0

1. Purpose

A Proof Pack is a portable, verifiable record that a maintenance job was completed, which surfaces were covered, and the before/after evidence that proves it.

The goal is to make a service outcome auditable by a third party (a client, a facilities manager, an insurer, or a regulator) without that party having to trust the provider's word or reconstruct the job from raw logs. A Proof Pack answers four questions in a single package:

  1. What job was done, where, and when?
  2. What was covered, and how completely?
  3. What did the work look like before and after?
  4. Has any of this been altered since it was issued?

This specification defines the package layout and the manifest format. It does not define how evidence is captured, scored, or rendered. Those are implementation concerns left to the provider.

2. Relationship to existing standards

A Proof Pack deliberately does not reinvent per-image authenticity. It operates one level up, at the package layer, and references lower-level standards where they fit:

  • C2PA / Content Credentials provide cryptographic provenance for an individual media file. A Proof Pack records whether each media file carries a C2PA manifest (media.c2pa) and relies on C2PA for per-asset signing where available.
  • Chain of custody practice informs the custody fields: the issuer, the asset, the accountable operator, and capture timestamps.
  • Hash chaining (a SHA-256 chain, as used in tamper-evident audit logs) links a Proof Pack to the previous pack issued by the same issuer, so that packs cannot be silently removed or reordered after the fact.

3. Related work and where Proof Pack sits

Several open projects address pieces of the verifiable-evidence problem. A Proof Pack is designed to compose with them, not replace them. It occupies the gap none of them fill: a vendor-neutral description of a service job's outcome.

  • C2PA and ProofMode secure a single media file at the point of capture. They answer "is this image authentic and unedited?" They do not describe what job the image belongs to, which surface it shows, or whether the work was completed. A Proof Pack references them per file and adds the job context around them.
  • W3C Verifiable Credentials are a generic envelope for signed claims, with a pluggable proof mechanism. A Proof Pack is domain content, not an envelope: a Proof Pack manifest can be embedded as the credentialSubject of a Verifiable Credential where an issuer wants VC-based signing and presentation.
  • OpenTimestamps provides blockchain-backed timestamp proofs for arbitrary data. A Proof Pack's manifestHash can be timestamped with OpenTimestamps to add independent proof that the pack existed at a point in time.
  • IFC (ISO 16739) and the Facility Data Standard model the building and its assets for BIM and facility lifecycle data. They describe the thing being maintained, not the evidence that a given maintenance job was carried out. A Proof Pack's site and surfaces can reference identifiers from those models.

In short: existing standards authenticate a file, carry a claim, timestamp a hash, or model a building. A Proof Pack ties a job's evidence together into one checkable package and leaves those lower layers to the standards that already do them well.

4. Package layout

A Proof Pack is a directory (which may be distributed as a single ZIP archive):

proof-pack/
  manifest.json        # the Proof Pack manifest, conforming to schema/proof-pack.schema.json
  media/               # referenced media files
    before-01.jpg
    after-01.jpg
    heatmap.png

manifest.json is the authoritative record. Every media file referenced by the manifest carries a sha256 of its bytes, so a file cannot be swapped without invalidating the manifest. Media may also be referenced by absolute URL instead of a local path; the content hash requirement is unchanged.

5. Manifest structure

The manifest is a single JSON object. The normative definition is schema/proof-pack.schema.json (JSON Schema, draft 2020-12). The top-level fields are:

Field Required Description
specVersion yes The specification version, e.g. 0.1.0.
id yes Globally unique identifier for the pack (UUID recommended).
issuer yes The organization that produced and stands behind the pack.
job yes The job: id, service type, and completion time.
site yes Where the work was performed.
assets no The robots, drones, or equipment used, and the accountable operator.
surfaces no The distinct surfaces or zones serviced, with area and material.
coverage no Planned vs covered area, coverage percentage, and an optional heatmap.
evidence yes Captured media. At least one item is required.
integrity yes Tamper-evidence for the pack as a whole.

5.1 Evidence and before/after pairs

Each evidence item has a kind (before, after, during, defect, thermal, wide, other). A before item and its matching after item are linked by a shared pairId. Both items should reference the same surfaceId. This lets a consumer line up a verifiable before/after comparison per surface rather than guessing from filenames.

5.2 Coverage

coverage quantifies the outcome. coveragePercent is the headline number; it should be consistent with coveredAreaSqm / plannedAreaSqm when both are present. The optional heatmap media reference points at a rendered coverage or dirt heatmap.

6. Integrity

The integrity object makes the pack tamper-evident.

6.1 Manifest hash

integrity.manifestHash is the hash of the canonicalized manifest with the integrity.manifestHash and integrity.signature fields excluded from the input.

Canonicalization, for the purpose of this version, is RFC 8785 JSON Canonicalization Scheme (JCS): UTF-8, lexicographically sorted object keys, no insignificant whitespace. A verifier recomputes the hash over the canonical form and compares.

6.2 Hash chain

integrity.previousHash, when present, is the manifestHash of the previous Proof Pack issued by the same issuer. A consumer holding a series of packs can confirm the chain is intact and that no pack was dropped or reordered.

6.3 Signature

integrity.signature is an optional detached signature over manifestHash. The signing algorithm, the public key, and an optional certificate chain are recorded so a verifier can confirm the pack was issued by the claimed issuer. Per-image signing is left to C2PA; this signature covers the manifest.

7. Validation

A document is a valid Proof Pack if all of the following hold:

  1. It validates against schema/proof-pack.schema.json.
  2. Every referenced media file is present and its bytes hash to the recorded sha256.
  3. integrity.manifestHash matches the recomputed hash from section 6.1.
  4. If integrity.signature is present, it verifies against manifestHash.

8. Conformance and versioning

This specification uses semantic versioning. Within a 0.x series, the format may change between minor versions. specVersion in a manifest states the version it was written against.

9. License

This specification and the accompanying schema are released under the Apache License, Version 2.0. See LICENSE.