Open Patient Record Protocol Architecture Decisions
This log distinguishes agreed requirements from implementation proposals and unresolved choices. Change an accepted requirement only through an explicit product decision. Implementation details can evolve based on measured results without weakening the agreed guarantees.
Accepted decisions
| Decision | Rationale |
|---|---|
| Name the protocol Open Patient Record Protocol or OPRP | The name describes an independently implementable patient-record protocol. Convey receives creator attribution. |
| Patients choose independent Hosts | Hosting choice and portability are the core product purpose. |
| Host software handles at-rest protection | A wire protocol cannot directly prove an operator's storage practices. Assess operational security separately. |
| Encrypt and sign payloads in both directions with post-quantum protection | Protection is explicit at the application message layer, with HTTPS carrying the messages. |
| Use separate signing and encryption keys | Authentication and confidentiality have distinct cryptographic purposes. |
| Use FHIR, JWT, and selected OAuth and SMART conventions | Reuse standards without requiring SMART App Launch or a patient portal workflow. |
| Use DNS and WebFinger for account discovery | Reuse the Internet namespace without a Convey-controlled global resolver. |
| Support independent credential authorities | No company is a mandatory vendor-verification gatekeeper. |
| Separate verified identity from patient permission | A valid vendor credential does not authorize clinical access. |
| The Host issues tokens under current authorization policies | Vendors ask the Host; valid standing grants or preauthorization allow automatic issuance without patient interaction. |
| Separate consent and standing authority from token issuance | Token renewal does not require a new patient login or approval when authority still applies. |
| Keep authorization decision rules and approval interfaces Host-specific | The protocol standardizes requests, scoped tokens, and outcomes; a Host may require login and approval or issue automatically. |
| Require approval initiation when requested permissions need fresh patient permission | Evaluate each requested permission; preauthorized access does not trigger a new approval, and pending permissions never appear in issued tokens. |
| Include requested access duration in authorization requests | Hosts evaluate both scope and period and return the actual authorized end time. |
| Separate authorization duration from access-token lifetime | Weeks or months of approved access do not require weeks or months of JWT validity. |
| Define optional refresh issuance within the approved period | Refresh supports mobile and persistent clients without broadening scope, extending authorization, or requiring patient login for each JWT. |
| Support emergency-purpose requests and preauthorization | Hosts may permit limited emergency access without contemporaneous patient approval under their policies. |
| Include scoped delegation and legal representation in the core | Parents, guardians, patient-appointed delegates, and applicable power-of-attorney representatives use their own identities. |
| Make queues, receipts, conflict handling, and change feeds part of the protocol | Clients and Hosts need a common recovery contract. |
| Include export, backup, restore, and Host transfer | Patient custody must be practically movable and recoverable. |
| Require change feeds and define optional webhook delivery | Every client can synchronize, including those without public callbacks. |
| Provide TypeScript, .NET, and Python SDKs first | Cover initial application platforms with a shared interoperable contract. |
| Target the US with separable national profiles | Keep the core usable internationally. |
| Build the EMR after the protocol is demonstrated | The EMR uses the same interfaces as other applications. |
Proposed implementation defaults
| Proposal | How it will be resolved |
|---|---|
| FHIR R4 4.0.1 with JWT and selected SMART 2.2.0 conventions | Evaluate backend token issuance and scope conventions; specify OPRP request and decision semantics without mandating SMART flows or internal Host policies. |
| TypeScript reference services with PostgreSQL and storage adapters | Validate cryptography support, transaction durability, portability, and operational simplicity. |
| ML-KEM and ML-DSA with authenticated symmetric payload encryption | Select a reviewed construction, exact parameters, maintained libraries, and common vectors. |
| Temporary encryption keys or authenticated sessions for forward secrecy | Test key compromise, recovery, expiry, and interactions with durable queues. |
| An encrypted POST envelope carrying inner FHIR operations | Validate confidential search, signatures, streaming, proxy behavior, and SDK simplicity. |
| Minimal events followed by authorized record retrieval | Demonstrate low-disclosure notifications, catch-up, and current authorization checks. |
| One authoritative Host at a time | Prove coordinated migration and recovery; concurrent writable replicas require a later separate design. |
Decisions required during design
- Exact encrypted-envelope format, serialization, algorithms, key derivation, signature coverage, and large-message framing.
- Post-quantum credentials for authorities, address delegation, Hosts, applications, and grants; interoperability with established certificate formats.
- Authority governance, trust-bundle distribution, revocation freshness, compromise handling, and configurable local trust.
- Interoperable patient and representative context, emergency-request fields, pending-decision behavior, and account reuse. Patient enrollment, recovery, legal evidence, and approval workflows remain Host-specific; reference guidance is designed alongside the core.
- Fine-grained clinical permissions beyond resource categories, including field edits and attachment or reference access.
- Host-issued JWT claims, requested-duration start semantics, mixed-scope lifetimes, refresh exchanges and instance authentication, rotation recovery, grant extension and key rotation, stale-token invalidation, and confidential token placement.
- Deduplication and event retention, expired cursors, snapshot semantics, and safe migration retry resolution.
- Archive layout, independent recovery keys, signature-verification evidence, audit export, and activation of restored backups.
- Apache 2.0 is selected for OPRP original software and specification materials. Broader standards patent commitments, contribution governance and use of conformance or certification marks remain to be defined.
- Public website integration and release workflow once its repository or deployment configuration is available.
Executable prototype choices, October 1, 2026
These choices make the current experiment reproducible; they are not frozen production requirements. See wire profile and implementation status.
| Choice | Evidence and boundary |
|---|---|
| TypeScript/Node 24 native cryptography and SQLite Host/queue adapters | Working HTTPS workflow and durable retry tests. PostgreSQL and broader storage adapters remain optional deployment work. |
| ML-KEM-768, ML-DSA-65, HKDF-SHA-512 and AES-256-GCM | OpenSSL/PQClean interoperability is demonstrated; the new composition still needs independent review and a forward-secrecy design. |
| Signed WebFinger domain-to-Host delegation under constrained directory roots | Tested without Convey lookup infrastructure. Real enrollment, public root policy, revocation and account lifecycle remain unresolved. |
| Confidential JWT inside encrypted POST body | Protects token context and avoids ordinary GET bodies. This requires OPRP-aware clients/gateways; conventional OAuth header placement is not asserted. |
| All-or-nothing pending for mixed scope requests | No pending permission enters a JWT; the Host commits one durable approval task. Actual approval channels remain Host integrations. |
| Authorization starts at grant issuance; reference JWTs last at most five minutes | Requested and approved periods are distinct, and refresh cannot extend the grant. These illustrative limits are not production defaults. |
| Single-worker ordered durable queue and atomic mutation receipts/events | Loss/restart recovery and conflicts tested for two narrow operations. Scoped change feeds are working; general dependencies, receipt retention and migration remain open. |
The next executable increment adds scoped snapshots and durable accepted-change events, private context-bound cursors, visible-history retention, approval expiry/cancellation/denial/quotas, and bounded same-ID refresh recovery. Tests cover their failure and restart boundaries. General dependencies, deletion/visibility transitions, migration, cross-process coordination and production trust lifecycle remain unresolved. See synchronization, refresh recovery, and changelog.
Claims to avoid before verification
Do not equate HTTPS with post-quantum payload protection, a self-signed document with trusted identity, identity verification with consent, or an encrypted message with protected endpoint storage. Do not claim that ordinary FHIR clients already understand OPRP envelopes.
A successful HTTP request does not prove a clinical mutation was committed. A webhook acknowledgement does not prove the subscriber processed it. A copied archive does not prove a usable backup until restore succeeds. A migration is not complete until cutover, discovery, and retry recovery are verified.
The documents now include an executable experimental profile and a plan for completing it. They do not establish a production security guarantee, legal compliance, external certification, name exclusivity, or existing industry adoption.
Decision 15 Host-owned visibility and cache generation
Grant scope is necessary but not sufficient for disclosure. The reference Host adds exact label policy and bounded field removal, marks partial representations SUBSETTED, protects classification from requester mutation and requires full visibility for complete requester archives. Policy and visible classification changes invalidate opaque grant-specific epochs; mirrors clear and rebuild instead of inferring field removal from clinical versions. This adds no mandatory patient login, centralized Convey clearance service or public administration endpoint. See visibility and negative conformance for the implemented contract and limits.