# PactVerity Evidence Gateway 1.1.0

Released software: a buyer-operated, zero-dependency Node 24+ HTTPS collector and offline invoice-credit evaluator. Available for authorised service measurements and reproducible invoice-credit claims. No wallet, token purchase, custody, payment, automatic refund, hosted monitoring account or background daemon. Independent security review is not completed; this release is not an uptime guarantee or a certification of evidence truth.

## Start

1. Download `collector.mjs` and `evaluator.mjs` into the same local folder. Inspect the source and compare the published SHA-256 checksums. Use Node.js 24 or later from nodejs.org.
2. Open https://pactverity.com/evidence-gateway and create a measurement contract for an endpoint you are authorised to probe. No login or query-string URLs. Choose the agreed invoice currency, invoice amount, per-failed-window credit and cap. These are explicit custom terms, not a translation of a vendor's monthly SLA. Agree them with the provider first; record the contract fingerprint outside the evidence file.
3. Download `contract.json`. Set its UTC start in the future, allowing time to start the command (2 seconds to 24 hours). Interval 5–3600 seconds; 1–2016 windows; duration at most seven days. Each window contains ONE scheduled GET, not continuous monitoring. The latency is DNS + connection + TLS + response-headers time, not full-body completion or AI output quality.
4. Optional signing: `node collector.mjs keygen signing-key.pem public-key.txt`. Keep the PEM private and never upload it. Files are created exclusively with mode 0600; Windows users must also restrict access using Windows permissions. Share the public-key hex and agreed contract fingerprint through a separately trusted channel. There is no hosted key recovery.
5. Run: `node collector.mjs run --contract contract.json --out evidence.json --authorised --key signing-key.pem`. Omit `--key` for unsigned evidence. Keep the computer running. Output files cannot already exist. Ctrl+C cancels active network work and stops future probes. Completed observations are retained; an interrupted request remains an unknown window, never a provider failure. There is no resume command; a new contract/run is required.
6. Import `evidence.json` into the website workbench. Processing is in your browser; evidence and keys are not uploaded or persisted by this feature. Optional public-key and contract-fingerprint fields pin your independent trust anchors. Do not upload private keys or confidential logs.
7. Offline replay: `node collector.mjs verify --file evidence.json --trusted-key public-key.txt --contract-hash YOUR_AGREED_64_HEX_FINGERPRINT --report report.csv`. Replace the fingerprint with the value agreed for your real contract. This command makes no network calls. Omit the optional trust arguments only if you intend to check consistency, not agreed identity/terms.

## Exact rules

Each UTC half-open window has one scheduled probe at its beginning. Starts over one second late become UNKNOWN; missed windows are UNKNOWN. Maintenance exclusions are explicit zero-based indexes agreed before collection. A signature binds the entire contract, run mode, collector version, timestamps and observations. The collector rejects contracts whose start has already passed and compares elapsed wall-clock and monotonic time between successive checks while waiting and after each request. An abrupt difference over one second stops collection; gradual clock synchronisation is allowed. The last checkpoint remains usable as incomplete evidence. A dishonest collector can still lie, omit observations or backdate a contract. A signature cannot prevent that.

PASS: HTTP 200–299 with header latency at or below the limit. FAIL: other observed non-2xx codes except the exceptions below, or an observed 2xx above the latency limit. UNKNOWN: missing sample, late start, DNS/TLS/network error, timeout, redirects, HTTP 401/403, or HTTP 429. These conservative rules do not attribute local network failures, access failures or quota exhaustion to a provider. A 404 does count as a failure under this contract, so agree and check the exact endpoint. EXCLUDED: predeclared maintenance; no request is made.

Header latency is rounded to the nearest millisecond. Timeout is bounded by the interval and 10 seconds. One sample cannot establish full-window uptime, continuous availability, data freshness, response-body integrity or semantic AI correctness. No such claims appear in this report.

Credit uses integer minor units (USD/GBP/EUR cents/pence):

`floor(invoiceCents * min(capBps, failCount * creditPerFailureBps) / 10000)`

100 basis points = 1%. The cap cannot exceed 100% of the invoice. Round down once after aggregating. Zero invoice or zero credit terms are valid for non-financial testing. UNKNOWN windows do not generate credit and make coverage incomplete; they are never counted as passes. A complete report means all scheduled observations are classified, not that the whole service was observed. All outputs remain provisional claims requiring counterparty acceptance, not issued credit notes, refund entitlements, tax invoices or payments. Do not count the same run twice when claiming credits. Agreement ID, contract hash and evidence digest identify it.

## Safety and privacy

Only explicit authorised public HTTPS GETs on port 443. No redirects, cookies, authentication headers, query strings, response bodies or full error strings are captured. The endpoint path may itself reveal private information: do not use secret-bearing paths. IPv4 DNS results are checked, and a validated address is pinned per request while preserving TLS hostname verification and SNI. Private, reserved, loopback, metadata and multicast IPv4 addresses are rejected; IPv6-only endpoints are unsupported. Mixed private/public DNS answers fail closed. No general-purpose public fetch proxy is deployed.

