Build on the diagnos vault

Quick start#

1. Get a token. A workspace admin issues a service-account token in the diagnos web app:

export DIAGNOS_API_TOKEN="apikey-…"

2. Enroll. The first run prints a link and a 6-digit code; an admin approves it in the web app and picks which security groups this process may read.

from diagnos import Diagnos

with Diagnos() as vault:  # enrolls on entry: prints the approval link + code
    print(vault.workspace_id)
    print(vault.security_groups)  # the groups the admin granted

diagnos login          # the same enrollment, from the terminal
diagnos status         # token, OpenBao and SDK version

3. Use it. Patients, exams and files hang off the same object — vault.patients, vault.exams, vault.drives. The quickstart goes from here to your first encrypted patient and file.

Private keys never leave the process and nothing is written to disk, so the next process needs a new approval — that is the design, not a limitation. Authentication shows the whole enrollment, and Sessions how servers restart without a human.

What you get for free#

• 🔐 End-to-end by default — records and files are encrypted in your process; the vault sees ciphertext, signed requests and presigned URLs. Exactly what it sees.
• 🛡️ Post-quantum hybrid — enrollment uses X25519 + ML-KEM-768, so a recorded session stays safe against a future quantum adversary.
• 🧱 Keys in a Rust enclave — mlocked memory, guard pages, excluded from core dumps, zeroed on fork() and on drop, never handed back to Python as bytes. Threat model: apps/sdk/native/README.md.
• 🔁 Retries and clock skew handled — idempotent retries, clock sync with the vault, stable exceptions: Errors.
• 📐 Pinned byte formats — docs/PROTOCOL.md is normative, and test vectors generated from the vault's reference implementation pin every byte.

Servers without a human#

A human approval on every restart is fine for a laptop; it is not fine for a Kubernetes pod. Point the SDK at OpenBao and it saves its unlocked session right after enrollment and restores it on every start — a deliberate trade, explained in full before you turn it on. Ready-made manifests live in apps/api/deploy/: Docker Compose and Kubernetes, with OpenBao auto-unseal for AWS KMS, Azure Key Vault, GCP KMS, Transit, Shamir and static keys.

Documentation#

The developer site publishes these same pages at /dev/docs, plus a reference generated from the code — every command, route and class. How the docs are built and checked.

Quality gates#

Every badge above is a workflow you can run locally with one command.

The contract is consumer-driven: the SDK's tests write contracts/diagnos-sdk-diagnos-vault.json, and the vault verifies that same file against its real code before it deploys.

flowchart LR
    SDK["SDK tests<br/>(Pact mock, Rust engine)"] -->|write| C[("diagnos-sdk-diagnos-vault.json")]
    C -->|replayed against| V["vault.diagnos.health<br/>provider verification"]

Repository layout#

integration/
├── apps/
│   ├── sdk/           diagnos          the library — everything lives here
│   │   └── native/    diagnos._secure  Rust memory enclave
│   ├── cli/           diagnos-cli      `diagnos …` in your terminal
│   └── api/           diagnos-api      REST facade (FastAPI), mTLS only
│       └── deploy/    compose · k8s    ready-to-run manifests
├── contracts/         Pact             consumer contract with the vault + its tests
├── docs/              guides/          the documentation · reference/ generated from the code
│                      PROTOCOL.md      normative byte formats · COMPATIBILITY.md · site.json
└── scripts/           docs/            the checks behind `make lint`, `make docs-check` and CI

Contributing#

You need uv, Python 3.11–3.13 and, to build the enclave from source, Rust stable.

git clone https://github.com/diagnos-tech/integration && cd integration
make sync    # installs everything and builds the Rust enclave
make check   # exactly what CI runs: lint, types, unit and contract tests, docs
make         # lists every other target

Read CONTRIBUTING.md before your first pull request. Coming from the imgexam packages? See MIGRATING.md.

Security#

Found a vulnerability? Please do not open a public issue — report it privately through GitHub Security Advisories. Details in SECURITY.md.

---

Apache-2.0 · diagnos.health