HX-Provenance on Google Cloud¶

HX-Provenance is a private Google Cloud VM appliance for issuing, verifying, and exporting post-quantum signed provenance receipts and evidence bundles. It runs inside your Google Cloud project and keeps the trust boundary under your control.

The appliance issues ML-DSA-65 signed receipts for registered artifacts, verifies receipts online, exports signed evidence bundles, and supports offline verification without a call back to HolonomiX.

This deployment procedure is for Google Cloud. AWS customers: follow the usage instructions for your selected version in the AWS Marketplace listing. The support section below accepts AWS, Google Cloud, Vertex AI, and private-deployment inquiries.

Deployment model¶

Component	Description
Product	HX-Provenance
Delivery model	Google Cloud Marketplace VM appliance
Runtime location	Customer Google Cloud project
Operating system	Ubuntu 24.04 LTS
Compute	Compute Engine VM
Recommended baseline	`n4-standard-4`
Ingress	HTTPS on port 443
Front end	nginx TLS termination
Application service	FastAPI bound to `127.0.0.1:8001`
Signing algorithm	ML-DSA-65
Signing key model	Per-instance key generated at first boot
Call-home dependency	None for receipt issuance or verification
Runtime data custody	Customer-controlled Google Cloud environment

Prerequisites¶

A Google Cloud project where you can deploy Marketplace VM products.
A VPC and subnet controlled by your organization.
Firewall rules that allow only authorized clients to reach HTTPS port 443.
Administrative access to the VM through your approved Google Cloud access path.
A secure place to store first-boot API keys and public-key fingerprints.
A decision on where your organization will store receipts and evidence bundles.

Deploy from Google Cloud Marketplace¶

Deploy from the Marketplace product page, selecting the project, region, zone, machine type, network, subnet, and disk configuration per your requirements. Then confirm and inspect the instance:

gcloud compute instances list
gcloud compute instances describe <INSTANCE_NAME> --zone=<ZONE>

Record the instance name, zone, machine type, boot/data disks, network and subnet, IP address, firewall rules, and deployment timestamp.

First boot¶

On first boot the appliance generates a per-instance ML-DSA-65 signing keypair, mints API keys, writes runtime configuration, prepares nginx, and starts the service.

Retrieve the first-boot API keys from the VM serial port output (Compute Engine → your VM → serial console) and store them in your secret manager.

Treat API keys as secrets

API keys are required for receipt issuance and evidence-bundle export. Copy them into your approved secret-management system and do not commit them to source control or send them through support channels.

Connect and confirm health¶

# Connect through IAP (if your deployment uses it)
gcloud compute ssh <INSTANCE_NAME> \
  --zone=<ZONE> \
  --tunnel-through-iap

# Confirm the services are active
sudo systemctl status hx-provenance.service
sudo systemctl status nginx

From an authorized client, check health and retrieve the appliance public key:

curl -fsS https://<HOST>/health
curl -fsS https://<HOST>/v1/provenance/public-key

A healthy deployment reports service status, receipt schema, and ML-DSA-65 as the active signing algorithm. Store the public key and fingerprint with your verification policy so verifiers can confirm receipts were signed by the expected appliance instance.

Issue, verify, and test tamper rejection¶

# Issue a signed receipt (save the response as receipt.json)
curl -fsS -X POST https://<HOST>/v1/provenance/exact \
  -H "Authorization: Bearer <ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d @sample-request.json

# Verify online — returns a deterministic verdict
curl -fsS -X POST https://<HOST>/v1/provenance/verify \
  -H "Content-Type: application/json" \
  -d @receipt.json

# Tamper test — a modified receipt should FAIL verification
cp receipt.json tampered-receipt.json
# change one signed field in tampered-receipt.json, then:
curl -fsS -X POST https://<HOST>/v1/provenance/verify \
  -H "Content-Type: application/json" \
  -d @tampered-receipt.json

Store receipts in your own system of record — HX-Provenance signs and returns receipts; your organization controls retention.

Export and verify an evidence bundle¶

# Export a portable evidence bundle (the appliance verifies the receipt first)
curl -fsS -X POST https://<HOST>/v1/provenance/evidence-bundle \
  -H "Authorization: Bearer <ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d @bundle-request.json \
  -o evidence-bundle.zip

# Verify offline — no network to HolonomiX or the appliance required
cd /opt/hx-provenance
python -m products.hx_provenance.tools.verify_receipt --receipt /path/to/receipt.json

A valid receipt exits successfully and reports a valid verdict; a tampered or mismatched receipt exits non-zero. A tampered receipt is rejected before bundle export.

Operational validation¶

Before accepting the deployment, confirm:

VM launches from the Marketplace image and hx-provenance.service is active.
/health returns a successful response.
HTTPS on port 443 is reachable only from authorized clients.
Receipt issuance, verification, and tamper rejection behave as expected.
The public-key endpoint returns the expected key material.
Evidence-bundle export and offline verification succeed.
Support-bundle contents are sanitized before transmission.

