Requirements

• 1: Vision Document
• 2: System Requirements Document
• 3: Use Case Specification Document
• 4: Technology Stack Document
• 5: Data Protection Impact Assessment
• 6: Data Retention Schedule Document
• 7: Data Protection Document
• 8: Privacy Notice
• 9: Data Processing Agreement
• 10: Incident Response Document
• 11: Testing Specification Document
• 12: Threat Model Document
• 13: Development Workflow Document
• 14: Operations & Infrastructure Document

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.

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

3.3 Role Assignment

3.4 Authentication

3.5 Password Recovery

3.6 Email Verification

3.7 Application Management

3.8 Google Sign-In

3.8a Self-Registration

3.9 Scope Permission Management

3.10 Two-Factor Authentication

3.11 Audit Trail

4. Data Model

4.0 Identifier Strategy

Every top-level entity (Scope, Role, Person, Application, Google User, Scope Permission) has two identifiers:

• Id — an auto-incrementing bigint, the physical primary key used for storage and all foreign keys (ScopeId, RoleId, OwnerId, PersonId, and the columns of SCOPE_OWNER/SCOPE_USER). Never exposed outside the database.
• PublicId — a GUID generated at creation time, used as the entity’s identifier everywhere it is addressed from outside the database: API path segments (e.g. /api/scopes/{id}), response bodies, and authentication token claims (e.g. the personId/scopeId claims in FR-AU-04). It is immutable, enforced by trigger, on every table listed above and on APPLICATION_CREDENTIAL and PENDING_REGISTRATION, no new row of those tables may take a PublicId that another of them holds, and a new PERSON or GOOGLE_USER row may not take one that an audit entry names (#199): the audit trail’s retention rules read it as proof that an id names a person (NFR-21).

PASSWORD_RESET_TOKEN and EMAIL_VERIFICATION_TOKEN use only an internal bigint Id — they are never addressed by ID at all; the caller-facing reference is the random Token string already required by FR-PR-02/FR-EV-02. PENDING_REGISTRATION is reached the same way by the registrant — through the mailed token, of which only the hash is stored — and also carries a PublicId, the administrative reference by which a scope’s owners list and discard it (FR-SR-11, FR-SR-12). SCOPE_OWNER and SCOPE_USER are join rows, not independently addressable resources, so they carry no PublicId either — their ScopeId/PersonId columns are internal bigint foreign keys. TWO_FACTOR_AUTH and TWO_FACTOR_RECOVERY_CODE follow the same no-PublicId pattern as the token tables: a person’s two-factor configuration is reached implicitly through their own authenticated identity, never by ID in a path.

This split keeps sequential record counts and creation order — which a raw auto-increment Id would reveal — out of anything a caller can see, while still giving the database compact integer keys for joins and indexes.

4.1 Entity Relationship Diagram

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"
    SCOPE ||--o{ SCOPE_PERMISSION : "defines"
    SCOPE ||--o{ PENDING_REGISTRATION : "awaits confirmation of"
    PERSON ||--o| TWO_FACTOR_AUTH : "configures"
    TWO_FACTOR_AUTH ||--o{ TWO_FACTOR_RECOVERY_CODE : "issues"

    SCOPE {
        bigint Id PK "Internal auto-increment identifier"
        guid PublicId "External identifier, used in API paths/responses"
        string Name "Scope display name"
        string Description "Optional description"
        bool IsDeleted "Logical deletion flag"
        bool GoogleSignInEnabled "Whether Google sign-up/sign-in is enabled for this scope"
        bool SelfRegistrationEnabled "Whether anonymous callers may register password Users in this scope"
        string EmailVerificationUrl "Optional base link of this scope's verification emails, max 2048 characters; null uses the global one (FR-SR-10)"
        string PasswordResetUrl "Optional base link of this scope's password-reset emails, max 2048 characters; null uses the global one (FR-SR-10)"
        datetime CreatedAt "Creation timestamp"
        datetime UpdatedAt "Last update timestamp"
    }

    GOOGLE_USER {
        bigint Id PK "Internal auto-increment identifier"
        guid PublicId "External identifier, used in API paths/responses"
        string GoogleId "Google's stable 'sub' claim, unique within the scope"
        string Name "Full name, from Google's 'name' claim"
        string Email "Email address, from Google's 'email' claim (unique per scope, jointly with User persons)"
        bool EmailVerified "From Google's 'email_verified' claim"
        string ProfilePictureUrl "From Google's 'picture' claim, optional"
        bool IsDeleted "Logical deletion flag"
        bigint ScopeId FK "Associated scope (internal Id)"
        datetime CreatedAt "Creation timestamp"
        datetime UpdatedAt "Last update timestamp"
    }

    ROLE {
        bigint Id PK "Internal auto-increment identifier"
        guid PublicId "External identifier, used in API paths/responses"
        string Name "Role name: User | ScopeAdmin | SystemAdmin"
        string Description "Optional explanation of the role's purpose and permissions"
    }

    PERSON {
        bigint Id PK "Internal auto-increment identifier"
        guid PublicId "External identifier, used in API paths/responses and token claims"
        string Name "Full name"
        string Email "Email address (unique among a scope's Users; unique among Admins system-wide)"
        bytes PasswordHash "Hashed password, stored as a byte array"
        bytes Salt "Random salt used to hash the password, stored as a byte array"
        guid SecurityStamp "Carried by every token issued to the person; replaced on a credential change"
        bool IsDeleted "Logical deletion flag"
        bool EmailVerified "Email verification status"
        bigint RoleId FK "Associated role (internal Id)"
        datetime CreatedAt "Creation timestamp"
        datetime UpdatedAt "Last update timestamp"
    }

    SCOPE_OWNER {
        bigint ScopeId FK "Owned scope (internal Id)"
        bigint PersonId FK "Owning person (internal Id), must have the ScopeAdmin role"
    }

    SCOPE_USER {
        bigint ScopeId FK "Scope the person belongs to (internal Id)"
        bigint PersonId FK "Person (internal Id), must have the User role, unique across this table"
    }

    PASSWORD_RESET_TOKEN {
        bigint Id PK "Internal auto-increment identifier, never exposed"
        bigint PersonId FK "Associated person (internal Id)"
        string Token "Reset token value — the caller-facing reference"
        datetime ExpiresAt "Expiration timestamp"
        bool Used "Whether the token has been consumed"
    }

    EMAIL_VERIFICATION_TOKEN {
        bigint Id PK "Internal auto-increment identifier, never exposed"
        bigint PersonId FK "Associated person (internal Id)"
        string Token "Verification token value — the caller-facing reference"
        datetime ExpiresAt "Expiration timestamp"
        bool Used "Whether the token has been consumed"
    }

    PENDING_REGISTRATION {
        bigint Id PK "Internal auto-increment identifier, never exposed"
        guid PublicId "Administrative reference for listing and discarding (FR-SR-11, FR-SR-12); the registrant's reference is the token"
        bigint ScopeId FK "Scope registered into (internal Id)"
        string Name "Name the registrant gave"
        string Email "Address awaiting confirmation"
        bytes PasswordHash "Password hash computed on the request path"
        bytes Salt "Salt of the password hash, carried to the User on confirmation"
        string TokenHash "SHA-256 of the mailed token — the caller-facing reference is the token itself"
        datetime ExpiresAt "Expiration timestamp"
        datetime CreatedAt "When the registration was stored"
        int FailedAttempts "Wrong confirmation passwords so far; the row is discarded at 10"
    }

    ATTEMPT_NOTICE_BUDGET {
        bigint Id PK "Internal auto-increment identifier, never exposed"
        string AddressHash "SHA-256 of the trimmed, lower-cased address; unique (FR-SR-14)"
        int NoticesSent "Registration-attempt notices sent in the current window"
        datetime WindowEndsAt "End of the current one-day window"
    }

    APPLICATION {
        bigint Id PK "Internal auto-increment identifier"
        guid PublicId "External identifier, used in API paths/responses"
        string Name "Application display name"
        bool IsDeleted "Logical deletion flag"
        bigint ScopeId FK "Associated scope (internal Id)"
        bigint OwnerId FK "Owning person (internal Id)"
        datetime CreatedAt "Creation timestamp"
        datetime UpdatedAt "Last update timestamp"
    }

    SCOPE_PERMISSION {
        bigint Id PK "Internal auto-increment identifier"
        guid PublicId "External identifier, used in API paths/responses"
        string Name "Permission display name, max 200 characters"
        string Description "Optional description, max 500 characters"
        bool IncludeAsJwtClaim "When true, the Name is added as a JWT claim at issue"
        bool IsDeleted "Logical deletion flag"
        bigint ScopeId FK "Associated scope (internal Id)"
        datetime CreatedAt "Creation timestamp"
        datetime UpdatedAt "Last update timestamp"
    }

    PERSON ||--o{ PASSWORD_RESET_TOKEN : "requests"
    PERSON ||--o{ EMAIL_VERIFICATION_TOKEN : "receives"

    TWO_FACTOR_AUTH {
        bigint Id PK "Internal auto-increment identifier, never exposed"
        bigint PersonId FK "Owning person (internal Id), unique — one configuration per person"
        bool AppEnabled "Whether the authenticator-app method is configured"
        bool EmailEnabled "Whether the email method is configured"
        bytes TotpSecretEncrypted "Encrypted TOTP secret, present only when AppEnabled"
        bool IsActive "True once every selected method has been confirmed (FR-2F-04)"
        datetime CreatedAt "Creation timestamp"
        datetime UpdatedAt "Last update timestamp"
    }

    TWO_FACTOR_RECOVERY_CODE {
        bigint Id PK "Internal auto-increment identifier, never exposed"
        bigint TwoFactorAuthId FK "Owning two-factor configuration (internal Id)"
        bytes CodeHash "Hashed recovery code — the plaintext is never stored"
        bool Used "Whether the code has been consumed"
        datetime UsedAt "Timestamp the code was consumed, null until then"
        datetime CreatedAt "Creation timestamp"
    }

4.2 Person Fields

A person has no ScopeId column. Its relationship to scopes is derived from its role:

• User: exactly one row in SCOPE_USER.
• ScopeAdmin: one or more rows in SCOPE_OWNER.
• SystemAdmin: no rows in either SCOPE_OWNER or SCOPE_USER.

4.3 Role Fields

4.4 Application Fields

4.5 Scope Owner Fields

A scope may have many rows (one or more owners); a person may have many rows (a Scope Admin may own several scopes). Composite key (ScopeId, PersonId) must be unique. This join table has no PublicId — it is not an independently addressable API resource.

4.6 Scope User Fields

PersonId is unique across this table, enforcing that a User belongs to exactly one scope. A scope may have many rows (one or more users). This join table has no PublicId.

4.7 Google User Fields

GOOGLE_USER is a separate table from PERSON. Unlike PERSON, it has a direct ScopeId column rather than going through SCOPE_USER, because a Google User always represents the User role and single-scope membership — it never needs the ownership/multi-scope semantics that SCOPE_OWNER exists for. It has no PasswordHash, Salt, or RoleId: authentication is delegated to Google, and the role is implicitly User.

4.8 Scope Permission Fields

A scope permission belongs to exactly one scope, and unlike APPLICATION it has no separate owner — owning the scope is the whole of the authorization to manage it. The IncludeAsJwtClaim flag has no enforcement role of its own; it is read at login time by FR-AU-08, which folds every flagged, non-deleted permission name of the acting scope into the issued token as a scopePermissions claim.

4.9 Two-Factor Auth Fields

A person has at most one TWO_FACTOR_AUTH row. Its absence means the person has never initiated setup; IsActive = false with a row present means setup was initiated but not yet confirmed.

4.10 Two-Factor Recovery Code Fields

Exactly ten rows are created together at confirmation (FR-2F-05) or regeneration (FR-2F-12); regeneration deletes the previous ten and inserts ten new ones in the same operation.

5. API Endpoints Overview

Every {id}, {scopeId}, {personId} (etc.) path segment below refers to the entity’s PublicId (GUID), never its internal bigint Id (see §4.0).

5.1 Scope Endpoints

5.2 Person Endpoints

5.3 Application Endpoints

5.4 Authentication Endpoints

5.5 Google Sign-In Endpoints

5.6 Scope Permission Endpoints

5.7 Audit Trail Endpoints

6. Non-Functional Requirements

The security requirements below state what this API does. What they defend against, and what is left after them, is in the Threat Model Document — including two cases where a control is narrower than the threat it appears to cover.

6.1 The reference configuration

The figures in NFR-05 and NFR-18 are measurements, not estimates. They were taken by ResponseTimeMeasurementTests, which drives the running API against the suite’s PostgreSQL container and writes TestResults/response-times.md. Reproducing them is a test run, not an exercise in trusting this document.

Two runs are quoted, because the difference between them is itself a finding. Idle is the measurement suite running alone. Loaded is the same suite as part of a full solution test run, with the rest of the functional tests and their container competing for the same machine.

Reference configuration: 32 logical processors, PostgreSQL in a local container, server-side time only — no network between caller and API. Median and slowest of 12 samples after 3 discarded warm-up requests, which pay for JIT, the EF model and the first query plan: costs a process meets once rather than costs a caller meets per request.

The loaded column is why NFR-05’s budget is set at 100 ms rather than at the idle figures. Contention moves a write from 5.5 ms to 16.8 ms and its slowest sample from 8.2 ms to 38.2 ms — a factor of three to five, on a machine with thirty-two cores and no other tenant. A budget written to the idle numbers would be a budget that fails whenever the machine is busy, which is precisely when a response-time requirement is supposed to hold.

Two things follow from the table, and both were invisible while NFR-05 was a single unmeasured number. Everything that is not a password check runs one to two orders of magnitude inside the old 500 ms budget, so that budget constrained nothing. And the one endpoint it should have constrained already exceeded it — 534 ms at the slowest when idle, 582 ms under load, on hardware more generous than most production deployments — because Argon2id is expensive on purpose. A single figure could describe neither.

The automated ceilings in the measurement tests are set well above these numbers. They exist to catch an order-of-magnitude regression — an accidental N+1 in a listing, a password check running twice — not to certify conformance on a shared runner, where a scheduling hiccup would otherwise fail a build for no defect.

6.2 What horizontal scaling depends on

NFR-06 is a statement about shared state, and verifying it found a place where the claim did not hold. ASP.NET Core’s Data Protection stores its key ring on the local filesystem by default; the container image does not persist that directory and two instances do not share it. The TOTP secrets of UC-36 are encrypted with those keys, so a second instance — or the same instance after being recreated — could not decrypt them. Nothing announced it: the protector throws, the verifier reports a wrong code, and every caller whose second factor is an authenticator app is quietly locked out of it. The key ring is now kept in the database, and DataProtectionKeyRingTests builds two providers the way two instances would and requires one to read the other’s payload.

What remains per-instance is the rate limiter’s fixed window (§ Operations). That is deliberate and documented there: it is a defence-in-depth throttle, and the per-account budgets of FR-AU-09, FR-AU-12, FR-AU-13, FR-PE-16 and FR-2F-13, the per-address notice budget of FR-SR-14 and the token-derived cooldowns of FR-EV-07, FR-PR-06 and FR-PR-07 — which are in the database — are what hold across instances.

6.3 Under load

NFR-05 used to promise a response time “under normal load” while nothing in the repository generated any, so the clause could be neither met nor missed and the phrase was removed. It is back, with a number behind it: scripts/load_test.py drives a deployment through tools/ArturRios.Heimdall.LoadTest, and the figures below are what that produced.

Two runs, at 32 and at 128 callers in flight, 20 seconds per scenario, against the container image served over loopback with PostgreSQL in a second container, each from a freshly migrated database and each after the harness warmed the scenario at the same concurrency.

Throughput and latency describe the requests the API answered. Attempts counts everything sent, which for login is overwhelmingly what the rate limiter refused — see below.

Nothing failed, timed out or answered 5xx in either run, across 2.5 million requests.

NFR-05’s load condition is set at 128 because every non-password endpoint still meets it there — but the write meets it by 5%, not by an order of magnitude. POST /api/scopes runs at 94.7 ms against a 100 ms median budget, where the reads sit ten to sixty times inside theirs. The write is the endpoint that will breach NFR-05 first, and §6.3.2 is why that matters sooner than the margin suggests.

6.3.1 Login is limited to ten requests a minute, and that is the design

Both runs sent login well over half a million times and were answered ten times. That is not a defect: the per-IP fixed window in §Operations permits 10 requests a minute, and it refused everything else in under a millisecond. The limiter is doing exactly what it was written to do.

What the run adds is the cost of the ten that got through: 2.8 seconds each, against the 534–582 ms NFR-18 documents for a single caller. The window releases its whole budget at once, so ten Argon2id verifications start together, each configured for 600 MB and 16 threads. Ten of them is 6 GB of working set and 160 threads of demand on a 32-core machine, and they queue behind each other.

The consequence was not what a reader of NFR-18 would expect: the rate limiter was not only anti-brute-force, it was the only thing bounding login’s memory demand. One IP could ask for 6 GB of Argon2id working set every minute and be within policy, and because the limiter is per-instance and per-IP (§6.2), callers spread across addresses multiplied that budget rather than sharing it.

There is now a second bound that does not depend on where the callers come from. PasswordHashGate permits four derivations at once across the whole process — about 2.4 GB — and refuses the rest with 503 after ten seconds rather than queueing them. It covers every derivation on a request path, not only login: an authenticated caller creating persons in a loop reaches the same memory, and a bound with a way around it is not a bound. HEIMDALL_AUTH_MAX_CONCURRENT_PASSWORD_HASHES raises or lowers it (Threat Model TH-03).

Measuring it settled a question the change raised. Bounding concurrency looked like it should make login slower, since the ten the limiter admits now queue behind four permits. It did not: the same 128-caller run measured 2,314 ms at the median against 2,890 ms without the gate. Ten concurrent 600 MB derivations contend for memory bandwidth badly enough that doing four at a time finishes the same work no slower. The reading is “the bound cost nothing measurable”, not “the bound made login faster” — the two runs were taken on a machine in different states, and the figure moves with both.

What a load run from one address cannot show is the gate shedding, because the rate limiter admits only ten a minute from one IP and the gate permits four at once. The 503 path is verified by test instead — a functional test holds the only permit and requires login to answer 503 with a Retry-After rather than 500.

6.3.2 The write degrades with the size of the table

The 128-caller write figures above are from an empty database. Repeating the run against the same deployment after roughly 45,000 scopes had accumulated from earlier runs gave 168 ms at the median and 264 ms at the 99th — breaching NFR-05 on both counts, on the same hardware at the same concurrency, with nothing changed but the row count.

The indexes are not the explanation: scope carries a unique index on name and another on public_id, so neither the uniqueness check nor the lookup degrades into a scan. What grows is the insert-side work — index maintenance across the row’s own indexes, the scope_owner insert, and the audit entry NFR-09 requires on every write — under sustained insert pressure with autovacuum trying to keep up.

So NFR-05’s write budget is met at a row count the load run creates in twenty seconds and missed at a row count it creates in a few minutes. That is a real limit rather than a measurement artefact, and it is the strongest argument in this document for treating these figures as a baseline to compare against rather than a service level to quote. It also names the next performance question worth asking, which none of these runs answers: how the write path behaves at a production row count, against a database that has been vacuumed and analysed rather than filled in one burst.

These numbers are not comparable to §6.1’s and must not be read against them. §6.1 measures server-side handler time for one caller; this measures wall-clock at the client and therefore includes every queue between the two, which is the whole reason to run it.

Warm-up dominates a cold deployment badly enough to invalidate a run, which is why the harness discards an opening phase at the same concurrency before it starts sampling. Measured before that existed, a run against a freshly started container reported the authenticated read and the health check at two to four times their warm medians — the JIT, the EF model and the first query plans, all charged to the first few seconds of traffic.

The harness is a closed loop — each caller waits for its own response before sending the next — so the offered rate falls as the API slows, and the latencies are optimistic against a fixed-rate arrival. Correcting for that would mean building a benchmark harness, which is not what NFR-05 needs. Compare these runs against each other across releases; do not publish them as a service level.

The run is deliberately not part of dotnet test. It needs a deployment, takes minutes, and its figures depend on the machine it is driven from — none of which belongs in a suite that gates a merge.

6.4 Accepted exception to NFR-15

Person.RoleId. RoleId is an internal bigint foreign key into the Role table, and is exposed as Role in PersonOutput/CreatePersonCommandOutput/ UpdatePersonCommandOutput and as a roleId JWT claim, rather than Role.PublicId or a symbolic name. This is accepted rather than fixed: Role is not an addressable resource — there is no endpoint that looks a role up by ID, nothing to enumerate, and no per-tenant data behind it — it is a closed, fixed set of three rows (SystemAdmin=1, ScopeAdmin=2, User=3) that already correspond 1:1 to the public Roles enum every caller of this API already knows. NFR-15 exists to keep an attacker from inferring the existence or count of other tenants’ rows (scopes, persons, applications) from a sequential ID; a fixed three-value role lookup carries none of that information, so threading a second identifier through every response and claim for it would add surface area without closing a real gap.

7. Authorization Matrix

block-beta
    columns 5
    block:header:5
        H1["Action"] H2["SystemAdmin"] H3["ScopeAdmin"] H4["User"] H5["Anonymous"]
    end
    block:row1:5
        A1["Create Scope"] A2["✅"] A3["❌"] A4["❌"] A5["❌"]
    end
    block:row2:5
        B1["Delete Scope"] B2["✅"] B3["❌"] B4["❌"] B5["❌"]
    end
    block:row3:5
        C1["Create User"] C2["✅"] C3["✅ (owned scope)"] C4["❌"] C5["❌"]
    end
    block:row4:5
        D1["Update Person"] D2["✅"] D3["✅ (owned scope)"] D4["✅ (self)"] D5["❌"]
    end
    block:row5:5
        E1["Hard Delete"] E2["✅"] E3["❌"] E4["❌"] E5["❌"]
    end
    block:row6:5
        F1["Login"] F2["✅"] F3["✅"] F4["✅"] F5["✅"]
    end
    block:row7:5
        G1["Password Recovery"] G2["✅"] G3["✅"] G4["✅"] G5["✅"]
    end
    block:row8:5
        H1["Create Application"] H2["✅"] H3["✅ (own scope, self as owner)"] H4["❌"] H5["❌"]
    end
    block:row9:5
        I1["Update/Delete Application"] I2["✅"] I3["✅ (owned application)"] I4["❌"] I5["❌"]
    end
    block:row10:5
        J1["Add/Remove Scope Owner"] J2["✅"] J3["✅ (owned scope)"] J4["❌"] J5["❌"]
    end
    block:row11:5
        K1["Assign SystemAdmin Role"] K2["✅"] K3["❌"] K4["❌"] K5["❌"]
    end
    block:row12:5
        L1["Create/Promote Co-Owner (own scope)"] L2["✅"] L3["✅ (owned scope)"] L4["❌"] L5["❌"]
    end
    block:row13:5
        M1["Enable/Disable Google Sign-In"] M2["✅"] M3["✅ (owned scope)"] M4["❌"] M5["❌"]
    end
    block:row14:5
        N1["Google Sign-Up / Sign-In"] N2["N/A"] N3["N/A"] N4["N/A"] N5["✅ (unauthenticated call)"]
    end
    block:row15:5
        O1["Read/Delete Google User"] O2["✅"] O3["✅ (owned scope)"] O4["✅ (self)"] O5["❌"]
    end
    block:row16:5
        P1["Create/Read/Update/L-Delete Scope Permission"] P2["✅"] P3["✅ (owned scope)"] P4["❌"] P5["❌"]
    end
    block:row17:5
        Q1["Hard Delete Scope Permission"] Q2["✅"] Q3["❌"] Q4["❌"] Q5["❌"]
    end
    block:row18:5
        R1["Enable/Confirm/Disable/Regenerate 2FA"] R2["✅ (self)"] R3["✅ (self)"] R4["✅ (self)"] R5["❌"]
    end
    block:row19:5
        S1["Verify 2FA Challenge"] S2["N/A"] S3["N/A"] S4["N/A"] S5["✅ (holds challenge token)"]
    end
    block:row20:5
        T1["Enable/Disable Self-Registration"] T2["✅"] T3["✅ (owned scope)"] T4["❌"] T5["❌"]
    end
    block:row21:5
        U1["Register a Password User"] U2["✅"] U3["✅"] U4["✅"] U5["✅"]
    end
    block:row22:5
        V1["Set Scope Email Links"] V2["✅"] V3["✅ (owned scope)"] V4["❌"] V5["❌"]
    end

8. Deletion Strategy

flowchart TD
    A[Delete Request] --> B{Deletion Type?}
    B -->|Logical| C[Set IsDeleted = true]
    C --> C1{Entity Type?}
    C1 -->|Scope| C2[Cascade: logically delete SCOPE_USER persons, Google Users, and applications in scope]
    C1 -->|Person, Google User, or Application| C3[Record remains in database]
    C2 --> D[Record remains in database]
    C3 --> D
    D --> E[Excluded from default queries]

    B -->|Hard| F{Entity Type?}
    F -->|Person owned by no other scope| G[Permanently remove person record]
    G --> K[Cascade: permanently remove applications owned by person, their SCOPE_OWNER/SCOPE_USER rows, and their two-factor configuration and recovery codes]
    F -->|Google User| M[Permanently remove Google User record]
    F -->|Application| L[Permanently remove application record]
    F -->|Scope Permission| SP[Permanently remove scope permission record]
    F -->|Scope| H2[Permanently remove scope]
    H2 --> I[Cascade: remove SCOPE_OWNER/SCOPE_USER rows; permanently remove SCOPE_USER persons, Google Users, applications, and scope permissions in scope]
    G --> J[Record removed from database]
    K --> J
    M --> J
    L --> J
    I --> J

8.1 What each strategy means under GDPR and LGPD

The two strategies are not merely different mechanics; they discharge different obligations, and §8 described only the mechanics.

Logical deletion is a restriction of processing, not an erasure. It removes the identity from default queries and stops it authenticating, which is what GDPR Art. 18 and LGPD Art. 18 IV describe. It is a legitimate state and the system needs it — an administrator must be able to undo a mistake, and a contested record must be suspendable without being destroyed. What it is not is an answer to GDPR Art. 17 or LGPD Art. 16: the name, the address and the credential material are all still there.

Anonymisation is the terminal state, and the one that discharges erasure. After the retention window (NFR-20), the record retains no value identifying a natural person. GDPR Recital 26 and LGPD Art. 12 both place anonymised data outside the law’s scope, so an anonymised row is no longer personal data being retained. It is reached automatically by a scheduled pass, not by a caller.

Anonymisation overwrites rather than removes, and that is a consequence of NFR-07 rather than a preference: the audit trail, the scope membership and ownership rows, and the applications an owner held all point at the record, and deleting it breaks every one of those references.

Hard deletion removes the row, along with the cascades §8 lists. It remains available (UC-05, UC-10, UC-20, UC-29, UC-35) for callers that want the record gone rather than emptied, and it is the right answer when nothing needs the reference to keep resolving.

Notes on cascading behavior:

• Logically deleting a scope logically deletes its SCOPE_USER persons (Users), its Google Users, and its applications, but does not affect Scope Admins who own it — they may own other, active scopes.

• Hard deleting a scope permanently removes its SCOPE_OWNER and SCOPE_USER rows, its Users, its Google Users, its applications, and its scope permissions (the latter via the scope_permission → scope foreign key’s ON DELETE CASCADE). It does not remove Scope Admin person records themselves, since they may still own other scopes. NFR-12 does not guard this direction: it protects a scope from losing its owners, and a scope that no longer exists has nothing to protect. A ScopeAdmin whose only scope was hard-deleted is therefore left owning none — see the note below.

• Hard deleting a User person removes their SCOPE_USER row. A User cannot own an application (FR-AP-03), so there is nothing further to cascade.

• Hard deleting a ScopeAdmin person removes all of their SCOPE_OWNER rows and any applications they own; per NFR-12, this is rejected if it would leave any owned scope with zero owners.

• Hard deleting a Google User simply removes its record. A Google User cannot own an application (FR-AP-03 restricts application ownership to a ScopeAdmin or SystemAdmin who owns the scope), so no further cascade is needed.

• Hard deleting a scope permission simply removes its record. A scope permission is a leaf in the data model — no entity carries a foreign key to it — so nothing further cascades (FR-SP-08).

• Logically deleting a scope permission flips only its own IsDeleted flag (FR-SP-07); nothing cascades, for the same leaf reason.

• Hard deleting a person permanently removes their TWO_FACTOR_AUTH row and its TWO_FACTOR_RECOVERY_CODE rows, via the two_factor_recovery_code → two_factor_auth → person foreign keys’ ON DELETE CASCADE. Logical deletion of a person does not touch two-factor state — a restored person keeps whatever 2FA configuration they had.

• Logical deletion of a person or a Google User now records when it happened and why (DeletedAt, DeletionKind), because NFR-20’s window is measured from the deletion and the two kinds carry different deadlines. UpdatedAt cannot serve: any later write moves it, which would silently restart the window.

• Anonymisation removes the person’s single-use tokens and their TWO_FACTOR_AUTH row, whose ON DELETE CASCADE foreign keys take the recovery codes and email codes with it. It does not touch SCOPE_USER, SCOPE_OWNER, the applications an owner held, or the audit trail — all are references NFR-07 requires to keep resolving, and none identifies a person once the record it points at has been anonymised. The audit trail’s own actor reference is governed separately (see the retention schedule).

On scope permissions and a logically deleted scope. Unlike applications, scope permissions are not cascaded when their scope is logically deleted (UC-04): the scope’s permissions are left with whatever IsDeleted state they already had. They become unreachable through the listing endpoint, which gates on the scope’s IsDeleted (AF-31a reused), and they are excluded from the JWT-claim fold at login (FR-AU-08), which reads only permissions of non-deleted scopes. They are not purged, so a restored scope recovers its permission set unchanged; and a hard delete of the scope (UC-05) does purge them, via the cascade above.

On a ScopeAdmin left owning no scope. Hard-deleting a scope (UC-05) — and removing an owner (UC-22) — can leave a ScopeAdmin person with zero SCOPE_OWNER rows, which FR-PE-11 says should not happen. The record is deliberately left in place rather than deleted along with the scope: the person may be about to be given another scope (UC-21), and destroying a person as a side effect of a scope operation is not something either use case promises. Until they own a scope again they cannot authenticate — FR-AU-07 rejects a ScopeAdmin with no live owned scope — so the dangling state grants no access. Cleaning it up is UC-10 (Hard Delete Person). Read FR-PE-11 as an invariant the scope-assignment operations maintain (UC-01, UC-06 path c, UC-21, UC-23), not one that survives the removal of the scope itself.

9. Traceability

3 - Use Case Specification Document

Use Case Specification Document — Heimdall API

1. Introduction

1.1 Purpose

This document specifies the actor-facing use cases for the Heimdall API — UC-01 through UC-29 and UC-31 through UC-40. Each describes actor interactions, preconditions, postconditions, main flows, and alternative/exception flows.

UC-30 (Check API Health) is specified in the Operations & Infrastructure Document , §3.5, alongside the FR-HC requirements it realises: it describes how the system is operated rather than what it does for an actor, and keeping it with the monitoring requirements keeps the two together.

Note on identifiers: every {id} / {scopeId} / {personId} referenced in these flows is the entity’s PublicId (a GUID). Internally, each entity also has an auto-increment bigint Id used only for storage and joins — it is never seen by any actor in these use cases (see the System Requirements Document, §4.0).

1.2 Actors

1.3 Use Case Overview

graph LR
    subgraph Actors
        SA(("System Admin"))
        SCA(("Scope Admin"))
        U(("User"))
        AN(("Anonymous"))
        ES(("Email Service"))
        GU(("Google User"))
        GIP(("Google Identity Platform"))
    end

    subgraph "Scope Management"
        UC01[UC-01: Create Scope]
        UC02[UC-02: View Scope]
        UC03[UC-03: Update Scope]
        UC04[UC-04: Logical Delete Scope]
        UC05[UC-05: Hard Delete Scope]
        UC21[UC-21: Add Scope Owner]
        UC22[UC-22: Remove Scope Owner]
        UC23[UC-23: Promote User to Scope Owner]
    end

    subgraph "Person Management"
        UC06[UC-06: Create Person]
        UC07[UC-07: View Person]
        UC08[UC-08: Update Person]
        UC09[UC-09: Logical Delete Person]
        UC10[UC-10: Hard Delete Person]
    end

    subgraph "Authentication & Security"
        UC11[UC-11: Login]
        UC12[UC-12: Password Recovery]
        UC13[UC-13: Reset Password]
        UC14[UC-14: Email Verification]
        UC15[UC-15: Resend Verification Email]
    end

    subgraph "Application Management"
        UC16[UC-16: Create Application]
        UC17[UC-17: View Application]
        UC18[UC-18: Update Application]
        UC19[UC-19: Logical Delete Application]
        UC20[UC-20: Hard Delete Application]
    end

    subgraph "Google Sign-In"
        UC24[UC-24: Enable/Disable Google Sign-In]
        UC25[UC-25: Sign Up / Sign In via Google]
        UC26[UC-26: Sign Out via Google]
        UC27[UC-27: View Google User]
        UC28[UC-28: Logical Delete Google User]
        UC29[UC-29: Hard Delete Google User]
    end

    subgraph "Scope Permission Management"
        UC31[UC-31: Create Scope Permission]
        UC32[UC-32: View Scope Permission]
        UC33[UC-33: Update Scope Permission]
        UC34[UC-34: Logical Delete Scope Permission]
        UC35[UC-35: Hard Delete Scope Permission]
    end

    subgraph "Two-Factor Authentication"
        UC36[UC-36: Enable Two-Factor Authentication]
        UC37[UC-37: Confirm Two-Factor Authentication Setup]
        UC38[UC-38: Verify Second Factor]
        UC39[UC-39: Disable Two-Factor Authentication]
        UC40[UC-40: Regenerate Recovery Codes]
    end

    SA --> UC01 & UC02 & UC03 & UC04 & UC05
    SA --> UC21 & UC22 & UC23
    SCA --> UC02 & UC21 & UC22 & UC23
    SA --> UC06 & UC07 & UC08 & UC09 & UC10
    SCA --> UC06 & UC07 & UC08 & UC09
    U --> UC07 & UC08
    SA & SCA & U --> UC11 & UC15
    AN --> UC11 & UC12 & UC13 & UC14
    UC12 --> ES
    UC14 --> ES
    UC06 --> ES
    UC15 --> ES
    SA --> UC16 & UC17 & UC18 & UC19 & UC20
    SCA --> UC16 & UC17 & UC18 & UC19
    SA --> UC24 & UC27 & UC28 & UC29
    SCA --> UC24 & UC27 & UC28
    AN --> UC25
    UC25 --> GIP
    GU --> UC26 & UC27
    UC25 -.-> GU
    SA --> UC31 & UC32 & UC33 & UC34 & UC35
    SCA --> UC31 & UC32 & UC33 & UC34
    SA & SCA & U --> UC36 & UC37 & UC39 & UC40
    AN --> UC38
    UC36 --> ES
    UC38 --> ES

2. Use Case Specifications

UC-01: Create Scope

Main Flow:

sequenceDiagram
    actor SA as System Admin
    participant API as Heimdall API
    participant DB as Database

    SA->>API: POST /api/scopes { name, description, ownerIds }
    API->>API: Validate input
    API->>DB: Check scope name uniqueness
    DB-->>API: Name is unique
    API->>DB: Verify each ownerId is a non-logically-deleted ScopeAdmin or SystemAdmin
    DB-->>API: Owners found
    API->>DB: Insert scope record
    API->>DB: Insert SCOPE_OWNER row for each owner
    DB-->>API: Scope created
    API-->>SA: 201 Created { scope }

1. System Admin sends a request with scope name, optional description, and at least one owner ID.
2. The system validates the input fields.
3. The system verifies the scope name is unique.
4. The system verifies each referenced owner is an existing, non-logically-deleted person with the ScopeAdmin or SystemAdmin role (FR-SC-08).
5. The system creates the scope record with IsDeleted = false and a SCOPE_OWNER row for each initial owner.
6. The system returns the created scope.

Alternative Flows:

UC-02: View Scope

Main Flow (read a — scope by ID):

1. Actor requests scope details by ID.
2. The system loads the scope, filtering out logically deleted scopes unless explicitly requested.
3. The system checks authorization:
   • System Admin: can view any scope.
   • Scope Admin: can view only the scopes they own.
   • User: can view only the scope they belong to.
4. The system returns the scope data.

Main Flow (read b — list scopes):

1. A System Admin or a Scope Admin requests a list of scopes, optionally filtering by name (case-insensitive) and paging the result (FR-SC-03).
2. For a Scope Admin, the system keeps only the scopes they own, as the scope-owner records stand now.
3. The system filters out logically deleted scopes unless explicitly requested.
4. The system returns the page of scopes, its total counting only what the caller may see.

Alternative Flows:

On who may list. A Scope Admin’s console has a scopes screen, and building it from the ownedScopeIds claim plus one read (a) per scope made the screen depend on a sign-in-time snapshot and cost a request per row. So read (b) is open to Scope Admins, filtered to the scopes they own before pagination: the total they see is their own count, and the number of scopes other tenants hold — the fact that kept the listing System-Admin-only — stays out of reach. Ownership is read from the scope-owner records, so an owner removed by UC-22 stops seeing the scope at once rather than when their token expires. A User has exactly one scope and reads it by ID; the collection stays closed to them. System Requirements Document §5.1 and §7 record the same.

UC-03: Update Scope

Main Flow:

1. System Admin sends an update request with the scope ID and new field values.
2. The system validates the input.
3. The system verifies the scope exists and is not logically deleted.
4. The system applies the updates and sets UpdatedAt.
5. The system returns the updated scope.

Alternative Flows:

UC-04: Logical Delete Scope

Main Flow:

sequenceDiagram
    actor SA as System Admin
    participant API as Heimdall API
    participant DB as Database

    SA->>API: DELETE /api/scopes/{id}
    API->>DB: Find scope by ID
    DB-->>API: Scope found
    API->>DB: Set scope.IsDeleted = true
    API->>DB: Set IsDeleted = true for all SCOPE_USER persons in scope
    API->>DB: Set IsDeleted = true for all Google Users in scope
    API->>DB: Set IsDeleted = true for all applications in scope
    DB-->>API: Updated
    API-->>SA: 200 OK

1. System Admin sends a delete request for a scope.
2. The system locates the scope.
3. The system sets IsDeleted = true on the scope.
4. The system sets IsDeleted = true on all Users belonging to the scope (via SCOPE_USER), all Google Users in the scope, and all applications in the scope. Scope Admins who own the scope are not modified.
5. The system returns success, including the scope’s identifier and the total number of Users, Google Users, and applications belonging to the scope (counted regardless of their individual deletion state).

Alternative Flows:

UC-05: Hard Delete Scope

Main Flow:

1. System Admin sends a hard delete request.
2. The system locates the scope.
3. The system records a tombstone in ERASED_SUBJECT for each User and Google User it is about to remove — their PublicId, which kind, and when — before anything is deleted, so the audit entries naming them can still be cleared once their rows are gone (NFR-21, #195). Scope Admins are not removed and get none; nor does the scope.
4. The system permanently deletes all Users belonging to the scope (via SCOPE_USER), all Google Users in the scope, and all applications in the scope.
5. The system removes all SCOPE_OWNER and SCOPE_USER rows referencing the scope, and cascade-deletes any remaining scope permissions.
6. The system permanently deletes the scope record.
7. The system returns success, including the count of scope permissions removed.

Alternative Flows:

On NFR-12 and this use case. There is deliberately no last-owner guard here, unlike UC-10. NFR-12 protects a scope from losing its owners; a scope being removed outright has nothing left to protect. An already logically deleted scope can be hard-deleted too — soft deletion is a state a cleanup pass starts from, not a block on it.

On an owner left with no scope. A ScopeAdmin whose only scope this removes is left owning none, which FR-PE-11 describes as a state that should not exist. Their person record is kept anyway: they may be given another scope next (UC-21), and destroying a person as a side effect of deleting a scope is not something this use case promises. They cannot authenticate meanwhile (AF-11e), so the dangling state grants nothing; removing them is UC-10. See §8 of the System Requirements Document.

UC-06: Create Person

Main Flow (path a — Create User in a scope):

sequenceDiagram
    actor Admin as Scope Admin (owner) / System Admin
    participant API as Heimdall API
    participant DB as Database
    participant ES as Email Service

    Admin->>API: POST /api/scopes/{scopeId}/persons { name, email, password }
    API->>API: Validate input
    API->>DB: Verify scope exists and is not logically deleted
    DB-->>API: Scope found
    API->>DB: Check email uniqueness within scope
    DB-->>API: Email is unique
    API->>API: Generate random Salt
    API->>API: Hash password using Salt
    API->>DB: Insert person record { PasswordHash, Salt, RoleId = User }
    API->>DB: Insert SCOPE_USER row { ScopeId, PersonId }
    DB-->>API: Person created
    API->>API: Generate email verification token
    API->>DB: Store verification token
    API->>ES: Send verification email
    ES-->>API: Email queued
    API-->>Admin: 201 Created { person }

1. Scope Admin (an owner of the scope) or System Admin sends a request with person data (name, email, password) targeting a scope.
2. The system validates all fields and verifies the scope exists and is not logically deleted.
3. The system checks that the email is unique within the scope.
4. The system generates a random Salt and hashes the password using it.
5. The system creates the person record with RoleId = User, IsDeleted = false, EmailVerified = false, storing PasswordHash and Salt as byte arrays, and inserts a SCOPE_USER row linking the person to the scope.
6. The system generates a verification token and sends a verification email.
7. The system returns the created person (excluding PasswordHash and Salt).

Main Flow (path b — Create Scope Admin / System Admin, no scope):

1. System Admin sends a request to POST /api/persons with person data (name, email, password, roleId referencing ScopeAdmin or SystemAdmin).
2. The system validates all fields and verifies the email is not already held by another ScopeAdmin or SystemAdmin anywhere in the system (FR-PE-09).
3. The system generates a random Salt and hashes the password using it.
4. The system creates the person record with the requested RoleId, IsDeleted = false, EmailVerified = false. No SCOPE_OWNER or SCOPE_USER row is created (a ScopeAdmin created this way becomes an owner separately, via UC-21).
5. The system generates a verification token and sends a verification email.
6. The system returns the created person.

Main Flow (path c — Scope Admin creates a new co-owner):

sequenceDiagram
    actor Owner as Scope Admin (owner) / System Admin
    participant API as Heimdall API
    participant DB as Database
    participant ES as Email Service

    Owner->>API: POST /api/scopes/{scopeId}/owners { name, email, password }
    API->>API: Validate input
    API->>DB: Verify scope exists and is not logically deleted
    DB-->>API: Scope found
    API->>DB: Check email uniqueness among admins system-wide
    DB-->>API: Email is unique
    API->>API: Generate random Salt
    API->>API: Hash password using Salt
    API->>DB: Insert person record { PasswordHash, Salt, RoleId = ScopeAdmin }
    API->>DB: Insert SCOPE_OWNER row { ScopeId, PersonId }
    DB-->>API: Person created
    API->>API: Generate email verification token
    API->>DB: Store verification token
    API->>ES: Send verification email
    ES-->>API: Email queued
    API-->>Owner: 201 Created { person }

1. A Scope Admin who owns the scope, or a System Admin, sends a request with person data (name, email, password) targeting the scope.
2. The system validates all fields and verifies the target scope exists and is not logically deleted.
3. The system checks that the email is not already held by another ScopeAdmin or SystemAdmin anywhere in the system (since ScopeAdmin emails are not scoped — FR-PE-09).
4. The system generates a random Salt and hashes the password using it.
5. The system creates the person record with RoleId = ScopeAdmin, IsDeleted = false, EmailVerified = false, and inserts a SCOPE_OWNER row linking the person to the scope as a co-owner.
6. The system generates a verification token and sends a verification email.
7. The system returns the created person.

Alternative Flows:

UC-07: View Person

Main Flow (read a — person by ID):

1. Actor requests a person by ID.
2. The system loads the person, excluding logically deleted persons unless includeDeleted is explicitly requested (FR-PE-08).
3. The system checks authorization, allowing the read when any of the following holds:
   • The actor is a System Admin — they may view any person.
   • The actor is the requested person — every actor may view their own record.
   • The actor is a Scope Admin and the requested person is a User of a scope the actor owns.
   • The actor is a Scope Admin and the requested person is another Scope Admin co-owning one of the actor’s scopes.
4. The system returns the person data (excluding PasswordHash and Salt). The scopes the person owns are listed in full to a System Admin and to the person themselves; to a Scope Admin reading somebody else, only the scopes the actor owns too (FR-PE-19).

Main Flow (read b — list the Users of a scope):

1. A System Admin or a Scope Admin requests the Users of a scope, optionally filtering by name or email and paging the result (FR-PE-04).
2. The system verifies the scope exists and is not logically deleted.
3. The system verifies the actor may read the scope: a System Admin always may; a Scope Admin must own it.
4. The system returns the scope’s User persons, excluding logically deleted persons unless explicitly requested. The scope’s owners are not part of this listing. Each person’s scope ownerships are reported as in read a (FR-PE-19).

Main Flow (read c — list the owners of a scope):

1. A System Admin or a Scope Admin requests the owners of a scope, optionally filtering by name or email and paging the result (FR-PE-04).
2. The system applies the same scope and authorization checks as read (b).
3. The system returns the scope’s owners, excluding logically deleted persons unless explicitly requested. The scope’s Users are not part of this listing. Each owner’s scope ownerships are reported as in read a (FR-PE-19): to a Scope Admin, the scopes the owner shares with them, this one among them.

Main Flow (read d — list the system’s Scope Admins):

1. A System Admin or a Scope Admin requests the persons who may own a scope, optionally filtering by name or email, optionally naming a scope whose current owners are to be excluded, and paging the result (FR-PE-12).
2. If a scope was named for exclusion, the system verifies it exists, is not logically deleted, and that the actor may manage it: a System Admin always may; a Scope Admin must own it.
3. The system returns every ScopeAdmin person that is not logically deleted — and, for a System Admin caller, every such SystemAdmin person too — less the named scope’s current owners if one was named, projected to the person’s identifier, name, and email only.

Main Flow (read e — list the system’s System Admins):

1. A System Admin requests the system’s SystemAdmin persons, optionally filtering by name or email and paging the result (FR-PE-13).
2. The system returns every SystemAdmin person that is not logically deleted and whose processing is not restricted, ordered by name, projected to the person’s identifier, name, and email only.

Alternative Flows:

On read d being open to a Scope Admin. Read a’s visibility rule lets a Scope Admin see only the Scope Admins co-owning the scopes they own. Read d is deliberately wider: the client’s UI-14 (Manage scope owners, specified in the heimdall-ui repository) has a Scope Admin add a co-owner through UC-21, and that person by definition does not own the scope yet, so under read a’s rule that person could never be found and the flow could not be completed at all. What makes the widening safe is the projection, not the audience — identifier, name, and email, and nothing else. A Scope Admin learns that an administrator with a given address exists, which they can already establish by submitting that address to UC-06 path c and reading the duplicate-email refusal. The exclusion parameter is gated separately, because it is a different question: subtracting a scope’s owners from a list reveals them by comparison, so only an actor entitled to manage that scope may ask for it.

On read e being System Admin only. Read d already offers System Admins to a System Admin caller, but mixed with the Scope Admins and with no role to tell them apart, because it answers a different question — who may own a scope. Read e answers who else holds full access to the deployment. Its only actor is the System Admin, and the endpoint’s [RoleRequirement(SystemAdmin)] settles that: a ScopeAdmin or User is refused with 403 before the handler runs, and an unauthenticated caller with 401. No data-dependent rule is left, which is why read e adds no alternative flow — the same reasoning UC-35 and UC-43 follow. A Scope Admin is excluded because a System Admin’s address is not tenant-facing, the reason read d withholds System Admins from them too.

UC-08: Update Person

Main Flow:

1. Actor sends an update request to PUT /api/persons/{id} with the person ID and new values. Name and Email are replaced; RoleId is optional and, when omitted, leaves the role unchanged. An actor changing their own email also sends currentPassword, and twoFactorCode when their two-factor authentication is active (step 4).
2. The system validates the input.
3. The system checks authorization, allowing the update when any of the following holds:
   • The actor is a System Admin — they may update any person, including RoleId.
   • The actor is the person being updated — every actor may update their own name and email.
   • The actor is a Scope Admin and the person is a User of a scope the actor owns — name and email only; a Scope Admin may never change RoleId.
4. If email changes — compared exactly, after trimming, so a change of case is a change too:
   • When the actor is the person being updated, the system first re-authenticates them (FR-PE-14): currentPassword must match their password, checked as UC-39 checks it (AF-08h), and when their two-factor authentication is active, twoFactorCode must be a current authenticator-app or email code or an unused recovery code, checked as UC-38 checks it (AF-08i). A recovery code is spent, as everywhere. No endpoint sends an email code to a signed-in caller, so a person whose only method is Email uses a recovery code here. This happens before the uniqueness check, so a caller without them learns nothing about the new address. An administrator changing someone else’s email presents no credential of that person: their own authorisation (step 3) covers it. A change of name alone asks for nothing.
   • The system checks uniqueness per FR-PE-09 — among the scope’s Users for a User, among all ScopeAdmin/SystemAdmin persons for an admin, evaluated against the role the person will hold after this update — and resets EmailVerified = false. No verification email is sent — issuing a fresh token is UC-14 / UC-15’s responsibility.
   • The system retires every live password-reset link and verification link the person holds (FR-PE-17): they were mailed to the address being replaced. It does so before the new address is saved and again immediately after, before the notice below, for any mailed to the old address in between; a reset or verification that read the person before the change writes only while the address is the one it read, so it cannot write after the change (FR-PR-08, FR-EV-08). Following a retired link answers UC-13’s AF-13b or UC-14’s AF-14b.
   • Just before the update is saved, the system replaces the person’s security stamp, which revokes every token they hold (FR-AU-11) — whoever made the change — and replaces it once more after the save. The first replacement means a save that fails costs one extra sign-in rather than leaving old sessions live; the second ends any session opened while the save was in flight. The new address is stored trimmed; an address that differs only by surrounding whitespace is no change and is not written. An actor who changed their own email is answered 200 OK, but the token that made the request is revoked with the rest: the client signs in again, with the new address.
   • The system sends a notice to the previous address (FR-PE-15): the account’s email was changed, and if that was not the person, they should contact an administrator. The notice names neither the new address nor any link. A failed delivery is logged and does not fail the update.
5. If RoleId changes (System Admin only), the system supports only a change to SystemAdmin, and removes the person’s SCOPE_USER or SCOPE_OWNER rows so that a System Admin holds no scope association (FR-PE-10). Any other target role is refused: making someone a ScopeAdmin requires naming the scope they will own (FR-PE-11) and making someone a User requires naming the scope they will join (FR-PE-02), neither of which this request carries. Those transitions belong to UC-21 (Add Scope Owner) and UC-23 (Promote User to Scope Owner).
6. The system applies updates and sets UpdatedAt.
7. The system returns the updated person (excluding PasswordHash and Salt), its scope ownerships reported as UC-07 read a reports them (FR-PE-19).

On re-authenticating an email change. An address change requires proof of identity, because account recovery follows the address and a bearer token is not proof that the account holder is present. An own email change therefore asks for what UC-39 and UC-42 ask for. The previous address is told, so a change its owner did not make does not go unnoticed, and the stamp rotation ends the sessions opened before it.

On FR-RO-05. FR-RO-05 states that Scope Admins may assign the User role to persons within their scope. That is satisfied by UC-06 path (a), where a Scope Admin creates a person in a scope they own with RoleId = User. UC-08 keeps role changes System-Admin-only, per step 3 and AF-08c.

Alternative Flows:

UC-09: Logical Delete Person

Main Flow:

1. Actor sends DELETE /api/persons/{id} for a person.
2. The system loads the person in any deletion state — an already-deleted person must be found so AF-09b can answer idempotently rather than as a 404.
3. The system checks authorization: System Admin may delete any person; a Scope Admin may only delete a User within a scope they own.
4. The system sets IsDeleted = true on the person record and stamps UpdatedAt.
5. The system returns success, reporting whether the person was already deleted.

Alternative Flows:

On AF-09e. NFR-12 names only removing an owner (UC-22) and hard-deleting the last owning person (UC-10). It is applied to a logical deletion too because a soft-deleted ScopeAdmin can no longer authenticate, so a scope whose only owner is soft-deleted is effectively ownerless — the state NFR-12 exists to prevent. UC-08 resolves the same tension the same way for its role change.

On the order of AF-09b and AF-09e. An already-deleted person is answered before the last-owner check runs. Such an owner is already out of the scope, so re-checking would turn the idempotent success AF-09b requires into a conflict.

On AF-09d. UC-09 grants a System Admin the right to delete “any person”, which would literally include themselves. Self-deletion is refused so a single call cannot lock an administrator out of the system.

UC-10: Hard Delete Person

Main Flow:

1. System Admin sends a hard delete request to DELETE /api/persons/{id}/hard.
2. The system loads the person in any deletion state — a logically deleted person is exactly what a cleanup pass starts from, so soft deletion must not block a hard one.
3. If the person owns any scope, the system verifies that every scope they own has at least one other owner.
4. The system records a tombstone for the person in ERASED_SUBJECT — their PublicId, that it was a person, and when — before anything is deleted, so the audit entries naming them, this hard delete’s own among them, can still be cleared once the row is gone (NFR-21, #195). A retry records it again without error.
5. The system permanently deletes all tokens (password reset, email verification) associated with the person.
6. The system permanently deletes any applications owned by the person.
7. The system removes the person’s SCOPE_USER row (if a User) or SCOPE_OWNER rows (if they own any scope).
8. The system permanently deletes the person record.
9. The system returns success, reporting how many applications and tokens went with the person.

Alternative Flows:

On AF-10c. UC-10 grants a System Admin the right to remove a person, which would literally include themselves. Self-deletion is refused so a single, irreversible call cannot destroy the caller’s own account. UC-09 refuses the same thing for the same reason (AF-09d).

On AF-10b and an already-deleted target. The last-owner check runs even when the person is already logically deleted — deliberately the opposite of UC-09, where the idempotent AF-09b is answered before the guard. NFR-12 names hard-deleting the last owning person outright, and applying the guard unconditionally keeps every scope backed by at least one SCOPE_OWNER row. Removing a soft-deleted sole owner therefore takes two steps: add another owner (UC-21) or hard-delete the scope (UC-05) first.

On the cascade. Hard deletion is the mirror image of UC-09: where a logical deletion touches nothing but the flag, this removes the person’s tokens, the applications they own (NFR-11), and their join rows (System Requirements Document §8). Google Users are unaffected — they belong to a scope rather than to a person, and cannot own an application.

UC-11: Login

Main Flow (User):

sequenceDiagram
    actor U as User
    participant API as Heimdall API
    participant DB as Database

    U->>API: POST /api/auth/login { email, password, scopeId }
    API->>DB: Find SCOPE_USER person by email and scopeId
    DB-->>API: Person found { PasswordHash, Salt, RoleId }
    API->>API: Hash provided password using stored Salt
    API->>API: Compare computed hash to stored PasswordHash
    API->>API: Check IsDeleted == false
    API->>API: Check scope.IsDeleted == false
    API->>API: Generate JWT token { personId, role, scopeId }
    API-->>U: 200 OK { token, expiresAt, emailVerified }

Main Flow (Scope Admin / System Admin):

sequenceDiagram
    actor A as Scope Admin / System Admin
    participant API as Heimdall API
    participant DB as Database

    A->>API: POST /api/auth/login { email, password }
    API->>DB: Find person by email (system-wide)
    DB-->>API: Person found { PasswordHash, Salt, RoleId }
    API->>API: Hash provided password using stored Salt
    API->>API: Compare computed hash to stored PasswordHash
    API->>API: Check IsDeleted == false
    API->>DB: If ScopeAdmin, load owned ScopeIds and check at least one is not logically deleted
    API->>API: Generate JWT token { personId, role, ownedScopeIds? }
    API-->>A: 200 OK { token, expiresAt, emailVerified }

1. Caller sends email and password to POST /api/auth/login (a User also sends their scope ID). The endpoint is open to anonymous callers — it is where every other endpoint’s token comes from.
2. The system locates the person: a User is looked up by email within the given scope; a ScopeAdmin/SystemAdmin is looked up by email system-wide. Emails are compared case-insensitively, and the lookup does not filter logically deleted persons — AF-11c rejects them at step 4.
3. The system hashes the provided password using the person’s stored Salt and compares it to the stored PasswordHash.
4. The system confirms the person is not logically deleted.
5. For a User, the system confirms their scope is not logically deleted. For a ScopeAdmin, the system confirms at least one owned scope is not logically deleted. If processing of the person is restricted (NFR-24), steps 4 and 5 do not apply and the login ends in AF-11i instead.
6. If the person does not have active two-factor authentication (TWO_FACTOR_AUTH.IsActive), the system generates and returns the full authentication token containing the person’s PublicId, display name and role, plus: the scope’s PublicId for a User; the list of owned scopes’ PublicIds for a ScopeAdmin — only those not logically deleted; no scope claim for a SystemAdmin. The response also reports when the token expires. Every token issued to a person — this one, AF-11g’s challenge token and AF-11i’s subject-rights-only token — also carries the person’s current security stamp, and is refused on every later request once the stamp has been replaced by a credential change (FR-AU-11). If the person does have active two-factor authentication, go to AF-11g instead.

Alternative Flows:

On the lockout. AF-11h joins the collapse deliberately. Answering it distinctly would tell an anonymous caller that an address is registered and that they have made it stop responding, which is the pair of facts the uniform rejection exists to withhold. FR-AU-10 keeps the timing uniform too, so the lockout is not detectable by how quickly the refusal arrives. It expires on its own after fifteen minutes — no operator action clears it — because reaching the threshold needs nothing but wrong guesses, and a lock that persisted would hand any caller a denial of service against any address they know.

On the single rejection. AF-11a through AF-11e are five different conditions with one indistinguishable response: the same 401 and the same message. Telling them apart would turn the login endpoint into a directory — confirming which emails are registered, which accounts have been deleted, and which scopes still exist — to a caller who has proved nothing. UC-12 takes the same position for password recovery.

On AF-11i. A restriction used to be a refusal here, folded into the uniform 401. That left a restricted subject only the token they held when they asked for it — an hour by default — to lift their own restriction (UC-45), export (UC-41) or erase (UC-42); after that only a System Admin could act for them. A token confined to those four endpoints gives the subject their rights back without letting the restricted record be processed for anything else. It comes after the password and lockout checks, so only someone holding the credential learns that the account is restricted, and it skips the deletion and scope checks because a suspended subject keeps their rights until the record is anonymised (NFR-20), and a token that claims no scope has no scope to check. It stays confined once the restriction is lifted: the subject signs in again for a full token.

On AF-11f. NFR-10 requires every input to be validated, so a request missing an email or password is refused as malformed before any lookup happens. The validation deliberately stops short of a minimum password length, unlike person creation: at login a short password is a wrong password (401), and answering 400 to it would tell the caller their guess was too short to be anyone’s password.

UC-12: Password Recovery

Main Flow:

sequenceDiagram
    actor U as Anonymous
    participant API as Heimdall API
    participant DB as Database
    participant ES as Email Service

    U->>API: POST /api/auth/password-recovery { email, scopeId? }
    API->>DB: Find person by email (and scopeId, if provided, for a User)
    DB-->>API: Person found
    API->>API: Generate time-limited reset token
    API->>DB: Store reset token
    API->>ES: Send recovery email with reset link
    ES-->>API: Email queued
    API-->>U: 200 OK "If the email exists, a reset link has been sent"

1. Caller provides their email (and scope ID, if they are a User, since email is only unique within a scope for Users).
2. The system locates the person.
3. The system generates a time-limited password reset token.
4. The system stores the token and sends a recovery email.
5. The system returns a generic success message (does not reveal whether the email exists).

Steps 2 to 4 run after step 5, outside the request: the API validates the request, queues it, and answers; a background worker then does the lookup, the token and the email (FR-PR-02). The answer is therefore identical in time as well as in content for a registered and an unknown address — while the work ran on the request, a registered address answered a Mailgun round trip later, which gave away exactly what AF-12a withholds. The queue lives in memory, so a restart drops pending requests; a person who receives nothing asks again, as for any email that does not arrive.

Alternative Flows:

UC-13: Reset Password

Main Flow:

1. Caller provides the reset token and a new password.
2. The system validates the token (exists, its person may still be acted on, not expired, not used). The person is checked by UC-12’s rule as they stand now (FR-PR-08, AF-13e).
3. The system generates a new random Salt and hashes the new password using it.
4. The system marks the token as used, then writes the new PasswordHash and Salt together with a fresh security stamp, which revokes every token issued to the person before the reset (FR-AU-11) — full, challenge and subject-rights-only alike. It is one conditional write that repeats step 2’s checks on the person and requires the address they were read with, so no sign-in can read the new password beside the old stamp, and a write refused because the person changed meanwhile leaves the person, stamp included, as it was (answered as AF-13e).
5. The system returns success. The person signs in again with the new password; a session opened with the old one, by them or by anybody else, ends at its next request.

Alternative Flows:

UC-14: Email Verification

Main Flow:

sequenceDiagram
    actor U as Person
    participant API as Heimdall API
    participant DB as Database

    U->>API: POST /api/auth/verify-email { token }
    API->>DB: Find verification token
    DB-->>API: Token found
    API->>API: Validate token (not expired, not used)
    API->>DB: Set person.EmailVerified = true
    API->>DB: Mark token as used
    DB-->>API: Updated
    API-->>U: 200 OK "Email verified"

1. Person clicks the verification link which calls the API with the token.
2. The system locates and validates the token, and checks the person by UC-12’s rule as they stand now (FR-EV-08, AF-14d).
3. The system sets EmailVerified = true on the person record, in one conditional write that repeats step 2’s checks and requires the address the person was read with.
4. The system marks the token as used.
5. The system returns success.

Alternative Flows:

A token may name a pending registration. A token that matches no verification token is looked up among pending registrations (UC-47). If one matches, the request must also carry password, the one chosen at sign-up (FR-SR-09), and with it the confirmation creates the account: the system checks the password, claims the row, re-checks that the scope is still open and the address still free, creates the User with its address verified, and removes the address’s other pending registrations. An expired one answers AF-14a. Without a password the answer is 422 Unprocessable Entity, and with a wrong one 401 Unauthorized; neither consumes the registration, so the registrant may try again, but each guess is charged before it is compared, and after 10 wrong passwords the registration is discarded and the token answers AF-14c. A link followed again once the account exists finds no registration and answers AF-14c — “Invalid token” — not AF-14b, which here means only a concurrent request that claimed the registration first. One the system refuses to act on, because the scope closed or the address was taken, also answers AF-14c. password is ignored for an ordinary verification token.

UC-15: Resend Verification Email

Main Flow:

1. Authenticated person requests a new verification email.
2. The system checks that the email is not already verified, and reserves the send against the person’s account-email budget (FR-PE-16).
3. The system invalidates any existing verification tokens.
4. The system generates a new time-limited verification token.
5. The system sends the verification email.
6. The system returns success.

Alternative Flows:

On the cooldown and the rate limit. The endpoint mails the account’s own address on every successful call, and a bearer token is all it asks for, so without a bound whoever held one could mail that address once per request — and the address may be one the account holder set without proving it. The resend shares one budget with the person’s other self-service account mail (FR-PE-16), reserved by one write before anything is sent, so even a burst of simultaneous requests sends one. A link an administrator sent (UC-06, UC-51) is not charged to it, so the person may still ask once straight after. The endpoint is also under the credential endpoints’ rate limit, whose own 429 is “Too many requests.” with a Retry-After header.

UC-16: Create Application

Main Flow:

sequenceDiagram
    actor Caller
    participant API as Heimdall API
    participant DB as Database

    Caller->>API: POST /api/scopes/{scopeId}/applications { name, ownerId }
    API->>API: Validate input
    API->>DB: Verify scope exists and is not logically deleted
    DB-->>API: Scope found
    API->>DB: Verify owner is a ScopeAdmin or SystemAdmin with a SCOPE_OWNER row for the scope, and not logically deleted
    DB-->>API: Owner found
    API->>DB: Insert application record
    DB-->>API: Application created
    API-->>Caller: 201 Created { application }

1. Caller sends a request with application data (name, ownerId) targeting a scope.
2. The system validates all fields.
3. The system verifies the target scope exists and is not logically deleted.
4. The system verifies the owner is an existing, non-logically-deleted ScopeAdmin or SystemAdmin who owns the scope.
5. The system creates the application record with IsDeleted = false.
6. The system returns the created application.

Alternative Flows:

UC-17: View Application

Main Flow:

1. Actor requests an application by ID, or a list of the applications within a scope.
2. The system checks authorization:
   • System Admin: can view every application, in any scope.
   • Scope Admin: can view only the applications they own. To list a scope’s applications they must also own that scope.
3. Logically deleted applications are excluded unless explicitly requested.
4. The system returns application data.

Alternative Flows:

UC-18: Update Application

Main Flow:

1. Actor sends an update request with the application ID and new values.
2. The system validates the input.
3. The system checks authorization:
   • System Admin: can update any application.
   • Scope Admin: can update only the applications they own.
4. If the owner changes, the system verifies the new owner is an existing, non-logically-deleted ScopeAdmin or SystemAdmin who owns the application’s scope.
5. The system applies the updates and sets UpdatedAt.
6. The system returns the updated application.

Alternative Flows:

UC-19: Logical Delete Application

Main Flow:

1. Actor sends a delete request for an application.
2. The system checks authorization (System Admin, or the ScopeAdmin who owns the application).
3. The system sets IsDeleted = true on the application record.
4. The system returns success.

Alternative Flows:

UC-20: Hard Delete Application

Main Flow:

1. System Admin sends a hard delete request.
2. The system permanently deletes the application record.
3. The system returns success.

Alternative Flows:

UC-21: Add Scope Owner

Main Flow:

sequenceDiagram
    actor Admin as System Admin / Existing Owner
    participant API as Heimdall API
    participant DB as Database

    Admin->>API: POST /api/scopes/{id}/owners/{personId}
    API->>DB: Verify scope exists and is not logically deleted
    DB-->>API: Scope found
    API->>DB: Verify person exists, is not logically deleted, and has the ScopeAdmin or SystemAdmin role
    DB-->>API: Person found
    API->>DB: Insert SCOPE_OWNER row { ScopeId, PersonId }
    DB-->>API: Owner added
    API-->>Admin: 201 Created

1. Actor sends a request to add a person as an owner of a scope.
2. The system verifies the scope exists and is not logically deleted.
3. The system verifies the person exists, is not logically deleted, and has the ScopeAdmin or SystemAdmin role.
4. The system inserts a SCOPE_OWNER row linking the scope to the person (no-op if it already exists).
5. The system returns success.

Alternative Flows:

On the person added. The person is not asked to accept; the ownership takes effect at once (Threat Model TH-41).

UC-22: Remove Scope Owner

Main Flow:

1. Actor sends a request to remove a person’s ownership of a scope.
2. The system verifies the scope exists and that the person is currently an owner.
3. The system verifies the scope has more than one owner.
4. The system removes the SCOPE_OWNER row.
5. The system returns success.

Alternative Flows:

UC-23: Promote User to Scope Owner

Main Flow:

sequenceDiagram
    actor Admin as System Admin / Existing Owner
    participant API as Heimdall API
    participant DB as Database

    Admin->>API: POST /api/scopes/{id}/users/{personId}/promote
    API->>DB: Verify scope exists and is not logically deleted
    DB-->>API: Scope found
    API->>DB: Verify person is a non-logically-deleted SCOPE_USER of the scope
    DB-->>API: Person found
    API->>DB: Set person.RoleId = ScopeAdmin
    API->>DB: Remove SCOPE_USER row { ScopeId, PersonId }
    API->>DB: Insert SCOPE_OWNER row { ScopeId, PersonId }
    DB-->>API: Person promoted
    API-->>Admin: 200 OK { person }

1. Actor sends a request to promote a person to owner of a scope.
2. The system verifies the scope exists and is not logically deleted.
3. The system verifies the person exists, is not logically deleted, and is currently a User belonging to that scope.
4. The system changes the person’s RoleId to ScopeAdmin.
5. The system removes the person’s SCOPE_USER row and inserts a SCOPE_OWNER row linking them to the scope.
6. The system returns the updated person.

Alternative Flows:

On AF-23e. A User’s email is unique only within their scope; a ScopeAdmin’s is unique system-wide (FR-PE-09). Promotion moves the person between those two namespaces, so the same email that was fine as a User can collide with an existing admin the moment it becomes global. This is checked the same way UC-08’s role change re-checks uniqueness against the role the person is about to hold.

UC-24: Enable/Disable Google Sign-In

Main Flow:

sequenceDiagram
    actor Admin as System Admin / Existing Owner
    participant API as Heimdall API
    participant DB as Database

    Admin->>API: PUT /api/scopes/{id}/google-signin { enabled }
    API->>DB: Verify scope exists
    DB-->>API: Scope found
    API->>DB: Set scope.GoogleSignInEnabled = enabled
    DB-->>API: Updated
    API-->>Admin: 200 OK { scope }

1. Actor sends a request to enable or disable Google Sign-In for a scope.
2. The system validates the input fields.
3. The system verifies the scope exists.
4. The system checks authorization: System Admin, or an existing owner of the scope.
5. The system sets GoogleSignInEnabled to the requested value.
6. The system returns the updated scope.

Alternative Flows:

On AF-24c. The request body carries a single boolean, so an omitted enabled cannot be distinguished from an explicit false once bound — a malformed request would silently perform the disable half of this use case. The value is therefore required rather than defaulted, and is checked before the scope is looked up (step 2, as in UC-01). NFR-10 already asks for this; the flow is named here so the refusal is specified rather than incidental.

UC-25: Sign Up / Sign In via Google

Main Flow:

sequenceDiagram
    actor Caller as Anonymous
    participant GIP as Google Identity Platform
    participant API as Heimdall API
    participant DB as Database

    Caller->>GIP: Authenticate with Google
    GIP-->>Caller: ID token { sub, email, email_verified, name, picture }
    Caller->>API: POST /api/auth/google { scopeId, idToken, nonce? }
    API->>GIP: Verify ID token signature, issuer, audience, expiration
    GIP-->>API: Token valid, claims
    API->>DB: Verify scope exists, is not logically deleted, and GoogleSignInEnabled = true
    DB-->>API: Scope found
    API->>DB: Find GOOGLE_USER by GoogleId (sub) and scopeId
    alt Google User does not exist
        API->>API: Require email_verified == true
        API->>DB: Check email uniqueness in scope (jointly with User persons)
        DB-->>API: Email is unique
        API->>DB: Insert GOOGLE_USER row { GoogleId, Name, Email, EmailVerified, ProfilePictureUrl, ScopeId }
        DB-->>API: Google User created
    else Google User exists
        API->>DB: Check IsDeleted == false
        DB-->>API: Confirmed
        API->>DB: Refresh EmailVerified from the token claims if it differs
    end
    API->>API: Generate JWT token { googleUserId, role = User, scopeId }
    API-->>Caller: 200 OK { token, expiresAt, emailVerified }

1. The caller authenticates with Google (outside this API) and obtains a signed ID token.
2. The caller sends the ID token and target scope ID to the API, and optionally the nonce it sent Google when asking for the token.
3. The system verifies the ID token’s signature, issuer, audience, and expiration. When the request carries a nonce, the token’s nonce claim must equal it (FR-GO-20, AF-25g).
4. The system verifies the target scope exists, is not logically deleted, and has GoogleSignInEnabled = true.
5. The system looks up a Google User by GoogleId (the token’s sub claim) within the scope.
6. If none exists: the system requires the token’s email_verified claim to be true (AF-25f), verifies the token’s email is unique within the scope (jointly with User persons’ emails), then creates a new Google User populated from the token’s claims (Name, Email, EmailVerified, ProfilePictureUrl).
7. If one exists: the system confirms it is not under a restriction on processing (AF-25e) and not logically deleted, and refreshes the stored EmailVerified from the token’s claims when the two differ (FR-GO-19). A token carrying no email_verified claim asserts nothing about the address, so the stored value is left as it stands.
8. The system issues an authentication token containing the Google User’s ID, display name, role = User, and the scope ID. When Google supplied no name, the verified email is used as the display name.

Alternative Flows:

UC-26: Sign Out via Google

Main Flow:

1. The Google User sends a sign-out request with their current token.
2. The system confirms the token still names a live Google User and instructs the client to discard it. It revokes nothing: Heimdall’s tokens are stateless (NFR-03), a Google User’s token carries no security stamp (FR-AU-11), and Heimdall holds no session with Google to end.
3. The system returns success.

Alternative Flows:

UC-27: View Google User

Main Flow:

1. Actor requests a Google User by ID or a list of Google Users within a scope.
2. The system checks authorization:
   • System Admin: can view any Google User.
   • Scope Admin: can view the Google Users of the scopes they own.
   • Google User: can view only their own record.
3. Logically deleted Google Users are excluded unless explicitly requested.
4. The system returns Google User data.

Alternative Flows:

UC-28: Logical Delete Google User

Main Flow:

1. Actor sends a delete request for a Google User.
2. The system checks authorization: System Admin, or an owner of the Google User’s scope.
3. The system sets IsDeleted = true on the Google User record.
4. The system returns success.

Alternative Flows:

UC-29: Hard Delete Google User

Main Flow:

1. System Admin sends a hard delete request.
2. The system records a tombstone for the Google User in ERASED_SUBJECT — their PublicId, that it was a Google User, and when — before the record is deleted, so the audit entries naming them, this hard delete’s own among them, can still be cleared once the row is gone (NFR-21, #195). A retry records it again without error.
3. The system permanently deletes the Google User record.
4. The system returns success.

Alternative Flows:

UC-31: Create Scope Permission

Main Flow:

sequenceDiagram
    actor Caller as System Admin / Scope Admin (owner)
    participant API as Heimdall API
    participant DB as Database

    Caller->>API: POST /api/scopes/{scopeId}/permissions { name, description?, includeAsJwtClaim? }
    API->>API: Validate input
    API->>DB: Verify scope exists and is not logically deleted
    DB-->>API: Scope found
    API->>API: Verify actor may manage the scope (System Admin bypasses, Scope Admin must own it)
    API->>DB: Insert scope permission record { Name, Description, IncludeAsJwtClaim, ScopeId, IsDeleted = false }
    DB-->>API: Permission created
    API-->>Caller: 201 Created { permission }

1. Caller sends a request with the permission Name, an optional Description, and an optional IncludeAsJwtClaim flag, targeting a scope.
2. The system validates the input shape: Name is required and at most 200 characters; Description, when supplied, is at most 500 characters.
3. The system verifies the target scope exists and is not logically deleted.
4. The system verifies the actor may manage the scope — a System Admin bypasses the check; a Scope Admin must own it.
5. The system creates the scope permission record with IsDeleted = false and IncludeAsJwtClaim as supplied (defaulting to false when omitted).
6. The system returns the created permission.

Alternative Flows:

On the role gate. The endpoint carries [RoleRequirement(SystemAdmin, ScopeAdmin)], so a User is refused with 403 before the handler runs — independently of the data-dependent AF-31e. The same framework-level refusal applies to every scope-permission endpoint in UC-31 through UC-34; only UC-35 restricts further, to SystemAdmin alone. These framework refusals are not listed as separate alternative flows because they are settled by the attribute, not by the use case’s data rules.

UC-32: View Scope Permission

Main Flow (read a — permission by ID):

1. Actor requests a scope permission by ID within a scope.
2. The system loads the permission, qualifying the lookup by the route’s scopeId, and excluding logically deleted permissions unless includeDeleted is explicitly requested (FR-SP-09).
3. The system checks authorization: a System Admin sees any permission; a Scope Admin must own the permission’s scope.
4. The system returns the permission data.

Main Flow (read b — list a scope’s permissions):

1. A System Admin or a Scope Admin requests the permissions of a scope, optionally filtering by Name (case-insensitive) and paging the result (FR-SP-05).
2. The system verifies the scope exists and is not logically deleted.
3. The system verifies the actor may manage the scope: a System Admin always may; a Scope Admin must own it.
4. The system returns the page of the scope’s permissions, excluding logically deleted permissions unless explicitly requested. There is no per-owner narrowing — a scope permission has no owner of its own, so owning the scope is the whole of the rule.

Alternative Flows:

UC-33: Update Scope Permission

Main Flow:

1. Actor sends an update request to PUT /api/scopes/{scopeId}/permissions/{id} with the new Name, Description, and IncludeAsJwtClaim values.
2. The system validates the input shape, reusing UC-31’s rules.
3. The system loads the permission inside the addressed scope, excluding logically deleted permissions.
4. The system checks authorization: a System Admin may update any permission; a Scope Admin must own the permission’s scope.
5. The system applies the updates and stamps UpdatedAt.
6. The system returns the updated permission.

Alternative Flows:

UC-34: Logical Delete Scope Permission

Main Flow:

1. Actor sends DELETE /api/scopes/{scopeId}/permissions/{id}.
2. The system locates the permission inside the addressed scope in any deletion state — an already-deleted permission must be found so AF-34b can answer idempotently rather than as a 404.
3. The system checks authorization: a System Admin may delete any permission; a Scope Admin must own the permission’s scope. This runs before the idempotent check, so an already-deleted permission cannot be used to probe for scopes the caller may not act on.
4. If the permission is already logically deleted, the system returns success with alreadyDeleted = true and writes nothing.
5. Otherwise the system sets IsDeleted = true, stamps UpdatedAt, and returns success with alreadyDeleted = false.

Alternative Flows:

UC-35: Hard Delete Scope Permission

Main Flow:

1. System Admin sends DELETE /api/scopes/{scopeId}/permissions/{id}/hard.
2. The system locates the permission inside the addressed scope in any deletion state — a logically deleted permission is exactly what a cleanup pass starts from, so soft deletion must not block a hard one.
3. The system permanently deletes the record. No dependent is removed first — no entity carries a foreign key to a scope permission.
4. The system returns success.

Alternative Flows:

On UC-35’s only refusals. Authorization is settled entirely by the endpoint’s [RoleRequirement(SystemAdmin)]: a ScopeAdmin or User is refused with 403 before the handler runs, and an unauthenticated caller is refused with 401. No data-dependent authorization rule is left for the handler to apply, which is why no AF-35e appears here — unlike UC-31 through UC-34, whose scope-ownership rule is data-dependent and lives in the handler.

UC-36: Enable Two-Factor Authentication

Main Flow (a — initiate setup):

sequenceDiagram
    actor P as Person
    participant API as Heimdall API
    participant DB as Database
    participant ES as Email Service

    P->>API: POST /api/auth/2fa/enable { methods: ["App", "Email"], currentPassword }
    API->>API: Verify currentPassword against PasswordHash/Salt
    API->>DB: Find or create TWO_FACTOR_AUTH row for the person (IsActive = false)
    API->>API: If App selected, generate TOTP secret and encrypt it
    API->>DB: Store encrypted secret, AppEnabled = true
    API->>ES: If Email selected, send first 6-digit code
    ES-->>API: Email queued
    API-->>P: 200 OK { otpAuthUri?, emailCodeSent? }

1. Caller sends POST /api/auth/2fa/enable with the method(s) they want: App, Email, or both, and their currentPassword (FR-2F-18).
2. The system confirms the caller has no already-active two-factor configuration, that their account-email budget would admit a send when Email is selected (AF-36f, AF-36g), and that currentPassword matches their password (AF-36e); with Email, it then reserves the send (FR-2F-19), and creates (or reuses a not-yet-confirmed) TWO_FACTOR_AUTH row for them.
3. If App was selected, the system generates a random TOTP secret (RFC 6238), stores it encrypted, and returns an otpauth:// provisioning URI for QR scanning. The plaintext secret is never stored — only the encrypted form.
4. If Email was selected, the system generates a random 6-digit code, stores it (hashed, 10-minute expiry), and sends it through the email service.
5. The system returns success, confirming which method(s) are pending confirmation. Nothing is active yet — UC-37 finishes the job.

Main Flow (b — read the caller’s own status):

1. An authenticated person requests their own two-factor state through GET /api/auth/2fa (FR-2F-15). The person read is always the caller, taken from their token — a configuration is never addressed by an identifier in a path.
2. The system loads the caller’s TWO_FACTOR_AUTH row, if one exists.
3. The system returns whether two-factor authentication is active, which methods are configured, and how many issued recovery codes remain unused. No secret is returned: never the TOTP secret, never a recovery code.
4. A caller with no TWO_FACTOR_AUTH row is answered successfully, with every flag false and a zero count. Never having enabled two-factor authentication is an ordinary state, not a fault, and a setup initiated but not yet confirmed is reported as inactive with its selected methods set.

Alternative Flows:

On requiring the password. Adding a second factor requires proof of identity, as removing one does (UC-39): the method chosen here is what UC-38 demands at every later login, and a bearer token is not proof that the account holder is present.

UC-37: Confirm Two-Factor Authentication Setup

Main Flow:

sequenceDiagram
    actor P as Person
    participant API as Heimdall API
    participant DB as Database

    P->>API: POST /api/auth/2fa/confirm { appCode?, emailCode? }
    API->>DB: Load the pending TWO_FACTOR_AUTH row
    API->>API: Verify appCode against the TOTP secret, if AppEnabled
    API->>API: Verify emailCode against the stored hash, if EmailEnabled
    API->>DB: Set IsActive = true
    API->>API: Generate 10 recovery codes, hashing each
    API->>DB: Store the 10 hashed recovery codes
    API-->>P: 200 OK { enabled: true, recoveryCodes: [10 plaintext codes] }

1. Caller sends POST /api/auth/2fa/confirm with a code for every method they selected in UC-36 (an appCode if AppEnabled, an emailCode if EmailEnabled — both, if both).
2. The system verifies each provided code against its method: the TOTP code against the stored secret, the email code against its stored hash and expiry.
3. Only once every required code checks out, the system replaces the person’s security stamp, which revokes every token issued before the second factor was required, the caller’s own included (FR-AU-11).
4. The system generates ten random recovery codes, hashes each, and stores the hashes. Each is 80 bits, sixteen characters of Crockford’s base32 shown as XXXX-XXXX-XXXX-XXXX (FR-2F-20).
5. The system sets IsActive = true.
6. The system returns the ten recovery codes in plaintext. This is the only response that will ever contain them — they are not retrievable again (only regenerable, via UC-40). The client keeps them, then signs in again; that login now goes through UC-38.

Alternative Flows:

On requiring every selected method’s code. If both App and Email were chosen in UC-36, both codes are required in the same confirmation request. Confirming with only one channel would activate a method whose configuration was never actually exercised — for the app, that a QR code was scanned into a real authenticator; for email, that the address reliably receives mail — leaving a silently broken second factor discovered only at the next login.

UC-38: Verify Second Factor (Login Challenge)

Main Flow:

sequenceDiagram
    actor U as Anonymous
    participant API as Heimdall API
    participant DB as Database

    U->>API: POST /api/auth/2fa/verify { challengeToken, code }
    API->>API: Validate challengeToken (signature, not expired, MFA-pending claim)
    API->>DB: Load the person's TWO_FACTOR_AUTH row
    API->>API: Verify code as a current TOTP/email code, or as an unused recovery code
    API->>DB: If a recovery code was used, mark it Used = true
    API->>API: Generate full JWT token { personId, role, scopeId/ownedScopeIds? }
    API-->>U: 200 OK { token, expiresAt, emailVerified }

1. Caller sends the challenge token from UC-11’s login response, together with either a current app/email code or a recovery code.
2. The system validates the challenge token: signature, expiration, and that it carries the MFA-pending claim (FR-2F-10) — this endpoint is the only one that accepts such a token. The token must also still name the person’s outstanding challenge: redeeming a challenge spends it, and a newer login replaces it, so a challenge is redeemable once (FR-2F-10).
3. The system checks the supplied value: a TOTP code against the stored secret, an email code against its stored hash and expiry, or a recovery code against the stored hashes — ignoring its hyphens, whitespace and case, and reading an O, I or L in a sixteen-character code as 0, 1 and 1; a code of the shorter XXXX-XXXX shape issued before still matches as it was stored (FR-2F-20). A guess with an app code or a recovery code is first charged to the challenge, which allows five (FR-2F-17); an email code’s guesses are charged to the code (FR-2F-13). Every guess is also charged to the person, across challenges, and a correct password does not reset that count: the tenth failure locks the second factor, for fifteen minutes and twice as long at each repeat, up to a day, and only a second factor that checks out resets it (FR-AU-12).
4. If a recovery code was used, the system marks it consumed — it cannot be used again.
5. The system marks the challenge redeemed, then generates and returns the full authentication token, identical in shape to a direct UC-11 success. A person whose processing is restricted (NFR-24) — including one restricted after the challenge was issued — gets UC-11’s AF-11i subject-rights-only token instead, and AF-38d’s scope check does not apply to them.

Alternative Flows:

On the single rejection. As with UC-11’s own AF-11a..e, AF-38a through AF-38c collapse to one indistinguishable 401 — telling an unauthenticated caller which part of their guess was wrong would leak whether a challenge token is merely expired versus outright forged, or whether a recovery code was ever real.

On AF-38d being separate. AF-38d is not folded into that collapse: the caller who reaches it proved both a valid challenge token and a genuine factor, so the failure is not “you guessed wrong” but “your account stopped qualifying between UC-11 and now.” There is nothing to hide by distinguishing it — the caller already holds proof they are who they say they are.

UC-39: Disable Two-Factor Authentication

Main Flow:

sequenceDiagram
    actor P as Person
    participant API as Heimdall API
    participant DB as Database

    P->>API: POST /api/auth/2fa/disable { password, code }
    API->>DB: Load person and TWO_FACTOR_AUTH row
    API->>API: Verify password against PasswordHash/Salt
    API->>API: Verify code as a current TOTP/email code, or as an unused recovery code
    API->>DB: Delete TWO_FACTOR_AUTH row (cascades to recovery codes)
    API-->>P: 200 OK

1. Caller sends their current password together with a valid second factor — an app/email code or a recovery code.
2. The system verifies the password, exactly as UC-11 does.
3. The system verifies the second factor, exactly as UC-38 does.
4. Only when both check out, the system replaces the person’s security stamp, revoking every token issued while the factor stood (FR-AU-11), then deletes the TWO_FACTOR_AUTH row, which cascades to its recovery codes.
5. The system returns success. The token that made the request is revoked with the rest, so the client signs in again; two-factor authentication no longer applies to that login.

Alternative Flows:

On requiring both factors to disable. Password alone is not enough: an attacker holding only a stolen session or a leaked password should not be able to strip two-factor protection off an account they don’t fully control. Requiring the second factor too makes disabling exactly as hard as a login.

UC-40: Regenerate Recovery Codes

Main Flow:

sequenceDiagram
    actor P as Person
    participant API as Heimdall API
    participant DB as Database

    P->>API: POST /api/auth/2fa/recovery-codes/regenerate { code }
    API->>DB: Load TWO_FACTOR_AUTH row
    API->>API: Verify code as a current TOTP/email code, or as an unused recovery code
    API->>DB: Delete all existing TWO_FACTOR_RECOVERY_CODE rows for the person
    API->>API: Generate 10 new recovery codes, hashing each
    API->>DB: Store the 10 new hashed recovery codes
    API-->>P: 200 OK { recoveryCodes: [10 plaintext codes] }

1. Caller sends a valid second factor — an app/email code, or one of their remaining recovery codes.
2. The system verifies it, exactly as UC-38 does.
3. The system replaces the person’s security stamp, revoking every token issued before (FR-AU-11): the codes are usually replaced because the old set may be known to somebody else, and so may a session opened with one.
4. The system generates ten new codes of the current shape (FR-2F-20), hashes each, and stores them, then deletes every earlier recovery code row for the person, including any still unused. This is also how a person holding the shorter codes issued before FR-2F-20 gets the stronger ones.
5. The system returns the ten new codes in plaintext — the only response that will ever contain them. The client keeps them, then signs in again.

Alternative Flows:

On invalidating the whole set. Regeneration replaces all ten codes at once rather than topping up the used ones back to ten: a partial refill would leave old, already-distributed codes valid alongside new ones, defeating the point of rotating them.

UC-46: Resend Second-Factor Email Code

Main Flow:

sequenceDiagram
    actor U as Anonymous
    participant API as Heimdall API
    participant DB as Database
    participant M as Mail

    U->>API: POST /api/auth/2fa/challenge/resend { challengeToken }
    API->>API: Validate challengeToken (signature, not expired, MFA-pending claim)
    API->>DB: Load the person and their active TWO_FACTOR_AUTH row
    API->>DB: Increment the challenge's reissue count (refuse past the cap)
    API->>DB: Mark outstanding email codes Used = true
    API->>DB: Store a fresh 6-digit code, hashed, expiring per FR-2F-03
    API->>M: Send the code to the person's stored address
    API-->>U: 200 OK

1. Caller sends the challenge token UC-11’s login response returned. Nothing else — no address, no scope, no credential.
2. The system validates the challenge token exactly as UC-38 step 2 does: signature, expiration, and the MFA-pending claim (FR-2F-10).
3. The system resolves the person the token names and their active two-factor configuration, and confirms the email method is enabled for them.
4. The system confirms the challenge has reissues left (FR-2F-13) and charges one against it.
5. The system retires the person’s outstanding email codes and stores a fresh one, hashed, expiring per FR-2F-03.
6. The system mails the code to the person’s stored address.
7. The system answers 200 OK, carrying no data.

Alternative Flows:

On the single answer. Every flow above, and the main flow, return the same 200 OK with the same message and no data. That is the point of the endpoint’s design rather than an economy in writing it: this route is anonymous, and an answer that varied would say whether an address is registered, whether it has email two-factor enabled, and how much of its guessing budget is left. It is the same reasoning behind UC-11’s AF-11a…AF-11e and UC-38’s AF-38a…AF-38c, with the sign flipped — those collapse to one 401 because the caller asked to be let in; this collapses to one 200 because they asked for something to be sent, and “we have sent it if there was anything to send” is the most that can be said without answering a question they did not earn the right to ask.

On the challenge not being extended. A reissue puts a fresh code inside the existing challenge’s window; it never lengthens it and never returns a new challenge token. This is forced rather than chosen: a new token could only be returned for a challenge that was genuine, so returning one would be precisely the oracle the paragraph above rules out. The window’s ceiling is therefore NFR-17’s, which is the same ten minutes FR-2F-03 gives the code — so a reissue inside the window is worth having rather than a formality.

On the reissue cap. FR-2F-13 retires an email code after five wrong guesses. Without a cap, this use case would turn that bound into five guesses times however many reissues a caller could obtain, which would make it a property of the rate limiter’s configuration rather than of the specification. Three reissues per challenge keeps it stated: at most twenty guesses at a six-digit code per authentication, after which a further code costs a fresh password check — which is what FR-2F-13 always charged.

UC-47: Register a Password User

Main Flow:

sequenceDiagram
    actor U as Anonymous
    participant API as Heimdall API
    participant Q as Registration queue
    participant DB as Database
    participant M as Mail

    U->>API: POST /api/auth/register { name, email, password, scopeId }
    API->>API: Validate the request
    API->>DB: Confirm the scope is open
    API->>API: Hash the password
    API->>Q: Queue { scopeId, name, email, hash, salt }
    API-->>U: 202 Accepted
    Q->>DB: Re-check the scope, look the address up in the scope
    Q->>DB: Write a pending registration (address free)
    Q->>M: Send the confirmation email (UC-14 link)
    U->>API: POST /api/auth/verify-email { token, password } (UC-14)
    API->>API: Check the password against the stored hash
    API->>DB: Re-check the scope and the address
    API->>DB: Create the User, verified; remove the address's pending registrations
    API-->>U: 200 OK

1. Caller sends a name, an email address, a password and the scope’s PublicId.
2. The system validates the request with the rules UC-06 path a applies (FR-SR-03).
3. The system confirms the scope exists, is live and is open to self-registration.
4. The system hashes the password, queues the request and answers 202 Accepted with a fixed message.
5. Afterwards, the system re-checks the scope and confirms the address is held by no live person and no Google User of the scope (FR-SR-04).
6. The system writes a pending registration — name, address, password hash and salt, and the hash of a single-use token, expiring with the email-verification token lifetime (FR-SR-08) — and mails the token’s link (FR-EV-01/02), in a message that tells the registrant to enter the password chosen at sign-up. It creates no User.
7. The person follows the link (UC-14) and enters the password chosen at sign-up (FR-SR-09).
8. The system checks the password against the stored hash, re-checks that the scope is still open and the address still free, creates the User, verified, records its legal basis (NFR-23), and removes the address’s pending registrations (FR-SR-07).

Alternative Flows:

On the single answer. As UC-12 and UC-46 do, this anonymous route answers a free and a taken address alike, in content and in time (FR-SR-06). Everything whose cost depends on the answer runs after the response. The scope check stays on the request path because it says nothing about any address.

On the mail an address can be sent. Each request may mail the address it names, and the caller cannot see whether it did, so the bound has to be on the recipient rather than the caller: the per-IP rate limit does nothing against a sender with many source addresses. AF-47k bounds the confirmation mail to three live links per scope; AF-47l bounds the notices to three a day per address across every scope. Both are applied after the response, like everything else that depends on the address, so they change nothing the caller sees.

UC-41: Export Own Personal Data

Main flow

1. The system resolves the subject from the authentication token — never from the request, which carries no identifier for one.
2. The system assembles the identity, the security state — whether a password and second factor are set, and the counters and locks of the login lockout (FR-AU-09), the second-factor budget (FR-AU-12) and the re-authentication budget (FR-AU-13) — the lawful basis and notice version, the deletion and erasure state, scope memberships and ownerships, owned applications, and the audit entries still attributed to the subject.
3. The system adds the context Art. 15 requires alongside the data: who else receives it, how long each category is kept, and what is held but not reproduced.
4. The system returns the document with Cache-Control: no-store.

Alternative flows

Notes

• POST, for something that reads. A GET response is cacheable, and this one is a document containing everything about a person — exactly what must not sit in a proxy or browser cache. The export is also the highest-value action a stolen token can take, so it must reach the audit trail, which here means being a command.
• One endpoint, not one per identity type. The subject is the token’s, so a second endpoint would be a second way to say the same thing and a second place to get authorization wrong.
• Secret material is named, not reproduced. Art. 15(4) says the right to a copy must not adversely affect others’ rights, and reproducing a password hash or a TOTP secret would hand whoever holds the document the material to attack the account. Each is listed with the reason, so the subject learns what exists.
• A suspended identity can still export. The lookups omit the !IsDeleted filter most handlers apply: somebody suspended pending erasure has more reason to want a copy than anyone, and Art. 15 is not conditional on the account being in good standing.
• So can a restricted one (NFR-24: “remaining reachable by its own subject’s export”). The liveness check that refuses a restricted or suspended identity’s token everywhere else steps aside for this endpoint and for UC-42, UC-44 and UC-45; an anonymised identity is still refused.
• Cleared audit attributions cannot appear. Once NFR-21 clears an attribution, nothing connects the entry to the person; reporting it would itself be a re-identification.

UC-42: Request Erasure of Own Identity

Main flow

1. The caller submits their credential: a password if they are a person, a freshly issued Google ID token if they are a Google User.
2. The system resolves the subject from the authentication token — never from the request, which carries no identifier for one.
3. The system verifies the credential against that identity.
4. The system records ErasureRequestedAt and computes ErasureDueAt from the statutory deadline, storing it so a later configuration change cannot move an obligation that has already attached.
5. If the subject’s processing is restricted (UC-44), the system lifts the restriction in the same write, as UC-45 does for a subject lifting their own — no notification — and records the lift in the audit trail (NFR-09).
6. The system suspends the identity, marking the deletion as subject-requested so the shorter deadline applies.
7. The system returns the request timestamp, the deadline, and whether a restriction was lifted.

Alternative flows

Notes

• The suspension is immediate and deliberate: a subject who has asked to be erased has withdrawn the basis on which the account operates, so continuing to authenticate them while the deadline runs would be processing they have objected to.
• AF-42d is a success rather than a refusal. The subject’s right does not depend on the scope’s ownership arrangements, and GDPR Art. 12(3)’s clock starts at the request whether or not anything blocks it. Answering 4xx would tell the subject their right had been refused when it has not.
• Because it verifies a password, this use case’s endpoint is governed by NFR-18 rather than NFR-05.
• A restricted subject may request erasure, and the request lifts the restriction (NFR-24). The right does not lapse with the restriction, and the request is the subject’s own consent to the processing it involves (Art. 18(2)). Left in place, the restriction would keep the record out of the anonymisation pass while the deadline ran out. Only the subject can impose a restriction (UC-44), and only the subject, credential in hand, can reach this step — so the request is their later and more specific instruction, and it supersedes their wish that the record be preserved. No Art. 18(3) notification is sent: the subject is the person it would inform (UC-45). The response says so (restrictionLifted), and the audit trail records a LiftProcessingRestrictionCommand entry on the subject beside the request’s own.
• A restriction imposed after the request holds the erasure. A suspended identity may still restrict (UC-44), and that later instruction is not overridden: NFR-24 keeps the record out of the anonymisation pass until it is lifted — by the subject (UC-45), or by a System Admin after informing them — and UC-43 shows it meanwhile. Repeating the erasure request is AF-42c and lifts nothing.
• This use case does not change UC-09 or UC-10. Those remain administrative operations and keep refusing self-deletion; this is a separate path with a different actor and a different meaning.

UC-44: Restrict Processing of Own Identity

Main flow

1. The caller names one of Art. 18(1)’s four grounds.
2. The system resolves the subject from the authentication token — never from the request.
3. The system records the restriction and the ground.
4. From that moment the identity can authenticate only for its subject’s own rights (a subject-rights-only token — UC-11 AF-11i, UC-25 AF-25e), receives no email but the second-factor codes its subject asks for when signing in, and is withheld from tenant-facing listings.

Alternative flows

Notes

• Restriction is not deletion, and the two are independent states. IsDeleted means the identity is on its way out — excluded from reads, cascaded by UC-04, eventually anonymised by NFR-20. A restriction means the opposite: the record is disputed and must be preserved exactly as it stands. Reusing the flag would start an erasure clock on data the subject has specifically asked be kept.
• No credential is required, unlike UC-42. Erasure is irreversible and demands proof the person is present. A restriction destroys nothing and is liftable, and somebody asking for one may be doing so precisely because they believe the account is compromised — demanding the password of a person in that position would be the wrong way round.
• A suspended identity may still restrict. Art. 18 does not require the account to be in good standing, and a person pending erasure may well want to contest what is held about them. Such a restriction holds the erasure until it is lifted (UC-45), because it is the subject’s later instruction; the reverse order differs — an erasure request lifts a restriction already in place (UC-42).
• A restricted identity can still reach this use case and its siblings. Every other endpoint refuses its token (NFR-24), but UC-41, UC-42, UC-44 and UC-45 are how the subject exercises their rights over the restricted record, so they admit a restricted or suspended (not anonymised) subject and answer with their own flows — here, AF-44a.
• The grounds are an enum rather than free text: Art. 18(1) is exhaustive, so prose would add unbounded personal data with no purpose the ground does not already serve.

UC-45: Lift a Restriction on Processing

Main flow

1. The system resolves the subject — the caller’s own identity, or the one named where a System Admin is acting.
2. Where the caller is not the subject, the system informs the subject before proceeding.
3. The system clears the restriction and records that the notification happened.

Alternative flows

Notes

• AF-45b is the opposite of how every other delivery in this API behaves. Elsewhere a failed send is deliberately not the caller’s problem: a verification email that does not arrive is re-requested, and surfacing the failure would leak whether an address exists. Art. 18(3) makes this one a precondition — the subject “shall be informed before the restriction is lifted” — so a lift that proceeded after a failed send would be unlawful, and would look identical to one that worked.
• The subject can reach this while restricted. Their token is refused everywhere else (NFR-24), but lifting their own restriction is their right, so this endpoint admits it. It admits nothing more: a restricted System Admin is a subject here, not an administrator (AF-45c).
• Signing in still reaches it. A subject whose earlier tokens have expired signs in as usual and is issued a subject-rights-only token (UC-11 AF-11i, UC-25 AF-25e, UC-38), which this endpoint admits. That token acts for its subject alone — a System Admin holding one is refused somebody else’s (AF-45c) — and stays confined to UC-41, UC-42, UC-44 and UC-45 after the lift, so the subject signs in again for a full token.
• A subject lifting their own needs no notification. They are the person Art. 18(3) exists to inform. Requiring an email to somebody standing in front of you, and refusing their request when it bounces, would be the article’s letter against its purpose.

UC-43: List Outstanding Erasure Requests

Main flow

1. The system reads the outstanding requests from both identity tables — those with a request recorded and no anonymisation yet.
2. The system marks each as overdue or not, against the moment the queue is read.
3. The system returns them paginated, soonest deadline first, optionally filtered to the overdue ones.

Notes

• The listing exists because a deadline nobody can see is a deadline nobody meets. Most requests need no human at all — the anonymisation pass carries them out — but the ones AF-42d blocks need an owner transferred first, and without this they would sit unnoticed until the deadline had passed.
• A Scope Admin is deliberately excluded, though they administer their scope’s users: which of them has asked to be erased is not something the request entitles anyone to know.
• The projection carries no name and no email address. The subject has asked to be erased; a queue an administrator works from is the last place to widen who sees their details.

UC-48: List the Audit Trail

Main Flow:

sequenceDiagram
    actor SA as System Admin
    participant API as Heimdall API
    participant DB as Database

    SA->>API: GET /api/audit-log?from&to&actorId&action&targetId&succeeded&pageNumber&pageSize
    API->>API: Validate the filters and the page
    API->>DB: Read the matching AUDIT_LOG rows, newest first
    API-->>SA: 200 OK — a page of entries

1. A System Admin requests the audit trail, optionally filtering by an inclusive range of when entries were recorded (from, to, UTC; a value without an offset is read as UTC), by the actor’s identifier, by the exact action (the command’s type name, e.g. CreateScopeCommand), by the affected entity’s identifier, and by outcome (succeeded), and paging the result (FR-AT-01). Filters combine with AND; an empty action is no filter.
2. The system validates the request: the range must not run backwards, the action must fit its column (200 characters), and the page must be within NFR-10’s bounds.
3. The system returns the matching entries newest first, ties broken by the order they were written, each with its identifier, when it was recorded, the actor and their role, the action, the target, whether it succeeded and, for a refusal, the canonical reason (FR-AT-02).

Alternative Flows:

On cleared actors. The listing shows each entry as stored and never reconstructs a cleared actor — no join to PERSON, no inference from other entries (NFR-09, NFR-21, Data Retention Schedule §7.1). An entry whose attribution period is over, or whose actor has been anonymised, reads actorId: null, and filtering by actorId cannot find it. The same holds for targets: an entry whose target was a person or Google User has that target cleared on the same two grounds and reads targetId: null, so filtering by targetId cannot find it either. So does an entry whose target was hard-deleted (UC-05, UC-10, UC-29) — the hard delete’s own entry included — on the pass after the delete, at any age, because the hard delete tombstoned the id first (#195). Targets naming anything else — a scope, an application, a credential, a permission — are kept and stay filterable, as is the id of a person hard-deleted before tombstones existed, which nothing recorded.

On Scope Admins. AUDIT_LOG has no scope column, and an old entry’s target may since have been deleted or anonymised, so the trail cannot be divided by scope reliably. The listing is therefore System Admins’ only.

UC-49: List Pending Registrations

Main Flow:

sequenceDiagram
    actor A as System Admin / Scope Admin
    participant API as Heimdall API
    participant DB as Database

    A->>API: GET /api/scopes/{id}/pending-registrations?pageNumber&pageSize
    API->>DB: Find the live scope
    API->>DB: Confirm the actor may manage it
    API->>DB: Read the scope's PENDING_REGISTRATION rows, newest first
    API-->>A: 200 OK — a page of registrations

1. A System Admin or a Scope Admin requests a scope’s pending registrations, paging the result (FR-SR-11).
2. The system confirms the scope exists and is not logically deleted.
3. The system confirms the actor may manage the scope: a System Admin always may; a Scope Admin must own it.
4. The system returns the scope’s pending registrations, newest first, each with its identifier, name, address, when it was stored and expires, how many wrong confirmation passwords it may still take (never below zero), and whether it has already expired. Whether the scope is still open to self-registration does not matter. The password hash, salt and token hash are never returned.

Alternative Flows:

On anti-enumeration. FR-SR-06’s guarantee is about the anonymous POST /api/auth/register, which still answers free and taken addresses alike. This listing is authenticated and limited to the scope’s owners, who would see the same name and address in their user list once the registration is confirmed, and a taken address never produces a pending row — so it reveals nothing about existing accounts.

UC-50: Discard a Pending Registration

Main Flow:

sequenceDiagram
    actor A as System Admin / Scope Admin
    participant API as Heimdall API
    participant DB as Database

    A->>API: DELETE /api/scopes/{id}/pending-registrations/{registrationId}
    API->>DB: Find the live scope, confirm the actor may manage it
    API->>DB: Find the registration within that scope
    API->>DB: Delete it
    API->>DB: Write the audit entry (target: the registration)
    API-->>A: 200 OK

1. A System Admin or a Scope Admin asks to discard a scope’s pending registration, by the identifier UC-49 returned (FR-SR-12).
2. The system confirms the scope exists, is not logically deleted, and that the actor may manage it.
3. The system finds the registration among that scope’s.
4. The system deletes it, records the discard in the audit trail with the registration as target (NFR-09), and answers with its identifier. Following its link now behaves as for any unknown token (UC-14 AF-14c); the registrant may sign up again.

Alternative Flows:

UC-51: Send a Verification Email on a Person’s Behalf

Main Flow:

sequenceDiagram
    actor A as System Admin / Scope Admin
    participant API as Heimdall API
    participant DB as Database
    participant M as Email Service

    A->>API: POST /api/persons/{id}/verification-email
    API->>DB: Find the person, confirm the actor may act on them
    API->>API: Refuse if restricted, deleted or already verified
    API->>DB: Any verification token issued within the cooldown?
    API->>DB: Retire live verification tokens, write a new one
    API->>M: Send the link to the person's stored address
    API-->>A: 200 OK

1. A System Admin or a Scope Admin asks for a verification email for a person, by the person’s identifier; there is no body (FR-EV-06).
2. The system finds the person and confirms the actor may act on them: a System Admin on anyone; a Scope Admin only on a User of a scope they own.
3. The system refuses a person whose processing is restricted (NFR-24), who is logically deleted, or whose address is already verified.
4. The system refuses if a verification email went to this person within the cooldown — any verification token issued for them in that window, by anyone, used or not (FR-EV-07).
5. As UC-15 does, the system retires the person’s live verification tokens, issues a new one and mails its link to the person’s stored address, using the scope’s verification URL when it has one.
6. The system answers with a fixed message; the token is never returned, logged or accepted.

Alternative Flows:

Best effort. The cooldown is read from the issued token rows, not held under a lock, so simultaneous requests for the same person can both pass it.

On delivery. 200 means the email was handed to the sender. A delivery failure is logged and swallowed, as for every email this API sends.

UC-52: Send a Password Reset on a Person’s Behalf

Main Flow:

sequenceDiagram
    actor A as System Admin / Scope Admin
    participant API as Heimdall API
    participant DB as Database
    participant M as Email Service

    A->>API: POST /api/persons/{id}/password-reset
    API->>DB: Find the person, confirm the actor may act on them
    API->>API: Apply UC-12's eligibility
    API->>DB: Any reset token issued within the cooldown?
    API->>DB: Write a reset token
    API->>M: Send the link to the person's stored address
    API-->>A: 200 OK

1. A System Admin or a Scope Admin asks for a password reset for a person, by the person’s identifier; there is no body (FR-PR-05).
2. The system finds the person and confirms the actor may act on them, as UC-51.
3. The system applies UC-12’s eligibility, shared with it: the person’s processing must not be restricted, the person must not be logically deleted, and the account must be able to sign in — a User’s scope live, a ScopeAdmin owning at least one live scope.
4. The system refuses if a reset email went to this person within the cooldown — any reset token issued for them in that window, by anyone, used or not (FR-PR-06).
5. The system issues a reset token and mails its link to the person’s stored address, using the scope’s reset URL when it has one. Unlike UC-12 the work is not queued: the caller is authenticated and is owed a real answer. Earlier live reset links are left as UC-12 leaves them.
6. The system answers with a fixed message; neither a token nor a password is returned, logged or accepted.

Alternative Flows:

Best effort. As for UC-51, simultaneous requests for the same person can both pass the cooldown.

UC-53: Issue an Application Credential

Main Flow:

sequenceDiagram
    actor A as System Admin / Scope Admin
    participant API as Heimdall API
    participant DB as Database

    A->>API: POST /api/scopes/{scopeId}/applications/{id}/credentials (expiresAt?)
    API->>API: Validate the expiry
    API->>DB: Find the live application in the live scope
    API->>API: Confirm the actor may manage it
    API->>API: Generate a secret, hash it
    API->>DB: Lock the application's row, count live credentials, insert if fewer than two
    API-->>A: 201 Created — id, secret, createdAt, expiresAt

1. A System Admin or a Scope Admin asks for a credential for an application, optionally with an expiry (expiresAt) (FR-AP-10).
2. The system validates the expiry: it must be in the future, and a value without an offset (what a datetime-local input produces) is read as UTC.
3. The system resolves the application in the addressed scope; it must be live, and so must the scope.
4. The system checks the actor may manage the application: a System Admin always may; a Scope Admin only if they own the application and still own its scope (FR-AP-12).
5. The system generates a secret (hds_ plus 32 random bytes, base64url, 47 characters) and stores only its SHA-256, under a lock on the application’s row, provided fewer than two live credentials exist (FR-AP-11). Two administrators issuing at the same moment cannot leave three live secrets.
6. The system answers 201 Created with the credential’s id, the secret, createdAt and expiresAt. The audit entry names the credential as target and never holds the secret (NFR-09).

Alternative Flows:

Why two. A secret is rotated without downtime by issuing the second, deploying it to the consumer, and only then revoking the first (FR-AP-11). A third would only let spent secrets pile up unrevoked. A credential that has expired or been revoked does not count towards the two.

Why the secret is never shown again. Heimdall keeps the hash alone, so neither the database, a backup nor a log can leak it, and no later call can return it. A lost secret is replaced, not recovered: issue another and revoke the lost one. The hds_ prefix lets a secret scanner recognise a leak (TH-33).

UC-54: List an Application’s Credentials

Main Flow:

sequenceDiagram
    actor A as System Admin / Scope Admin
    participant API as Heimdall API
    participant DB as Database

    A->>API: GET /api/scopes/{scopeId}/applications/{id}/credentials
    API->>DB: Find the live application in the live scope
    API->>API: Confirm the actor may manage it
    API->>DB: Read the application's credentials, newest first
    API-->>A: 200 OK — the credentials

1. A System Admin or a Scope Admin asks for an application’s credentials (FR-AP-12).
2. The system resolves the application and checks the actor may manage it, exactly as UC-53 does, not-found before authorization.
3. The system answers 200 OK with every credential, newest first, each with whether it is live now (not revoked, and not expired). The list is not paginated: at most two credentials are live, and spent ones are purged (Data Retention Schedule §5).

Alternative Flows:

UC-55: Revoke an Application Credential

Main Flow:

sequenceDiagram
    actor A as System Admin / Scope Admin
    participant API as Heimdall API
    participant DB as Database

    A->>API: DELETE /api/scopes/{scopeId}/applications/{id}/credentials/{credentialId}
    API->>DB: Find the live application in the live scope
    API->>API: Confirm the actor may manage it
    API->>DB: Find the credential on this application
    API->>DB: Set RevokedAt
    API-->>A: 200 OK — id, revokedAt

1. A System Admin or a Scope Admin asks to revoke a credential of an application (FR-AP-12).
2. The system resolves the application and checks the actor may manage it, as UC-53 does.
3. The system finds the credential on that application; one that belongs to another application is not found.
4. The system sets RevokedAt and answers 200 OK with the credential’s id and revokedAt (FR-AP-16, NFR-09).

Alternative Flows:

Expired credentials. A credential that has expired may still be revoked: it is stored until the retention purge, and revoking it only records the decision.

Revocation is immediate. It does not wait for the tokens already issued from the credential to expire; they fail UC-57’s live check at once (FR-AP-16).

UC-56: Obtain an Application Token

Main Flow:

sequenceDiagram
    participant App as Application
    participant API as Heimdall API
    participant DB as Database

    App->>API: POST /api/applications/token (applicationId, scopeId, secret)
    API->>API: Validate the fields
    API->>DB: Find a live credential by the hash of the trimmed secret
    API->>API: Confirm credential, application and scope match and are live
    API->>API: Sign a token under the application audience
    API->>DB: Stamp LastUsedAt, write the audit entry
    API-->>App: 200 OK — token, expiresAt

1. The application sends its applicationId, the scopeId and the secret.
2. The system validates their shape: each field is present and the secret is at most 100 characters.
3. The system trims the secret (a secret read from a file often carries a trailing newline), hashes it and looks the hash up among live credentials.
4. The system confirms the credential belongs to that application, the application to that scope, and that the application and scope are live.
5. The system issues a token signed like person tokens (HMAC-SHA256, the same keys) but under HEIMDALL_APPLICATION_TOKEN_AUDIENCE, valid for HEIMDALL_APPLICATION_TOKEN_EXPIRATION_IN_SECONDS (default 600), with the claims tokenKind, id, scopeId, credentialId and name and no role (FR-AP-13).
6. The system stamps the credential’s LastUsedAt, audits the issue (no actor; the application as target), and answers 200 OK with id, token and expiresAt.

Alternative Flows:

One refusal. As for UC-11, every refusal of the exchange is the same 401 with the same message, whatever failed, so the endpoint reveals nothing about which applications, scopes or credentials exist (FR-AP-14). Only a malformed request is told apart, and it learns nothing about any credential.

Rate limit. The endpoint shares the AuthAnonymous limit with person sign-in, per client address; TH-32’s trusted-caller key applies to it as to them.