docs(mfa): document the in-app MFA recovery endpoints in the OpenAPI spec

[geovannewashington]

What

Spec + a forced test fix. Updates the OpenAPI spec to match the cloud
backend changes for in-app MFA recovery, plus one frontend test fix the
spec change forces (the generated SDK is rebuilt from the spec at build
time, so the new token field breaks a stale test mock). No runtime
behaviour changes. Commits on this branch:

1. docs(mfa): document the in-app MFA reset token in the OpenAPI spec (team#87)
2. docs(mfa): document the emailed reset codes on disableMFA (team#88)
3. test(mfa): update mfaResetStore mocks for the new reset token type

Why

The backend gained a new response field and now accepts new request inputs.
Leaving the spec unchanged would let it lie about the API: generated clients
and contract tests would not know about the token response or the new
disable inputs.

Changes

reset flow

• POST /api/user/mfa/reset: the 200 response now documents the token
  body (marked required, since a success always returns it).
• PUT /api/user/mfa/reset/{user-id}: the user-id path param is
  documented as accepting either the opaque token (in-app flow) or the raw
  user ID (emailed-link flow), and the operation description reflects that.
  Also fixed an auto-generated POST -> PUT in the description.
  Build fix (SDK ripple)
• The console's generated SDK (src/client/, gitignored, rebuilt from the
  spec) now types requestResetMfa as returning { token }. Updated the
  mfaResetStore test mocks to match, keeping tsc -b green. Type-only;
  the store's actual re-wire to use the token stays in the frontend
  follow-up (see below)

disable flow

• PUT /api/user/mfa/disable: the mfaDisable request schema gains optional
  main_email_code / recovery_email_code fields, mirroring mfaReset.
  They are optional, not required: the endpoint takes one of a TOTP code, a
  recovery code, or the two email codes, so marking them required would
  misdescribe the other paths. The operation description lists the three
  options.

Testing

• Both edited files parse as valid YAML.
• Semantic OpenAPI lint (redocly/openapi toolchain) was not run locally, as
  it runs in a container rather than on the host. Worth running in CI or
  before merge if there is a spec-lint target.

Companion PR

shellhub-io/cloud#2430

The backend implementation lives in shellhub-io/cloud (branch
feat/mfa-inapp-reset-disable): the opaque reset token and the emailed-code
DisableMFA support this spec documents.

Follow-up

The frontend re-wire in shellhub/ui/ (restore the reset-verify page and
the disable-via-email-codes screen) is still required for these flows to be
usable in the product. Tracked with the backend PR.

Refs: shellhub-io/team#87
Refs: shellhub-io/team#88

[github-actions]

Claude finished @geovannewashington's task in 1m 43s —— View job

---

Code Review Complete

Reviewed 4 files across code quality, security, testing, language patterns, and architecture — no new issues found. The code looks good as-is.

I verified the spec against the cloud backend (cloud/internal/cloud/) and every documented claim matches the implementation:

• POST /api/user/mfa/reset — RequestResetMFA returns &responses.RequestResetMFA{Token: token} ({"token": ...}), always present on success, so documenting token as required in the 200 body is correct.
• PUT /api/user/mfa/reset/{user-id} — service.ResetMFA looks the user-id segment up as a cache token and falls back to a raw user ID on a miss, exactly as the new param/description describe.
• PUT /api/user/mfa/disable — requests.DisableMFA gained main_email_code / recovery_email_code with no validate:"required" tag, and service.DisableMFA treats them as a third alternative alongside TOTP and recovery codes — so keeping them optional in mfaDisable (unlike the required pair in mfaReset) is the right call. The "must be sent together" note matches validateResetMFACodes, which fails unless both are present and match.

All four YAML files are well-formed and internally consistent.

If you push additional changes and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[otavio]

/review

[github-actions]

Claude finished @otavio's task in 51s —— View job

---

Code Review Complete

Reviewed 5 files across code quality, security, testing, language patterns, and architecture — no new issues found. The code looks good as-is.

I verified the spec changes are well-formed and internally consistent, and cross-checked them against the frontend touched by this PR:

• mfaResetStore.test.ts — the new mockSdkResponse({ token: "reset-token" }) and SdkResponse<{ token: string }> mocks are type-only and match the store's actual behavior: requestMfaReset still keys off the identifier (not the returned token), so the assertions on mfaResetUserId/mfaResetIdentifier remain correct. The token-consuming re-wire is correctly left to the frontend follow-up.
• mfaDisable.yaml — main_email_code / recovery_email_code are kept optional (unlike the required pair in mfaReset), which correctly reflects that disable accepts TOTP, a recovery code, or the two email codes.
• reset paths — the token 200 body (required) and the user-id path param accepting either an opaque token or a raw user ID line up with the documented in-app / emailed-link flows.

All edited YAML files parse cleanly and no runtime behaviour changes.

If you push additional changes and want a new review, tag @shellhub-io/admin and a team member can trigger it.