Architecture¶

HX-Provenance is deployed into the customer tenant and does not require a HolonomiX runtime to issue or verify receipts.

Runtime path¶

Client systems send authorized requests over HTTPS. The application service binds to loopback; nginx provides the customer-facing HTTPS boundary.

Customer application
  → HTTPS :443
  → nginx (TLS termination)
  → FastAPI on 127.0.0.1:8001
  → HX-Provenance signing / verification logic

Signing model¶

HX-Provenance signs receipts with ML-DSA-65. Each instance generates its own keypair at first boot; the secret key remains on the customer-controlled VM, and the public key is retrievable for verifier pinning. Receipts signed by one instance verify against that instance's public key — for multiple instances, pin public keys per issuer or establish an issuer policy.

Storage model¶

HX-Provenance signs and returns receipts; customers retain receipts and evidence bundles in their own systems of record. The appliance stores runtime configuration, service material, logs, and per-instance keys in the customer environment.

Path	Purpose
`/opt/hx-provenance`	Application payload
`/etc/hx-provenance/service.env`	Runtime configuration and API keys
`/var/lib/hx-provenance/keys`	Per-instance signing keys
`/var/log/hx-provenance`	Service logs

Network posture & upgrades¶

Restrict HTTPS :443 to authorized clients; administer the VM through approved Google Cloud access paths.
Monitor /health and alert on service failures; retain firewall changes in change management.
Pin the appliance public key before accepting receipts in production.
Optional integrations (Cloud Storage, Cloud Logging, Cloud Monitoring, CI/CD) stay inside your environment unless you configure otherwise.
Upgrades launch a newer immutable image and validate before shifting traffic; back up and restore per-instance keys if signer continuity is required.

API reference¶

Base URL is https://<HOST>. Receipt issuance and evidence-bundle export require an admin API key (Authorization: Bearer <ADMIN_API_KEY>); verification and public-key retrieval are usable without authentication so third parties can verify receipts.

Method	Endpoint	Auth	Purpose
`GET`	`/health`	none	Appliance health, schema, signing algorithm, backend status
`GET`	`/v1/provenance/public-key`	none	Public key + fingerprint for verification and signer pinning
`POST`	`/v1/provenance/exact`	admin key	Issue an ML-DSA-65 signed provenance receipt
`POST`	`/v1/provenance/verify`	none	Verify a signed receipt (deterministic verdict)
`POST`	`/v1/provenance/evidence-bundle`	admin key	Export a portable evidence bundle (verifies first)
`GET`	`/metrics`	internal	Operational metrics for monitoring systems

Verification behavior: a valid receipt returns a successful verdict; a modified receipt fails; an unsupported schema returns a structured failure; a signer mismatch fails when the verifier enforces pinning.

Offline verification¶

Use offline verification when evidence must survive network loss, cloud-provider dependency, system migration, litigation, audit review, long-term retention, or external handoff. Verification is fail-closed: any required check that cannot be satisfied causes rejection.

Offline verification checks receipt schema support, ML-DSA-65 signature validity, public-key fingerprint match, canonical receipt body, signed-field integrity, artifact commitment consistency, and (for bundles) manifest integrity.

Run the public verification demo¶

Download the synthetic verification demo (ZIP). The package includes a fictional record, its signed receipt and evidence bundle, matching standalone verifiers, and deliberate rejection cases. Read the package instructions or the public verification guide.

This package demonstrates verification mechanics. It is not production evidence or a production release attestation. Its key was created only for this example; never use the demo key or fingerprint to establish a production issuer.

Extract the ZIP and open a terminal in its provenance-demo directory. Use Python 3.11 or later. Install the supplied, pinned dependencies before disconnecting; verification then runs without a network connection, appliance, account, or HX-Provenance installation.

python3 -m venv .venv
.venv/bin/python -m pip install -r verifier/requirements.txt
.venv/bin/python verify_demo.py

On Windows, substitute .venv\Scripts\python.exe for .venv/bin/python; in PowerShell, enter each backslash-continued example below as a single line. The requirements file pins pqcrypto==0.4.0 and zstandard==0.25.0. The runner first checks the package's SHA256SUMS, then checks seven outcomes: the original receipt and bundle pass; the altered record, receipt, and bundle and both wrong-issuer cases are rejected.

To run the standalone tools directly, use the following demo-only commands from the same directory:

.venv/bin/python verifier/verify_receipt.py \
  --receipt receipt.json \
  --public-key issuer-public.pub \
  --expected-fingerprint d9bf869b298636bbe7ad0226b4a4063da60b2a8ca5863a9dc9ff31b1a9f7367e \
  --artifact record.json

.venv/bin/python verifier/verify_bundle.py \
  --bundle evidence-bundle.jsondir --format json-dir \
  --public-key issuer-public.pub \
  --expected-fingerprint d9bf869b298636bbe7ad0226b4a4063da60b2a8ca5863a9dc9ff31b1a9f7367e \
  --artifact record.json

