Reference source · 0.1.0-dev.11

developer-start.md

docs/developer-start.md · Download original file

# Start building with OPRP

OPRP is an experimental backend protocol for patient-selected record hosting. This guide gets an application developer from source checkout to an authenticated, encrypted exchange with synthetic records. A Host evaluates requested permissions and duration; it requests a patient decision only when its policy requires one. SDKs do not impose a patient portal login on every token request.

## Choose your starting point

| Your goal | Start here |
| --- | --- |
| Build an application | [SDK installation and examples](sdks.md), then the developer lab below. |
| Implement or operate a Host | [Host operations](host-operations.md), [reference Host](reference-host.md), and [wire contract](wire-profile.md). |
| Implement another SDK | [Cryptographic evaluation](cryptography-evaluation.md), [authorization](authorization-model.md), and executable interoperability cases. |
| Review the architecture | [Requirements](requirements.md), [decisions](architecture-decisions.md), [threat model](threat-model.md), and [project roadmap](project-roadmap.md). |

Use Node **24.7–24.x**, preferably the tested Node 24.19.0 runtime. Earlier Node versions do not provide the native post-quantum primitives used here. Install npm and OpenSSL for the development TLS certificate. Python/.NET SDK packaging additionally needs Python 3.12 with the pinned dependencies and .NET 10; those are not prerequisites for the basic Node Host lab.

```sh
npm ci
npm test
npm run typecheck
npm run host -- init .demo/host-lab
```

From separate terminals, start both Hosts:

```sh
npm run host -- serve .demo/host-lab a 6771
npm run host -- serve .demo/host-lab b 6772
```

In a third terminal:

```sh
npm run host -- probe .demo/host-lab a
npm run host -- probe .demo/host-lab b
npm run host -- status .demo/host-lab a
```

The probe uses verified development HTTPS and the same protected payload contract as an SDK application. Host A issues standing-policy access to its synthetic record without a patient login; Host B verifies the application and returns capabilities without an installed patient record. Host databases and identities persist when a server is stopped and restarted. The lab uses local-only development addresses and authorities, not an enrollment or production identity service.

## Integrate an SDK

Read [the backend SDK guide](sdks.md) for the exact TypeScript, Python and .NET constructors, installed-package examples, dependencies and runtime limitations. Each SDK accepts your application's identity/credential, Host credential, trust configuration, transport and clock. Your production enrollment process must supply verified identities; the development lab generates its own test authorities and credentials.

1. Resolve an email-shaped address through WebFinger and verify its signed address-to-Host delegation.
2. Request specific read/create/update/delete permissions and an intended access period from that Host.
3. Handle `granted`, `pending` and `denied` responses. Poll the Host's approval status if a decision is pending; the approval channel and user interface are Host policy.
4. Perform protected clinical operations with the issued token, maintaining operation IDs across retries.
5. Persist token/refresh state and ordered write intent. Use a durable mirror for authorized clinical reads after synchronization.

Use separate credentials for applications and human representatives. Requested permissions and refresh never override the Host's grant or the representative's actual authority. Current authorization, visibility and resource versions are checked again when an operation arrives.

## Exercise recovery before writing your own integration

```sh
npm run demo
npm run migration
npm run subscriptions
npm run recovery
```

These commands use temporary synthetic fixtures to demonstrate conditional approval, lost responses, replay-safe writes, change catch-up, protected notification delivery, backups and a complete Host transfer. They are separate from the persistent lab and remove their temporary databases/certificates. [Quickstart](quickstart.md) describes the first encrypted patient workflow in detail.

## Understand the current boundary

The reference Host supports a declared FHIR subset and six expanded clinical resource types. It is not a general FHIR REST server or a certified US Core service. [Clinical coverage](fhir-coverage.md) lists supported interactions. Optional [offline clinical validation](durable-clinical-validation.md) strengthens admission but has finite terminology coverage.

The development setup is restricted to loopback and synthetic records. Real deployment requires independent security assessment, secure persistence/key custody, actual identity verification, approval/representation evidence integration and broader clinical conformance. [Project status](implementation-status.md) distinguishes tested behavior from remaining work.

**Next:** complete your first authorized read, then add an idempotent write and test lost-response recovery before integrating real workflows.