Kaiba contracts

Shared contracts from device provisioning to publication of a graphical device configuration. This repository defines the records, responsibilities, and guarantees that connect Kaiba subsystems. It does not implement a provisioning lane, controller, signer, device agent, or production admission service.

Status: proposed contract set 0.4.0-draft.1, plus an isolated 0.5.0-draft.1 WorkloadBinding draft and transient DNSWorkloadAuthorization RPC response, and a 0.6.0-draft.1 bounded renewal delegation. Additive families require explicit producer and consumer adoption. The original family is used by the isolated enrollment rehearsal. Passing the included tests means the documents' sample records satisfy the checked rules; it does not qualify hardware, authenticate a device, or authorize a release.

Read in this order

The process guide website provides a visual walkthrough of the handoffs, ownership, contract coverage and current development slice. It is published by GitHub Pages once the repository's Pages source is enabled. See website maintenance and setup.

The visual device story introduces the journey in plain language, with an animated device and before/after states. The technical walkthrough adds contract fixtures, exact state transitions and acceptance rules. Both support development restrictions, conflicting assignments and a lost confirmation.

1. System specification: pipeline, authorities, and invariants.
2. Contract catalog: every handoff, including deferred contracts.
3. Common rules: identity, digests, versioning, and errors.
4. Initial detailed contracts:
   • ProvisioningRecord
   • DeviceBinding
   • Publication, including PublishRequest
   • Existing-device pilot enrollment
   • Explicit pilot renewal authorization
   • Pilot renewal installation and cutover
   • Proposed expired pilot recovery
   • Recovery issuance, installation and cutover
   • Proposed SPIFFE WorkloadBinding
   • Per-request DNS workload authorization
5. Conformance and examples.

The original wire family remains in schemas/0.1.0-draft.1. The new pilot family lives in schemas/0.2.0-draft.1. The additive renewal authorization lives in schemas/0.3.0-draft.1. Proposed recovery approval, key proof and cutover live in schemas/0.4.0-draft.1; runtime adoption remains pending. The isolated, unadopted WorkloadBinding and DNSWorkloadAuthorization drafts live in schemas/0.5.0-draft.1. This additive family leaves the existing contract-set VERSION, enrollment and pilot wire families unchanged. All use exact contract/version dispatch; pilot records do not upgrade legacy readiness or confer full qualification. They use JSON Schema Draft 2020-12 and resolve entirely from local files. Examples use fictitious identifiers and evidence references; they contain no credentials or live grants.

Validate locally

Python 3.12 or newer:

python -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python tools/validate.py examples/valid/publish-request.json

On Windows, use .venv\Scripts\python.exe. Validation includes schema checks, record-local semantic checks, linked fixture digests, and negative cases. Runtime authorization obligations are listed separately and require subsystem tests.

Ownership and adoption

The system contract belongs here. Each producer and affected consumer reviews changes; implementation, deployment, key custody, and internal state remain in the owning project. See contributing and the adoption checklist.

The implementation owners are kaiba-provisioning for the ProvisioningRecord producer and kaiba-fleet for enrollment, identity inventory and the DeviceBinding producer. Fleet implements the isolated rehearsal; pilot runtime support and fully qualified admission remain separate work. Naming owners does not establish contract adoption or production conformance.

The provisioning baseline is pinned in sources. Its current development posture cannot enter enrollment_ready. The proposed production examples here do not change that status. The proposed pilot family needs explicit producer/consumer adoption and its own authenticated policy before live use.