The expected SHA-256 fingerprint above is also published in the demo public-key instructions. Compare it with the key in the download. A key and fingerprint supplied together inside an untrusted package establish only internal consistency; they do not independently establish the issuer you intended to trust.

Verify evidence from a deployed appliance¶

Obtain the release-matched standalone verifier, dependency file, and instructions through your agreed release delivery channel. If they are missing, contact product support with the deployed release identifier. Do not assume the public demo's verifier is compatible with a different product or evidence version.

Obtain the complete exported receipt or evidence bundle and any original artifact or linked material required by that release's procedure.
Obtain the expected issuer's raw public key and SHA-256 fingerprint through an independently trusted channel controlled by the customer or authorized issuer. Confirm the intended deployment and key version. Do not take the expected identity solely from the package being checked.
Install the matching verifier's dependencies before moving to the offline review host. Follow its supplied commands and provide the expected key and fingerprint explicitly. Use the production issuer's values, not the demonstration identity above.
Review the complete verdict and retain the inputs, release identifier, and verification output. A failed or unsupported check must not be treated as verified. The standalone tools' --integrity-only mode does not authenticate an expected issuer and is not a substitute for issuer-pinned verification.

An evidence bundle can include receipt.json, artifact and verification manifests, the signer public key, signature metadata, a MANIFEST.sha256, and bundle signature material. Use the matching bundle verifier to check the manifest, included file commitments, manifest signature, and receipts, then confirm that the result satisfies your acceptance policy.

Auditor handoff

Provide the evidence bundle, the independently established appliance public key and fingerprint, verification instructions, the release identifier, the export timestamp, and a contact for interpretation. Never send API keys, signing keys, private keys, or raw regulated data through ordinary support or email channels.

Security & data handling¶

The primary trust boundary is your Google Cloud project. HX-Provenance runs on a customer-controlled Compute Engine VM and does not require HolonomiX to receive customer data, receipts, or signing keys during normal operation.

Key custody

Each instance generates its own ML-DSA-65 signing keypair at first boot; the secret key stays on the appliance under customer-controlled permissions.
Customer-held material: per-instance signing key, API keys, runtime configuration, retained receipts, evidence bundles, and public-key pinning policy.
HolonomiX does not receive the appliance signing key during normal operation.
Retain prior public keys for historical verification — receipts signed by a prior key remain verifiable with that key.

Network & authentication

The application service binds to loopback; nginx terminates TLS on :443 and forwards to the local FastAPI service.
Restrict :443 to authorized clients; use approved administrative access paths; monitor /health and hx-provenance.service.
Receipt issuance and evidence-bundle export require an admin API key; verification and public-key retrieval are available without authentication by design.

Support-data handling

Sanitize support bundles before transmission. Exclude signing keys, API keys, private keys, secrets, customer corpus or query data, regulated records, confidential evidence artifacts, and unsanitized receipts. Report security issues to [email protected].

Support¶

HolonomiX supports HX-Provenance deployment, configuration, operation, and verification workflows. This support destination is shared by the AWS and Google Cloud listings. Select your deployment route when preparing a product support inquiry.

Include your organization, HX-Provenance release version, deployment route, Marketplace order reference when applicable, an issue summary with timestamps, reproduction steps, and relevant non-secret health or service output. Add the environment identifiers for your route:

Deployment route	Environment context
AWS Marketplace	AWS account reference, region, EC2 instance ID, AMI ID, and selected listing version
Google Cloud Marketplace	Google Cloud project ID, region/zone, VM name, image, and selected listing version
HX-Provenance for Vertex AI	Google Cloud context above, adapter release, and affected Vertex integration
Private Appliance or pilot	Supplied release identifier, deployment environment, and the scope agreed for your organization

Use the service and diagnostic commands supplied with your deployed release. For the Google Cloud appliance documented on this page:

# Service status + recent logs
sudo systemctl status hx-provenance.service
sudo systemctl status nginx
sudo journalctl -u hx-provenance.service --since "30 minutes ago"
curl -fsS https://<HOST>/health

General support: [email protected]
Security-sensitive issues: [email protected]

Send support materials only through a secure channel agreed with HolonomiX, and never include keys, secrets, or regulated data.

Release notes — g6g7-prod-3¶

The current enterprise-validated release line for the private appliance surface.

Single-tenant VM appliance on Ubuntu 24.04 LTS, CPU-only runtime, FastAPI behind nginx.
ML-DSA-65 receipt signing; per-instance signing key generated at first boot.
Online and offline receipt verification; evidence-bundle export.
Support-bundle redaction guidance; immutable-image upgrade and rollback model.

Upgrades launch a newer image version, validate it, and shift traffic per your operational process. If signer continuity is required, back up and restore per-instance signing keys and runtime configuration per your key-custody policy, and retain retired public keys for historical receipt verification.