Documentation

• 1: Overview
• 2: Getting started
• 3: Architecture
• 4: Domain model
• 5: API reference
• 6: API explorer
• 7: Flows
• 7.1: Login
• 7.2: Two-factor authentication
• 7.3: Google Sign-In
• 7.4: Person onboarding
• 7.5: Password recovery
• 7.6: Scope permission claims
• 7.7: Audit logging
• 7.8: Application authentication
• 8: Environments and deployment
• 9: Operations
• 10: Requirements
• 10.1: Vision Document
• 10.2: System Requirements Document
• 10.3: Use Case Specification Document
• 10.4: Technology Stack Document
• 10.5: Data Protection Impact Assessment
• 10.6: Data Retention Schedule Document
• 10.7: Data Protection Document
• 10.8: Privacy Notice
• 10.9: Data Processing Agreement
• 10.10: Incident Response Document
• 10.11: Testing Specification Document
• 10.12: Threat Model Document
• 10.13: Development Workflow Document
• 10.14: Operations & Infrastructure Document
• 11: Changelog
• 12: Contributing

1 - Overview

Heimdall is a centralized identity management API. Several client systems delegate their identity concerns to one deployment of it, and each of those systems gets an isolated slice of the data called a scope.

Everything else in the model is defined relative to that boundary.

The vocabulary

How a person relates to a scope

This is the single rule that most often surprises newcomers: Person has no ScopeId.

flowchart TD
    P[Person] --> R{Role}
    R -->|SystemAdmin| S1["Belongs to no scope<br/>Governs the whole system<br/>May own scopes via SCOPE_OWNER"]
    R -->|ScopeAdmin| S2["Owns 1..n scopes<br/>via SCOPE_OWNER"]
    R -->|User| S3["Belongs to exactly 1 scope<br/>via SCOPE_USER"]

An administrator with a SCOPE_USER row, or a User with two, is not representable — the join tables carry the constraints (SCOPE_USER.PersonId is unique; SCOPE_OWNER has a composite key).

Two identifiers per entity

Every top-level entity carries both:

• Id — an auto-incrementing bigint. The physical primary key and the target of every foreign key. Never leaves the database.
• PublicId — a GUID generated at creation. The identifier used in API paths, response bodies, and token claims.

The split keeps record counts and creation order — which a sequential integer would leak — out of anything a caller can see, while the database keeps compact integer keys for joins and indexes. This is NFR-15; see the System Requirements Document for the one documented and accepted exception (Person.RoleId).

Two kinds of caller, two kinds of token

Both produce the same kind of stateless, signed JWT. Authentication reads no database per request — the identity is rebuilt from the token’s claims — which is why the sign-out endpoint revokes nothing and why a token can outlive the account it names until it expires.

What the API is composed of

graph LR
    subgraph Clients
        C1[Client System A]
        C2[Client System B]
        C3[Client System N]
    end

    subgraph Heimdall["Heimdall API"]
        AUTH[Authentication]
        TFA[Two-Factor Auth]
        GS[Google Sign-In]
        PM[Person Management]
        AM[Application Management]
        SM[Scope Management]
        SPM[Scope Permissions]
        PR[Password Recovery]
        EV[Email Verification]
        AL[Audit Logging]
    end

    subgraph Infrastructure
        DB[(PostgreSQL)]
        EMAIL[Mailgun]
        GOOGLE[Google Identity]
    end

    C1 & C2 & C3 --> AUTH & PM & AM & SM & GS
    AUTH --> TFA
    AUTH & PM & AM & SM & SPM & GS & TFA & AL --> DB
    PR & EV & TFA --> EMAIL
    GS --> GOOGLE

Every one of those write paths also produces an audit trail entry (NFR-09) — see Audit logging .

Where the rules are written down

Nothing on this site is the specification. The specification is the set of numbered requirements and use cases under Requirements :

• FR-… — functional requirements, grouped by capability (FR-AU-… authentication, FR-GO-… Google Sign-In, FR-2F-… two-factor, and so on).
• NFR-… — non-functional requirements (security, data integrity, validation, logging).
• UC-… — use cases, each with a main flow and numbered alternative flows (AF-11a, AF-11b, …).

The source code cites these identifiers in its comments, so a line of code can be traced back to the flow that demanded it.

2 - Getting started

Prerequisites

• .NET 10 SDK
• PostgreSQL — the API’s relational database.
• Python 3 — only to run the migration menu script.
• The pinned EF Core CLI tool. Restore it once after cloning:

dotnet tool restore

Building from source, running the test suites and the other contributor tooling are covered in Contributing .

Clone

The documentation site’s theme is a git submodule, so clone with submodules (or initialise them afterwards):

git clone --recurse-submodules https://github.com/artur-rios/heimdall-api.git

Configure

Environments/.env is a tracked template listing every variable the API reads. Real values live in per-environment files that are gitignored. Create your local one before the first run:

cp src/Presentation/ArturRios.Heimdall.WebApi/Environments/.env src/Presentation/ArturRios.Heimdall.WebApi/Environments/.env.local

How the environment picks its files

ASPNETCORE_ENVIRONMENT selects two files, both resolved next to the built assembly:

Both sets are gitignored — the env files hold credentials, and the app settings are per-machine. They are for running from source: the image carries no Environments/ file, and a container takes its variables from the env file Compose is given instead — see Environments and deployment , where local and development run as Development, homologation as Staging and production as Production. Settings/appsettings.json is tracked and loaded first, so a missing environment file costs defaults rather than the whole configuration.

Could not find variables for Development environment. Loading default environment Local instead...

Required — the API will not start without these

Optional — each falls back to a default

Optional integrations

Email delivery (Mailgun) and Google Sign-In are each configured by their own variables, and each has a documented behaviour when left unconfigured. See Operations for the full table and the reasoning — including why an unconfigured Production deployment refuses to start rather than logging tokens in plaintext.

Apply migrations

The schema is managed with EF Core migrations, applied explicitly. The API never migrates on startup, and refuses to start when migrations are pending — so this step comes before the first run:

python scripts/migrations.py

The script asks which environment file to load (for the connection string), then offers list, create, and apply; apply is the one a deployment needs. See Operations for more, and Contributing for authoring a new migration.

Run

dotnet run --project src/Presentation/ArturRios.Heimdall.WebApi

On the first run against an empty database, the seeder creates the roles and the master system administrator from HEIMDALL_MASTER_USER_NAME / _EMAIL / _PASSWORD. On later runs, an existing system admin means those variables are read but unused.

The http launch profile serves on http://localhost:5177; the https profile adds https://localhost:7235.

Swagger UI is at http://localhost:5177/swagger , with JWT wired in: press Authorize, paste the token from a login, and call any endpoint from the browser. It shows each controller’s own summary and marks which endpoints need a token, because SwaggerConfiguration is applied over it.

That same class produces the document behind the API explorer , so the two are the same document — literally: python scripts/openapi.py writes byte-for-byte what a running instance serves at /swagger/v1/swagger.json. Read the API without running it through the explorer; call it through Swagger UI or api-client/.

First calls

Liveness — anonymous, no database:

curl http://localhost:5177/healthcheck

Log in as the master system administrator:

curl -X POST http://localhost:5177/api/auth/login -H "Content-Type: application/json" -d '{"email":"<master-email>","password":"<master-password>"}'

The response carries token, expiresAt, and emailVerified — the last telling you whether to prompt the person to confirm their address. Send it as Authorization: Bearer <token> on every other endpoint — see the API reference for who may call what.

Calling the API

api-client/ holds ready-to-send requests for every operation in the OpenAPI document, in two formats — pick whichever your editor already opens:

Neither asks you to copy a GUID by hand: a response handler stores the token that login returns, and each request that creates something stores the new id for the requests that need it. Point the environment file at your master user’s credentials first — http/http-client.env.json or bruno/environments/Local.bru.

On an empty database four requests have to run in order before anything else will find its subject: Login, then Create an administrator, then Create a scope, then Create a User in a scope. See api-client/README.md for the whole story, including how to keep real credentials out of git.

To run the Bruno collection without installing anything:

npx @usebruno/cli run Auth --env Local

Next

• Contributing — building, testing, and the branching and release process.
• Architecture — what happens between the controller and the database.
• Development Workflow — how a use case goes from backlog to merged.

3 - Architecture

Heimdall is a layered (DDD-flavoured) solution with CQRS in the application layer. Reads and writes travel different objects, through different mediators, into different handlers.

The layers

graph TB
    subgraph P["Presentation — ArturRios.Heimdall.WebApi"]
        CTRL[Controllers]
        SEC[Security: token issuers, mappers, filters]
        MAIL[Email senders]
    end
    subgraph A["Application"]
        subgraph CMD["ArturRios.Heimdall.Command"]
            CH[Command handlers]
            CV[FluentValidation validators]
            CS[Services: token, 2FA, email verification]
            AUD[Auditing decorator]
        end
        subgraph QRY["ArturRios.Heimdall.Query"]
            QH[Query handlers]
            HC[Health checks]
        end
        subgraph SHR["ArturRios.Heimdall.Shared"]
            MSG[Messages + status-code maps]
            OWN[IScopeOwnershipChecker, IActorAccessor]
        end
    end
    subgraph D["Domain — ArturRios.Heimdall.Domain"]
        ENT[Entities + Roles enum]
    end
    subgraph I["Infrastructure — ArturRios.Heimdall.Data"]
        CTX[AppDbContext]
        MAPS[Entity maps]
        MIG[Migrations]
        SEED[DatabaseSeeder]
    end

    CTRL --> CMD & QRY
    CTRL --> MSG
    CMD & QRY --> SHR
    CMD & QRY --> ENT
    CMD & QRY -->|repository interfaces| I
    I --> ENT
    SEC -.implements.-> CS
    MAIL -.implements.-> CS

The arrows only ever point inwards or sideways: Domain depends on nothing, and Application depends on Infrastructure only through repository interfaces (IAsyncRepository<T, long>, IAsyncReadOnlyRepository<T, long>) that Infrastructure implements. Presentation supplies the concrete adapters for the abstractions the Application layer declares — IAuthTokenIssuer, IEmailVerificationSender, IGoogleIdTokenVerifier — which is why swapping Mailgun for logging, or the real Google verifier for the refusing one, is a start-up registration decision and nothing else.

CQRS: two mediators, two shapes

classDiagram
    class Controller {
        -CommandMediator commandMediator
        -QueryMediator queryMediator
    }
    class CommandMediator {
        +ExecuteCommandAsync~TCommand, TOutput~(command) DataOutput~TOutput~
    }
    class QueryMediator {
        +ExecuteQueryAsync~TQuery, TOutput~(query) DataOutput~TOutput~
        +ExecutePaginatedQueryAsync~TQuery, TOutput~(query) PaginatedOutput~TOutput~
    }
    class ICommandHandlerAsync~TCommand, TOutput~ {
        <<interface>>
        +HandleAsync(command, cancellationToken) DataOutput~TOutput~
    }
    class IQueryHandlerAsync~TQuery, TOutput~ {
        <<interface>>
        +HandleAsync(query, cancellationToken) DataOutput~TOutput~
    }
    class IPaginatedQueryHandlerAsync~TQuery, TOutput~ {
        <<interface>>
        +HandleAsync(query, cancellationToken) PaginatedOutput~TOutput~
    }
    class AuditingCommandHandler~TCommand, TOutput~ {
        -ICommandHandlerAsync inner
        -IAuditLogWriter auditLogWriter
        +HandleAsync(command, cancellationToken) DataOutput~TOutput~
    }
    class ConcreteCommandHandler {
        -IValidator~TCommand~ validator
        -IAsyncRepository~T~ repository
        +HandleAsync(command, cancellationToken) DataOutput~TOutput~
    }

    Controller --> CommandMediator
    Controller --> QueryMediator
    CommandMediator --> ICommandHandlerAsync
    QueryMediator --> IQueryHandlerAsync
    QueryMediator --> IPaginatedQueryHandlerAsync
    ICommandHandlerAsync <|.. AuditingCommandHandler
    ICommandHandlerAsync <|.. ConcreteCommandHandler
    AuditingCommandHandler o-- ConcreteCommandHandler : decorates

A controller action is deliberately thin — bind, dispatch, resolve:

[HttpPost]
[RoleRequirement((int)Roles.SystemAdmin)]
public async Task<ActionResult<DataOutput<CreateScopeCommandOutput?>>> Create(
    [FromBody] CreateScopeCommand command)
{
    var result = await commandMediator
        .ExecuteCommandAsync<CreateScopeCommand, CreateScopeCommandOutput>(command);

    return result.ToActionResult(statusMap: ScopeMessageMap.StatusCodes);
}

No business rule lives in a controller. The handler returns a DataOutput<T> carrying data, messages, and errors; Util.WebApi’s ToActionResult turns that into an HTTP status using the per-area message map — a dictionary from message text to status code — so “which error is a 404 and which is a 409” is a single table per area rather than scattered return NotFound() calls.

Auditing by decoration

Every write handler is registered through AddAuditedCommandHandler, which registers the concrete handler and then registers the interface as an AuditingCommandHandler wrapping it (NFR-09):

services.AddScoped<THandler>();
services.AddScoped<ICommandHandlerAsync<TCommand, TOutput>>(provider =>
    new AuditingCommandHandler<TCommand, TOutput>(
        provider.GetRequiredService<THandler>(),
        provider.GetRequiredService<IAuditLogWriter>(),
        provider.GetRequiredService<ILogger<AuditingCommandHandler<TCommand, TOutput>>>()));

The decorator writes one AuditLog row per successful command, resolving the target from the output’s Id/PublicId by reflection and the actor from IActorAccessor (the current request’s identity). A failure to write the audit entry is logged as a warning and never fails the request the user already succeeded at.

See Audit logging for the sequence.

How a failure becomes a status

ToActionResult resolves the HTTP status from the envelope’s first error (or, on success, its first message) against the map the controller passes it, falling back to 200 on success and 400 on failure. Each use case owns a *MessageMap naming its own outcomes — InvalidCredentials is a 401, EmailAlreadyExists a 409, and so on.

Persistence failures are not the use case’s vocabulary, and until recently they had none of their own: a repository handed back the provider’s text, which named the violated index, the conflicting value, or the column and its type. Nothing stable could be keyed off that, so every one of them fell through to the 400 default — a duplicate that lost a race and a database that had gone away were both reported as bad requests, and the message leaked schema detail to the caller.

ArturRios.Data.Relational.Core (since 4.0.0) classifies each failure into one of five fixed, caller-safe messages instead, reading the provider text only to decide which. DataAccessMessageMap folds four of them into every use case’s map:

The fifth, the unclassified A data-access error occurred., is deliberately left unmapped and keeps the 400 default. It covers both causes a caller can fix — a value longer than its column, where a validator failed to bound it — and causes only an operator can, so neither 400 nor 500 fits all of it, and 400 is the safer of the two.

A use case’s own entries always win over these, so a map assembled this way can never override the vocabulary the use case defines.

The HTTP request pipeline

graph LR
    REQ([Request]) --> FWD["Forwarded headers<br/>trusted proxies only"]
    FWD --> HTTPS[HTTPS redirect]
    HTTPS --> TRACE[TraceActivityMiddleware]
    TRACE --> EX[ExceptionMiddleware]
    EX --> CORS["CORS<br/>configured origins only"]
    CORS --> AUTHN[AuthenticationMiddleware]
    AUTHN --> RL[Rate limiter<br/>credential-checking endpoints only]
    RL --> MFA[MfaPendingGuardFilter]
    MFA --> SRO[SubjectRightsOnlyGuardFilter]
    SRO --> LIVE[ActorLivenessFilter]
    LIVE --> ROLE["RoleRequirement /<br/>AllowAnonymous"]
    ROLE --> CTRL[Controller action]
    CTRL --> MED[Mediator]
    MED --> H[Handler]
    H --> DB[(PostgreSQL)]
    H --> RES[DataOutput]
    RES --> RR["ToActionResult<br/>+ message map"]
    RR --> RESP([HTTP response])

Everything from TraceActivityMiddleware to AuthenticationMiddleware is Util.WebApi’s standard pipeline, which Startup derives from WebApiStartup to get. What it has no place for is added around it: the metrics scrape branch (on its own port, ahead of everything — see Operations ), forwarded headers and HTTPS redirection go in front through a startup filter, and the rate limiter goes after it. TraceActivityMiddleware logs every request with the caller’s IP address — the real caller’s when HEIMDALL_TRUSTED_PROXIES names the proxy in front of the API, the proxy’s otherwise.

Six things about this pipeline are worth knowing before reading any handler:

Authentication reads no database. AddTokenAuthentication<IdentityUserMapper> is configured with JwtValidationMode.ClaimsOnly and TokenSource.Header: the IdentityUser is rebuilt from the token’s claims alone, and nothing is looked up while the token is validated. The library’s validator checks the signature (HS256 only) and lifetime; PersonTokenValidator takes its place, wrapping it, and also requires HEIMDALL_AUTH_TOKEN_ISSUER and exactly one of the three person audiences (NFR-30), so a correctly signed token Heimdall did not issue for itself is refused like a forged one.

But the identity it names is checked. ActorLivenessFilter runs globally, right after the challenge-token guard, and refuses a token whose person or Google User is absent or logically deleted (FR-AU-05, FR-GO-12). Without it, ClaimsOnly meant a token kept working for its whole lifetime after the account behind it was deleted — and the handlers compensated unevenly: ScopeOwnershipChecker excluded a deleted Scope Admin, while every System Admin bypass and every “acting on yourself” branch trusted the role claim alone, leaving the protection in place for the lesser role and absent for the greater one. It costs one indexed read per authenticated request, and two for a Google User, since the token does not say which table its subject lives in. A restricted identity (NFR-24) is refused the same way — except on the four actions marked [DataSubjectRight] (export, erasure request, restriction, lifting one’s own restriction), where a restricted or suspended subject still reaches the handler and the use case’s own flows answer.

Single-use state is spent in the database, not in memory. The repositories write whole rows — read, change, save — so two requests that read the same recovery code, token, challenge or counter before either saved would both act on it. IAtomicWrites (Domain, implemented in Data on ExecuteUpdate) makes each of those a single conditional UPDATE … WHERE whose affected-row count says who won, and charges every guess budget before the comparison it guards.

One class owns both directions of the claims. IdentityUserMapper writes the claims when a token is issued and reads them when one is validated, so the two cannot drift. Every claim value is a PublicId; an internal bigint never reaches a token (NFR-15).

A challenge token is inert everywhere but one endpoint. MfaPendingGuardFilter is registered globally and rejects any request whose identity carries MfaPending with a 401 (FR-2F-10, NFR-17). The second-factor endpoint itself is unaffected because it is [AllowAnonymous] and takes the challenge token as a body field, never as a bearer credential. The token also carries an audience of its own, HEIMDALL_AUTH_TOKEN_AUDIENCE + .2fa-challenge, so a consumer that pins the person audience refuses it, and IdentityUserMapper reads mfaPending only under that audience.

A subject-rights-only token is confined to four actions. A restricted identity that signs in (NFR-24, UC-11 AF-11i, UC-25 AF-25e) is issued a token carrying the subjectRightsOnly claim and no scope, under its own audience, HEIMDALL_AUTH_TOKEN_AUDIENCE + .subject-rights, which consumers pinning the person audience refuse. SubjectRightsOnlyGuardFilter, registered globally after the challenge-token guard, answers it 403 on every action not marked [DataSubjectRight] — on its claims alone, before the liveness check’s read. The liveness check would refuse it there too while the restriction stands; the guard keeps it confined after the restriction is lifted, so a lift never turns it into a full token.

Authorization

Role checks are declarative, via [RoleRequirement] on the action:

[HttpDelete("{id:guid}/hard")]
[RoleRequirement((int)Roles.SystemAdmin)]

Ownership checks — “is this Scope Admin an owner of this scope?” — cannot be expressed in an attribute, so they live behind IScopeOwnershipChecker, resolved inside the handler. A handful of endpoints carry no role attribute on purpose: GET /api/scopes/{scopeId}/google-users/{id}, for example, must admit the Google User themselves, whose token is User-role, so any attribute strong enough to exclude other users would exclude the actor the use case grants.

