Flows on Heimdall API

Login

Mon, 01 Jan 0001 00:00:00 +0000

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:

Two-factor authentication

Mon, 01 Jan 0001 00:00:00 +0000

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.

Google Sign-In

Mon, 01 Jan 0001 00:00:00 +0000

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.

Person onboarding

Mon, 01 Jan 0001 00:00:00 +0000

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.

Endpoint	Path	Creates
`POST /api/persons`	b	A `ScopeAdmin` or `SystemAdmin` with no scope
`POST /api/scopes/{scopeId}/persons`	a	A `User` in that scope, with a `SCOPE_USER` row
`POST /api/scopes/{scopeId}/owners`	c	A brand-new `ScopeAdmin` directly as a co-owner, with a `SCOPE_OWNER` row

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.

Password recovery

Mon, 01 Jan 0001 00:00:00 +0000

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.

Scope permission claims

Mon, 01 Jan 0001 00:00:00 +0000

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.

Audit logging

Mon, 01 Jan 0001 00:00:00 +0000

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:

Application authentication

Mon, 01 Jan 0001 00:00:00 +0000

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.