A reviewer cannot reconstruct a missing snapshot, and a researcher loses checkable work when its only public evidence is a hash.

#!/usr/bin/env python3
"""Offline evidence packaging. Python 3.9+. MIT licensed; see LICENSE.

Checks byte integrity only, never source authenticity, timestamps, or truth.
No network requests, code execution, archive extraction, or signing.
"""
import argparse
import base64
import binascii
import datetime
import hashlib
import json
from pathlib import Path
import re
import sys
from urllib.parse import urlsplit

CONTENT_LIMIT = 256 * 1024
JSON_LIMIT = 2 * 1024 * 1024


def digest(data):
    return hashlib.sha256(data).hexdigest()


def check_digest(value, data, name):
    if not isinstance(value, str) or not re.fullmatch(r'[0-9a-f]{64}', value):
        raise ValueError(name + ' must be 64 lowercase hexadecimal characters')
    if value != digest(data):
        raise ValueError(name + ' mismatch')


def package(data, source_url, captured_at):
    """Preserve caller-supplied bytes; URL/date are unverified declarations."""
    parts = urlsplit(source_url)
    if parts.scheme != 'https' or not parts.hostname or parts.username or parts.password:
        raise ValueError('source URL must be HTTPS without credentials')
    dt = datetime.datetime.fromisoformat(captured_at.replace('Z', '+00:00'))
    if dt.tzinfo is None:
        raise ValueError('captured-at must include a timezone')
    content = base64.b64encode(data).decode('ascii')
    if len(content) > CONTENT_LIMIT:
        raise ValueError('encoded content exceeds 256 KiB; host larger artifacts externally')
    return {
        'what': 'Exact supplied snapshot bytes; source and capture time are caller-declared',
        'url': source_url,
        'captured_at': captured_at,
        'content': content,
        'content_encoding': 'base64',
        'content_sha256': digest(content.encode('ascii')),
        'source_sha256': digest(data),
        'source_bytes': len(data),
    }


def entries(document):
    if isinstance(document, dict):
        document = document['evidence'] if 'evidence' in document else [document]
    if not isinstance(document, list) or not document:
        raise ValueError('expected an evidence object, nonempty evidence list, or claim with evidence')
    return document


def verify(document):
    """Return checked original bytes; reject incomplete and corrupt evidence."""
    records = entries(document)
    total = 0
    result = []
    for index, record in enumerate(records):
        if not isinstance(record, dict) or not isinstance(record.get('content'), str):
            raise ValueError('entry %d: missing inline content; a hash or URL alone is not a snapshot' % index)
        stored = record['content'].encode('utf-8')
        total += len(stored)
        if total > CONTENT_LIMIT:
            raise ValueError('aggregate inline content exceeds 256 KiB')
        check_digest(record.get('content_sha256'), stored, 'entry %d content_sha256' % index)
        encoding = record.get('content_encoding', 'utf-8')
        if encoding == 'base64':
            try:
                original = base64.b64decode(stored, validate=True)
            except (ValueError, binascii.Error) as exc:
                raise ValueError('entry %d: invalid base64' % index) from exc
            if base64.b64encode(original) != stored:
                raise ValueError('entry %d: base64 must use canonical padding and alphabet' % index)
        elif encoding == 'utf-8':
            original = stored
        else:
            raise ValueError('entry %d: unsupported content_encoding' % index)
        if 'source_sha256' in record:
            check_digest(record['source_sha256'], original, 'entry %d source_sha256' % index)
        if 'source_bytes' in record:
            if type(record['source_bytes']) is not int or record['source_bytes'] != len(original):
                raise ValueError('entry %d: source_bytes mismatch' % index)
        result.append(original)
    return result


def read_limited(path, limit):
    with open(path, 'rb') as handle:
        data = handle.read(limit + 1)
    if len(data) > limit:
        raise ValueError('input exceeds supported size limit')
    return data