The complete matrix — every action against every role — is §7 of the System Requirements Document , summarised per endpoint in the API reference .

Validation

Input validation is FluentValidation, one validator per command or query, registered alongside its handler (NFR-10). Where a command has no validator it is a documented decision, not an omission — the start-up registrations carry the reason inline. The two recurring reasons:

• Nothing to validate. Every field is a typed route value already constrained by the route ({id:guid}), or the request carries no caller-supplied input at all because the subject comes from the bearer token.
• The rule needs the database. Which second factor is required depends on the stored AppEnabled/EmailEnabled of the person’s configuration — a read only the handler can make.

Every paginated list query does have a validator, so page size and filters are checked before a query reaches the database.

Persistence

AppDbContext applies one entity map per entity (PersonDbMap, ScopeDbMap, …) rather than annotating the domain classes, keeping storage concerns out of the domain. Handlers never touch the context: they depend on IAsyncRepository<T, long> for writes and IAsyncReadOnlyRepository<T, long> for reads, the latter exposing Query() so a handler can compose an IQueryable and let the database do the filtering.

EF diagnostics — sensitive data logging and detailed errors — are enabled outside Production only; they would otherwise print parameter values including password hashes, salts, and email addresses.

Where to go next

• Domain model — entities, relationships, and deletion cascades.
• Flows — the same pipeline traced end-to-end for specific use cases.
• Operations — migrations, health checks, logging, and rate limiting.

4 - Domain model

The domain layer is intentionally anemic: entities are data holders with properties and navigation collections. Decisions live in the command and query handlers, so the diagrams below are a map of shape and relationship, not of behaviour.

The core model

The entities every request touches: a scope, the persons related to it through the two join tables, the applications and Google Users it contains, and the permissions it defines.

classDiagram
    direction LR

    class Scope {
        +Guid PublicId
        +string Name
        +string? Description
        +bool IsDeleted
        +bool GoogleSignInEnabled
    }
    class Person {
        +Guid PublicId
        +string Name
        +string Email
        +byte[] PasswordHash
        +byte[] Salt
        +bool IsDeleted
        +bool EmailVerified
        +long RoleId
    }
    class Role {
        +Guid PublicId
        +string Name
        +string? Description
    }
    class ScopeOwner {
        +long ScopeId
        +long PersonId
    }
    class ScopeUser {
        +long ScopeId
        +long PersonId
    }
    class Application {
        +Guid PublicId
        +string Name
        +bool IsDeleted
        +long ScopeId
        +long OwnerId
    }
    class GoogleUser {
        +Guid PublicId
        +string GoogleId
        +string Name
        +string Email
        +bool EmailVerified
        +string? ProfilePictureUrl
        +bool IsDeleted
        +long ScopeId
    }
    class ScopePermission {
        +Guid PublicId
        +string Name
        +string? Description
        +bool IncludeAsJwtClaim
        +bool IsDeleted
        +long ScopeId
    }

    Role "1" o-- "0..*" Person : classifies
    Scope "1" o-- "0..*" ScopeOwner : has
    Person "1" o-- "0..*" ScopeOwner : owns via
    Scope "1" o-- "0..*" ScopeUser : has
    Person "1" o-- "0..1" ScopeUser : belongs via
    Scope "1" o-- "0..*" Application : contains
    Person "1" o-- "0..*" Application : owns
    Scope "1" o-- "0..*" GoogleUser : contains
    Scope "1" o-- "0..*" ScopePermission : defines

Credentials, tokens and the audit trail

The entities hanging off a person: their two-factor configuration with its codes, the two kinds of single-use token, and the append-only audit log.

classDiagram
    direction LR

    class Person {
        +Guid PublicId
        +string Email
        +bool EmailVerified
        +int FailedLoginAttempts
        +DateTime? LockedOutUntil
        +int FailedSecondFactorAttempts
        +DateTime? SecondFactorLockedOutUntil
        +int SecondFactorLockouts
        +int FailedReauthenticationAttempts
        +DateTime? ReauthenticationWindowStartedAt
        +DateTime? ReauthenticationPausedUntil
        +int AccountEmailsSent
        +DateTime? AccountEmailWindowEndsAt
        +DateTime? AccountEmailLastSentAt
        +long? ScopeId
    }
    class TwoFactorAuth {
        +long PersonId
        +bool AppEnabled
        +bool EmailEnabled
        +byte[]? TotpSecretEncrypted
        +bool IsActive
        +long? LastTotpTimeStepUsed
        +int EmailCodeReissueCount
        +Guid? ChallengeId
        +int ChallengeAttempts
    }
    class TwoFactorEmailCode {
        +long TwoFactorAuthId
        +byte[] CodeHash
        +byte[] Salt
        +DateTime ExpiresAt
        +bool Used
        +int FailedAttempts
    }
    class TwoFactorRecoveryCode {
        +long TwoFactorAuthId
        +byte[] CodeHash
        +bool Used
        +DateTime? UsedAt
    }
    class EmailVerificationToken {
        +long PersonId
        +string Token
        +DateTime ExpiresAt
        +bool Used
    }
    class PasswordResetToken {
        +long PersonId
        +string Token
        +DateTime ExpiresAt
        +bool Used
    }
    class AuditLog {
        +Guid PublicId
        +Guid? ActorPersonId
        +int? ActorRole
        +string Action
        +Guid? TargetId
        +DateTime CreatedAt
    }

    Person "1" o-- "0..1" TwoFactorAuth : configures
    TwoFactorAuth "1" o-- "0..*" TwoFactorEmailCode : issues
    TwoFactorAuth "1" o-- "0..*" TwoFactorRecoveryCode : issues
    Person "1" o-- "0..*" EmailVerificationToken : holds
    Person "1" o-- "0..*" PasswordResetToken : holds

AuditLog is deliberately unconnected. Its ActorPersonId is a bare PublicId, not a foreign key, so an entry survives the hard deletion of the person who made the write.

Common shape

Every entity above derives from Entity<long>, which contributes the internal key, and each one that is addressable from outside also carries timestamps:

classDiagram
    direction LR
    class Entity~long~ {
        <<abstract>>
        +long Id
    }
    class AddressableEntity {
        <<pattern>>
        +Guid PublicId
        +DateTime CreatedAt
        +DateTime UpdatedAt
    }
    Entity~long~ <|-- AddressableEntity

Scope, Role, Person, Application, GoogleUser, ScopePermission, AuditLog and PendingRegistration follow the addressable pattern. The join rows, token rows and two-factor rows carry only the internal Id — see the table below for why.

Which entities carry a PublicId

The right-hand column is never addressed by ID from outside:

• Join rows (ScopeOwner, ScopeUser) are not independently addressable resources — they are reached through the scope and person they connect.
• Token rows are reached by their random Token string, which is already the caller-facing reference.
• Two-factor rows are reached implicitly through the authenticated person’s own identity — a person’s configuration is never named by ID in a path.

PendingRegistration carries a PublicId for administrators only: a scope’s owners list and discard registrations by it (UC-49, UC-50). The registrant never sees it — their reference is the mailed token.

Secrets at rest

That split is NFR-16. The email code gets a salt and the recovery code does not for a concrete reason: a six-digit code has a million possible values and would fall to a rainbow table without one, while a recovery code is 80 random bits, where a plain one-way hash already makes the plaintext unrecoverable: finding one from its digest takes about 2^79 SHA-256 evaluations, and even a search over a million stored codes at once leaves about 2^60 (Threat Model TH-16).

Deletion cascades

flowchart TD
    A[Delete request] --> B{Logical or hard?}

    B -->|Logical| C[Set IsDeleted = true]
    C --> C1{Entity}
    C1 -->|Scope| C2["Cascades to its Users,<br/>Google Users, applications<br/>— not to its owners,<br/>not to its permissions"]
    C1 -->|Person / Google User /<br/>Application / Permission| C3[Only its own flag]
    C2 & C3 --> D[Row stays, excluded from<br/>default queries]

    B -->|Hard| F{Entity}
    F -->|Scope| G["Removes SCOPE_OWNER/SCOPE_USER rows,<br/>its Users, Google Users,<br/>applications and permissions"]
    F -->|ScopeAdmin| H["Removes SCOPE_OWNER rows,<br/>owned applications,<br/>2FA config + recovery codes"]
    F -->|User| I["Removes SCOPE_USER row,<br/>2FA config + recovery codes"]
    F -->|Google User /<br/>Application / Permission| J[Leaf — nothing cascades]
    H --> K{Would any owned scope<br/>be left ownerless?}
    K -->|Yes| L["Rejected — NFR-12"]
    K -->|No| M[Row removed]
    G & I & J --> M

The rules that most often catch people out:

Logically deleting a scope does not touch its permissions. Applications cascade; permissions do not. They become unreachable anyway — the listing endpoint gates on the scope’s IsDeleted, and the JWT-claim fold at login reads only permissions of non-deleted scopes — so a restored scope recovers its permission set unchanged. A hard delete does purge them, through the foreign key’s ON DELETE CASCADE.

Logically deleting a scope does not touch its owners. A Scope Admin may own other, active scopes.

A scope must always retain at least one owner (NFR-12) — removing the last owner, or hard-deleting the last owning person, is rejected. NFR-12 does not guard the other direction: hard-deleting a scope can leave a Scope Admin owning nothing. That record is left in place on purpose (they may be about to be given another scope), and it grants no access in the meantime, because a ScopeAdmin with no live owned scope cannot authenticate (FR-AU-07).

Logical deletion never touches two-factor state. A restored person keeps whatever configuration they had. Hard deletion removes it, via two_factor_recovery_code → two_factor_auth → person.

The authoritative version of all of this — including the reasoning per rule — is §8 of the System Requirements Document .

Persistence mapping

Each entity has a map class under ArturRios.Heimdall.Data/EntityMaps/ (PersonDbMap, ScopeOwnerDbMap, …) applied by AppDbContext. Constraints that the C# class cannot express live there: the composite key of ScopeOwner, the uniqueness of ScopeUser.PersonId (which is what makes “a User belongs to exactly one scope” true rather than merely intended), the per-scope uniqueness of GoogleUser.GoogleId and GoogleUser.Email, and the cascade behaviour above.

Email uniqueness

FR-PE-09 and FR-GO-07 make an address unique in a namespace chosen by role, and the three halves differ in how far the database can enforce them.

All three indexes are over LOWER(email) because the handlers compare addresses case-insensitively; an index over the raw column would enforce a different rule than the one the code applies, and accept pairs a handler had already refused.

The scope a User belongs to, twice

PERSON.scope_id is a copy of the owning SCOPE_USER row’s scope, and exists for one reason: the third rule above could not otherwise be enforced. The scope lives in SCOPE_USER and the address in PERSON, a PostgreSQL unique index covers one table, and a trigger closes nothing — under READ COMMITTED two concurrent inserts see the same pre-write snapshot and both find the address free. Only a unique index serialises them, and an index needs its columns on one table.

SCOPE_USER remains the relationship (§4.6) and every read goes through it. The copy is written by the three handlers that write the membership — UC-06 path a sets both, UC-23 and UC-08’s role change clear both — and the index’s condition matches CreateUserCommandHandler’s check term for term, so the rule itself did not change. Only who enforces it under concurrency did.

A caller who loses that race is answered by AF-06a, the same conflict they would have got had the address already been taken when they asked, rather than a persistence failure: losing a race is not something the API makes visible.

5 - API reference

Schema-level documentation — every parameter, every request and response body — is published as an OpenAPI document and rendered by the API explorer , which is the same document a running instance serves through its own Swagger UI at /swagger. To call the endpoints, use that, or the .http files or Bruno collection in api-client/.

This page is the map — what exists, who may call it, and which use case it implements.

Reading the “Who” column

Two rules apply everywhere and are not repeated per row:

• The identifier in a path is always a PublicId (GUID), never an internal id.
• A challenge token (issued by a 2FA-gated login) is rejected by every endpoint below except POST /api/auth/2fa/verify, with a 401.

Authentication — /api/auth

Every anonymous endpoint here is rate-limited to 10 requests per minute per IP. Each of them checks a credential, and none is protected by a token — see Operations for why that matters and what the limit does not replace. The authenticated endpoints that check a password or a second factor — 2fa/enable, 2fa/confirm, 2fa/disable, 2fa/recovery-codes/regenerate, erasure-request and PUT /persons/{id} — share the same limit.

The 2FA endpoints never name a person: the subject is always the caller, read from the bearer token, so a caller can only ever act on their own configuration.

A token naming a restricted identity (UC-44), or one logically deleted and not yet anonymised, is refused everywhere with a 401 — except data-export, erasure-request, processing-restriction and processing-restriction/lift, through which the subject exercises their own rights (NFR-24). Those answer with the use case’s own flows instead: a restricted subject can export, request erasure — which lifts the restriction, so the erasure is not held behind it — lift their own restriction, and is told a second restriction is a conflict (AF-44a).

A restricted identity can still sign in — login, 2fa/verify and google answer 200 with processingRestricted: true and a subject-rights-only token (UC-11 AF-11i, UC-25 AF-25e). That token claims no scope and only those four endpoints accept it; every other endpoint answers 403, even after the restriction is lifted, when the subject signs in again for a full token.

Scopes — /api/scopes

Persons — /api

Applications — /api/scopes/{scopeId}/applications

An application’s owner must be a ScopeAdmin or SystemAdmin who owns that scope — a User may never own one (FR-AP-03).

Application credentials — /api/scopes/{scopeId}/applications/{id}/credentials

A Scope Admin may manage the credentials only of an application they own, in a scope they still own, the rule GET/PUT /{id} apply (FR-AP-12).

Application tokens — /api/applications

The Application authentication guide is the page for the service consuming these tokens.

Scope permissions — /api/scopes/{scopeId}/permissions

Owning the scope is the whole of the authorization to manage its permissions — a permission has no owner of its own. A permission with IncludeAsJwtClaim set has its name folded into the JWT of identities acting within that scope (FR-AU-08); see Scope permission claims .

Google Users — /api/scopes/{scopeId}/google-users

The by-id read carries no role attribute for a concrete reason: a Google User’s token is User-role, so any attribute strong enough to keep other Users out would lock out the actor UC-27 explicitly grants. The listing admits none of them.

Both deletions take the scope’s PublicId in the path and refuse a Google User reached through the wrong scope.

Audit trail — /api/audit-log

An entry is shown as stored: an actor the retention pass has cleared reads as null, so filtering by actorId cannot find it. action is the command’s type name, matched exactly (CreateScopeCommand). A Scope Admin is refused — the trail has no scope column to divide it by.

Health check — /api/healthcheck

The API also answers both at the root, /healthcheck and /healthcheck/detailed, for the container health check and yggdrasil’s status page, which call it on its own port. Behind Traefik, only the /api/ addresses reach it from the web UI’s host.

Response shape

Every endpoint answers one of two envelopes:

// DataOutput<T>
{
  "data": { /* the resource, or null */ },
  "messages": ["Scope created successfully"],
  "errors": [],
  "success": true
}

// PaginatedOutput<T> — every list endpoint
{
  "data": [ /* the page */ ],
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 137,
  "messages": [],
  "errors": [],
  "success": true
}

The HTTP status comes from the handler’s message, mapped through the area’s message map (a dictionary from message text to status code), rather than from the controller choosing a status per branch. Same message, same status, everywhere it is returned.

List endpoints accept pagination and filter parameters, all validated before the query runs (NFR-10), and most accept includeDeleted=true to see logically deleted rows.

Malformed requests

A request that cannot be bound — a body that is not JSON, or a value of the wrong type in the body or query string (?succeeded=maybe, {"name": 123}) — answers 400 with the error The request is malformed., on every endpoint (NFR-10). The answer is a DataOutput envelope even on list endpoints. Authentication and role checks come first, so a caller without a valid token still receives 401, and one of the wrong role 403; refusals that depend on data, made in a handler, come after the 400.

A query parameter that is not nullable no longer falls back to its default when it is empty or unparseable: ?pageNumber=, ?pageNumber=abc, ?pageSize=, ?includeDeleted= and ?includeDeleted=1 are all 400. A nullable one sent empty (?succeeded=) still binds to null and is ignored. A missing required field is not a binding failure: it keeps the field’s own message from the validator.

Of the endpoints that take a body, only POST …/credentials accepts an empty one, meaning “no expiry”.

Errors that are deliberately vague

Some responses tell the caller less than the API knows, on purpose:

• POST /api/auth/login answers the same “invalid credentials” error whether the email is unknown, the password wrong, the person logically deleted, or their scope gone (AF-11a…AF-11e). The checks still run in the specification’s order so the code reads against UC-11 — only the answer is uniform.
• POST /api/auth/password-recovery answers identically whether or not the address belongs to anyone — in the same time, too: it only queues the request, and the lookup, the token and the email happen after the response. A Mailgun failure is logged rather than surfaced — an email outage must not turn into a 500 that confirms an anonymous caller’s guess.
• POST /api/auth/google answers alike for an unverifiable token, a token that does not carry the nonce the request sent, and a Google User whose account is gone (AF-25a, AF-25g, AF-25d).
• POST /api/auth/password-reset and POST /api/auth/verify-email answer “Invalid token.” both for a token nobody issued and for one whose person has since been restricted, deleted or anonymised, or can no longer sign in (AF-13e, AF-14d).

The specification

§5 of the System Requirements Document lists the endpoints as specified, and §7 is the full authorization matrix — every action against every role, including Anonymous. The Use Case Specification Document gives each endpoint’s main flow and every numbered alternative flow.

6 - API explorer

Every endpoint the API exposes, rendered from the published OpenAPI document . The document is generated from the controllers themselves — the summaries below are the ones in the source — and regenerated with python scripts/openapi.py. It is byte-for-byte what a running instance serves at /swagger/v1/swagger.json: both come from the same SwaggerConfiguration.

7 - Flows

Most endpoints are a straight line: validate, read, write, respond. The flows collected here are the ones that are not — they cross services, branch on stored state, or deliberately answer the same way down several different paths.

Each page cites the use case (UC-…) and alternative flows (AF-…) it implements. The authoritative descriptions live in the Use Case Specification Document .

7.1 - Login

POST /api/auth/login — anonymous, rate-limited.

The sequence

sequenceDiagram
    autonumber
    actor C as Client
    participant AC as AuthController
    participant M as CommandMediator
    participant AH as AuditingCommandHandler
    participant H as LoginCommandHandler
    participant V as LoginCommandValidator
    participant PR as Person repository
    participant TS as PersonAuthTokenService
    participant TI as JwtAuthTokenIssuer
    participant DB as PostgreSQL

    C->>AC: POST /api/auth/login {email, password, scopeId?}
    AC->>M: ExecuteCommandAsync(LoginCommand)
    M->>AH: HandleAsync
    AH->>H: HandleAsync

    H->>V: ValidateAsync
    alt invalid shape (AF-11f)
        V-->>H: errors
        H-->>C: 400 validation errors
    end

    H->>PR: find by the lookup the role implies
    PR->>DB: SELECT person + role + scope navigations
    DB-->>PR: person or null
    Note over H: AF-11a unknown · AF-11b wrong password<br/>AF-11c deleted person · AF-11d/e scope not eligible<br/>locked out (FR-AU-09)<br/>→ all answer "invalid credentials"

    H->>H: Hash.TextMatches(password, hash, salt)
    H->>TS: TryBuildSubject(person)

    H->>DB: SELECT active TwoFactorAuth for person
    alt 2FA active (AF-11g)
        H->>H: retire live email codes, issue + mail a fresh one
        H->>H: issue challenge token (MfaPending, ~5 min)
        H-->>C: 200 {requiresTwoFactor, challengeToken, availableMethods}
    else no 2FA
        H->>TS: IssueAsync(subject)
        TS->>TI: IssueAsync
        TI->>DB: SELECT flagged scope permissions
        TI-->>TS: signed JWT + expiry
        H-->>AH: DataOutput{token, expiresAt, emailVerified}
        AH->>DB: INSERT AuditLog(LoginCommand)
        AH-->>C: 200 {token, expiresAt, emailVerified}
    end

