Metadata-Version: 2.4
Name: certiv-receipts
Version: 1.0.0
Summary: Author-declared computational checks with hash-pinned receipts.
Author: Certiv contributors
License-Expression: Apache-2.0
Keywords: reproducibility,receipts,verification,deterministic-builds
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: TRADEMARKS.md
Requires-Dist: PyYAML<7,>=6.0.3
Provides-Extra: node
Requires-Dist: cryptography<50,>=49; extra == "node"
Requires-Dist: fastapi<0.140,>=0.139; extra == "node"
Requires-Dist: python-multipart<0.1,>=0.0.32; extra == "node"
Requires-Dist: uvicorn<0.52,>=0.51; extra == "node"
Provides-Extra: dev
Requires-Dist: httpx<0.29,>=0.28.1; extra == "dev"
Requires-Dist: jsonschema<5,>=4.26; extra == "dev"
Requires-Dist: mypy<2.3,>=2.2; extra == "dev"
Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15.21; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20260518; extra == "dev"
Dynamic: license-file

# Certiv 1.0 GA

Certiv is a generally available, local-first toolkit for author-declared
computational checks. It hash-pins declared inputs, evaluates executable claims
twice from separate workspace copies, records exact expectations, and emits a
machine-readable `receipt.certiv`.

A passing author receipt is evidence of observed local repeatability under the
recorded conditions. It is not evidence that the scientific claim is true, that
the inputs are authentic or representative, that the method is valid, or that
the paper interprets the output correctly.

## Supported production boundary

Version 1.0 supports:

- the local CLI for manifest validation, pack, check, evidence, and local
  registry operations;
- strict manifest and receipt schemas plus the separate standard-library
  reference kernel;
- deterministic local T2 archives and exact-byte evidence packets;
- a durable local CAS, serialized hash-chain ledger, bounded self-hashed
  checkpoints, operator-signed head responses, and a read-only self-hosted API;
- an operator-managed verifier worker that fails closed unless its digest-pinned
  image and configured isolation floor are available;
- the static certiv.org documentation, worked example, machine descriptor,
  schemas, and downloadable kernel.

The public certiv.org deployment is intentionally read-only. Public uploads,
managed private custody, accounts, billing, subscriptions, and a managed
verification service are not part of the GA support boundary.

## Evidence boundary

A T1 author receipt can support this narrow statement:

> The author-declared check ran twice from separate copies of the recorded source
> tree; source and result digests, exit status, output hashes, and the pinned
> expectation agreed under Certiv's comparison rules at pack time.

It cannot support claims about truth, novelty, provenance, ethics, safety,
causality, legal priority, independent reproduction, or correct interpretation.
A verifier-node verdict is a separate signed ledger entry and still has the
same scientific limits.

## Security warning

`certiv pack`, `certiv check`, and the kernel's `--execute` mode run
author-declared shell commands. The local workflow is not a sandbox. Run only
code you trust, or use a disposable VM with no secrets, credentials, or valuable
files.

The verifier worker has no host-process fallback. It requires a preloaded,
digest-pinned image and an allowed isolation runtime. These controls materially
reduce risk, but operators accepting arbitrary third-party code still need a
deployment-specific security assessment.

## Installation from a reviewed release

Python 3.10 or later is required. Do not substitute `pip install certiv`: the
bare PyPI namespace currently resolves to a separate distribution. The
distribution name for this repository is `certiv-receipts`.

The canonical 1.0.0 wheel, full reviewed source, minimal runtime lock, SBOM,
build receipts, and SHA-256 manifest are published at
`https://certiv.org/releases/`. Verify the downloaded `SHA256SUMS` before
installing.

~~~sh
python3.10 -m venv .venv
.venv/bin/python -m pip install --isolated --require-hashes -r requirements/bootstrap.lock
.venv/bin/python -m pip install --isolated --require-hashes -r requirements/api.lock
.venv/bin/python -m pip install --isolated --no-index --no-deps --no-build-isolation .
.venv/bin/certiv --version
~~~

For CLI-only environments, install the runtime dependencies from an approved
hash-locked release process, then install the local wheel without dependency
resolution. Never substitute an unreviewed package index.

Typical author workflow:

~~~sh
certiv init ./paper
certiv pack ./paper
certiv check ./paper
python3 src/certiv/kernel/certiv-kernel.py ./paper
~~~

