ping-mee-self-service-platform/_bmad-output/specs/spec-ping-mee-self-service-platform/SPEC.md

---
id: SPEC-ping-mee-self-service-platform
companions:
  - ../../prds/prd-ping-mee-self-service-platform-2026-10-15/prd.md
  - ../../prds/prd-ping-mee-self-service-platform-2026-10-15/addendum.md
  - ../../architecture/architecture-ping-mee-self-service-platform-2026-10-15/ARCHITECTURE-SPINE.md
  - ../../ux-designs/ux-ping-mee-self-service-platform-2026-10-15/DESIGN.md
  - ../../ux-designs/ux-ping-mee-self-service-platform-2026-10-15/EXPERIENCE.md
sources:
  - ../../briefs/brief-ping-mee-self-service-platform-2026-10-15/brief.md
  - ../../briefs/brief-ping-mee-self-service-platform-2026-10-15/addendum.md
---

> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability — consult them only if you need narrative rationale or prose color this contract intentionally omits.

# ping-mee Self-Service Portal

## Why

The ping-mee homelab, used by about ten family members and friends, keeps all accounts in one Active Directory. Today every change — a password, a name, a phone number, a picture — goes through the admin by hand, and there is no single place to announce downtime. This is a pain to solve for the admin and the users, and it should be built to a standard that lets it run safely on the internet and later be deployed in other Active Directory homelabs.

## Capabilities

*Each capability's requirement-level detail (FR-N with testable consequences) is in the PRD companion; the number in brackets is the PRD range.*

- **CAP-1** [FR-1..FR-4]
  - **intent:** A person with an AD account signs in through the identity provider and gets only the access their AD group membership allows.
  - **success:** A user in the configured OU signs in via OIDC; a user outside the Publisher and Admin groups cannot reach those pages by direct address; sessions end after 1 hour idle or 4 hours total; a disabled or locked AD account loses access at its next request; repeated sensitive requests are refused before any AD call.
- **CAP-2** [FR-5..FR-7]
  - **intent:** A signed-in user changes their own password.
  - **success:** With the correct current password and a policy-conforming new one, the AD password changes over LDAPS, the user's other sessions end and a confirmation e-mail is sent; a policy rejection is shown in plain words with no change; five wrong current-password attempts block further tries for the configured pause.
- **CAP-3** [FR-8..FR-11]
  - **intent:** A signed-in user edits their own first name, last name, display name, e-mail and telephone numbers.
  - **success:** Saved values appear in the matching AD attributes; injection strings change nothing else; an e-mail change applies only after the current password, a click on a confirmation page from the new address, and sends the old address a notice with a 24-hour undo that ends the user's sessions and notifies the Admin.
- **CAP-4** [FR-12..FR-15]
  - **intent:** A signed-in user sets or removes their profile picture.
  - **success:** A JPEG, PNG, HEIC or WebP file up to 10 MB is cropped, re-encoded and written as `<sAMAccountName>.jpg` to the source folder; the page shows Pending until `processed/<name>.md5` matches the written file; other formats and larger files are refused with a reason.
- **CAP-5** [FR-16..FR-19]
  - **intent:** A Publisher announces planned changes and downtime.
  - **success:** A Publisher writes a titled announcement in a rich-text editor with an always-set severity and an optional downtime window, expiry and publish time; it appears as a banner and in a list for signed-in users, can be edited, withdrawn, or re-sent on request; script content in the body never runs.
- **CAP-6** [FR-20, FR-21]
  - **intent:** Users hear about announcements by e-mail unless they opted out.
  - **success:** On publish every user in the OU with a valid e-mail address, minus explicit opt-outs, receives the e-mail through the configured SMTP server; users who opted out receive nothing; the Publisher sees counts and reasons beforehand; failures are listed for the Admin.
- **CAP-7** [FR-22..FR-25, FR-32]
  - **intent:** An Admin manages how the portal looks and behaves and can see whether it is healthy.
  - **success:** Only Admin-group members reach the Admin pages; the accent colour is checked for contrast in both themes with a warning but allowed; runtime settings change without restart; the status page shows backup age, failed e-mails and job runs; the audit log is readable.