Which lookup, and why

Person has no scope column, so how the person is found depends on the role being sought:

The lookup deliberately omits an !IsDeleted filter. AF-11c exists to reject a logically deleted person, so the person has to be found before they can be rejected.

One answer for five causes

AF-11a (unknown email), AF-11b (wrong password), AF-11c (deleted person), AF-11d (a User whose scope is logically deleted) and AF-11e (a ScopeAdmin with no live owned scope) all return the same invalid credentials error.

The checks still run in the specification’s order, so the code reads against UC-11 line by line — only the answer is uniform. An anonymous endpoint that distinguished them would be a directory of which addresses are registered and which accounts still exist.

The answer has to be uniform in time as well as in text. AF-11a used to return without hashing anything, since there was no stored hash to compare against — so “no such account” came back in single-digit milliseconds while every other rejection paid a full Argon2id verification (600 MB / 16 threads) and took hundreds. That gap answered the question the shared message refuses, and varying the scope id turned it into a per-scope directory. The handler now verifies the submitted password against a decoy hash — of a random secret generated once per process, belonging to nobody — and discards the result. A lockout takes the same path, so it is not detectable either.

The lockout counts attempts as they start, not as they fail. Each attempt reserves itself in failed_login_attempts — one conditional UPDATE, refused once the account is locked or ten attempts are already counted — before the password is derived; a wrong password leaves the reservation standing, a right one clears the count. The attempt that reaches ten also sets locked_out_until and resets the count in that same UPDATE, so a sign-in cut short at the limit still locks the account for the usual fifteen minutes, and it unlocks by itself. A right password on the tenth attempt still signs in and clears the lock. Counting after the derivation let ten simultaneous wrong passwords all read a count of zero and all write one, so the account never locked (FR-AU-09).

Scope eligibility

PersonAuthTokenService.TryBuildSubject is the single place the eligibility rules live, shared with two-factor verification so a gated login ends exactly like a direct one:

flowchart LR
    P[Person] --> R{Role}
    R -->|User| U{Their scope deleted?}
    U -->|Yes| X[Not eligible — AF-11d]
    U -->|No| T["Subject: personId, roleId,<br/>scopeId"]
    R -->|ScopeAdmin| A{Any live owned scope?}
    A -->|No| X2[Not eligible — AF-11e]
    A -->|Yes| T2["Subject: personId, roleId,<br/>ownedScopeIds"]
    R -->|SystemAdmin| T3["Subject: personId, roleId<br/>— no scope claims"]

What the token carries

Claims are written by IdentityUserMapper, the same class that reads them back on validation:

The claims are omitted rather than emitted empty, so a token never suggests a scope association the person does not have. Every value is a PublicId — an internal id never reaches a token (NFR-15), except sst, a random value that means nothing outside Heimdall.

Revocation: when a token stops working

A person token is refused, with 401 and “This token has been revoked. Sign in again.”, from the first request after any of these, whoever made the change and whichever token made it:

Each replaces the person’s security stamp, and ActorLivenessFilter, which already reads the person’s row on every request, refuses a token whose sst is missing or no longer matches. The request that made the change still succeeds, but its token is revoked with the rest, so a client signs in again after it. A token issued before this mechanism existed carries no sst and is refused the same way. A 2FA challenge token outdated by such a change is refused at POST /api/auth/2fa/verify as an invalid challenge.

Consumers validating person tokens offline do not see a revocation: they still accept the token until it expires. Heimdall itself refuses it.

Audiences: what a consumer must pin

Heimdall issues three kinds of person token, signed with the same keys under the same issuer. Only the full token is a sign-in, and the audience says which kind a token is:

With HEIMDALL_AUTH_TOKEN_AUDIENCE=heimdall, those are heimdall, heimdall.2fa-challenge and heimdall.subject-rights. The two derived audiences need no configuration of their own, and start-up logs all three.

A consumer that accepts person tokens must validate the audience, pinned to HEIMDALL_AUTH_TOKEN_AUDIENCE exactly. It then refuses challenge tokens, subject-rights-only tokens and application tokens with no knowledge of Heimdall’s claims. A consumer that skips the audience check would take a challenge token, which a password alone obtains, for a full sign-in. Set HEIMDALL_AUTH_TOKEN_AUDIENCE (it defaults to empty), so there is an audience to pin.

Inside Heimdall every bearer token must name HEIMDALL_AUTH_TOKEN_ISSUER as its issuer and exactly one of these three audiences (NFR-30); anything else is refused with 401 “Invalid token”, as a bad signature is. IdentityUserMapper then holds each token to its own audience: it maps a token only when its audience and its mfaPending and subjectRightsOnly claims agree, and refuses one that carries either claim under the wrong audience or one of the derived audiences without its claim.

The 2FA branch

When the person has an active two-factor configuration, login does not return an authentication token at all. It returns a short-lived challenge token carrying mfaPending under its own audience . Only POST /api/auth/2fa/verify and the email-code resend accept it, as a body field; MfaPendingGuardFilter rejects it as a bearer token everywhere, and a consumer pinning the person audience refuses it.

If the Email method is enabled, login retires every live email code for that configuration and mails a fresh one first — so only the code mailed for this attempt can complete it.

Continue at Two-factor authentication .

7.2 - Two-factor authentication

Two-factor authentication is opt-in, per person, and available to User, ScopeAdmin, and SystemAdmin alike. It is not available to Google Users, who are already subject to Google’s own account security.

Every 2FA endpoint acts on the caller themselves — the person comes from the bearer token, never from a path or body — so no caller can reach another person’s configuration.

The lifecycle

stateDiagram-v2
    [*] --> None: no TwoFactorAuth row
    None --> Pending: UC-36 enable<br/>(row created, IsActive = false)
    Pending --> Pending: UC-36 again<br/>(AF-36d — selection overwritten)
    Pending --> Active: UC-37 confirm<br/>(every selected method proven)
    Active --> Active: UC-40 regenerate<br/>(ten fresh recovery codes)
    Active --> None: UC-39 disable
    Active --> Active: UC-38 verify<br/>(completes a gated login)

Setup — UC-36 and UC-37

sequenceDiagram
    autonumber
    actor P as Person (authenticated)
    participant AC as AuthController
    participant EH as EnableTwoFactorAuthCommandHandler
    participant CH as ConfirmTwoFactorAuthCommandHandler
    participant TP as ITotpSecretProtector
    participant ES as ITwoFactorEmailSender
    participant DB as PostgreSQL

    P->>AC: POST /api/auth/2fa/enable {methods, currentPassword}
    AC->>EH: HandleAsync
    EH->>DB: SELECT TwoFactorAuth for caller
    alt already active (AF-36a)
        EH-->>P: rejected — configuration untouched
    end
    alt Email selected and the account-email budget would refuse (AF-36f, AF-36g)
        EH-->>P: 429 — nothing changed or sent, no password check
    end
    alt currentPassword missing or wrong (AF-36e)
        EH-->>P: 401 — nothing created, no account email charged
    end
    opt Email selected
        EH->>DB: reserve one account email (FR-PE-16) — a burst gets one
    end
    EH->>DB: UPSERT pending row (IsActive = false)
    Note over EH,DB: AF-36d — re-initiating overwrites<br/>the pending selection entirely

    opt App selected
        EH->>TP: Protect(fresh TOTP secret)
        TP-->>EH: encrypted secret
        EH->>DB: store TotpSecretEncrypted
        EH-->>P: secret returned once, for enrolment
    end
    opt Email selected
        EH->>DB: retire outstanding codes, INSERT fresh 6-digit code (hash + salt, 10 min)
        EH->>ES: SendAsync(email, code)
    end

    P->>AC: POST /api/auth/2fa/confirm {appCode?, emailCode?}
    AC->>CH: HandleAsync
    CH->>DB: SELECT pending row
    CH->>DB: charge the re-authentication budget (FR-AU-13)
    CH->>CH: check appCode if AppEnabled (AF-37b)
    CH->>CH: check emailCode if EmailEnabled (AF-37c)
    CH->>DB: replace the person's security stamp
    CH->>DB: INSERT 10 recovery codes (SHA-256 digests only)
    CH->>DB: UPDATE IsActive = true
    CH->>DB: mark the confirming email code Used
    CH-->>P: 200 — ten recovery codes, shown exactly once

Recovery codes are 80 bits (FR-2F-20): ten random bytes written as sixteen characters of Crockford’s base32 — the digits and the uppercase letters without I, L, O and U — and shown as XXXX-XXXX-XXXX-XXXX. A code is accepted with or without its hyphens, with spaces, and in any case, and an O, I or L typed in one reads as 0, 1 and 1. Codes of the shorter XXXX-XXXX shape issued before keep working until they are used or regenerated; regenerating (UC-40) is how a person gets the stronger ones.

Enabling needs the password (FR-2F-18): adding a second factor requires proof of identity, as removing one does, and a bearer token alone is not that proof. Confirming revokes every token the person holds, the confirming one included (FR-AU-11): the client keeps the recovery codes, then signs in again, now through UC-38.

IsActive is what separates a confirmed configuration from one still pending. A row with IsActive = false means UC-36 created it and UC-37 has not yet activated it — and only an active configuration gates a login.

The order of the recovery-code and activation writes is deliberate. The repository layer exposes no transaction, so ordering is what stands in for one, and the dangerous half-write is “two-factor is active but the caller holds no recovery codes” — which locks someone out of their own account on the strength of a request that reported failure. Writing the codes first (in one insert, not ten) leaves only harmless failure modes: codes stored against a configuration that never activated, which the next attempt replaces, and which authenticate nothing while IsActive is false. UC-40 orders its writes the same way and for the same reason, creating the replacements before deleting the set they replace, so a failure leaves the caller with the codes they already hold rather than none at all.

Confirmation requires proof of every method selected at setup: an appCode if AppEnabled, an emailCode if EmailEnabled, both if both. A missing or wrong code answers 401 “The password or code is incorrect.”, whichever it was, and is charged to the re-authentication budget below.

Completing a gated login — UC-38

