Shade/docs/key-transparency.md

Key Transparency (V3.12)

Status: v0.4.0+ — opt-in. Server runs unchanged when KT is off. Klient ignorerer proof-felt når KT-config mangler. Trygg å rulle ut uten klient-update.

Shades prekey-server er sannhetskilde for hvilket bundle som er publisert for hver adresse. Uten Key Transparency (KT) kan en ondsinnet eller kompromittert server bytte ut et bundle uten at noen oppdager det. Med KT er hvert bundle som leveres kryptografisk forpliktet i en append-only Merkle log som tredjeparts-witnesses kan auditere.

Se også docs/V3.12-DESIGN.md for designnotat med trusselmodell og beslutningsspor.

---

Hva KT garanterer

Angrep	Detektert?
Server gir Bob feil bundle for alice	Ja — inklusjons-proof matcher ikke
Server gir Bob og Charlie ulike bundles for alice	Ja — witness-gossip ser to STH-er på samme tree_size
Server skriver om historikk for å skjule tidligere svik	Ja — konsistens-proof feiler
Server signerer "stale" STH for å holde et tidsvindu åpent	Ja — klient avviser STH eldre enn maxStaleMs (default 24t)
Førstegangs-impersonering av en helt ny adresse	Nei — KT ser bare etter at adressen er i loggen, ikke at den er "riktig" person. Bruk V3.3 (fingerprint-gate) + V3.10 (social recovery) for det.

---

Operatør: skru på KT

KT er opt-in og krever:

1. Et Ed25519 signing-keypair for STH-signering. Dette er operatørens nøkkel og må beskyttes som en code-signing-key.
2. En persistent KTLogStore. I produksjon: PostgresKTLogStore. I test/dev: MemoryKTLogStore.
3. At klienter pinner samme logPublicKey OOB (typisk via Shade.config-bundling i appen).

Generere signing-key

bun run scripts/generate-kt-key.ts > kt-key.json

(Eller kjør manuelt: crypto.generateEd25519KeyPair() i en Bun REPL.) Lagre privateKey i operatørens secret-store. Distribuér publicKey til klienter sammen med app-config.

Boot serveren med KT

import { createPrekeyServerWithKT } from '@shade/server';
import { PostgresPrekeyStore, PostgresKTLogStore } from '@shade/storage-postgres';
import { SubtleCryptoProvider } from '@shade/crypto-web';

const crypto = new SubtleCryptoProvider();

const prekeyStore = await PostgresPrekeyStore.create(process.env.DATABASE_URL!);
const ktStore = await PostgresKTLogStore.create(process.env.DATABASE_URL!);

const { app, kt } = await createPrekeyServerWithKT({
  crypto,
  store: prekeyStore,
  keyTransparency: {
    store: ktStore,
    signingPrivateKey: loadFromSecret('SHADE_KT_SIGNING_PRIVATE_KEY'),
    signingPublicKey: loadFromSecret('SHADE_KT_SIGNING_PUBLIC_KEY'),
    heartbeatIntervalMs: 10 * 60 * 1000, // default; 0 = off
  },
});

export default { port: 3900, fetch: app.fetch };

Når KT er på blir disse rutene tilgjengelig:

Route	Hva den returnerer
GET /v1/kt/log_id	{ logId, publicKey } (begge base64)
GET /v1/kt/sth	Siste signed tree head
GET /v1/kt/sth/:treeSize	Historisk STH for et bestemt tree_size
GET /v1/kt/consistency?from=N1&to=N2	Konsistens-proof N1 → N2

Bundle-fetch (GET /v1/keys/bundle/:address) får nå et ktProof-felt i responsen.

Migrasjon fra ikke-KT

KT er bakoverkompatibel:

1. Skru på KT-config i serveren. Restart.
2. Eksisterende klienter ignorerer proof-feltene (ktProof, ktSth).
3. Etter hvert som klienter oppgraderes med KT-config (mode: 'observe'), begynner de å verifisere.
4. Når øko-systemet er vant til det, eskalér klienter til 'observe-strict' for å avvise prekey-server-svar uten proof.

Ved første boot scanner KT-tjenesten ikke automatisk eksisterende prekey-store-tilstand inn i loggen. Re-registrering av eksisterende adresser (dvs. en POST /v1/keys/register-runde fra hver klient) er det som backfiller. For et større deployment: anbefalt at en operatør varsler brukerne om å re-registrere innen et tidsvindue. Klienter som ikke re-registrerer vil feile observe-strict-fetch til de får ny key fra peer.

---

