Integration guide

Python API

from pathlib import Path
from govp import load_record, verify

record = load_record("record.govp.txt")
result = verify(record, asset_bytes=Path("artifact.bin").read_bytes())
if not result.ok:
    raise ValueError(result.checks)

The supported top-level API also exports parse_record, derive_govp_id, signing_input, sign_record, serialize_record, evaluate_status, VerifyResult and StatusResult. SemVer applies to these documented exports.

JavaScript API

import { verifyText } from '@govp/verifier';

const result = await verifyText(recordText, { assetBytes, fetchedUrl });
if (!result.ok) throw new Error(JSON.stringify(result.checks));

The JavaScript package works in Node.js 20+ and modern browsers. It independently implements GOVP-1 and GOVP-STATUS-1 against the published vectors and deliberately leaves network retrieval to the caller.

Issue without reconstructing the signature format

govp issue --asset artifact.bin \
  --canonical 'https://issuer.example/.well-known/govp/{govp-id}.govp' \
  --publisher "Example issuer" --asset-type document \
  --asset-id example/release --evidence https://issuer.example/release \
  --private-key issuer-private.pem --output record.govp

The issuer computes the digest, ID, raw public key and signature and refuses to overwrite existing output. Keep keys outside repositories and use an HSM/KMS for high-value production.

CLI JSON contract

govp verify RECORD --asset FILE --json

Treat the process exit code and each returned check as the interface. Preserve unknown fields, warnings and the original record for auditability.

Verification policy

Enterprise HTTPS

Network commands use Certifi by default and accept an explicit --ca-bundle PEM. They do not silently inherit SSL_CERT_FILE or REQUESTS_CA_BUNDLE. Approved enterprise transport can download a record for offline verification; canonical and live-status checks then remain not evaluated.

Composed evidence

The asset can be an upstream evidence object such as a SCITT receipt, COSE message, DSSE envelope, in-toto attestation or Sigstore bundle. Require both the GOVP asset check and the upstream system's native verification, then apply local policy. Keep the verdicts separate: govp_valid does not imply upstream_valid.

Composition model and system-specific boundaries

Untrusted input

• Bound record and asset sizes before buffering.
• Never execute or render evidence URLs as trusted markup.
• Use HTTPS with normal certificate validation for remote retrieval.
• Do not silently follow a redirect to a URL different from canonical.
• Do not discard unknown signed fields.

Compatibility

GOVP-1 is frozen. New semantics require a governed extension or a new protocol version; integrations must fail closed on an unknown version.