Local firewall, security software and upstream services can still limit probes. This is not a hardened sandbox. Never run against endpoints without permission. Keep samples away from personal data. Cryptographic hashes do not anonymise sensitive data. The browser demo targets only PactVerity's own health endpoint and is labelled first-party; synthetic examples are explicitly labelled. Neither is independent customer adoption.

## Verification semantics

The sorted-key canonical JSON format is specified by the shipped evaluator; it is not advertised as complete RFC 8785. SHA-256 input is UTF-8 `pactverity.gateway.v1\n` followed by canonical payload JSON. Ed25519 signs UTF-8 `pactverity.gateway.v1\n` followed by the lowercase digest. The receipt contains the public key only. Unsupported versions, extra fields, duplicate samples, malformed timestamps, invalid signatures and digest mismatches are rejected. Summary totals are recomputed, never trusted from a file.

A valid self-asserted key proves only that its matching private key signed the bytes. Pin a known public key and agreed contract hash separately to verify those expectations. Even a trusted signature does not establish independent measurement or truthful inputs. The rule set, trusted observation source and contractual acceptance are separate requirements.

Security reports: contact@pactverity.com. No promised bounty or response time.

## Release hardening

Version 1.1.0 adds cancellable DNS/HTTPS waits, monotonic-clock checks during scheduling, immutable collection terms and flushed checkpoint files. Each checkpoint is written exclusively to a unique `.pending` file in the output directory, flushed and renamed over the reserved output. If replacement fails, the last committed output is preserved and the newest pending file is retained with its path reported. If there is no committed checkpoint, the empty reserved output is removed. A hard kill can leave pending files; verify them before recovery because a write may have been interrupted. No guarantee is made against filesystem corruption, device failure or an administrator changing local files.

The website's `/api/v1/health` includes a fixed synthetic Evidence Gateway calculation and digest-verification self-test. It is a current known-answer check, not customer activity or historical uptime. The release tests include rendered-interface race and trust-edit tests, cancellation, missed windows, checkpoint failure recovery and a maximum seven-day schedule with gradual clock slew under an accelerated test clock. Accelerated testing is not seven days of observed real-world operation. Multi-day unattended operation has not completed a real-time soak test; use short supervised collection runs until that evidence is available.

## Operating and recovering

- Store output in a private writable directory on a local disk with adequate free space. Keep private keys separate from evidence files and never attach keys to support requests.
- Agree the endpoint and credit terms before running; do a short authorised non-financial run first. Keep the host awake, clock synchronised and network available. One collector process owns each output file.
- After collection, verify using the independently agreed public key and contract fingerprint. Review unknown windows before sharing a claim. Export JSON and CSV; print the browser report to PDF if required.
- On a stopped or failed run, replay the last output with `verify`. A retained pending file can also be passed to `verify`; reject it if malformed, incomplete or inconsistent. Keep the old file before manually recovering a newer valid checkpoint. Never merge runs or count credits twice.
- Report reproducible issues to contact@pactverity.com with the software version and a sanitised description. Do not email private keys or confidential evidence. No support-response SLA is promised.
- Compatibility: existing `pactverity.gateway.v1` evidence remains supported. Invalid first-party claims, malformed signatures, tampered digests and unsafe input continue to fail closed.

## Reproducing release checks from source

Install the isolated UI test dependencies from `tests/gateway-ui` using its pinned lockfile, without changing the website's runtime dependencies. Build the project, then run `node --test tests/*.test.mjs` from the project root. The UI tests render the real component in jsdom with delayed imports and cryptographic completion. The collector tests use injected clocks/transports; live acceptance checks are separate, explicitly authorised first-party requests.

The browser live check runs only at https://pactverity.com. Local previews and alternate hostnames cannot label their own health endpoint as a production measurement; they retain import and synthetic-example functionality.

Version 1.0.1 prevents stale asynchronous browser results after a newer import or a trust-anchor edit. Imported mode labels are explicitly self-declared, never treated as proof of live collection. Browser-first-party files are restricted to the zero-value PactVerity health check. Text fields reject terminal and bidirectional formatting controls. Input reads are size-bounded and reject malformed UTF-8, links and directories. Signing algorithms are checked before collection starts; duplicate and unknown command-line options are rejected. Verification snapshots input before asynchronous cryptographic checks.

Inputs are limited to 1.5 MB, safe integer JSON numbers (no negative zero), no duplicate decoded property names, and 32 nesting levels. Strings are rendered as text, not HTML. CSV text cells are escaped against spreadsheet formulas. HTTPS headers are limited to 16 KiB and the total DNS/connection/TLS/headers operation is deadline-bounded; no response body is stored. On POSIX systems, group/other-readable private key files are refused; Windows users must restrict access using file permissions themselves. A checkpoint's signed contract includes the entire schedule and expected window count. The verifier derives missing windows and completeness rather than trusting a supplied run-status label.
