Developer documentation
Every governed package version is signed when it is created. Ed25519 signatures can be checked by the installer, offline, against HoloSignal's published public keys.
New versions are signed with an Ed25519 key held only by HoloSignal. The signature covers a domain-separated payload that includes the package id and version, so it cannot be replayed onto another package or version. Anyone with the public key set can verify it.
Versions created before Ed25519 signing were signed with a shared secret. HoloSignal still verifies them through the verify endpoint, but an installer cannot check them independently. They report installer_verifiable: false and jwks_url: null.
The key set is a standard JWKS at https://holosignal.xyz/.well-known/holosignal-marketplace-keys.json. It is public, needs no credential and may be cached for five minutes. When the signing key rotates, the new key is added and earlier keys stay listed, so older versions keep verifying. Match keys by kid.
{
"keys": [
{ "kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "hs-mkt-2026-09", "alg": "EdDSA", "use": "sig" }
]
}The verify endpoint checks a version server-side and returns everything needed to repeat the check: the manifest, the algorithm, the key id, the exact signed payload and the key set URL. It requires workspace:read. reason is ok, content_hash_mismatch, unknown_key, bad_signature, verifier_unavailable or unsupported_algorithm.
GET /api/v1/marketplace/pkg_…/verify?version=1.2.0
Authorization: Bearer oxy_live_…{
"package_id": "pkg_…", "version_id": "mkt_…", "version": "1.2.0",
"valid": true, "reason": "ok",
"alg": "ed25519", "key_id": "hs-mkt-2026-09", "installer_verifiable": true,
"signed_payload": "holosignal-marketplace-v2\npkg_…\n1.2.0\n9f2c…",
"jwks_url": "https://holosignal.xyz/.well-known/holosignal-marketplace-keys.json",
"content_hash": "9f2c…", "signature": "base64url…",
"manifest": { "context_contract": "1.0", "entrypoint": "recipe.json", … },
"status": "published", "verified_at": "2026-09-23T…"
}To verify without trusting the API at install time, repeat these steps on the manifest you are about to install.
01
Serialise it as JSON with object keys sorted (by UTF-16 code unit), no whitespace, and members whose value is undefined dropped. Numbers and strings use JSON.stringify formatting.
02
content_hash is the lowercase hex SHA-256 of those UTF-8 bytes. It must equal the record's content_hash.
03
holosignal-marketplace-v2, the package id, the version and the content hash, joined by single \n characters with no trailing newline. Build it yourself rather than trusting signed_payload.
04
Pick the JWK in the published key set whose kid equals the record's key_id. An unknown kid fails.
05
Verify the base64url signature with Ed25519 (RFC 8032) over the payload's UTF-8 bytes.
Both SDKs implement the steps above. They return valid and a reason: ok, not_installer_verifiable (a legacy HMAC version), unknown_key, content_hash_mismatch or bad_signature. The Python helper needs the optional cryptography dependency.
import { HoloSignal, verifyMarketplaceSignature } from "@oxysignal/sdk";
const client = new HoloSignal({ apiKey: process.env.HOLOSIGNAL_API_KEY! });
const record = await client.verifyMarketplacePackage("pkg_…", "1.2.0");
// Fetch the keys from the well-known URL you trust, not from the record's jwks_url.
const jwks = await (await fetch("https://holosignal.xyz/.well-known/holosignal-marketplace-keys.json")).json();
const check = await verifyMarketplaceSignature(record, jwks);
if (!check.valid) throw new Error(`Refusing to install: ${check.reason}`);# pip install "oxysignal[marketplace]" (adds the cryptography dependency)
import httpx
from oxysignal import HoloSignal, MARKETPLACE_JWKS_URL, verify_marketplace_signature
client = HoloSignal(api_key="oxy_live_…")
record = client.verify_marketplace_package("pkg_…", "1.2.0")
jwks = httpx.get(MARKETPLACE_JWKS_URL).json()
check = verify_marketplace_signature(record, jwks)
if not check.valid:
raise RuntimeError(f"Refusing to install: {check.reason}")