Skip to content

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.

python scripts/release/service_recovery_drill.py --output service-recovery-drill.json

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

  1. Check out the exact candidate commit with network access disabled.
  2. 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)"
  1. Collect the security-profile report, no-egress attestation, migration rehearsal matrix and protocol map from their producers, and the P0 status snapshot.
  2. Write a manifest that lists every file with its SHA-256, kind, candidate commit and generation time.
  3. 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
  1. 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.