Klient: skru på KT

import { createShade } from '@shade/sdk';

const shade = await createShade({
  prekeyServer: 'https://shade.example.com',
  address: 'alice',
  keyTransparency: {
    mode: 'observe-strict',                // eller 'observe'
    logPublicKey: KT_LOG_PUBLIC_KEY_BASE64, // eller Uint8Array
    maxStaleMs: 24 * 60 * 60 * 1000,        // default 24t
  },
});

shade.getKTWitness() returnerer LightWitness-instansen som samler observerte STH-er. Bruk .compare(otherSth) for manuell gossip-sjekk mot peers.

mode: 'observe'

• Verifiserer proof når serveren leverer det.
• Skipper verifisering hvis ktProof mangler i bundle-respons.
• Anbefalt under første utrulling der ikke alle klienter har re-registrert ennå.

mode: 'observe-strict'

• Krever proof på hver 200-respons. Mangler proof → kast KTVerificationError.
• Krever proof på hver 404-respons også (for absence/tombstone-pinning).
• Anbefalt produksjons-modus når KT-økosystemet er etablert.

---

Witness / auditor

@shade/key-transparency eksporterer LightWitness. Et CLI-verktøy eller backend-job kan bruke den slik:

import { LightWitness } from '@shade/key-transparency';
import { SubtleCryptoProvider } from '@shade/crypto-web';

const crypto = new SubtleCryptoProvider();
const witness = new LightWitness({
  crypto,
  logPublicKey: KT_LOG_PUBLIC_KEY,
  fetcher: {
    async fetchLatestSTH() {
      const r = await fetch('https://shade.example.com/v1/kt/sth');
      return r.json();
    },
    async fetchConsistencyProof(from, to) {
      const r = await fetch(`https://shade.example.com/v1/kt/consistency?from=${from}&to=${to}`);
      return r.json();
    },
  },
});

// Poll periodically (e.g. every 5 minutes)
setInterval(async () => {
  try {
    const sth = await witness.pollOnce();
    console.log(`Observed STH: tree_size=${sth.treeSize}, root=${Buffer.from(sth.rootHash).toString('hex').slice(0, 16)}`);
  } catch (err) {
    console.error('Witness alarm:', err);
    // Send to PagerDuty / Slack / whatever
  }
}, 5 * 60 * 1000);

Witness-koden detekterer:

• Stale STH — server publiserer ikke nye STH-er i tide.
• Split view — to STH-er ved samme tree_size med ulik root.
• Re-write — konsistens-proof feiler.
• Wrong key — log_id matcher ikke pinnet logPublicKey.

---

Operatørkost (estimat)

For et deployment med:

• 100k registrerte adresser
• 1 identitets-rotasjon per år per bruker
• 52 replenish per år (én i uka, ikke committed til loggen — bare register/delete er)

Ressurs	Per år	Kommentar
Log-rader	~100k	bare register/delete
Lagring (leaves+index)	~25 MB	base64-kodet
STH-rows	~52k	én per heartbeat (10 min)
STH-storage	~7 MB
CPU per STH	~1ms	Ed25519-signing er trivielt
Bundle-fetch overhead	<2ms	inkluderer audit-path-bygg

Backup: behandle KT-tabellene som "kan ikke gjenopprettes" data — shade_kt_leaves har en database-trigger som forbyr UPDATE/DELETE i PostgreSQL-implementasjonen. Backup-strategi:

• Daglig full backup av shade_kt_* tabellene.
• WAL-shipping anbefalt (tap < 60 s i verste fall).
• Test recovery kvartalsvis. Recovery-prosedyre står under.

---

Recovery

Scenario 1 — STH-signing-key tapt eller kompromittert

Loggen forblir konsistent (alle gamle STH-er er allerede signert), men nye STH-er kan ikke signeres med samme key.

Steg:

1. Generer ny Ed25519-keypair.
2. Skriv inn et "rotation breaks here"-leaf i loggen (operasjon = 0x03 på en spesiell __log__-adresse) — operasjonen er rent informativ, men gjør rotasjonen synlig i tree.
3. Re-konfigurer serveren med ny key. Restart.
4. Server publiserer en ny STH; den vil ha en ny log_id (siden log_id = SHA-256(publicKey)).
5. Klienter må eksplisitt akseptere ny key. Inntil de pinner ny logPublicKey, vil deres LightWitness kaste KTLogIdMismatchError. Operatør publiserer ny key OOB med "rotated from <gammel logId>"-melding signert med gammel key (siste handling før gammel key zeroizes).

