Accounts and identity UX implementation plan¶
Status: implementation handoff specification
Date: 2026-08-21
Audience: product/design implementers and coding agents working on feat/accounts-identity-foundation
Lifecycle: active implementation contract where the roadmap still schedules the work. Check the platform roadmap before treating an unchecked step as current priority.
This document is the player-facing and implementation handoff companion to Accounts and subscriptions plan. That document remains authoritative for the overall identity, BFF trust-boundary, storage, and billing architecture. This document is authoritative for account UI, user journeys, state transitions, recovery behavior, errors, undo semantics, and the order in which those experiences should be implemented.
The Engagement platform plan remains authoritative for the broader product principles: anonymous play remains available, account prompts appear only at natural value moments, groups are the social boundary, and the puzzle remains the quietest screen.
This document deliberately refines two earlier implementation sketches: the OIDC callback now uses the non-mutating prepare/pause/commit seam in section 6.2.1 whenever player choice is required, and account deletion retains only legally required pseudonymized financial/audit records rather than promising indiscriminate deletion from Stripe or other processors. If older plan wording conflicts on those two points, this document controls the implementation handoff.
The duplicate-play and concurrent-merge algorithms in section 7 mirror section 3a of
doc/accounts-and-subscriptions-plan.md. Treat them as one locked cross-document contract and
update both documents together if a future game requires different logical-play semantics.
1. Locked product decisions¶
The following decisions are settled for the first account release.
- Playing without an account remains a complete supported mode. First visit never begins with an account wall.
- A Verbolus account owns the player's canonical profile, plays, statistics, streaks, groups, preferences, and future entitlements.
- A Verbolus account can have multiple sign-in methods from its first release.
- The intended sign-in methods are:
- email address and password through Microsoft Entra External ID;
- Google Account;
- personal Microsoft account (MSA: Outlook.com, Hotmail, Xbox, and personal Microsoft 365);
- Facebook is optional and must remain disabled in the hosted user flow until approved.
- “Continue with Microsoft” means personal Microsoft accounts. A connection to one organization's workforce Entra tenant must not be substituted or labeled as generic Microsoft sign-in.
- The local method is called email and password in user-facing copy. Do not call it username and password unless Verbolus later deliberately adopts Entra's username/alias preview feature.
- Microsoft Entra External ID owns credential entry, email verification, password creation, password reset, provider consent, and provider authentication. Verbolus never receives or logs a password or social-provider token.
- The hosted authentication page is branded “Verbolus.” There is no duplicate Verbolus-built provider chooser. A Verbolus CTA redirects to the single Entra-hosted flow.
- The player's display name is a Verbolus nickname shown in groups and leaderboards. It is separate from the login email and from any provider's profile name.
- An existing cookie-only profile is never silently discarded or silently merged. The player sees a summary and chooses whether to keep its progress, start fresh, or cancel.
- Identity methods are never auto-linked merely because two providers return the same email address. Linking requires a currently authenticated Verbolus account and successful proof of control of the new method.
- Social providers are authentication only. Request only the minimal OIDC scopes needed for authentication. Do not import contacts, Facebook friends, profile posts, or Google People data. Result sharing continues through the existing explicit native share/copy actions.
- Signing out signs out of Verbolus on the current device. It does not unexpectedly sign the user out of Google, Microsoft, or Facebook.
- Switching accounts is distinct from signing out and distinct from merging accounts.
- The one-time Stripe tip does not require an account and never grants an entitlement. A future recurring Supporter subscription requires a verified account and recent authentication.
2. Terminology and identity model¶
Use these terms consistently in code, contracts, telemetry, tests, and user-facing documentation.
| Term | Meaning | Player-facing wording |
|---|---|---|
| Guest profile | The existing cookie-only player record on one browser/install | “Progress on this device” |
| Verbolus account | The durable canonical player identity | “Your Verbolus account” |
| Sign-in method | One verified external identity attached to an account | “Email and password,” “Google,” “Microsoft,” or “Facebook” |
playerId |
Stable canonical account/profile identifier | Never display it |
installationId |
Stable identifier for one browser/PWA installation | Normally never display it |
| External identity | Stable OIDC issuer + subject (and provider metadata) |
Display only the friendly provider name and masked identifier |
| Session | The current device's verified access to a Verbolus account | “Signed in on this device” |
| Guest import | Attaching a guest profile's data to an account | “Keep this device's progress” |
| Account merge | Combining two independently established Verbolus accounts | “Combine accounts” |
One provider identity maps to exactly one canonical playerId. One playerId may have many provider
identities. Provider email is metadata, not the account key and not proof that two identities belong
to the same person.
3. Account states¶
Model these states explicitly. Do not infer them from whether a display name or email happens to be present.
| State | Meaning | Allowed experience |
|---|---|---|
guest |
Valid signed anonymous cookie; no verified identity | Full ordinary play, local progress, account prompts at value moments |
authenticating |
OIDC transaction has started | Return/cancel safely; do not change player identity yet |
needs-account-decision |
OIDC succeeded; guest data and target account disposition await choice | Only the completion/merge flow and safe cancellation |
merge-pending |
A confirmed idempotent import/merge operation is running or awaiting reconciliation | Show progress and retry status; source and target remain protected |
verified |
Valid account session | Cross-device data, sign-in-method management, future billing |
reauth-required |
Account session is valid, but the requested sensitive action needs fresh proof | Preserve form/context and launch step-up authentication |
session-expired |
This installation previously used an account, but verified session expired | Prompt to sign in again; do not silently present an empty new profile as the account |
deletion-scheduled |
Renewal is canceled and account deletion awaits its effective date | Read-only warning, cancel-deletion action, export, sign out |
deletion-running |
Destructive deletion job has crossed its irreversible checkpoint | Status only; do not claim completion until reconciliation succeeds |
deleted |
Player data and identity mappings are removed/anonymized as specified | A later sign-up creates a new empty account; old progress is not restored |
Transitions must be server-authoritative and idempotent. Browser query parameters and local storage may choose presentation but never establish authentication, merge completion, or entitlement.
4. Navigation and screens¶
4.1 Header and menu¶
Preserve the existing compact header. Do not add a permanent avatar or account button.
In the hamburger menu:
- guest: retain
Settings; optionally add a quiet secondary line or menu item,Create account or sign in, only after the account feature is released; - verified: label the destination
Account & settings, with a non-sensitive secondary line such asSigned in as Mayawhen a display name exists; - never display an email address in the closed menu or on a signed-out screen, because devices can be shared.
4.2 Settings information architecture¶
Evolve /settings from the current long form into a small index. The initial implementation may
keep sections on one page if routes would delay delivery, but contracts and components should
support these focused destinations:
Settings
Profile Display name
Appearance Theme
Account Status and sign-in methods
Privacy and data Consent, export, deletion
Membership Supporter status, when available
Notifications Later
4.3 Guest Account screen¶
Account
You're playing without an account.
Your progress is saved in this browser. Create an account to keep your streaks,
groups, and settings if you change devices.
[ Create account or sign in ]
You can keep playing without an account.
Do not use fear copy such as “Your progress is at risk” or imply that ordinary guest play is temporary. Explain the real limitation: clearing browser data, changing browsers, or losing the device can make a guest profile inaccessible.
4.4 Verified Account screen¶
Account
Signed in as Maya
Your progress is saved to your Verbolus account.
Sign-in methods
Google ma•••@gmail.com Connected
Microsoft Not connected [ Add ]
Email and password Not connected [ Add ]
Facebook Not connected [ Add ] (only when enabled)
[ Switch account ]
[ Sign out of this device ]
Danger zone
[ Delete Verbolus account ]
Each connected method has a stable opaque method ID, friendly provider, masked identifier when available, link date, and whether it may be removed. Do not send raw issuer/subject values to a client component unless a server-only route needs them.
4.5 Entra-hosted screen¶
Use one hosted screen for sign-up and sign-in:
Verbolus
Email address
[ ]
No account? Create one
[ Next ]
---------------- or ----------------
[ Continue with Google ]
[ Continue with Microsoft ]
[ Continue with Facebook ] (optional)
Use the actual provider brand assets and follow their branding requirements. Keep supporting text
short: Sign in to save your progress across devices. Privacy and Terms links must point to current
Verbolus pages.
5. Account entry points and prompt frequency¶
Always provide Account from Settings. Additionally show a dismissible contextual prompt only at a natural pause:
| Trigger | Copy direction | Primary action |
|---|---|---|
| A meaningful Daily streak | “Keep your 7-day streak across devices.” | Save my progress |
| Immediately after creating or joining a group | “Keep this group if you change phones.” | Create account or sign in |
| Future supporter checkout | “A Verbolus account keeps supporter benefits available on your devices.” | Sign in to continue |
| Future cross-device notifications | “Sign in to receive this event on your devices.” | Sign in |
Rules:
- never prompt on the first page load;
- never prompt over an active puzzle board;
- never show more than one account prompt in one session;
- dismissal suppresses that prompt reason for 30 days on the installation;
- a materially different value moment may prompt later;
- Settings remains available regardless of suppression;
- track prompt reason and outcome without email, name, issuer, subject, or provider account ID.
6. End-to-end user workflows¶
6.1 First visit and continued guest play¶
- The proxy creates or preserves the signed anonymous player cookie.
- The player chooses a game and plays without registration.
- Plays, scorecard, streaks, settings, and groups continue to attach to the guest
playerId. - Settings describes the state as
Playing without an account. - Clearing the cookie is not treated as deletion. The privacy UI explains that deletion must be requested before clearing inaccessible browser state.
- A later contextual prompt may start account creation; ignoring it changes nothing.
Acceptance outcome: no account component, Entra request, or auth JavaScript blocks or delays first play.
6.2 Start sign-up or sign-in from a guest profile¶
- The player selects
Create account or sign in. - The BFF creates an authorization transaction containing:
- random transaction/operation ID;
- current guest
playerId, resolved from the signed cookie; - installation ID;
- validated same-origin return path and prompt reason;
- PKCE verifier/challenge, state, nonce, creation time, and expiry;
- no raw credential or provider token in browser-readable storage.
- The BFF redirects to the single Entra user flow.
- The player uses email/password or a provider.
- Cancellation, back navigation, or denial returns to the originating safe route with a neutral
Sign-in canceled. Your device progress is unchanged.message. - On callback, the BFF validates code, state, nonce, issuer, audience, timestamps, and PKCE before trusting any claim.
- Tokens remain server-side. The BFF resolves the external identity through the internal backend trust boundary.
- The BFF does not replace the guest cookie or issue a verified session until the account decision reaches a safe checkpoint.
6.2.1 Required callback-to-completion handoff¶
This is a required design and implementation boundary, not merely a UI detail. The OIDC callback finishes identity authentication, but sign-in is not necessarily complete. When meaningful guest data could be promoted, deferred, or merged, the player must decide what happens before Verbolus issues a verified account session.
Use this sequence:
Entra callback
|
| validate code + PKCE + state + nonce + token
v
Prepare sign-in (server-side, no mutation of player ownership)
|
+-- no decision needed --> Commit automatically --> mint verified cookie
|
+-- decision needed ----> /account/finish --> player chooses
|
v
Commit chosen operation
|
v
mint verified cookie
Prepare¶
- The callback validates the OIDC result completely. At this point Verbolus knows that the user controls an external identity, but the browser still has its original guest/account session.
- The BFF sends the verified identity to a new non-destructive internal operation such as
POST /v1/internal/identity/prepare, authenticated through the completed BFF app-role boundary and forwarding the original browser cookie. prepareresolves:- current source
playerIdfrom the forwarded signed cookie; - external identity owner, if any;
- whether the source contains meaningful data;
- whether this is a same-account sign-in, new-account promotion, existing-account sign-in, guest import, or sign-in-method collision;
- a fresh preview of plays, streaks, groups, settings, and display-name conflict.
preparemust not call the current mutatinglinkormergeoperation. In particular, the existing/linkendpoint links a previously unowned identity immediately and therefore cannot be the callback's first call whenKeep this progressversusStart freshis still undecided. Wrap/extend the current foundation with prepare/commit semantics rather than weakening the UX.- The backend stores a short-lived pending sign-in attempt containing the verified identity, source/target references, mode, preview version, Entra-supplied Display Name candidate, safe return path reference, creation/expiry, and idempotency key. Raw provider tokens are not stored.
- Return an opaque attempt ID and one disposition:
complete-same-account;complete-no-guest-data;choose-new-account-progress(Keep this progress/Start fresh/Cancel);choose-existing-account-import(Add this device's progress/Use account only/Cancel);choose-account-mergefor a link-method collision;blockedfor a security, billing, or unreconciled-account conflict.- Do not return source/target player IDs, issuer, or subject to browser components. The opaque attempt ID is not sufficient authorization by itself.
Pause¶
- If no decision is needed, the callback may immediately call commit and finish sign-in.
- If a decision is needed, set a short-lived
Secure,HttpOnly, intentional-SameSitepending cookie bound to the attempt and installation, then redirect to/account/finishwith at most an opaque attempt reference. - Keep the original signed guest cookie unchanged. Do not set
authLevel=verified, expose account data through ordinary endpoints, or redirect to the requested paid/account action yet. /account/finishloads its current preview server-side. Browser code receives only the counts, labels, choices, and conflict data needed to render the screen.- A second tab may keep playing while the decision screen is open. Commit must therefore re-read
source state and either incorporate later safe changes or return
preview-changedand require a refreshed confirmation; it must not silently act on a stale destructive preview. - Pending attempts expire after a short fixed window (initial recommendation: 10 minutes). Expiry leaves the original guest/session cookie and all player data unchanged. The player restarts authentication; callbacks and attempts are one-time-use.
Commit¶
- The finish screen posts one explicit decision and the opaque attempt reference to a BFF action.
The BFF combines the pending cookie, original browser cookie, CSRF proof, and app-role credential
when calling a new internal operation such as
POST /v1/internal/identity/commit. - The backend verifies that the attempt is unexpired, unused, bound to the same source player and installation, and compatible with the requested decision.
- The backend records the durable operation before changing ownership, identity mappings, aliases, groups, or settings.
keeppromotes or merges;start-freshcreates/uses the clean target plus a deferred-import record;use-account-onlysigns into the existing target plus a deferred-import record; account-merge follows the separately confirmed account rules.- Repeating commit with the same attempt/decision returns the same result. A conflicting second decision is rejected.
- Commit returns only after the canonical account and external-identity mapping have reached the documented safe checkpoint. Non-critical reconciliation may continue durably, with status shown to the player.
- Only now does the BFF mint/rotate the signed verified cookie for the canonical
playerId, clear the pending cookie, invalidate the attempt, and redirect to the original allowed return path. - A commit failure leaves the player in
needs-account-decisionormerge-pending; it never falls through to an apparently successful account session. - If another operation currently owns a required account lease, commit keeps the same operation
ID, honors
Retry-After, and remains inmerge-pending. After acquiring both current-root leases it re-resolves the roots and rechecks the material preview fingerprint; a changed duplicate winner or other material conflict returns toneeds-account-decisioninstead of silently applying stale consent.
Cancel¶
- Cancel invalidates the pending attempt/cookie and returns to the original guest or verified session unchanged.
- It does not unlink an existing identity, delete an Entra customer object, delete guest data, or mint a verified session.
- The fact that Entra may retain its own SSO session does not mean Verbolus sign-in completed.
Signed-cookie authLevel¶
Evolve the existing signed cookie as described in doc/accounts-and-subscriptions-plan.md, with a
versioned payload containing at least:
authLevel=anonymousmeans the cookie identifies a guest profile. Ordinary gameplay continues to work as it does today.authLevel=verifiedmeans an OIDC identity was proven and the callback-to-completion commit above succeeded. Billing and other account-only endpoints require this level plus any recent-auth requirement.- Legacy bare/signed UUID cookies migrate as anonymous without changing their underlying player ID.
GetUserId()continues to expose only the resolved canonical player ID to ordinary endpoints; add a focused verified-session authorization helper/policy rather than scattering cookie parsing.- Enforce expiry server-side, rotate verified cookies through the BFF, and prevent session fixation.
- Never set
verifiedimmediately after token validation if an account decision or merge is pending.
6.3 Create an account with email and password¶
- On the Entra page, the player enters an email address and selects
Next. - If no local identity exists, the player selects
Create one. - Entra verifies ownership of the email using its configured verification flow.
- Entra asks for password and confirmation. Password policy, visibility control, validation, throttling, and breach/risk protections belong to Entra; Verbolus must not duplicate rules it cannot authoritatively enforce.
- Entra collects
Display Nameduring sign-up. Customize the label/help if supported:Shown in Verbolus groups and leaderboards. You can change it later. - Display-name input is trimmed and normalized consistently with Verbolus settings. Maximum length is 32 Unicode characters/grapheme policy as implemented by the backend. Reject control characters and dangerous/invisible-only values. Do not require a real/legal name.
- Entra creates the customer identity and returns to the callback.
- Verbolus creates or resolves the canonical account and proceeds to the guest-progress decision in section 6.6.
- The explicit display name entered during this sign-up becomes the account's initial Verbolus display name. If an existing canonical account is being recovered, its existing name wins unless the player explicitly changes it later.
- The final success screen says
Account createdand summarizes what was kept. It never displays the password.
If the email is already registered, Entra moves to sign-in or presents recovery without revealing more account-existence information than its standard protected flow.
6.4 Create an account with Google, Microsoft MSA, or Facebook¶
- The player selects the provider on the Entra-hosted screen.
- The provider authenticates and displays its own consent experience.
- Request only
openid, the stable subject, and the minimalprofile/verified-email claims needed for display and support. Do not request contacts, posts, calendar, files, friend lists, or offline API access unrelated to authentication. - If Entra needs an additional Display Name, it asks during the same sign-up flow using the Verbolus-specific explanation above.
- Provider cancellation or consent denial returns to Verbolus without changing the guest profile.
- On success, Verbolus resolves the identity and proceeds to section 6.6.
Microsoft MSA is a release requirement but a configuration spike is mandatory before UI work is declared complete. Prove personal Outlook/Hotmail/Xbox accounts end to end. Do not mark the task complete with only a workforce-tenant Entra federation.
6.5 Sign in to an existing account on a device with no meaningful guest data¶
- The player authenticates using any connected method.
- The identity lookup resolves the canonical
playerId. - If the current guest profile has no saved plays, streaks, group memberships, non-default settings, or meaningful local state, skip the merge preview.
- Issue/rotate the verified session for the canonical account.
- Redirect to the validated return path and show
Signed in as Maya. - Load canonical server data; never show an empty guest scorecard while account data is loading.
6.6 Create a new account from a guest profile with progress¶
After authentication creates a new identity and no existing account owns it, show:
Save this device's progress?
This browser already has:
24 completed games
A 7-day current streak
2 groups
Display name: Maya
[ Keep this progress ]
[ Start fresh ]
[ Cancel ]
Keep this progress:
- Promote the existing guest
playerIdin place whenever possible. - Attach the new verified identity to that canonical profile.
- Preserve plays, statistics, streaks, groups, ownership, settings, and display name.
- If the sign-up flow supplied a different display name, explain the difference and let the player choose on the confirmation screen. Default to the newly entered name because it is the most recent explicit choice; do not silently overwrite.
- Issue the verified session only after the external-identity mapping and canonical profile are at a safe, idempotent checkpoint.
Start fresh:
- Create an empty canonical account for the verified identity.
- Do not attach or delete the guest profile immediately.
- Create a server-side deferred-import record linking the authenticated account, installation, and source guest profile for 30 days. Do not expose either player ID.
- Show a persistent-but-dismissible Settings notice during the grace period:
Progress from this device was not added. Review and add it before September 20. Review and addreturns to the same preview and can complete the import.- At the end of 30 days, purge the abandoned guest profile and the deferred-import record through a reconciled deletion job. The original confirmation must say this will happen.
Cancel:
- Do not link the identity, create the verified session, or alter the guest cookie.
- If Entra has already created a customer directory object, it may remain unlinked until a later sign-in; the next successful attempt resumes account completion safely.
- Return to the originating route with all guest progress intact.
6.7 Sign in to an existing account from a guest device that has progress¶
Show a two-sided summary without exposing raw IDs:
We found your Verbolus account
Your account
86 completed games · 12-day streak · 3 groups
Progress on this device
5 completed games · 2-day streak · 1 group
[ Add this device's progress ]
[ Use my account without adding it ]
[ Cancel ]
Add this device's progress:
- Create an idempotent durable merge/import operation before mutation.
- Keep the existing verified account as canonical.
- Apply the conflict rules in section 7.
- Repoint group membership/ownership and installation-scoped services.
- Preserve an alias from the source profile until every dependent read, export, deletion, and reconciliation path understands the merge.
- Issue the canonical verified session at the safe checkpoint.
- Show
Signed in. Progress from this device was added.
Use my account without adding it uses the 30-day deferred-import behavior from section 6.6. It
must not immediately delete the guest data.
Cancel returns to guest play unchanged.
6.8 Merge is slow, interrupted, or partially completed¶
- After confirmation, route to a dedicated status surface keyed by an opaque operation ID.
- Show
Combining your progress… You can leave this page. - Poll with bounded backoff or refresh via a server response; never retry the mutation with a new operation ID.
- Refresh/retry uses the same idempotency key.
- If recoverable work is pending, say
Your progress is safe. We're still finishing the update. - Provide
Try againonly when it resumes/reconciles the same operation. - A support reference may display a short non-secret correlation code, never a player ID, issuer, subject, token, or exception.
- Do not claim success until the canonical profile, external-identity lookup, aliases, and critical group ownership are consistent or recorded for guaranteed reconciliation.
6.9 Ordinary returning sign-in¶
- The player selects
Sign infrom Account or a contextual action. - Entra may reuse its own SSO session or ask for credentials/provider choice.
- Verbolus resolves the returned identity to one canonical account.
- A guest preview appears only when meaningful guest data exists.
- The BFF rotates the verified session and redirects to the original same-origin path.
- An unrecognized identity goes through account completion; it must not receive another account's data because an email happens to match.
6.10 Add another sign-in method¶
This capability ships with accounts, not as a speculative later feature.
- From Account, select
Addbeside Email and password, Google, Microsoft, or Facebook. - If the account session is not recently authenticated, complete reauthentication first.
- The BFF starts a link transaction bound to:
- current canonical account;
- requested provider;
- state/nonce/PKCE;
- validated Account return path;
- short expiry and one-time use.
- Entra/provider authenticates the new method. Provider selection is constrained to the method the player chose so a Google link cannot unexpectedly become Facebook.
- The backend checks the verified
issuer + subjectmapping.
Outcomes:
- Not linked anywhere: attach it to the current canonical account and show
Microsoft was added as a sign-in method. - Already linked to this account: treat as idempotent success and show
Microsoft is already connected. - Linked to another account: do not move it silently. Continue to section 6.11.
- Canceled/denied/expired: leave the method list unchanged and show a recoverable message.
Adding email and password from a social-only account requires verified email ownership and setting a password entirely in Entra. Do not accept an email/password pair through a Verbolus API.
6.11 New sign-in method belongs to another Verbolus account¶
Both accounts have now been independently authenticated, so offer an explicit account merge:
This Microsoft sign-in is already connected to another Verbolus account.
Current account
Maya · 86 games · 3 groups
Other account
Maya R · 14 games · 1 group
Combining accounts cannot be automatically undone.
[ Review combined account ]
[ Cancel ]
The review includes duplicate-play handling, groups, display-name choice, and membership/billing impact. When duplicate Dailies exist, say plainly that the first completed result remains official; do not describe the rule as “best score.” Rules:
- Keep the currently signed-in account canonical unless an active billing entitlement requires the other account to remain canonical.
- If exactly one account has an active subscription, preserve that account's canonical billing identity.
- If both have active subscriptions or incompatible billing records, block automatic merge and provide a support path. Never discard, duplicate, or transfer billing silently.
- Ask which display name to keep when both are nonempty and different.
- Combine all verified sign-in methods and prevent removal of the final one.
- Apply section 7's deterministic data rules.
- Record the merge and identity reassignment durably and idempotently.
6.12 Remove a sign-in method¶
- Show
Removeonly when at least one other usable verified method will remain. - Require recent authentication using a method other than the one being removed when feasible.
- Confirm with explicit copy:
Remove Google sign-in? This does not delete your Google Account. You can add it again later. - Remove the external-identity mapping and update the account method list atomically or through a reconciled operation.
- Revoke/delete any Verbolus-held provider credential if one exists; ordinary authentication should avoid retaining provider access/refresh tokens beyond the OIDC session need.
- Show
Google sign-in removed.withAdd it againas a safe recovery action, not a client-only undo that bypasses provider authentication. - Never allow removing the last method. Explain:
Add another sign-in method before removing this one.
6.13 Change password¶
Only show this action when email and password is connected.
- Select
Change passwordfrom Account. - Explain before leaving Verbolus:
Microsoft manages your password. You'll verify your email and choose a new password on the Verbolus sign-in page. - Start a dedicated, server-bound password-management transaction and use Entra External ID's Microsoft-hosted self-service password reset (SSPR) experience. Require fresh proof; do not treat the current Verbolus cookie alone as authority to change a credential.
- The implementation must first prove the supported browser-delegated entry point in the configured
tenant. Microsoft's current documented SSPR journey
begins at the hosted sign-in page and its
Forgot password?action. If Entra cannot directly enter that hosted journey, show the short instruction above and force the hosted login page rather than inventing a Verbolus password form. - Do not use Microsoft Graph
POST /me/changePasswordin this architecture: it requires delegatedDirectory.AccessAsUser.Alland would make Verbolus handle current/new password values. Adopting it would be a separate, explicit security-architecture decision, not a shortcut for this UI. - Verbolus never renders current/new password inputs, logs password validation errors, or proxies password values through its backend.
- Return to Account on success or cancellation. Show
Password changed.only if Entra provides a trustworthy success result for the dedicated transaction; an ordinary successful sign-in is not proof that the player used the reset link. Otherwise use neutral return copy. - Existing sessions follow the chosen Entra/session revocation policy. At minimum, rotate the
current Verbolus session after a proven change. Provide
Sign out other devicesonly after a real server-side session registry exists.
6.14 Forgot password and signed-out recovery¶
- On the Entra email/password screen, select
Forgot password?. - Entra performs account discovery, email verification, throttling, and reset.
- Responses must avoid useful account enumeration. Use generic copy when Verbolus displays an
error:
If that address can be recovered, follow the instructions sent to it. - After reset, return through the normal validated callback and account-resolution flow.
- Preserve the original Verbolus return path, but never put email or reset state in the URL.
- If the user normally signs in through Google/Microsoft/Facebook, direct them to that provider's recovery flow; Verbolus cannot reset those credentials.
- Support must never transfer an account based only on display name, claimed email, receipt image, cookie value, or player ID.
Recovery scenarios:
- lost one provider but another linked method works: sign in with the working method, then remove or replace the inaccessible one;
- inaccessible local email but a social method works: sign in socially, add and verify a new local method, then remove the old method;
- only provider is inaccessible: use that provider's recovery; no manual Verbolus bypass;
- deletion is scheduled but not executed: sign in, reauthenticate, and cancel deletion;
- deletion completed: old data is not recoverable; create a new account.
6.15 Change email address for the local method¶
Model this as replacement of a verified sign-in method, not an unverified profile edit.
- Select
Change sign-in email. - Require recent authentication.
- Verify the new email through Entra before it becomes usable.
- Keep the old email method until the new method is confirmed.
- Once confirmed, replace/remove the old method and rotate the current session.
- If the new identity belongs to another account, use the explicit account-merge flow.
6.16 Edit display name¶
- Profile shows the current name and the existing explanation,
Used in groups and leaderboards. - Saving is allowed for guests and accounts; it does not require reauthentication.
- Trim and validate server-side; maximum 32 characters.
- Update current group/member/standings projections through the existing authoritative update mechanism so old snapshots do not remain indefinitely.
- Show inline validation and an announced success message.
- A later moderation/reporting policy may restrict names, but do not silently replace a rejected name with a provider's real name.
6.17 Session expiry¶
The deployed cookie policy and game recovery behavior are documented in Expired account session recovery. The following describes the original design proposal.
- Verified sessions use an explicit idle and absolute lifetime, with server-side rotation. A reasonable starting policy is 30-day idle and 90-day absolute expiry, subject to the security implementation's final review.
- Sensitive actions require authentication within the preceding 15 minutes.
- When a session expires, retain a non-sensitive indication that this installation previously
used an account and show:
Your session expired. Sign in again to access your saved Verbolus account. - Do not silently mint a new guest identity and make the scorecard appear erased.
- Offer
Sign in againand an explicitContinue as a guestchoice. - Starting guest play creates a new guest profile and never copies account data out of the expired session.
6.18 Sign out of this device¶
- Select
Sign out of this device. - Confirm only when the consequences need explanation:
Your account and saved progress will remain. This device will start a new guest profile. - Revoke/delete the Verbolus BFF session and refresh material for this device.
- Replace the account cookie with a new signed guest profile cookie; do not reuse the canonical
account's
playerIdas a guest. - Detach installation-scoped push subscriptions as specified by notification policy.
- Do not globally sign out of Google, Microsoft, or Facebook.
- Return home with
Signed out on this device.
6.19 Switch account¶
- Select
Switch account. - Explain:
You'll choose another Verbolus account for this device. Your current account remains unchanged. - Start an OIDC flow that asks Entra/provider to select or authenticate an account rather than automatically reusing the current identity when technically possible.
- Keep the current Verbolus session until the replacement authentication succeeds.
- On cancel/failure, restore the current account unchanged.
- On success, replace the local Verbolus session with the selected canonical account.
- Do not merge the two signed-in accounts. Account merging occurs only through the explicit sign-in-method collision workflow.
6.20 Export data¶
Guests and verified users retain the existing export capability.
For verified accounts, export must include data owned through merged aliases, linked-provider
metadata appropriate for the user (friendly provider, masked identifier/link date; never tokens),
merge history needed to explain provenance, and future billing metadata required by the privacy
policy. A merge is incomplete if exported/source play history disappears merely because play
documents still carry an old userId.
Sensitive export from a verified account requires recent authentication. Generate bounded exports; move to an asynchronous expiring download if data volume outgrows a request.
6.21 Delete guest data¶
- Retain the existing
Delete my Verbolus dataaction. - Preview saved plays, scorecard, streaks, groups, and settings to be removed.
- Require typed
DELETEconfirmation. - Explain that clearing cookies is not equivalent to server deletion.
- Delete/reconcile plays, profile, group memberships/ownership according to existing rules, and issue a new empty guest cookie.
- Once the irreversible request is accepted, there is no undo. Show completion only after the deletion operation reaches its committed checkpoint.
6.22 Delete a verified account without an active subscription¶
- Select
Delete Verbolus accountfrom the danger zone. - Require recent authentication with a connected method.
- Offer
Download my databefore confirmation. - Explain exactly what is deleted:
- plays, scorecard, statistics, streaks, display name, settings;
- group memberships and applicable ownership handling;
- Verbolus sign-in-method links and Entra customer account(s) controlled by Verbolus;
- installation/notification records and future non-required account data.
- Explain what is not deleted: Google, Microsoft, or Facebook accounts themselves; legally required security/audit/financial records retained under a documented policy.
- Require typed
DELETEand a final destructive button labelledDelete Verbolus account. - Create an idempotent durable deletion operation, revoke active Verbolus sessions, and cross the irreversible checkpoint only after the request is recorded.
- Delete every alias/source profile and all linked identity lookups; do not leave a merged profile accessible through an old cookie.
- Delete or disable the corresponding Entra customer identities so a later authentication cannot silently resurrect the deleted profile.
- Pseudonymize retained audit references and set explicit retention expiry.
- Return to a new guest state with
Your Verbolus account was deleted.
There is no undo after the final request is accepted. The deliberate review, reauthentication, typed confirmation, and durable checkpoint are the undo boundary.
6.23 Delete a verified account with an active or prepaid subscription¶
Default policy:
- Explain the current paid-through date.
Schedule deletioncancels renewal immediately and schedules account deletion for the end of the paid period so the player receives the benefit already purchased.- While scheduled, show a persistent account notice with effective date,
Cancel deletion,Download my data, andDelete now instead. Cancel deletionrequires recent authentication and cancels only the deletion request; renewing the subscription remains a separate explicit Stripe action.Delete now insteadrequires another clear confirmation, ends Verbolus access/entitlements, and starts immediate deletion. Refund rights and support contact must be explained according to the published billing/refund policy.- At effective deletion, remove/anonymize Verbolus data. Stripe may retain legally required transaction/tax records; minimize and pseudonymize Verbolus-side linkage rather than promising that payment records outside Verbolus are erased.
If product/legal review chooses a different cancellation policy, update the UI, Stripe configuration, privacy policy, terms, and tests together. Do not ship ambiguous behavior.
7. Deterministic migration and account-merge rules¶
These rules must live in one testable domain service and be shown accurately in the preview.
7.1 Canonical identity¶
- Guest promotion keeps the existing guest
playerId. - Signing into an existing account keeps the existing account's
playerId. - When linking collides with another account, keep the current account canonical unless billing requires the other account; record the choice and aliases.
- Never choose canonical identity based on newest email, provider, browser, or lexicographic ID.
7.2 Plays and statistics¶
- Preserve all source play records for export/audit until the relevant retention policy expires.
- Deduplicate by the game-owned logical puzzle identity, currently
puzzleKey. A Daily puzzle contributes at most one completed play to statistics, streaks, scorecards, and standings. - If one record is completed and the other is in progress, the completed record is authoritative.
- If both are completed, the earliest immutable
completedAtis authoritative. Do not choose by score: Letter Golf is lower-score-wins, and selecting a preferred result would make merging a way to shop multiple guest attempts. - Add
completedAtto persisted plays, assign it server-side only on the transition to Completed, and never accept or later change it from client input. For legacy records, fall back toupdatedAt; if still tied/unknown, prefer the pre-merge canonical target's record and then ordinalplayKey({puzzleKey}|{userId}today) as the final deterministic fallback. - Combine eligibility flags conservatively. If any duplicate says solutions were viewed before completion, the merged logical play remains excluded from stats/streaks.
- Preserve the non-authoritative record as superseded merge provenance for export/support/deletion, with an exclusion reason. It never contributes to aggregates, standings, or resumed play.
- If both records are in progress, retain the pre-merge canonical target's state; if there is no
canonical-target record, use the oldest
createdAtand ordinalplayKeyfallback. Do not fabricate a union of two word lists. - Practice puzzles with distinct puzzle IDs remain distinct.
- Recompute statistics and streaks chronologically from the deduplicated authoritative play set. A
qualifying
gameType + scope + puzzleDatecontributes once, so overlapping devices never double-count a day and non-overlapping dates extend the combined streak normally. - All normal reads, scorecards, export, and deletion must resolve aliases. Merely recomputing aggregates while leaving source plays invisible to the canonical account is not sufficient.
7.3 Groups¶
- Union memberships.
- If both profiles belong to one group, retain one canonical membership.
- Transfer source ownership to the canonical account.
- If both memberships have distinct display snapshots, update to the chosen canonical display name.
- Reconcile standings so the same person does not occupy two leaderboard rows after merge.
- Never reveal private group names from one account until both accounts are authenticated and the merge preview is authorized.
7.4 Settings¶
- For guest import into an existing account, the existing account's explicit settings win.
- Fill only truly unset settings from the guest profile.
- For a brand-new account promoted from a guest, guest settings are preserved.
- Display-name conflicts require an explicit choice.
- Consent does not automatically broaden during merge. Use the most privacy-preserving applicable state and let the player change it later.
- Installation-local choices remain installation-local.
7.5 Sign-in methods and billing¶
- Union verified methods after explicit account-merge confirmation.
- A provider identity may map to only one canonical account after reconciliation.
- Never use email equality as a merge rule.
- One active Stripe customer/subscription maps to one canonical account.
- Two active billing identities block automatic merge and require support resolution.
7.6 Concurrent merges and alias-graph safety¶
- Resolve the current roots, then serialize a merge with renewable, ETag-guarded leases on both the
source and target canonical root records, owned by the durable operation ID. Acquire them in
ordinal
playerIdorder, release an owned partial acquisition before retrying, and re-resolve both roots after acquiring them. This prevents both same-target lost updates and reciprocalA → B/B → Aalias cycles. - Store lease owner, acquisition time, and expiry; never use an unbounded Boolean lock that can remain stuck after a crash. Renew during work and clear only a lease still owned by the operation.
- A live competing required lease produces internal
merge_account_busy(409 plusRetry-After). The BFF retries the same operation with bounded jitter while the UI remains onCombining your progress…. - After acquiring both leases and revalidating the roots, re-read the canonical target, all aliases already merged into it, and the new source closure. Recompute plays/stats from that complete fresh union so a second near-simultaneous merge includes the first one's data.
- Recompute the preview's material decision fingerprint. If the prior merge changed a duplicate
winner, display-name decision, billing/canonical choice, or another user-visible conflict, return
to
needs-account-decisionwith a refreshed preview. Count-only changes may proceed without a new confirmation. - Save the target with ETag protection and re-read/recompute on conflict while the operation still owns both leases. Release or renew a lease only through a matching operation ID.
- A crashed holder is recovered after lease expiry from its durable operation state. Same-operation retries converge; a source already merged elsewhere is a hard conflict, never an alias fork.
- Ordinary plays may finish during a merge. Do not block gameplay; reconcile after the safe checkpoint so late plays appear once in the alias-aware canonical result.
8. Error, interruption, and edge-case matrix¶
| Situation | Player response | System behavior |
|---|---|---|
| User cancels Entra/provider | Sign-in canceled. Your progress is unchanged. |
Discard transaction; preserve current session/cookie |
| State/nonce/PKCE invalid | We couldn't complete sign-in. Please try again. |
No identity change; security telemetry without token/PII |
| Auth transaction expired | That sign-in attempt expired. + Try again |
Start a new transaction; never replay callback |
| Provider unavailable | Google sign-in is temporarily unavailable. Try another method. |
Keep current state; provider-specific circuit/telemetry |
| Callback succeeds but backend unavailable | You're signed in, but we couldn't finish connecting your progress. |
Retain resumable operation; no data deletion |
| Identity lookup race | Neutral processing/retry UI | Conditional create/idempotency; one canonical owner wins |
| Merge operation retried | Same operation status | Idempotent no-op/resume; never double-count |
| Display names conflict | Ask which one to keep | No silent overwrite |
| Duplicate Daily plays | Explain that the first completed result remains official | Earliest completedAt wins; other is preserved as superseded and excluded |
| Another merge holds a required account lease | Continue showing Combining your progress… |
Retry the same operation after Retry-After; refresh preview only if material decisions changed |
| Add method already on same account | Already connected. |
Idempotent success |
| Add method belongs to other account | Account-merge preview | No silent reassignment |
| Remove last method | Inline explanation | Reject server-side even if client bypassed |
| Password reset email delayed | Entra recovery guidance | No custom credential handling |
| Session expires during form | Preserve non-sensitive form data; reauthenticate | Resume action only after CSRF/session validation |
| Switch-account authentication canceled | Account switch canceled. |
Keep original account session |
| Deletion job partially fails | Deletion is still being completed. |
Durable retry/reconciliation; sessions stay revoked |
| Deleted identity signs up later | New-account experience | Never restore deleted player data |
| Facebook disabled after being linked | Existing linked users can still sign in during deprecation window or must first add another method | Never strand an account; removal plan required before provider shutdown |
| MSA spike cannot authenticate personal accounts | Do not display Microsoft button | Block required-provider launch or explicitly renegotiate scope; do not substitute workforce federation |
| Microsoft account chooser/passkey auto-selects the wrong personal MSA via an existing browser session | Player must manually pick Use another account on Microsoft's own screen |
Known Microsoft-hosted limitation, not app-controllable; External ID's user-flow-based custom OIDC configuration has no field to force prompt=select_account on the upstream authorize request (that level of control needs Identity Experience Framework/custom policies, which External ID/CIAM does not support). Not a launch blocker. |
All API errors use stable machine-readable codes and safe ProblemDetails. UI maps codes to useful
copy. Never display stack traces, raw provider errors, issuer, subject, tenant IDs, client IDs,
tokens, or internal player IDs.
9. Password and account security requirements¶
- Use authorization code + PKCE with validated state and nonce.
- Keep ID/access/refresh tokens server-side; never expose them to client JavaScript or local storage.
- Entra owns passwords, verification, lockout, risk controls, and password recovery.
- Configure Entra's current recommended password and smart-lockout protections. Do not create a weaker parallel password policy in Verbolus.
- Rate-limit auth start/callback completion, link, unlink, merge preview/commit, recovery initiation, session refresh, export, and deletion according to their abuse profiles.
- Require recent authentication (initially 15 minutes) for:
- adding/removing a sign-in method;
- changing password or sign-in email;
- account-to-account merge;
- beginning subscription checkout;
- opening billing management;
- exporting verified-account data;
- scheduling/canceling/immediately executing deletion.
- Protect cookie-authenticated mutations with explicit CSRF defenses in addition to intentional
SameSite,Secure, andHttpOnlycookie settings. - Validate return URLs against a same-origin allowlist; never accept arbitrary callback or post-auth redirects.
- Rotate verified sessions at sign-in, privilege/identity-method change, password change, and recovery. Prevent session fixation.
- Do not add
Sign out all devicesuntil sessions are individually registered and revocable. - Do not claim MFA or passkey support until it is configured and tested end to end. Keep the UI model extensible so a future passkey is another sign-in method.
- Log security events with correlation IDs and provider category only. Exclude email, display name, subject, full IP where unnecessary, tokens, cookies, authorization codes, and password data.
10. Privacy and social boundaries¶
- Update Privacy and Terms before public rollout to disclose Entra and enabled providers, stored identity metadata, account merge, retention, export/deletion behavior, and Stripe when applicable.
- Collect only authentication scopes. Google, Microsoft, and Facebook sign-in do not grant Verbolus contact/friend access.
- Do not build “Invite Facebook friends,” address-book upload, WhatsApp contact import, wall posting, or automatic social posting.
- Keep groups private and invitation-based. Identity-provider account details never become a public profile.
- Continue explicit native result sharing. The player chooses the destination in the OS/browser share sheet.
- Display names are user-generated content. Normalize and validate them, and retain the existing plan for reporting/profanity/impersonation controls before profiles become more public.
- Account and consent surfaces never contain advertisements.
11. Accessibility and responsive behavior¶
Target WCAG 2.2 AA.
- Entra branding and custom CSS must preserve keyboard operation, visible focus, zoom/reflow, high-contrast behavior, provider-button names, and error associations.
- Verbolus dialogs use Radix primitives with initial focus on the heading or safest action, Escape behavior where safe, focus return to the invoker, and no destructive action as default focus.
- Merge summaries use real lists/tables with textual labels, not color alone.
- Async auth/merge/deletion status uses a restrained
role=statuslive region; errors receive focus at the summary and remain associated with fields. - Buttons use exact action labels (
Keep this progress,Start fresh,Delete Verbolus account), not ambiguousContinuewhere consequences differ. - Support 320 CSS-pixel width, 200% zoom, light/dark themes, reduced motion, keyboard-only use, and screen readers.
- Localize visible/authentication copy, accessible names, errors, dates, counts, and pluralization.
Use
Intlfor the 30-day import and deletion dates.
12. Telemetry and supportability¶
Recommended events, all free of direct PII:
account_prompt_shown/dismissed/acceptedwith prompt reason;auth_started/completed/canceled/failedwith provider category and safe error code;guest_import_previewed/kept/deferred/canceledwith count buckets, not group names;merge_started/completed/failed/reconciledwith opaque operation correlation;signin_method_add_started/completed/canceled/collision;signin_method_removed;reauth_started/completed/failedwith action category;signout_completed,account_switch_completed/canceled;deletion_scheduled/canceled/started/completed;- recovery entry and completion category without email.
Do not measure passwords, provider tokens, authorization codes, email addresses, display names, group names, raw player IDs, issuer/subject, or merge source/target IDs in analytics. Protected operational logs may use a one-way/correlated internal identifier when necessary for support.
13. Backend and data implementation instructions¶
13.1 Contracts and services¶
- Keep HTTP endpoints thin. Put account resolution, sign-in-method policy, merge conflict rules, session policy, and deletion orchestration in testable services.
- Extend the current internal identity foundation rather than introducing a client-trusted identity
route. The Next.js BFF validates OIDC and authenticates to
/v1/internal/identity/*using the existing app-role/managed-identity boundary. - The acting source player always comes from the signed browser cookie forwarded by the BFF, never
a JSON
playerIdsupplied by browser code. - Replace any internal API contract that returns raw target player IDs to browser code with an opaque server-side transaction/operation ID. Raw IDs may remain between trusted BFF/backend components only.
- Add an account summary contract containing auth state, display name, safe sign-in-method summaries, deferred-import status, deletion status, and future entitlement summary.
- Add durable auth/account-operation records for guest import, account merge, identity reassignment, and deletion. Each has operation ID, type, source/target references, state, timestamps, version, error/retry metadata, and idempotency key.
- Make every mutating endpoint cancelable, idempotent where retried, CSRF-protected at the browser boundary, rate-limited, and represented in OpenAPI where public contracts apply.
13.2 Identity storage¶
- Continue using
issuer + subjectas the stable external-identity key. - Add provider category, masked-display metadata, linked timestamp, last-used timestamp, and method status without storing unnecessary provider profile data.
- Enforce one external identity to one canonical account using conditional create/ETag semantics.
- Allow one player to own multiple external identities.
- Never store social-provider access to contacts/files or long-lived tokens unless a future feature separately justifies and secures them.
- Treat email as mutable display/recovery metadata, never as the identity lookup key.
13.3 Merge foundation gap to close¶
The current branch recomputes target aggregates from both players and leaves source play documents under the source user ID while marking the source profile as merged. Before releasing migration:
- define canonical reads through a bounded alias set or physically migrate/recreate play documents;
- ensure scorecard/history, duplicate-Daily rules, exports, deletion, group standings, and future recomputation see the same authoritative play set;
- ensure a stale source cookie resolves safely to the target or is rotated;
- add a reconciler for best-effort group/lookup writes;
- never declare merge complete while source history is invisible to the canonical account.
Implement completedAt, the first-completion duplicate resolver, superseded-play provenance, and
the renewable ordered root-pair operation leases from section 3a of
doc/accounts-and-subscriptions-plan.md. The current aggregate recomputation concatenates source and
target completions, so it will double-count a shared puzzleKey until it first constructs the
deduplicated authoritative play set. Its current target ETag retry protects one player-document
write but does not serialize two distinct merges or force the second merge to include aliases from
the first; both behaviors must be closed before rollout.
13.4 Deletion¶
Deletion is a durable operation, not a chain of best-effort request writes. It must enumerate and reconcile canonical profile, aliases, plays, groups/ownership, standings, lookup records, auth methods/Entra objects, sessions, installation records, notifications, deferred imports, billing records subject to retention, and audit pseudonymization.
14. Next.js BFF and frontend implementation instructions¶
- Prefer Server Components and server-only modules for account state and auth orchestration. Keep provider tokens and internal app-role credentials out of client bundles.
- Suggested BFF routes/actions (exact naming may follow established conventions):
GET /api/auth/start;GET /api/auth/callback;POST /api/auth/account-decision;POST /api/auth/link/start;POST /api/auth/unlink;POST /api/auth/sign-out;POST /api/auth/switch/start;POST /api/auth/reauth/start;- status routes for opaque merge/deletion operation IDs.
- Use server-set HttpOnly cookies. Do not put OIDC tokens, source/target IDs, merge authorization, or provider identity in local storage or query parameters.
- Preserve only validated same-origin return paths.
- Add explicit loading, success, empty, expired, canceled, and recoverable error UI for every route.
- Use one account-state loader so header/menu, Settings, Support, and prompts do not disagree.
- Do not personalize from a shared Next.js cache. Account responses are private/no-store.
- Extend existing design language: narrow 600px account/settings column, bordered cards, restrained blue actions, destructive red only in the danger zone, light/dark support, and 44px targets.
15. Entra and provider configuration checklist¶
- Tenant-facing name is
Verbolus. - Configure logo, favicon, colors, Privacy URL, Terms URL, sign-in page text, and supported locales.
- Enable email with password and self-service password reset.
- Configure Google and validate production consent/redirect domains.
- Configure and prove personal Microsoft MSA end to end. Test Outlook.com/Hotmail and a personal Microsoft account that also belongs to an organization to catch account-choice ambiguity.
- Configure Facebook only when approved. Entra user-flow/provider configuration is the authoritative switch for whether its hosted button appears; an application feature flag alone cannot hide a provider after redirect. If staged rollout needs both variants, use a tested provider-specific flow/application arrangement rather than showing a dead button.
- Collect Display Name during sign-up with Verbolus-specific help text and 32-character-compatible validation.
- Minimize claims/scopes and verify the
idp/identity-source information needed for friendly method labels. - Register exact local/staging/production redirect and post-logout URIs. No wildcard redirect URIs.
- Test cancel, denial, bad state, reset, link, unlink, SSO reuse, account selection, sign-out, and provider outage behavior.
- Do not make a custom login domain a launch blocker; track it as a separate trust/branding enhancement.
16. Implementation phases¶
Each phase ends with executable checks and a deployable/rollback-safe state. Do not expose UI before its complete backend path is feature-flagged and safe.
Phase 0 — provider and UX proof¶
- Prove hosted email/password, Google, personal Microsoft MSA, and optional Facebook.
- Finalize branding, Display Name collection, password reset, callback claims, and provider labels.
- Record screenshots and claim samples with secrets/tokens removed.
- Resolve whether app-level linking can reuse one Entra customer object or will map multiple Entra subjects to one Verbolus account. The Verbolus model must support either.
Exit: all required provider flows work in a non-production environment; MSA is truly personal MSA.
Phase 1 — account/session read model¶
- Implement verified session payload/rotation/expiry and account-state contract.
- Preserve anonymous cookies and backward compatibility.
- Add guest/verified/session-expired Account UI behind a feature flag.
- Add server-only OIDC transaction storage and callback validation.
- Implement the section 6.2.1 prepare/pause/commit protocol. The callback must be able to finish
cryptographic authentication, redirect to
/account/finishwithout minting a verified cookie, and resume from an opaque pending attempt after the player's decision.
Exit: sign-in resolves an identity without yet mutating guest data; negative auth tests pass.
Phase 2 — account creation and guest migration¶
- Implement promotion, meaningful-data detection, merge preview, keep/start-fresh/cancel, deferred import, operation status, alias-aware reads, and reconciliation.
- Implement explicit Display Name conflict choice.
- Update scorecard/export/group behavior for aliases and duplicate Daily rules.
Exit: cookie-only users can create/sign into accounts without silent data loss.
Phase 3 — multiple sign-in methods¶
- Implement safe method summaries, add/link, idempotent already-linked handling, last-method guard, remove, change password/email handoffs, and account-collision merge.
- Add billing-aware canonical selection even if billing is not enabled yet; inactive/default state is sufficient for this phase.
Exit: every required provider can be added to an existing account and used for a later sign-in.
Phase 4 — sessions, sign-out, switch, recovery¶
- Implement recent-auth policy and continuation.
- Implement local-device sign-out and deliberate switch-account behavior.
- Complete password/provider recovery copy and session-expiry UX.
Exit: shared-device and expired-session journeys do not leak or appear to lose account data.
Phase 5 — export, deletion, privacy, operations¶
- Implement alias-complete export and durable verified-account deletion.
- Implement subscription-aware scheduled deletion state even if subscription activation follows.
- Update Privacy, Terms, support runbook, telemetry, and reconciliation alerts.
Exit: deletion/export cover canonical and merged data; Entra mappings cannot resurrect deleted data.
Phase 6 — controlled rollout¶
- Target internal accounts/installations with existing feature flags.
- Run provider and merge smoke tests in staging and production configuration without real user data.
- Expand through small stable cohorts; monitor auth completion, merge failures, account collisions, recovery, session loops, and support contacts.
- Keep a server-side kill switch that hides account entry points without invalidating existing users' ability to sign in/manage/delete their accounts.
17. Test and acceptance matrix¶
17.1 Backend unit tests¶
- session sign/verify/expiry/rotation and legacy-cookie compatibility;
- external-identity uniqueness and multi-method rules;
- meaningful guest-data detection;
- promote vs merge vs deferred import;
- completed-over-in-progress, earliest-
completedAt, legacy fallback, eligibility taint, and superseded-provenance duplicate resolution; - chronological deduplicated streak recomputation;
- group/member/owner deduplication;
- settings/display-name conflict rules;
- canonical selection with zero/one/two active billing identities;
- last-method removal rejection;
- durable operation idempotency and state transitions;
- ordered root-pair lease acquire/partial release/renew/expire/owner-only release and reciprocal merge-cycle prevention;
- material preview-fingerprint change versus harmless count-only rebase;
- deletion enumeration and retry behavior.
17.2 Backend integration/Cosmos tests¶
- BFF app-role required for every internal identity endpoint;
- acting player comes from signed cookie, not request body;
- invalid/unsigned-forged cookies rejected according to rollout policy;
- identity link race produces one owner;
- merge retry after failure does not double-count;
- two different sources racing into one target serialize, and the second recomputes from the target's full alias set;
- reciprocal
A → BandB → Amerge attempts cannot create an alias cycle; - a live required lease returns
merge_account_busywithRetry-After; an expired lease is safely taken over; - same-source/same-target retries converge while same-source/different-target is rejected;
- a concurrent first merge that creates a new duplicate-play conflict forces the second preview to be reconfirmed;
- alias-aware scorecard, export, and delete include source plays;
- group owner/membership/standings reconciliation;
- CSRF, authorization, rate limit, validation, and safe ProblemDetails negatives;
- deleted Entra identity mapping cannot resolve old account.
- callback prepare is non-mutating and leaves the original cookie unchanged;
- a decision-required callback cannot access account-only endpoints before commit;
- pending attempt is bound to source cookie/installation, one-time, expiring, CSRF-protected, and safe under replay;
- verified
authLevelis minted only after commit's safe checkpoint; - stale preview produces a refreshed decision instead of silently committing changed data.
17.3 Frontend component tests¶
- guest and verified Account screens;
- provider list, masking, add/remove/last-method states;
- meaningful merge summaries and all three decisions;
- Display Name conflict selection;
- loading, canceled, expired, retrying, failed, and completed status;
- reauth continuation;
- sign-out and switch-account confirmation/cancellation;
- deletion without/with subscription;
- keyboard focus, live-region announcements, accessible names, and error association.
17.4 Playwright critical journeys¶
- New visitor plays, creates email/password account, chooses Keep, and retains score/streak/group.
- New visitor plays, creates Google account, chooses Start fresh, then imports within 30 days.
- Existing account signs in on a guest device and merges progress.
- Existing account chooses account-only, then later imports deferred progress.
- Email/password account adds Google and signs in with Google after signing out.
- Google account adds personal Microsoft MSA and signs in with Microsoft.
- Adding a provider already owned by another account produces explicit account merge.
- Remove a method; attempt to remove final method is blocked server-side and in UI.
- Forgot password returns to the intended Verbolus route.
- Expired session does not show an empty scorecard; reauthentication restores account.
- Switch account cancel keeps original session; successful switch does not merge accounts.
- Merge interrupted mid-operation resumes without duplicate stats.
- Two devices confirm merges into the same target together; both sources appear once and neither sees a raw 409.
- A concurrent merge changes which duplicate Daily is first; the affected finish screen refreshes and requests reconfirmation.
- Guest deletion and verified deletion remove all relevant data, including superseded duplicates.
- Active subscriber schedules deletion and can cancel it before the effective date.
- Provider outage/cancel/bad callback preserves current profile.
Run desktop and mobile viewports, keyboard-only navigation, automated accessibility checks, and a manual screen-reader pass. Test light/dark, 200% zoom, reduced motion, a long localized string set, and at least one non-English locale.
17.5 Required validation commands¶
Run focused tests first, then the repository checks relevant to all touched surfaces. Do not claim a check passed unless it ran successfully.
dotnet restore .\MiniGamesBackEnd\MiniGamesBackEnd.csproj
dotnet build .\MiniGamesBackEnd\MiniGamesBackEnd.csproj -c Release --no-restore
dotnet test -c Release --no-build
npm ci --prefix .\frontend\minigames
npm run lint --prefix .\frontend\minigames
npx --prefix .\frontend\minigames tsc --noEmit
npm run build --prefix .\frontend\minigames
terraform -chdir=tf fmt -check -recursive
terraform -chdir=tf init -backend=false
terraform -chdir=tf validate
18. Agent handoff instructions¶
18.1 Rules for every implementation agent¶
Before editing:
- Read repository
AGENTS.mdand the matching.github/instructions/*.instructions.mdfiles. - Read this document,
doc/accounts-and-subscriptions-plan.md, and the relevant sections ofdoc/engagement-platform-plan.md. - Inspect
git status; the working branch contains active user work. Preserve it. Never reset, discard, reformat, or overwrite unrelated changes. - Inspect the smallest owning implementation, neighboring tests, public contract, and Terraform configuration before proposing an abstraction.
- Implement one phase or one clearly bounded slice at a time. Feature-flag incomplete public UI.
- Add executable regression checks with each behavior change.
- Report assumptions, files changed, tests run, failures, security/privacy implications, and the next safe slice.
Do not deploy, run Terraform apply, mutate Entra/Stripe/Azure production resources, publish images, or create production secrets without explicit user approval and reviewed targets.
18.2 Work reserved for Opus/Sonnet-class agents¶
Assign security-sensitive or cross-boundary work to Opus/Sonnet:
- OIDC/MSAL/BFF transaction and callback implementation;
- verified-session cookie design, rotation, expiry, CSRF, and recent-auth policy;
- Entra provider configuration design, especially personal Microsoft MSA validation;
- external-identity/account data model and lookup uniqueness;
- guest promotion, account merge, aliases/play ownership, conflict rules, durable operations, and reconciliation;
- first-completion play deduplication, immutable completion timestamps, ordered root-pair merge leases, alias-cycle prevention, and material preview fingerprints;
- account-to-account merge and billing-aware canonical selection;
- password/email-method linking semantics;
- durable export/deletion and Entra/Stripe coordination;
- Terraform, managed identity, app roles, secrets, and rollout architecture;
- threat model, API contracts, authorization negatives, and end-to-end test architecture.
Give one lead agent ownership of contracts and merge/session invariants. Do not let multiple agents invent competing identity models or edit the same central files concurrently.
Suggested lead prompt:
Implement Phase N of doc/accounts-identity-ux-implementation-plan.md on
feat/accounts-identity-foundation. Treat its locked decisions, state model, workflow, conflict
rules, security requirements, and acceptance tests as requirements. Read AGENTS.md and all
matching .github/instructions first. Preserve existing dirty work. Inspect the current foundation
before editing and make the smallest coherent, backward-compatible slice. Keep OIDC/provider
tokens server-side, keep acting player identity cookie-derived at the internal API boundary, and
do not trust browser-supplied player IDs. Add focused tests, run affected validation, review the
diff, and report any requirement that the current architecture cannot safely satisfy.
18.2.1 Immediate Opus/Sonnet handoff: callback completion seam¶
The current branch has the BFF-to-backend app-role client and internal link, merge-preview, and
merge endpoints. The next lead-agent slice is specifically:
- Implement the versioned signed-cookie payload and
authLevelparsing/policy with legacy cookie compatibility. - Implement OIDC start/callback validation server-side.
- Add the non-mutating
prepareand idempotentcommitlayer in section 6.2.1 around the current link/merge foundation. - Add
/account/finishas a server-loaded state screen. It must support: - new identity + meaningful guest data: Keep / Start fresh / Cancel;
- existing identity + meaningful guest data: Add progress / Use account only / Cancel;
- display-name conflict choice;
- expired, stale-preview, processing, recoverable-failure, and completed states.
- Keep the original cookie active during the pause and mint
authLevel=verifiedonly after commit. - Use an opaque attempt plus an HttpOnly pending cookie; no raw player IDs or provider identity in the browser.
- Add integration and Playwright coverage proving the pending state cannot read the target account or accidentally complete sign-in.
This slice owns the seam between “Entra proved who this is” and “Verbolus has safely decided which
player profile this session represents.” Do not let the callback call the current mutating /link
endpoint before a required user decision.
Suggested focused prompt:
Implement the callback-to-completion seam in section 6.2.1 of
doc/accounts-identity-ux-implementation-plan.md. The existing BFF app-role client and internal
identity endpoints are foundation, but /link currently mutates too early for Keep vs Start fresh.
Add a non-mutating prepare disposition and idempotent commit, a short-lived server-bound pending
attempt, the /account/finish decision states, and a versioned cookie whose authLevel becomes
verified only after commit reaches its safe checkpoint. Preserve legacy anonymous cookie player
IDs and all active user work. Keep tokens and raw identity/player IDs server-side. Add focused
negative/replay/stale-preview tests and run backend, frontend, and affected infrastructure checks.
18.3 Work suitable for Haiku-class agents¶
Use Haiku only after contracts and states for the slice are frozen. Give it one bounded leaf task at a time, for example:
- implement one presentational Account card from an existing typed DTO;
- add one dialog's copy/states using existing callbacks;
- add Testing Library cases for an already-implemented component;
- add provider icons/labels using approved assets and existing button primitives;
- update Privacy/Terms/Support copy from approved wording;
- add Storybook-like fixtures if the repository adopts such a pattern;
- run and report a defined lint/typecheck/test command;
- perform a focused accessibility checklist against one completed screen.
Do not assign Haiku independent decisions about auth protocols, cookies, merge direction, identity uniqueness, account deletion, billing, Terraform, secrets, provider configuration, or security error handling.
Suggested bounded prompt:
Implement only [named component/test/copy task] from
doc/accounts-identity-ux-implementation-plan.md. The DTO, callbacks, state names, and copy in the
task are fixed; do not redesign authentication or add dependencies. Read AGENTS.md and the
matching frontend/testing/accessibility instructions. Preserve unrelated changes. Add/update the
focused component tests, run [exact commands], and report the files and results.
18.4 Review gates between agents¶
After every slice, the lead Opus/Sonnet agent reviews:
- identity source and authorization boundary;
- idempotency and failure checkpoints;
- account/guest data-loss possibilities;
- information leakage and account enumeration;
- session fixation/CSRF/open redirect risks;
- accessibility and localization of visible states;
- contract compatibility and rollback;
- whether tests prove the negative paths, not only success.
No later agent should proceed from an unreviewed central contract or a failing focused test suite.
19. Definition of done for the account release¶
The account release is done only when:
- guest play remains fully functional;
- email/password, Google, and personal Microsoft MSA work end to end; Facebook behaves correctly if enabled and is absent if disabled;
- a player can add every enabled method to one existing Verbolus account;
- no method is auto-linked by email and the final method cannot be removed;
- cookie-only progress can be kept, deferred/start-fresh, canceled, or merged without silent loss;
- duplicate Daily results, groups, display names, settings, aliases, exports, and deletion follow the documented deterministic rules;
- password change and recovery stay entirely within Entra/provider-hosted flows;
- session expiry, sign-out, and switching accounts cannot expose another user's data or impersonate an empty/lost account;
- verified-account export and deletion cover canonical and merged data;
- all sensitive actions require recent authentication and CSRF protection;
- Privacy/Terms/support documentation matches actual behavior;
- accessibility, localization, security negatives, focused tests, builds, and provider smoke tests pass;
- feature flags and rollback preserve existing account holders' ability to sign in, export, manage methods, and delete even if new account creation is paused.
20. Immediate account-management and discoverability handoff¶
Status: locked near-term UI design for the branch following the identity foundation. This section refines sections 4, 5, 6.13, and 6.18 for the current implementation. It does not reopen the identity or merge architecture.
20.1 Current implementation facts¶
/accountalready distinguishes guest, expired, and verified cookies and forwards the cookie server-side for player/settings reads.- The verified Account client already contains method removal, add-method, switch-account, and
sign-out behavior. Those controls are currently coupled in one
SignInMethodscomponent, which makes a failed or empty methods result look like a missing account UI. /settingscurrently has anAccountheading only for deletion. Its deletion explanation sayson this device, which is accurate for a guest profile but not for verified deletion across the canonical account's merge-alias closure.- The desktop menu is already right-aligned with
align="end"; retain and regression-test it rather than opening another implementation item. - Header Account visibility is feature-flagged and fetched after hydration, so a rollout-targeted user can briefly open the menu before the link appears.
- Auth telemetry and the local-password implementation are active work elsewhere. This section defines their UI integration points but must not create a second event vocabulary or password implementation.
20.2 Information architecture decision¶
Use one full manager and one summary:
/accountis the identity and current-device session control center: status, connected methods, local password action, add/remove method, switch account, and sign out.Settings > Accountis a concise status and method summary with a clear link to/account, plus the existing destructive deletion action at the bottom. Do not duplicate link/unlink/switch and password transaction logic insidesettings-form.tsx.- Keep the page and section names
Account; do not rename Settings or createSecurityfor this release. - Do not put a direct Sign out command in the global hamburger menu.
Menu → Account → Sign outis two deliberate actions, keeps the navigation menu stable for guests, and leaves enough room to explain that the device becomes a new guest profile.
20.3 Settings Account section¶
settings/page.tsx derives a small server-side account view model from the signed cookie and
fetchPlayerMe, using the same cookie-forwarding pattern as /account. Pass only renderable status,
provider category, masked label, and method count to the client form; do not pass raw player IDs,
issuer/subject pairs, or provider tokens merely to render a summary.
For this branch, extend the existing Account section in place at the bottom of the long Settings
form. Put status and method summary at the top of that section and keep deletion at the bottom of
the page and section, separated by spacing, a border, and a Danger zone subheading. A later
Settings-index refactor may move the Account navigation row without moving destructive actions into
the middle of an ordinary preferences form.
Guest state:
Account
Playing without an account
Your progress is saved in this browser. Create an account to keep it if you change devices.
[ Create account or sign in ]
────────────────────────
Danger zone
Delete the Verbolus data saved for this guest profile.
[ Delete my Verbolus data ]
Verified state:
Account
Signed in as Maya
Your progress is saved to your Verbolus account.
Sign-in methods
Google ma•••@gmail.com
Email & password ju•••@example.com
[ Manage account ]
────────────────────────
Danger zone
Permanently delete your Verbolus account and its saved plays, streaks, groups, and settings.
[ Delete Verbolus account ]
Expired state:
- say
Your session expired. Sign in again to access your saved Verbolus account.; - provide
Sign in againand a secondaryContinue as a guest; - do not render verified methods or account deletion from stale data;
- preserve the prior-account hint without displaying an email address.
Failure rules:
- Cookie/session status and method-fetch status are independent. If the cookie is verified but the
method read fails, keep
Signed inand showSign-in methods are temporarily unavailable.plusManage account; do not silently render the guest card. - An empty method array for a verified account is an invariant/error state, not
No methods connected. Show the same unavailable state and emit the existing operational diagnostic. - Use
Create account or sign in, not onlySign in, for a guest because the Entra page owns both.
20.4 /account verified layout¶
Split the current client component into independent visual/behavioral regions so one failed read cannot hide unrelated actions:
- Status —
Signed in as MayaandYour progress is saved to your Verbolus account. - Sign-in methods — one row/card per returned method, with friendly provider and masked label.
- Add a sign-in method — one full-width secondary action after the list.
- This device —
Switch accountandSign out on this device. - Privacy and data — a normal link to the Settings Account danger zone; do not duplicate the deletion dialog on both pages in this slice.
Method-row rules:
- Local row label:
Email & password; showChange passwordonly on this row. - Google, Microsoft, and Facebook rows remain visible as connected methods, but receive no provider-specific password/profile-management UI.
- Keep existing Remove behavior when another method remains. The final method explains why Remove is unavailable.
- Method-list loading/failure/empty-invariant states occupy the list region only. Add/switch/sign-out
availability derives from verified session state, not from
methods.length. - Place success/error notices directly below the Account heading in an announced status region. Query-string messages must be consumed or replaced after display so refresh does not repeat a stale success message.
20.5 Sign out on this device¶
Use an outline/secondary button, not destructive red: sign-out does not delete the account.
- Player selects
Sign out on this device. - Show a confirmation dialog:
Sign out on this device?
Your Verbolus account and saved progress will remain. This device will start with a new guest
profile. This won't sign you out of Google, Microsoft, or Facebook.
[ Cancel ] [ Sign out ]
- Cancel closes the dialog without changing cookies or navigation.
- Confirm disables both actions, labels the primary action
Signing out…, and posts to the current BFF sign-out route. - On success, replace the verified cookie with a fresh anonymous profile exactly once, clear pending
auth cookies, redirect to
/, and announceSigned out. You're now playing as a guest. - On failure, remain signed in, restore the actions, and show
We couldn't sign you out. Please try again.Never navigate optimistically before the response succeeds. Switch accountremains separate and uses the provider account picker. Do not implement switching as sign-out followed by ordinary sign-in, because provider SSO may immediately select the same account.
20.6 Local password action¶
Follow section 6.13 and the active password-work branch. The UI contract is:
- render
Change passwordonly when at least one connected method has categoryLocal; - use an ordinary secondary action within the Local row, not a page-wide danger action;
- explain that Microsoft hosts the credential flow before redirecting;
- preserve
/accountas the validated return path; - cancellation leaves the Verbolus session and methods unchanged;
- never show success solely because a normal OIDC callback succeeded;
- never add password fields, Graph password proxying, or
Directory.AccessAsUser.Allas an incidental UI implementation detail.
Before merge, prove the exact Entra browser-delegated journey with the configured customer tenant:
local method detection, SSPR enabled, hosted reset link visible, cancellation, completed reset,
return routing, and subsequent sign-in with the new password. If the platform exposes only the
hosted Forgot password? entry, retain the Change password user intent but show the instructional
interstitial from section 6.13.
20.7 Account discovery and guest prompts¶
Do not add an account banner to a first-time home page. The first visit should still answer one question—what can I play?—and account creation remains optional.
Use this discovery ladder instead:
- Persistent, quiet: Account appears in the menu whenever
AccountsUiis enabled; Settings always includes the Account section. - Intentional: Scorecard and Groups may show a small guest status card because visiting those surfaces demonstrates interest in saved history/social continuity.
- Contextual: after a completed puzzle, a meaningful streak, or successful group activity, show one dismissible prompt at the next natural pause—not over the board.
- Required later: subscription checkout asks for sign-in only when the player elects to begin an account-bound purchase.
The first contextual prompt may appear after the first completed saved game or on the next home visit, but never on the untouched initial home page. Recommended copy:
Keep your progress across devices
Create an account or sign in to keep your saved games and future streaks if you change devices.
[ Create account or sign in ] [ Not now ]
Dismissal and frequency follow section 5. Do not add a prompt based only on cookie age, page views, or an arbitrary timer. Verified users never see guest prompts.
20.8 Header feature-loading decision¶
The alignment bug is complete: retain align="end" and add/keep a regression assertion.
For the Account-link flash, accept the brief fail-closed omission during targeted rollout rather
than blocking or delaying the entire navigation menu. Once Accounts UI is released to everyone,
remove the conditional link gating and the flash disappears. If the flag must remain targeted for a
long period, seed HeaderMenu with server-evaluated features from dynamic pages; do not make static
content pages wait on the backend merely to render their navigation.
20.9 Telemetry integration boundary¶
Sonnet's active auth-telemetry work owns event names and shared properties. UI implementation in
this section must call that existing contract rather than introducing parallel trackEvent names.
It needs to distinguish these product states:
- entry surface: menu Account, Settings Account, Account page, contextual prompt, or required action;
- user intent: start sign-in, add method, change password, switch account, sign out, or delete;
- terminal outcome: completed, canceled, recoverable failure, blocked, or abandoned/expired where the server can authoritatively determine it;
- prompt reason and dismissal, using fixed low-cardinality values.
Security/operation outcomes belong on the authoritative BFF/backend path and correlate with existing request/dependency traces. Browser-only impressions and clicks remain subject to analytics consent. Never include email/masked email, display name, issuer, subject, player ID, cookie, authorization code, tokens, password data, free-form provider errors, or return URLs in event properties.
20.10 Accessibility and failure acceptance¶
- Account status, method-load errors, password returns, unlink results, and sign-out results use
appropriate
role="status"orrole="alert"live regions without stealing focus. - Dialogs have a visible title/description, initial focus on Cancel for deletion and sign-out, Escape support, focus containment, and trigger focus restoration.
- Method rows and actions remain usable at 200% zoom and narrow mobile widths; masked labels wrap rather than forcing horizontal scrolling.
- Loading labels use the typographic ellipsis consistently and buttons cannot submit twice.
- Provider/category labels are localized display strings; internal category values are never shown as fallback copy to players.
20.11 Required focused tests¶
Settings component/server tests:
- guest, verified, expired, method-read failure, and verified-empty-invariant renderings;
- guest versus verified deletion wording and button labels;
- only the summary DTO reaches the client component;
Manage accountandCreate account or sign indestinations preserve safe return behavior.
Account component tests:
- all supported method categories render friendly labels and masked values;
- Local alone receives
Change password; - method failure does not hide add/switch/sign-out controls;
- last-method Remove explanation and multi-method Remove behavior;
- sign-out confirmation cancel/success/failure/double-submit and focus restoration;
- switch and sign-out remain distinct operations.
Navigation/prompt tests:
- desktop menu remains end-aligned and mobile/desktop Account visibility agrees after flags resolve;
- first untouched home visit has no account banner;
- eligible guest prompt render/dismiss/suppression and verified-user exclusion;
- no PII appears in UI telemetry calls or rendered signed-out states.
20.12 Immediate Opus/Sonnet implementation order¶
- Preserve the already-landed menu alignment and sign-out route fixes; verify deployment before duplicating them.
- Introduce the server-derived Settings account view model and render guest/verified/expired/error summaries with correct deletion copy.
- Refactor
/accountinto independent Status, Methods, and This device regions; fix explicit method loading/error/empty states. - Wire the active local-password work into the Local row after its Entra acceptance tests pass.
- Add the sign-out confirmation and success/failure experience around the existing BFF route.
- Integrate the existing telemetry contract at the defined intent/outcome points without renaming or duplicating Sonnet's events.
- Add contextual guest prompting only after the management surfaces are stable; do not block the branch on a first-home banner.
- Run focused Vitest/Testing Library tests, then lint, TypeScript, build, mobile/desktop keyboard checks, and a real Entra local-account password smoke test.