Historic Atlas — Your corner of the atlas
The original prompt, shown in full as plain text.
Prompt
# SPEC: Users
Status: draft. Part of [SPEC.md](../SPEC.md).
## Purpose
Define the application's own record of a person, so that data of the
application, starting with preferences, can be attached to them.
## Requirements
- Keycloak stays the owner of accounts, credentials and roles
([SPEC-auth.md](SPEC-auth.md)); the application keeps a `User` for what
Keycloak does not hold.
- A `User` is created at the first successful login and found again at every
later one.
- A user reads their own record and changes their own preferences, nobody
else's.
## Data model
The tables are in the [data model diagram](datamodel-diagram.md).
**User**
| Field | Type | Notes |
|-------|------|-------|
| `id` | UUID | Assigned by the system, never reused. |
| `kc_subject` | text | The `sub` claim of the realm, unique. It is the only link to Keycloak; users are never matched by email or name, which can change. |
| `kc_username`, `kc_email`, `kc_first_name`, `kc_last_name`, `kc_display_name` | text | Imported from Keycloak, see below. Optional, as the token may lack a claim. |
| `preferences` | JSON object | Owned by the application, see below. Defaults to `{}`. |
| `created_at`, `last_login_at` | timestamp (UTC) | Set by the system. |
**Avatar** (at most one per user, see "Avatar" below)
| Field | Type | Notes |
|-------|------|-------|
| `user_id` | UUID | The user, primary key. The row goes with the user. |
| `source` | text | `upload` or `gravatar`. |
| `content_type` | text | Always `image/png`. |
| `data` | bytea | The image after processing, 256 x 256 pixels. |
| `updated_at` | timestamp (UTC) | Set by the system at every change. |
## Decisions
- **Column names:** the columns that hold what is fetched from Keycloak carry
the prefix `kc_`, so they are told apart from the application's own
columns; the API shows them without it (`username`, `email`, ...). They
were renamed from the plain names by migration `V3`.
- **Backend module:** `user` ([SPEC-backend.md](SPEC-backend.md)). The login
in `auth` announces itself as an application event, a type in the API of
`auth`, and `user` listens to it; `auth` has no reference to `user`.
- **Creation:** the first login finds no user for the `kc_subject` and creates
one. The creation is idempotent: two simultaneous first logins end with one
user (unique constraint, then a read), never with an error for the person.
- **Imported properties:** the profile claims of the ID token (`preferred_username`,
`email`, `given_name`, `family_name`, `name`) are copied at every login, so
they follow changes made in Keycloak. Keycloak is the source of truth: the
application never edits them and the API offers no way to change them. The
stored copy is personal data: only claims that a feature uses are imported,
so a claim is dropped from the list when nothing uses it. Roles are not
copied; they stay in the token.
- **Failure at login:** a failure to store the user is logged and does not
block the login. The user is then created or refreshed at the next login,
and `GET /api/users/me` creates a missing user on demand.
- **Preferences:** stored as one JSON object, so a preference is added
without a schema change. The first is `appearance`: `light`, `dark` or
`system` (default, follow the browser). Unknown keys and invalid values are
rejected. Applying the appearance is a task of the frontend. The language
is not stored until a feature needs it.
- **API:** under `/api/users/`, in the OpenAPI document.
- `GET /api/users/me` answers the record of the logged-in user: `id`,
`username`, `email`, `firstName`, `lastName`, `displayName`,
`preferences`, without the subject.
- `PATCH /api/users/me` takes `{"preferences": {...}}`, merges the given
keys into the stored preferences and answers the record. It requires the
CSRF token.
- There is no endpoint by id and none that lists users. `GET /api/auth/me`
keeps its meaning.
- **Avatar:** a user has one image, shown instead of their initials. It is
set in one of two ways, both stored the same way, in the database next to
the user (a table of its own, so reading the user does not read the image;
the nightly dumps and the restore cover it):
- *Upload:* a PNG or JPEG of at most 2 MB and 4096 x 4096 pixels. The
backend decodes it itself and does not trust the declared type (SVG, GIF
and everything else are refused), cuts the largest centred square, scales
it to 256 x 256 and stores it as PNG, which drops metadata such as
location and camera data.
- *Gravatar:* on the user's request only, the backend fetches the Gravatar
of the user's email address once (`https://gravatar.com/avatar/<SHA-256 of
the trimmed, lower-case email>`, size 256, "no default image"; a fixed
host, a timeout of five seconds, at most 1 MB, redirects only within the
host) and stores it through the same processing as an upload, as a copy.
Browsers never contact Gravatar, and nothing is sent without that request.
The copy does not follow later changes at Gravatar until the user asks
again. An address without a Gravatar, or a user without an email, is
answered with an error that says so.
A new avatar replaces the old one; the user can remove theirs. Avatars are
personal data: they are part of the privacy statement
([AVARC-9](../tasks/TASK-licensing-decision.md)), which names Gravatar as
the one third party contacted, and only on request.
- **Avatar API:** under `/api/users/me/avatar`, in the OpenAPI document; the
writing calls require the CSRF token.
- `GET` answers the image (`image/png`, `X-Content-Type-Options: nosniff`,
an `ETag` and `Cache-Control: private`), or 404 without an avatar.
- `PUT` takes the file as `multipart/form-data` (part `file`) and answers
the record of the user; 400 for a file that is not an accepted image,
413 for one that is too large.
- `POST /gravatar` fetches the Gravatar as above and answers the record;
404 when the address has none, 409 for a user without an email, 502 when
Gravatar does not answer.
- `DELETE` removes the avatar.
- `GET /api/users/me` gains `avatar`: `null` or `{"source": ..., "updatedAt":
...}`, so the frontend can build the address with `updatedAt` as the
cache-busting value. There is still no endpoint by id: an avatar is shown
to its own user only, until a feature shows other users (for example the
editor of a location), which then specifies who may see it.
- **Deleted accounts:** an account deleted in Keycloak leaves its user
record behind and nothing removes it. The `kc_subject` is never reused, so
`created_by` and `updated_by` of locations
([SPEC-locations.md](SPEC-locations.md)) keep their meaning. Removing the
personal data of deleted accounts is added when a feature needs it.