NSA-9931: Fix Entra registration race condition

[AhmadiRamin]

Summary

Fixes NSA-9931 (Unlinked Entra accounts): two concurrent Entra registration attempts for the same email could both pass CreateUserUseCase's duplicate check before either committed, creating orphaned duplicate [user] rows. Confirmed live in production (a real duplicate pair found during investigation).

• Adds a unique index on [user].email (IDX__user__email__unique) — the first EF Core migration ever scaffolded for DbDirectoriesContext. See migrations/README.md for the baselining requirement before this can be applied to the live database.
• Makes CreateUserUseCase recover from the resulting DbUpdateException by resolving to the concurrent winner's user ID instead of failing.
• Adds audit logging in TokenIssuanceStartHandler for permanent (non-self-healing) linking failures, with wording that distinguishes genuinely permanent failures from ones that may self-heal on retry.

Not included in this PR

• The 3 known existing duplicate email groups have NOT been remediated. The migration will fail with a duplicate-key error if applied while they still exist. Manual DBA remediation is required first (including 4 tables that reference user.sub with no FK constraint) — see the plan's Rollout order section for detail.
• __EFMigrationsHistory baselining for this database has not been performed — see migrations/README.md.
• A pre-existing, unrelated schema drift (email/given_name modeled as nvarchar vs the live varchar) is flagged for a separate follow-up ticket, not fixed here.

Design & implementation record

Full investigation, design decisions, and implementation plan: see docs/superpowers/specs/2026-08-03-nsa-9931-unlinked-entra-accounts-design.md and docs/superpowers/plans/2026-08-03-nsa-9931-fix-registration-race.md in the login.dfe.node workspace repo.

Test plan

• dotnet build dsi-platform.sln — clean, including the migrations project
• Full dotnet test suite passes, including new tests for the race-recovery and audit-failure-isolation paths
• DBA review of the migration baselining plan
• Manual remediation of the 3 known duplicate groups before this migration is applied to any environment

[Copilot]

Pull request overview

Fixes a production race in Entra-driven registration/linking by enforcing email uniqueness at the database level and making the registration flow resilient to concurrent creates, while adding audit visibility for link failures.

Changes:

• Added a unique index on user.email via EF Core model configuration and a new Directories migration.
• Updated CreateUserUseCase to recover from unique-constraint DbUpdateException by resolving the “race winner” user ID.
• Added audit logging in TokenIssuanceStartHandler for non-success linking outcomes, plus unit tests covering the new paths.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Dfe.SignIn.Gateways.EntityFramework.UnitTests/UserEntityConfigurationTests.cs	Adds SQLite-backed test to prove the EF unique email index is enforced.
tests/Dfe.SignIn.Gateways.EntityFramework.UnitTests/Dfe.SignIn.Gateways.EntityFramework.UnitTests.csproj	Adds EF Core SQLite provider dependency for relational constraint testing.
tests/Dfe.SignIn.Fn.AuthExtensions.UnitTests/TokenIssuanceStartHandlerTests.cs	Adds tests verifying audit write/rethrow behavior and audit isolation on failure.
tests/Dfe.SignIn.Core.UseCases.UnitTests/Users/CreateUserUseCaseTests.cs	Adds tests for “race winner” recovery and rethrow behavior when recovery isn’t possible.
src/Dfe.SignIn.Gateways.EntityFramework/Configuration/Directories/UserEntityConfiguration.cs	Adds unique index on UserEntity.Email.
src/Dfe.SignIn.Fn.AuthExtensions/OnTokenIssuanceStart/TokenIssuanceStartHandler.cs	Adds audit logging for specific linking failures and ensures audit errors don’t mask the original exception.
src/Dfe.SignIn.Core.UseCases/Users/CreateUserUseCase.cs	Implements post-DbUpdateException recovery by querying for the now-existing user row.
src/Dfe.SignIn.Core.Contracts/Audit/AuditConstants.cs	Introduces AuditAuthEventNames.LinkFailed.
migrations/README.md	Documents baselining requirements for first migrations on pre-existing databases.
migrations/migrations.csproj	Updates migrations project metadata (including ProjectGuid).
migrations/Directories/DbDirectoriesContextModelSnapshot.cs	Adds email unique index to the Directories model snapshot.
migrations/Directories/20260803140316_AddUniqueIndexToUserEmail.Designer.cs	Adds designer output for the unique email index migration.
migrations/Directories/20260803140316_AddUniqueIndexToUserEmail.cs	Adds migration creating the unique email index.
migrations/Directories/20260803140253_InitialCreate.Designer.cs	Adds baseline “InitialCreate” migration designer for Directories context.
migrations/Directories/20260803140253_InitialCreate.cs	Adds baseline “InitialCreate” migration with safety warnings.
dsi-platform.sln	Adds the migrations project to the solution.
Directory.Packages.props	Pins Microsoft.EntityFrameworkCore.Sqlite for test usage.

Files not reviewed (2)

• migrations/Directories/20260803140253_InitialCreate.Designer.cs: Generated file
• migrations/Directories/20260803140316_AddUniqueIndexToUserEmail.Designer.cs: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AhmadiRamin]

Update: removed the EF Core migrations (InitialCreate baseline + AddUniqueIndexToUserEmail) from this PR.

They required baselining __EFMigrationsHistory for DbDirectoriesContext's first-ever migration just to land one index - a real deployment hazard needing DBA sign-off. Since Fn.AuthExtensions never actually wires up the local EF-backed CreateUserUseCase for the live token-issuance path (that dispatches to Node - see login.dfe.directories#383), the only thing that needs to change for real is the physical index in the Directories database. That's now a plain SQL script in login.dfe.db-scripts instead: schema/dirs-db/NSA-9931_create_unique_index_user_email.sql.

UserEntityConfiguration.cs's HasIndex(...).IsUnique() and its SQLite unit test are unchanged - kept as documentation of the constraint for dsi-platform's own EF model, for whenever CreateUserUseCase's path goes live.

Also fixed a build break: a Copilot Autofix suggestion applied directly to this branch (commit 0c90c77) left a duplicated outcomeGuidance declaration in TokenIssuanceStartHandler.cs (CS0128). Merged it into the single, more complete version.

[AhmadiRamin]

Addressed the other Copilot finding too (CreateUserUseCase.cs race-recovery): the catch is now gated to actual unique-constraint violations only (not any DbUpdateException), and the winner lookup requires matching both email and entra_oid — a partial match (email reused by a different Entra identity) now surfaces the original exception instead of risking an ambiguous SingleOrDefaultAsync throw or a silent cross-identity resolution. Two new tests cover both cases; existing race test corrected to model a genuine same-identity race.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/Dfe.SignIn.Core.UseCases/Users/CreateUserUseCase.cs:90

• In the unique-constraint recovery path, newUser is still tracked as Added. If this DbContext is reused later in the same scope, a subsequent SaveChangesAsync will try to insert it again and can re-trigger the unique constraint violation. Detach/remove the pending entity before returning the race-winner.

            return new CreateUserResponse {
                UserId = raceWinner.Sub
            };
        }

src/Dfe.SignIn.Core.Contracts/Audit/AuditConstants.cs:75

• AuditAuthEventNames.LinkFailed is used for both permanent linking conflicts and potentially self-healing failures (e.g., a registration race). The XML summary currently states it is a permanent failure, which is misleading for consumers of the audit taxonomy.

    /// <summary>
    /// Indicates that linking an Entra account to a DfE Sign-In user permanently failed.
    /// </summary>
    public const string LinkFailed = "link-failed";