From cdf64b2a10c3427ee11409a0ddb63dcf022fde51 Mon Sep 17 00:00:00 2001 From: Heimdall Date: Sat, 14 Nov 2026 06:48:43 +0000 Subject: [PATCH] Account merge saga: Confirm with consent record and sealed proofs, one crash-safe step function for the Heimdall move and reversal, one merge loop AccountMergeSaga is the only caller of the move client and the only writer of Confirmed, HeimdallMoved, Failed, UndoRequested and HeimdallReversed; the ledger keeps Committed, Final and Undone. Migration AddAccountMergeSaga adds the saga columns and the two move-id keys; its Down is roll-forward only. AccountMergeSweeper becomes the one loop: saga advance, then finalize, every 30 s. Co-Authored-By: Claude Sonnet 5.5 --- src/Bifrost.Web/Data/BifrostDbContext.cs | 11 + .../20261114130000_AddAccountMergeSaga.cs | 78 +++ .../BifrostDbContextModelSnapshot.cs | 68 +++ src/Bifrost.Web/Domain/AccountMergeModels.cs | 42 ++ .../Heimdall/HeimdallIdentityMoveClient.cs | 2 +- .../Features/Membership/AccountMergeLedger.cs | 54 +- .../Features/Membership/AccountMergeSaga.cs | 475 ++++++++++++++++++ src/Bifrost.Web/Program.cs | 1 + 8 files changed, 726 insertions(+), 5 deletions(-) create mode 100644 src/Bifrost.Web/Data/Migrations/20261114130000_AddAccountMergeSaga.cs create mode 100644 src/Bifrost.Web/Features/Membership/AccountMergeSaga.cs diff --git a/src/Bifrost.Web/Data/BifrostDbContext.cs b/src/Bifrost.Web/Data/BifrostDbContext.cs index 544d770..7b0a20d 100644 --- a/src/Bifrost.Web/Data/BifrostDbContext.cs +++ b/src/Bifrost.Web/Data/BifrostDbContext.cs @@ -635,6 +635,17 @@ public sealed class BifrostDbContext(DbContextOptions options) // State is the token: a transition computed from a stale read (the sweeper's Final over a saga's UndoRequested) fails its save. entity.Property(x => x.State).HasConversion().HasMaxLength(24).IsConcurrencyToken(); entity.Property(x => x.FailureCode).HasMaxLength(64); + entity.Property(x => x.HeimdallMoveId).HasMaxLength(64); + entity.Property(x => x.HeimdallReverseMoveId).HasMaxLength(64); + entity.Property(x => x.PreviewDigest).HasMaxLength(64); + entity.Property(x => x.SurvivorProofProvider).HasMaxLength(32); + entity.Property(x => x.FoldedProofProviders).HasMaxLength(120); + entity.Property(x => x.ProofFromTier).HasMaxLength(8); + entity.Property(x => x.ProofToTier).HasMaxLength(8); + entity.Property(x => x.LastOutcome).HasMaxLength(64); + // Heimdall's idempotency keys: one merge, one forward key and one reverse key, and no key shared by two merges. + entity.HasIndex(x => x.HeimdallMoveId).IsUnique().HasFilter("\"HeimdallMoveId\" IS NOT NULL"); + entity.HasIndex(x => x.HeimdallReverseMoveId).IsUnique().HasFilter("\"HeimdallReverseMoveId\" IS NOT NULL"); entity.HasIndex(x => new { x.FoldedUserAccountId, x.State }); // An account is folded once: the DB refuses a second live merge folding it. The cross-role case (a survivor that is also // folded) cannot be one unique index; the migration's trigger refuses it. diff --git a/src/Bifrost.Web/Data/Migrations/20261114130000_AddAccountMergeSaga.cs b/src/Bifrost.Web/Data/Migrations/20261114130000_AddAccountMergeSaga.cs new file mode 100644 index 0000000..cb0b5fb --- /dev/null +++ b/src/Bifrost.Web/Data/Migrations/20261114130000_AddAccountMergeSaga.cs @@ -0,0 +1,78 @@ +using System; +using Microsoft.EntityFrameworkCore.Infrastructure; +using Microsoft.EntityFrameworkCore.Migrations; + +#nullable disable + +namespace Bifrost.Web.Data.Migrations +{ + // Hand-written like AddAccountMerges, the snapshot edited to match. Additive: the saga's columns on AccountMerges. Down is + // roll-forward only, like AddAccountMerges: it drops the Heimdall idempotency keys and the consent record, so it refuses while + // any merge row exists (heimdall-body:ruling:merge-roll-forward-only). + [DbContext(typeof(BifrostDbContext))] + [Migration("20261114130000_AddAccountMergeSaga")] + public partial class AddAccountMergeSaga : Migration + { + private static readonly string[] Columns = + [ + "HeimdallMoveId", "HeimdallReverseMoveId", "SealedProofs", "PreviewDigest", "ConfirmedByUserAccountId", "ConfirmedUtc", + "SurvivorProofProvider", "FoldedProofProviders", "ProofFromTier", "ProofToTier", "MovedIdentityIds", "Attempts", + "NextAttemptUtc", "LastOutcome", "UndoRequestedUtc", "ReversedUtc" + ]; + + /// + protected override void Up(MigrationBuilder migrationBuilder) + { + migrationBuilder.AddColumn(name: "HeimdallMoveId", table: "AccountMerges", type: "character varying(64)", maxLength: 64, nullable: true); + migrationBuilder.AddColumn(name: "HeimdallReverseMoveId", table: "AccountMerges", type: "character varying(64)", maxLength: 64, nullable: true); + migrationBuilder.AddColumn(name: "SealedProofs", table: "AccountMerges", type: "text", nullable: true); + migrationBuilder.AddColumn(name: "PreviewDigest", table: "AccountMerges", type: "character varying(64)", maxLength: 64, nullable: false, defaultValue: ""); + migrationBuilder.AddColumn(name: "ConfirmedByUserAccountId", table: "AccountMerges", type: "uuid", nullable: true); + migrationBuilder.AddColumn(name: "ConfirmedUtc", table: "AccountMerges", type: "timestamp with time zone", nullable: true); + migrationBuilder.AddColumn(name: "SurvivorProofProvider", table: "AccountMerges", type: "character varying(32)", maxLength: 32, nullable: false, defaultValue: ""); + migrationBuilder.AddColumn(name: "FoldedProofProviders", table: "AccountMerges", type: "character varying(120)", maxLength: 120, nullable: false, defaultValue: ""); + migrationBuilder.AddColumn(name: "ProofFromTier", table: "AccountMerges", type: "character varying(8)", maxLength: 8, nullable: true); + migrationBuilder.AddColumn(name: "ProofToTier", table: "AccountMerges", type: "character varying(8)", maxLength: 8, nullable: true); + migrationBuilder.AddColumn(name: "MovedIdentityIds", table: "AccountMerges", type: "text", nullable: true); + migrationBuilder.AddColumn(name: "Attempts", table: "AccountMerges", type: "integer", nullable: false, defaultValue: 0); + migrationBuilder.AddColumn(name: "NextAttemptUtc", table: "AccountMerges", type: "timestamp with time zone", nullable: true); + migrationBuilder.AddColumn(name: "LastOutcome", table: "AccountMerges", type: "character varying(64)", maxLength: 64, nullable: false, defaultValue: ""); + migrationBuilder.AddColumn(name: "UndoRequestedUtc", table: "AccountMerges", type: "timestamp with time zone", nullable: true); + migrationBuilder.AddColumn(name: "ReversedUtc", table: "AccountMerges", type: "timestamp with time zone", nullable: true); + + migrationBuilder.CreateIndex( + name: "IX_AccountMerges_HeimdallMoveId", + table: "AccountMerges", + column: "HeimdallMoveId", + unique: true, + filter: "\"HeimdallMoveId\" IS NOT NULL"); + + migrationBuilder.CreateIndex( + name: "IX_AccountMerges_HeimdallReverseMoveId", + table: "AccountMerges", + column: "HeimdallReverseMoveId", + unique: true, + filter: "\"HeimdallReverseMoveId\" IS NOT NULL"); + } + + /// + protected override void Down(MigrationBuilder migrationBuilder) + { + migrationBuilder.Sql(@" +DO $$ +BEGIN + IF EXISTS (SELECT 1 FROM ""AccountMerges"") THEN + RAISE EXCEPTION 'AddAccountMergeSaga cannot be reverted once an account merge exists: Bifrost is roll-forward only'; + END IF; +END +$$;"); + + migrationBuilder.DropIndex(name: "IX_AccountMerges_HeimdallMoveId", table: "AccountMerges"); + migrationBuilder.DropIndex(name: "IX_AccountMerges_HeimdallReverseMoveId", table: "AccountMerges"); + foreach (var column in Columns) + { + migrationBuilder.DropColumn(name: column, table: "AccountMerges"); + } + } + } +} diff --git a/src/Bifrost.Web/Data/Migrations/BifrostDbContextModelSnapshot.cs b/src/Bifrost.Web/Data/Migrations/BifrostDbContextModelSnapshot.cs index 3966dd3..2d1d304 100644 --- a/src/Bifrost.Web/Data/Migrations/BifrostDbContextModelSnapshot.cs +++ b/src/Bifrost.Web/Data/Migrations/BifrostDbContextModelSnapshot.cs @@ -28,9 +28,18 @@ namespace Bifrost.Web.Data.Migrations .ValueGeneratedOnAdd() .HasColumnType("uuid"); + b.Property("Attempts") + .HasColumnType("integer"); + b.Property("CommittedUtc") .HasColumnType("timestamp with time zone"); + b.Property("ConfirmedByUserAccountId") + .HasColumnType("uuid"); + + b.Property("ConfirmedUtc") + .HasColumnType("timestamp with time zone"); + b.Property("CreatedUtc") .HasColumnType("timestamp with time zone"); @@ -45,24 +54,75 @@ namespace Bifrost.Web.Data.Migrations b.Property("FinalizedUtc") .HasColumnType("timestamp with time zone"); + b.Property("FoldedProofProviders") + .IsRequired() + .HasMaxLength(120) + .HasColumnType("character varying(120)"); + b.Property("FoldedUserAccountId") .HasColumnType("uuid"); b.Property("GraceEndsUtc") .HasColumnType("timestamp with time zone"); + b.Property("HeimdallMoveId") + .HasMaxLength(64) + .HasColumnType("character varying(64)"); + + b.Property("HeimdallReverseMoveId") + .HasMaxLength(64) + .HasColumnType("character varying(64)"); + + b.Property("LastOutcome") + .IsRequired() + .HasMaxLength(64) + .HasColumnType("character varying(64)"); + + b.Property("MovedIdentityIds") + .HasColumnType("text"); + + b.Property("NextAttemptUtc") + .HasColumnType("timestamp with time zone"); + + b.Property("PreviewDigest") + .IsRequired() + .HasMaxLength(64) + .HasColumnType("character varying(64)"); + + b.Property("ProofFromTier") + .HasMaxLength(8) + .HasColumnType("character varying(8)"); + + b.Property("ProofToTier") + .HasMaxLength(8) + .HasColumnType("character varying(8)"); + + b.Property("ReversedUtc") + .HasColumnType("timestamp with time zone"); + + b.Property("SealedProofs") + .HasColumnType("text"); + b.Property("State") .IsConcurrencyToken() .IsRequired() .HasMaxLength(24) .HasColumnType("character varying(24)"); + b.Property("SurvivorProofProvider") + .IsRequired() + .HasMaxLength(32) + .HasColumnType("character varying(32)"); + b.Property("SurvivorUserAccountId") .HasColumnType("uuid"); b.Property("UndoneUtc") .HasColumnType("timestamp with time zone"); + b.Property("UndoRequestedUtc") + .HasColumnType("timestamp with time zone"); + b.HasKey("Id"); b.HasIndex("FoldedUserAccountId") @@ -72,6 +132,14 @@ namespace Bifrost.Web.Data.Migrations b.HasIndex("FoldedUserAccountId", "State"); + b.HasIndex("HeimdallMoveId") + .IsUnique() + .HasFilter("\"HeimdallMoveId\" IS NOT NULL"); + + b.HasIndex("HeimdallReverseMoveId") + .IsUnique() + .HasFilter("\"HeimdallReverseMoveId\" IS NOT NULL"); + b.HasIndex("State", "GraceEndsUtc"); b.HasIndex("SurvivorUserAccountId", "State"); diff --git a/src/Bifrost.Web/Domain/AccountMergeModels.cs b/src/Bifrost.Web/Domain/AccountMergeModels.cs index 619d45b..cadcac2 100644 --- a/src/Bifrost.Web/Domain/AccountMergeModels.cs +++ b/src/Bifrost.Web/Domain/AccountMergeModels.cs @@ -62,6 +62,48 @@ public sealed class AccountMerge public string FailureCode { get; set; } = string.Empty; + // ---- the saga's columns (AccountMergeSaga is their one writer; docs/account-merge.md, Saga) ---- + + /// Heimdall's idempotency key of the forward move: random, minted in the save that enters Confirmed, never derived from , never re-minted. + public string? HeimdallMoveId { get; set; } + + /// The same for the reversal, minted in the save that enters UndoRequested. + public string? HeimdallReverseMoveId { get; set; } + + /// The Heimdall bearers the move or reversal will replay, protected; non-null only from Confirmed/UndoRequested until Heimdall's final answer. + public string? SealedProofs { get; set; } + + /// Digest of the plan the member saw when confirming (MergePlan.Digest); with the next four columns it is the consent record. + public string PreviewDigest { get; set; } = string.Empty; + + public Guid? ConfirmedByUserAccountId { get; set; } + + public DateTimeOffset? ConfirmedUtc { get; set; } + + public string SurvivorProofProvider { get; set; } = string.Empty; + + /// The providers of the folded side's proofs, sorted and comma-joined. + public string FoldedProofProviders { get; set; } = string.Empty; + + /// The proof tiers Heimdall's receipt named (weak or strong); ProofToTier is null for a receipt without one. + public string? ProofFromTier { get; set; } + + public string? ProofToTier { get; set; } + + /// The logins the forward move carried, a JSON array of Heimdall identity ids, from the receipt. + public string? MovedIdentityIds { get; set; } + + public int Attempts { get; set; } + + public DateTimeOffset? NextAttemptUtc { get; set; } + + /// The last Heimdall answer's class or refusal code, or the saga's own stall code; never an input value. + public string LastOutcome { get; set; } = string.Empty; + + public DateTimeOffset? UndoRequestedUtc { get; set; } + + public DateTimeOffset? ReversedUtc { get; set; } + public ICollection Entries { get; set; } = []; } diff --git a/src/Bifrost.Web/Features/Heimdall/HeimdallIdentityMoveClient.cs b/src/Bifrost.Web/Features/Heimdall/HeimdallIdentityMoveClient.cs index f285ae2..af61e4e 100644 --- a/src/Bifrost.Web/Features/Heimdall/HeimdallIdentityMoveClient.cs +++ b/src/Bifrost.Web/Features/Heimdall/HeimdallIdentityMoveClient.cs @@ -87,7 +87,7 @@ public sealed partial class HeimdallIdentityMoveClient( private const int MaxMovedIdentities = 256; private const int MaxIdentityIdLength = 128; private const int MaxReceiptBytes = 64 * 1024; - private const int MaxProofLength = 8192; + public const int MaxProofLength = 8192; // \z, not $: $ also matches before a final line feed, which Heimdall's schema pattern refuses with a 400. [GeneratedRegex("^[A-Za-z0-9_-]{16,64}\\z")] diff --git a/src/Bifrost.Web/Features/Membership/AccountMergeLedger.cs b/src/Bifrost.Web/Features/Membership/AccountMergeLedger.cs index c84d6f8..b242101 100644 --- a/src/Bifrost.Web/Features/Membership/AccountMergeLedger.cs +++ b/src/Bifrost.Web/Features/Membership/AccountMergeLedger.cs @@ -26,7 +26,46 @@ public sealed record MergePlanEntry( public sealed record MergePlan( IReadOnlyList Blocks, IReadOnlyList Entries, - IReadOnlyDictionary Left); + IReadOnlyDictionary Left) +{ + /// + /// Lowercase hex SHA-256 over a canonical text of the plan, in plan order (Left by key): what the member saw, comparable at confirm. + /// Every field is length-prefixed, so no value can imitate a separator. The plan holds no account ids of its own, so the caller + /// names the pair the plan was made for. + /// + public string Digest(Guid survivorId, Guid foldedId) + { + var text = new System.Text.StringBuilder(); + void Field(string? value) => text.Append(value is null ? "-" : $"{value.Length}:{value}").Append('|'); + Field(survivorId.ToString("N")); + Field(foldedId.ToString("N")); + foreach (var entry in Entries) + { + Field(entry.Kind.ToString()); + Field(entry.Action.ToString()); + Field(entry.RecordId.ToString("N")); + Field(entry.PriorUserAccountId?.ToString("N")); + Field(entry.PriorText); + Field(entry.PriorAtUtc?.ToUniversalTime().ToString("O", CultureInfo.InvariantCulture)); + text.Append('\n'); + } + + text.Append("left\n"); + foreach (var (key, count) in Left.OrderBy(x => x.Key, StringComparer.Ordinal)) + { + Field(key); + Field(count.ToString(CultureInfo.InvariantCulture)); + } + + text.Append("\nblocks\n"); + foreach (var block in Blocks) + { + Field(block); + } + + return Convert.ToHexString(System.Security.Cryptography.SHA256.HashData(System.Text.Encoding.UTF8.GetBytes(text.ToString()))).ToLowerInvariant(); + } +} /// /// The one owner of what an account merge does to Bifrost records and of how an account stands under one: the plan, the Committed @@ -696,18 +735,25 @@ public sealed class AccountMergeLedger( } } -/// Finalizes merges past their grace every five minutes. Copies the SealedBallotCloser shape: a new scope per tick, a warning on failure. +/// +/// The one merge loop, every 30 seconds: the saga advances every due in-flight merge (confirm, replay, undo), then the ledger finalizes +/// merges past their grace. A new scope per tick, a warning on failure, the SealedBallotCloser shape. No second merge hosted service exists. +/// public sealed class AccountMergeSweeper(IServiceScopeFactory scopes, TimeProvider clock, ILogger logger) : BackgroundService { + public static readonly TimeSpan Tick = TimeSpan.FromSeconds(30); + protected override async Task ExecuteAsync(CancellationToken stoppingToken) { - using var timer = new PeriodicTimer(TimeSpan.FromMinutes(5)); + using var timer = new PeriodicTimer(Tick); do { try { using var scope = scopes.CreateScope(); - await scope.ServiceProvider.GetRequiredService().FinalizeDueAsync(clock.GetUtcNow(), stoppingToken); + var now = clock.GetUtcNow(); + await scope.ServiceProvider.GetRequiredService().AdvanceDueAsync(now, stoppingToken); + await scope.ServiceProvider.GetRequiredService().FinalizeDueAsync(now, stoppingToken); } catch (Exception error) when (error is not OperationCanceledException) { diff --git a/src/Bifrost.Web/Features/Membership/AccountMergeSaga.cs b/src/Bifrost.Web/Features/Membership/AccountMergeSaga.cs new file mode 100644 index 0000000..8281e9e --- /dev/null +++ b/src/Bifrost.Web/Features/Membership/AccountMergeSaga.cs @@ -0,0 +1,475 @@ +using System.Security.Cryptography; +using System.Text; +using System.Text.Json; +using System.Text.RegularExpressions; +using Bifrost.Web.Data; +using Bifrost.Web.Domain; +using Bifrost.Web.Features.Heimdall; +using Microsoft.AspNetCore.DataProtection; +using Microsoft.EntityFrameworkCore; +using Npgsql; + +namespace Bifrost.Web.Features.Membership; + +/// +/// A live Heimdall bearer a member redeemed from a fresh sign-in, with the Heimdall account and provider it came through. The token is a +/// secret: never prints it (nor the account id), so no log or exception that holds a proof can leak it. +/// +public sealed record MergeProof(string AccessToken, string HeimdallAccountId, string Provider) +{ + private bool PrintMembers(StringBuilder builder) + { + builder.Append($"Provider = {Provider}"); + return true; + } +} + +/// What the member confirmed: the pair, the plan digest they saw, and a proof for every login of each side that must speak. +public sealed record ConfirmMergeRequest( + Guid ActorUserAccountId, + Guid SurvivorUserAccountId, + Guid FoldedUserAccountId, + string PreviewDigest, + MergeProof SurvivorProof, + IReadOnlyList FoldedProofs); + +/// The closed answer to a confirm. Only Confirmed wrote a row. +public abstract record ConfirmOutcome +{ + private ConfirmOutcome() + { + } + + public sealed record Confirmed(Guid MergeId) : ConfirmOutcome; + + /// The plan's block codes (never account names), or merge_in_flight when the database refused an overlapping merge. + public sealed record Blocked(IReadOnlyList Codes) : ConfirmOutcome; + + public sealed record PreviewStale : ConfirmOutcome; + + public sealed record NotParty : ConfirmOutcome; + + public sealed record ProofAccountMismatch : ConfirmOutcome; +} + +/// The closed answer to an undo request. Only Requested wrote. +public abstract record UndoOutcome +{ + private UndoOutcome() + { + } + + public sealed record Requested : UndoOutcome; + + public sealed record NotCommitted : UndoOutcome; + + public sealed record GraceOver : UndoOutcome; + + public sealed record NotSurvivor : UndoOutcome; + + public sealed record ProofAccountMismatch : UndoOutcome; +} + +/// +/// The one owner of an account merge's lifecycle outside the ledger's Committed, Final and Undone, and the only caller of +/// . It inserts Confirmed (the consent record, with the Heimdall bearers sealed and the move +/// id minted), runs the one idempotent step function (move, commit, reverse, undo), and writes +/// HeimdallMoved, Failed, UndoRequested and HeimdallReversed. It never writes votes, memberships or journal rows (the ledger's), never +/// judges a proof's tier or freshness (Heimdall's), and reads no standing of its own: the plan's blocks and the database's live-merge +/// index answer overlap, and the writers that act for an account go through . +/// Every transition is one save guarded by State, the merge's concurrency token; the loser of a race reloads and continues from the +/// stored state. Heimdall's closed outcome is consumed as is: Unknown (a lost answer, an outage) is replayed with the same stored +/// move id and never fails a merge. Logs name the merge id, state, outcome class and refusal code only. +/// +public sealed partial class AccountMergeSaga( + BifrostDbContext dbContext, + AccountMergeLedger ledger, + HeimdallIdentityMoveClient mover, + IDataProtectionProvider dataProtection, + TimeProvider timeProvider, + ILogger logger) +{ + public const string MergeInFlight = "merge_in_flight"; + public const string ReceiptMismatch = "receipt_mismatch"; + public const string ProofsUnreadable = "proofs_unreadable"; + + private const string LiveMergeIndex = "UX_AccountMerges_FoldedUserAccountId_Live"; + private const int MaxProofs = 8; + + private static readonly TimeSpan[] Backoff = [TimeSpan.FromSeconds(15), TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(5), TimeSpan.FromMinutes(15)]; + private static readonly TimeSpan UnreadableRetry = TimeSpan.FromHours(1); + + private static readonly AccountMergeState[] DueStates = + [AccountMergeState.Confirmed, AccountMergeState.HeimdallMoved, AccountMergeState.UndoRequested, AccountMergeState.HeimdallReversed]; + + private readonly IDataProtector _seal = dataProtection.CreateProtector("Bifrost.AccountMerge.Proofs.v1"); + + private sealed record ProofSeal(List From, string? To); + + // ---- confirm ---- + + /// + /// The member's consent, as one insert. The actor must be one of the pair; the plan must have no blocks and be the one the member + /// saw (digest); every proof must be of its side's Heimdall account. Calls no Heimdall: the caller runs . + /// + public async Task ConfirmAsync(ConfirmMergeRequest request, CancellationToken cancellationToken) + { + RequireProofs(request.SurvivorProof, request.FoldedProofs); + if (request.ActorUserAccountId != request.SurvivorUserAccountId && request.ActorUserAccountId != request.FoldedUserAccountId) + { + return new ConfirmOutcome.NotParty(); + } + + try + { + return await AccountMergeLedger.WriteAsAsync(dbContext, request.ActorUserAccountId, _ => InsertConfirmedAsync(request, cancellationToken), cancellationToken); + } + catch (DbUpdateException error) when (IsLiveMergeViolation(error)) + { + dbContext.ChangeTracker.Clear(); + return new ConfirmOutcome.Blocked([MergeInFlight]); + } + } + + private async Task InsertConfirmedAsync(ConfirmMergeRequest request, CancellationToken cancellationToken) + { + var plan = await ledger.PlanAsync(request.SurvivorUserAccountId, request.FoldedUserAccountId, cancellationToken); + if (plan.Blocks.Count > 0) + { + return new ConfirmOutcome.Blocked(plan.Blocks); + } + + if (!string.Equals(plan.Digest(request.SurvivorUserAccountId, request.FoldedUserAccountId), request.PreviewDigest, StringComparison.Ordinal)) + { + return new ConfirmOutcome.PreviewStale(); + } + + var survivorHeimdall = await HeimdallAccountAsync(request.SurvivorUserAccountId, cancellationToken); + var foldedHeimdall = await HeimdallAccountAsync(request.FoldedUserAccountId, cancellationToken); + if (request.SurvivorProof.HeimdallAccountId != survivorHeimdall || request.FoldedProofs.Any(x => x.HeimdallAccountId != foldedHeimdall)) + { + return new ConfirmOutcome.ProofAccountMismatch(); + } + + var now = timeProvider.GetUtcNow(); + var merge = new AccountMerge + { + State = AccountMergeState.Confirmed, + SurvivorUserAccountId = request.SurvivorUserAccountId, + FoldedUserAccountId = request.FoldedUserAccountId, + CreatedUtc = now, + ConfirmedByUserAccountId = request.ActorUserAccountId, + ConfirmedUtc = now, + PreviewDigest = request.PreviewDigest, + SurvivorProofProvider = request.SurvivorProof.Provider, + FoldedProofProviders = string.Join(',', request.FoldedProofs.Select(x => x.Provider).Distinct(StringComparer.Ordinal).Order(StringComparer.Ordinal)), + // Heimdall's idempotency key: random, minted once here, read back from the row on every call, never derived from the merge id. + HeimdallMoveId = Guid.NewGuid().ToString("N"), + SealedProofs = Seal(request.FoldedProofs.Select(x => x.AccessToken), request.SurvivorProof.AccessToken), + LastOutcome = "confirmed" + }; + dbContext.AccountMerges.Add(merge); + await dbContext.SaveChangesAsync(cancellationToken); + logger.LogInformation("Account merge {MergeId} {State}", merge.Id, merge.State); + return new ConfirmOutcome.Confirmed(merge.Id); + } + + // ---- undo request ---- + + /// + /// The survivor's request to give the moved logins back, inside the grace and with fresh survivor proofs. One save: UndoRequested, a + /// freshly minted reverse move id, the sealed proofs. Losing the race to the Final sweep is the State token's, answered GraceOver. + /// + public async Task RequestUndoAsync( + Guid mergeId, Guid actorUserAccountId, IReadOnlyList survivorProofs, CancellationToken cancellationToken) + { + RequireProofs(null, survivorProofs); + try + { + return await AccountMergeLedger.WriteAsAsync(dbContext, actorUserAccountId, _ => WriteUndoRequestedAsync(mergeId, actorUserAccountId, survivorProofs, cancellationToken), cancellationToken); + } + catch (DbUpdateConcurrencyException) + { + dbContext.ChangeTracker.Clear(); + return new UndoOutcome.GraceOver(); + } + } + + private async Task WriteUndoRequestedAsync( + Guid mergeId, Guid actorUserAccountId, IReadOnlyList survivorProofs, CancellationToken cancellationToken) + { + var merge = await LoadAsync(mergeId, cancellationToken); + if (merge is null) + { + return new UndoOutcome.NotCommitted(); + } + + var now = timeProvider.GetUtcNow(); + if (actorUserAccountId != merge.SurvivorUserAccountId) + { + return new UndoOutcome.NotSurvivor(); + } + + if (merge.State == AccountMergeState.Final || merge.FinalizedUtc is not null) + { + return new UndoOutcome.GraceOver(); + } + + if (merge.State != AccountMergeState.Committed) + { + return new UndoOutcome.NotCommitted(); + } + + if (merge.GraceEndsUtc is not { } graceEnds || now >= graceEnds) + { + return new UndoOutcome.GraceOver(); + } + + var survivorHeimdall = await HeimdallAccountAsync(merge.SurvivorUserAccountId, cancellationToken); + if (survivorProofs.Any(x => x.HeimdallAccountId != survivorHeimdall)) + { + return new UndoOutcome.ProofAccountMismatch(); + } + + merge.State = AccountMergeState.UndoRequested; + merge.UndoRequestedUtc = now; + merge.HeimdallReverseMoveId = Guid.NewGuid().ToString("N"); + merge.SealedProofs = Seal(survivorProofs.Select(x => x.AccessToken), null); + merge.Attempts = 0; + merge.NextAttemptUtc = null; + merge.LastOutcome = "undo_requested"; + await dbContext.SaveChangesAsync(cancellationToken); + logger.LogInformation("Account merge {MergeId} {State}", merge.Id, merge.State); + return new UndoOutcome.Requested(); + } + + // ---- the step function ---- + + /// + /// The one step function: confirm's inline advance, the sweeper's resume after a crash and an undo request all run it. From the + /// stored state it makes the Heimdall move (or reversal) under the stored id, records the answer, and calls the ledger's commit (or + /// local undo). Idempotent: every state has one next step and every step is safe to repeat. Other states are a no-op. + /// + public async Task AdvanceAsync(Guid mergeId, CancellationToken cancellationToken) + { + for (var lost = 0; ; lost++) + { + try + { + return await AdvanceOnceAsync(mergeId, cancellationToken); + } + catch (DbUpdateConcurrencyException) when (lost < 2) + { + // Another advancer saved first: forget what this context staged and continue from the stored state. + dbContext.ChangeTracker.Clear(); + } + } + } + + private async Task AdvanceOnceAsync(Guid mergeId, CancellationToken cancellationToken) + { + var merge = await LoadAsync(mergeId, cancellationToken) ?? throw new InvalidOperationException($"Merge {mergeId} does not exist."); + if (merge.State is AccountMergeState.Confirmed or AccountMergeState.UndoRequested) + { + merge = await MoveAsync(merge, cancellationToken); + } + + return merge.State switch + { + AccountMergeState.HeimdallMoved => await ledger.CommitAsync(merge.Id, cancellationToken), + AccountMergeState.HeimdallReversed => await ledger.UndoLocalAsync(merge.Id, cancellationToken), + _ => merge + }; + } + + private async Task MoveAsync(AccountMerge merge, CancellationToken cancellationToken) + { + if (merge.LastOutcome == ReceiptMismatch) + { + return merge; // Heimdall answered, wrongly, and its proofs are wiped: replay can only repeat the same answer. + } + + var forward = merge.State == AccountMergeState.Confirmed; + var now = timeProvider.GetUtcNow(); + if (Open(merge.SealedProofs) is not { } proofs) + { + // The key ring is lost or rotated out. Heimdall may already have moved, so nothing changes but the retry time. + merge.LastOutcome = ProofsUnreadable; + merge.NextAttemptUtc = now + UnreadableRetry; + await dbContext.SaveChangesAsync(cancellationToken); + logger.LogError("Account merge {MergeId} {State}: sealed proofs unreadable", merge.Id, merge.State); + return merge; + } + + var request = forward + ? new HeimdallMoveRequest(merge.HeimdallMoveId!, proofs.From, proofs.To) + : new HeimdallMoveRequest(merge.HeimdallReverseMoveId!, proofs.From, ReversesMoveId: merge.HeimdallMoveId); + var outcome = await mover.MoveAsync(request, cancellationToken); + var code = outcome is HeimdallMoveOutcome.Refused refused ? RefusalCode(refused.Code) : null; + switch (outcome) + { + case HeimdallMoveOutcome.Moved moved: + // The leg's destination is the survivor going forward and the folded account coming back. + var destination = await HeimdallAccountAsync(forward ? merge.SurvivorUserAccountId : merge.FoldedUserAccountId, cancellationToken); + merge.SealedProofs = null; + if (moved.Receipt.AccountId != destination) + { + merge.LastOutcome = ReceiptMismatch; + break; + } + + merge.Attempts = 0; + merge.NextAttemptUtc = null; + merge.LastOutcome = "moved"; + if (forward) + { + merge.State = AccountMergeState.HeimdallMoved; + merge.ProofFromTier = Tier(moved.Receipt.ProofFrom); + merge.ProofToTier = moved.Receipt.ProofTo is { } to ? Tier(to) : null; + merge.MovedIdentityIds = JsonSerializer.Serialize(moved.Receipt.MovedIdentityIds); + } + else + { + merge.State = AccountMergeState.HeimdallReversed; + merge.ReversedUtc = now; + } + + break; + case HeimdallMoveOutcome.Refused: + // Heimdall applied nothing before a 4xx. A forward refusal ends the merge; a refused undo leaves it as it was. + merge.SealedProofs = null; + merge.NextAttemptUtc = null; + if (forward) + { + merge.State = AccountMergeState.Failed; + merge.FailedUtc = now; + merge.FailureCode = code!; + merge.LastOutcome = "refused"; + } + else + { + merge.State = AccountMergeState.Committed; + merge.LastOutcome = "undo_" + code; + } + + break; + case HeimdallMoveOutcome.Unknown unknown: + merge.Attempts++; + merge.NextAttemptUtc = now + Backoff[Math.Min(merge.Attempts, Backoff.Length) - 1]; + merge.LastOutcome = unknown.Reason.Length > 64 ? unknown.Reason[..64] : unknown.Reason; + break; + } + + await dbContext.SaveChangesAsync(cancellationToken); + logger.LogInformation("Account merge {MergeId} {State}: {Outcome} {Code}", merge.Id, merge.State, outcome.GetType().Name, code); + return merge; + } + + /// Advances every in-flight merge that is due, oldest first. One that throws is logged and skipped; returns how many were advanced. + public async Task AdvanceDueAsync(DateTimeOffset now, CancellationToken cancellationToken) + { + var due = await dbContext.AccountMerges.AsNoTracking() + .Where(x => DueStates.Contains(x.State) && (x.NextAttemptUtc == null || x.NextAttemptUtc <= now)) + .OrderBy(x => x.CreatedUtc) + .Select(x => x.Id) + .ToListAsync(cancellationToken); + var advanced = 0; + foreach (var id in due) + { + try + { + await AdvanceAsync(id, cancellationToken); + advanced++; + } + catch (Exception error) when (error is not OperationCanceledException) + { + dbContext.ChangeTracker.Clear(); + logger.LogWarning("Account merge {MergeId} advance failed: {Error}", id, error.GetType().Name); + } + } + + return advanced; + } + + // ---- helpers ---- + + /// The merge as stored now: a row this context already tracks is reloaded, never trusted. + private async Task LoadAsync(Guid mergeId, CancellationToken cancellationToken) + { + var tracked = dbContext.AccountMerges.Local.FirstOrDefault(x => x.Id == mergeId); + if (tracked is not null) + { + await dbContext.Entry(tracked).ReloadAsync(cancellationToken); + return dbContext.Entry(tracked).State == EntityState.Detached ? null : tracked; + } + + return await dbContext.AccountMerges.SingleOrDefaultAsync(x => x.Id == mergeId, cancellationToken); + } + + private Task HeimdallAccountAsync(Guid userAccountId, CancellationToken cancellationToken) => + dbContext.UserAccounts.AsNoTracking().Where(x => x.Id == userAccountId).Select(x => x.HeimdallAccountId).SingleAsync(cancellationToken); + + /// Shapes Heimdall would 400 are refused before a row exists, so a confirm can never store a merge that cannot call. Messages name no value. + private static void RequireProofs(MergeProof? one, IReadOnlyList many) + { + if (many is not { Count: >= 1 and <= MaxProofs }) + { + throw new ArgumentException("1 to 8 proofs are required", nameof(many)); + } + + foreach (var proof in one is null ? many : [one, .. many]) + { + if (string.IsNullOrEmpty(proof.AccessToken) || proof.AccessToken.Length > HeimdallIdentityMoveClient.MaxProofLength + || string.IsNullOrEmpty(proof.HeimdallAccountId) || string.IsNullOrEmpty(proof.Provider) || proof.Provider.Length > 32) + { + throw new ArgumentException("a proof is malformed", nameof(many)); + } + } + + if (many.Select(x => x.Provider).Distinct(StringComparer.Ordinal).Sum(x => x.Length + 1) > 121) + { + throw new ArgumentException("the proofs' providers do not fit the record", nameof(many)); + } + } + + private string Seal(IEnumerable from, string? to) => _seal.Protect(JsonSerializer.Serialize(new ProofSeal([.. from], to))); + + private ProofSeal? Open(string? sealedProofs) + { + if (sealedProofs is null) + { + return null; + } + + try + { + return JsonSerializer.Deserialize(_seal.Unprotect(sealedProofs)) is { From.Count: > 0 } proofs ? proofs : null; + } + catch (Exception error) when (error is CryptographicException or JsonException) + { + return null; + } + } + + private static string Tier(HeimdallProofTier tier) => tier == HeimdallProofTier.Strong ? "strong" : "weak"; + + private static string RefusalCode(HeimdallMoveRefusal code) => + code == HeimdallMoveRefusal.RequestInvalid ? "invalid_request" : WordBoundary().Replace(code.ToString(), "_$1").ToLowerInvariant(); + + [GeneratedRegex("(?The database's refusal of an overlapping merge: the live-merge unique index or the chain trigger's exclusion violation. + private static bool IsLiveMergeViolation(DbUpdateException error) + { + for (var current = (Exception?)error; current is not null; current = current.InnerException) + { + if (current is PostgresException { SqlState: "23P01" } or PostgresException { SqlState: "23505", ConstraintName: LiveMergeIndex }) + { + return true; + } + } + + return false; + } +} diff --git a/src/Bifrost.Web/Program.cs b/src/Bifrost.Web/Program.cs index 25b91ac..2985fe2 100644 --- a/src/Bifrost.Web/Program.cs +++ b/src/Bifrost.Web/Program.cs @@ -140,6 +140,7 @@ builder.Services.AddSingleton(); builder.Services.AddScoped(); builder.Services.AddHostedService(); builder.Services.AddScoped(); +builder.Services.AddScoped(); builder.Services.AddHostedService(); builder.Services.AddScoped(); builder.Services.AddScoped();