@masmarino/gabarit 2.0.0 → 2.1.1

package/auth/README.md

@@ -0,0 +1,155 @@
+# Auth kit
+
+The public sign-in pages and the account's second-factor settings, as components an application uses
+as they are: login (with the MFA challenge), free registration, invitation activation, the new
+password after an administrator's reset, the mandatory
+first MFA enrolment (authenticator app or passkey, then backup codes), and the account cards for the
+authenticator app and the passkeys. Every application that uses them gets the same behaviour, the same
+accessibility and the same look, by construction.
+
+The kit is **router-agnostic** (it never imports `@angular/router`: it emits outputs and shows the
+links the application projects), **backend-agnostic** (it never talks HTTP: every call goes through a
+port the application implements), **storage-agnostic** (it never touches `localStorage`: sessions are
+the port's business) and **locale-agnostic** (every string is a label with an English default).
+
+| Component                                                 | Selector               | Port                                     |
+| --------------------------------------------------------- | ---------------------- | ---------------------------------------- |
+| [`AuthLogin`](../auth-login/README.md)                          | `gbt-auth-login`       | `AUTH_PORT`                              |
+| [`AuthRegister`](../auth-register/README.md)                    | `gbt-auth-register`    | `AUTH_PORT`                              |
+| [`AuthActivate`](../auth-activate/README.md)                    | `gbt-auth-activate`    | `AUTH_PORT`                              |
+| [`AuthResetPassword`](../auth-reset-password/README.md)         | `gbt-auth-reset-password` | `AUTH_PORT`                           |
+| [`MfaEnrollment`](../mfa-enrollment/README.md)             | `gbt-mfa-enrollment`   | `AUTH_PORT`                              |
+| [`MfaSettings`](../mfa-settings/README.md)                 | `gbt-mfa-settings`     | `MFA_PORT`                               |
+| [`PasskeySettings`](../passkey-settings/README.md)         | `gbt-passkey-settings` | `MFA_PORT` (and `AUTH_PORT` if provided) |
+| [`AuthPanel`](auth-panel/README.md)                     | `gbt-auth-panel`       | —                                        |
+| [`AuthFooter`, `AuthFooterLink`](auth-footer/README.md) | `gbt-auth-footer`      | —                                        |
+| [`TotpQr`](../mfa-enrollment/totp-qr/README.md)                           | `gbt-totp-qr`          | — (`TOTP_QR_RENDERER`)                   |
+| [`BackupCodes`](../mfa-enrollment/backup-codes/README.md)                 | `gbt-backup-codes`     | —                                        |
+
+## Wiring
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useExisting: AuthService }, // your service implements AuthPort
+  { provide: MFA_PORT, useExisting: MfaService }, // your service implements MfaPort
+  {
+    provide: TOTP_QR_RENDERER, // Gabarit ships no QR encoder: bring one, loaded lazily
+    useValue: (text: string, options: TotpQrRenderOptions) =>
+      import('qrcode').then((qr) => qr.toDataURL(text, options)),
+  },
+  provideAuthLabels(MY_AUTH_LABELS), // optional: localise the whole kit once
+]
+```
+
+> **Security: `TOTP_QR_RENDERER` receives the user's TOTP secret.** It is called with the full
+> `otpauth://…?secret=…` URL, raw secret included. The renderer **must encode locally**, in the
+> browser (a bundled library such as `qrcode`, as above): **no network call, never a hosted or
+> third-party QR service** (a `https://…?data=otpauth…` image would hand every user's second factor
+> to that service and its access logs). It **must not log** the text, nor send it to analytics or
+> error reports. See [TotpQr](../mfa-enrollment/totp-qr/README.md).
+
+```html
+<!-- login.page.html: a thin wrapper, routed at /login -->
+<gbt-auth-login (loggedIn)="router.navigateByUrl('/home')">
+  <img auth-logo src="logo.svg" alt="Acme" width="480" height="120" />
+  <a gbtButton variant="link" gbtAuthFooterLink routerLink="/register">Create an account</a>
+</gbt-auth-login>
+```
+
+Every page takes the application's logo in its `[auth-logo]` slot (an `img`, a `picture` or an
+`svg`) and the link of its footer in `[gbtAuthFooterLink]` (an `a[gbtButton]` in its `link` variant,
+carrying the application's `routerLink` or `href`). A page without a projected footer link shows no
+footer.
+
+**`gbt-auth-register`, `gbt-auth-activate` and `gbt-auth-reset-password` also emit `(signIn)`**, from
+their own terminal states (registration closed, account created, activation succeeded, password
+changed, dead link), where "Sign in" is a button
+rather than the projected link. That output is in addition to the projected `[gbtAuthFooterLink]`,
+not instead of it: **wire both** (`(signIn)="router.navigateByUrl('/login')"` and the footer link)
+for every path to reach the sign-in page.
+
+## The `AuthPort` contract
+
+- **Sessions.** `login`, `register`, `verifyMfa` and `finishPasskeyChallenge` store the session they
+  obtain, when there is one (`LoginResponse.token` not null), then the page emits its success output.
+  `confirmTotp` and `finishPasskeySetup` must **not** store theirs: the enrolment holds the session
+  back until the user has acknowledged the backup codes (shown once), then the page hands it to
+  `setToken(token)` and emits.
+- **MFA.** A `LoginResponse` with `token: null` and an `mfaToken` sends the user to the challenge
+  (`mfaHasTotp`, `mfaHasPasskey` say what they can use) or, with `mfaSetupRequired`, to the mandatory
+  enrolment.
+- **Configuration.** `authConfig()` is read once by the login page (a failed read hides the
+  registration link; passkeys stay "unknown", which does not block them) and by the registration page
+  (a failed read shows the form: the server has the last word).
+
+## The error contract
+
+A failed port call errors with `{ status, error }`: the HTTP status and the response body, the shape
+of Angular's `HttpErrorResponse` (an adapter on `HttpClient` passes its errors through untouched). A
+browser's WebAuthn error (a `DOMException`, no `status`) is told apart from a server answer by that
+shape. The kit words every failure itself; the server's text is never shown. What it recognises
+(`AUTH_PORT_ERROR_BODIES` holds the strings):
+
+| Call                                  | Answer                                                                                                             | Read as                                                                      |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `login`                               | 401                                                                                                                | wrong username or password (any other failure: "sign-in failed")             |
+| any                                   | 429                                                                                                                | too many attempts                                                            |
+| MFA calls with an `mfaToken`          | 401 `invalid or expired token`                                                                                     | the sign-in expired: back to the credentials                                 |
+| `verifyMfa`, `finishPasskeyChallenge` | 401 (any other body)                                                                                               | wrong code / passkey refused                                                 |
+| `confirmTotp`, `confirm`              | 400 `invalid code`                                                                                                 | wrong code                                                                   |
+| enrolment calls                       | 400 `MFA is already set up`                                                                                        | the account got a factor meanwhile: back to the credentials                  |
+| passkey calls                         | 503                                                                                                                | passkeys not available on this server                                        |
+| `finishPasskeySetup`, registration    | 409                                                                                                                | this key is already registered                                               |
+| password-gated `MfaPort` calls        | 400 `current password is incorrect` (exactly)                                                                      | wrong password (never a 401, which an interceptor would take for a sign-out) |
+| `startPasskeyRegistration`/`finish…`  | 400 `too many passkeys`                                                                                            | the account holds the most passkeys the server keeps                         |
+| `deletePasskey`                       | 404                                                                                                                | already gone: removed from the list, nobody signed out                       |
+| `register`                            | 400 `registration is disabled`                                                                                     | the closed state                                                             |
+| `register`                            | 400 `username is reserved` / `username …` / `email is not a valid address` / `password must be at least …` / other | the field concerned, else "check the fields"                                 |
+| `register`                            | 409 `email already in use` / other 409                                                                             | address taken / name taken                                                   |
+| `activate`, `resetPassword`           | 400 `password must be at least …` / other 400                                                                      | weak password (the link still works) / dead link                             |
+
+An adapter for a backend that words these differently maps its answers onto them with `catchError`.
+
+## Session revocation
+
+`MfaPort.disable` and `MfaPort.deletePasskey` revoke the caller's own session on the server (MFA
+being mandatory, removing a factor signs every device out). The cards then emit `sessionRevoked`:
+the application must discard its local session and go to its sign-in page. As a safety net, the card
+that revoked the session also turns inert ("You have been signed out", its `signedOut` label, and no
+action left), so an unbound output never leaves a live card acting on a dead session; it cannot clear
+the application's stored session, though: binding `sessionRevoked` stays mandatory.
+
+## Activation and password-reset links
+
+The mail should carry the token in the URL fragment (`/activate#token=…`,
+`/reset-password#token=…`), which no server ever sees. The application's wrapper reads it once with
+`activationToken(fragment, query)`, removes it from the address bar and history
+(`navigateByUrl('/activate', { replaceUrl: true })`), and hands it to the `token` input of
+`gbt-auth-activate` or `gbt-auth-reset-password`.
+
+**The `token` input must be a one-time snapshot of the URL, never a value that reactively follows the
+URL (e.g. a signal derived from `route.fragment`): the component resets when it changes.** Scrubbing
+the URL would otherwise turn the token into `null` and flip the page to the dead-link view, even over
+its success view.
+
+## Labels
+
+Each component has a `labels` input (a partial object) over `provideAuthLabels({ … })` over its
+English defaults (`DEFAULT_LOGIN_LABELS`, …); nested pieces (`gbt-mfa-enrollment` inside the login
+page, `gbt-totp-qr` and `gbt-backup-codes` inside the enrolment and the settings) read the provided
+labels, so an application localises the whole kit in one place. Interpolated strings are functions
+(`step(current, total)`, `codesLeft(count)`, `passkeyAdded(name)`…).
+
+## The account cards together
+
+`gbt-mfa-settings` and `gbt-passkey-settings` are meant to sit side by side. They share
+`MfaSettingsState` (root-provided; provide it on a page to scope it): the factors as last read or
+changed by either card, so the app becomes optional as soon as a passkey is added and deleting the
+only key is flagged as removing the last factor; and which card owns the open form, so a view never
+shows two password prompts (two primary buttons) at once.
+
+## Theming
+
+`--gbt-auth-panel-logo-width` (15rem) sizes the logo; `--gbt-auth-panel-logo-offset` (0) pulls it
+up when the artwork has a transparent margin above its drawing.

