Reference source · 0.1.0-dev.11

implementation-plan.md

docs/implementation-plan.md · Download original file

# Open Patient Record Protocol Implementation Plan

Build OPRP in demonstrated increments with Jason and Codex as the team. Each milestone delivers documentation, executable examples, implementation, and verification. Speed comes from resolving shared interfaces once and testing a complete workflow early. Calendar estimates are not assigned before implementation evidence exists.

Status: active implementation plan, October 1, 2026. Secure exchange/discovery, authorization/lifecycle, bounded refresh recovery, TypeScript SDK, independent Python operations, durable queue and scoped snapshot/change feed are executable. Milestones 0–3 remain open against their full acceptance criteria. See [implementation status](implementation-status.md) for evidence and remaining work. The existing portal and OpenEMR test environment are separate projects.

## Team responsibilities

Jason supplies product decisions, clinical workflow feedback, account ownership, and publication decisions. Codex drafts the specification, implements the reference software and SDKs, maintains documentation, and records test evidence. Routine reversible development can proceed within the agreed scope. Present concrete results when a decision is needed.

Independent cryptographic assessment and real-world provider interoperability are external validation dependencies before a production claim. Internal adversarial tests can proceed immediately; they do not constitute an independent audit.

## Proposed project structure

Keep the work under `protocol/` with specification sources, schemas, synthetic fixtures, shared vectors, SDK packages, a reference Host, a development authority, a patient interface, conformance tools, and a documentation site adapter. Exact folders follow the selected stack and package conventions.

The first SDK and Host use TypeScript on Node 24 with native ML-KEM and ML-DSA, and SQLite for a low-setup durable reference adapter. PostgreSQL and attachment storage remain deployment options to implement later. These are implementation choices, not protocol requirements. Python's independently implemented cryptographic exchange is working; .NET and complete Python SDKs remain planned.

Support storage adapters so a local installation does not require a cloud vendor. A Docker-based demonstration runs two Hosts, two authorities, a domain-discovery fixture, and synthetic client applications. Use isolated synthetic data and development credentials.

## Milestones

| Milestone | Deliverable | Completion evidence |
| --- | --- | --- |
| 0 Requirements and design inventory | Requirements, decision log, threat model, documentation map, pinned standards baseline | Every accepted requirement is mapped to a specification section and verification case. |
| 1 Secure message and trust prototype | Credential validation, signed discovery, encrypted request and response, independent runtime vectors | Two runtimes exchange messages; tampering, wrong recipients, expired credentials, and replay are rejected. |
| 2 First patient workflow | Reference Host with configurable approval policies, optional sample approval interface, scoped representation, TypeScript SDK, demographics and labs | Hosts with automatic and interactive approval return the same protocol outcomes; limited emergency and representative access work, and forbidden operations fail. |
| 3 Durable changes and synchronization | Transactions, receipts, conflict responses, queue adapter, change feed | Lost responses, restarts, duplicate sends, dependency failures, concurrent edits, and revoked queued writes recover safely. |
| 4 Portable records | Archive format, export, import, backup, restore, transfer | Two Hosts complete a verified migration, including interrupted cutover and outstanding client retries. |
| 5 Subscriptions | FHIR-aligned topics, webhook registration, event worker, catch-up | Notifications are confidential, duplicate-safe, permission-filtered, and recover after downtime and migration. |
| 6 SDK interoperability | .NET and Python SDKs and common conformance suite | Every client works against the Host and agrees on credentials, encrypted messages, errors, and portability formats. |
| 7 Host and client operations | Installers, recovery guides, lifecycle policies, mobile design, broader clinical profiles | Local and hosted deployment recipes are reproduced; restore and key-compromise exercises succeed. |
| 8 Public developer draft | Website section, versioned specification, examples, reference releases | Documentation builds, all examples execute, links resolve, and implementation status is accurately published. |
| 9 Release and EMR readiness | Reviewed v1 scope, interoperability evidence, security assessment, adoption guide | Required conformance cases pass and material findings are resolved or explicitly gate release. |

Documentation runs continuously through milestones 0 to 9. The public draft can be published before v1 when its limitations are clearly labeled. Swift and Kotlin follow the common message and authorization contract, rather than delaying the initial server-to-server workflow.

## Milestone 0 Requirements and design inventory

