Reference source · 0.1.0-dev.11
README.md

# Open Patient Record Protocol

Open Patient Record Protocol (OPRP) defines how applications discover, request permission for, and exchange patient-controlled health records with independently operated Hosts. Patients choose where their records live and can export, back up, restore, or transfer them. Created by Convey.

Status: executable experimental prototype `0.1.0-dev.11`, October 5, 2026. The TypeScript Host/SDK, durable client queue, scoped change feed, approval lifecycle, refresh recovery, credential/status lifecycle, requester rotation, independent encrypted backups/restore, coordinated two-Host migration, optional encrypted subscriptions with durable webhook retries, six additional versioned clinical resource types, locally packaged TypeScript/Python/.NET SDKs, stricter subset validation, stable paged reads, durable mirrors in all three SDKs, field/security-label filtering with visibility generation invalidation, authenticated rejection cases, versioned R4 profiles, locked offline HL7 validation, finite local terminology and durable intake/migration validation jobs, HTTPS demonstrations, persistent two-Host developer operations, injectable storage and a generated documentation website are working. The specification remains a draft; no certification or production security claim is implied.

## Project documents

- [Quickstart](docs/quickstart.md) runs the synthetic HTTPS workflow, tests, and independent Python interoperability check.
- [Implementation status and verification](docs/implementation-status.md) maps requirements to working evidence and outstanding acceptance criteria.
- [Experimental wire profile](docs/wire-profile.md) describes discovery, credential/message bytes, tokens, operations and retry semantics.
- [Threat model](docs/threat-model.md) identifies trust boundaries, tested controls and release gates.
- [Reference Host and queue integration](docs/reference-host.md) explains approval-policy integration and durable write handling.
- [Refresh recovery](docs/refresh-recovery.md) specifies bounded retries and SDK state persistence after response loss.
- [Synchronization](docs/synchronization.md) explains consistent snapshots, private cursors, ordered events and retention recovery.
- [Credential lifecycle](docs/credential-lifecycle.md) defines constrained authorities, durable fresh status, renewal and dual-key requester rotation.
- [Portability](docs/portability.md) specifies full signed archives, independent encrypted recovery and duplicate-safe restore.
- [Host migration](docs/host-migration.md) defines fencing, signed release/activation, discovery cutover and late queue recovery.
- [Migration conformance and recovery](docs/migration-conformance.md) records failure expectations and evidence.
- [FHIR coverage](docs/fhir-coverage.md) defines the six new clinical profiles, scoped interactions, history and deletion markers.
- [Durable clinical validation](docs/durable-clinical-validation.md) covers locked installation, local terminology, worker recovery and migration admission.
- [External clinical profiles and validation](docs/external-clinical-validation.md) documents versioned R4 profiles, selected US Core targets and the trusted Host admission gate.
- [Clinical validation](docs/clinical-validation.md) records checked fields, invariants and admission limits.
- [Pagination and mirrors](docs/pagination-mirrors.md) explains stable read sessions, local caching, recovery and SDK integration.
- [Visibility and cache invalidation](docs/visibility.md) defines Host-owned labels, field masks, incomplete views and cache rebuilding.
- [Negative conformance](docs/negative-conformance.md) records authenticated rejection cases and packaged SDK evidence.
- [Backend SDKs](docs/sdks.md) explains local packages, runtime providers, persistence and shared conformance.
- [Subscriptions and encrypted notifications](docs/subscriptions.md) defines callback proof, current permissions, durable delivery and feed catch-up.
- [Subscription conformance and recovery](docs/subscription-conformance.md) records failure cases and evidence.
- [Changelog](docs/changelog.md) records draft changes, including the required refresh transaction ID.
- [Cryptographic runtime evaluation](docs/cryptography-evaluation.md) records native implementations and independently verified interoperability.
- [Agreed requirements](docs/requirements.md) records the protocol scope and boundaries.
- [Implementation plan](docs/implementation-plan.md) defines the build order, deliverables, and completion criteria.
- [Architecture decisions](docs/architecture-decisions.md) separates accepted decisions from proposed implementation choices.
- [Authorization and representation](docs/authorization-model.md) explains Host-issued tokens, standing permissions, emergency preauthorization, and delegated control.
- [Website documentation plan](docs/website-documentation.md) defines the section intended for www.convey.care.
- [Standards references](docs/standards-references.md) identifies the primary sources to use when drafting the specification.
- [Envelope/access-request schema](schemas/exchange.schema.json), [decrypted request/decision schema](schemas/application.schema.json), [authority-status/rotation schema](schemas/trust.schema.json), [archive/backup schema](schemas/archive.schema.json), [migration schema](schemas/migration.schema.json), [subscription/callback schema](schemas/subscription.schema.json), [expanded clinical request schema](schemas/clinical.schema.json), and [HTTP API description](schemas/http-api.openapi.json) supply initial machine-readable structural artifacts.

