Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0

docs/operations/OPERATOR_ACCESS.md

@@ -0,0 +1,108 @@
+# Operator access
+
+Use a separate personal key for each human. Viewer reads protected evidence; operator can additionally
+perform permitted operational actions and previews; administrator controls configuration apply,
+credentials, destructive lifecycle and recovery. The API enforces every route's declared role.
+Project `mfsvc_`, node `mfnode_` and enrollment keys never unlock the Console.
+
+## Deployment-owned personal identities
+
+In a private local terminal run:
+
+```sh
+python scripts/operator_identity.py --subject alice --role viewer --days 30
+```
+
+Save `one_time_key` in your password manager and give it only to that person through your approved
+private channel. Add **only** `deployment_record` to the JSON array in `MODELFORGE_OPERATOR_IDENTITIES`.
+The array must contain 1–100 records. A `.env` assignment uses single quotes around the JSON array.
+Never put the complete command output in `.env`, Git, a ticket, an export or a release artifact.
+The stored record contains a credential ID, subject, role, digest and timezone-aware expiry; it does
+not contain the usable key. Configuration reads redact the entire registry.
+
+Apply the deployment setting using the normal controlled API recreation procedure. On the next
+request the API uses the new registry. Enter the personal key in the Console's Operator API key
+field. Verify the displayed subject and role before acting. `GET /api/v1/operator/identity`, with
+`X-ModelForge-Admin-Token` supplied from your private credential store, provides the same information.
+There is no API for reading a key back.
+
+## Deployment-owned rotation, revocation and recovery
+
+Generate a replacement record with the same subject and role and a new credential ID. Add it alongside
+the old record, recreate the API, and verify the replacement login and role. Remove the old record
+and recreate the API again to end the overlap. The old key then receives 401. To revoke immediately,
+remove the record and recreate the API without an overlap. Record the subject, credential IDs,
+approver, reason and application time in the private deployment change record; never record keys.
+These deployment operations do not currently produce online identity-lifecycle audit events.
+
+Changes require recreation, not just editing the host environment. In-flight operations already
+authorized may finish. The expiry itself is checked on every request without a restart. Retain an
+independent administrator or controlled recovery credential during rotation. Conflicting roles for
+one subject are rejected; change every overlapping record together when changing a role.
+
+The legacy `MODELFORGE_OPERATOR_API_KEY` remains the `legacy-operator` administrator. Once a personal
+administrator is proven, clear that setting and recreate the API to disable shared access. Production
+startup refuses an installation without either a valid bootstrap key or an unexpired named admin.
+Keep recovery material outside the database backup and protect it according to your deployment policy.
+Managed database identities do not replace this independent startup/recovery requirement.
+
+## Managed personal identities
+
+The RC personal-key provider also supports online identity administration. An administrator can
+list identity metadata, create a managed identity, rotate its key, change its role or enabled state,
+and revoke its credentials. Deployment-owned entries remain read-only in this interface. Managed
+subjects use `managed:<slug>` and keys use the distinct `mfopm_` namespace. Existing `mfop_`
+deployment keys retain their authentication and recreation behavior.
+
+Create the first managed identity as an administrator. Choose the minimum necessary role and a
+key lifetime of 1–365 days. Issuance returns the key once; save it in an approved private credential
+store before leaving the page. A lost response cannot be recovered from the database: rotate to
+issue another key. Only a digest is persisted. Never paste the issuance response into a ticket,
+audit reason, repository, configuration export or diagnostic bundle.
+
+Rotation accepts an overlap of 0–900 seconds. Verify the replacement key promptly; zero overlap
+invalidates the predecessor immediately. Revocation requires the exact canonical subject and a
+reason. These mutations use the displayed version, recheck administrator authority, and record an
+attributed audit event in the same transaction. A stale version requires refresh and a new review.
+Once initialized, administration cannot remove the last currently usable managed administrator.
+Expiry can still exhaust access later; maintain the independent deployment recovery authority.
+
+The Console requires at least 120 seconds of overlap when rotating your own key, and at least
+120 seconds remaining before both the current key expiry and local Console lock. Re-unlock first
+if the local deadline is too close; use another administrator or the recovery authority when the
+key itself is near expiry. The replacement is displayed for 60 seconds without a follow-up read
+that could invalidate the issuance response. Save it, then lock and unlock with the replacement
+before the overlap ends. Navigation, form changes and locking clear the displayed key.
+
+The metadata endpoint is `GET /api/v1/operator/managed-identities`. Creation uses POST to that
+collection; rotation and revocation use POST to `/{slug}/rotate` and `/{slug}/revoke`, and role or
+enabled-state changes use PATCH to `/{slug}`. All require administrator authority. Keys never appear
+in metadata, and a managed-key lookup failure cannot fall back to the deployment administrator.
+
+## Managed keys after database recovery
+
+Supported recovery restores the authoritative identity and credential history, then clears managed
+credential activations during reconciliation. Validation independently checks that these current
+activation rows are absent. A restored key is therefore quarantined even if the backup predates
+its later revocation. Do not reopen access to a raw `pg_restore` result: use the complete isolated
+ModelForge recovery workflow and its validation gate.
+
+After validated recovery, authenticate using the independent deployment administrator and issue a
+fresh managed administrator key by rotation or creation. Verify that new key before resuming
+ordinary identity administration. Restored keys remain unusable; preserving their metadata is not
+permission to reactivate them. Keep the restored environment isolated until these checks complete.
+
+## Console locking and limitations
+
+The Console displays identity, role, key expiry and its local lock time. It locks at the earlier of
+fifteen minutes after unlock or key expiry. Lock console and reload both clear the memory-only key.
+Public liveness and version remain visible while locked. A 403 keeps the session and reports a
+forbidden operation; a database/service outage also keeps the key. A 401 clears it. No credential is
+stored in cookies, localStorage, sessionStorage or a URL, and protected API responses are not cached.
+
+The local lock is not a server-issued session or key revocation: a copied key remains usable until
+its expiry or removal. OIDC/Authentik and SSO logout are not implemented; personal header keys are
+the explicitly supported RC provider. Deployment-secret lifecycle is a separate feature.
+Use HTTPS outside an explicitly trusted private lab, and protect the deployment
+registry so an untrusted user cannot replace roles or credential digests. The full RC authentication
+and secret-lifecycle acceptance remains open until those documented decisions and journeys close.