# Reset forgotten password

**Flow key:** `password-reset`

## Outcome

An eligible user securely proves control, sets a new credential, and invalidates the intended old credentials without account enumeration.

## Actors

- User
- Identity service
- Email/SMS provider
- Risk controls

## Preconditions and entry points

- A controllable active account exists.
- Old and new synthetic credentials are known.
- Session invalidation policy is known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Identity | `carbon.reset+001@example.test` | unknown, locked, disabled, unverified, Unicode username |
| Reset proof | latest fresh reset link/code | expired, replayed, malformed, prior resend, wrong account |
| New password | valid distinct synthetic passphrase | same as old, weak, compromised, min/max, emoji/spaces |
| Sessions | current and second-device sessions | no session, API token, remembered device |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Open Forgot password and submit the account identity. | Response and timing follow the anti-enumeration policy. |
| 2 | Receive and open the latest reset proof. | Proof identifies the intended action and expires safely. |
| 3 | Follow the link or enter the code. | Proof binds to the right account and cannot be replayed. |
| 4 | Enter and confirm a valid new password. | Policy is visible; no trimming, normalization, or silent truncation occurs. |
| 5 | Submit once. | Credential changes atomically and the user receives a truthful security notification. |
| 6 | Attempt old/new credentials and existing sessions. | New credential works; old credential and intended sessions/tokens no longer work. |

## Alternate paths

- Reset while already signed in
- Admin-initiated reset
- Passwordless account adding a password
- Recovery-code path
- SSO-managed password path

## Failure and recovery paths

- Unknown identity leaks existence
- Old resend link remains valid
- Timeout after password commit
- Session invalidation only partly succeeds
- Notification fails after successful reset

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [password recovery and account recovery](../../items/identity/password-recovery-and-account-recovery.md)
- [password](../../items/controls/password.md)
- [session lifecycle](../../items/identity/session-lifecycle.md)
- [email and outbound message](../../items/content/email-and-outbound-message.md)

[Back to Identity and access flows](index.md)
