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.

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.

# Copy the receipt + public-key material to an independent host, then:
python -m products.hx_provenance.tools.verify_receipt --receipt receipt.json
# provide the expected public key / fingerprint to enforce signer pinning

An evidence bundle is designed for independent review and can include receipt.json, artifact and verification manifests, the signer public key, signature metadata, a MANIFEST.sha256, and bundle signature material. Extract it, verify manifest hashes, verify the manifest signature against the signer public key, verify the receipt, then confirm the result matches your acceptance policy.

Auditor handoff

Provide the evidence bundle, the appliance public key or 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 on Google Cloud.

# 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

Before contacting support, collect: organization name, Google Cloud project ID, region/zone, VM name, HX-Provenance release version, Marketplace order reference, an issue summary with timestamps, relevant non-secret logs, /health output, service status, and reproduction steps.

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.