Service Security-policy Generations¶
openmed.service.policy_generations applies runtime changes to the REST service's non-secret security policy as versioned, fully validated generations. A candidate is either activated atomically as the next generation or rejected while the prior generation stays active. In-flight work is pinned to one generation, so a request never combines old and new limits, scopes, or egress rules.
The module is a standalone, opt-in primitive: it does not change how the service reads its environment at startup, and existing deployments behave exactly as before until an operator wires a manager in.
Covered settings¶
A candidate document must declare every field below. Partial documents are reported as incomplete; they are never merged with the active generation or with defaults.
| Section | Field | Startup source | Validator reused |
|---|---|---|---|
limits | max_request_bytes | OPENMED_SERVICE_MAX_REQUEST_BYTES | OperationalLimits safe range |
limits | max_text_length | OPENMED_SERVICE_MAX_TEXT_LENGTH | parse_max_text_length (strict) |
limits | rate_limit_rps, rate_limit_burst | OPENMED_SERVICE_RATE_LIMIT_RPS, _BURST | runtime throttle parsers |
limits | max_concurrency | OPENMED_SERVICE_RATE_LIMIT_MAX_CONCURRENCY | runtime throttle parser |
limits | concurrency_wait_seconds | OPENMED_SERVICE_CONCURRENCY_WAIT_SECONDS | runtime throttle parser |
limits | throttle_key | OPENMED_SERVICE_THROTTLE_KEY | parse_service_throttle_key |
authorization | enabled, deny_by_default | OPENMED_SERVICE_AUTH_ENABLED, _DENY_BY_DEFAULT | strict booleans |
authorization | route_scopes | OPENMED_SERVICE_AUTH_ROUTE_SCOPES | parse_route_scopes (declared routes only) |
authorization | failure_rate_limit_rps, _burst, _key | OPENMED_SERVICE_AUTH_FAILURE_RATE_LIMIT_* | auth parsers |
egress | offline | OPENMED_OFFLINE | strict boolean |
egress | require_tls | none (defaults to true) | strict boolean |
egress | allowed_purposes | presence of a privacy-gateway or OTLP endpoint | closed purpose vocabulary |
The egress purpose vocabulary is fhir_bulk, openhim, privacy_gateway, remote_inference, smart_backend, trace_export, and webhook_callback. EgressPolicy.allows(purpose, tls=...) denies when offline, when the purpose is not allowed or unknown, and when TLS is required but absent.
Out of scope: TLS and mTLS material, API keys, JWKS, JWT issuer, audience and lifetime settings (verifier rotation), endpoints and headers, CORS origins and trusted hosts, and the service profile itself. Changing profile at runtime is rejected with profile_change_unsupported.
Bootstrap and reload¶
from openmed.service.policy_generations import (
PolicyGenerationManager,
policy_document_from_environment,
)
# Pass os.environ (the default) in a deployment; this mapping is synthetic.
environ = {
"OPENMED_PROFILE": "prod",
"OPENMED_SERVICE_AUTH_ENABLED": "true",
"OPENMED_SERVICE_RATE_LIMIT_MAX_CONCURRENCY": "8",
}
manager = PolicyGenerationManager(policy_document_from_environment(environ))
candidate = manager.active.settings.to_document()
candidate["limits"]["max_request_bytes"] = 2 * 1024 * 1024
result = manager.reload(candidate)
print(result.outcome, result.active_generation) # activated 2
policy_document_from_environment() reads only the variables listed above, through the same parsers the service uses at startup. Credentials, verifier keys, endpoint values, headers and certificate paths are never copied into the document; a configured endpoint only contributes its egress purpose. An unparsable variable raises PolicyGenerationError("environment_invalid") without echoing the value.
reload() is propose() followed by activate() under one lock. Calling them separately lets an operator inspect a candidate first; activation then fails with candidate_stale if another generation was activated in between. A candidate whose effective policy equals the active one returns unchanged and does not create a generation.
Validation as one unit¶
Every candidate is validated as a whole before activation:
- Structure: schema version, every section and field present, no unsupported keys.
- Field parsing with the existing startup validators listed above. Unlike the startup text-length parser, a reload never silently substitutes a default.
- Production posture for the
prodprofile: authentication enabled, deny-by-default kept, a failed-authentication rate limit, at least one admission budget (concurrency cap or rate limit), TLS required for egress, and non-empty scopes on every route that declares scopes by default. - Injected self-checks. Pass
self_checks=[...]to plug in a deployment self-check; each returns snake_case finding codes, and any finding blocks activation. A check that raises reportsself_check_failed; a free-text finding is replaced byself_check_finding_invalid.
A rejected candidate never changes the active generation, so a failed reload cannot weaken readiness. manager.readiness() stays ready: true and reports the last outcome and its finding codes.
Pinning in-flight work¶
body = b'{"text": "synthetic note"}'
with manager.pin() as pin:
within_limit = pin.settings.limits.allows_request_bytes(len(body))
may_forward = pin.settings.egress.allows("privacy_gateway", tls=True)
print(pin.generation.number, within_limit, may_forward) # 2 True False
Read every decision through pin.settings; the pin only changes binding inside checkpoint(), and then as a whole. PolicyGenerationMiddleware pins every HTTP and WebSocket connection, stores the pin in scope["state"] under openmed_policy_pin, and releases it after the application returns, including after the final chunk of a streaming response. readiness()["inflight"] reports pinned work per generation, which supports draining.
Emergency restrictive changes¶
manager.reload(document, emergency=True) is the tighten-only fast path. The candidate passes the same full validation and must also be no more permissive than the active generation in every dimension: lower or equal byte, length, rate, burst, concurrency and wait limits (a disabled gate counts as unlimited), authentication and deny-by-default not relaxed, route scopes as supersets, egress purposes as subsets, offline and TLS requirements not relaxed, and identical throttle keying. Otherwise it is rejected with emergency_not_restrictive.
Standard reloads affect new work only. Emergency reloads also reach pinned work at its next declared checkpoint, where pin.checkpoint() returns:
| Action | Code | When | What the work does |
|---|---|---|---|
continue | policy_pinned | No emergency since the work was pinned, or the pinned generation is already at least as strict as the active one | Keep using the pinned generation |
rebound | policy_rebound | The active generation is no more permissive than the pinned one | Continue under the active generation as a whole |
halt | policy_continuation_denied | Neither generation is uniformly stricter | Stop or checkpoint durably; the decision is sticky |
Rebinding never grants pinned work more than it was admitted with. Long-running work should call checkpoint() before each batch, chunk, retry, or outbound call.
Diagnostics¶
Reload results, readiness, history, generation summaries, and every repr contain only generation numbers, digests (sha256: over the canonical effective policy), injected-clock timestamps, counts, fixed finding codes, and field names from the fixed schema. They never contain environment values, endpoints, secrets, scope strings, route templates, or other policy text. Unknown keys are reported as field_unsupported without naming the key.
Finding codes: document_invalid, schema_version_unsupported, field_missing, field_unsupported, field_invalid, profile_invalid, route_scopes_invalid, egress_purpose_unsupported, auth_disabled, deny_by_default_disabled, auth_failure_limit_disabled, route_scope_missing, admission_unbounded, egress_tls_not_required, profile_change_unsupported, emergency_not_restrictive, candidate_stale, candidate_invalid, self_check_failed, and self_check_finding_invalid.
Validation¶
The tests use synthetic documents, an injected clock, and an in-process ASGI client. They cover rejected and incomplete candidates, the production posture rules, stale candidates, emergency continuation outcomes, a multi-threaded mixed-generation check, and sentinel leak scans.