Scenario 2 — KT-database korrumpert / tapt før backup

Dette er det verste utfallet. Loggen er per design ikke gjenopprettbar — å "rekonstruere" den fra prekey-store ville bryte selve invarianten KT lover.

Steg:

1. Stopp serveren.
2. Deklarer en "log-restart event" via offentlig kanal (status-side, release-notes, Twitter, etc.) — inkluder timestamp, tapte tree_size (siste backup-bare snapshot om mulig), og ny logPublicKey.
3. Generer ny KT-keypair (ikke bruk gamle).
4. Boot serveren tom (tom shade_kt_* tabell). Første STH er fra tree_size = 0.
5. Be brukerne om å re-registrere identitetene sine. Klientene vil trigge V3.3 fingerprint-gate på første re-meldings-flyt etterpå siden rotasjons-fingerprintet endres.
6. Auditor-organisasjoner kan publisere "vi observerte gammel log inntil tree_size N, ny log starter på 0 fra T+0" — dette gir sluttbruker mulighet til å vurdere hvor stort hullet er.

Beskytt mot dette: WAL-shipping + off-site backup. Aldri kjør KT med kun én database-instans uten replicas.

Scenario 3 — Witness oppdager split-view

Witness kaster KTSplitViewError i LightWitness.observe() eller KTVerificationError i transport. Dette betyr:

• Operatøren har enten (a) hatt en software-bug som signerte to ulike STH-er ved samme tree_size, eller (b) er kompromittert / ondsinnet.

Operatør-handling:

1. Pause POST /v1/keys/register, DELETE, og bundle-fetch umiddelbart (return 503).
2. Audit shade_kt_sths — hvis du finner to rader med samme tree_size men ulik root_hash, har serveren gjort feil. Dette er alvorlig — finn root cause før du fortsetter.
3. Kommuniser ut til brukerne. Forutsett at en angriper har vært inne; trigge en bredere reset (recovery scenario 2) hvis det er mistanke om tampering.

Klient-handling:

• LightWitness har allerede holdt brukeren tilbake.
• SDK-en surfacer feilen som KTSplitViewError til app-koden.
• App-en bør vise advarsel: "Operatørens server kan ikke verifiseres. Avstå fra sending av sensitive meldinger inntil videre."

---

Sikkerhets-anbefalinger

1. Kjør minst én uavhengig witness. Operatørens egen "witness" teller ikke — det må være en separat prosess på separate infrastruktur eid av en separat aktør (community-medlem, security firm, e.l.).

2. Pin logPublicKey i app-binær eller signert config. En man-in-the-middle som kan bytte både prekey-server og KT-key fanges ikke av KT alene.

3. Loggrotasjon krever menneske-i-løkken. Ikke automatiser key-rotation for KT — den eksplisitte breaking-event er en feature.

4. maxStaleMs bør samsvare med din heartbeat. 24t default tåler en heartbeat-pause på opptil et døgn; senk til 1–4t hvis du har strenge krav til friskhet.

5. observe-strict bør være standard når økosystemet er etablert. Default 'observe' er en operasjonell overgangsmodus, ikke et sluttmål.

---

Kjente begrensninger

• Federation mellom flere prekey-servere er ikke støttet i V3.12. Hver Shade-deployment har én log eller ingen.
• Sparse Merkle tree for adresse-index brukes ikke i V3.12 — fravær-proof er foreløpig nabopar-bevis. <100 KB ved 100k adresser er akseptabelt; sparse tree blir relevant fra ~10M+ adresser.
• One-time prekey-rotasjon committes ikke til loggen. OTP er ephemerale og inkludering ville støy-fylle loggen. Dette betyr at en server som svarer med riktig identitet men feil OTP fanges ikke av KT — forsvar mot dette ligger i V3.3 fingerprint-gate (samme identitet) + sesjons-etableringens X3DH (feil OTP gir feil shared secret → første melding feiler decryption).

---

Tester og test-vektorer

• packages/shade-key-transparency/tests/ — RFC 6962-kompatibel Merkle-log + STH + index-proofs (58 tests).
• packages/shade-server/tests/kt.test.ts — server-integrasjon (8 tests).
• packages/shade-transport/tests/kt-transport.test.ts — klient- verifikasjon over HTTP (4 tests).
• packages/shade-transport/tests/kt-split-view-e2e.test.ts — V3.12-akseptanse split-view-deteksjon (3 tests).
• packages/shade-sdk/tests/kt.test.ts — SDK-config + witness wiring (3 tests).

Totalt 76 tester dedikert til KT.