Write the sign-in diagnosis contract (NK-WP-0051-T01).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1041694@bnt-lap001
Assistant-Session: 7af0bb68-ac4a-4ce3-8639-24ddd84c0b52

docs/sign-in-diagnosis.md

@@ -0,0 +1,67 @@
+# Sign-in diagnosis contract
+
+Status: accepted contract for NK-WP-0051. This document is the only copy of
+the field list; other repositories link here instead of restating it.
+
+## Why
+
+MASON-WP-0011 took a day because three facts about one login were split
+across the account site, Authelia, and OpenBao. OpenBao said only
+`claim "groups" does not match any associated bound claim values`. Every
+surface below shows the same three facts, named the same way, for **this
+authorization request and no earlier one**.
+
+## Fields
+
+| Field | Meaning | Source |
+| --- | --- | --- |
+| `uid` | The uid KeyCape resolved for this request | Authelia `preferred_username` (fallback `sub`), as KeyCape's Authelia adapter resolves it |
+| `groups` | Directory group display names, sorted | That uid's LLDAP `memberOf`, reduced to display names |
+| `assurance` | `aal2` if this request verified a one-time code, else `aal1` | KeyCape's assurance decision for this request (`MFAVerified`) |
+| `client_id` | The relying party the login returns to | The authorization request |
+| `openbao_error` | OpenBao's error text, verbatim | ops-mason receipt only |
+
+`assurance` is per request. A reused session that was `aal2` earlier is
+`aal1` here unless this request asked for and verified the one-time code.
+Enrolling a factor is not `aal2`.
+
+## Never shown or logged
+
+Tokens (ID, access, refresh, OpenBao), authorization codes, email
+addresses, one-time passwords or seeds, passwords, session cookies, and raw
+`memberOf` DNs. Group display names and the uid are the diagnosis; they are
+not secret.
+
+## Where each field appears
+
+| Surface | Fields | Owner | Task |
+| --- | --- | --- | --- |
+| KeyCape page before the redirect to the application. Opt-in per client (registration flag, default off), enabled first for the OpenBao client. One action: continue, plus how to sign in as someone else | `uid`, `groups`, `assurance`, `client_id` | key-cape | NK-WP-0051-T02 |
+| The existing KeyCape auth log line | `client_id`, `uid`, `assurance` | key-cape | NK-WP-0051-T02 |
+| Account site `users.coulomb.social`: account-site uid and current Authelia uid on two separate lines. Authelia's cookie domain stays `coulomb.social` | `uid` (twice, labelled by session) | user-engine | NK-WP-0051-T03 |
+| `lldap_admin.py groups --user <uid>` (read-only preview) | `uid`, `groups` | net-kingdom | NK-WP-0051-T04 |
+| ops-mason verifier receipt for an attended `bao login` | `uid`, `openbao_error` (and `assurance` when known) | ops-mason | NK-WP-0051-T06 |
+
+Matching `groups` to an OpenBao role stays a metadata read in ops-mason.
+
+## Negative-login fixture
+
+Fixture uid: `signin-probe-negative`.
+
+- not a member of `reuse-surface-hub-writers`
+- not a platform admin (`net-kingdom-admins`)
+- holds a one-time password (enrolled by the founder in NK-WP-0051-T05 at
+  `https://pink-account.coulomb.social/`, realm `coulomb`)
+
+The user is never created or described with credentials in git. A
+successful diagnosis of this fixture shows `uid=signin-probe-negative`,
+groups without `reuse-surface-hub-writers`, `assurance=aal2`, and then the
+OpenBao groups refusal.
+
+## Evidence
+
+| Item | Value |
+| --- | --- |
+| key-cape image digest with the page and log line | _pending NK-WP-0051-T02_ |
+| user-engine change | _pending NK-WP-0051-T03_ |
+| ops-mason / railiance-platform acceptance | _pending NK-WP-0051-T06_ |