- **CAP-8** [FR-28]
  - **intent:** The Admin can reconstruct who changed what.
  - **success:** Every password change, profile change, e-mail change step, picture action, announcement action, settings change and throttled or failed attempt produces an entry with who, what, when and IP, kept 12 months, holding no password, token or picture content.
- **CAP-9** [FR-29..FR-31]
  - **intent:** Each user sees a clear landing page and sets how the portal looks and speaks on their own device.
  - **success:** The dashboard shows active announcements and an account card with the password date; theme, language and German form of address are chosen from the avatar menu and stored on the device; German and English work, with formal and informal German; the portal is usable on desktop and phone and meets WCAG 2.1 AA.
- **CAP-10** [FR-26, FR-27]
  - **intent:** The portal runs unchanged in any environment from configuration alone.
  - **success:** One Docker image starts only when all required environment variables are valid; no image content names ping-mee, a domain, OU, group, IP or path; secrets appear in no log or UI; a health check works without AD; consistent database backup files appear in the backup folder on schedule.

## Constraints

- Architecture is binding as written in `ARCHITECTURE-SPINE.md` (rules AD-1..AD-19): Django modular monolith with one owner per external system.
- One container, one worker, SQLite on a volume; the portal writes its own consistent backups, because the host copy job copies directories.
- AD is reached only over LDAPS with a service account limited to a configurable OU and fixed read and write attribute lists; `cn` and `name` are never edited.
- The existing PowerShell sync, logon and registry scripts stay unchanged; the portal only writes `<sAMAccountName>.jpg` to the source folder and reads `<sAMAccountName>.md5` from the processed folder.
- The portal is internet-facing: no injection, no cross-user access, throttling before any AD call, passwords never stored or logged, strict content-security policy with no inline script and no external fonts, scripts or CDNs.
- Expired, forgotten or must-change passwords are never handled by the portal; the Admin resets them in AD.
- Precedence when companions differ: behavior follows the PRD, architecture follows the spine, look follows `DESIGN.md`, screen behavior follows `EXPERIENCE.md`.

## Non-goals

- No forgotten-password or expired-password flow.
- No admin console for other users' data: Admins cannot edit another user's profile, picture or password.
- No renaming of AD objects (`cn`, `name`).
- No multi-domain support.
- No replacement of the PowerShell scripts or the sync task.
- No public status or announcement page; signed-out visitors see nothing.
- No SVG uploads.
- No alerting beyond the Admin status page; no staging environment (a test OU is used instead).
- No identity-provider features of its own: sign-in and multi-factor stay with authentik.

## Success signal

A family member with no help from the admin changes their password, name, phone number and picture in the portal, while the admin publishes a scheduled downtime announcement that every opted-in user receives by e-mail and sees as a banner, and an attacker's injection, cross-user and brute-force attempts against the internet-facing portal all fail and are recorded.

## Assumptions

- Default values are placeholders to confirm at build: failed-attempt limit and pause (5, 15 minutes), confirmation link lifetime (1 hour), picture output (512×512 JPEG), Pending timeout, throttle limits per endpoint, backup retention, and the "backup too old" age (26 hours).
- E-mails use the portal-wide default form of address, because a per-device choice cannot reach server-sent mail.
- The default accent colour is the Fluent 2 default blue (`#0F6CBD`) and needs verifying against the component package.
- Active Directory attribute names for the password policy (`minPwdLength`, `pwdProperties`, `pwdHistoryLength`, `msDS-ResultantPSO`) need verifying in the test OU.
- Users depend on authentik being available for sign-in; no fallback.
- Data of users removed from AD is deleted by a nightly reconciliation; audit entries stay until retention ends.
- Sample personas and journeys in the PRD and UX documents are illustrative.

## Open Questions

- What are the exact retry count and the IONOS sending limits for announcement e-mail?
- How is a restore from the portal's backup files tested before it is needed?
- Does sign-out also end the authentik session?
- Which rich-text editor library is used, and how are the front-end assets built into the image?
- Where does the Docker image live: a registry, or built on the host?
- Is the early-clearing of Pending after a failed AD write by the sync script an acceptable limitation (PRD Q-9; accepted in the spine, confirm at first use)?