From 8b055912b7fc78fd1a99e8c94c875087e03ad9b7 Mon Sep 17 00:00:00 2001 From: Sterister Date: Sat, 2 May 2026 14:11:42 +0200 Subject: [PATCH] docs(readme): reflect @shade/files + @shade/streams + @shade/transfer + 0.3.0 wire bump MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Top-of-file callout for the 0.2.x → 0.3.0 wire incompatibility. - "What you get" picks up E2EE file transfers + filesystem RPC bullets. - Quick start gains a `Shade.files.serve()` / `.client()` snippet. - Packages table adds @shade/streams, @shade/transfer, @shade/files; @shade/sdk and @shade/widgets descriptions extended for the new APIs. - Documentation index links docs/files.md, docs/streams.md, examples/07 and 08. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 024ed07..e40ed1e 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ End-to-end encryption library implementing the Signal Protocol (X3DH + Double Ratchet) for TypeScript/Bun. Drop into any project — frontend, backend, mobile — to get forward secrecy, post-compromise recovery, and self-healing security. +> **0.3.0 — wire format breaking change.** The wire VERSION was bumped from +> `0x01` to `0x02` (length prefixes u16 → u32) to support inline file ops up +> to 256 KiB. **0.3.x peers cannot interoperate with 0.2.x peers** — both +> ends must upgrade. See [CHANGELOG.md](./CHANGELOG.md) for the full diff. + ## What you get - **X3DH** initial key agreement (works asynchronously via prekey bundles) @@ -14,6 +19,8 @@ End-to-end encryption library implementing the Signal Protocol (X3DH + Double Ra - **Binary wire format** that's significantly smaller than JSON - **Crash-safe** — sessions survive container restarts, power outages, SIGKILL - **Live observability** — bundled dashboard SPA + embeddable React widgets to see what's happening between every step +- **E2EE file transfers** — multi-lane chunked uploads/downloads with resume, integrity checks, and HTTP/WS fallback (`@shade/streams` + `@shade/transfer`) +- **E2EE filesystem RPC** — typed `list/stat/mkdir/delete/move/read/write/getThumbnail` + custom ops between peers, with rate-limit, retention, and fingerprint-gate hooks (`@shade/files`) ## Quick start @@ -64,6 +71,25 @@ const plaintext = await shade.receive('alice@example.com', incomingEnvelope); console.log(await shade.fingerprint); ``` +Need to ship a file or expose a filesystem to a peer? `Shade.files` is the high-level entrypoint: + +```ts +// Server side — Bob exposes a virtual filesystem +const stop = await shade.files.serve({ + list: async (ctx) => ({ entries: await readdirAt(ctx.path), hasMore: false }), + read: async (ctx) => readAt(ctx.path), // returns inline ≤ 256 KiB or streams + write: async (ctx) => writeAt(ctx.args), // receives inline or streams + // + stat, mkdir, delete, move, getThumbnail, plus typed custom ops +}); + +// Client side — Alice consumes Bob's filesystem +const fs = await shade.files.client('bob'); +await fs.write('/photos/cover.png', new Uint8Array(...)); // auto inline/streams +const result = await fs.read('/photos/cover.png'); +``` + +Files ≤ 256 KiB ride inline in the RPC envelope; larger files automatically promote to multi-lane `@shade/transfer` streams with sha256 integrity. See [`docs/files.md`](./docs/files.md) for the full API. + Or use the lower-level packages directly if you need full control: ```ts @@ -111,10 +137,13 @@ await manager.initialize(); | `@shade/server` | Prekey server (Hono routes, auth, rate limit, health, metrics) | | `@shade/transport` | HTTP + WebSocket transport wrappers with auto-encryption | | `@shade/proto` | Compact binary wire format (smaller than JSON) | +| `@shade/streams` | Multi-lane chunk encryption — HKDF-derived per-lane keys, deterministic AES-GCM nonces, streaming SHA-256 | +| `@shade/transfer` | Transfer engine on top of streams: parallel lanes, resume, HTTP + WS transport with auto-fallback, integrity verification | +| `@shade/files` | Typed E2EE filesystem RPC — list/stat/mkdir/delete/move/read/write/getThumbnail + custom ops, auto inline/streams routing, production hooks (rate limit, retention, fingerprint gate, metrics), React hooks | | `@shade/observer` | Live debugger backend (snapshot, SSE, dashboard) — see [README](./packages/shade-observer/README.md) | -| `@shade/widgets` | Embeddable React widgets — see [README](./packages/shade-widgets/README.md) | +| `@shade/widgets` | Embeddable React widgets including transfer uploader/downloader — see [README](./packages/shade-widgets/README.md) | | `@shade/dashboard` | Standalone dashboard SPA bundled into the observer | -| `@shade/sdk` | High-level wrapper with `createShade()` one-liner, auto-publish, auto-establish, auto-replenish | +| `@shade/sdk` | High-level wrapper with `createShade()` one-liner, auto-publish, auto-establish, auto-replenish, `Shade.files` namespace | | `@shade/cli` | `shade init` scaffolder + utilities (fingerprint, rotate, peer, dashboard, doctor) | ## Shade as a modular toolkit @@ -156,9 +185,13 @@ bun run publish:all ## Documentation - [docs/SHADE-BY-SCENARIO.md](./docs/SHADE-BY-SCENARIO.md) — **Modular toolkit**: pick packages by scenario (messages, files, browser, ops) +- [docs/files.md](./docs/files.md) — `@shade/files` API + design (filesystem RPC, custom ops, hooks, React) +- [docs/streams.md](./docs/streams.md) — `@shade/streams` + `@shade/transfer` deep dive - [SECURITY.md](./SECURITY.md) — Reporting vulnerabilities, security policy - [THREAT-MODEL.md](./THREAT-MODEL.md) — Honest threat model and assumptions -- [examples/](./examples/) — Runnable example applications +- [examples/](./examples/) — Runnable example applications, including + [`07-streams-upload`](./examples/07-streams-upload) (multi-lane file transfer) + and [`08-files-browser`](./examples/08-files-browser) (filesystem RPC) - [MIGRATION.md](./MIGRATION.md) — How to replace existing crypto with Shade ## Deployment — one container per project