Draft an architecture document with actors, trust boundaries, message flows, storage responsibilities, and authority governance. Trace requirements from patient addressing through migration. Use FHIR R4 4.0.1 as the proposed clinical baseline and evaluate JWT, OAuth, and selected SMART 2.2.0 backend and scope conventions without mandating App Launch. Select the US Core and subscription-backport versions explicitly. Recheck current publications before freezing them.

Define the essential identifiers: account address, record identity, vendor, application, deployment, actor, standing policy, grant, representative authority, credential key, message, operation, event, subscription, and migration. Determine which remain stable across key rotation and Host transfer. Define account reuse so an old address cannot grant access to a different patient's record.

Specify the backend token request with explicit requested permissions and access duration, the authorized period, JWT expiry, pending decision, denial, emergency purpose, and representation context before building the token endpoint. Define per-permission evaluation and mixed requests, including initiating approval for scope or duration requiring a fresh patient decision. Specify refresh capability, requester binding, rotation, expiry, and recovery from response loss; distinguish refresh from authorization extension. Discover how clients follow or check the Host's pending process without prescribing its approval interface. Keep authorization rules behind a reference Host decision-provider interface so independent Hosts can substitute their own policies and approval systems. Model parent and conditional power-of-attorney authority separately from voluntary patient-appointed delegates in reference examples.

Resolve the protected wire boundary. Ordinary HTTP GET bodies are unsuitable for dependable encrypted searches. Evaluate a POST envelope carrying an inner FHIR operation and encrypted query context, or another standards-compatible arrangement. Document the effect on unmodified FHIR clients and gateways. Resolve token placement, error confidentiality, signature coverage, and algorithm identifiers before generating APIs.

Deliver the first normative draft only after these choices are testable. Define open licensing and patent policy before publishing code or specification rights. Do not infer that existing portal code is licensed for public reuse.

## Milestone 1 Secure message and trust prototype

Evaluate maintained cryptographic implementations for ML-KEM and ML-DSA across Node, .NET, and Python. Record versions, parameter sets, security properties, maintenance status, license, and platform support. Choose a reviewed KEM-based authenticated-encryption construction; do not create custom cryptographic primitives.

Specify credential contents, the verification chain, root trust distribution, revocation freshness, compromise recovery, and maximum cache age. Build two development authorities to prove that the implementation does not privilege Convey. Authenticate address-to-Host delegation and Host keys; signing a key document with an untrusted key is insufficient.

Define required algorithms, key separation, key derivation, nonce generation, associated data, canonical serialization, message expiry, recipient binding, and response-to-request binding. Include credential, token, and discovery authentication in the post-quantum policy. Prove forward-secrecy behavior or explicitly limit the prototype claim while temporary-key/session design is unresolved.

Create deterministic test vectors where the construction permits them, known-answer cases, malformed inputs, and cross-runtime round trips. Use independent implementations of serialization and verification, not only tests that invoke the same helper twice. Benchmark key sizes, message overhead, latency, memory use, and large attachments.

## Milestone 2 First patient workflow

Implement authenticated discovery, Host capability metadata, verified token requests, scoped JWTs, representative context, and the encrypted exchange gateway. The reference Host uses a configurable decision provider and demonstrates standing policies, grants, and representative authority. Approval is conditional: when requested permissions require a new patient decision, the Host must initiate it; already authorized permissions need no new approval. An optional sample interface describes the requester, purpose, permissions, duration, and status. Its presentation and advance-permission choices are not protocol requirements. Block invalid requesters and limit repetitive requests before notification.

Implement one synthetic adult patient, demographic updates, lab creation and retrieval, provenance, and an audit view. Enforce operation and category permissions through search results, histories, related resources, attachments, and errors. Do not expose another patient's data through guessed IDs. Separate trusted organization credentials from patient grants.

The TypeScript quickstart completes the workflow from address to authorized record access. Demonstrate one Host policy issuing automatically and another requiring login and approval, with identical client-facing contracts. Test a mixed request that initiates approval only for permissions needing a fresh decision and never grants pending scope. Test token replacement without interaction when permitted, pending interaction when required, limited emergency preauthorization, scoped parental control, and conditional representative authority using synthetic evidence. Test denial, expiry, revocation, scope escalation, authority changes, and requester-key rotation. Document human actor attribution for staff behind an EMR deployment. Sharing the patient's account is never the representative workflow.

Add requested and approved periods, short-lived JWTs, and an optional refresh exchange to this milestone. Use a controllable test clock to verify day-long and months-long authorizations without waiting for wall time. Test shorter Host-approved durations, new approval for an uncovered extension, refresh without interaction, expired authority, rotation reuse, response loss, and concurrent SDK refresh. Never treat refresh as permission to expand access.

