# Personal data register

Every piece of data the API keeps, who can read it, how it is protected and when it goes away.
Update this file in the same commit as any entity field, group or access rule it describes.

Legend: **Personal** = identifies or describes a person. **Sensitive** = personal data about a
person who may be a minor, or whose leak would harm them (birth date, contact, photo).
**Encrypted** = sealed at rest by `Security/PiiCipher` (XChaCha20-Poly1305, key `PII_KEY`).

## Principles

- Collect only what a coach needs. Not collected on purpose: weight, health records, the name of an
  uploaded file, the metadata of a photo (location, device: re-encoded away), the address of a person
  invited but who never answered (deleted on expiry). The one exception is the optional reason of an
  absence in the attendance of a training run (an injury, an illness, with a free detail): health
  data, encrypted, read by the staff only.
- Sensitive data is encrypted at rest, because the MySQL server is shared with other projects: a
  dump of it, or access to it, reveals none of it. The key lives outside the repository (`.env.local`,
  environment, secrets vault). **Back up `PII_KEY` with the database and `MEDIA_STORAGE_DIR`:
  without the key, encrypted data and photos are lost.**
- Personal data of players is returned only to the staff of their club (administrators, coaches),
  to the player themselves, decided record by record (`PlayerNormalizer`, `PlayerVoter`), and to
  the platform staff through its support access (see below), whose writes are logged.
- The server decides every access; clients only hide what the server would refuse.

## Accounts and sessions

| Table | Field | Personal | Encrypted | Who reads it |
|---|---|---|---|---|
| `user` | `email` | yes | no (needed to sign in, unique) | the user (`/me`); platform staff (`/users`) |
| `user` | `first_name`, `last_name` | yes | no | the user; platform staff; the staff of the user's clubs (member list, team coach); the other members read `displayName`, in the format the user chose |
| `user` | `password` | secret | hashed (Symfony auto hasher) | nobody |
| `user` | `pending_email` | yes | no | the user (`/me`), until they confirm it from the link sent there; then it replaces `email` |
| `user` | `roles`, `email_verified_at`, `created_at`, `updated_at` | account data | no | the user; platform staff |
| `user` | `scheduled_deletion_at`, `deletion_self_requested` | account data | no | platform staff |
| `user` | `nickname`, `name_display`, `public_name_display` | yes | no | the user; copied to their player records (see Players) |
| `user` | `photo_audience`, `age_audience`, `sport_audience`, `contact_email_audience` | choices | no | the user; copied to their player records |
| `user` | `gender`, `height_cm`, `dominant_hand`, `spike_reach_cm`, `block_reach_cm` | sporting profile | no | the user; copied to their player records |
| `user` | `birth_date`, `license_number`, `contact_email`, `phone`, `guardian_name`, `guardian_phone` | yes, sensitive | **yes** | the user; copied to their player records. `contact_email` is the address given to the clubs, unrelated to the sign-in `email` |
| `user` | photo (`avatar_id` → `media`, file in `MEDIA_STORAGE_DIR`) | yes, sensitive | **file encrypted** | the user (`GET /me/photo`, never cached); copied to their player records; any signed-in user when `photo_audience` is `public` (`GET /community/people/{id}/photo`, see Community) |
| `refresh_token` | `token_hash`, `family_id`, dates | session data | the token is stored as a SHA-256 hash | nobody (server only) |
| `refresh_token` | `device_label` | device name given by the client | no | nobody yet (planned: list of signed-in devices) |
| `user_token` | `token_hash`, `purpose`, dates | e-mail link tokens (verification, reset, staff invitation, change of sign-in address) | SHA-256 hash | nobody |

Retention: an access token lives 15 minutes (never stored). A refresh token lives 30 days, a session
at most 180 days; used or revoked tokens stay until the end of their session so that a replay is
detected. Expired tokens are deleted by `app:tokens:purge` (to schedule daily).

