# Two-factor panel (`two-factor`)

The 2FA enrolment/settings card: QR + manual secret, the big-digit code input, recovery-code grid, and factor status rows.

> **Layer:** L2 host · **Recipe:** _(unset — see docs/agent/pick-a-surface.md)_
> Curriculum: `AGENTS.md` · pick matrix: `docs/agent/pick-a-surface.md` · blast radius: `CONSUMER_MAP.md`

> **Dialect:** Partial below is **unprefixed** (gallery / standalone HM). DOM contract Python often uses the **source token** `data-dz-*` / `dz-*` (Dazzle dual-lock). Match the CSS/JS bundle you load.

> **Demo vs contract:** Live gallery behaviour may use `/mock/*` or flash toasts. Those are **offline demos only** — implement **Server exchange** + **DOM contract**, not the mock. See AGENTS.md › Gallery demos.

## Copy this

```html
<div class="auth-card hm-measure">
  <h1 class="auth-card-title">Set Up 2FA</h1>
  <p class="auth-card-subtitle">Aurora Ops</p>
  <h2 class="auth-section-title">Authenticator App</h2>
  <p class="auth-section-body">Scan this QR code with your authenticator app.</p>
  <div class="auth-qr-container"><button class="button" data-variant="outline">Generate QR Code</button></div>
  <p class="auth-section-body">Or enter the secret manually: <code class="auth-secret-inline">JBSW Y3DP EHPK 3PXP</code></p>
  <form class="auth-form">
    <div class="auth-field">
      <label for="hm-2fa-code" class="auth-label">Enter code from app</label>
      <input type="text" id="hm-2fa-code" inputmode="numeric" pattern="[0-9]*" maxlength="6" placeholder="000000" class="auth-input-code">
    </div>
    <button type="submit" class="button auth-submit" data-variant="primary">Verify and Enable</button>
  </form>
  <hr class="auth-hr">
  <div class="auth-recovery-alert" role="alert">
    <h3 class="auth-recovery-alert-title">Save Your Recovery Codes</h3>
    <p class="auth-recovery-alert-body">Store these codes in a safe place. Each code can only be used once.</p>
  </div>
  <div class="auth-recovery-grid"><span class="auth-recovery-pill">QK2M-8Y1D</span><span class="auth-recovery-pill">HW7C-04RA</span><span class="auth-recovery-pill">ZX3N-55PT</span><span class="auth-recovery-pill">MB9E-71LQ</span></div>
  <div class="auth-status-row">
    <div class="auth-status-label">Authenticator app</div>
    <span class="badge" data-tone="success">Enabled</span>
  </div>
  <div class="auth-status-row is-last">
    <div class="auth-status-label">Email codes</div>
    <span class="badge">Off</span>
  </div>
  <a href="#" class="auth-back-link">Back to App</a>
</div>
```

## Server exchange

This Hyperpart has **no server exchange** — presentation or client chrome only. If you put `hx-*` on a control that uses this markup, that action's exchange belongs to the action, not this part.

## Swap contract

Agent-visible HTMX topology (ADR-0054 / decision 0012). **Exchange envelope** = what the response may re-emit relative to the persistent slot (`body_only` | `outer` | `none` | `host_owned` | `document`). Dual-lock validates part markup only — not this envelope. Stem: `stems/morph-safe-hypermedia.md`.

**No host HTMX exchange** on this part — presentation or client chrome only. **Exchange envelope:** `n/a`.

If a **host** wraps this markup in `hx-*`, **that host owns the swap contract** (sole identity + envelope). Prefer `innerMorph` / `outerMorph` for stable slots; replacement for flash; body-only responses under inner swaps.

### Envelope response examples

What the **server returns** for each exchange. Match the **exchange envelope**; dual-lock still applies to interior markup.

This part has no owned exchange (envelope `n/a`). If a host adds `hx-*`, that host’s envelope applies — typically `body_only`:

```html
<!-- Prefer hx-swap=innerMorph into a stable body slot -->
<div class="dz-stack">content…</div>
```

Do **not** re-own the slot:

```html
<div id="two-factor-root" data-dz-region>…</div>
```

## How to use it

No extended guidance authored yet — start from Copy this and the dependency chips.

### Seams

- copy the partial under Copy this; keep root class and data-* modifiers so the CSS/JS bundle matches
- no Server exchange on this part — pure presentation or client chrome
- satisfy the DOM contract tables (CI stop-ship)

## DOM contract

What emitted markup must satisfy (CI: `tests/test_contracts.py`). Do not invent attrs outside the tables. Python modules under `contracts/` are **package-internal dual-locks** (`from contracts._kit import …`) — not FastAPI business handlers. App servers implement **Server exchange** endpoints; this section constrains the HTML those endpoints return.

### `contracts/two_factor.py`

- **Required root:** `.dz-auth-card` (part `two_factor`)

| Node | Attr | Constraint |
|---|---|---|
| `.dz-auth-card` | `—` | — |

#### Module source

Monorepo dual-lock only — import `contracts._kit` from the HM package. Do not paste into app route modules.

```python
"""HYPERPART: two_factor — 2FA enrolment/settings auth card.

Dual-lock unit is the auth-card root. QR container, code input, recovery
grid, and factor status rows are host-owned. Class ``.dz-auth-card`` is the
stable substrate root (gallery CSS / two-factor panel; no FragmentRenderer
emit yet).
"""

from contracts._kit import DomContract, Node

DOM_CONTRACT = DomContract(
    part="two_factor",
    root=".dz-auth-card",
    nodes=(Node(".dz-auth-card", attrs={}),),
)

__all__ = ["DOM_CONTRACT"]
```

## Notes

In Dazzle the enrolment flow is driven by ID-anchored vanilla JS (dz-2fa-setup.js/-settings.js against JSON endpoints): the QR image lands CLASSLESS in dz-auth-qr-container (the container styles it), recovery pills and status rows are JS-created (shown here with status badges; the Dazzle settings JS renders dz-button action controls in that slot), and the error/success alerts toggle via the native hidden attribute on stable ids. The code input reserves letter-spacing for six digits. Wrap full pages in dz-auth-page for the centered layout. Dual-lock root .dz-auth-card (HMC-148).

## Source files

- `site/registry.py` (partial + exchanges + guidance)
- `contracts/two_factor.py`