## Milestone 3 Durable changes and synchronization

Add durable client queue interfaces and a reference persistence adapter. Model pending, submitted, committed, conflicted, and rejected outcomes. Queue entries preserve operation intent; retries re-encrypt and re-sign with current transmission credentials.

Commit operation receipts with mutations, define the equivalence rule for retried operations, and bind deduplication to the correct principal. Specify retention and explicit recovery when receipts expire. Add conditional updates, dependency checks, atomic transaction handling, and patient-safe conflict responses.

Implement a durable, permission-filtered change feed. Specify cursor expiry, visibility changes, resynchronization, deletion markers, and authorized offline caching. Test process termination before and after commit, response loss, concurrent workers, reordered arrivals, and revoked grants. The acceptance criterion is observed record correctness after recovery, not only HTTP success.

## Milestone 4 Portable records

Define a versioned package with a manifest, resource identities, versions, attachments, integrity information, provenance, signature-verification evidence, and the synchronization state needed for transfer. Decide audit-export scope. Preserve unknown content explicitly and report unsupported validation. Provide resumable large-file handling and encrypted offline archives with independently recoverable keys.

Implement full and incremental export, validation, import, restore, and source/destination receipts. Test the case where the source provider is unavailable during restore. A successful import proves content integrity and reports clinical/profile validation separately.

Implement migration as a state machine: authorized, snapshotting, copying, catching up, ready, cutover, completed, or recoverable failure. Prevent writes to the old authoritative generation after cutover. Preserve deduplication records or provide a provably safe retry-resolution method. Update discovery and re-establish destination grants and subscriptions.

Test interrupted uploads, broken manifests, repeated imports, destination crashes, discovery-cache delays, late client retries, and failure on each side of cutover. Deletion of the source copy is a separate operation. Backups remain copies unless explicitly activated through a recovery process.

## Milestone 5 Subscriptions

Use the FHIR topic-based subscription model and selected backport profile. Define required change-feed support and optional webhook capability advertisement. Start with minimal notifications and normal authorized retrieval.

Bind callback endpoints to verified deployment identities, test endpoint control, and prevent requests to unsafe internal destinations or redirects. Commit event creation with record changes and use a durable worker with bounded retries, batching, rate limits, and delivery status. Encrypt notifications and recheck grant and recipient-key status on every delivery.

Test duplicate and reordered events, missed acknowledgements, revoked subscriptions, expired keys, retention gaps, migration, and updates echoed by subscribers. Acknowledgement means accepted delivery, not completed clinical work. No event may disclose restricted record existence.

## Milestone 6 SDK interoperability

Create idiomatic .NET and Python SDKs using the same public schemas and vectors. Each supports discovery, credentials, consent, exchange, queue hooks, synchronization, subscriptions, and portability. Keep service policy and database implementation out of client libraries.

All SDKs distinguish authorization expiry from JWT expiry and implement automatic refresh or authenticated replacement under the Host's advertised capabilities. Test instance-bound mobile credential behavior separately from server-client credentials, including secure-storage integration and refresh races.

Run the same client scenarios across every SDK. Build at least one independently implemented validation path or minimal second Host so interoperability evidence is not confined to a single shared codebase. Distinguish server, browser, and mobile key handling; never put an organization-wide private key in browser-delivered code.

Generate API references and execute documentation snippets against the synthetic demonstration. SDK versions declare compatible protocol versions. Define stable error categories and recovery actions rather than requiring applications to parse prose messages.

## Milestone 7 Host and client operations

Document installation, network reachability, TLS, key custody, backups, monitoring, audit access, revocation, incident recovery, and administrative permissions. Provide local and cloud storage adapters with the same protocol behavior. Do not require the existing portal's hosted identity or database vendors.

Complete operational identity enrollment, recovery, representative-evidence validation, jurisdiction-specific minor and emergency rules, conflicting authority handling, and closure on top of the policy and representation model implemented earlier. These rules must be verified before supporting their corresponding real clinical workflows. Add broader record profiles with real validation and round-trip preservation tests. Design Swift and Kotlin around mobile lifecycle, background limits, and platform key storage.

Publish protocol-conformance criteria separately from Host security assessment. Define assessor evidence, renewal, exceptions, and public status. Hosting certification does not automatically establish legal compliance or independent cryptographic review.

## Milestone 8 Public developer draft

