Shade

En gjenbrukbar modul for ende-til-ende-kryptert kommunikasjon i egne apper — med samme type protokoll som brukes i Signal.

X3DH Double Ratchet TypeScript Plattformagnostisk crypto

Hva gjør prosjektet?

Shade er et monorepo som implementerer sikker meldingskryptering mellom to parter (for eksempel nettleser og server, eller to klienter). Meldingene er kryptert slik at transportlaget (HTTP, WebSocket, e.l.) bare ser uleselige bytes — ikke innholdet.

Kjerneideen: Du bygger inn ShadeSessionManager (fra @shade/core) sammen med en CryptoProvider (f.eks. Web Crypto i nettleser/Bun) og lagring. Deretter kan du kalle encrypt / decrypt per motpart, akkurat som i demo-koden demo.ts.

Første melding til noen ny inneholder nøkkelavtale (X3DH). Etterpå bruker hver melding Double Ratchet: nye meldingsnøkler og periodiske DH-steg gir forward secrecy (gamle meldinger overlever ikke nøkkellekkasje) og post-compromise security (systemet «helbreder» seg over tid etter kompromittering).

Pakkene (hvordan det henger sammen)

Protokollen. X3DH, Double Ratchet, sesjonstyper, feiltyper. Ingen plattformkrypto her — bare grensesnittet CryptoProvider.

ShadeSessionManager — høynivå-API: initialize, createPreKeyBundle, initSessionFromBundle, encrypt, decrypt
Symmetrisk kryptering: AES-256-GCM med AAD fra ratchet-header

Implementasjon av crypto for web/Bun/Node via SubtleCrypto — X25519, Ed25519, HKDF, HMAC, tilfeldige bytes.

Gjør det mulig å bruke shade-core i nettleser og i servere som støtter Web Crypto
Kommentarer i koden peker på fremtidig Android (f.eks. Tink) som egen provider

Binært wire-format for meldinger: versjon + type + lengdeprefiksede felt (big-endian).

Type 0x01 = PreKeyMessage, 0x02 = RatchetMessage
Brukes når du vil serialisere ShadeEnvelope effektivt over nettet

Prekey-server (Hono) — lagrer offentlige nøkler slik at Alice kan starte samtale mens Bob er «offline».

POST /v1/keys/register — registrer identitet + bundle
GET /v1/keys/bundle/:address — hent bundle (forbruker én engangsnøkkel om tilgjengelig)
POST /v1/keys/replenish — etterfyll engangsnøkler

Nøkler i korthet

Ed25519 brukes til å signere den «signerte prekeyen». X25519 brukes i Diffie-Hellman i X3DH og i ratchet. Én identitet per enhet/bruker i typisk oppsett.

Valgfrie, men viktige for ekstra sikkerhet: hver hentet bundle kan inkludere én engangsnøkkel som slettes etter bruk (processPreKeyMessage fjerner den fra lager). Gir bedre beskyttelse mot visse angrep når mange klienter kobler til samme mottaker.

Interaktiv flyt: fra null til kryptert melding

Klikk «Neste» for å gå gjennom rekkefølgen slik Shade er bygget. Dette speiler ShadeSessionManager og demoen i repoet.

Sesjon og meldinger

X3DH og Double Ratchet (kort forklart)

X3DH løser problemet «jeg vil snakke med Bob nå, men Bob svarer ikke før senere». Bob legger ut en prekey bundle på serveren. Alice henter den, gjør 3 eller 4 DH-operasjoner (avhengig av om engangsnøkkel brukes), og deriverer en felles rot-nøkkel som begge kan rekonstruere uten at serveren kjenner hemmeligheten.

Double Ratchet bruker den roten som startpunkt. For hver melding (eller ved nye DH-nøkler) avledes nye nøkler; meldinger på ledningen er AES-GCM med autentisering (AAD binder kryptoteksten til ratchet-header). Protokollen håndterer også meldinger i feil rekkefølge innenfor grenser (MAX_SKIP).

Spesifikasjoner fra Signal (engelsk): X3DH · Double Ratchet.

Bruke Shade i flere prosjekter

Tenk på Shade som tre lag du kan kombinere etter behov:

Core + crypto-provider + storage — selve E2EE-motoren (kan kjøre i klient eller serverprosess som skal dekryptere).
Proto — når du vil ha kompakt binær serialisering.
Transport + prekey-server — når du vil standardisere nøkkelutveksling og kanaler.

Referansekjøring: bun demo.ts i rotmappen viser frontend/backend-flyt med minnelager og ekte kryptoprimitiver.