package/auth-activate/README.md

@@ -0,0 +1,119 @@
+# AuthActivate
+
+The activation page of the auth kit: where the link of an invitation mail lands, outside the app shell,
+in the sign-in panel ([`gbt-auth-panel`](../auth/auth-panel/auth-panel.ts)). The invited user chooses a
+password; no session comes out of it: they sign in afterwards and are taken through the mandatory MFA
+enrolment like everybody. It never talks HTTP, never reads the URL and never navigates: the backend is
+the application's `AUTH_PORT`, the token is an input, and the page tells the application where to go
+through its outputs.
+
+**Selector**: `gbt-auth-activate`
+
+## Views
+
+| View    | What shows                                                                                                                                                                |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| form    | A token was given: "Activate your account", New password (with its hint), Confirm the password, one primary "Activate my account", then the projected sign-in link.       |
+| success | The server accepted: "Your account is activated", what comes next, one "Sign in" button.                                                                                  |
+| invalid | No token (`null` or `''`), or the server refused it (unknown, expired or used): an error-toned state, "This link does not work", ask for a new invitation, one "Sign in". |
+
+## Inputs
+
+| Input               | Type                      | Default                   | Role                                                                                                                                                                                               |
+| ------------------- | ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token`             | `string \| null`          | `null`                    | The invitation's token, as the application read it from its URL with `activationToken(fragment, query)`. `null` (or `''`) is the dead link, without any request. A new value starts the page over. |
+| `labels`            | `Partial<ActivateLabels>` | `{}`                      | Strings to change, over `provideAuthLabels({ activate })` and the English defaults (`DEFAULT_ACTIVATE_LABELS`).                                                                                    |
+| `minPasswordLength` | `number`                  | `MIN_PASSWORD_LENGTH` (8) | The server's minimum password length, checked before the round trip; also worded in the hint and the errors.                                                                                       |
+| `chooseUsername`    | `boolean`                 | `false`                   | For servers where the administrator invites by e-mail only: a Username field comes first, and the invitee's choice is sent as `activate(token, password, username)`.                             |
+| `usernamePattern`   | `RegExp`                  | `USERNAME_PATTERN`        | The server's username rule, checked before the round trip when `chooseUsername` is on.                                                                                                             |
+
+## Outputs
+
+| Output      | Payload | Role                                                                             |
+| ----------- | ------- | -------------------------------------------------------------------------------- |
+| `activated` | `void`  | The server accepted the password: the success view shows. No session was opened. |
+| `signIn`    | `void`  | "Sign in" was pressed in the success or dead-link view: go to the sign-in page.  |
+
+## Slots
+
+| Selector              | Role                                                                                                                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[auth-logo]`         | The application's logo (an `img`, `picture` or `svg`), on top of the panel. Optional.                                                                                         |
+| `[auth-backdrop]` | What is drawn on the graphite page, behind the panel: `gbt-git-field`, the family's animated commit graph (`@masmarino/gabarit/git-field`). Optional. |
+| `[gbtAuthFooterLink]` | The link to the sign-in page, under the form after "Is your account already active?". An `a gbtButton variant="link"` carrying `routerLink` or `href`. No footer when absent. |
+
+## Behaviour
+
+- **The token.** The page sends it with the password (`activate(token, password)`) and never renders it
+  (not in the markup, not in a field). Once spent (success) or refused (a 400 other than a weak password),
+  it is dropped: the page does not send it again until a new `token` arrives.
+- **The application's part** (it owns the URL): put the token in the link's **fragment**
+  (`/activate#token=…`) so that no server, proxy or access log ever sees it; read it once with
+  `activationToken(route.snapshot.fragment, route.snapshot.queryParamMap.get('token'))` (the query is only a
+  fallback for older links; a token not shaped like the server's is `null`); then remove it (and any other
+  parameter) from the address bar and the history entry, e.g.
+  `router.navigateByUrl('/activate', { replaceUrl: true })` after the first render, so it does not linger in
+  a screenshot or a shared tab.
+- **The `token` input must be a one-time snapshot of the URL, never a value that reactively follows the
+  URL (e.g. a signal derived from `route.fragment`): the component resets when it changes.** Scrubbing the
+  URL as above would otherwise turn the token into `null` and flip the page to the dead-link view, even over
+  its success view. Read it into a plain field, as in the example below.
+- **`chooseUsername`.** The intro becomes `introWithUsername`, the Username field (with `usernameHint`) comes
+  before the passwords and takes the first focus, and it is checked first (`usernameEmpty`,
+  `usernameInvalid`). The value is sent trimmed; the server keeps the final say: a 400 `username is reserved`
+  (`usernameReserved`), another 400 starting with `username ` (`usernameInvalid`) or a 409
+  (`usernameTaken`) keeps the form, in an alert, the focus in the Username field.
+- **`minPasswordLength` must mirror the server's own rule.** It only spares a round trip: the server stays
+  the authority, and a looser value only moves the refusal to the server's answer.
+- **Checks before the request.** Nothing is said while typing; after a first attempt the password rule and
+  the confirmation ("Confirm your password", "The passwords do not match") show under their fields, the
+  focus moves to the first wrong one, and the checks stay live.
+- **Failures** are worded from the labels, in an alert, the focus back in the password field: a weak-password
+  400 keeps the form (the link is still good), a 429 says to wait, anything else (5xx, network) says the
+  activation failed and the same token can be retried. Any other 400 (but the username ones, with
+  `chooseUsername`) is the dead link.
+- **Focus**: the form starts in the new-password field; the success and dead-link views move the focus to
+  their `h1` (focusable by script, not a tab stop). The passwords are emptied when the server accepted or
+  refused the link.
+
+## Example
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useClass: HttpAuthPort }, // your adapter over HttpClient
+  provideAuthLabels({ activate: { signInPrompt: 'Already signed up?' } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthActivate, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-activate [token]="token" (signIn)="router.navigateByUrl('/login')">
+      <img auth-logo src="/logo.svg" alt="Acme" width="160" height="40" />
+      <a gbtButton variant="link" gbtAuthFooterLink routerLink="/login">Sign in</a>
+    </gbt-auth-activate>
+  `,
+})
+export class ActivateRoute {
+  protected readonly router = inject(Router)
+  private readonly route = inject(ActivatedRoute)
+  // Read once, then scrubbed from the address bar and the history entry.
+  protected readonly token = activationToken(
+    this.route.snapshot.fragment,
+    this.route.snapshot.queryParamMap.get('token'),
+  )
+
+  constructor() {
+    const { fragment, queryParamMap } = this.route.snapshot
+    if (fragment !== null || queryParamMap.keys.length > 0) {
+      afterNextRender(() => void this.router.navigateByUrl('/activate', { replaceUrl: true }))
+    }
+  }
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The panel owns the page's `<main>` landmark and its `h1`.

package/auth-login/README.md

@@ -0,0 +1,113 @@
+# AuthLogin
+
+The sign-in page of the auth kit, outside the app shell: the application's logo,
+a heading, the username and password fields and one "Sign in" button; then,
+when the password is accepted, the second factor. It is router-, storage- and
+backend-agnostic: every call goes through the application's
+[`AuthPort`](../auth/ports/auth.port.ts), and the page tells the application the
+user is signed in with `loggedIn` (the application navigates).
+
+**Selector**: `gbt-auth-login`
+
+## States
+
+| State       | When                                                                           | What shows                                                                                                                                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Credentials | On open, after "Back", after an expired second step.                           | "Sign in", the two fields, the submit button; the registration footer when registration is open and the application projected a link.                                                                                                                         |
+| Challenge   | `login` answered an `mfaToken` without `mfaSetupRequired`.                     | "Two-step verification", with what this user can do here: their passkey (when they have one and both the browser and the server can run it), the 6-digit code of their app (when they have one), and always a backup code.                                    |
+| Enrolment   | `login` answered an `mfaToken` with `mfaSetupRequired` (no second factor yet). | "Two-factor authentication" and [`gbt-mfa-enrollment`](../mfa-enrollment/mfa-enrollment.ts) in a wider panel: the mandatory first set-up of an app or a passkey, then the backup codes. The session is only handed over once the user acknowledged the codes. |
+
+## Inputs
+
+| Input    | Type                   | Default | Role                                                                                                                        |
+| -------- | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `labels` | `Partial<LoginLabels>` | `{}`    | Strings to change, string by string, over `provideAuthLabels({ login })` and the English defaults (`DEFAULT_LOGIN_LABELS`). |
+
+The enrolment takes its strings from `provideAuthLabels({ mfaEnrollment, totpQr, backupCodes })`.
+
+## Outputs
+
+| Output     | Payload | Role                                                                                                                                                                                                                       |
+| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loggedIn` | `void`  | The user is signed in: the port stored the session (`login`, `verifyMfa`, `finishPasskeyChallenge`), or the page handed the held-back session of a finished enrolment to `AuthPort.setToken`. Navigate to the application. |
+
+## Slots
+
+| Selector              | Role                                                                                                                                                                                                                        |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[auth-logo]`         | The application's logo (an `img`, a `picture`, an `svg`) at the top of the panel, on every state. Give it its `alt`.                                                                                                        |
+| `[auth-backdrop]` | What is drawn on the graphite page, behind the panel: `gbt-git-field`, the family's animated commit graph (`@masmarino/gabarit/git-field`). Optional. |
+| `[gbtAuthFooterLink]` | The link to the application's registration page (`<a gbtButton variant="link" gbtAuthFooterLink routerLink="/register">`). Shown under the form, after "No account yet?", only when `authConfig` says registration is open. |
+| `[auth-notice]`       | Something the application has to say before the credentials (a session that ended, a sign-in link that failed), e.g. a `gbt-alert`. First in the form, on the credentials step only.                                        |
+
+## Providers
+
+| Token                               | Required               | Role                                                                                                                                       |
+| ----------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AUTH_PORT`                         | Yes                    | The backend: `authConfig`, `login`, `verifyMfa`, `startPasskeyChallenge`, `finishPasskeyChallenge`, `setToken`, and the enrolment's calls. |
+| `TOTP_QR_RENDERER`                  | For the enrolment's QR | The QR encoder of the authenticator-app set-up. Without one the enrolment shows the secret to type by hand.                                |
+| `AUTH_LABELS` (`provideAuthLabels`) | No                     | The application's wording, once for the whole kit.                                                                                         |
+
+## Behaviour
+
+- **Configuration.** `authConfig` is read once, when the page opens. A failed read only hides
+  the registration link, and is not taken for "no passkeys on this server": signing in never
+  depends on it.
+- **Password step.** Only a 401 says "Incorrect username or password"; a 429 says to wait; any
+  other failure (a 5xx, a network error, an answer with neither `token` nor `mfaToken`) says the
+  sign-in failed. The password is dropped from memory as soon as the server accepted it.
+- **Challenge.** One primary button per view: "Use a passkey" when it is offered, else "Verify".
+  A user with both factors gets the passkey first and the code form under "or". Spaces are
+  stripped from a code. A refused code empties the field; a 429 keeps it. A passkey-only user
+  whose passkey cannot run here (no WebAuthn in the browser, or passkeys off on the server) is
+  told why and given the backup-code form, never a dead end.
+- **Passkey.** `startPasskeyChallenge`, the browser's prompt, then `finishPasskeyChallenge`. A
+  dismissed prompt is a quiet "Operation cancelled" (not an error) and keeps the screen. While
+  the prompt is open "Use a backup code" and "Back" stay usable; leaving drops the ceremony, so a
+  late answer is never sent.
+- **Expiry.** A dead `mfaToken` (401 `invalid or expired token`, at the challenge, the passkey
+  or the enrolment) goes back to the credentials with "Your sign-in has expired, sign in again."
+  and the username kept.
+- **Enrolment.** The page embeds `gbt-mfa-enrollment`: `completed` hands the session to
+  `AuthPort.setToken` then emits `loggedIn`; `cancelled` ("Back") returns to the credentials;
+  `expired` returns with the expiry message. The passkey option is only offered when the
+  server said `passkeysAvailable: true` and the browser has WebAuthn.
+- **Focus.** On open the username field; after a failed sign-in the password field; on the
+  challenge the passkey button or the code field; after a failure the field (or button) to retry;
+  after "Back" the password field.
+
+Failures are classified by status and by the body's `error` string (see
+`AUTH_PORT_ERROR_BODIES`): the backend's own text is never shown.
+
+## Example
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useClass: HttpAuthPort }, // your adapter over HttpClient
+  {
+    provide: TOTP_QR_RENDERER,
+    useValue: (text, options) => import('qrcode').then((m) => m.toDataURL(text, options)),
+  },
+  provideAuthLabels({ login: { heading: 'Connexion', submit: 'Se connecter' /* … */ } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthLogin, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-login (loggedIn)="router.navigateByUrl('/home')">
+      <img auth-logo src="/logo.svg" alt="Acme" width="160" height="40" />
+      <a gbtButton variant="link" gbtAuthFooterLink routerLink="/register">Create an account</a>
+    </gbt-auth-login>
+  `,
+})
+export class LoginPage {
+  protected readonly router = inject(Router)
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The page title (`<title>`) is the application's: set it on the route.

package/auth-register/README.md

@@ -0,0 +1,104 @@
+# AuthRegister
+
+The free registration page of the auth kit, outside the app shell, in the sign-in panel
+([`gbt-auth-panel`](../auth/auth-panel/auth-panel.ts)). It asks the backend whether registration is open,
+shows the form (or "Registration is closed"), creates the account, then takes the new account through
+the mandatory first MFA enrolment ([`gbt-mfa-enrollment`](../mfa-enrollment/mfa-enrollment.ts)) right
+in the panel. It never talks HTTP, never touches storage and never navigates: the backend is the
+application's `AUTH_PORT`, and the page tells the application where to go through its outputs.
+
+**Selector**: `gbt-auth-register`
+
+## States
+
+| State     | What shows                                                                                                                                                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| loading   | Until `AuthPort.authConfig()` answers: a skeleton of the form (`role="status"`, `aria-busy`, a visually hidden "Loading"), no heading, never a flash of the form.                                                                                                  |
+| open      | The form: username, email address, password, one primary "Create my account", then the projected sign-in link. Also shown when `authConfig()` fails: the server enforces the switch anyway.                                                                        |
+| closed    | `registrationEnabled` is false (or the server answered "registration is disabled" to a submit): a lock state with "Registration is closed", its explanation and one "Sign in" button.                                                                              |
+| enrolment | The server answered an `mfaToken`: the panel widens (`wide`), its heading becomes "Two-factor authentication" and `gbt-mfa-enrollment` replaces the form. A passkey is offered when `authConfig().passkeysAvailable` is true and the browser supports WebAuthn.    |
+| created   | The enrolment was left ("Back") or its token expired: the account exists, so the page says "Your account has been created", names it (lower-cased, as stored; "The setup has expired." first when it expired) and offers one "Sign in" button. No session is held. |
+
+## Inputs
+
+| Input               | Type                      | Default                                | Role                                                                                                                                           |
+| ------------------- | ------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels`            | `Partial<RegisterLabels>` | `{}`                                   | Strings to change, over `provideAuthLabels({ register })` and the English defaults (`DEFAULT_REGISTER_LABELS`).                                |
+| `minPasswordLength` | `number`                  | `MIN_PASSWORD_LENGTH` (8)              | The server's minimum password length, checked before the round trip; also worded in the hint and the error.                                    |
+| `usernamePattern`   | `RegExp`                  | `USERNAME_PATTERN` (a letter, 3 to 32) | The server's username rule, checked on the trimmed name before the round trip. Adjust the `usernameHint` and `usernameInvalid` labels with it. |
+
+The enrolment's own strings are `MfaEnrollmentLabels`: localise them with `provideAuthLabels({ mfaEnrollment })`.
+
+**A custom `usernamePattern` must not use the `g` or `y` regex flags (they make `.test()` stateful across
+calls, so the same name would pass and fail in turn) and must mirror the server's own rule.** The same goes
+for `minPasswordLength`: both only spare a round trip, the server stays the authority.
+
+## Outputs
+
+| Output       | Payload | Role                                                                                                                                                                                                            |
+| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registered` | `void`  | The account exists and has a session: either the backend issued one at once (the port stored it), or the enrolment finished and the held-back session was handed to `AuthPort.setToken`. Navigate into the app. |
+| `signIn`     | `void`  | "Sign in" was pressed in the closed or created state: go to the sign-in page.                                                                                                                                   |
+
+## Slots
+
+| Selector              | Role                                                                                                                                                                   |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[auth-logo]`         | The application's logo (an `img`, `picture` or `svg`), on top of the panel. Optional.                                                                                  |
+| `[auth-backdrop]` | What is drawn on the graphite page, behind the panel: `gbt-git-field`, the family's animated commit graph (`@masmarino/gabarit/git-field`). Optional. |
+| `[gbtAuthFooterLink]` | The link to the sign-in page, under the form after "Already have an account?". An `a gbtButton variant="link"` carrying `routerLink` or `href`. No footer when absent. |
+
+## Behaviour
+
+- **Checks before the request.** Nothing is said while the user types; after a first "Create my account"
+  every wrong field shows its rule (in place of its hint, as its only `aria-describedby`) and the focus moves
+  to the first wrong one. The checks then stay live. Nothing is sent while a field is wrong.
+- **Sent**: `register(username.trim(), email.trim(), password)`. A second submit while in flight is ignored;
+  the button shows its spinner and is disabled. The password is emptied as soon as the server answered.
+- **Failures** are worded from the labels, never from the backend's text, in an alert (`role="alert"`), and the
+  focus goes where the user retypes: a 400 naming a field focuses that field ("Check the fields"); a 400 naming
+  none focuses the alert; a reserved name, a taken name or address (409) focus the field concerned; a 429 says
+  to wait; anything else (5xx, network, a browser error) says the creation failed and keeps what was typed. A
+  400 "registration is disabled" switches to the closed state. The recognised bodies are in
+  `AUTH_PORT_ERROR_BODIES`.
+- **Focus**: the form starts in the username field; the closed and created states move the focus to their
+  `h1` (focusable by script, not a tab stop) so the change is announced.
+- **Sessions**: the page never stores one. A backend without MFA enforcement answers a `token` (the port stores
+  it): `registered` fires at once. Otherwise the enrolment keeps the session until the backup codes are
+  acknowledged, then the page hands it to `AuthPort.setToken` and emits `registered`.
+
+## Example
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useClass: HttpAuthPort }, // your adapter over HttpClient
+  {
+    provide: TOTP_QR_RENDERER,
+    useValue: (text, options) => import('qrcode').then((m) => m.toDataURL(text, options)),
+  },
+  provideAuthLabels({ register: { intro: 'Join Acme to host your repositories.' } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthRegister, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-register
+      (registered)="router.navigateByUrl('/home')"
+      (signIn)="router.navigateByUrl('/login')"
+    >
+      <img auth-logo src="/logo.svg" alt="Acme" width="160" height="40" />
+      <a gbtButton variant="link" gbtAuthFooterLink routerLink="/login">Sign in</a>
+    </gbt-auth-register>
+  `,
+})
+export class RegisterRoute {
+  protected readonly router = inject(Router)
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The panel owns the page's `<main>` landmark and its `h1`.

package/auth-reset-password/README.md

@@ -0,0 +1,120 @@
+# AuthResetPassword
+
+The password-reset page of the auth kit: where the link of a password-reset mail lands, outside the app
+shell, in the sign-in panel ([`gbt-auth-panel`](../auth/auth-panel/auth-panel.ts)). An administrator has
+reset the password of an existing account; the user follows the link and chooses a new password. No
+session comes out of it: they sign in afterwards, through their second factor as on any sign-in (a
+password reset leaves the account's factors untouched). It never talks HTTP, never reads the URL and
+never navigates: the backend is the application's `AUTH_PORT`, the token is an input, and the page tells
+the application where to go through its outputs.
+
+**Selector**: `gbt-auth-reset-password`
+
+It is the sibling of [`gbt-auth-activate`](../auth-activate/README.md): same one-time link mechanics, same
+form, same failure handling; only the call (`resetPassword` instead of `activate`), the output and the
+wording differ.
+
+## Views
+
+| View    | What shows                                                                                                                                                                                  |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| form    | A token was given: "Choose a new password", why (an administrator reset it), New password (with its hint), Confirm the new password, one primary "Set new password", then the projected sign-in link. |
+| success | The server accepted: "Your password has been changed", sign in with the new one, one "Sign in" button.                                                                                          |
+| invalid | No token (`null` or `''`), or the server refused it (unknown, expired or used): an error-toned state, "This link does not work", ask an administrator for a new link, one "Sign in".            |
+
+## Inputs
+
+| Input               | Type                           | Default                   | Role                                                                                                                                                                                                        |
+| ------------------- | ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token`             | `string \| null`               | `null`                    | The reset link's token, as the application read it from its URL with `activationToken(fragment, null)`. `null` (or `''`) is the dead link, without any request. A new value starts the page over. |
+| `labels`            | `Partial<ResetPasswordLabels>` | `{}`                      | Strings to change, over `provideAuthLabels({ resetPassword })` and the English defaults (`DEFAULT_RESET_PASSWORD_LABELS`).                                                                                  |
+| `minPasswordLength` | `number`                       | `MIN_PASSWORD_LENGTH` (8) | The server's minimum password length, checked before the round trip; also worded in the hint and the errors.                                                                                                |
+
+## Outputs
+
+| Output          | Payload | Role                                                                                 |
+| --------------- | ------- | ------------------------------------------------------------------------------------ |
+| `passwordReset` | `void`  | The server accepted the new password: the success view shows. No session was opened. |
+| `signIn`        | `void`  | "Sign in" was pressed in the success or dead-link view: go to the sign-in page.      |
+
+The success output is `passwordReset`, not `reset`: an output named after a native DOM event would
+also catch the `reset` events bubbling from the page's own `<form>`.
+
+## Slots
+
+| Selector              | Role                                                                                                                                                                                         |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[auth-logo]`         | The application's logo (an `img`, `picture` or `svg`), on top of the panel. Optional.                                                                                                        |
+| `[auth-backdrop]` | What is drawn on the graphite page, behind the panel: `gbt-git-field`, the family's animated commit graph (`@masmarino/gabarit/git-field`). Optional. |
+| `[gbtAuthFooterLink]` | The link to the sign-in page, under the form after "Already set your new password?". An `a gbtButton variant="link"` carrying `routerLink` or `href`. No footer when absent. |
+
+## Behaviour
+
+- **The token.** The page sends it with the new password (`resetPassword(token, password)`) and never
+  renders it (not in the markup, not in a field). Once spent (success) or refused (a 400 other than a weak
+  password), it is dropped: the page does not send it again until a new `token` arrives.
+- **The application's part** (it owns the URL): put the token in the link's **fragment**
+  (`/reset-password#token=…`) so that no server, proxy or access log ever sees it; read it once with
+  `activationToken(route.snapshot.fragment, null)` (the helper is shared with the activation: a token not
+  shaped like the server's, 64 hexadecimal characters by default, is `null`; pass your own `shape` as its
+  third argument if your backend's differs); then remove it (and any other parameter) from the address bar
+  and the history entry, e.g. `router.navigateByUrl('/reset-password', { replaceUrl: true })` after the
+  first render, so it does not linger in a screenshot or a shared tab. Unlike the activation, there is no
+  older `?token=` link to support: read the fragment only.
+- **The `token` input must be a one-time snapshot of the URL, never a value that reactively follows the
+  URL (e.g. a signal derived from `route.fragment`): the component resets when it changes.** Scrubbing the
+  URL as above would otherwise turn the token into `null` and flip the page to the dead-link view, even over
+  its success view. Read it into a plain field, as in the example below.
+- **`minPasswordLength` must mirror the server's own rule.** It only spares a round trip: the server stays
+  the authority, and a looser value only moves the refusal to the server's answer.
+- **Checks before the request.** Nothing is said while typing; after a first attempt the password rule and
+  the confirmation ("Confirm your new password", "The passwords do not match") show under their fields, the
+  focus moves to the first wrong one, and the checks stay live.
+- **Failures** are worded from the labels, in an alert, the focus back in the password field: a weak-password
+  400 keeps the form (the link is still good), a 429 says to wait, anything else (5xx, network) says the new
+  password could not be set and the same token can be retried. Any other 400 is the dead link: the server
+  is expected to answer one generic 400 for an unknown, expired, used or malformed token, so that nobody
+  probing links can tell them apart; the page words them all the same way. The failures are read by
+  `classifyActivateFailure`, shared with the activation.
+- **Focus**: the form starts in the new-password field; the success and dead-link views move the focus to
+  their `h1` (focusable by script, not a tab stop). The passwords are emptied when the server accepted or
+  refused the link.
+
+## Example
+
+```ts
+// app.config.ts
+providers: [
+  { provide: AUTH_PORT, useClass: HttpAuthPort }, // your adapter over HttpClient
+  provideAuthLabels({ resetPassword: { signInPrompt: 'Password already changed?' } }),
+]
+```
+
+```ts
+@Component({
+  imports: [AuthResetPassword, Button, AuthFooterLink, RouterLink],
+  template: `
+    <gbt-auth-reset-password [token]="token" (signIn)="router.navigateByUrl('/login')">
+      <img auth-logo src="/logo.svg" alt="Acme" width="160" height="40" />
+      <a gbtButton variant="link" gbtAuthFooterLink routerLink="/login">Sign in</a>
+    </gbt-auth-reset-password>
+  `,
+})
+export class ResetPasswordRoute {
+  protected readonly router = inject(Router)
+  private readonly route = inject(ActivatedRoute)
+  // Read once, then scrubbed from the address bar and the history entry.
+  protected readonly token = activationToken(this.route.snapshot.fragment, null)
+
+  constructor() {
+    const { fragment, queryParamMap } = this.route.snapshot
+    if (fragment !== null || queryParamMap.keys.length > 0) {
+      afterNextRender(() => void this.router.navigateByUrl('/reset-password', { replaceUrl: true }))
+    }
+  }
+}
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md). The panel owns the page's `<main>` landmark and its `h1`.