Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0

docs/operations/SECRET_LIFECYCLE.md

@@ -0,0 +1,57 @@
+# Platform secret lifecycle
+
+Implementation qualification in progress. This procedure describes the P01 control-plane
+Hugging Face slot; it does not certify live provider access or download-node credentials.
+
+## Boundaries
+
+The managed slot supplies Hugging Face authentication for control-plane discovery and repository
+metadata. A successful test confirms that the provider accepts that exact candidate credential;
+it does not establish a repository licence, gated-model approval, artifact safety or node download
+readiness. Download nodes retain their separate deployment-managed credential.
+
+Database bootstrap, migration access, deployment administrator recovery credentials and backup
+encryption remain outside the managed slot. Their metadata must show external ownership and
+unknown versions or test state truthfully. Do not put the root key or bootstrap credentials into
+the slot they would protect.
+
+## Operator workflow
+
+1. Provision and retain the separate encryption root key outside database backups, using the
+   documented deployment settings. Keep its identifier stable for the ciphertext it protects.
+   `MODELFORGE_SECRET_SLOT_ROOT_KEY` contains a base64-encoded random 32-byte AES key;
+   `MODELFORGE_SECRET_SLOT_ROOT_KEY_ID` identifies it. Recreate the API after changing these
+   deployment settings. Historical ciphertext still needs its original key and identifier.
+2. As an administrator, enter the Hugging Face token and an audit reason. Review the current
+   revision. Saving creates an encrypted candidate; it does not replace the active credential.
+   The first save opts into managed mode immediately: metadata/discovery access is blocked until
+   that candidate is tested and activated. Plan that initial switch as a short maintenance action.
+3. Test that candidate. A rejected token, provider outage or stale candidate blocks activation
+   and leaves the existing active credential intact. Review the recorded result and time.
+4. Explicitly activate the successfully tested version. New control-plane requests resolve that
+   version; already-started requests may retain their credential snapshot.
+   The successful test must be less than five minutes old and refer to the latest candidate.
+5. To rotate, repeat candidate creation, testing and activation with the replacement token.
+   Confirm ordinary discovery/metadata access before revoking the old token at the provider.
+6. To disable use, explicitly revoke the managed slot. ModelForge must not silently fall back
+   to a deployment token. Provider-side token revocation is a separate action.
+
+The token cannot be read back. Configuration export contains only the slot reference, never
+ciphertext, plaintext or the root key. Never include tokens in reasons, logs, tickets or reports.
+Use the Console's lock action when finished; token input must be cleared after submission and
+when leaving the workflow.
+
+## Failure and recovery
+
+Missing encryption material, a wrong key or invalid ciphertext makes a managed credential
+unavailable. Restore the externally retained matching root key through the deployment process;
+do not replace it with an unrelated key merely to make startup appear healthy.
+
+A supported database restore preserves encrypted history but invalidates prior test and activation
+evidence. Keep the restored environment isolated. An administrator must test and explicitly
+activate the intended version again. Old provider credentials may already have expired or been
+revoked; database rollback cannot undo that external state. A raw database restore is not proof
+that a secret is safe to reactivate.
+
+Final RC evidence must include live provider qualification and safe root-key provisioning on the
+isolated RC host. Node credential activation and gated downloads require their own evidence.