ModelForge-Public/docs/operations/SECRET_LIFECYCLE.md

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.