# Clinical Transfer In/Out

The main implementation is in `Music/mam`. The page is `/clinic-transfers`, linked from the type-2 Programs menu. All web actions enforce authenticated `user.type = 2`.

## What is transferred

Only the explicit clinical model/table list in `config/transfer.php` is eligible. Tables must exist, have a primary key and use InnoDB. "All" means all eligible tables, not every database table. Required clinical parent tables are included with all their rows.

These tables are blocked in the server-side registry, including when manually selected or included in a crafted package:

- Patient identity tables: `pt_configs`, `patients` and their identity logs. These are never exported, imported or deleted by this feature.
- Laboratory tables, including `labs`, `lab_*`, `labstitests`, `rprtests`, `viralloads`, `urines`, OfficeLab and related laboratory table names.
- `followup_generals` / Followup General.
- `dispensings`, `consumptions` and their shared `medicalitems_entries` catalog.
- Users, credentials, tokens and other system tables are outside the allowlist.

Laboratory, Followup General, dispensing, consumption and shared medicine catalog exclusions also apply to the existing `SyncTableRegistry`, and therefore to `sync:export`, `sync:push`, `sync:push-all` and `/api/sync/table` receiving. The existing general sync feature otherwise keeps its prior behavior. Existing files already exported by that older feature are not rewritten.

Clinical rows retain their patient-reference IDs. The receiving clinic must already have the referenced patient identities; this feature does not create or copy them. Existing references outside the clinical allowlist must also already exist at the receiver. Clinical rows can contain program-specific clinical fields; the exclusion is by table, not a field redaction feature.

## Initial setup on each clinic

Set the following in `.env`, using your real clinic IDs and labels:

```dotenv
TRANSFER_CLINIC_ID=clinic-a
TRANSFER_CLINICS_JSON='{"clinic-a":{"label":"Clinic A"},"clinic-b":{"label":"Clinic B"}}'
TRANSFER_RELAY_ENABLED=false
```

Then run:

```bash
php artisan config:clear
php artisan view:clear
```

Use PHP 8 or newer with the sodium extension for Argon2id and streaming authenticated encryption. Package passphrases are independent of Laravel's APP_KEY: clinics can have different APP_KEY values. Passphrases must be at least 12 characters. Share them separately from packages.

No database migrations are needed. Metadata, encrypted packages and encrypted source snapshots are stored privately under `storage/app/clinic-transfers`, not the public storage disk. Give the application and scheduler user access to this directory. Protect and retain the source APP_KEY: source snapshot and receipt-verification keys are encrypted with it.

The transfer worker uses the existing Laravel scheduler:

```cron
* * * * * cd /path/to/mam && php artisan schedule:run >> /dev/null 2>&1
```

For a manual processing pass:

```bash
php artisan transfer:work
```

Use the same application filesystem and Unix ownership for the web process and worker. File locks and atomic status writes protect concurrent processing on one installation. Do not deploy multiple independent local-storage workers for the same clinic.

Clinical data and identity-reference databases must be on the same MySQL server, with matching configured endpoint/socket, so one connection can perform atomic clinical imports and read identity references. The primary database user needs SELECT access to the identity database and SELECT/INSERT/DELETE access to approved clinical tables. Identity tables are read-only to this feature. Source and receiver schemas, primary keys and unique indexes must match. Non-InnoDB and primary-key-less tables are omitted.

## Offline flow

1. Source user chooses a target, all eligible data or multiple tables, and an export passphrase.
2. The worker creates an encrypted `.mamt` package. Download it from history and deliver it to the target.
3. Target user uploads the file with its passphrase. The worker validates schema, target clinic, keys and references.
4. History shows new/identical/conflicting rows. Approve copy and merge with the passphrase again.
5. After import, download the signed import-confirmation JSON and return it to the source.
6. Upload that confirmation against the original outgoing transfer. Verification starts the 15-day source cleanup period.

Validation uses a transaction and rolls it back; no clinical row additions remain after validation. Import repeats validation and commits only if the complete package is valid. New rows are inserted with their source IDs, identical rows are skipped, and differing rows with colliding keys block the entire import. There is no silent overwrite or numeric-ID reassignment. A blocked package can be revalidated after staff resolve the destination conflict or missing reference.

Tables with triggers that write outside transactional InnoDB storage or call external services are not suitable for this validation workflow. Verify custom triggers before adding custom tables to the allowlist.

## Central relay setup and flow

Deploy the relay controller, transfer store, transfer configuration and `routes/clinic_relay.php` to the central server, and require that route file from its existing `routes/api.php`. Clinic transfer pages and the cleanup worker belong on clinic installations. The central relay only stores opaque encrypted packages; it never receives their passphrases or clinical plaintext.

