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