Secrets at rest error codes (mpbx-secrets)
Raised by the keyring that encrypts stored third-party secrets and by
mpbx init --rotate master-key (W1-PBX-09). Messages never contain a secret, a key or a
ciphertext; they name data key ids and master key ids (MPBX_MASTER_KEY_ID fingerprints) at most.
Guide: secrets at rest.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-SECRETS-WRONG-MASTER-KEY | config | The master key given to the process (or held by a sink during a rotation) is not the key this database's secrets are encrypted with. Raised at startup by Keyring::open, so a regenerated key never orphans existing secrets. | Restore the original MPBX_MASTER_KEY and MPBX_MASTER_KEY_ID from the secrets backup or the recovery key. Never replace the key with a new one by hand; rotate with mpbx init --rotate master-key. |
MPBX-SECRETS-MASTER-KEY-ROTATED | config | The process still runs with the previous master key after a rotation finished, and needs a data key it had not cached; or a data key was offered for storage wrapped with a key that is not the current one. | Restart the process with the current install secrets. |
MPBX-SECRETS-ROTATION-PENDING | conflict | A master key rotation is between its two database steps: storing the first secret of a company (a new data key) is refused until it finishes. Also raised when a rotation is started while another is pending. Retryable. | Wait for the rotation, or run mpbx init --rotate master-key again with the same sinks to finish it. |
MPBX-SECRETS-KEYRING-UNINITIALISED | config | A data key was written before the keyring recorded the master key (secret_master_key is empty), or a rotation was finished on a database where none was started. | Open the keyring (Keyring::open) at startup before storing secrets. |
MPBX-SECRETS-DECRYPT-FAILED | internal | Authenticated decryption failed: the value was moved to another row, column or company, was modified, or a data key does not open with the master key. Nothing is returned. | Treat it as tampering or corruption: restore the row from a backup. If every secret fails, the master key is wrong (see above). |
MPBX-SECRETS-KEY-NOT-FOUND | internal | The ciphertext names a data key that does not exist in the requested scope: another company's secret presented under this one, an install-wide secret presented under a company (or the reverse). | Check the row's company and whether the secret is install-wide (Scope::System); restore from a backup if the data key row was deleted. |
MPBX-SECRETS-SCOPE-MISMATCH | permission_denied | The data key exists in the requested scope but belongs to another key family (purpose) than the scope opens, for example a media key presented as a configuration secret. Refused before any decryption. | A bug in the caller: use the scope and purpose the secret was sealed with. |
MPBX-SECRETS-CIPHERTEXT-INVALID | internal | A stored value is truncated, has an unknown format version (including 0x01, the W1-PBX-09 format without owner and purpose binding), or a wrapped data key has the wrong length. | Restore the row from a backup. |
MPBX-SECRETS-CONTEXT-INVALID | invalid_argument | A field name is not <table>.<column> in lowercase (a programming error). | Use a name from mpbx_secrets::context::fields. |
MPBX-SECRETS-SCHEMA-OUTDATED | config | mpbx init --rotate master-key found pending database migrations. | Start this release once (it applies the migrations), then rotate. |
MPBX-SECRETS-INVALID | config | MPBX_MASTER_KEY is not base64url of 32 bytes or does not match MPBX_MASTER_KEY_ID (same code as in mpbx init). Also raised when a rotation would reuse the current key. | Restore the original pair from a backup. |
MPBX-SECRETS-RNG | internal | The OS random number generator failed (same code as in mpbx init). | Check the host and retry. |
Codes shared with mpbx init that --rotate master-key also raises: MPBX-SECRETS-MISSING (a
sink does not exist or lacks the master key), MPBX-SECRETS-CONFLICT (a sink holds an unexpected
value, sinks disagree, a Kubernetes 409 during the update, or --recovery-key-file exists),
MPBX-SECRETS-SINK (I/O or API failure; for Kubernetes a 403 names the update permission the
rotation needs) and MPBX-RECOVERY-NOT-CONFIRMED. See installer errors.