V4.0 Secure Service Release Gate¶
The OpenMed secure service is ready for a v4.0 release only when one signed, offline-verifiable packet says so for the exact candidate commit. Issue closure is not release authority, and neither is a passing CI run or a built package.
The secure exchange and recoverable service scope was planned as v3.4 and was folded into v4.0 (release plan #4253, workstream #3543). The gate, its schemas, the recovery drill and the committed P0 checklist therefore carry the v4.0 name. This page belongs to #3603.
This is technical release evidence. It is not clinical validation, certification, a medical-device determination, or permission for autonomous clinical action, and a READY packet does not tag, publish or deploy anything.
Public contracts¶
| Contract | Location |
|---|---|
| Manifest JSON Schema | openmed/core/schemas/json/service_release_manifest.schema.json |
| Signed packet JSON Schema | openmed/core/schemas/json/service_release_packet.schema.json |
| Recovery-drill report JSON Schema | openmed/core/schemas/json/service_recovery_drill.schema.json |
P0 checklist (openmed.service_release.p0_checklist.v1) | openmed/eval/data/service_release_p0.json |
| Gate, loaders and offline verifier | openmed/eval/service_release.py |
| Recovery drill | openmed/eval/service_recovery_drill.py |
| Commands | scripts/release/service_release_gate.py, scripts/release/service_recovery_drill.py |
Manifests and packets use schema version 1.0.0 and compatibility policy same_major. Unknown fields, duplicate JSON keys, non-finite numbers, absolute paths, parent traversal, symlinked evidence and free-text moved-item fields are rejected. The packet reuses the v3 Journey gate's canonical JSON, caller-keyed HMAC-SHA256 signature and atomic writer.
Evidence kinds¶
Every kind is required. A kind with no manifest entry is not_present; a kind whose entry fails any check is blocked. Either makes the packet NOT_READY. Every entry names the candidate commit and its generation time, and the gate recomputes its SHA-256 beneath the checkout without following symlinks.
| Kind | Producer | Loader on master | What it binds |
|---|---|---|---|
security_profile_report | #3552 | unavailable | Production security-profile self-check result. |
no_egress_attestation | #3551 | unavailable | OS-enforced no-egress gate attestation. |
recovery_drill_report | #3603 | typed | Reference drill: every phase and objective. |
migration_rehearsal_matrix | #3578 | unavailable | Forward and rollback rehearsal for every durable schema. |
protocol_map | #3548 | unavailable | REST, GraphQL and gRPC semantic and privacy parity map. |
fixture | #3603 | digest only | Synthetic fixtures under tests/fixtures/ or fixtures/. |
failure_code_inventory | #3603 | typed | Every controlled code the gate, verifier, drill and REST service emit. |
p0_status | #3603 | typed | Captured state of every checklist P0. |
threat_model | #3603 | digest only | The service threat model. |
"Unavailable" means the producer is open work. Its digest is bound, but the entry is blocked with typed_loader_unavailable until a typed loader for that kind is passed to evaluate_service_release(..., loaders=...). The gate never treats an unparsed file as proof for those kinds.
Loaders receive the digested bytes and the release binding, never the path. They return value-free codes and a summary of counts, booleans, short codes and digests. A loader that raises, returns a non-code or a free-text summary value is blocked with evidence_loader_failed, loader_code_invalid or loader_summary_invalid.
P0 checklist¶
openmed/eval/data/service_release_p0.json lists every v4.0 service P0 and the evidence kinds it requires. It also lists the protected invariants that a moved item may not narrow.
| P0 | Control | Required evidence |
|---|---|---|
| #3544 | GraphQL POST-only and IDE hardening | security_profile_report, protocol_map, fixture |
| #3546 | gRPC loopback default and TLS | security_profile_report, protocol_map |
| #3547 | gRPC authorization and budgets | protocol_map, failure_code_inventory |
| #3549 | Journey principal binding | protocol_map, fixture |
| #3550 | Journey application-layer encryption | security_profile_report, migration_rehearsal_matrix |
| #3552 | Production security profile | security_profile_report |
| #3574 | Durable async jobs | recovery_drill_report, migration_rehearsal_matrix |
| #3575 | Transactional model activation | recovery_drill_report, failure_code_inventory |
| #3603 | Signed service release evidence | no_egress_attestation, recovery_drill_report, fixture, failure_code_inventory, p0_status, threat_model |
For each P0 the packet records its captured state and any missing kinds. A P0 blocks with p0_evidence_missing:<issue>:<kind> when a required kind is not present, p0_open:<issue> when the status snapshot shows it open, p0_status_missing:<issue> when the snapshot omits it, and p0_status_unverifiable:<issue> when no valid snapshot is bound. Closing an issue without its evidence does not make it complete.
The status snapshot is captured offline by the release operator and normalized with build_p0_status; the gate itself makes no network call.
from openmed.eval.service_release import build_p0_status
status = build_p0_status(
{"#3544": "closed", "#3546": "closed"}, # one entry per checklist P0
candidate_commit=candidate,
)
The packet records the checklist digest. The command-line verifier compares it with the committed checklist and fails with p0_checklist_mismatch when a packet was evaluated against another one.
Moved P1 and P2 work¶
A manifest may record work moved out of the release. Each item names the issue, priority, a controlled rationale, a later destination milestone, a coded residual risk and the claims it narrows. No free text enters the packet.
| Blocking code | Condition |
|---|---|
p0_moved:<issue> | The item is a P0 or appears in the P0 checklist. P0 work cannot move. |
moved_item_rationale_missing:<issue> | The rationale is not one of blocked_by_dependency, evidence_incomplete, hardware_unavailable, out_of_scope, risk_not_accepted, toolchain_unavailable or upstream_unreleased. |
moved_item_destination_invalid:<issue> | The destination is missing or not later than v4.0. |
moved_item_residual_risk_missing:<issue> | No residual-risk code is recorded. |
moved_item_weakens_invariant:<issue> | A narrowed claim is a protected invariant. |
Reference recovery drill¶
scripts/release/service_recovery_drill.py runs profile reference-v4.0: one declared failure per category, each walked through inject, detect, contain, recover, verify and resume, on synthetic state in a private temporary directory.
| Category | Declared failure | Available on master | not_available (owner) |
|---|---|---|---|
storage | Job-store write fails like a full disk | Failure surfaces, in-memory and on-disk state roll back, committed records survive a reopen, admission resumes | recover: encrypted backup and restore (#3577) |
process | Worker stops without shutdown mid-job | Committed job metadata survives the restart, admission resumes | detect, contain, recover: leases, poison quarantine, checkpoint replay (#3574) |
network | Model backend refuses connections | Circuit opens, requests are shed without reaching the backend, one recovery probe is admitted, the circuit closes, admission resumes | none |
corrupted_state | One Journey blob has a flipped byte | Integrity failure detected, corrupted bytes never served or silently replaced, unaffected blobs still served | recover: verified restore (#3577); verify: continuity manifest (#3599) |
Data-integrity objectives have a target of zero: lost_committed_records, partial_writes_visible, corrupted_bytes_served, admissions_during_open_circuit and unverified_restored_records. An objective is not_measured while one of its steps is not_available. Recovery-time objectives belong to the reference deployment declaration; the drill does not measure wall-clock time.
A report is complete only when all 24 steps pass and every objective is met. On master it is incomplete, so the gate blocks with drill_step_not_available, drill_objective_not_measured and drill_incomplete. When an owning issue lands, pass its implementation for that (category, phase) pair through run_recovery_drill(steps=...) and add it to DEFAULT_DRILL_STEPS.
The report records codes, counts, issue references and a canonical report_digest; never paths, record contents or exception text. A step that raises is recorded as failed with step_raised.
The command returns 0 only for a complete report, 1 for incomplete or failed, and 2 when no report could be written.
Sentinel scan¶
The gate scans every evidence file it retains and the final packet for prohibited value classes: absolute_user_path, aws_access_key, bearer_token, email_address, github_token, private_key_block, us_ssn, and planted_sentinel for synthetic sentinels passed with --sentinel-file. A match blocks with sentinel_detected:<class>:<entry id or packet>. Only the class name is recorded, and planted sentinels enter the packet as a count and digest. The documentation tests apply the same scan to this page and to the threat model.
Building and verifying a packet¶
- Check out the exact candidate commit with network access disabled.
- Run the recovery drill and write the failure-code inventory:
python scripts/release/service_recovery_drill.py \
--output evidence/service-recovery-drill.json
python scripts/release/service_release_gate.py \
--write-failure-codes evidence/failure-codes.json \
--candidate "$(git rev-parse HEAD)"
- Collect the security-profile report, no-egress attestation, migration rehearsal matrix and protocol map from their producers, and the P0 status snapshot.
- Write a manifest that lists every file with its SHA-256, kind, candidate commit and generation time.
- Build the packet with a key from a secret manager:
export OPENMED_SERVICE_RELEASE_KEY="$(security find-generic-password \
-s openmed-service-release -w)"
python scripts/release/service_release_gate.py \
--manifest service-release-manifest.json \
--output service-release-packet.json
- Verify it in a separate process:
python scripts/release/service_release_gate.py \
--verify service-release-packet.json \
--expected-candidate "$(git rev-parse HEAD)" \
--expected-release 4.0.0 --require-ready
A build returns 0 for a signed READY packet, 1 for a signed NOT_READY packet and 2 when the manifest, checklist, key or output is unusable. The command refuses to replace a packet unless --overwrite is given. The key must be at least 32 bytes and is read from OPENMED_SERVICE_RELEASE_KEY or a regular --signing-key-file; only its --key-id is recorded.
--verify returns 0 only for a valid packet. It recomputes the canonical digest and HMAC and re-checks the packet's own structure, so a changed, missing, reordered, unsigned or wrong-release entry is rejected even when an attacker re-signs it with the same key:
| Verifier code | Meaning |
|---|---|
packet_digest_mismatch, signature_invalid | A signed field changed. |
signature_missing, signature_algorithm_unsupported | The packet is unsigned or uses another algorithm. |
evidence_count_mismatch:<kind> | An evidence row was added or removed. |
evidence_kind_missing:<kind> | A required kind row is absent. |
evidence_order_invalid | Evidence or P0 rows are not in canonical order. |
wrong_candidate:<id> | A row names another commit without the gate's own block. |
candidate_mismatch, release_mismatch | The packet names another commit or release version than expected. |
release_target_unsupported | The packet is not for v4.0. |
p0_checklist_mismatch | The packet was evaluated against a different checklist. |
decision_inconsistent | The decision does not follow from the recorded rows. |
decision_not_ready | --require-ready was given and the packet is NOT_READY. |
unknown_schema, packet_malformed | The packet is not a v4.0 service packet. |
from openmed.eval.service_release import verify_service_release_packet
result = verify_service_release_packet(
payload, signing_key, expected_candidate=candidate, require_ready=True
)
assert result.valid, result.reason_codes
Release-gate reason codes¶
Gate codes carry a :<entry id>, :<kind> or :<issue> suffix where one applies. The complete root list is SERVICE_RELEASE_REASON_CODES; the failure-code inventory must include every one of them, every verifier and drill code, and the REST service's stable error categories.
| Code | Condition |
|---|---|
checkout_commit_mismatch, checkout_unresolved | HEAD is not the candidate commit. |
evidence_not_present:<kind>, evidence_kind_repeated:<kind> | A kind is missing or a single-entry kind repeats. |
evidence_missing, stale_digest | A file is absent, a symlink, or has a different digest. |
wrong_candidate | Evidence names another commit. |
evidence_expired, evidence_from_future | Evidence is older than the policy allows or newer than the evaluation. |
typed_loader_unavailable | The kind needs a typed loader that this checkout lacks. |
drill_* | The drill report is invalid, incomplete, failed or missed an objective. |
failure_code_inventory_invalid, failure_code_inventory_incomplete | The inventory is malformed or misses a controlled code. |
p0_*, moved_item_* | See the P0 and moved-work sections above. |
sentinel_detected:<class> | A prohibited value class was found. |
Structural problems (unknown schema, invalid fields, absolute or traversing paths, fixtures outside synthetic roots, a checklist for another release, an unusable key) stop the command with exit status 2 and no packet.
What master cannot prove yet¶
On master the gate always returns NOT_READY: the four producer kinds have no typed loader, six drill phases are not_available, and every checklist P0 is still open. The tests reach READY only with TEST-ONLY stand-in loaders and drill steps and a committed TEST-ONLY key in tests/fixtures/service_release.py. They prove the gate's behaviour, not the controls those stand-ins represent. The signature is symmetric HMAC, and the threat model still needs an independent review.