agents: let trigger rotate_secret revoke the outgoing webhook secret (MARSOHS-1078)

[sdharavath]

Summary

triggers.rotate_secret() can only ask for the default rotation, and its docstring says the old secret "stays valid briefly" — which is exactly the unactionable wording MARSOHS-1078 was filed about. Someone responding to a leaked secret can neither kill the old value nor tell from the response whether it is already dead.

This adds revoke_previous to the sync and async clients. The default is unchanged.

# routine rotation: grace window, unchanged behaviour
resp = client.agents.triggers.rotate_secret("trig-abc123")
resp.previous_secret_expires_at   # when the old secret stops verifying

# breach response: retire the outgoing secret on this call
resp = client.agents.triggers.rotate_secret("trig-abc123", revoke_previous=True)
resp.previous_secret_revoked      # True; no expiry is reported

Why grace is still the default: the provider side holds one secret at a time (a GitHub webhook has a single Secret field), so it keeps signing with the old value until a human pastes the new one in. Revoking on every rotate would turn routine rotation into a delivery outage lasting as long as that handoff. revoke_previous=True accepts that gap deliberately, because a leaked secret is the worse risk.

The response now always states the outcome — exactly one of previous_secret_expires_at and previous_secret_revoked is present, so a caller never infers it from a missing field. The docstrings were rewritten to say so.

Notes for review

• Purely additive: revoke_previous is keyword-only and defaults to False.
• No Autorest regen. This is the hand-authored custom_triggers.py surface, so nothing here depends on an openapi publish — unlike Point pydo at Hosted Agents Origin openapi tip (MARSOHS-551) #699 / Document Agent Configs openapi dependency (MARSOHS-741) #708, there is no DO_OPENAPI_COMMIT_SHA.txt bump to wait on.
• The shared _send helper already drops None params, so the default rotate puts no query parameter on the wire at all. Both suites assert that rather than only asserting the revoke case.
• Based on OHS_endpoints, matching Document Agent Configs openapi dependency (MARSOHS-741) #708 — so Integrate Harness APIs #680 picks this up when it carries the branch to main.

Related

• Server side: digitalocean/cthulhu#172453 (harness-trigger — ?revoke_previous=true, plus a cleaner sweep that nulls the expired ciphertext once the window closes).
• godo: hosted agents: let rotate-secret revoke the outgoing webhook secret (MARSOHS-1078) godo#1092 (same change, also on OHS_endpoints).
• doctl: agents: add --revoke-previous to triggers rotate-secret doctl#1922 (doctl agents triggers rotate-secret --revoke-previous).

Test plan

• pytest tests/agents/ — 127 passed, 1 skipped (pre-existing)
• New: test_rotate_secret_revoke_previous and test_async_rotate_secret_revoke_previous assert revoke_previous=true reaches the wire and the revoked flag parses
• Existing test_rotate_secret extended to assert the default sends no revoke_previous and parses the expiry
• black --check clean

Made with Cursor

[sdharavath]

@SSharma-10 review request when you have time — pydo half of MARSOHS-1078 (P1, webhook secret rotation).

Touches only the hand-authored triggers modules: rotate_secret gains a keyword-only revoke_previous=False, sync and async, with the docstring explaining that the response carries either previous_secret_expires_at or previous_secret_revoked and never both. Nothing generated changes.

I can't add reviewers on this repo, so mentioning instead.

[SSharma-10]

LGTM