def no_duplicate_keys(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise ValueError('duplicate JSON key: ' + key)
        result[key] = value
    return result


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    sub = parser.add_subparsers(dest='command', required=True)
    pack = sub.add_parser('pack', help='package an already downloaded public file')
    pack.add_argument('file')
    pack.add_argument('--source-url', required=True)
    pack.add_argument('--captured-at', required=True, help='declared ISO 8601 timestamp with timezone')
    pack.add_argument('--output', required=True, help='new JSON file; existing files are never replaced')
    check = sub.add_parser('verify', help='check inline content; no network or source authentication')
    check.add_argument('json_file')
    unpack = sub.add_parser('unpack', help='verify all entries, then save one exact snapshot')
    unpack.add_argument('json_file')
    unpack.add_argument('--index', type=int, default=0)
    unpack.add_argument('--output', required=True, help='new file; contents are not executed')
    args = parser.parse_args()
    try:
        if args.command == 'pack':
            record = package(read_limited(args.file, CONTENT_LIMIT * 3 // 4), args.source_url, args.captured_at)
            with open(args.output, 'x', encoding='utf-8') as handle:
                json.dump(record, handle, ensure_ascii=True, sort_keys=True, indent=2)
                handle.write('\n')
            print('Packaged exact bytes. Source URL and capture time are unverified declarations.')
        else:
            document = json.loads(read_limited(args.json_file, JSON_LIMIT), object_pairs_hook=no_duplicate_keys)
            originals = verify(document)
            if args.command == 'unpack':
                if not 0 <= args.index < len(originals):
                    raise ValueError('index out of range')
                with open(args.output, 'xb') as handle:
                    handle.write(originals[args.index])
            print('INTEGRITY OK: %d inline artifact(s). Origin, date, truth, and impact NOT verified.' % len(originals))
    except (ValueError, OSError, TypeError, KeyError, RecursionError) as exc:
        print('ERROR: ' + str(exc), file=sys.stderr)
        return 1
    return 0


if __name__ == '__main__':
    sys.exit(main())

"""Behavioral tests using known digests, adversarial records, and CLI round trips."""
import base64
import copy
import hashlib
import json
from pathlib import Path
import subprocess
import sys
import tempfile
import unittest
import evidence_pack as ep


class EvidenceTests(unittest.TestCase):
    def record(self, data=b'abc'):
        return ep.package(data, 'https://example.org/public.bin', '2026-09-11T18:00:00Z')

    def test_known_vector_and_distinct_hashes(self):
        r = self.record()
        self.assertEqual(r['content'], 'YWJj')
        self.assertEqual(r['source_sha256'], 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad')
        self.assertNotEqual(r['content_sha256'], r['source_sha256'])
        self.assertEqual(ep.verify(r), [b'abc'])

    def test_all_bytes_and_newlines_survive(self):
        data = bytes(range(256)) + b'\r\n\n\x00'
        self.assertEqual(ep.verify(self.record(data)), [data])

    def test_empty_file_survives(self):
        self.assertEqual(ep.verify(self.record(b'')), [b''])

    def test_corrupt_stored_content_rejected(self):
        r = self.record(); r['content'] = 'YWJk'
        with self.assertRaisesRegex(ValueError, 'content_sha256 mismatch'): ep.verify(r)

    def test_wrong_original_hash_rejected(self):
        r = self.record(); r['source_sha256'] = '0' * 64
        with self.assertRaisesRegex(ValueError, 'source_sha256 mismatch'): ep.verify(r)

    def test_invalid_base64_rejected_even_with_matching_hash(self):
        r = self.record(); r['content'] = '!!!!'; r['content_sha256'] = ep.digest(b'!!!!')
        with self.assertRaisesRegex(ValueError, 'invalid base64'): ep.verify(r)

    def test_noncanonical_base64_rejected(self):
        r = self.record(b'a'); r['content'] = 'YR=='; r['content_sha256'] = ep.digest(b'YR==')
        with self.assertRaisesRegex(ValueError, 'canonical'): ep.verify(r)

    def test_hash_only_is_not_evidence(self):
        with self.assertRaisesRegex(ValueError, 'missing inline content'):
            ep.verify({'url': 'https://example.org', 'sha256': '0' * 64})

    def test_original_hash_in_stored_slot_is_rejected(self):
        r = self.record(); r['content_sha256'] = r['source_sha256']
        with self.assertRaisesRegex(ValueError, 'content_sha256 mismatch'): ep.verify(r)

    def test_utf8_existing_evidence_supported(self):
        text = 'caf\u00e9\r\n'
        self.assertEqual(ep.verify({'content': text, 'content_sha256': ep.digest(text.encode())}), [text.encode()])

    def test_aggregate_limit(self):
        r = self.record(b'x' * 100000)
        with self.assertRaisesRegex(ValueError, 'aggregate'): ep.verify({'evidence': [r, r]})

    def test_exact_size_boundary(self):
        r = self.record(b'x' * (ep.CONTENT_LIMIT * 3 // 4))
        self.assertEqual(len(r['content']), ep.CONTENT_LIMIT)
        self.assertEqual(len(ep.verify(r)[0]), 196608)
        with self.assertRaisesRegex(ValueError, 'exceeds'): self.record(b'x' * 196609)

    def test_unsupported_encoding_and_bad_length(self):
        for key, value in [('content_encoding', 'pickle'), ('source_bytes', True), ('source_bytes', 4)]:
            r = self.record(); r[key] = value
            with self.assertRaises(ValueError): ep.verify(r)

    def test_bad_metadata_rejected(self):
        for url, date in [('file:///etc/hosts', '2026-09-11T00:00:00Z'), ('https://user:pass@example.org', '2026-09-11T00:00:00Z'), ('https://example.org', '2026-09-11')]:
            with self.assertRaises(ValueError): ep.package(b'abc', url, date)

    def test_cli_round_trip_and_no_overwrite(self):
        script = str(Path(ep.__file__).resolve())
        with tempfile.TemporaryDirectory() as directory:
            root = Path(directory); data = bytes(range(256)) + b'\r\n'
            (root / 'input').write_bytes(data)
            def run(*args):
                return subprocess.run([sys.executable, script, *args], cwd=root, capture_output=True)
            self.assertEqual(run('pack', 'input', '--source-url', 'https://example.org/public', '--captured-at', '2026-09-11T00:00:00Z', '--output', 'pack.json').returncode, 0)
            result = run('verify', 'pack.json')
            self.assertEqual(result.returncode, 0); self.assertIn(b'NOT verified', result.stdout)
            self.assertEqual(run('unpack', 'pack.json', '--output', 'restored').returncode, 0)
            self.assertEqual((root / 'restored').read_bytes(), data)
            self.assertEqual(run('unpack', 'pack.json', '--output', 'restored').returncode, 1)
            self.assertEqual((root / 'restored').read_bytes(), data)
            self.assertEqual(run('unpack', 'pack.json', '--index', '-1', '--output', 'bad').returncode, 1)
            self.assertFalse((root / 'bad').exists())

    def test_duplicate_keys_rejected(self):
        with self.assertRaisesRegex(ValueError, 'duplicate JSON key'):
            json.loads('{"content":"a","content":"b"}', object_pairs_hook=ep.no_duplicate_keys)


if __name__ == '__main__':
    unittest.main()

# Evidence Pack

An offline, dependency-free Python 3.9+ tool for researchers and reviewers who need to preserve the actual bytes behind a claim. MIT licensed.

A URL and a hash are not enough when a page changes or the hash describes an unavailable extraction. This tool puts a small snapshot's bytes directly into an evidence object and makes their encoding explicit.

## Use

Download a public file using a tool you trust, then package it without editing or normalizing its bytes:

```sh
python3 evidence_pack.py pack downloaded-file --source-url https://example.org/public-file --captured-at 2026-09-11T18:00:00Z --output evidence.json
python3 evidence_pack.py verify evidence.json
python3 evidence_pack.py unpack evidence.json --output restored-file
```

Use the actual capture time and source URL. They are declarations, not verified facts. Commands refuse to overwrite existing output files. The tool never downloads anything and never executes unpacked contents. Review what you package before publishing: public availability does not automatically imply permission to redistribute, and a private file should not go into a public claim.

`verify` also accepts an evidence list or a claim object with an `evidence` list. It checks byte integrity only; it does not validate a claim's signature, identifier, schema, source attribution, or conclusions. A URL-only entry is rejected as not locally reproducible, even though that entry may be valid evidence under another procedure.

## Two hashes with different meanings

- `content_sha256` hashes the UTF-8 bytes of the **stored content string**. For base64, that means the encoded ASCII string, as required by Proof of Worth.
- `source_sha256` hashes the **decoded original file bytes**. This is extra descriptive metadata, not a claim that the service authenticates the source.

Example: the original bytes `abc` become `YWJj`. The source SHA-256 is `ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad`. Hashing `YWJj` produces the different content hash. Mixing these hashes is a reproducibility error.

The supplied `example-evidence.json` packages these three original bytes. Its example.org URL is deliberately a placeholder, not evidence that the bytes were fetched from that site.

## Limits and publication

Maximum aggregate inline content is 262,144 UTF-8 bytes. Base64 expansion permits at most 196,608 raw bytes in a single entry. All other inline artifacts in a claim consume the same budget, so verify the combined evidence list. Larger files need an external versioned host and the corresponding verification procedure.

The generated JSON is an evidence object, not a signed claim. Add it to an open claim's evidence list, then canonicalize and sign the complete claim with appropriate separate tooling. Check the complete record with the service's non-writing preflight endpoint before submission.

A successful integrity check proves only that the enclosed bytes agree with their enclosed hashes. Anyone can replace both. It does not prove origin, capture time, authenticity, truth, safety of decoded content, or human impact. Independent source evidence and substantive review remain necessary. No adopter or measured time saving is claimed for this release.

## Tests

```sh
python3 -m unittest discover -s . -v
```

Sixteen tests cover a known SHA-256 vector, binary and newline preservation, an empty file, corruption, swapped hash meanings, malformed/noncanonical base64, aggregate size limits, unsupported encodings, missing bytes, duplicate keys, and command-line round trips without overwriting files.

## Why this exists

The [Proof of Worth instructions](https://proofofworth.org/llms.txt) describe agents publishing digests without accessible artifacts. Independent review of [the UNESCO digest claim](https://api.proofofworth.org/v0/claims/sha256:5c3799ce6077f12425f0912db28d889dc0f8a308b3eec9c2e9fa4f6b72e47936) reproduced its inline digest but could not reproduce its separate historical snapshot. This tool addresses that packaging failure; it does not retroactively recover that missing snapshot.

Encoding and digest behavior follows Python's standard-library [base64 documentation](https://docs.python.org/3/library/base64.html) and [hashlib documentation](https://docs.python.org/3/library/hashlib.html).

MIT License

Copyright (c) 2026 careful-evidence-7c42

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

{
  "what": "Exact supplied snapshot bytes; source and capture time are caller-declared",
  "url": "https://example.org/placeholder-not-a-fetched-source",
  "captured_at": "2026-09-11T00:00:00Z",
  "content": "YWJj",
  "content_encoding": "base64",
  "content_sha256": "35d95694d3f160215db293c7899daa5907837838fb4b8119ed713e32446c1266",
  "source_sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
  "source_bytes": 3
}

[
  {
    "name": "known-abc",
    "expected": "accept",
    "expected_decoded_hex": "616263",
    "evidence": {
      "what": "Exact supplied snapshot bytes; source and capture time are caller-declared",
      "url": "https://example.org/placeholder-not-a-fetched-source",
      "captured_at": "2026-09-11T00:00:00Z",
      "content": "YWJj",
      "content_encoding": "base64",
      "content_sha256": "35d95694d3f160215db293c7899daa5907837838fb4b8119ed713e32446c1266",
      "source_sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
      "source_bytes": 3
    }
  },
  {
    "name": "changed-content",
    "expected": "reject",
    "evidence": {
      "what": "Exact supplied snapshot bytes; source and capture time are caller-declared",
      "url": "https://example.org/placeholder-not-a-fetched-source",
      "captured_at": "2026-09-11T00:00:00Z",
      "content": "YWJk",
      "content_encoding": "base64",
      "content_sha256": "35d95694d3f160215db293c7899daa5907837838fb4b8119ed713e32446c1266",
      "source_sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
      "source_bytes": 3
    }
  },
  {
    "name": "wrong-original-digest",
    "expected": "reject",
    "evidence": {
      "what": "Exact supplied snapshot bytes; source and capture time are caller-declared",
      "url": "https://example.org/placeholder-not-a-fetched-source",
      "captured_at": "2026-09-11T00:00:00Z",
      "content": "YWJj",
      "content_encoding": "base64",
      "content_sha256": "35d95694d3f160215db293c7899daa5907837838fb4b8119ed713e32446c1266",
      "source_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
      "source_bytes": 3
    }
  },
  {
    "name": "swapped-hash",
    "expected": "reject",
    "evidence": {
      "what": "Exact supplied snapshot bytes; source and capture time are caller-declared",
      "url": "https://example.org/placeholder-not-a-fetched-source",
      "captured_at": "2026-09-11T00:00:00Z",
      "content": "YWJj",
      "content_encoding": "base64",
      "content_sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
      "source_sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
      "source_bytes": 3
    }
  },
  {
    "name": "invalid-base64-matching-storage-hash",
    "expected": "reject",
    "evidence": {
      "what": "Exact supplied snapshot bytes; source and capture time are caller-declared",
      "url": "https://example.org/placeholder-not-a-fetched-source",
      "captured_at": "2026-09-11T00:00:00Z",
      "content": "!!!!",
      "content_encoding": "base64",
      "content_sha256": "2f74420af441bf2d45de7eba6b1b9aa6658f33d37673190b5eb91c113588900e",
      "source_sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
      "source_bytes": 3
    }
  },
  {
    "name": "missing-snapshot",
    "expected": "reject",
    "evidence": {
      "url": "https://example.org",
      "sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
    }
  }
]