# Shade V3.3 — Fingerprint Gates & Trust UX

**Status:** Done
**Effort:** M (2–4 uker)
**Forrige:** V3.1
**Adresserer:** V2.3 §1B
**Implementert:** se `docs/trust-ux.md`

---

## Mål

Gjør safety numbers **handlingspålagte** — ikke bare synlige — i flyt der
MITM-risikoen er reell. I dag finnes `FingerprintCompare`-widget og
`requireFingerprintVerifiedFor` i `@shade/files`, men hovedkjernen
(`Shade.send`, first-large-file, backup-import) har ingen automatisk gate.
Resultat: alert-fatigue-fri, men også gate-fri.

Dette legger inn **eksplisitt blokkerende verifisering** på et lite antall
kritiske hendelser, plus widget-støtte for å eksponere det i UI.

---

## Scope

### Inn — kritiske hendelser

1. **Før første store fil** — `Shade.upload` over en bytes-terskel uten
   verifisert peer.
2. **Før backup-import** — `Shade.importBackup` blokkerer til peer (eller egen
   identitet) er bekreftet.
3. **Ny enhet med rotert identitet** — `acceptIdentityChange` blokkerer på
   første bruk inntil verifisert.
4. **Før `@shade/inbox` fan-out** (V3.6) — gate per mottaker.

### Inn — APIer

- `Shade.beforeFirstLargeFile(threshold, handler)` — appen får mulighet til å
  vise modal og returnere bekreftelse.
- `Shade.beforeBackupImport(handler)` — samme mønster.
- `Shade.beforeNewDeviceTrust(handler)` — ditto.
- `Shade.markPeerVerified(address)` / `Shade.isPeerVerified(address)` —
  persistent state.

### Inn — widgets

- `<FingerprintGate />` — render-prop wrapper som blokkerer barn til
  verifisert.
- `<FingerprintCompare />` utvides med "kopier OOB-tekst" + "jeg har
  verifisert".

### Ut

- "Tving alle peers verifisert før hver melding" — alert fatigue.
- Cross-device sync av verified-state (kommer evt. via V3.6 inbox).

---

## Design

### Persistent verified-state

Ny tabell `peer_verifications`:

```sql
CREATE TABLE peer_verifications (
  peer_address      TEXT PRIMARY KEY,
  fingerprint       TEXT NOT NULL,
  verified_at       INTEGER NOT NULL,
  verified_by       TEXT,        -- "user" | "transitive" | "tofu-after-warning"
  identity_version  INTEGER NOT NULL  -- knytter verifikasjon til identity-rotasjon
);
```

Når peer roterer identitet → `identity_version` bumper → verifikasjon "ugyldig"
til ny verifisering.

### Hook-flyt

```text
shade.upload(peer, file)
    │
    ├─ if !verified(peer) AND file.size > threshold
    │    │
    │    └─ await beforeFirstLargeFileHandler(peer, fingerprint)
    │          ├─ true  → markPeerVerified(peer); proceed
    │          └─ false → throw FingerprintNotVerifiedError
    │
    └─ proceed
```

---

## Leveranser

### Kode

- `@shade/core` — `peer_verifications`-tabell + storage methods.
- `@shade/sdk` — gate-hooks + `markPeerVerified` / `isPeerVerified`.
- `@shade/widgets` — `<FingerprintGate />`, utvidet `<FingerprintCompare />`.

### Tester

- Unit: gate kalles, ikke kalles, retur false → throw, retur true → proceed.
- Integration: fil < threshold går gjennom uten gate; fil > threshold
  blokkerer.
- Identity-rotasjon ugyldiggjør verifikasjon.
- Backup-import blokkerer.

### Dokumentasjon

- `docs/trust-ux.md` — guide til hvilke gates som finnes og når de bør tunes.

---

## Akseptansekriterier

- [ ] Gate kan ikke bypasses ved å nulle `threshold` ut — minimum gate finnes
      alltid for backup-import og new-device.
- [ ] App uten registrerte gates får sane defaults (logger en warning, men
      kjører — ikke krasj).
- [ ] Identity-rotasjon resetter verifikasjon i en testet ende-til-ende-flow.
- [ ] Widget kan rendres SSR uten å trigge runtime-gate.

---

## Avhengigheter

- V3.1 — threat-matrise oppdatert til å vise hvilke gates som dekker hvilke
  rader.

---

## Risiko

- **Alert fatigue.** Hvis terskler er for lave → bruker klikker blindt.
  Mitiger ved å sette default-terskler høyt (10 MiB for first-large-file)
  og dokumenter justerings-guide.
- **DX-friksjon.** Apper som ikke vet om gates får uventede prompts. Mitiger
  ved å logge tydelig ved første aktivering: "Shade.beforeFirstLargeFile not
  configured — using default modal".

---

## Migrasjon

0.3.x apps får defaults aktivert med warning. Ingen breaking change.