Developers

Build with OpenAIIS.

Everything an implementer needs: the reference implementation, its HTTP APIs, the exact wire identifiers and the conformance rules. Or start right here, by checking a real signed claim in your browser.

Signed claim software_release

profile: openaiis-universal-registry-v1
record_type: software_release
subject_id: release:companyx/billing-app/2.4.0
issuer_id: agent:companyx/release-bot
issuer_key_id: sha256:6d61b230e405ba09feb6a6ed1e4d887308b329983f6b8a8ce43f955d2407d9b3
content_sha256: sha256:c40ebf0c1a6d67831fd947f6c5d759c063da4ddbefb6c3fd3628792952e4e6e4
payload_schema: schema:company-release-v1
payload_sha256: sha256:0df32e49d828a758480446073950b4174413cced00b3797facece9a97e6a9ae9
authority_refs: sha256:d0ba84c1c98095f586c3d816e0980305a3f9abec0148880e4fc484f12a2123d5
evidence_refs: sha256:0e83fb9ed226a231a91f89584cc8a42366510c353010af433b1ab9287d43ff37
consent_refs: []
related_record_refs: []
claimed_at: 1793102400
signature: dzCZCGuWRUwaVbLbpSF/Zmu1ggNzQBxMxlW/0ZW+jei8WJU+hmrUuInLn0S3aNKlNGbrOHiCDjSWmpvbvt06Dg==

An example record, signed by the reference implementation with a throwaway key. The check runs entirely in your browser.

Quickstart

The source repository for the Python reference implementation is not public yet. The documents, API contracts and identifiers on this page are enough to start an independent, compatible implementation.

With a copy of the source, it needs Python 3.12 or 3.13. Install it from the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
python -m pip check

Start the read-only inclusion verifier on your own machine, then query it from another terminal:

openaiis-verify-http --host 127.0.0.1 --port 8081

curl http://127.0.0.1:8081/health
curl http://127.0.0.1:8081/v1/capabilities

The package installs three commands: openaiis-verify-http (the verifier above), openaiis-registry-http (the owner-operated registry) and openaiis-demo. Runtime dependencies are pinned: cryptography for Ed25519 and cbor2 for CBOR.

The registry service binds to 127.0.0.1 and needs a durable database, a checkpoint database, a registry origin, issuer policy, a checkpoint signing key and an operator token. Keep its configuration files owner-only (0600) and never publish signing keys or operator credentials.

HTTP API

Both services describe themselves in OpenAPI 3.1. They are local reference services; an endpoint existing does not mean a public service is running.

Registry registry-openapi.json

Method	Path	What it does
`GET`	`/health`	Process liveness
`GET`	`/v1/capabilities`	Complete local registry capability manifest
`POST`	`/v1/verify/inclusion`	Verify signed inclusion against caller pinned keys
`POST`	`/v1/claims`	Submit externally signed typed claim against operator provisioned pins
`POST`	`/v1/checkpoints`	Sign and durably store Merkle checkpoint with operator authorization
`GET`	`/v1/claims/{digest}`	Retrieve a persisted canonical signed claim, but not typed payload
`GET`	`/v1/claims/{digest}/receipt`	Proof of inclusion against a stored signed checkpoint
`GET`	`/v1/checkpoints/latest`	Latest signed checkpoint; does not assert Bitcoin confirmation
`GET`	`/v1/checkpoints/{size}`	Retrieve a particular immutable checkpoint
`GET`	`/v1/proofs/consistency`	Consistency path between two published checkpoint tree sizes
`GET`	`/v1/registry/status`	Durable append-only registry current status
`GET`	`/v1/claim-types`	List all supported typed claim profiles
`POST`	`/v1/verify/record`	Verify canonical record signature against caller-provided pinned key
`POST`	`/v1/verify/typed`	Verify typed payload and issuer signature against caller-provided pinned key

POST /v1/claims takes exactly record_base64, payload_base64 and issuer_id; the claim must already be signed by its issuer. POST /v1/checkpoints requires the operator's bearer token. Public read and verify routes never get signing authority.

Read-only verifier verifier-openapi.json

Method	Path
`GET`	`/health`
`GET`	`/v1/capabilities`
`POST`	`/v1/verify/inclusion`

A verification response reports cryptographic validity against the keys you supply. CRYPTOGRAPHIC_INCLUSION_VERIFIED is an inclusion result, not an operational ALLOW, and a checkpoint marked SIGNED is not a Bitcoin confirmation.

Wire identifiers

Exact strings from Protocol V5.0 Appendix A. \0 means one zero byte. A verifier must reject a record presented under the wrong profile or domain.

Object	Identifier
Signed universal record	`openaiis-universal-registry-v1`
Record signing domain (ASCII + NUL)	`OPENAIIS/UNIVERSAL-REGISTRATION/v1\0`
Inclusion receipt	`openaiis-universal-inclusion-v1`
Registry log kind	`registry_record`
Core 17-type catalogue	`openaiis-universal-type-lock-v1`
Extension type catalogue	`openaiis-universal-type-extensions-v2`
Identity consent-intent domain (ASCII + NUL)	`OPENAIIS/IDENTITY-CONSENT/v1\0`
Private artifact registration profile	`openaiis-artifact_registration-private-v1`
Private artifact commitment domain (ASCII + NUL)	`OPENAIIS/PRIVATE-ARTIFACT-COMMITMENT/v1\0`
Authenticated lifecycle index	`openaiis-lifecycle-index-v1`
Lifecycle-index proof	`openaiis-lifecycle-index-proof-v1`
Universal Bitcoin proof bundle	`openaiis-universal-bitcoin-bundle-v1`

Building a compatible verifier

Start with Protocol V5.0 §17, which lists the eleven requirements a conforming verifier must apply, and Appendix B, the 23 invariants it must preserve. Given the same evidence, trust roots, profiles and policy, independent verifiers must reach the same result and reasons.

The documents are licensed under CC BY 4.0, so you may reuse and adapt the specification with attribution. Independent compatible implementations are welcome. See Licensing and name for what the licences do and do not cover.