sequenceDiagram
    autonumber
    actor C as Client
    participant AC as AuthController
    participant VH as VerifyTwoFactorAuthCommandHandler
    participant CT as JwtTwoFactorChallengeTokenIssuer
    participant FV as ITwoFactorFactorVerifier
    participant TS as PersonAuthTokenService
    participant DB as PostgreSQL

    Note over C: login answered requiresTwoFactor<br/>with a challenge token
    C->>AC: POST /api/auth/2fa/verify {challengeToken, code | recoveryCode}
    AC->>VH: HandleAsync

    VH->>CT: validate signature, expiry, challenge audience + mfaPending claim
    alt invalid (AF-38a)
        CT-->>VH: rejected
        VH-->>C: 401 challenge invalid
    end

    VH->>DB: SELECT person + active TwoFactorAuth
    opt app code or recovery code (FR-2F-17)
        VH->>DB: charge one guess to the challenge (UPDATE … WHERE attempts < 5)
        alt no guesses left, or redeemed meanwhile
            VH-->>C: 401 challenge invalid
        end
    end
    VH->>DB: charge one failure to the account (FR-AU-12)
    VH->>FV: TOTP? live email code? unused recovery code?
    alt none matches, or the account's second factor is locked (AF-38b / AF-38c)
        FV-->>VH: no
        VH->>DB: at the fifth guess, clear the challenge
        VH-->>C: 401 factor invalid
    end

    VH->>DB: clear the account's second-factor failures
    VH->>TS: TryBuildSubject(person)
    alt scope no longer eligible
        VH-->>C: 401 scope no longer eligible
    end

    VH->>DB: redeem the challenge (UPDATE … WHERE challenge_id = token's)
    VH->>DB: spend the recovery code (UPDATE … WHERE NOT used) + UsedAt
    VH->>DB: spend the email code (UPDATE … WHERE NOT used)
    VH->>TS: IssueAsync(subject)
    TS-->>VH: full authentication token
    VH-->>C: 200 {token, expiresAt, emailVerified}

Three details in that diagram carry real weight:

AF-38b and AF-38c answer identically. A wrong code and an already-used recovery code both return factor invalid, 401 — the same reasoning that collapses UC-11’s five rejections into one.

Scope ineligibility gets its own message. If the challenge token and the second factor were both valid but the person’s scope eligibility no longer holds, the answer is scope no longer eligible, not challenge invalid. Collapsing that case would misdescribe what actually happened — nothing the caller supplied was wrong.

Nothing can be replayed. The redeemed recovery code and the redeemed email code are both marked used before the token is issued. An app code is single-use too, though it has no row to mark: the time step it was accepted at is recorded on TWO_FACTOR_AUTH.last_totp_time_step_used, and a code from that step or earlier is refused (RFC 6238 §5.2). Without it the ±1-step tolerance meant an observed code stayed usable for up to ninety seconds, across verify, disable, and regenerate alike.

A wrong email code costs the code. Five wrong guesses retire it (failed_attempts), so the million values a six-digit code can take are not a million attempts — guessing again costs a fresh login, which is rate limited and mails the account holder a code they did not ask for.

A challenge allows five guesses with an app code or a recovery code (FR-2F-17). Neither has a row of its own to count on, so they are counted on the challenge (challenge_attempts), and at five the challenge is cleared: its token is refused as AF-38a from then on, and further guessing costs a fresh password check. A login resets the count with the challenge.

The account allows ten failures, whatever the challenge (FR-AU-12). Every guess — app code, email code or recovery code — is also counted on the person, and neither a new challenge nor a correct password resets that count; only a second factor that checks out does. The tenth failure locks second-factor verification for fifteen minutes, twice as long at each repeat, up to a day. While it is locked every code is refused, the right one included, with the same factor invalid answer, and the challenge’s own five still run out as usual — so the lock does not show.

All of it holds when requests arrive together. Redeeming the challenge, spending a code, accepting a TOTP step and charging a guess are each one conditional UPDATE (IAtomicWrites), and every guess is charged before it is compared. Of any number of simultaneous requests carrying the same challenge or the same code, exactly one gets a token; a parallel burst of guesses gets exactly the budget compared, no more.

The final token is issued by PersonAuthTokenService — the same service a direct login uses — so a 2FA-gated login ends with exactly the token a direct one would have produced.

Why the guard filter never fires here

MfaPendingGuardFilter runs on every controller action and rejects any identity carrying MfaPending. It never trips on POST /api/auth/2fa/verify because that endpoint is [AllowAnonymous] and reads the challenge token as a body field, not as an Authorization: Bearer credential — so the pipeline never attaches an MFA-pending identity for that call. The filter only ever fires when a challenge token is misused as a bearer token somewhere else — exactly the case FR-2F-10 wants blocked.

Disable and regenerate — UC-39 and UC-40

Both require a valid second factor as well as authentication, and both reuse ITwoFactorFactorVerifier, so “match against TOTP, or the current email code, or an unused recovery code” is implemented in exactly one place.

Every check under a bearer token shares one budget and one answer (FR-AU-13). Enabling, confirming and disabling two-factor authentication, regenerating recovery codes, an own email change and a person’s erasure request are each charged to the account’s re-authentication budget before anything is compared: five failures within fifteen minutes pause them for fifteen minutes. A wrong or missing password, a wrong, missing or used code, and a pause all answer 401 “The password or code is incorrect.” — so disabling never says which of its two credentials was wrong. The budget is kept apart from the login lockout and the second-factor budget, so a stolen token cannot be used to lock its owner out of signing in.

Storage of secrets

That is NFR-16. See Domain model .

7.3 - Google Sign-In

Google Sign-In is off by default and enabled per scope. A Google identity is always User-equivalent — it can never create or authenticate a Scope Admin or System Admin, whatever the Google account is (FR-GO-04).

Enabling it — two independent switches

flowchart LR
    A["PUT /api/scopes/{id}/google-signin<br/>UC-24 — per scope"] --> C{Both true?}
    B["HEIMDALL_GOOGLE_CLIENT_IDS<br/>— per deployment"] --> C
    C -->|Yes| D[Google sign-in works]
    C -->|Scope off| E["403 — sign-in unavailable"]
    C -->|No client IDs| F["401 — every token refused"]

With no client IDs configured, the API registers a verifier that refuses every token and warns once at start-up. This is not a convenience fallback: verification needs an audience to check against (NFR-13), and a verifier with no configured client could only reject everything or trust everything — so it rejects. Every other endpoint keeps working.

Sign-up and sign-in — UC-25

One endpoint, POST /api/auth/google, does both. The first call for a given Google account in a given scope creates the Google User; every later one authenticates it.

sequenceDiagram
    autonumber
    actor C as Client
    participant AC as AuthController
    participant H as GoogleSignInCommandHandler
    participant GV as IGoogleIdTokenVerifier
    participant G as Google
    participant TI as JwtAuthTokenIssuer
    participant DB as PostgreSQL

    C->>AC: POST /api/auth/google {idToken, scopeId, nonce?}
    AC->>H: HandleAsync

    H->>GV: VerifyAsync(idToken)
    GV->>G: signature, issuer, audience, expiry (NFR-13)
    alt unverifiable or absent (AF-25a)
        GV-->>H: null
        H-->>C: 401 google authentication failed
    end
    G-->>GV: payload {sub, email, email_verified, name, picture, nonce}
    alt nonce sent and the token's differs or is absent (AF-25g)
        H-->>C: 401 google authentication failed
    end

    H->>DB: SELECT scope WHERE PublicId = scopeId<br/>AND NOT IsDeleted AND GoogleSignInEnabled
    alt missing, deleted, or disabled (AF-25b)
        H-->>C: 403 google sign-in unavailable
    end

    H->>DB: SELECT GoogleUser WHERE ScopeId AND GoogleId = sub
    alt not found — sign-up (FR-GO-09)
        alt email_verified is not true (AF-25f)
            H-->>C: 403 sign-up requires a verified email address
        end
        H->>DB: is the email free among the scope's Google Users AND Users?
        alt taken (AF-25c)
            H-->>C: 409 email already registered
        end
        H->>DB: INSERT GoogleUser from the verified claims
    else found but deleted (AF-25d)
        H-->>C: 401 google authentication failed
    end

    H->>TI: IssueAsync(googleUser.PublicId, User role, scope.PublicId)
    TI->>DB: SELECT flagged scope permissions
    TI-->>H: signed JWT + expiry
    H-->>C: 200 {token, expiresAt, emailVerified}

Verification comes first, before the scope is even read. An unverified caller learns nothing about which scopes exist. It is also what answers a request that omitted the token entirely — which is why UC-25 needs no 400 flow at all.

AF-25b answers alike for three different situations — the scope is missing, logically deleted, or has the feature switched off. The alternative flow names all three as one outcome, so one filter answers for all three.

A nonce binds the token to the client’s own sign-in attempt (FR-GO-20). nonce is optional: a client that sent one to Google when asking for the ID token sends the same value here, and the token’s nonce claim must equal it exactly; a token with another nonce, or none, answers as an unverifiable token does. The nonce is a client-side check that the token it presents was issued for its own sign-in request; whether a token is accepted rests on its signature, issuer, audience and expiry (NFR-13). A request without nonce compares nothing, as before.

Only an address Google vouches for can sign up (FR-GO-07, AF-25f). A first sign-in whose token does not carry email_verified: true — false, or absent — creates nothing and answers 403 “Google sign-up requires a verified email address.”. This is checked before the address is compared with the scope’s. A Google User that already exists signs in whatever the claim says; FR-GO-19 keeps its stored flag current.

AF-25c is named separately, on purpose. Being told the address is already registered reveals something — but the caller has proved to Google that the address is theirs, and Google vouches for it, so it tells them only about themselves. Uniqueness is checked jointly against the scope’s Google Users and its password Users.

Signing out — UC-26

POST /api/auth/google/sign-out ends the client’s session and nothing else. Heimdall keeps no Google session, and its tokens are stateless signed JWTs with an expiry, so there is nothing to revoke: a copy of the token kept elsewhere stays valid until it expires (FR-GO-18). What the endpoint does is check — it confirms the token still names a live Google User and then answers the success that tells the client to drop the token.

That check is the substance. Authentication reads no database per request, so a token outlives the account it names; one naming a deleted or unknown Google User is refused here.

Administering Google Users — UC-27 to UC-29

All four endpoints are nested under the scope the Google User belongs to (FR-GO-06), and each refuses a Google User reached through the wrong scope.

The by-id read is the one that admits a Google User, and it is why that endpoint carries no [RoleRequirement]: a Google User’s token is User-role, so anything strong enough to keep other Users out would lock out the actor UC-27 grants. The listing admits none of them.

The logical delete is idempotent — repeating it answers 200 with alreadyDeleted: true and writes nothing — and it is honoured everywhere it matters: a deleted account cannot sign in, cannot sign out, and is absent from reads unless includeDeleted=true. The hard delete has no idempotent path; a second call is a 404. Neither cascades, because a Google User owns nothing.

Testing without Google

A third verifier exists for the functional suite, which cannot override a DI registration and must still reach the flows behind verification. It is guarded twice — never in Production, and never without an explicitly set signing secret — and is checked before the real verifier so a test environment cannot accidentally run both.

7.4 - Person onboarding

Creating a person is one use case (UC-06) with three paths, decided by which endpoint is called rather than by a field in the body.

Creating a User — UC-06 path a

sequenceDiagram
    autonumber
    actor A as Actor (SystemAdmin or ScopeAdmin)
    participant PC as PersonController
    participant AH as AuditingCommandHandler
    participant H as CreateUserCommandHandler
    participant OC as IScopeOwnershipChecker
    participant EV as IEmailVerificationService
    participant ES as IEmailVerificationSender
    participant DB as PostgreSQL

    A->>PC: POST /api/scopes/{scopeId}/persons {name, email, password}
    PC->>AH: ExecuteCommandAsync
    AH->>H: HandleAsync

    H->>H: validate input (AF-06d)
    H->>DB: SELECT scope — must exist and not be deleted (AF-06b)
    H->>OC: does the actor own this scope? (AF-06e)
    Note over OC: a SystemAdmin bypasses this check
    H->>DB: is the email free among the scope's Users? (AF-06a, case-insensitive)
    H->>DB: INSERT person (Argon2id hash + salt) + SCOPE_USER row

    H->>EV: IssueAndSendAsync(person)
    EV->>DB: INSERT EmailVerificationToken (48 chars, time-limited)
    EV->>ES: SendAsync(email, token)
    Note over EV,ES: a send failure does not undo the person —<br/>the token is persisted and can be re-sent (UC-15)

    H-->>AH: DataOutput{person}
    AH->>DB: INSERT AuditLog(CreateUserCommand)
    AH-->>A: 201 person created

Email uniqueness is scoped to the role: a User’s address must be unique within their scope (compared case-insensitively, LOWER() in SQL), while a ScopeAdmin’s or SystemAdmin’s is unique system-wide. The same address can therefore be a User in several different scopes — which is exactly why login needs a scope identifier to find a User.

Verifying the address — UC-14

sequenceDiagram
    autonumber
    actor P as Person
    participant FE as Front-end verification page
    participant AC as AuthController
    participant H as VerifyEmailCommandHandler
    participant DB as PostgreSQL

    Note over P: opens the emailed link<br/>?token=…
    P->>FE: click link
    FE->>AC: POST /api/auth/verify-email {token}
    AC->>H: HandleAsync
    H->>DB: SELECT token, its person and their scopes
    alt unknown (AF-14c), or the person may no longer be acted on (AF-14d)
        H-->>FE: 400 — invalid token
    end
    alt expired (AF-14a) / spent (AF-14b)
        H-->>FE: 400 — each rejection named distinctly
    end
    H->>DB: UPDATE person.EmailVerified = true<br/>WHERE address unchanged AND not restricted / deleted / anonymised
    H->>DB: mark every live token for this person Used
    H-->>FE: 200

The endpoint is anonymous — someone arriving from a link in their mail client holds no token of any other kind.

Spending a token retires every other live token the person holds of that kind, so a verification link left in an inbox stops working once the address is verified. An address that was already verified answers 200 rather than an error: UC-14 defines no alternative flow for it, and the caller’s intent has been satisfied either way. A person restricted, deleted or anonymised since the link was mailed, or who can no longer sign in through their scope, gets 400 “Invalid token.” and nothing is written (FR-EV-08), as UC-13 answers them.

Replacing a lost link — UC-15

POST /api/auth/resend-verification is authenticated and takes no body. The person is read from the bearer token, so a caller can only ever ask for their own link.

flowchart TD
    A[POST /api/auth/resend-verification<br/>bearer token only] --> B{Already verified?}
    B -->|Yes| C["400 — AF-15a<br/>a link mailed to it could do nothing"]
    B -->|No| G{Account-email budget<br/>reserves a send?}
    G -->|"No — cooldown or daily limit"| H["429 — AF-15b / AF-15c<br/>nothing sent; the last link still works"]
    G -->|Yes| D[Retire outstanding tokens]
    D --> E[Issue + mail a fresh one]
    E --> F[200 — only the newest link works]

Note the asymmetry with UC-14: verifying an already-verified address answers 200, but resending to one answers 400. Verification’s job is done either way; a resend would mail a link that could do nothing when clicked.

A resend is charged to the person’s account-email budget (FR-PE-16), which it shares with a two-factor setup code and the notice an own email change sends: one per HEIMDALL_ADMIN_EMAIL_COOLDOWN_IN_SECONDS (five minutes by default) and five per day-long window from the first, reserved by one write before anything is sent. Inside the cooldown the answer is 429 “An email of this kind was sent to you recently. Try again in a few minutes.” (AF-15b); once the window’s five are spent, 429 “You have reached the limit for account emails. Try again later.” (AF-15c). Both carry Retry-After, the seconds until a send would be accepted. Nothing is sent or retired either way. A link an administrator sent, at creation or through UC-51, is not charged, so the person may still ask once straight after. The endpoint is under the credential endpoints’ rate limit too, whose own 429 says “Too many requests.” and carries a Retry-After header.

An administrator resending it — UC-51

A System Admin, or the owner of a User’s scope, can ask for the link on the person’s behalf with POST /api/persons/{id}/verification-email. It is UC-15’s send — live links retired, a new one mailed to the person’s own address — refused for a deleted or restricted person (409) or a verified address (400). At most one such email goes to a person per HEIMDALL_ADMIN_EMAIL_COOLDOWN_IN_SECONDS (five minutes by default), counting any verification email sent to the person in the window, including the one sent when the account was created; a request inside the window answers 429 and sends nothing. The check is best-effort: simultaneous requests for the same person can both pass it.

Without mail credentials

With Mailgun unconfigured, the API registers logging senders instead: each token is written to the log rather than emailed, with a single warning at start-up. That keeps local runs and the functional suite working without credentials and off the network.

It is a supported mode, not a broken one — outside Production. An unconfigured Production deployment refuses to start outright, because the fallback would print verification tokens, password reset tokens, and 2FA codes in plaintext to the logs, which is an account-takeover primitive for anyone who can read them.

Both emails carry a link built from HEIMDALL_EMAIL_VERIFICATION_URL / HEIMDALL_PASSWORD_RESET_URL, with the token appended as a token query parameter. If no link is configured the email carries the bare token instead, which still works — the link is only a convenience wrapper around it.

A scope may override both links for its own Users (PUT /api/scopes/{id}/email-links), so a client system’s users are sent to that system’s screens; administrators, and a scope with no link set, use the global ones.

7.5 - Password recovery

Two anonymous, rate-limited endpoints: one asks for a link, the other spends it.

Requesting a link — UC-12

sequenceDiagram
    autonumber
    actor C as Anonymous caller
    participant AC as AuthController
    participant H as PasswordRecoveryCommandHandler
    participant Q as PasswordRecoveryQueue
    participant W as PasswordRecoveryDispatcher
    participant PR as PasswordRecoveryProcessor
    participant PS as IPasswordResetService
    participant S as IPasswordResetSender
    participant DB as PostgreSQL

    C->>AC: POST /api/auth/password-recovery {email, scopeId?}
    AC->>H: HandleAsync
    H->>H: validate input shape (NFR-10)
    Note right of H: the only rejection this endpoint ever issues
    H->>Q: TryEnqueue(email, scopeId)
    H-->>C: 200 — identical response, in the same time, either way

    Q-->>W: next request (background, own DI scope)
    W->>PR: ProcessAsync
    PR->>DB: find by the lookup the role implies
    alt person found and eligible
        PR->>PS: issue token
        PS->>DB: INSERT PasswordResetToken (time-limited)
        PS->>S: SendAsync(email, token)
    else nobody, deleted or restricted person, or deleted scope (AF-12a)
        Note over PR,DB: no row written, no email sent
    end

Every path returns the same success output. AF-12a — the address belongs to nobody — is not an error flow but the absence of one: the handler issues no token and answers exactly as it would have. A logically deleted person, and a User whose scope is deleted, are treated the same way.

The only thing that distinguishes the two paths is a row that does not get written and an email that consequently never arrives — neither of which is visible to the caller.

The same answer, in the same time. While the lookup, the token insert and the Mailgun call ran on the request, a registered address answered a Mailgun round trip later than an unknown one — a timing difference that answered exactly what the uniform response refuses. So the handler only validates and queues; everything that depends on the address happens afterwards, in PasswordRecoveryProcessor, run by a hosted service in a DI scope of its own (never the finished request’s). The queue is in memory and bounded: a durable outbox would keep every address anybody typed, registered or not, and a response-time floor would have to outlast Mailgun’s slowest send. The cost is that a restart drops whatever is still queued, which a person who receives nothing simply asks for again.

An administrator sending the link — UC-52

POST /api/persons/{id}/password-reset lets a System Admin, or the owner of a User’s scope, have the link mailed to the person’s own address. Eligibility is UC-12’s, from the same code — but because the caller is authenticated, a refusal is reported instead of hidden: 409 for a deleted or restricted person, or one whose account could not sign in. The send is not queued, since there is no anonymous caller to protect from a timing difference. The same per-person cooldown as UC-51 applies (429), and is best-effort: simultaneous requests for the same person can both pass it.

Setting the new password — UC-13

sequenceDiagram
    autonumber
    actor P as Person
    participant FE as Front-end reset page
    participant AC as AuthController
    participant H as ResetPasswordCommandHandler
    participant DB as PostgreSQL

    P->>FE: opens the emailed link ?token=…
    FE->>AC: POST /api/auth/password-reset {token, newPassword}
    AC->>H: HandleAsync
    H->>H: validate the new password's shape
    H->>DB: SELECT token, its person and their scopes
    alt unknown, or the person may no longer be acted on (AF-13c / AF-13e)
        H-->>FE: 400 — invalid token
    end
    alt expired / already spent
        H-->>FE: 400 — each rejection named
    end
    H->>DB: spend the token (UPDATE … WHERE NOT used AND unexpired)
    alt a parallel request spent it first
        H-->>FE: 400 — already used (AF-13b)
    end
    H->>DB: UPDATE person SET hash, salt, security stamp<br/>WHERE address unchanged AND not restricted / deleted / anonymised
    alt the person changed since it was read
        H-->>FE: 400 — invalid token
    end
    H->>DB: mark every other live reset token for this person Used
    H-->>FE: 200

Both endpoints are anonymous because someone arriving from a link in their mail client holds no token of any other kind.

Spending a reset token retires every other live reset token the person holds. A second “forgot password” click cannot be replayed after the first has already changed the password.

The account is checked again when the link is followed (FR-PR-08). A link lives for an hour, and the person may be restricted, deleted or anonymised, or lose the scope they sign in through, while it waits in a mailbox. UC-12’s rule is run again, and a person it no longer admits gets exactly the unknown-token answer, 400 “Invalid token.”, with nothing written — the token stays as it was, and a restricted record is preserved. The password itself is written by one conditional UPDATE, together with a fresh security stamp that revokes every earlier session, which repeats those checks and requires the address the person was read with. After the row is created nothing else writes the password columns, so an edit saved from an older copy of the person cannot put the old password back.

An email change retires the links (FR-PE-17). Whoever changes a person’s address, every live reset and verification link they hold is retired, before the new address is saved and again straight after. Following one afterwards answers 400 “Token already used.”.

Why login costs what it costs

Password verification is Argon2id — by this codebase’s hashing library defaults, 600 MB and 16 threads per verification. That is deliberate for a stored credential, and it is also precisely why these endpoints are rate-limited: an unthrottled burst against /login is a memory and CPU exhaustion vector before it is a brute-force one. See Operations .

7.6 - Scope permission claims

A scope permission is a named permission defined inside one scope. It has no owner of its own — owning the scope is the whole of the authorization to manage it — and it is a leaf in the data model: nothing carries a foreign key to it.

Its one moving part is the IncludeAsJwtClaim flag.

From definition to claim

sequenceDiagram
    autonumber
    actor SA as Scope Admin
    participant SPC as ScopePermissionController
    participant CH as CreateScopePermissionCommandHandler
    participant DB as PostgreSQL
    actor U as User in that scope
    participant AC as AuthController
    participant LH as LoginCommandHandler
    participant TI as JwtAuthTokenIssuer

    SA->>SPC: POST /api/scopes/{scopeId}/permissions<br/>{name, description, includeAsJwtClaim: true}
    SPC->>CH: HandleAsync
    CH->>DB: is the actor an owner of this scope?
    CH->>DB: INSERT ScopePermission
    CH-->>SA: 201

    Note over U: later — an ordinary login
    U->>AC: POST /api/auth/login
    AC->>LH: HandleAsync
    LH->>TI: IssueAsync(subject)
    TI->>DB: SELECT DISTINCT name<br/>WHERE scope in subject's scopes<br/>AND NOT scope.IsDeleted<br/>AND NOT permission.IsDeleted<br/>AND IncludeAsJwtClaim
    DB-->>TI: permission names
    TI->>TI: fold into the scopePermissions claim
    TI-->>U: JWT carrying the permission names

Which permissions a caller claims

flowchart TD
    S[Subject being issued a token] --> R{Role}
    R -->|User| A["The permissions of<br/>the one scope they belong to"]
    R -->|ScopeAdmin| B["The union over<br/>every scope they own"]
    R -->|SystemAdmin| C["None — they belong<br/>to no scope"]
    A & B --> F["Filtered: scope not deleted,<br/>permission not deleted,<br/>IncludeAsJwtClaim set"]
    F --> G["Distinct names →<br/>scopePermissions claim (JSON array)"]

The fold happens at issuance, reading the database once. A permission created, flagged, or deleted after a token was issued does not change that token — the holder picks up the change on their next login. This is the same trade the rest of the authentication design makes: no database read per request, in exchange for claims that are a snapshot rather than a live view.

A System Admin carries no scopePermissions claim at all. They belong to no scope, so there is nothing to fold — and nothing they need it for, since their authority is not scope-derived.

Managing them — UC-31 to UC-35

The hard delete is System-Admin-only for the same reason it is on applications and Google Users: a Scope Admin may retire a permission in a scope they own, but never purge it.

Deletion behaviour

Both deletions are simple, because a permission is a leaf:

• Logical delete (UC-34) flips only its own IsDeleted flag. Nothing cascades. It stops being folded into new tokens immediately.
• Hard delete (UC-35) removes the row. Nothing cascades.

The interesting case is the scope’s deletion:

Not cascading the logical delete is deliberate. The permissions become unreachable anyway — the listing endpoint gates on the scope’s IsDeleted, and the claim fold above excludes permissions of deleted scopes — so nothing is exposed. Leaving them untouched means a restored scope recovers its permission set unchanged, which cascading would have destroyed.

7.7 - Audit logging

NFR-09: all write operations shall produce audit log entries.

Rather than a line in every handler — forgettable, and duplicated forty times — this is a decorator applied at registration.

How a handler gets audited

sequenceDiagram
    autonumber
    participant DI as DI container
    participant M as CommandMediator
    participant A as AuditingCommandHandler
    participant H as Concrete handler
    participant W as AuditLogWriter
    participant AA as IActorAccessor
    participant DB as PostgreSQL

    M->>DI: resolve ICommandHandlerAsync<TCommand, TOutput>
    DI-->>M: AuditingCommandHandler wrapping the concrete handler
    M->>A: HandleAsync(command, cancellationToken)
    A->>H: HandleAsync(command, cancellationToken)
    H->>DB: the actual write
    H-->>A: DataOutput{success, data}

    alt success
        A->>A: resolve target from output.Id / output.PublicId
        A->>W: WriteAsync(commandTypeName, targetId)
        W->>AA: ActorPersonId, ActorRole
        AA-->>W: from the current request's IdentityUser
        W->>DB: INSERT AuditLog
        alt the insert fails
            W--xA: exception
            A->>A: log a warning — the request still succeeds
        end
    else failure
        Note over A: nothing written — only successful writes are audited
    end

    A-->>M: the unchanged DataOutput

Registration is the whole mechanism:

services.AddScoped<THandler>();
services.AddScoped<ICommandHandlerAsync<TCommand, TOutput>>(provider =>
    new AuditingCommandHandler<TCommand, TOutput>(
        provider.GetRequiredService<THandler>(),
        provider.GetRequiredService<IAuditLogWriter>(),
        provider.GetRequiredService<ILogger<AuditingCommandHandler<TCommand, TOutput>>>()));

Every write handler in Startup.AddDependencies is registered with AddAuditedCommandHandler, so adding a new command means adding one registration line and inheriting the audit trail.

What an entry records

Three design choices are worth calling out.

ActorPersonId is not a foreign key. It is a bare PublicId, so an entry survives the hard deletion of the person who made the write — which is exactly the case an audit trail exists for.

The table is append-only. Entries are never deleted. The only update a database trigger permits is the retention pass clearing the actor attribution, and a target naming a person or Google User, once due (NFR-21).

The target is resolved reflectively, from the output’s Id or PublicId property. Commands whose output carries neither record a null target rather than failing.

Failures never fail the request

If writing the entry throws, the decorator logs a warning and returns the original result. The user’s write already succeeded and committed; turning that into a 500 would misreport what happened and invite a retry of an operation that already took effect.

The trade is explicit: audit-trail completeness is best-effort against a database failure, and the warning in the log is the record that a gap exists.

Anonymous writes

IActorAccessor reads the current request’s IdentityUser, which is null on an anonymous request. The anonymous write endpoints — login, password recovery, password reset, email verification, Google sign-in, second-factor verification — therefore produce entries with a null actor. The Action still names the command, so the entry records what happened even when it cannot record who.

Reading the trail — UC-48

GET /api/audit-log lists entries for a System Admin, newest first. Ties are broken by write order, so the order is deterministic for a fixed set of rows. Every command writes to the trail, so entries written between two page requests shift older ones and the next page can repeat some; to page a stable snapshot, pin to to the time of your first request. It filters by from/to (UTC, inclusive; a value without an offset is read as UTC), actorId, action, targetId and succeeded, combined with AND. targetId is indexed (ix_audit_log_target_id), so “what happened to this entity?” does not scan the table.

The listing reads AUDIT_LOG and nothing else. A cleared attribution stays cleared: actorId and actorRole read null, and no join or neighbouring entry is used to put a name back. A cleared person target reads targetId: null the same way, so filtering by targetId cannot find that entry. Listing is a read and writes no entry of its own.

7.8 - Application authentication

An application authenticates to Heimdall as itself: an administrator issues it a secret (UC-53), the application exchanges the secret for a short-lived token (UC-56), and a consumer service checks that token live (UC-57). This page is written for the people building that consumer. The authoritative descriptions live in the Use Case Specification Document .

Who this is for

A service that must know which registered application is calling it, not which person. Cerberus is the first. Such a service never sees a person’s token for this purpose and never holds a role: an application token carries the application’s identity and nothing else.

Provisioning and rotation

A System Admin, or the Scope Admin who owns the application and still owns its scope, issues a credential. The expiresAt in the body is optional; a value without an offset is read as UTC.

curl -X POST http://localhost:5177/api/scopes/$SCOPE_ID/applications/$APPLICATION_ID/credentials \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiresAt":"2030-01-01T00:00:00Z"}'

The answer is 201 Created:

{
  "data": {
    "id": "6f1c0d52-8f0e-4a43-9c52-2d6f6a9b1d11",
    "secret": "hds_q3y0lV8mJ1k0d9yq5Qh2a8Xv7nTz4RbC6uWe1sPoKfM",
    "createdAt": "2026-10-14T12:00:00Z",
    "expiresAt": "2030-01-01T00:00:00Z"
  },
  "messages": ["Application credential issued. Store the secret now: it is never shown again."],
  "errors": [],
  "success": true
}

The secret appears in this response and nowhere else. Heimdall keeps only its SHA-256 hash, so no later call, backup or log can return it. Put it in the consumer’s secret store now. A lost secret is replaced, not recovered: issue another and revoke the lost one.

An application holds at most two live credentials (not revoked, not expired). That limit is what makes rotation free of downtime:

1. issue a second credential (POST …/credentials);
2. deploy its secret to the application;
3. revoke the first (DELETE …/credentials/{credentialId}).

With two already live, a third is refused with 409 Conflict; revoke one first. GET …/credentials lists them newest first with id, createdAt, expiresAt, revokedAt, lastUsedAt and live, so you can see the new secret in use (lastUsedAt) before you revoke the old one.

Obtaining a token

The application exchanges a secret for a token. The endpoint is anonymous: the secret authenticates.

curl -X POST http://localhost:5177/api/applications/token \
  -H "Content-Type: application/json" \
  -d "{\"applicationId\":\"$APPLICATION_ID\",\"scopeId\":\"$SCOPE_ID\",\"secret\":\"$APPLICATION_SECRET\"}"

{
  "data": {
    "id": "0c9a3e7e-5a53-4a61-8e57-6b3f0e0d7a10",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
    "expiresAt": "2026-10-14T12:10:00Z"
  },
  "messages": ["Application token issued."],
  "errors": [],
  "success": true
}

Request a new token shortly before expiresAt and reuse it until then. Never request one per call: the endpoint is rate-limited per client address like person sign-in, and each exchange is audited.

Every refusal is the same 401 Unauthorized — “The application credentials were not accepted.” — so the endpoint reveals nothing about which applications, scopes or credentials exist. When you see it, check, in order:

• the applicationId is the application the credential was issued for;
• the scopeId is that application’s scope;
• the credential is live: not revoked, not past its expiresAt, and the application and scope are not deleted (GET …/credentials shows live);
• the secret is exactly as issued. Surrounding whitespace is trimmed (a trailing newline from a file, for one); a truncated or altered secret is not accepted.

A request that is missing a field, carries a secret over 100 characters, or is not readable JSON (or carries an id that is not a GUID) is a 400 instead: the field’s message, or “The request is malformed.” for a body that cannot be read.

The token

An application token is a JWT signed with HMAC-SHA256 under the same keys as person tokens, valid for ten minutes by default (HEIMDALL_APPLICATION_TOKEN_EXPIRATION_IN_SECONDS).

There is no role claim. An application token never grants a role, and Heimdall’s own endpoints refuse it: any token carrying tokenKind is refused where a person token is expected.

Validating offline

A consumer can validate the token without calling Heimdall. It must check all of these:

• the algorithm is HS256, and nothing else is accepted;
• the signature, against both signing keys while a rotation is in progress (HEIMDALL_AUTH_TOKEN_SECRET and HEIMDALL_AUTH_TOKEN_SECRET_PREVIOUS);
• the issuer, when Heimdall is configured with one (Heimdall itself requires its own issuer, or none when none is configured, and the application audience as the token’s only audience — NFR-30);
• the audience is the application audience, the value of HEIMDALL_APPLICATION_TOKEN_AUDIENCE;
• the lifetime, with zero clock skew;
• tokenKind is "application".

If the consumer also validates person tokens, it must pin the person audience. Both kinds are signed with the same keys. A consumer that checks the signature but not the audience would accept an application token as a person’s. Heimdall refuses to start when the two audiences are equal for exactly this reason. Pinning it also refuses Heimdall’s 2FA challenge and subject-rights-only tokens, which carry audiences of their own (Login: audiences ).

Heimdall itself validates with zero skew, so instances whose clocks differ can refuse a freshly issued token for the length of the drift. Keep clocks synchronised (NTP).

Checking live

Offline validation says the token was issued and has not expired. It cannot say the credential is still wanted. For that, present the token to Heimdall:

curl http://localhost:5177/api/applications/self \
  -H "Authorization: Bearer $APPLICATION_TOKEN"

{
  "data": {
    "applicationId": "0c9a3e7e-5a53-4a61-8e57-6b3f0e0d7a10",
    "name": "Cerberus",
    "scopeId": "3b1e5d46-1d3c-4f4e-8a35-0f6d6b6f8e22",
    "credentialId": "6f1c0d52-8f0e-4a43-9c52-2d6f6a9b1d11",
    "expiresAt": "2026-10-14T12:10:00Z"
  },
  "messages": ["Application token accepted."],
  "errors": [],
  "success": true
}

The answer is 200 OK only when the token validates (as above) and its credential is live and its application and scope are live and match the token. Anything else is one 401 Unauthorized — “The application token was not accepted.” — whatever failed.

Revocation policy

Revoking or expiring a credential, or deleting the application or its scope, takes effect at the next live check for every token already issued. A token’s own exp is fixed when it is issued, so it stays valid offline for up to its whole lifetime, ten minutes by default, after its credential expires or is revoked. Only the live check reflects that at once. So a consumer re-checks before every sensitive release, and treats the offline check as a fast path for everything else.

Status codes

8 - Environments and deployment

The API runs in four environments. All of them use the same image and the same docker-compose.yml ; what differs between them is the env file, who deploys it and, mostly, what the host’s PostgreSQL has to be told to allow.

example.com stands for the real domain throughout this page. In every VPS environment the API is also served under the web UI’s own host at /api/ (https://heimdall-dev.example.com/api/…, -hml, and https://heimdall.example.com/api/…), which is how heimdall-ui’s browser build calls it without CORS.

What the ASP.NET environment changes:

Local is deployed by hand on Docker Desktop. Development, homologation and production share one Ubuntu VPS and are deployed by yggdrasil , whose Jenkins runs this repository’s Jenkinsfile . Development and homologation are started only while somebody uses them.

What is being deployed

One service, api, built from the repository’s Dockerfile :

• A multi-stage build that publishes the Web API and an EF Core migrations bundle. The bundle is a plain executable, so the runtime image never needs the SDK or dotnet-ef.
• The entrypoint applies pending migrations and only then starts the API — which is what lets a container be pointed at an empty database. Set HEIMDALL_RUN_MIGRATIONS=false to apply them out of band instead; see Operations . With HEIMDALL_MIGRATIONS_CONNECTIONSTRING set, the bundle migrates as that connection’s role — the schema’s owner — and the API runs as a role that owns nothing; see Database roles .
• The container drops to a non-root user, writes logs to a named volume, and answers a health check on /healthcheck — Compose reports the container healthy only once the API answers.

PostgreSQL is deliberately not a service in the Compose file. Every host already runs one instance shared by several services and environments, each owning a database of its own. So the first half of each walkthrough below is about that instance, not about Docker.

Windows — the local environment

Docker Desktop on the developer’s machine, against the PostgreSQL installed on Windows. Nothing deploys here but the developer: no Jenkins, no Traefik, the port published on the host.

1. Check the engine

In PowerShell, from the repository root:

docker version --format '{{.Server.Version}}'
docker context ls

The context marked * should be desktop-linux. If the command fails, start Docker Desktop and wait for the whale icon to stop animating.

2. Create the database and its login

Each service on the shared instance gets its own database and its own role. With psql on PATH (C:\Program Files\PostgreSQL\18\bin), as the postgres superuser:

psql -U postgres -c "CREATE ROLE heimdall_svc LOGIN PASSWORD '<pick-a-password>';"
psql -U postgres -c "CREATE DATABASE heimdall_local OWNER heimdall_svc;"

3. Confirm the container can reach it

Docker Desktop forwards a container’s connection to host.docker.internal through its own VM, and the Windows PostgreSQL sees it arrive from 127.0.0.1 — so the stock pg_hba.conf, which allows host all all 127.0.0.1/32, already covers it. Nothing to change here, and no Windows Firewall rule to add either, because nothing crosses a real network interface.

Prove it before going further, rather than discovering it from a container that will not start:

docker run --rm --add-host host.docker.internal:host-gateway alpine sh -c 'nc -z -w 3 host.docker.internal 5432 && echo reachable || echo unreachable'

And that the credentials themselves work, end to end:

docker run --rm --add-host host.docker.internal:host-gateway postgres:18-alpine psql "postgresql://heimdall_svc:<password>@host.docker.internal:5432/heimdall_local" -c "select 1"

A row of 1 means the container has everything it needs. no pg_hba.conf entry for host "<address>" means the connection arrived from an address the rules do not cover — add host heimdall_local heimdall_svc <that-address>/32 scram-sha-256 to pg_hba.conf and reload the service.

4. Write the env file

Copy-Item docker/local.env.example docker/local.env -Confirm

-Confirm is not decoration: the template’s values are empty, so re-running this over a file already filled in silently un-fills it, and the next up fails with required variable ... is missing a value — which reads like the file was never written rather than like it was overwritten.

docker/local.env is gitignored — it holds the database password, the token signing secret and the master user’s credentials. Open it and fill in at least:

DB_HOST=host.docker.internal is already correct for Docker Desktop. To generate the secret:

[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Maximum 256 }))