The final command validates structure and hashes without executing claims. Add
`--execute` only inside an appropriate isolation boundary.

## Evidence modes

| Mode | Supported behavior | Important limit |
|---|---|---|
| T0 | Pins artifact hashes and runs nothing | Integrity only |
| T1 | Runs an author command twice locally | Not hermetic or independent |
| T2 | T1 plus a deterministic local archive with `--seal` | Archive is unencrypted; no custody |
| T3 | Runs a trusted Lean 4 or Coq checker by registry ID | Only the encoded formal statement is checked |

Modes are not a quality ranking. `verified_local` means an author check passed
locally; `verified` is reserved for a signed verifier-node observation.

## Production operations

The public topology is a static export plus a read-only API. The API exposes
`/api/v1/health` for liveness and `/api/v1/ready` for configured readiness. A
deployment is not ready unless its ledger validates and its Ed25519 node key is
present with private permissions. If authenticated writes are explicitly
enabled, readiness also requires a strong bearer token and the configured
executor.

Backups are explicit and fail closed:

~~~sh
certiv node backup --registry REGISTRY --output registry-backup.tar.gz
certiv node restore --archive registry-backup.tar.gz --destination RESTORED \
  --expected-head EXTERNALLY_RETAINED_HEAD --key-file DECRYPTED/node_key.pem
python -m scripts.rehearse_recovery --registry REGISTRY --output-dir REHEARSAL \
  --expected-head EXTERNALLY_RETAINED_HEAD --key-file DECRYPTED/node_key.pem
~~~

The backup is mode `0600` but unencrypted, may contain private registry data,
and excludes both the node private key and disposable projections. See
`ops/PRODUCTION_RUNBOOK.md` for custody, release acceptance, monitoring,
restore, rollback, incident response, and verifier-host requirements.

## Repository map

- `src/certiv`: CLI, receipt, registry, node, and evidence implementation
- `src/certiv/kernel/certiv-kernel.py`: separate standard-library validator
- `schema`: strict manifest and receipt schemas
- `tests`: behavior, tamper, path, concurrency, API, readiness, sandbox, and
  kernel tests
- `web`: static Next.js public explanation and generated machine contracts
- `ops`: production deployment, readiness, rollback, and incident runbooks
- `docs`: design history and forward proposals; current support is controlled by
  this README, `HANDOFF.md`, and the public status page

## Release gates

~~~sh
python -m pytest -q
ruff check src tests scripts
mypy --strict src scripts
python -m scripts.secret_scan .
certiv verify-self
python -m scripts.build_release --output-dir release
(cd release && sha256sum --check --strict SHA256SUMS)
CERTIV_PYTHON="$(command -v python)" bash ops/deploy-static.sh --dry-run
~~~

The immutable-SHA CI policy in `.github/workflows/ci.yml` additionally audits
every Python lock, runs Bandit and ShellCheck, creates a CycloneDX SBOM,
smoke-installs only the staged wheel, exercises the API image as a non-root user
on a read-only filesystem, validates Caddy and Compose, and runs Chrome plus Axe
across every public route at desktop and mobile sizes.

`ops/deploy-static.sh` implements the deterministic static promotion path and
defaults to dry-run. Execute mode promotes an immutable directory, then
`scripts/probe_release.py` checks the live security headers, bounded GA
contract, guarded OpenAPI, v2 receipt and kernel, read-only API readiness, and
every file in the remote `SHA256SUMS`. Any failure restores the previously
validated release.

## Compatibility

The `certiv_manifest_v1` schema and frozen `certiv_receipt_v1` reader remain
compatible. New packs emit the strict `certiv_receipt_v2` contract; the
unversioned schema alias points to v2. CLI command names, status meanings, and
reference-validator behavior are stable for 1.x. Backward-incompatible changes
require a new major release or schema
identifier. Security fixes may tighten validation while preserving documented
valid inputs.

## License and identity

Code is licensed under Apache-2.0; see `LICENSE` and `NOTICE`. Certiv is the
owner-authorized brand used by this project. Apache-2.0 grants no trademark or
certification rights, and this release makes no representation that a trademark
application has been filed or allowed, that a registration exists, or that a
legal clearance opinion has been issued. See `TRADEMARKS.md` for the controlling
brand and package-namespace notice.