**Profile copies.** The profile of an account (everything above but the sign-in data) is copied to
its player record in every club where it is a member (`PlayerProfileSync`): when the user changes it,
and when an accepted invitation links a record (the record first fills what the account leaves empty).
A club the user left keeps the last copy it received. The photo is copied as a separate encrypted file
per club.

Deleting an account (by its owner with their password, or by the staff) puts it to sleep for
**30 days**, the one month the GDPR gives to act on an erasure request: its sessions are closed, it
cannot be used, and it disappears from member lists and team coaches, but nothing is erased. The
owner cancels by signing in; a deletion decided by the staff is only cancelled by the staff. After
30 days `app:deletions:purge` (to schedule daily) erases the account with its photo, tokens, memberships and
coach places. What the clubs own stays with them, without the link to the account: player records,
their places in teams and their statistics, authored trainings and exercises (the author link is
removed, and a run keeps no link to the coach who started it).

## Clubs and members

| Table | Field | Personal | Encrypted | Who reads it |
|---|---|---|---|---|
| `club` | name, address, city, state, postal code, country, website, logo (file encrypted) | no (an organisation) | no | members of the club; while `listed_in_directory` is on (the default, administrators may turn it off), any signed-in user through the club search, with the names of its teams and how many teams and members it has (`/directory/clubs`), never a person |
| `club` | `scheduled_deletion_at`, `deletion_requested_by` | — | no | administrators of the club |
| `membership` | user, club, roles (and `admin`), permissions given or taken, `joined_at`, `invited_by`, `ended_at` | yes (who belongs where) | no | the user; active members of the club (names only, never e-mail addresses); platform staff (every club's members, every account's clubs). Kept when the user leaves (history), erased with the account |
| `invitation` | `email` | yes, possibly of someone without an account | no (looked up by address) | administrators of the club; the owner of that confirmed address |
| `invitation` | roles, player, `invited_by`, `expires_at` | — | no | same |
| `join_request` | user, club | yes (who asks to join where) | no | the user; administrators of the club, with the user's names and **confirmed sign-in address**, and an e-mail that says so |
| `join_request` | `message` (written by the user) | possibly | **yes** | same |

Retention: an invitation is deleted as soon as it is accepted, declined or revoked, and after 7 days
by `app:tokens:purge`. A request to join is deleted once answered or withdrawn, when the user joins
the club another way, and with the account or the club. A membership lasts until the member leaves or is removed.

Deleting a club (any administrator) hides it from its members for **30 days**; its administrators
still read it and can restore it, and they are told by e-mail. Then `app:deletions:purge` erases the
club with everything it owns (database cascade) and the files of its photos.

## Players

`player` is the record of a player of a club, with or without an account.

| Field | Personal | Sensitive | Encrypted | Who reads it |
|---|---|---|---|---|
| `first_name`, `last_name`, `nickname` | yes | — | no (searchable) | staff of the club, the player; the other members read `displayName`, the name in the chosen format (initial, nickname…) |
| `name_display`, `public_name_display` | choice of the player | — | no | staff of the club, the player |
| `gender`, `positions` | yes | — | no | members of the club |
| `height_cm`, `dominant_hand`, `spike_reach_cm`, `block_reach_cm` | sporting profile | — | no | staff, the player, and the chosen audience (members of the club by default) |
| `birth_date` | yes | yes | **yes** | staff of the club, the player; the chosen audience reads the **age** only (staff by default) |
| `license_number`, `phone` | yes | yes | **yes** | staff of the club, the player |
| `contact_email` | yes | yes | **yes** | staff of the club, the player, and the chosen audience (staff by default) |
| `guardian_name`, `guardian_phone` (parent of a minor) | yes | yes | **yes** | staff of the club, the player |
| photo (`photo_id` → `media`, file in `MEDIA_STORAGE_DIR`) | yes | yes | **file encrypted** | staff of the club, the player, and the chosen audience (staff by default) (`GET /players/{id}/photo`, never cached) |
| `photo_audience`, `age_audience`, `sport_audience`, `contact_email_audience` | choices of the player | — | no | staff of the club, the player |
| `sign_in_email` (address the player signs in with, given by the staff before an account is linked) | yes | yes | **yes** | staff of the club, the player; the owner of that confirmed address sees only the club's name in their invitations. Cleared when an account is linked, or when that owner declines |
| `sign_in_email_index` | keyed fingerprint of `sign_in_email` (HMAC-SHA256, key derived from `PII_KEY`) | — | not reversible | nobody: only to find the records naming an address |
| `user_id` (linked account) | link | — | no | exposed as `hasAccount` only; set only by an accepted invitation or request to join |
| `profile_review_since` | — | — | no | the player: their record and their profile differ, they choose what to keep (`/me/profile_reviews` shows them both values of each differing field, as they already read their own record) |