Every other variable has a default that suits a local deployment: Swagger and the developer exception page are on, and verification and reset e-mails are written to the log instead of sent, because ASPNETCORE_ENVIRONMENT=Development and the Mailgun variables are empty. The e-mails’ links point at the local heimdall-ui, http://localhost:8081.

5. Build and start

docker compose --env-file docker/local.env up -d --build

The first build takes a few minutes — it restores, publishes, and builds the migrations bundle. Later builds reuse the layer cache, and a source-only change re-runs neither the tool restore nor the package restore.

6. Verify

docker compose --env-file docker/local.env ps

Wait for STATUS to read Up (healthy) — the health check has a 30 s start period, so starting is expected at first. Then:

curl.exe http://localhost:8080/healthcheck

The start-up log should show the migrations applied and then the API listening:

docker compose --env-file docker/local.env logs -f api

Swagger UI is at http://localhost:8080/swagger , and the master user from the env file can log in at POST /api/auth/login. On an empty database the entrypoint’s migration step is where a bad connection string surfaces — read the first twenty lines of the log before anything else.

7. Day-to-day

The env file has to be passed on every Compose command, not just up: it supplies COMPOSE_PROJECT_NAME, so without it Compose looks for a differently-named project and reports nothing running.

The VPS — development, homologation and production

One Ubuntu VPS runs all three, behind yggdrasil’s Traefik, against the PostgreSQL installed on the VPS itself. The VPS’s own setup — Docker, the platform stack, Jenkins, the wildcard certificate and the single *.example.com DNS record that covers heimdall-api-dev, heimdall-api-hml and heimdall-api alike — is yggdrasil’s, and described in its documentation. What follows is what this API needs on top of it.

How yggdrasil deploys it

Jenkins builds the image on the VPS and runs docker compose with this repository’s Compose file plus yggdrasil’s stacks/heimdall-api.proxy.yml, which:

• removes the host port — Traefik, on the shared edge network, is the only way in, so API_PORT means nothing here;
• names the project heimdall-api-<environment> (COMPOSE_PROJECT_NAME is ignored too) and gives the container the alias heimdall-api.<environment> on the edge and telemetry networks — Prometheus scrapes heimdall-api.<environment>:9464 there;
• routes two hosts to it: PUBLIC_HOST (heimdall-api-dev.example.com) for the mobile and desktop clients, and UI_HOST + /api/ (heimdall-dev.example.com/api/) for heimdall-ui’s browser build.

The env file is /etc/yggdrasil/<environment>/heimdall-api.env on the VPS, never in a repository.

Development and homologation are on demand. A deploy still builds, starts and health-checks the new version — a broken build is caught and rolled back either way — but an environment that was not running before the deploy is stopped again afterwards. To use one, on the VPS:

scripts/ygg.sh env start development

and scripts/ygg.sh env stop development when done (homologation likewise). The yggdrasil console shows each environment’s state, a stopped on-demand environment as Stopped rather than as a problem.

1. Open PostgreSQL to the bridge network

This is the step that fails silently if skipped. The container connects to host.docker.internal, which Compose maps to the Docker bridge gateway (172.17.0.1) — a real interface, not a forwarded loopback. Ubuntu’s PostgreSQL ships listening on 127.0.0.1 only, so it is unreachable from a container until told otherwise.

Check what it listens on:

ss -ltn | grep 5432

127.0.0.1:5432 alone means the edit below is needed. In /etc/postgresql/<version>/main/postgresql.conf:

listen_addresses = 'localhost,172.17.0.1'

Naming the gateway rather than * keeps the instance off every other interface — including the VPS’s public address. listen_addresses requires a restart:

sudo systemctl restart postgresql

2. Create each environment’s database and login

One PostgreSQL instance, one database and its own logins per environment, so that a development or homologation container — or a leaked development password — cannot reach production’s data. Production keeps the database it has always had, heimdall.

The supported setup runs the migrations as an owner role and the API as a role that owns nothing (NFR-29), so each environment has two logins. For a new environment:

sudo -u postgres createuser --pwprompt heimdall_development_owner
sudo -u postgres createuser --pwprompt heimdall_development_svc
sudo -u postgres createdb --owner heimdall_development_owner heimdall_development

sudo -u postgres createuser --pwprompt heimdall_homologation_owner
sudo -u postgres createuser --pwprompt heimdall_homologation_svc
sudo -u postgres createdb --owner heimdall_homologation_owner heimdall_homologation

then apply the grants and the rest of the steps in Operations, “Database roles” (“A new deployment”). Production’s pair is heimdall_owner and heimdall_svc. An environment whose database belongs to the API’s own login is moved to this setup with the steps in the same section (“Switching an existing deployment over”). Skip what an environment already has.

Then, in /etc/postgresql/<version>/main/pg_hba.conf, one rule per login for the Docker range, below the loopback rules — each login reaches its own database and no other:

host    heimdall                 heimdall_svc                   172.16.0.0/12    scram-sha-256
host    heimdall                 heimdall_owner                 172.16.0.0/12    scram-sha-256
host    heimdall_development     heimdall_development_svc       172.16.0.0/12    scram-sha-256
host    heimdall_development     heimdall_development_owner     172.16.0.0/12    scram-sha-256
host    heimdall_homologation    heimdall_homologation_svc      172.16.0.0/12    scram-sha-256
host    heimdall_homologation    heimdall_homologation_owner    172.16.0.0/12    scram-sha-256

The owner rules are needed only while the container migrates; an environment that migrates out of band gives its owner a local rule instead.

172.16.0.0/12 rather than one network’s subnet: yggdrasil’s edge and telemetry networks, and any network Docker creates later, are all allocated from it. pg_hba.conf needs only a reload:

sudo systemctl reload postgresql

3. Confirm a container can reach each database

docker run --rm --add-host host.docker.internal:host-gateway alpine sh -c 'nc -z -w 3 host.docker.internal 5432 && echo reachable || echo unreachable'
docker run --rm --add-host host.docker.internal:host-gateway postgres:18-alpine psql "postgresql://heimdall_development_svc:<password>@host.docker.internal:5432/heimdall_development" -c "select 1"

Repeat the second line for homologation and production. unreachable points back at listen_addresses; no pg_hba.conf entry for host points at the pg_hba.conf rules. And the separation should hold — the development login against production’s database must be refused:

docker run --rm --add-host host.docker.internal:host-gateway postgres:18-alpine psql "postgresql://heimdall_development_svc:<password>@host.docker.internal:5432/heimdall" -c "select 1"

4. Write each environment’s env file

Each environment has a template in the repository — docker/development.env.example, docker/homologation.env.example, docker/production.env.example — already filled in with what that environment needs, example.com standing for the domain. On the VPS, as the user that owns yggdrasil’s secrets directory:

cp docker/development.env.example /etc/yggdrasil/development/heimdall-api.env

Replace example.com with the real domain, then fill in at least:

What the templates already set, and how the three differ:

All three set DB_HOST=host.docker.internal and HEIMDALL_TRUSTED_PROXIES=172.16.0.0/12 — Traefik reaches the container from yggdrasil’s edge network, so forwarded addresses are believed from the Docker range and from nobody else — and leave HEIMDALL_CORS_ALLOWED_ORIGINS empty, since heimdall-ui calls the API under its own origin.

scripts/ygg.sh config heimdall-api on the VPS opens the file of the environment it asks for and redeploys with it.

5. Deploy and verify

Push — develop for development, a release/x.y.z branch for homologation — and follow the build in Jenkins or in the yggdrasil console. The first deploy of an on-demand environment ends stopped; start it, then:

curl https://heimdall-api-dev.example.com/healthcheck
curl https://heimdall-dev.example.com/api/healthcheck

Both answer when Traefik routes both hosts. The start-up log should show the migrations applied and then the API listening:

docker compose -p heimdall-api-development logs -f api

6. Day-to-day

Redeploys come from Jenkins, not from docker compose up by hand: a hand-run up would skip yggdrasil’s overlay and publish the API’s port on the host.

Production

Production follows the steps above with docker/production.env.example, and differs in what matters:

• ASPNETCORE_ENVIRONMENT=Production — no Swagger, no developer exception page, no EF parameter logging, and the API refuses to start without MAILGUN_API_KEY and MAILGUN_DOMAIN rather than silently swallowing every e-mail it owes a user. It never needs HEIMDALL_ALLOW_SENSITIVE_DIAGNOSTICS.
• It is always on: scripts/ygg.sh env stop production refuses unless forced.
• It is deployed only from a release pull request whose checks have all passed, and a failed deploy rolls back to the previous production image and leaves the pull request open.
• HEIMDALL_RUN_MIGRATIONS=false if it ever runs more than one replica: two containers applying migrations at start-up will race each other. Apply them as their own deploy step with python scripts/migrations.py.

For a PostgreSQL on another machine, put its private address in DB_HOST and require TLS through DB_CONNECTION_EXTRA=SSL Mode=Require;Trust Server Certificate=true — dropping Trust Server Certificate once the server presents a certificate the container can verify.

Troubleshooting

Next

• Operations — migrations, start-up guards, health checks, logging, integrations.
• Getting started — running the API from source instead.
• Contributing → Releasing — how a release reaches homologation and production.

9 - Operations

Migrations

The schema is managed with EF Core migrations, applied explicitly:

python scripts/migrations.py

The script asks which environment file to load (for the connection string), then offers list, create (generate), and apply. It needs dotnet tool restore to have been run once, for the pinned EF Core CLI tool. Authoring a migration is covered in Contributing .

The API never migrates on startup, and refuses to start when migrations are pending. The seeder checks GetPendingMigrationsAsync first and throws with the missing migration names:

The database is missing 2 migration(s): 20260811_AddAuditLog, 20260812_AddTwoFactorEmailCode.
Apply them with scripts/migrations.py before starting the API.

Automatic migration on startup is convenient exactly until two instances start at once, or until a deployment silently applies a migration nobody reviewed. An explicit step makes schema change a decision rather than a side effect.