On the relay:

```dotenv
TRANSFER_RELAY_ENABLED=true
TRANSFER_CLINICS_JSON='{"clinic-a":{"label":"Clinic A","token":"UNIQUE_RANDOM_TOKEN_A"},"clinic-b":{"label":"Clinic B","token":"UNIQUE_RANDOM_TOKEN_B"}}'
```

On Clinic A:

```dotenv
TRANSFER_RELAY_URL=https://relay.example.org
TRANSFER_RELAY_TOKEN=UNIQUE_RANDOM_TOKEN_A
```

Clinic B uses the same URL with token B. Configure HTTPS, optionally through a stable Cloudflare Tunnel hostname. If Cloudflare Access protects the relay, use a Service Auth policy and configure `TRANSFER_ACCESS_CLIENT_ID` and `TRANSFER_ACCESS_CLIENT_SECRET` on each clinic. Existing `CF_ACCESS_CLIENT_ID` / `CF_ACCESS_CLIENT_SECRET` values are used as defaults when the transfer-specific values are empty. Tokens and Access secrets remain server-side.

The sender uploads the encrypted package in 2 MiB chunks with retries. Initialization returns hashes of previously received chunks so a retry skips intact chunks and resends damaged or missing chunks. Initialization and completion are idempotent, so failed sends can be retried from history. A separate relay rate limit allows up to 300 requests per clinic per minute, with an additional IP limit. The client explicitly uses HTTP/1.1 for reliable downloads through the existing tunnel. The receiver checks its central inbox when online, downloads packages in chunks, validates them with the sender's passphrase and approves the import. The worker sends a signed import confirmation back to the relay. The source worker polls for confirmations and starts cleanup only after cryptographic verification. Sender identity is bound to its relay token; only the addressed clinic can download a package or submit its receipt.

The relay endpoints are under `/api/clinic-relay/packages`; they return 404 unless relay mode is explicitly enabled and require `X-Transfer-Clinic` plus its matching `X-Transfer-Token`. Missing credentials never permit anonymous access.

Limit upload requests at the reverse proxy as well as PHP. Offline uploads are capped at 512 MiB, so `upload_max_filesize`, `post_max_size` and the web-server body limit must permit the desired package size. Large transfers can be divided by table. Relay chunk uploads require at least a 2 MiB body allowance. Keep enough private disk space for encrypted package, encrypted source snapshot and temporary files. Transfer history shows the latest 100 records.

## Automatic source cleanup

Cleanup runs **15 days after this source verifies a successful import confirmation**, using the source clock. Uploading/exporting a package alone never starts cleanup. Repeated confirmations do not extend or shorten the deadline.

The confirmation is bound to the original transfer ID, source, target and encrypted-package SHA-256 digest, and signed using a random secret included inside the encrypted manifest. A relay upload acknowledgment cannot substitute for an import confirmation.

At the deadline the worker decrypts the private source snapshot, checks the current schema, and deletes only unchanged clinical rows whose original primary keys and full row contents still match. Children are processed before parents. Changed records and records with remaining dependent rows are retained and reported. Declared foreign-key dependents outside the allowlist are checked too. The excluded identity, laboratory, Followup General, dispensing and consumption tables never enter the cleanup snapshot. Unknown legacy relationships must be added to the catalog before adding further tables.

Schema/access failures stop cleanup and remain visible in history. The next worker pass retries confirmed cleanup; it never deletes from an unconfirmed or incorrectly addressed transfer. Source patient identities and excluded modules remain available. Keep routine database backups. Encrypted package files and history are retained for auditing; remove them according to your clinic's retention policy after checking cleanup results. No package retention job deletes clinical data.

## Validation

```bash
php vendor/bin/phpunit tests/Feature/ClinicTransferTest.php
TRANSFER_TEST_SOCKET=/path/to/isolated/mysql.sock php vendor/bin/phpunit tests/Feature/ClinicTransferDatabaseTest.php
```

The database suite creates and drops randomly named disposable test schemas on the explicitly supplied isolated MySQL instance. It skips when no isolated socket is supplied and never uses production schemas. It checks identity/laboratory exclusions, preview rollback, identical merges, conflict rollback, missing identities, dependency handling, the offline worker and receipt cycle, 15-day cleanup, and preservation of edited records and new dependents.

The main project's `.env` has not been changed and no live transfers or clinical cleanup have been run. Configure real clinic IDs, the scheduler and relay settings when deploying to the remote servers.
