Files
Shade/packages/shade-recovery
Sterister d47774ef1c
Some checks failed
Test / test (push) Has been cancelled
Cross-platform vectors / TypeScript vectors (bun) (push) Has been cancelled
Cross-platform vectors / Kotlin vectors (gradle) (push) Has been cancelled
release(v4.8.3): cross-channel msgId dedup + Shade.aliasSession
Two follow-ups to the V4.8.2 duplicate-fan-out fixes Prism filed.

1. `Inbox.acceptBridgeFrame(blob)` + shared 4096-entry msgId LRU.
   The relay durably stores blobs and pushes them to every active
   delivery channel; without a cross-channel ack the bridge frame
   ran first and the next inbox-poll re-dispatched the same blob
   ~30 s later, tripping on consumed prekeys. Bridge consumers now
   plumb pushed frames through `acceptBridgeFrame`, which shares
   the dedup gate + ack path with `pollOnce`. Whichever channel
   delivers first wins; the other acks-and-skips. Inbox records
   the msgId before the ack so a parallel poll can't observe an
   in-flight ack window.

2. `Shade.aliasSession(oldLabel, newLabel)`. First-contact forces
   the receiver to label the new session by the relay's sender
   fingerprint hint (`fp:<senderfp>`); the post-decrypt plaintext
   typically announces the peer's real address. Aliasing moves
   session, trusted identity, peer-verification, and identity-
   version under the canonical label. Holds the per-peer mutex on
   both labels (lexicographic order) so concurrent crypto ops can't
   observe a half-moved state. Refuses to overwrite an existing
   session at the new label.

Wire change: `IncomingMessage.expiresAt?` now surfaces the relay's
expiry so receivers can pass bridge frames straight to
`acceptBridgeFrame` without inventing a TTL.

Tests cover bridge-then-poll, poll-then-bridge, aliasSession happy
path, refuse-to-overwrite, and same-label no-op.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 15:49:36 +02:00
..

@shade/recovery

Social key recovery for Shade — V3.10.

Shamir Secret Sharing over GF(2^8) splits the user's identity backup key into n shares; any threshold-many k together reconstruct the identity onto a new device. Distribution and reconstruction ride existing 1:1 Shade sessions — no centralized recovery agent.

Install

bun add @shade/recovery

Quick wire-up

import {
  setupRecovery,
  attachGuardian,
  requestRecovery,
  MemoryRecoveryStore,
} from '@shade/recovery';

// Primary (Alice's existing device)
await setupRecovery({
  shade,
  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
  threshold: 3,
  deliver: async (to, envelope) => myOutbox.send(to, envelope),
});

// Each guardian
attachGuardian({
  shade,
  store: new MemoryRecoveryStore(),    // swap for persistent store in prod
  approve: async (ctx) => askUser(ctx),
  deliver: async (to, envelope) => myOutbox.send(to, envelope),
});

// New device (Alice on a fresh phone)
await requestRecovery({
  shade: tempShade,
  originalAddress: 'alice',
  setupId: '<from recovery card>',
  threshold: 3,
  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
  deliver: async (to, envelope) => myOutbox.send(to, envelope),
});

See docs/recovery.md for the full threat model, persistence recommendations, and guardian-UX guidance.

Tests

bun test                    # all
bun test tests/shamir       # Shamir primitives
bun test tests/integration  # 3-of-5 end-to-end
bun test tests/adversarial  # k-1 collusion + forged shares + OOB-gate