Shared public ids — before ProtectIdentityPublicIds (#199)

ProtectIdentityPublicIds and ProtectEntityPublicIds make public_id immutable on person, google_user, scope, application, application_credential, scope_permission, role and pending_registration, refuse a new row whose public_id another of those tables holds or a hard delete tombstoned, and refuse a new person or Google User whose id an audit entry names. They guard future writes only and do not look at what is already stored. The API only ever issues fresh random ids, so a duplicate can exist only if somebody wrote one by hand in SQL. To check for a hand-made duplicate, run both queries before migrating; each should return no rows.

-- 1. Any public_id that rows of two or more guarded tables hold.
WITH ids (tbl, public_id) AS (
    SELECT 'person', public_id FROM heimdall.person
    UNION ALL SELECT 'google_user', public_id FROM heimdall.google_user
    UNION ALL SELECT 'scope', public_id FROM heimdall.scope
    UNION ALL SELECT 'application', public_id FROM heimdall.application
    UNION ALL SELECT 'application_credential', public_id FROM heimdall.application_credential
    UNION ALL SELECT 'scope_permission', public_id FROM heimdall.scope_permission
    UNION ALL SELECT 'role', public_id FROM heimdall.role
    UNION ALL SELECT 'pending_registration', public_id FROM heimdall.pending_registration
)
SELECT public_id, string_agg(tbl, ', ' ORDER BY tbl) AS held_by
FROM ids
GROUP BY public_id
HAVING count(*) > 1;

-- 2. Any person or Google User whose id audit entries named before the identity existed, so those
--    entries were about something else. The minute absorbs clock skew between the API and the database.
SELECT 'person' AS tbl, p.public_id, count(*) AS earlier_entries
FROM heimdall.person p
JOIN heimdall.audit_log a ON a.target_id = p.public_id
WHERE a.created_at < p.created_at - interval '1 minute'
GROUP BY p.public_id
UNION ALL
SELECT 'google_user', g.public_id, count(*)
FROM heimdall.google_user g
JOIN heimdall.audit_log a ON a.target_id = g.public_id
WHERE a.created_at < g.created_at - interval '1 minute'
GROUP BY g.public_id;

A row from either query is worth investigating before anything else: it is either a hand-made fix-up or somebody preparing to make audit entries clearable. No rows proves less than it seems. Query 1 sees only rows that are there now. Query 2 trusts created_at, which an insert can set, so a backdated plant passes it. Neither sees a plant that has already run its course — target cleared, identity tombstoned and deleted — or a scope or other entity sitting on an id that erased_subject records. Once migrated, hand-written SQL that rewrites a public_id — a support fix-up, or a restore that remaps ids — fails with restrict_violation.

Database roles — TH-18

The supported setup runs the migrations as an owner role and the API as a role that owns nothing (NFR-29). The owner holds the schema and everything in it, including the audit triggers and their functions; the API’s role gets the row privileges it needs and nothing more. Two roles per environment, which the operator creates and applies:

The runtime role may connect, read and write rows, and nothing else: SELECT, INSERT, UPDATE and DELETE on the heimdall tables, except that audit_log gets no DELETE; SELECT on the migrations history, which the start-up seeder reads; no TRUNCATE anywhere and no CREATE on the database or a schema. audit_log keeps UPDATE because the retention pass writes the rows it clears whole; the triggers accept an update only when it clears the attribution or a person target once due (NFR-21). That covers everything the API does at runtime, attempt_notice_budget and the budget columns on person included.

Use one pair per environment, as the deployment guide does for logins: heimdall_owner and heimdall_svc for production, heimdall_development_owner and heimdall_development_svc, and so on. The SQL below is for production; substitute the names for another environment.

The grants

Run as a superuser (sudo -u postgres psql -d heimdall). Part 1 can run at any time, before the first migration too; part 2 needs the audit_log table, so it runs after the first migration.

-- Part 1. Access: connect, use the schema, read and write rows, create nothing.
GRANT CONNECT ON DATABASE heimdall TO heimdall_svc;
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
CREATE SCHEMA IF NOT EXISTS heimdall AUTHORIZATION heimdall_owner;
GRANT USAGE ON SCHEMA heimdall TO heimdall_svc;

-- What exists already.
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA heimdall TO heimdall_svc;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA heimdall TO heimdall_svc;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO heimdall_svc;

-- What later migrations create, as the owner, gets the same.
ALTER DEFAULT PRIVILEGES FOR ROLE heimdall_owner IN SCHEMA heimdall
    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO heimdall_svc;
ALTER DEFAULT PRIVILEGES FOR ROLE heimdall_owner IN SCHEMA heimdall
    GRANT USAGE, SELECT ON SEQUENCES TO heimdall_svc;
ALTER DEFAULT PRIVILEGES FOR ROLE heimdall_owner IN SCHEMA public
    GRANT SELECT ON TABLES TO heimdall_svc;

-- Part 2. The audit trail is never deleted from. Its triggers decide which updates it accepts.
REVOKE DELETE ON heimdall.audit_log FROM heimdall_svc;

public holds nothing but the migrations history ("__EFMigrationsHistory", kept there by the pinned Search Path=public), so the runtime role reads that table and nothing else of it. On PostgreSQL 15 and later nobody but the database owner may create in public anyway, and the REVOKE CREATE only restates it; CONNECT is granted to the runtime role by name, and whatever else PUBLIC may do on the database is left as it was. Default privileges are recorded against the owner, so they apply only to objects the owner creates: never run a migration as a superuser or as the runtime role, or its tables will not be granted. When a migration adds a table the API must not write freely — another append-only table, say — its revoke is added to part 2 of the grants here, and the operator runs it after that migration, as part 2 is run for audit_log.

Checking the setup

As a superuser, connected to the environment’s database. Each query must return no rows, and every column of the last one must be false:

-- 1. Nothing in this database, and no database, still belongs to the runtime login.
SELECT classid::regclass AS catalog, objid FROM pg_shdepend
WHERE deptype = 'o' AND refobjid = 'heimdall_svc'::regrole
  AND dbid IN (0, (SELECT oid FROM pg_database WHERE datname = 'heimdall'));

-- 2. The database, the schema, every table, sequence and index in heimdall and public, and every
--    function in heimdall belong to the owner.
SELECT 'database' AS kind, datname AS name, pg_get_userbyid(datdba) AS owner
FROM pg_database WHERE datname = 'heimdall' AND datdba <> 'heimdall_owner'::regrole
UNION ALL
SELECT 'schema', nspname, pg_get_userbyid(nspowner)
FROM pg_namespace WHERE nspname = 'heimdall' AND nspowner <> 'heimdall_owner'::regrole
UNION ALL
SELECT 'relation', n.nspname || '.' || c.relname, pg_get_userbyid(c.relowner)
FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname IN ('heimdall', 'public') AND c.relowner <> 'heimdall_owner'::regrole
UNION ALL
SELECT 'function', n.nspname || '.' || p.proname, pg_get_userbyid(p.proowner)
FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
WHERE n.nspname = 'heimdall' AND p.proowner <> 'heimdall_owner'::regrole;

-- 3. The runtime login's privileges and flags.
SELECT has_table_privilege(r.oid, 'heimdall.audit_log', 'DELETE') AS audit_delete,
       has_table_privilege(r.oid, 'heimdall.person', 'TRUNCATE') AS truncate,
       has_schema_privilege(r.oid, 'heimdall', 'CREATE') AS create_in_heimdall,
       has_schema_privilege(r.oid, 'public', 'CREATE') AS create_in_public,
       has_database_privilege(r.oid, 'heimdall', 'CREATE') AS create_schema,
       pg_has_role(r.oid, 'heimdall_owner', 'MEMBER') AS member_of_owner,
       r.rolsuper, r.rolcreaterole, r.rolcreatedb, r.rolbypassrls
FROM pg_roles r WHERE r.rolname = 'heimdall_svc';

Then, connected as heimdall_svc, this must fail with “must be owner of table audit_log”. It is wrapped in a transaction that is rolled back, so it changes nothing even if it is run by mistake as the owner — in which case it answers ALTER TABLE, and the session is the wrong one:

BEGIN; ALTER TABLE heimdall.audit_log DISABLE TRIGGER USER; ROLLBACK;

A new deployment

1. Create the two logins and the database, owned by the owner:

   sudo -u postgres createuser --pwprompt heimdall_owner
   sudo -u postgres createuser --pwprompt heimdall_svc
   sudo -u postgres createdb --owner heimdall_owner heimdall
   

   and give both a pg_hba.conf rule like the one in the deployment guide (heimdall_owner only needs it while the container migrates; a deployment that migrates out of band gives it a local rule instead).

2. Run part 1 of the grants.

3. In the env file, set DB_USER/DB_PASSWORD to the runtime login and HEIMDALL_MIGRATIONS_CONNECTIONSTRING to the owner’s whole connection string, with the same Search Path as the API’s: Host=host.docker.internal;Port=5432;Database=heimdall;Username=heimdall_owner;Password=…;Search Path=public. Deploy. The entrypoint migrates as the owner, and the API starts as the runtime role, which part 1’s default privileges have already granted the new tables.

4. Run part 2 of the grants.

5. Run the checks above.

Switching an existing deployment over

A deployment created from the earlier guide has one login, heimdall_svc, owning the database and everything in it. The switch moves the ownership to a new owner and grants the login back what the API needs, in one transaction.

1. First deploy a release whose entrypoint reads HEIMDALL_MIGRATIONS_CONNECTIONSTRING — this one or later. On an older image the variable is ignored.

2. Create the owner login: sudo -u postgres createuser --pwprompt heimdall_owner, and its pg_hba.conf rule as above.

3. Make sure no deploy runs between steps 4 and 5: once the ownership has moved, a container that migrates as heimdall_svc fails. Hold the environment’s deploys for those minutes, or set HEIMDALL_RUN_MIGRATIONS=false in its env file until step 5.

4. As a superuser, connected to the environment’s database (sudo -u postgres psql -d heimdall):

   BEGIN;
   SET LOCAL lock_timeout = '5s';
   ALTER DATABASE heimdall OWNER TO heimdall_owner;
   REASSIGN OWNED BY heimdall_svc TO heimdall_owner;
   -- Part 1 and part 2 of the grants, as above.
   COMMIT;
   

   REASSIGN OWNED moves everything the login owns in this database — the schema, the tables, their sequences, the trigger functions and the migrations history — and any database the login owns. It takes a lock on every table it changes and holds them until COMMIT, so requests wait for that moment; with lock_timeout the transaction gives up after five seconds rather than queue behind a long one, and rolls back whole. Run it again at a quieter moment if it does. Because it is one transaction, the API sees either the old ownership or the new one with its grants.

5. Add HEIMDALL_MIGRATIONS_CONNECTIONSTRING (the owner’s) to the env file, put HEIMDALL_RUN_MIGRATIONS back if step 3 changed it, and redeploy. Leave DB_USER as it is.

6. Run the checks above.

To undo it, reverse the ownership in one transaction, as a superuser connected to the environment’s database, with the same lock_timeout and the same retry as step 4:

BEGIN;
SET LOCAL lock_timeout = '5s';
ALTER DATABASE heimdall OWNER TO heimdall_svc;
REASSIGN OWNED BY heimdall_owner TO heimdall_svc;
COMMIT;

Then remove HEIMDALL_MIGRATIONS_CONNECTIONSTRING from the env file. The grants left behind then name the runtime login on objects it owns again, which changes nothing. On PostgreSQL 14 or earlier, where PUBLIC could create in public by default, GRANT CREATE ON SCHEMA public TO PUBLIC restores that too.

Where the owner’s password lives. With HEIMDALL_MIGRATIONS_CONNECTIONSTRING set, the owner’s connection string is in the env file and the container’s configuration, beside the other secrets there. The entrypoint hands it to the migration bundle through the bundle’s own environment, never its command line, and removes it before the API starts, so the API process never holds it. A deployment that wants it off the container altogether sets HEIMDALL_RUN_MIGRATIONS=false and migrates out of band with scripts/migrations.py, from an environment file that names the owner.

Start-up sequence

flowchart TD
    A[Configure Serilog] --> B[Load environment configuration]
    B --> C[Configure Web API + custom model-state response]
    C --> D0{Diagnostics on and<br/>a public host?}
    D0 -->|"Yes, and HEIMDALL_ALLOW_<br/>SENSITIVE_DIAGNOSTICS ≠ true"| D0X["Turn them off —<br/>one warning"]
    D0 -->|No, or allowed| D[Register dependencies]
    D0X --> D
    D --> D1{Production and<br/>Mailgun unconfigured?}
    D1 -->|Yes| DX["Refuse to start —<br/>tokens would be logged in plaintext"]
    D1 -->|No| E[Configure security + JWT + rate limiting]
    E --> E1{Token secret set?}
    E1 -->|No| EX["Refuse to start —<br/>every request would fail with IDX10703"]
    E1 -->|Yes| F[Build app + middlewares + Swagger]
    F --> G[Start services → DatabaseSeeder]
    G --> G1{Migrations pending?}
    G1 -->|Yes| GX[Refuse to start — names them]
    G1 -->|No| H[Ensure the three Role rows]
    H --> I{Any system admin?}
    I -->|No| J["Create one from<br/>HEIMDALL_MASTER_USER_*<br/>— refuses to start if unset"]
    I -->|Yes| K[Ready]
    J --> K

The seeder is idempotent, so it runs on every start-up: it ensures every Roles member exists as a row and that at least one system administrator exists to sign in as. It never applies migrations.

Each of those refusals replaces a failure that would otherwise appear far from its cause — an opaque IDX10703 on every authenticated request, a plaintext token in a production log, or a runtime error against a column that does not exist yet. Each is an unhandled exception at start-up: its message is the last thing the container logs, and the process exits non-zero, so the container restarts and the health check never turns green.

Diagnostics on a public host — NFR-28

Every environment but Production asks for EF Core’s sensitive data logging and detailed errors, which put query parameter values in the log, and Development and Local also ask for the developer exception page, which answers a failed request with its details. That suits a developer’s machine.

On an instance that serves a public host they are turned off, all three together, and the instance starts as usual with one warning:

This instance serves a public host (PUBLIC_HOST=heimdall-api-dev.example.com, UI_HOST=heimdall-dev.example.com),
so EF Core sensitive data logging, detailed errors and the developer exception page are off in the
"Development" environment. Set HEIMDALL_ALLOW_SENSITIVE_DIAGNOSTICS=true to keep them on where the
instance holds made-up people only

One decision, taken once at start-up, sets both EF Core’s options and the exception page, so neither can stay on while the other is off. It covers the exception page the host adds by itself in Development too: where the decision turns the page off, a failed request gets the API’s usual 500 body, “Internal server error, please try again later”.

A host is public when any of these names anything but localhost, a name under .localhost, or a loopback address: PUBLIC_HOST or UI_HOST (the names Traefik routes to the instance, which docker-compose.yml passes into the container), the host of HEIMDALL_EMAIL_VERIFICATION_URL or HEIMDALL_PASSWORD_RESET_URL, or any origin in HEIMDALL_CORS_ALLOWED_ORIGINS. A URL or an origin counts by its host, and one written without a scheme is read as a host name; a template placeholder ([[...]]) does not count. With none of them public, nothing changes: a developer machine and the functional suite keep their diagnostics.

HEIMDALL_ALLOW_SENSITIVE_DIAGNOSTICS=true keeps them on with a public host, and logs a warning at every start. Set it only where the environment holds no real person’s data. The templates leave it empty.

Health checks — UC-30

Both also answer at the root, /healthcheck and /healthcheck/detailed, which is what the container health check and yggdrasil’s status page call. Use the /api/ addresses through Traefik: on the web UI’s host, a path outside /api/ is served by heimdall-ui, not the API.

{
  "status": "Healthy",
  "services": [
    { "name": "Database", "status": "Healthy" }
  ]
}

The aggregate status is Healthy only when every entry is healthy (FR-HC-05).

The liveness endpoint is anonymous because a load balancer cannot authenticate; the detailed one is System-Admin-only because “which of my dependencies is down” is operational intelligence.

Each dependency is one IServiceHealthCheck registration. DatabaseHealthCheck issues a trivial read through the repository abstraction and catches everything — an unreachable database throws on execution, and the check reports unhealthy rather than propagating, so the aggregate can still be reported (AF-30c). Adding a verification is one more registration; the detailed handler resolves them all as IEnumerable<IServiceHealthCheck>.

Metrics — Prometheus

The API publishes its metrics in Prometheus text format at GET /metrics on port 9464 — and on that port only. They are collected with OpenTelemetry: request rate, duration and status per route (http.server.*), Kestrel connections, outbound HttpClient calls (Mailgun), the .NET runtime (GC, heap, thread pool, exceptions), EF Core, and the Npgsql connection pool. Every series carries service_name="heimdall-api".

The endpoint is recognised by the port the connection arrived on, never by the Host header. On the VPS (development, homologation, production) the API runs behind Traefik, which forwards the client’s own Host header — a check on it would be a check on a value any caller chooses. The local port of the socket is the one thing a caller cannot pick: Traefik reaches the container on 8080, Prometheus reaches it directly on 9464 over a private Docker network, and a request for /metrics on 8080 falls through to the API, which has no such route (401 without a token, 404 with one).

That guarantee holds only while 9464 stays private, so:

• Never publish 9464. docker-compose.yml maps only the API’s port; the image listens on both (ASPNETCORE_HTTP_PORTS=8080;9464). Put Prometheus on a network it shares with the api service and scrape it there — under yggdrasil, heimdall-api.<environment>:9464 on the telemetry network.
• Never route Traefik to 9464. With two ports exposed, give Traefik the service port explicitly (traefik.http.services.<name>.loadbalancer.server.port=8080) rather than letting it pick.
• Moving the port means moving both. A HEIMDALL_METRICS_PORT other than 9464 must also be added to ASPNETCORE_HTTP_PORTS, or Kestrel never listens where the endpoint waits.

The endpoint is mounted first in the pipeline, as a terminal branch: a scrape never meets CORS, rate limiting, authentication or authorization, and — not being a controller action — it is not in the OpenAPI document. The rest of the API is still served on 9464 too; only /metrics is special there, which is harmless for a port nothing outside the private network can reach.

A minimal scrape job:

scrape_configs:
  - job_name: heimdall-api
    static_configs:
      - targets: ["api:9464"]

Running from source (dotnet run), the API listens on 5177 only, so /metrics is not served; add the port to the URLs it listens on (--urls "http://localhost:5177;http://localhost:9464") to try it.

Logging

Serilog, configured before anything else so that even configuration failures are recorded:

• Console — JSON formatted.
• Rolling files — <HEIMDALL_LOG_DIRECTORY>/<yyyy/MM>/log-<date>.json, a new file per day inside a folder per month. HEIMDALL_LOG_DIRECTORY defaults to logs.

EF Core diagnostics are enabled outside Production only. SensitiveDataLogging and DetailedErrors print parameter and column values — password hashes, salts, email addresses — so they stay off where those logs are retained.

Retention and redaction — NFR-22

Log files are written flat under the log directory, one per day, and removed once older than HEIMDALL_RETENTION_LOG_DAYS (365 by default). They used to be nested in year/month directories via Serilog’s Map sink, which created a new sink per month — a retention limit bounds files within a sink, so it bounded each month’s directory and never removed a month. The flat sink is the shape where the limit applies.

No log statement writes an email address. Where a line needs to refer to one so an operator can correlate, it writes a stable non-reversible reference ({EmailRef}) instead. LogRedactionTests scans the source and fails if an {Email} placeholder reappears anywhere.

The reference is pseudonymisation, not anonymisation: somebody who already suspects an address can hash it and look for it. What it defeats is reading addresses out of the logs in bulk.

Rate limiting and lockout

Brute force is bounded in two independent places, because each covers what the other misses.

Per caller — a fixed-window limiter of 10 requests per minute, partitioned by client IP (an IPv6 caller by its /56, since a subscriber is routinely handed a whole /56 and counting per /64 would give them 256 partitions), applied to AuthController’s anonymous, credential-checking endpoints: login, password recovery, password reset, email verification, Google sign-in, and second-factor verification and resend. Rejections answer 429 with a Retry-After header (whole seconds) and the usual error envelope. None of these requires a bearer token, so nothing else bounds how fast one caller can hit them, and each login attempt costs a full Argon2id verification (600 MB / 16 threads by the hashing library’s defaults) — so memory exhaustion is realistic without it. The authenticated endpoints that check a password or a second factor — 2FA enable, confirm, disable and recovery-code regeneration, the erasure request, and the person update (PUT /api/persons/{id}, which checks the password when a person changes their own email) — share the same limit: a bearer token is not the password, and without it whoever held one could test passwords or six-digit codes against them unthrottled. The person update is limited whether or not it checks a password, administrators' updates included. The verification-link resend (POST /api/auth/resend-verification) shares it too, because every call mails the account’s address.

Per administrator — account creation. The three endpoints that create a person with a password — POST /api/persons, POST /api/scopes/{id}/persons and POST /api/scopes/{id}/owners — each derive an Argon2id hash, and need nothing but an administrator’s token. They are limited to 30 requests a minute per acting person and 30 a minute per address, both at once; a rejection is the same 429 with Retry-After. Only administrators’ access tokens count against the address, so other requests — without a token, or with a User’s, a two-factor challenge or a subject-rights token — cannot use up an address administrators share. Thirty a minute is more than anyone creates by hand, and a bulk import should pace itself to it. For traffic from many addresses at once, see Bounding a distributed flood at the edge .

Per account — a failure budget, which is what an attacker spread across many source addresses defeats the limiter with:

Every budget, and every single-use item — recovery codes, reset and verification tokens, the challenge, the TOTP step — is charged or spent by one conditional UPDATE whose WHERE clause is the rule itself (“unused”, “under the cap”, “still outstanding”), and before the comparison it guards rather than after it. A burst of parallel requests therefore cannot outrun a budget or spend one code twice: the database lets exactly as many through as the rule allows. A login attempt is counted in failed_login_attempts while it is in flight and cleared if the password turns out to be right.

A lockout is a window rather than a latch an administrator clears: reaching the threshold needs nothing but wrong guesses, so a permanent lock would hand any anonymous caller a denial of service against any address they know. It answers with UC-11’s ordinary InvalidCredentials, and spends the same Argon2id work a real check would, so it is not observable — by message or by timing — to a caller who does not already know the password.

Releasing a second-factor lock or a re-authentication pause

Both run out on their own: a second-factor lock after at most 24 hours, a re-authentication pause after 15 minutes. Heimdall has no endpoint to release either early, on purpose. For a support case that cannot wait, an operator can clear them in the database.

Replace the id with the person’s public_id (the id the API returns for them):

-- Second-factor lock at sign-in (FR-AU-12): the count, the lock, and the repeat count that sets
-- how long the next lock lasts.
UPDATE heimdall.person
SET failed_second_factor_attempts = 0,
    second_factor_locked_out_until = NULL,
    second_factor_lockouts = 0
WHERE public_id = '00000000-0000-0000-0000-000000000000';

-- Re-authentication pause (FR-AU-13): the count, the window and the pause.
UPDATE heimdall.person
SET failed_reauthentication_attempts = 0,
    reauthentication_window_started_at = NULL,
    reauthentication_paused_until = NULL
WHERE public_id = '00000000-0000-0000-0000-000000000000';

Each statement should report UPDATE 1. Run only the one you need. The person table’s triggers guard public_id alone, so these columns are writable by the API’s own role.

Bounding a distributed flood at the edge

Every password check passes through PasswordHashGate: four Argon2id derivations at a time per instance, about seven hundred a minute, the rest refused with 503 after a ten-second wait. The per-caller limit admits ten a minute, so about seventy unrelated networks sending login attempts with made-up addresses keep the gate full — and while they do, real sign-ins wait and fail. The API cannot stop this itself (Threat Model Document, TH-03): those callers look like real ones, and a global budget in the API would only let the attacker spend it and deny everybody at a lower cost. The bound belongs at the edge, where the request costs nothing to refuse.

On the VPS that edge is Traefik (v3.6). Add these labels to the overlay that declares Heimdall’s routers, yggdrasil’s stacks/heimdall-api.proxy.yml, beside its heimdall-api-${YGG_ENVIRONMENT} and heimdall-api-${YGG_ENVIRONMENT}-same-origin routers. Every name carries ${YGG_ENVIRONMENT}, because the environments share one Traefik.

labels:
  # The credential routes, on both hosts: the API's own and the web UI's same-origin /api/.
  # (?i): Traefik matches paths case-sensitively and ASP.NET does not, so /api/AUTH/login must not
  # slip past on the main router.
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth.rule=(Host(`${PUBLIC_HOST}`) || Host(`${UI_HOST}`)) && PathRegexp(`(?i)^/api/auth/`)
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth.entrypoints=websecure
  # The chain is replaced, not extended, so keep the headers every other router has.
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth.middlewares=secure-headers@file,heimdall-api-${YGG_ENVIRONMENT}-auth-limit
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth.service=heimdall-api-${YGG_ENVIRONMENT}
  # Per source: 10 a minute with a burst of 10, an IPv6 caller counted by its /56, as the API does.
  - traefik.http.middlewares.heimdall-api-${YGG_ENVIRONMENT}-auth-limit.ratelimit.average=10
  - traefik.http.middlewares.heimdall-api-${YGG_ENVIRONMENT}-auth-limit.ratelimit.period=1m
  - traefik.http.middlewares.heimdall-api-${YGG_ENVIRONMENT}-auth-limit.ratelimit.burst=10
  - traefik.http.middlewares.heimdall-api-${YGG_ENVIRONMENT}-auth-limit.ratelimit.sourcecriterion.ipstrategy.ipv6subnet=56

  # A client system that signs its users in through Heimdall (Fortuna) reaches it from one source,
  # so under the limit above all of its users would share one bucket of 10 a minute. It gets a
  # router and a bucket of its own, matched on that source. Inside the API its users are counted
  # apart only when it names each one's address with HEIMDALL_TRUSTED_CALLER_KEYS; until it does,
  # they share one bucket there too.
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna.rule=Host(`${PUBLIC_HOST}`) && PathRegexp(`(?i)^/api/auth/`) && ClientIP(`<fortuna-source>`)
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna.priority=1000
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna.entrypoints=websecure
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna.middlewares=secure-headers@file,heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna-limit
  - traefik.http.routers.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna.service=heimdall-api-${YGG_ENVIRONMENT}
  - traefik.http.middlewares.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna-limit.ratelimit.average=600
  - traefik.http.middlewares.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna-limit.ratelimit.period=1m
  - traefik.http.middlewares.heimdall-api-${YGG_ENVIRONMENT}-auth-fortuna-limit.ratelimit.burst=100

• TLS is set on the websecure entrypoint, so the routers need nothing more. No priority is needed on the first router: Traefik ranks the longer rule first, and it is longer than the main router’s. The relay router takes an explicit priority so it always wins over the first.
• Give each consumer its own bucket. One router and one middleware per client system that relays its users, each matched on that system’s source and sized for its users; never one bucket shared by every consumer, and never the public bucket for a relaying system. Replace <fortuna-source> with Fortuna’s address as Traefik sees it: the ClientHost of its requests in Traefik’s access log. Size average for the sign-ins Fortuna’s users make in a minute at their busiest.
• Only a source that is Fortuna’s alone. If Fortuna’s ClientHost is a Docker bridge gateway or a NAT router’s address — which it can be when it reaches Traefik through the public host, and which other traffic then shows too (hairpinned clients, or IPv6 clients that Docker’s port proxy forwards) — do not use ClientIP for the exemption: everything behind that address would land in the relay’s large bucket. Route Fortuna by a source only it has, such as a private network to Traefik or a host name of its own.
• Check the addresses first. Before relying on any of this, confirm in Traefik’s access log that ClientHost shows real client addresses, IPv6 ones included, rather than a proxy’s or Docker’s. A limiter keyed on the wrong address puts everybody in one bucket.
• This is the same per-source limit the API applies, moved in front of it: a refused request then never reaches an instance, and one Traefik counts across every replica behind it, where each instance’s own limiter counts alone.
• It does not, by itself, stop a flood from enough unrelated networks: that is the definition of one. What does is visibility and a decision: the hash gate’s 503s and the CREDENTIAL_VERIFICATION_SHEDDING security signal show it starting; the source networks are in Traefik’s access log; and a flood that persists is for the host firewall or an upstream filtering service, which can drop whole networks before they reach Traefik. Raising the replica count raises the gate’s total in proportion while it lasts.
• Do not add a global limit (one with sourcecriterion.requesthost=true) to the credential routes. It turns the flood into a denial of every caller at a lower cost, which is exactly what the API declines to do.

Bounds on the mail one address receives

Heimdall sends mail from the operator’s Mailgun domain, so mail an attacker can trigger costs the operator quota and sender reputation as well as annoying its recipient. A per-caller limit does not bound what one recipient receives from many callers. The sends a caller can repeat are bounded as follows; mail an administrator causes — the links of UC-51 and UC-52, a new account’s verification link, the notice when they change someone’s address — is trusted to administrators, as their other powers over the accounts they manage are:

The self-registration and recovery bounds are silent by design: the caller gets the same answer whatever happened, so the bound cannot be used to learn whether an address is registered.

A client system calling for its users — HEIMDALL_TRUSTED_CALLER_KEYS

A client system such as Fortuna’s API signs its users in on their behalf, so Heimdall sees one address for all of them — and the 10-a-minute limit on the anonymous endpoints is then shared by every user it serves. It can instead tell Heimdall whose request this is. Heimdall counts the request under that user’s address when it carries a key from HEIMDALL_TRUSTED_CALLER_KEYS:

• HEIMDALL_TRUSTED_CALLER_KEYS is a comma-separated list. Entries are trimmed and empty ones ignored. Each key must be at least 32 characters — they are secrets, so a shorter one stops start-up with an error naming its position, not its value. Generate them randomly, for example openssl rand -base64 48. Unset, no caller is trusted and the headers are ignored.
• The key is compared in constant time against every configured key. A wrong or missing key, or an address that does not parse, is not an error: the request is counted under the connection address as before. The headers can only choose the bucket; they authenticate nobody and open no endpoint.
• Rotating a key needs no downtime: list the new key beside the old (HEIMDALL_TRUSTED_CALLER_KEYS=<old>,<new>), restart Heimdall, move the client system to the new key, then remove the old one and restart again.
• Send the headers only from the client system’s server, over TLS, never from a browser or a mobile app, and keep the key in that system’s secret store.
• A named address is counted in its own caller: namespace, apart from direct connections, so a key holder cannot spend the budget of a real caller by naming their address.
• A leaked key lets its holder pick their own bucket, which only spreads credential guesses over invented addresses; the per-account budgets still count them. That includes the six authenticated endpoints the same limiter guards — 2fa/enable, 2fa/confirm, 2fa/disable, 2fa/recovery-codes/regenerate, erasure-request and PUT /api/persons/{id} — which share the re-authentication budget above, whatever addresses the guesses come from (Threat Model Document, TH-32 and TH-36). The seventh, resend-verification, is bounded per person by the account-email budget below, whatever bucket it is counted in.
• Start-up logs how many keys are configured, never the keys, and neither header’s value is logged.

Database connection encryption — NFR-25

The API warns at start-up when HEIMDALL_DATA_CONNECTIONSTRING does not require TLS. Npgsql’s default SSL Mode is Prefer, which silently falls back to an unencrypted connection when the server offers none — so a deployment can be sending every credential and address in clear text while looking correctly configured. Set SSL Mode=Require, VerifyCA or VerifyFull.

Turn it on once TLS is confirmed. It is opt-in rather than the default so that enabling it is a decision somebody makes, not one that happens to them during an upgrade — but a deployment that has verified TLS and left this off is one warning away from not noticing when the setting is lost.

Data retention — NFR-19

Personal data is kept only as long as its purpose requires (GDPR Art. 5(1)(e), LGPD Art. 15). The schedule — every table holding personal data, its period, and the reason for it — is the Data Retention Schedule Document , and it is the source of truth these settings are configured against.

The schedule marks which periods are enforced and which are not yet, so it never describes a guarantee the code does not make. Read it there rather than inferring enforcement from the presence of a setting here.

Single-use tokens are purged on a schedule. A hosted service dispatches a purge hourly by default, removing password reset tokens, email verification tokens, and two-factor email codes that are past their expiry by the grace period — and, with them, unconfirmed pending registrations, spent application credentials, and self-registration attempt-notice budgets whose day has ended. Each run removes at most a bounded batch per table, oldest first, so a backlog drains over several runs rather than in one long transaction — a purge is delete pressure on the same tables the login and recovery paths write to, and the write path degrades with table size (SRD §6.3.2).

The grace period is not zero, deliberately. UC-13 answers a presented token with TokenInvalid, TokenExpired or TokenAlreadyUsed, and purging the moment a token expires collapses the last two into the first — telling someone following a stale link that their token never existed. A live token is never at risk: the cutoff is strictly in the past.

Every instance runs its own purge and none coordinates with the others (NFR-06). The delete re-reads its batch, so an instance whose rows another already removed simply deletes fewer than it selected. Each run writes one audit entry (NFR-09) as an anonymous write — the evidence that the schedule was enforced, and when. A run that removes nothing is a success; most runs find nothing to do.

Logically deleted identities are anonymised on a schedule. A soft delete is a restriction of processing, not an erasure — the name, the address and the credential material all stay in the row. A second pass gives it a terminal state: once the retention window has elapsed, the record is anonymised in place, and the person’s single-use tokens and two-factor configuration go with it.

The window depends on why the record was deleted. Where the data subject asked (UC-42), it is 30 days — GDPR Art. 12(3)’s outer limit rather than a chosen period, and refused if configured higher. Where an administrator deleted it, it is 90 days, a reversal window. Records deleted before this existed carry no reason and take the longer one.

A subject’s request stores its own deadline when it is made, and that stored value wins over the configured window: a later change to the setting must not move an obligation already owed. Where NFR-12 blocked a request — the subject was a scope’s last owner — the pass retries it once ownership has been transferred, dating the suspension from the request rather than from the moment the block cleared, so a long-blocked request is due immediately rather than handed a fresh deadline. GET /api/auth/erasure-requests is the queue that surfaces those before they are late.

Anonymisation overwrites rather than removes, because NFR-07 requires every foreign key to keep resolving and the audit trail, the scope join rows and an owner’s applications all point at the record. Hard deletion (UC-10) remains available for callers that want the row gone.

The audit trail stops naming people on its own schedule. A third pass clears the actor attribution from entries past their attribution period, and immediately from entries naming an identity that has been anonymised. On the same two grounds it clears an entry’s target when that target is a person or Google User — a self-service command’s own account, or the person an administrator acted on. Targets naming anything else are kept. The entry itself is never removed and what it says happened is never altered — what happened, when and how often all survive.

The rule is enforced by a database trigger rather than by the pass, because this is the one table whose immutability is a security control. It permits the attribution, and a target naming a person, to be set to null and nothing else: no deletion, no truncation, no change to any other column, and no reassignment to a different value. A thirty-day floor stops somebody clearing their own attribution, or the person they acted on, for something they did this week; it is an anti-tamper backstop, not the retention period, which is eighteen months. A deployment upgrading to AllowClearingAuditTarget has its older person targets cleared over the next runs, one batch at a time.

A deployment that sets none of these still gets the published periods — an unset variable must not mean “keep forever”. A malformed or out-of-range value falls back to the default and is named in a start-up warning rather than failing start-up: a typo in a retention setting should not take down the identity provider every client system authenticates against. Falling back silently would be worse than either, since an operator would believe a setting was applied.

Each bound is enforced for a reason. A grace period beyond ten years is a stray unit rather than a policy. An interval below a minute turns a purge into continuous delete pressure on the tables the login path writes to; one above seven days is past what PeriodicTimer accepts, and the exception it would throw inside a hosted service stops the host by default.

Security signal detection — NFR-26

The API records strong signals and, until now, nothing read them. SecurityMonitoringService reads them on a schedule and writes what exceeds its thresholds to the log at warning level.

Every line carries the marker SECURITY_SIGNAL and a stable Kind. Match on those, not on the prose — the wording is written for whoever reads the line afterwards and will change.

Every threshold is a rate, not a total: twenty refusals over a year is somebody who forgets their password, twenty in a quarter of an hour is somebody trying things.

Signals repeat on every run while the condition persists. That is deliberate — an attack that continues is more interesting on its tenth tick than its first, and a detector that goes quiet while the thing it detects is still happening is worse than none. Deduplicate in the alerting rule if you want quiet, not here.

A signal is not a breach. It is a reason to look. What follows one is the Incident Response Document , which carries the notification deadlines and the register.

What a signal actually looks like

A warning-level log line, written to stdout and to the files in the log directory:

SECURITY_SIGNAL REPEATED_REFUSALS: One identity had 23 writes refused in the last
00:15:00. Sustained refusals are what somebody probing for what they may do looks
like. (count 23, actor 3f2a91c4-7d55-4e1a-9b2f-08c7d1e6a934)

To see what has been raised so far:

docker logs heimdall-api 2>&1 | grep SECURITY_SIGNAL

grep -h SECURITY_SIGNAL /path/to/logs/log-*.json

Collecting them — scripts/security_signals.py

Detection that tells nobody is not detection: both breach notification clocks run from awareness, so a signal sitting in a log file has not been detected. This job is what closes that. It reads the log files, finds the signals it has not reported before, and mails them to one address through the Mailgun account the API already uses.

python3 scripts/security_signals.py --stdout      # see what it would send, change nothing
python3 scripts/security_signals.py               # report new signals by e-mail
python3 scripts/security_signals.py --stdout --all  # ignore the watermark, print everything

Scheduling it. Every fifteen minutes matches the monitoring window’s default, so nothing waits longer to be reported than it waited to be detected:

MAILTO=you@example.com
*/15 * * * * cd /srv/heimdall && /usr/bin/python3 scripts/security_signals.py --quiet

The MAILTO is not decoration. The job exits non-zero when it cannot deliver, and prints the signals it was holding to stderr — so a broken collector announces itself instead of looking like a quiet week. Without a MAILTO, the failure of the thing that catches failures is itself uncaught. --quiet keeps the ordinary no-signal run silent, so the only mail cron sends is a real problem.

It needs to read the log files. docker-compose.yml keeps them in a named volume (logs:/app/logs), which the host cannot read directly — so run the job against that volume rather than against a host path:

docker run --rm \
  --volumes-from heimdall-api \
  -e HEIMDALL_LOG_DIRECTORY=/app/logs \
  -e HEIMDALL_SIGNAL_ALERT_TO -e MAILGUN_API_KEY -e MAILGUN_DOMAIN \
  -v "$PWD/scripts:/scripts:ro" python:3-slim \
  python3 /scripts/security_signals.py --quiet

The alternative is to change the volume to a bind mount and run the job on the host, which is simpler to schedule and puts the logs somewhere a backup can reach them. Either works; what does not work is scheduling it on the host and pointing it at a path the container owns.

The state file is written next to the logs by default, so it survives in the volume. Point HEIMDALL_SIGNAL_STATE_FILE somewhere writable if the log directory is read-only — and somewhere persistent, because losing it means the next run re-reports the history.

Exit codes: 0 ran and delivered whatever it found · 1 signals were found and could not be delivered · 2 the collection itself could not run.

Why it keeps a watermark

Signals repeat on every monitoring tick while a condition persists — that is deliberate in the service, and it would be intolerable in an inbox. The job records how far it has read, so each signal is reported once. An alert that resends its entire history is one that gets filtered into a folder within a week, and a filtered alert is the same non-detection the job exists to close.

Two details follow from that, and both are the conservative direction:

• The watermark advances only after delivery succeeds. A Mailgun outage delays signals rather than consuming them.
• An unreadable state file is treated as a first run, so the history is re-reported. Noisy, and the alternative — a truncated file silently meaning “everything is already handled” — is detection switching itself off without saying so.

Signals raised in the same monitoring tick share a timestamp exactly, so the watermark carries the digests of everything at its own instant. Without that, one of a pair raised together would be lost.

What is in the alert

The marker, the kind, the count, the timestamp, and the actor’s PublicId. That is a pseudonym — it identifies an account to somebody holding the database and to nobody else — so the alert can be read on a phone without carrying anybody’s e-mail address into a mailbox. NFR-22 keeps addresses out of the logs to begin with; the alert inherits that rather than re-deciding it. Do not extend the job to include addresses.

The alert also says, in its own body, that the moment you read it is when awareness happened — the timestamp that goes in the Art. 33(5) register, not the time the signal was raised.

Cross-origin requests

HEIMDALL_CORS_ALLOWED_ORIGINS lists the browser front ends allowed to call the API, comma separated, as scheme and host (https://app.example.com). With the variable unset, no cross-origin request is allowed.

Refusing by default is deliberate. The same-origin policy is what stops a page on an unrelated origin from reading an authenticated response, and an identity API is the last place to switch it off: any site the caller visited could otherwise read /api/persons/{id} with a token it scraped, and drive the anonymous endpoints from every visitor’s browser at once. A missing entry costs a front end its access until an operator adds one — visible, and quickly fixed. Defaulting to “any origin” would instead leave a deployment open with nothing to indicate it.

Server-to-server callers are unaffected: CORS is a browser rule, and non-browser clients send no Origin header.

Client addresses behind a proxy

On the VPS every connection reaches the API from Traefik, so the connection’s address is Traefik’s. The caller’s own address travels in X-Forwarded-For, and the scheme they used in X-Forwarded-Proto. HEIMDALL_TRUSTED_PROXIES lists the proxies those headers are believed from — addresses and CIDR networks, comma separated:

Two things read the result: the rate limiter, which partitions on it, and the request log, which records it (Started request with TraceId … from <address> on every request). Unset, nothing is trusted and both see Traefik — one rate-limit bucket for every caller, and a log that names the proxy. Start-up warns when that is the case.

Only the headers’ last hop is read: Traefik appends the address it saw to whatever the caller sent, so the rightmost entry is the only one it vouches for, and an earlier entry a caller forged is ignored. Never list a range a caller can originate from — anything trusted here can claim any address it likes. X-Forwarded-Host is not read; nothing in the API decides on the host name.

Integrations

Email delivery (Mailgun)

Region: United States. This is a deliberate choice, not an inherited default — Mailgun also offers an EU region. Data is hosted in Brazil, so every send is an international transfer under LGPD Art. 33 whichever region is picked; the choice is about which second jurisdiction is involved. The mechanism relied on is recorded in §7 of the Data Protection Document . Changing the region means updating that section and the sub-processor list in the Data Processing Agreement .

Verification (UC-06) and password reset (UC-12) emails, and 2FA email codes, go out through Mailgun via ArturRios.Messaging . Delivery is enabled only when both credentials are present:

Each page finishes the job by posting its token back — the verification page to POST /api/auth/verify-email, the reset page to POST /api/auth/password-reset with the new password. If no link is configured the email carries the bare token instead, which still works.

Pointing a scope at a client application’s screens

The two variables above are one link for the whole deployment. A client system such as Fortuna has its own /verify-email and /password-reset screens, and its users’ emails must lead there. A scope can carry its own link bases, which replace the global ones for that scope’s Users only:

PUT /api/scopes/{id}/email-links
Authorization: Bearer <System Admin or owning Scope Admin token>

{
  "emailVerificationUrl": "https://app.example.com/verify-email",
  "passwordResetUrl": "https://app.example.com/password-reset"
}

• Each must be an absolute http or https URL of at most 2048 characters; anything else is a 400. The token is appended as a token query parameter, as for the global links.
• The body is the whole state of the two links: one left out, null or empty is cleared, and the global link applies to that email again. They have their own endpoint, not fields of PUT /api/scopes/{id}, because that update replaces every field and would erase them whenever a client that does not know them sent it.
• The verification link is used for the sign-up confirmation (UC-47) and for address verification (UC-06, UC-15); the password-reset link for password recovery (UC-12). A Google User receives neither.
• Administrators have no scope, so their emails always use the global links.
• The client’s screens finish the job as the global ones do: the verification screen posts the token to POST /api/auth/verify-email (with the chosen password for a sign-up confirmation), the reset screen to POST /api/auth/password-reset.
• Both are returned on every scope response (GET /api/scopes, GET /api/scopes/{id} and the write endpoints).

Password recovery is answered before it is worked. POST /api/auth/password-recovery only validates the request and puts it on an in-process queue; a background worker then looks the address up, issues the token and sends the email. So the response takes the same time whether or not the address is registered — otherwise the Mailgun round trip a registered address waited for would give away what the uniform answer hides (AF-12a). Two consequences for operators:

• A restart drops whatever is still queued — at most a few seconds’ worth. Nobody is told; the person asks again, as they would for an email that never arrived.
• The queue holds 1,024 requests. Beyond that a request is dropped and the log says The password recovery queue is full — a sign that Mailgun is down or very slow, not that the endpoint is under attack (the rate limiter caps that first).

Google Sign-In

Unset, the API registers a verifier that refuses every token with a 401 and warns once at start-up. Unlike the email fallback this is not a convenience mode: verification needs an audience to check against (NFR-13), so a verifier with no configured client could only reject everything or trust everything. Every other endpoint is unaffected, as is any scope that never enabled the feature.

Google sign-in also requires the scope itself to have it switched on, through PUT /api/scopes/{id}/google-signin — it is off by default. See Google Sign-In .

Rotating the signing secret

HEIMDALL_AUTH_TOKEN_SECRET signs every token the API issues, so replacing it used to invalidate every token in flight the moment the new value took effect. HEIMDALL_AUTH_TOKEN_SECRET_PREVIOUS makes that a rotation instead: both secrets are accepted while only the current one signs.

1. Set HEIMDALL_AUTH_TOKEN_SECRET_PREVIOUS to the secret currently in use, set HEIMDALL_AUTH_TOKEN_SECRET to a new one, and restart. Tokens issued before the restart keep working; new ones are signed with the new secret.
2. Wait one HEIMDALL_AUTH_TOKEN_EXPIRATION_IN_SECONDS — an hour by default — so that no token signed with the old secret can still be alive.
3. Clear HEIMDALL_AUTH_TOKEN_SECRET_PREVIOUS and restart again.

Do step 3 immediately when the reason for rotating is that the old secret leaked. Withdrawing a key invalidates its tokens at once, which is the point: signing everybody out is the correct response to a compromised key and the wrong response to a routine replacement.

Every instance must carry the same pair, so roll the change out to all of them before step 3 — an instance that has already dropped the old secret will refuse tokens its neighbours still accept.

Both secrets must be at least 32 bytes of ASCII, or the API refuses to start, naming the variable and never the value (NFR-31); openssl rand -base64 48 gives 64. An empty previous variable, including one holding just "", means no previous key, so clearing it in step 3 is safe whatever the env file quoting.

Application tokens (UC-56) are signed with the same keys, so the same rotation covers them. Step 2 waits out the longer of the two lifetimes, HEIMDALL_AUTH_TOKEN_EXPIRATION_IN_SECONDS and HEIMDALL_APPLICATION_TOKEN_EXPIRATION_IN_SECONDS (ten minutes by default), and a consumer that validates them offline must be given both keys for the same period.

Environment variables at a glance

A present but unusable value of HEIMDALL_AUTH_TOKEN_EXPIRATION_IN_SECONDS, HEIMDALL_APPLICATION_TOKEN_EXPIRATION_IN_SECONDS or HEIMDALL_ADMIN_EMAIL_COOLDOWN_IN_SECONDS is logged as a warning at start-up, naming the variable, the rejected value and the default applied; an absent one is just the default and logs nothing.

Application tokens (HEIMDALL_APPLICATION_TOKEN_AUDIENCE, UC-56) are validated with zero clock skew, so instances whose clocks differ can refuse a freshly issued token for the length of the drift: keep instance clocks synchronised (NTP).

The account-email cooldown (HEIMDALL_ADMIN_EMAIL_COOLDOWN_IN_SECONDS) began as the administrators' (UC-51/UC-52) and keeps that name, but it now also sets the cooldown of a person’s own account-email budget (FR-PE-16) — resend, email setup code, email-change notice — and of anonymous password recovery (UC-12). A shorter value lets people retry sooner. 0 removes the cooldown: a person’s own sends are then bounded only by the budget’s five per window and the per-IP limit, and recovery only by the per-IP limit, so keep it on wherever the API faces the internet. For recovery the cooldown is held to the reset link’s lifetime (HEIMDALL_PASSWORD_RESET_TOKEN_EXPIRATION_IN_SECONDS), so a long cooldown can never leave the owner without a working link.

For the administrators’ sends and for recovery, the cooldown is derived from the issued token rows (ExpiresAt minus the token lifetime), not from a separate record. Two consequences: if HEIMDALL_RETENTION_TOKEN_GRACE_DAYS is 0 and a token lifetime is shorter than the cooldown, an expired token from inside the window may already have been purged, and the cooldown can undercount. And it is best-effort: simultaneous administrator requests for the same person can both pass it. Recovery requests are worked one at a time per instance, so only a second instance could overlap one. A person’s own budget is a conditional write on their row and has neither weakness.

Environments/.env in the Web API project is a tracked template listing every variable; real values live in per-environment files that are gitignored.

Scaling

The API is designed for horizontal scaling (NFR-06), and the authentication design is what makes that cheap: tokens are stateless and validated from their claims, so no session store or sticky routing is needed. The rate limiter’s window is per instance as a result, which is why the per-account failure budgets above live in the database instead.

A token still carries no revocation list, but it no longer outlives the identity it names: ActorLivenessFilter resolves the caller on every authenticated request and refuses a token whose person or Google User has been deleted (FR-AU-05, FR-GO-12) or is under a restriction of processing (NFR-24). That costs one indexed read per request — the price of making logical deletion and restriction take effect immediately rather than whenever the token happens to expire. The four endpoints through which a subject exercises their own rights — data export, erasure request, restriction and lifting their own restriction — still admit a restricted or suspended (not yet anonymised) subject, and leave the answer to the use case.

The full operational specification is the Operations & Infrastructure Document .

10 - Requirements

These fourteen documents are the specification for Heimdall. Everything else on this site describes what was built; these say what must be true.

They are also the working documents of the project, not a retrospective write-up: a feature is implemented by picking a use case, following its main and alternative flows, and citing the requirement identifiers in the code.

Identifier conventions

The capability groups are SC (scope), PE (person), RO (role), AU (authentication), PR (password recovery), EV (email verification), AP (application), GO (Google Sign-In), SP (scope permission), 2F (two-factor), HC (health check).

10.1 - Vision Document

Vision Document — Heimdall API

1. Introduction

1.1 Purpose

This document establishes the vision for the Heimdall API, a .NET Web API responsible for centralized management of user identities, authentication, and authorization across multiple independent systems.

1.2 Scope

The Heimdall API will serve as a single source of truth for person management, application management, authentication, role-based access control, and multi-tenant scoping. It is designed to be consumed by multiple client systems, each operating within its own isolated scope. Beyond human persons, the system also registers Applications — non-human identities representing other systems, each owned by a Scope Admin who owns the application’s scope.

1.3 Definitions and Acronyms

2. Problem Statement

Organizations integrating multiple systems face a recurring challenge: each system independently manages users, credentials, and permissions, leading to duplicated data, inconsistent security policies, and poor user experience. There is no unified mechanism for authentication, user lifecycle management, or cross-system identity governance.

3. Product Position Statement

4. Stakeholders

5. High-Level Architecture

C4Context
    title Heimdall API — Context Diagram

    Person(sysAdmin, "System Admin", "Manages all scopes, persons, and applications; belongs to no scope")
    Person(scopeAdmin, "Scope Admin", "Owns one or more scopes and manages their users and applications")
    Person(user, "End User", "Belongs to exactly one scope; authenticates and manages own profile")

    System(api, "Heimdall API", ".NET Web API for identity management")

    System_Ext(clientA, "Client System A", "Consumes identity services under Scope A")
    System_Ext(clientB, "Client System B", "Consumes identity services under Scope B")
    System_Ext(emailSvc, "Email Service", "Sends verification and recovery emails")

    Rel(sysAdmin, api, "Manages scopes, persons & applications")
    Rel(scopeAdmin, api, "Manages users & applications in owned scopes")
    Rel(user, api, "Authenticates, recovers password, verifies email")
    Rel(clientA, api, "Authenticates users, queries persons")
    Rel(clientB, api, "Authenticates users, queries persons")
    Rel(api, emailSvc, "Sends emails")

6. Core Features

7. Domain Model Overview

erDiagram
    SCOPE || --o{ APPLICATION : contains
    ROLE || --o{ PERSON : classifies
    PERSON || --o{ APPLICATION : owns
    SCOPE || --o{ SCOPE_OWNER : has
    PERSON || --o{ SCOPE_OWNER : owns
    SCOPE || --o{ SCOPE_USER : has
    PERSON || --o| SCOPE_USER : "belongs to"
    SCOPE || --o{ GOOGLE_USER : contains
    PERSON {
        bigint Id PK
        guid PublicId
        string Name
        string Email
        bytes PasswordHash
        bytes Salt
        bigint RoleId FK
        bool IsDeleted
    }
    SCOPE {
        bigint Id PK
        guid PublicId
        string Name
        bool IsDeleted
        bool GoogleSignInEnabled
    }
    GOOGLE_USER {
        bigint Id PK
        guid PublicId
        string GoogleId
        string Name
        string Email
        bool EmailVerified
        string ProfilePictureUrl
        bool IsDeleted
        bigint ScopeId FK
    }
    ROLE {
        bigint Id PK
        guid PublicId
        string Name
        string Description
    }
    APPLICATION {
        bigint Id PK
        guid PublicId
        string Name
        bool IsDeleted
        bigint ScopeId FK
        bigint OwnerId FK
    }
    SCOPE_OWNER {
        bigint ScopeId FK
        bigint PersonId FK
    }
    SCOPE_USER {
        bigint ScopeId FK
        bigint PersonId FK
    }

Note: PERSON has no ScopeId attribute. A User’s scope comes from its single SCOPE_USER row; a ScopeAdmin’s scopes come from its one-or-more SCOPE_OWNER rows; a SystemAdmin has neither. GOOGLE_USER is a separate table from PERSON — it has its own ScopeId FK directly, since a Google User always represents the User role and never needs the owner/multi-scope semantics that justify SCOPE_OWNER/SCOPE_USER for PERSON. Its fields mirror PERSON as closely as the Google identity claims allow (Id, Name, Email, IsDeleted), replacing PasswordHash/Salt with GoogleId, EmailVerified, and ProfilePictureUrl sourced from Google’s ID token.

Every top-level entity (SCOPE, ROLE, PERSON, APPLICATION, GOOGLE_USER) has two identifiers: an internal Id (bigint, auto-increment) used only for storage and foreign keys, and a PublicId (GUID) used everywhere the entity is addressed from outside the database — API paths, response bodies, and authentication token claims. Foreign keys (ScopeId, RoleId, OwnerId, and the columns in SCOPE_OWNER/SCOPE_USER) reference the internal bigint Id, not the PublicId. Join tables (SCOPE_OWNER, SCOPE_USER) are not directly addressable resources, so they carry no PublicId of their own.

8. Roles Hierarchy

graph TD
    SA["System Admin<br/>(belongs to no scope)"]
    SCA["Scope Admin<br/>(owns 1+ scopes)"]
    U["User<br/>(belongs to 1 scope)"]

    SA -->|manages all scopes| SCA
    SA -->|manages all persons & applications| U
    SCA -->|manages users & applications in owned scopes| U
    SCA -->|"promotes / creates as co-owner"| U

9. Constraints

• The API must be built with .NET (ASP.NET Core Web API). The full technology stack and versions are defined in the Technology Stack Document .
• A person has no direct scope attribute; its scope relationship is determined by its role.
• A User person must belong to exactly one scope.
• A ScopeAdmin person must own at least one scope, and does not belong to any scope as a user.
• A SystemAdmin person must not belong to any scope, either as an owner or as a user, and has all permissions across the system.
• A scope must have one or more owners, each a ScopeAdmin, and may have one or more User persons.
• A Scope Admin may add a co-owner to a scope they own either by creating a brand-new Scope Admin person, or by promoting an existing User of that scope (which removes that person’s User scope membership).
• Logical deletion must not remove data; it must set a flag.
• Hard deletion must permanently erase data.
• Email verification and password recovery require an external email delivery mechanism.
• Passwords must be stored as a PasswordHash byte array together with a per-person Salt byte array.
• Roles must be stored in a dedicated Role table (Id, Name, Description) and referenced by persons, not stored as a raw string or enum on the person record.
• Every application must belong to exactly one scope and have exactly one owner, which must be a Person associated with that scope (a User who belongs to it, or a Scope Admin who owns it).
• A scope has a GoogleSignInEnabled flag, off by default, that only its owners (or a System Admin) may turn on or off.
• Only accounts equivalent to the User role may sign up or sign in via Google; Google authentication must never create or authenticate a Scope Admin or System Admin.
• A Google User belongs to exactly one scope and is subject to the same IsDeleted lifecycle (logical and hard deletion) as a Person.
• A Google User’s email must be unique within its scope, considered jointly with the emails of User persons in that scope — the same email cannot be registered twice via Google, nor shared with a password-based User account in the same scope.
• Every top-level entity has an internal auto-increment bigint Id (never exposed) and a PublicId GUID (used in all API paths, responses, and tokens), to keep resource enumeration and record counts opaque to callers.

10. Success Criteria

• Client systems can register, authenticate, and manage users within their own scope without affecting other scopes.
• System admins can govern all scopes, persons, and applications from a single API, without belonging to any scope themselves.
• A scope can be co-owned by multiple Scope Admins, and a Scope Admin can own multiple scopes.
• Password recovery and email verification flows complete end-to-end.
• Both logical and hard deletion strategies are available and operate correctly.
• Persons can register and manage Applications representing other systems within their own scope.
• A Scope Admin can turn on Google Sign-In for a scope they own, letting Users of that scope sign up and sign in with a Google account.

10.2 - System Requirements Document

System Requirements Document — Heimdall API

1. Introduction

1.1 Purpose

This document specifies the functional and non-functional requirements for the Heimdall API, a .NET Web API that provides centralized person management, application management, authentication, and authorization for multiple client systems through scope-based tenancy.

The concrete technology stack — framework and language versions, first-party libraries, database, data-access, and tooling — is defined in the Technology Stack Document . This document states requirements and refers to that one for specific technologies and versions rather than restating them.

1.2 Scope

The system encompasses person CRUD, application CRUD, scope CRUD, scope-specific permission CRUD (permissions that may be folded into the JWT at issue), role-based access control, authentication (including Google Sign-In and optional two-factor authentication), password recovery, email verification, and both logical and hard deletion strategies.

1.3 Definitions

2. System Overview

graph LR
    subgraph Clients
        C1[Client System A]
        C2[Client System B]
        C3[Client System N]
    end

    subgraph Heimdall API
        AUTH[Authentication Module]
        PM[Person Management]
        AM[Application Management]
        SM[Scope Management]
        PR[Password Recovery]
        EV[Email Verification]
        GS[Google Sign-In Module]
        SPM[Scope Permission Management]
        TFA[Two-Factor Authentication Module]
    end

    subgraph Infrastructure
        DB[(Database)]
        EMAIL[Email Service]
        GOOGLE[Google Identity Platform]
    end

    C1 & C2 & C3 --> AUTH
    C1 & C2 & C3 --> PM
    C1 & C2 & C3 --> AM
    C1 & C2 & C3 --> SM
    C1 & C2 & C3 --> GS
    AUTH --> DB
    PM --> DB
    AM --> DB
    SM --> DB
    PR --> EMAIL
    EV --> EMAIL
    PR --> DB
    EV --> DB
    GS --> DB
    GS --> GOOGLE
    SPM --> DB
    TFA --> DB
    TFA --> EMAIL
    AUTH --> TFA

3. Functional Requirements

3.1 Scope Management

3.2 Person Management