Files
Shade/packages/shade-recovery
Sterister a98ea8a1bd
Some checks failed
Test / test (push) Has been cancelled
release(v4.8.4): server-side cross-channel dedup via BridgeDeliveryLog
V4.8.3 shipped client-side cross-channel dedup hook
(`Inbox.acceptBridgeFrame`), but recipients that didn't migrate to
the new wiring still observed the same envelope twice — once via
WS bridge push, again ~30 s later via inbox-poll. Prism re-verified
the FR after 4.8.3 and asked for a relay-side enforcement so app
code doesn't have to ack-via-DELETE on every bridge frame.

V4.8.4 adds an in-memory `BridgeDeliveryLog` (default 60 s grace,
8192-per-address cap) that records every successful WS / SSE /
long-poll push of `(address, msgId)`. The `/v1/inbox/:addr/fetch`
route filters out blobs in the log's grace window so a recipient
running both a bridge and the 30 s poll cadence sees exactly one
delivery. Cursor advances over the full fetched window so a poll
that straddles a suppressed blob doesn't stall.

The standalone server auto-wires the log between
`createBridgeRoutes` and `createInboxRoutes`. Custom mounts thread
the same instance through `bridgeDeliveryLog` on both factories.

Tests cover WS-then-poll, SSE-then-poll, and a negative control
(non-bridge-pushed blob still comes through inbox-fetch).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 16:31:42 +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