**Audiences** (`Privacy/PlayerPrivacy`): staff, team (the players and coaches of a team of the
player), club, public (the club until public pages exist). The player with an account chooses on
their profile; otherwise the coaches of their teams (the most restrictive when there are several);
otherwise the club (`club` and `team` tables: `name_display` and the four `*_audience` columns,
written by the administrators, resp. the staff); otherwise the defaults above. The same name rule
applies to accounts in member lists and team coaches (`UserNormalizer`). Known limit: searching the
player list by name (`?search=`) is open to the members, so a member can still test whether a name
matches a record shown under a nickname.

**Retention.** A record still needed (linked to an account, called up in a game, in an attendance
list) is archived when the staff deletes it, not erased: it leaves the lists and stays readable from
its games and by its player. A former member keeps reading their own record and games. A deleted club
closes after 30 days and is erased, with all its records, once no account is linked to it any more.
Known gap: a person without account cannot yet ask for their archived record to be erased
(anonymisation to come).

Writes: administrators and coaches of the club, until the record is managed by its player (linked to
an account that is a member of the club): the names, the personal fields and the photo are then the
copy of the player's own profile, which only the player changes (`ProfileOwnedByPlayer`, 409 on the
photo); the positions stay the club's. Deletion: administrators; deleting a record deletes its photo
file and its places in teams. Encrypted fields cannot be searched or sorted, and the
uniqueness of a licence number in a club is not enforced.

## Teams, games, trainings, exercises

