fors33-verifier 0.5.0

Verify attested data segments. Standalone SHA-256 verification for data provenance.

fors33-verifier

Standalone verification for attested data segments and general-purpose file integrity baselines. For machine-readable context (LLMs, crawlers), see LLM_CONTEXT.md. Confirm that a data segment or directory tree matches published hashes.

Warning: FORS33 Verifier provides cryptographic integrity checks only. It does not independently guarantee legal or regulatory compliance. See LEGAL_DISCLAIMER.md.

Install

pip install fors33-verifier

Releases are published to PyPI manually using python -m build and twine upload; the GitHub Actions workflow publish-fors33-verifier is responsible only for building and pushing Docker images. That workflow runs only when you trigger workflow_dispatch with explicit version (no leading v, e.g. 0.5.0) and push_latest—it does not run automatically on git tags.

Usage

Remote (presigned URL, full file):

fors33-verifier --url "https://..." --expected-hash <sha256_hex>

Remote (HTTP Range, segment only):

fors33-verifier --url "https://..." --start 0 --end 1048576 --expected-hash <sha256_hex>

Local full file:

fors33-verifier --file /path/to/segment.csv --expected-hash <sha256_hex>

Local segment (direct byte range):

fors33-verifier --file /path/to/data.csv --start 0 --end 4096 --expected-hash <sha256_hex>

Local segment (using attestation record):

fors33-verifier --file /path/to/data.csv --record /path/to/attestation_record.json

The attestation record JSON must contain byte_start, byte_end, and hash. Uses memory-efficient chunked reading so large files do not cause OOM.

Directory verification (manifest mode):

fors33-verifier --mode manifest --file ./baseline.sha256 --root ./root --format json

Use --root (or deprecated --target-dir) for the directory to verify. MD5/SHA-1 in manifests are rejected by default; use --force-insecure for legacy manifests. Verify a directory against a checksum manifest (GNU/BSD-style text or JSON). Emits a structured drift report with modified, created, deleted, mutated_during_verification, and skipped.

Sidecar verification:

fors33-verifier --mode sidecars --file ./root --format json

Walk the tree and verify .f33, .sha256, .sha512, and .md5 sidecars in place.

Optional TSA verification for JSON .f33 sidecars:

fors33-verifier --mode manifest --verify-tsa --file ./manifest.json --root ./root --format json

With --verify-tsa, the verifier accepts predicate.tsa.rfc3161_token_b64 (RFC 3161 TimeStampResp DER, Base64) and/or the legacy Ed25519 predicate.tsa block. RFC tokens are checked offline: PKI status granted, CMS signature on the timestamp token, and message imprint (hash OID from the token) over the same canonical JSON payload used for the main Ed25519 signature. MD5/SHA-1 imprint algorithms are rejected.

Manifest hashing workers (thread pool only):

fors33-verifier --mode manifest --workers 8 --file ./manifest.json --root ./root

FORS33_WORKERS overrides --workers after arguments are parsed. If unset, <= 0, or invalid, the default is _default_worker_count() (or 4 when FORS33_EXTENSION_MODE=1), capped at 64 when explicitly set.

Large-file hashing (hash_core): optional mmap window controlled by FORS33_MMAP_MIN_MB and FORS33_MMAP_MAX_MB (defaults 500 and 4000). Optional global read throttle: set_global_read_bytes_per_second (for hosted/extension use).

Output

System-log format with timestamp, target, SHA-256, and status.

Exit codes:

• 0: verified / no drift
• 1: drift or missing seal ([ ERR_MISSING_SEAL ])
• 2: invocation or parameter misuse
• 3: severe trust failures (e.g. bad signature, manifest compromise, invalid TSA)

Manifest/sidecars modes support --format json with --warn-only to report drift without failing.

GitHub Action (CI/CD)

Use FORS33 Data Provenance Check in your workflow. The step fails (exit 1) on hash mismatch, blocking the pipeline.

- name: Verify data integrity
  uses: fors33-official/fors33-verifier@v1  # or your tag
  with:
    file: ./dist/artifact.bin
    expected-hash: 'abc123...'

For URL verification (presigned URLs only; no file uploads):

- uses: fors33-official/fors33-verifier@v1
  with:
    url: 'https://example.com/presigned.csv'
    expected-hash: 'abc123...'

The FORS33 Data Provenance Kit runs on AWS S3, Snowflake, and local infrastructure. Procure licensing at fors33.com or GitHub Marketplace.

Docker

docker run --rm ghcr.io/fors33/fors33-verifier:latest --url "https://..." --expected-hash <sha256>
# or
docker run --rm docker.io/fors33/fors33-verifier:latest --file /data/file.csv --expected-hash <sha256>

URL-only API

For a hosted API that verifies presigned URLs only (no file uploads), run the image with the serve command. In-browser verification must use the Web Crypto API client-side; the file never leaves the user's machine.

Requirements

Python 3.9–3.12. cryptography and asn1crypto (required). Optional blake3 for faster hashing. Platforms: Linux, macOS, Windows.

License

MIT License. See LICENSE file.