Reference source · 0.1.0-dev.11
requirements.md
docs/requirements.md · Download original file
# Open Patient Record Protocol Requirements
This document records the agreed product requirements for OPRP. It is a planning baseline, not a normative wire specification. The implementation plan turns these requirements into versioned interfaces and tests.
## Purpose and ownership
Patients choose their Host, control application access to the record held there, and can move or copy their records without dependence on Convey. A Host can operate on commercial cloud infrastructure, a personal computer, a phone, or another platform able to implement the interface. Reachability and availability depend on the deployment; the protocol accommodates outages.
Patient control does not imply that copies already disclosed can be recalled. Preserve author attribution, original clinical signatures, and revision history. Record amendments must be distinguishable from the original entries. Provider-held records and applicable retention duties need separate treatment in the US implementation guide.
## Participants
| Participant | Responsibility |
| --- | --- |
| Patient or authorized representative | Exercises permitted record access or control; representation is scoped and independently verified. |
| Host | Stores records, enforces permissions, processes changes, and operates the patient interface. |
| Requesting application | Reads or writes within a grant and maintains its own durable outage queue. |
| Address provider | Resolves accounts within its domain to authorized Hosts. It may be separate from storage. |
| Credential authority | Verifies organizations and deployments and issues identity credentials. |
| Host assessor | Evaluates operational security separately from protocol interoperability. |
A vendor identity identifies the software organization. Application and deployment identities distinguish its products and installations. Host-provider migration means moving record custody, rather than changing the EMR vendor.
## Addressing and discovery
Use an email-shaped account address such as `jason@records.example`, represented for discovery as an account URI. An email mailbox is unnecessary. Use existing DNS and WebFinger, with an OPRP service link, rather than a private global directory.
The address domain may resolve an account to a different storage domain. Discovery describes supported versions, authentication services, and authenticated Host key information. It supplies no clinical data. Define bounded redirects, cache expiry, international domain handling, address normalization, account-reuse rules, and resistance to enumeration.
An address controlled by a provider cannot be guaranteed to survive the loss of that provider or its domain. Personal domains offer greater address continuity. Define aliases and authenticated migration. Avoid treating an address alone as permanent clinical identity, and avoid an obligatory global patient index.
## Record model and Host operations
OPRP is a backend protocol for information exchange. Use FHIR for clinical data, JWT for the access-token format, and selected OAuth and SMART conventions where they fit. The Host issues tokens under its own authorization policies. OPRP does not require SMART App Launch, a patient portal, or a standard patient-login or consent process. Define concrete versioned profiles and supported interactions before advertising conformance. OPRP encrypted transport adds requirements that ordinary FHIR or SMART clients do not automatically implement.
The Host interface covers reading, searching, creating, updating, and deleting records; atomic changes; history; attachments; provenance; and audit access. Read permission, search permission, creation, correction, and deletion must be distinguishable. Sensitive categories, linked resources, included search results, counts, histories, attachments, and error responses must enforce the same grant boundaries.
The initial demonstration includes demographics and laboratory observations, with supporting provenance and audit records. The eventual record profile covers medications, allergies, conditions, encounters, documents, imaging references, and other clinical content. Unrecognized portable resources must not be silently discarded or represented as clinically validated.
## Identity and access
Independent authorities issue credentials binding verified identities to signing and encryption keys. Participants keep private keys. Trust policy covers authority qualification, validation evidence, renewal, rotation, revocation, compromises, and removal. Multiple independent authorities can interoperate; Convey is not a mandatory authority or a runtime dependency.
An application requests its access token from the patient's Host or that Host's designated authorization service and explicitly includes the permissions and access period it wants. The Host verifies the requesting identity and evaluates each requested permission and its duration against existing authorization and its own policies. Verification alone does not grant access. Previously authorized permissions need no new patient approval when the requested period is also covered. If requested permissions or an extension of their duration require new patient approval, the Host must initiate that approval process, potentially through an authorized representative. Permissions prohibited by policy are denied rather than treated as approval requests. Automatic authorization can derive from advance patient permission, a hosting agreement, or another applicable authority recognized by the Host. Apply request limits and blocking before notifications.
The condition that triggers an approval request is part of the protocol contract; the approval mechanism is Host-specific. OPRP does not prescribe how advance patient permissions are obtained, which data elements are offered for advance authorization, how policies are represented, or how new approval is requested. The Host may require login to its system when approval is needed. A token must never include a permission that is still awaiting approval. Define mixed requests containing already authorized and approval-required permissions explicitly so clients can distinguish granted, pending, and denied scope.
Standardize the application-visible contract: authenticated token requests, requested permissions and patient context, issued scoped JWTs, denial, and pending authorization when fresh approval is required. Define how clients check a pending request or follow Host-provided interaction instructions without assuming a particular approval screen. Do not require a specific policy engine, internal grant schema, hosting agreement, consent channel, or patient authentication method.
Distinguish durable authority from the short-lived token representing it. The reference Host will demonstrate standing grants and patient-approved policies, but other Hosts can implement different decision systems. A new token request does not require a new consent event when the Host recognizes sufficient existing authority. The returned token states the access actually authorized; it does not prove which internal workflow produced that decision.
Support requests that express emergency purpose and the limited access sought without requiring contemporaneous patient approval. The reference Host will demonstrate patient-defined emergency preauthorization, including during incapacity. Each Host determines eligible requesters, required evidence, and applicable policies. The protocol binds the issued scope, lifetime, and actor context to the Host's decision. A requester's emergency assertion is not universal authorization; emergency access is not an automatic bypass in the wire protocol.
Access tokens use a signed JWT profile defined by OPRP and issued by the Host. JWT specifies a representation, not the workflow that authorizes issuance. Define issuer, audience, requester and patient context, scopes, validity, an opaque authorization-decision reference where applicable, and requester-key binding. Hosts need not expose internal policies or legal documents to requesters. Apply the chosen post-quantum authentication profile. Bind requests to the authorized principal and destination. Define expiry, renewal, revocation, and key rotation. The SDK requests replacement tokens automatically; the Host reevaluates under its rules and may issue, deny, or require interaction. Preserve individual actor attribution where an organization acts through staff or automated agents.
The Host remains responsible for current authorization at record access and notification delivery, even when a JWT has not expired. Define policy-version checks and invalidation of grants and delegated authority so stale tokens do not preserve revoked access.
## Access duration and refresh
Every access request specifies the requested authorization period, expressed through a duration or explicit end time in the finalized schema. Define when a requested duration starts; waiting for approval is not itself authorized access. The Host returns the actual authorized period, which can be shorter than requested but cannot silently exceed it or the underlying patient or representative authority. Include requested scope and period in any new approval process. An extension is a new authorization decision and triggers patient approval only when existing authority does not cover it.
Separate the authorization period, individual access-JWT lifetime, and refresh-credential lifetime. A hospital application may request weeks or months of authorization; a lab or simple application may request one day. Individual JWTs remain short-lived and never outlast the authorization they represent. Report the authorization end separately from JWT expiry so the SDK knows whether to refresh or request renewed access.
Specify refresh-token support and advertise its availability. Host policy decides whether to issue a refresh credential for an authorized client. A refresh request obtains a new short-lived JWT within the existing authorization; it cannot expand scope or extend the approved period. Refresh does not require patient interaction while sufficient current authority covers it. Hosts may also support direct authenticated token replacement for backend services without a refresh credential.
Bind refresh credentials to the client or application instance and the relevant patient authorization. Define rotation, reuse detection, revocation, absolute expiry, and any Host-selected inactivity expiry. Public mobile applications must not contain a shared vendor-wide private key or secret; use an appropriate instance-bound mechanism. The SDK handles refresh and advertises secure-storage requirements appropriate to its platform. Migration reestablishes refresh credentials at the destination rather than copying the source Host's secrets.
Refresh rechecks current permissions, representative authority, credential status, and authorized end time. Grant revocation, lost authority, and expiration prevent further refresh and affected record access. Queue submissions and notifications follow the same current-authorization rules; refreshing cannot revive expired permission for delayed work. See [Authorization and representation](authorization-model.md).
## Delegation and legal representation
Make patient-appointed delegates, parents, guardians, and health-care representatives under power of attorney first-class identities in the authorization model. A representative acts with their own authenticated identity; do not require them to share the patient's login or private keys. Distinguish permission to read records, manage application grants, export data, transfer Hosts, and appoint further delegates. Further delegation is permitted only where the underlying authority expressly allows it.
Define an interoperable way to distinguish patient, acting representative, requesting deployment, permitted actions, and the Host's authorization decision. Verification of authority and custody of supporting evidence are Host responsibilities. The reference model records source of authority, evidence, scope, effective dates or activation conditions, status, and history; equivalent internal models are permitted. A legal representative need not receive an in-app grant from an incapacitated patient or young child. A relationship label alone does not prove authority.
Support restricted parental access, changes in custody, confidentiality exceptions, majority or emancipation, conditional power of attorney, and competing representatives. Apply jurisdiction-specific rules rather than assuming every parent or every power of attorney grants unrestricted permanent control. Record the patient, actual actor, requesting deployment, and authority used for decisions and mutations. Changes to representative authority propagate to dependent grants, tokens, subscriptions, and queued work through a defined reevaluation policy.
Authentication and recovery methods, legal-evidence validation, rule precedence, competing instructions, and account closure are Host-specific policies. Publish reference and jurisdiction guides without prescribing one approval workflow. The core token contract and representation context are designed from the first milestone; the reference Host demonstrates different approval policies in the first authorization workflow. See [Authorization and representation](authorization-model.md).
## Message protection
HTTPS carries mandatory signed, post-quantum encrypted application messages in both directions. Applications encrypt for authenticated Host keys; Hosts encrypt for authenticated requester keys. Signing keys and encryption keys have separate purposes. Define one interoperable required cryptographic profile rather than relying on optional algorithm overlap.
Use standardized algorithms and reviewed constructions. Candidate primitives are ML-KEM for establishing shared secrets, ML-DSA for signatures, and authenticated symmetric encryption for payloads. Final parameter sets, key derivation, serialization, nonce rules, context binding, streaming, and signature placement require a design decision and cross-language vectors.
The authenticated trust path for Host and requester keys is part of the post-quantum design. A self-signed Host document or an encryption key obtained solely through an unverified lookup is insufficient. Include grants and credential signatures in the threat model.
Define protection of clinical search parameters, authorization material, and confidential error details as well as FHIR bodies. Minimize exposed routing metadata. Use authenticated temporary keys or sessions if required to achieve forward secrecy. No plaintext fallback is allowed in the OPRP secure profile.
Hosts and authorized applications can decrypt records. At-rest security remains an operator responsibility. Publish a separate Host security assessment program that evaluates outcomes without mandating one database or storage-encryption implementation.
## Queues and synchronization
Clients store pending changes durably and show whether a change is local or accepted by the Host. Every mutation has a stable operation ID, principal, target, dependency information, and applicable base versions. Retries refresh transmission authentication while preserving the logical operation.
Commit the mutation and its receipt atomically. An identical logical retry returns its authorized outcome without reapplying the change. Reuse of an operation ID for a different operation is rejected. Define deduplication retention and a safe recovery response when an old retry can no longer be proven equivalent.
Preserve dependencies within a client's sequence. Use version checks and explicit conflict resolution for concurrent edits from different systems. Timestamps alone do not establish a valid global order. Permission must still hold when a queued change arrives. Failed changes remain available for resolution.
Provide a permission-filtered durable change feed with resumable cursors, retention limits, and a resynchronization method when a cursor expires. Track deletion or visibility changes without exposing records outside a subscriber's grant. Offline reads require separately authorized local caching and clear stale-data indications.
## Portability and backups
Define export, import, full backup, incremental backup, restore, and coordinated transfer. Patient-downloadable archives work without another provider account. The package format is documented, versioned, and independently readable.
Preserve record identities, versions, attachments, clinical signatures, provenance, and the required synchronization and receipt history. Use a consistent snapshot, manifest, integrity verification, and explicit accounting for unsupported content. Define the scope of audit-history export, since it can include third-party information.
Encrypt direct transfers for the destination Host. Encrypt downloadable backups with a recovery method independent of the source provider. Test recovery from provider disappearance. Do not transfer Host private keys, existing access tokens, or operational service secrets. Revalidate consent policies and issue destination credentials.
A migration copies a snapshot, catches up changes, verifies completeness, and performs a coordinated cutover. One Host remains authoritative throughout. Discovery, pending client queues, event cursors, and deduplication must survive the handover or have explicit recovery procedures. A backup copy does not become authoritative automatically. Source deletion is a separate authorized action governed by the applicable retention policy.
## Subscriptions
Include standardized subscription creation, discovery, status, renewal, pause, and cancellation. The change feed is required; webhook delivery is a declared capability. Support clients without publicly reachable callback endpoints.
Minimal notifications followed by authorized retrieval are the initial delivery model. Events are signed and encrypted for the subscriber. Do not disclose the existence or category of a restricted record. Recheck grants and recipient-key status on every send and retry.
Validate callback control and permitted network destinations. Specify event IDs, cursors, retries with backoff, acknowledgement semantics, batching, expiration, retention, and catch-up after delivery failure. Subscribers tolerate duplicates and out-of-order messages. Receipt acknowledgement is distinct from clinical processing success.
Migration preserves subscription intent and revalidates it at the destination. Define origin and correlation information to avoid synchronization loops. Full clinical payload delivery can be a later authorized capability.
## SDKs and publication
Produce simple SDKs for TypeScript, .NET, and Python first, followed by Swift and Kotlin. Cover discovery, credentials, consent, secure exchange, durable queue adapters, synchronization, subscriptions, export, and migration. Mobile and browser runtimes need their own key-storage and networking guidance.
Publish extensive, versioned documentation at www.convey.care: patient explanations, implementer tutorials, the normative specification, schemas, SDK references, Host operation guides, authority policies, conformance cases, and security documentation. All core artifacts must be usable independently of that website.
Target US healthcare first. Keep jurisdiction-specific consent, terminology, retention, and administrative profiles separate from the international protocol core. Build Convey's own EMR after protocol behavior and interoperability are demonstrated.