| Table | Personal content | Who reads it |
|---|---|---|
| `team` | none (name, description, level) | members of the club |
| `team_member` | which player or coach is in which team, jersey number | members of the club (player name and positions, coach name) |
| `game`, `game_set` | authors (`game_user`), opponent's name, free notes, scores | depends on the visibility chosen by its authors: authors only, staff of the club, staff and team (players of the team, players called up), or members of the club. Authors are exposed as identifiers (IRIs) only |
| `game_player`, `game_set_lineup`, `game_set_event`, `game_set_stat_count` | which player was called up (names, jersey number, position played, libero, captain), who started, who came on, who was injured or sanctioned (warning, penalty, expulsion, disqualification), each player's statistics | same readers as the game, and the people its live input is shared with (`game_share`), who read the sheet without notes, authors or visibility. Retention: as long as the game, which administrators or its authors delete; deleting a player record removes their line and statistics and leaves the events without player |
| `game_player`, `game_set_lineup`, `game_set_event`, `game_set_stat_count` (my statistics, comparison) | a player's own games and statistics, in every club, without names | the player (`GET /me/stats`), with the same visibility as each game (a former member up to the day they left). For the comparison (`GET /stats/benchmark`), any signed-in user reads **anonymous** counts per person (games, sets, counts), shuffled, never a name or identifier, never from a private game, and nothing below 10 people |
| `game_share`, `game_share_access` | the account a live input is shared with, who shared it, hashes of the link and of the code chosen, devices that typed the code (`device_label`: browser and system, last use to the minute) | who may record the game. Retention: until the share ends or is deleted, or with its game; a new code or link deletes the devices |
| `training_session`, `training_session_exercise` | authors (`training_session_user`), free notes, label of the original of a copy (title and authors' public names) | its authors; the people, groups and clubs it is shared with (`training_share`); the members of a club that plans it; every user when public. Authors by their public name (`authorDetails`). Retention: as long as its authors keep it; it goes with an account that wrote it alone |
| `exercise`, `exercise_step`, `exercise_element` | authors (`exercise_user`), free text, label of the original of a copy | the same readers as a session, and those who read a session that runs it; a public exercise every user, which the platform moderation may unpublish or delete (logged in the platform log); a public or unlisted exercise anyone given its share link (`share_token`), signed in or not, without its authors |
| `planned_training`, `planned_training_team` | who planned it (`created_by_id`), notes | members of the club. Kept with its runs when the session goes |
| `training_run`, `training_run_entry` | who started the run (`started_by_id`), the coach's notes | staff of the club (administrators, coaches) |

Free text fields (descriptions, notes) may contain anything a coach types: they are not encrypted.

### Attendance of a training run (`training_attendance`)

| Field | Personal | Sensitive | Encrypted | Who reads it |
|---|---|---|---|---|
| `player_id` (record of the club), `team_id`, `status` (present, adapted, not training, excused, absent), `arrived_at`, `left_at` | yes | — | no | staff of the club |
| `guest_name` (someone from outside the club) | yes | — | no | staff of the club |
| `reason_category` (injury, illness, work/school, family, transport, other team, other) | yes | **health data** for injury and illness | **yes** | staff of the club |
| `reason_detail` (free text) | yes | **may be health data** | **yes** | staff of the club |

Players never read runs, not even their own line. Retention: as long as the run, which the staff
deletes (administrators, or the coach who started it); deleting the session deletes its runs, and
deleting a player record keeps the line without the player.

## Notifications

| Table | Field | Personal | Encrypted | Who reads it |
|---|---|---|---|---|
| `notification` | user, type, club, `subject_id`, `read_at` | yes (what happened to whom) | no | the user only (`/me/notifications`) |
| `notification` | `data`: names to show (club, team, opponent, title, the person who asks or joined) | names only, never contact details | no | same |
| `notification` | `in_app`, `email_pending` (shown in the app, waits for the e-mail digest) | no | no | nobody (server bookkeeping) |
| `user` | `notification_settings` (in the app / by e-mail, per type) | a preference | no | the user |
| `user` | `notifications_emailed_at` (last e-mail digest) | no | no | nobody (server bookkeeping) |

Retention: 90 days, read or not (`app:tokens:purge`); with the account or the club. A notification
wanted by e-mail only is not shown in the app and is deleted once mailed. The e-mail digest holds the
same names and links, nothing else.

## Community

What any signed-in user reads of a person outside their clubs (`/community/people`): the **public
name** (`public_name_display`, else `name_display`, else the full name; a search only matches a name
the format shows), the photo **only if** `photo_audience` is `public`, whether the account is private,
and the numbers of followers and follows. Never the names a format hides, an e-mail address, the
clubs or the profile. Unconfirmed accounts and accounts being deleted are not found.

| Table | Field | Personal | Encrypted | Who reads it |
|---|---|---|---|---|
| `user` | `private_account` (null = private for a minor by the birth date, public otherwise) | a preference | no | the user; others only see whether following needs an approval |
| `follow` | follower, followed user or club, `accepted_at` | yes (who follows whom) | no | the follower (`/me/follows`); the person followed (`/me/followers`, `/me/follow_requests`, with the follower's public name); everyone reads the counts |
| `follow` | `note` (why the follower follows, free text) | possibly | **yes** | the follower only |
| `contact` | requester, recipient, `accepted_at` | yes (who is in contact with whom) | no | the two people (`/me/contacts`, `/me/contact_requests`) |
| `contact` | `message` (why the requester asks, free text) | possibly | **yes** | the two people only |
| `user_group`, `group_member` | name and description of a group, its people, their role, who invited them, when they joined | yes (who is in which group) | no | the members of the group; an invited person reads the group's name, description, inviter and size |

Retention: until the follower stops, the person followed removes the follower, or either account (or
the club) is erased (database cascade). Accounts being deleted and clubs being deleted or closed are
left out of the lists and counts in the meantime.

**Posts** (`post`, `post_media`): who reads one is decided by its visibility (`Community/PostAccess`):
public (anyone signed in; a private account's only to its accepted followers), followers (of the
person, or of the club and its members for a post in its name), club (its active members). Its author
always reads it.

| Table | Field | Personal | Encrypted | Who reads it |
|---|---|---|---|---|
| `post` | `author_id` (shown by its public name, hidden for a post in the name of a club), `club_id`, `as_club`, `visibility`, `language`, `edited_at`, `exercise_id` | yes (who said what) | no | the readers of the post |
| `post` | `body` (free text) | possibly | no (published content, read by its audience) | the readers of the post |
| `post_media` → `media` | photos (re-encoded, no metadata, 1600 px at most, file encrypted) | possibly (people on the photo) | **file encrypted** | the readers of the post, through a signed link valid one to two hours (`/public/media/{id}`, no token, cached by the reader's browser only) |
| `post_media` → `media` (+ `poster_id`) | videos as recorded (100 MB at most) without their place and device metadata (MP4 / MOV boxes blanked), and their first image | possibly (people filmed) | **file encrypted by chunks** | the readers of the post, through a signed link, by parts (Range) |

| `reaction` | user, post or comment, type of reaction | yes (who reacts how to what) | no | the counts by type: the readers of the post; the user (their own, `/me/liked_posts`); the author is told by a notification |
| `comment` | author (public name), post, `body` (free text, may mention people), `edited_at` | yes | no | the readers of the post |

| `report` | reporter, post or comment, reason | yes (who reported what) | no | nobody but the server: the moderation reads the reasons, never who reported |
| `report` | `message` (free text for the moderation) | possibly | **yes** | the platform moderation |
| `link_preview` | url, title, description, site name of the first web link of a post; its image (stored like a photo) | the link a person chose to share | no (published with the post) | the readers of the post |

Mentions are stored as identifiers in the text (`@{user:<id>}`) and named at read time by the public
name: a hidden name never ends up in a text. Reading a link preview, the server calls the site of the
link once, with no information about the user (a fixed user agent, no cookie); readers never call it.

Retention: until its author deletes the post (or an administrator of the club it speaks for); the post
of an exercise until the exercise stops being public. Likes and comments go with the post or with the
account; a comment can also be deleted by its author or the author of the post. A report goes when the
moderation dismisses it, with its content, or with the account of the reporter; the moderation also
removes a reported content (its author is told, the act is logged without the content). A photo sent but never put in a post is deleted
after a day (`app:tokens:purge`). Erasing an account deletes its posts and their files; erasing a club,
the posts that belong to it and their files.

## Platform support access

The platform staff (moderators and above) reads every club as its administrators would, private
games and sessions included, to answer a request or handle a report; platform administrators also
change it (`Enum/ClubSupport`). Every change made that way is logged:

| Table | Field | Personal | Encrypted | Who reads it |
|---|---|---|---|---|
| `support_action` | `actor_id` (member of the staff), `method`, `path` (identifiers only, no query string, no body), `operation`, `created_at` | yes (who acted) | no | platform staff (`/admin/clubs/{id}/support_actions`; without club, the moderation of the community: `/admin/platform_actions`) |

Retention: as long as the club (database cascade); the actor link is removed when their account is
erased.

## Files

`media`: content type, size, opaque storage key, club, uploader. The file name of the upload is not
kept (always `photo.jpg`). Files are re-encoded (no metadata), encrypted, stored outside the public
directory and served only after an access check, or by a signed link given to the readers of a post.
Erasing a club deletes the files of its media (a photo of a post takes the club of its post).

## Planned, not built

- Sharing player information by private link or making it public, with the statistics: the link
  will carry a revocable token checked by the server, and will never expose the encrypted fields.
- A list of the signed-in devices of a user (`device_label`).
- Rotation of `PII_KEY` (the `v1:` prefix of every encrypted value leaves room for it).
