The workflow library

Known-fix workflows are the tickets your queue sees every week, encoded once, done right every time. Each one runs Diagnose → Fix → Verify: the diagnosis is shown verbatim before anything changes, the fix is applied step by step, and a fresh diagnosis proves (or disproves) the result. Every run is recorded with the operator's identity.

Identity

MFA / auth method reset mfa-reset

The "lost phone" ticket. Diagnose lists the user's registered authentication methods and warns when no strong method exists. Remediate revokes all sign-in sessions and removes every deletable registered method, forcing clean MFA re-registration at next sign-in. The password method is never touched.

Password reset + session revoke password-reset

Sets a generated 16-character temporary password (must change at next sign-in) and revokes existing sessions so the old credential stops working everywhere. Diagnose flags directory-synced accounts as a Blocker - a cloud-side reset doesn't stick for those; reset on-premises or via SSPR writeback instead. The temporary password is shown to the operator exactly once and never lands in run history or notifications.

Compromised account lockdown compromised-lockdown

First-response containment for a suspected BEC. Diagnose shows sign-in state, MFA registration, and inbox rules that forward, redirect, or delete mail - the classic persistence trick. Remediate blocks sign-in, revokes every session, and disables the risky rules (disabled, not deleted, so they survive as evidence for the investigation).

License assignment repair license-repair

The license that "is assigned but doesn't work". Diagnose checks the usage location (the usual silent culprit) and finds stuck SKUs. Remediate sets the usage location and reprocesses the assignment.

Mailbox

Mailbox archive repair mailbox-archive

The "mailbox full / not archiving" fix that replaces a ~10-cmdlet Exchange Online dance. Diagnose shows the full archive posture: sizes against quotas, archive + auto-expand state, retention policy, and the two hidden blockers (retention hold, disabled ELC processing) that silently stop the Managed Folder Assistant. Remediate enables the archive and auto-expansion, ensures a retention policy, clears the blockers, and kicks the assistant. The actual item move runs asynchronously on Microsoft's side - re-running remediate doubles as the nudge, which this problem routinely needs.

Run history & notifications

The Workflows tab shows recent runs: when, which workflow, which tenant, which operator, and the outcome. The full findings and steps of every run persist in Postgres - ticket-ready evidence of what was checked and what was changed. Configure the Notifications section to push failed runs to a Teams incoming webhook (Adaptive Card) or any JSON receiver:

"Notifications": {
  "WebhookUrl": "https://...",   // empty disables
  "Format": "teams",             // or "json"
  "NotifyOnSuccess": false
}

Writing your own

Implement IWorkflow in the project that owns the API you're calling, register it in that project's Add*Workflows() extension, and it appears in the catalog, the UI, and run history automatically. Guidelines:

• Diagnose must be read-only and explain why (Warning findings carry the reason, not just the fact).
• Remediation steps are idempotent; re-running a workflow is always safe.
• Use WorkflowRunResult.Ephemeral for show-once secrets - it is excluded from persistence and notifications by construction.
• Cover it with WireMock tests; no live tenant needed.

See CONTRIBUTING.md for the full conventions.