fix(credentials): a malformed credential archive is a 400 and an unstorable secret value is a named 422 (#3325)

[vybe]

Fixes #3325 — independent fix, one of ten small bug fixes in the trinity-pm chain-easy-1008 run. Base is dev. Draft until the operator merges.

What

• src/backend/services/credential_encryption.py::decrypt: every malformed envelope shape raises ValueError, as the function promises — JSON that is not an object ([], null), and a non-string nonce or ciphertext. Importing such a .credentials.enc now returns 400 instead of a 500 with a stack trace in the log. The envelope format and every successful decrypt are unchanged.
• src/backend/services/secret_settings.py::encrypt_secret_setting: the key is checked first, in its own try, and only that check can raise MissingEncryptionKeyError. A value that cannot be encoded (for example a lone surrogate) raises the new SecretSettingValueError(ValueError). Its message names the setting, never the value.
• src/backend/error_handlers.py + src/backend/main.py: one app-level handler maps SecretSettingValueError to 422. src/backend/routers/settings/credentials.py: three pass-through lines in the routes whose catch-all would have turned it into a 500 (Anthropic, GitHub PAT, PUT /slack).
• Tests: the three strict-xfail markers in test_ec_credential_crypto_edges.py are removed; new tests/unit/test_3325_credential_error_types.py (registered in tests/registry.json) asserts no value in the message or the exception chain, a missing key reported before a bad value, PUT /api/settings/api-keys/anthropic → 422, and that main.py registers the handler.

Rulings carried (orchestrator, on the operator's behalf — plan file)

• TD-1: one app-level handler plus the three pass-through lines — as recommended.
• TD-2: a .credentials.enc that decrypts correctly but whose contents are not an object is deferred — as recommended; forging one needs the platform key.
• TD-3: 422, matching the existing 422 for refused cleartext writes — as recommended.

Review + security

/review reading pass (claude-fable-5-1, report-only): MERGEABLE, no critical findings. The secret cannot leave through the new error: it is raised after the except block, so __context__ is cleared, not merely hidden; the handler returns only the message; nothing logs it; audit rows are written only after a successful write. The only residual carrier is traceback frame locals, which nothing in the backend renders. The handler is keyed on the subclass, so no other ValueError is swallowed or relabelled. /cso --diff: no findings.

Evidence sweep (claude-opus-5-5): GREEN. 23 unit files import the touched modules; the 16 most direct ran shuffled (seed 12345), one file per process, all passed. All 7 tests in the new file ran, 0 skipped. With both service files taken from dev, exactly the three formerly-xfail tests fail (8 cases). Seven less direct files are left to CI and named in the review file. git merge-tree against dev f6bedcd is clean.

Tests

Targeted counts above. Not run here: the full unit island (CI).

Before merge

• Startup auto-import (lifecycle.py) on a malformed envelope now lands in its ValueError retry arm: it retries without a warning per attempt and ends in the same "failed" result, with the existing error log after the last attempt.
• Enterprise callers of decrypt get ValueError where they got AttributeError / TypeError on a malformed envelope. Two catch broadly, three propagate as before; no change needed there.
• The new test file has a module-level importorskip for sqlalchemy and cryptography: it skips silently where those are missing. They are present on the engineer and in CI.
• Ten open PRs share tests/registry.json or src/backend/main.py with this branch (feat(skills): one Skills tab — own and shared skills, Run, Requires approval (abilityai/trinity-enterprise#754) #3412, fix(public-links): an expired visitor session asks for the email again, never the operator /login (#3406) #3411, feat(workspace): the role card's objectives in plain words — owned first, supported folded, no metric code names (abilityai/trinity-enterprise#843) #3407, fix(files): credential files are owner-tier to read; file reads never follow a link; runtime config files join the write deny lists #3304, feat(access): who an agent serves, its seat, and what reads it (abilityai/trinity-enterprise#810–#814, #817) #3271, feat(operator-queue): an agent sees its pending asks and can replace one (#3247) #3256, feat(workspace): the autonomy dial — what a companion may do unprompted (ent#641) #2984, feat(a2a): AAuth agent identity across instances, behind an off-by-default flag (abilityai/trinity-enterprise#623) #2956, feat(workspace): a stage advance reaches the Work card on the write, not the next poll (ent#533) #2713, feat(workspace): the rail's Canvas/Files dot lights on the write, not the next refetch (ent#532) #2709). A test-merge of this head against each adds no conflict beyond what that PR already has with dev.

Handoffs (not in this diff)

• TD-2 above: the decrypted-but-not-an-object case can still 500 on import.
• PUT /api/settings/slack saves the client ID before a later secret write fails (partial update, pre-existing).
• The GitHub PAT, Resend and Gemini routes are covered by the app-level handler but not exercised by the new route test.

🤖 Generated with Claude Code

[trinity-ability]

merge-train: batch validated on train/20261009-0735 (#3424)