## First runnable workflow

Use Node 24.19.0 (tested) or another compatible Node 24 runtime with native ML-KEM/ML-DSA APIs. From this folder run `npm ci`, `npm run typecheck`, `npm test`, `npm run demo`, `npm run recovery`, `npm run migration`, and `npm run subscriptions`. The Python interop and SDK package setup are in the quickstart. Run `npm run package:sdks` and `npm run sdk:conformance` after installing the SDK build prerequisites. The demos use synthetic identities and data and print only verification outcomes.

Working: signed WebFinger delegation; encrypted requests/responses; independent development credential authorities; scoped Host-issued JWTs; preauthorization or conditional approval with expiry/cancellation/denial/quotas; requested/approved periods; automatic refresh, bounded response-loss recovery and revocation; scoped representative context; limited Patient/laboratory operations; atomic receipts/events; a durable ordered write queue; scoped snapshots and paged change polling; constrained authorities and durable signed status; same-key renewal and dual-key requester rotation; separate export permission, signed archives and independent encrypted restore with preserved write receipts; inaccessible destination staging, durable source fencing, signed release/activation, monotonic discovery cutover and destination-authorized queue continuation; grant-bound subscription registration, signed encrypted callback challenges, durable minimal notifications, receiver deduplication/inbox and authorized catch-up.

The new Condition, AllergyIntolerance, MedicationStatement, Encounter, Procedure and Immunization profiles add separate read/create/update/delete permissions, immutable versions/history, scoped deletion markers, queue support, notification topics and expanded archives with migration preservation. Locally installable SDK packages are in `releases/0.1.0-dev.11/`; the .NET prototype uses an explicit local Python PQClean primitive provider on this macOS runtime.

Production gates include cryptographic composition/recovery review, forward secrecy, real authority and representative validation, cross-process coordination, broader FHIR validation and label policy/handling obligations, production subscription operations, general/incremental archives, production custody recovery and distributed fencing, native .NET/mobile providers, complete FHIR/US Core validation, broader mirror fault injection and production operations. The SQLite prototype stores records and queue data in plaintext; at-rest protection remains an operator responsibility.

## Development approach

Jason and Codex are the implementation team. Work proceeds by demonstrated milestones, with specification, code, examples, and verification developed together. The first complete workflow uses synthetic records. Security experiments are labeled until their construction and implementation are reviewed.

The protocol work lives here alongside the existing Convey exchange portal and OpenEMR integration environment. Those applications are useful context and possible later adapters; they do not already implement OPRP. The public website source and deployment configuration have not been located in this workspace.

## Publication approach

The planned public home is www.convey.care under a dedicated protocol section. Independently hosted copies of the specification, schemas, examples, SDKs, and conformance tools must remain possible. No required lookup, credential authority, account, or commercial service is operated exclusively by Convey.

The initial draft is version 0.1. OPRP original materials are licensed under Apache 2.0. Specification governance, broader standards patent commitments and naming of registered Internet identifiers remain release decisions. This license applies to the OPRP project and does not license the existing Convey applications.

## License

Copyright 2026 Convey, Inc. OPRP's original specification, documentation, schemas, profiles, reference Host, SDKs and tooling are licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE) and [third-party notices](THIRD_PARTY_NOTICES.md) for attribution and separately licensed materials. Apache 2.0 permits commercial use, modification and redistribution subject to its terms. It does not grant general rights to Convey's trademarks or establish interoperability certification.

## Website source

The Next.js, Tailwind CSS and shadcn/ui website project is in `website/`. See its [project README](website/README.md) for the Vercel root directory and development commands. React pages are under `website/app`; protocol Markdown remains under `docs`.