Requirements on Heimdall API

Vision Document

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

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.

System Requirements Document

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

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.

Use Case Specification Document

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

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.

Technology Stack Document

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

Technology Stack Document — Heimdall API

1. Purpose

This document is the single source of truth for the technologies used to build the Heimdall API — the runtime platform, language, first-party libraries, database, data-access stack, cross-cutting concerns, and testing tools, together with the version each is pinned to and the role it plays.

Every other document in this folder references this document for technical choices instead of restating them, so that:

Data Protection Impact Assessment

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

Data Protection Impact Assessment — Heimdall API

Version 1.3 — 10 September 2026 · Assessed by Artur Rios, controller and Encarregado

Version	Date	Change
1.3	10 September 2026	Backup location and transfer ground established (MEGA — §7.3 of the Data Protection Document). R-08 re-rated Medium → Low: the signals are now collected and mailed. No open actions remain
1.2	10 September 2026	GDPR confirmed to apply. R-01 re-rated Medium → Low on confirmation of encryption at rest, for the volume and the backups. EEA hosting resolved: direct sign-up is not a Chapter V transfer, and an EEA tenant’s is covered by SCCs now incorporated in the DPA
1.1	10 September 2026	R-07 re-rated High → Low: the Google transfer was found not to exist, and the email transfer’s ground established under LGPD Art. 33 IX
1.0	9 September 2026	First assessment

1. Why this exists, and why the Threat Model is not it

GDPR Art. 35 requires a DPIA before processing likely to result in a high risk to data subjects, expressly including large-scale processing and systematic monitoring. LGPD Art. 38 gives the ANPD power to require a Relatório de Impacto à Proteção de Dados, and its guidance treats identity platforms serving multiple organisations as within scope.

Data Retention Schedule Document

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

Data Retention Schedule Document — Heimdall API

1. Purpose

This document states how long the Heimdall API keeps each category of personal data, and why. It is the record NFR-19 requires, and it is the source of truth the retention passes are configured against.

Two obligations make it necessary. GDPR Art. 5(1)(e) and LGPD Art. 15 require that personal data be kept in identifiable form no longer than the purpose requires. GDPR Art. 13(2)(a) and Art. 30(1)(f) require that the period, or the criteria used to determine it, be stated — to the data subject at collection, and in the record of processing activities.

Data Protection Document

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

Data Protection Document — Heimdall API

1. Purpose

This is the record of processing activities LGPD Art. 37 and GDPR Art. 30 require, together with the two things that record depends on and that nothing else in this repository states: who controls the data, and where it goes.

It is kept here rather than in a filing cabinet because the schema is the source of truth and the schema changes. Keeping the record next to the requirements means it is reviewed in the same pull request as the migration that outdates it.

Privacy Notice

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

Privacy Notice — Heimdall API

Version 1.2 — 5 October 2026

1. What this is

Heimdall is a centralised identity service. If you have an account with a system that uses it, this notice tells you what it holds about you, why, for how long, and what you can make it do.

It is written to be read by the person it is about. The formal record behind it — legal bases, recipients, transfer mechanisms — is the Data Protection Document .

Data Processing Agreement

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

Data Processing Agreement — Heimdall API

Template version 1.0 — 9 September 2026

0. How to read this

This is the agreement between Heimdall’s controller (Artur Rios — the Processor below) and an organisation whose client system uses a Heimdall scope (the Controller below), covering the personal data of that organisation’s users.

It is a template. Executing it means naming the organisation, the scope or scopes, and the date, and signing it. Everything else is drafted to match what Heimdall actually does — the clauses cite the mechanisms in this repository rather than describing a system in general terms, so a clause that stops being true becomes a failing document rather than a comfortable one.

Incident Response Document

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

Incident Response Document — Heimdall API

1. Purpose

GDPR Art. 33 requires a personal data breach to be notified to the supervisory authority within 72 hours of the controller becoming aware of it, and Art. 34 requires the affected data subjects be told without undue delay where the risk to them is high. LGPD Art. 48 requires communication to the ANPD and the subjects, which ANPD Resolution CD/ANPD nº 15 of 24 April 2024 fixes at 3 working days. Art. 33(5) requires every breach be documented, whether or not it was notifiable.

Testing Specification Document

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

Testing Specification Document — Heimdall API

1. Purpose

This document defines how a use case is tested once it has been implemented. It is a standard to be followed by any human or agent that builds tests for this project. Following it guarantees that every use case (UC-01 … UC-35 in the Use Case Specification Document ) receives the same shape of testing, with the same tools, naming, and structure.

Threat Model Document

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

Threat Model Document — Heimdall API

1. Purpose

The System Requirements Document states the security controls this API implements. It does not state what they defend against, and a control without a stated threat cannot be judged: there is no way to tell whether it is sufficient, whether it is the right control, or whether removing it would matter.

This document states the threats. Each one names the asset at risk, what an attacker must already be able to do, the control that addresses it — cited as an existing FR or NFR rather than restated — and how anybody knows the control works. Where nothing addresses a threat, that is written down as a finding rather than left out.

Development Workflow Document

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

Development Workflow Document — Heimdall API

1. Purpose

This document defines how a use case moves from backlog to merged — the branch, the issue status transitions, the testing gate, and the pull request. It is the standard every contributor (human or agent) follows so that each use case (UC-01 … UC-29 in the Use Case Specification Document , plus later additions such as UC-30) is delivered the same way.

Operations & Infrastructure Document

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

Operations & Infrastructure Document — Heimdall API

0. Hosting region

Personal data is stored in Brazil, and that is a constraint rather than an incidental fact: it determines which transfer rules apply to everything leaving the deployment. Moving the region means redoing the assessment in §7 of the Data Protection Document , because the outbound flows to Mailgun and Google are measured from wherever the data sits.