Build the documentation section from versioned repository sources. Confirm the actual source and deployment path for www.convey.care before integration; the inspected public site does not identify that path. Keep preview publication reversible and show accurate draft and implementation status.

Create architecture illustrations, complete tutorials, generated API and SDK references, authority policies, Host guides, portable examples, threat-model documentation, and a conformance catalogue. Validate links and examples and make the site searchable and accessible. Preserve stable version links and downloadable releases.

Use a reproducible build and avoid runtime dependence on Convey for identifiers or schemas. A registered identifier can have Convey as its publication origin without requiring a network fetch during every transaction. Submit applicable Internet registrations only once the formats are stable.

## Milestone 9 Release and EMR readiness

Exercise at least two Hosts, two authorities, and all released SDKs across supported operations. Complete a documented security review, resolve material findings, and publish limitations honestly. Collect external implementation feedback before claiming broad ecosystem interoperability.

Freeze the v1 normative specification, conformance suite, required algorithms, compatibility policy, changelog, and migration rules. Publish reproducible packages and deployment instructions. An implementation that omits a required capability cannot claim full v1 conformance.

Then start Convey's EMR as a client of the same public protocol. Its clinical workflow, billing, patient lookup, and authorized local caches are separate requirements. Add an adapter to the existing exchange portal or OpenEMR only after a concrete integration scenario is selected.

## Current implementation sequence

The threat model, wire profile, discovery, independent runtime exchange, authorization/lifecycle/recovery, queue and scoped snapshots/changes are documented and executable. Constrained credential/status trust, dual-key requester rotation, explicit token replacement, signed full narrow-profile archives and independent encrypted backup/restore are now executable. Coordinated two-Host cutover now has inaccessible staging, exact final catch-up, durable source fences, signed release/activation, verified discovery publication and destination-authorized late queues. Optional subscriptions now include grant-bound registration, protected callback control, atomic minimal hints, durable leased delivery, receiver inbox recovery and current-authority/migration checks. The topic/backport mapping and production scheduler/egress/retention remain open. The next clinical slice now adds six scoped types with version history/deletion, queue/subscription integration and expanded archives. TypeScript/Python/.NET packages are locally installable with shared encrypted client scenarios; native reviewed .NET and secure platform storage remain open. Continue with full profile/US Core validation, shared serialization/fuzzing, comprehensive label/handling profiles and broader mirror failure injection, general/incremental portability, distributed custody/rollback recovery, approval delivery integration, status/renewal workers, full audit coverage and broader synchronization. The cryptographic composition and recovery design require independent review, and forward-secrecy behavior remains unresolved before any production claim.

Stable scoped baseline/search/history sessions and durable TypeScript/Python/.NET mirrors are now implemented. Selected R4 field/calendar/choice/status/invariant checks are tightened under `oprp-r4-clinical-2`; full external profile/terminology validation remains open. See [pagination/mirrors](pagination-mirrors.md) and [clinical validation](clinical-validation.md).

## Visibility profile update

The Host advertises `visibility_profile: "oprp-visibility-1"`. [Visibility and cache invalidation](visibility.md) defines trusted grant policy, exact security labels, `SUBSETTED` field projections, write/export protection and required baseline/change `visibility_epoch`. Changed visibility invalidates prior cursors and clears SDK mirrors before a new baseline; disconnected clients cannot learn unknown permission changes. [Negative conformance](negative-conformance.md) records authenticated rejection tests. Host policy and approval delivery remain local integration choices.

## External clinical validation update

The [external clinical validation guide](external-clinical-validation.md) now supplies versioned six-type R4 StructureDefinitions, local package/checksums, a pinned HL7 validator, selected US Core 9.0.0 targets and a trusted optional Host admission gate. Run `npm run setup:validator`, `npm run package:profiles` and `npm run clinical:conformance` with Java installed. Terminology remains disabled; a successful example does not establish complete US Core server or clinical conformance. Host policy, authorization and patient approval remain separate.

## Dev10 completed increment and next step

[Durable clinical validation](durable-clinical-validation.md) adds complete cache content locking, HTTP-disabled validation, finite local terminology, bounded persistent jobs/leases and destination archive/migration gates. Synthetic real-engine evidence and SDK package checks accompany this increment. Clinical terminology coverage remains finite; broad licensed systems and review remain release gates.

**Next:** implement replaceable Host persistence/storage interfaces, then reproduce a two-Host installation and add operator health/recovery tools. Documentation remains part of each step.