release(v4.1.0): browser-friendly HTTP RPC for @shade/files

Default shade.files.client(peer) requires both peers to be mutually
addressable over HTTP — the response round-trips through
Shade.deliverControlEnvelope (POST to peer's /v1/transfer/control).
Browser tabs can't host an HTTP server, so they couldn't consume
@shade/files at all. Dispatch's filutforsker (admin-panel browser UI)
is the canonical use-case.

This release adds a parallel request-response transport: one POST per
RPC, encrypted envelope in the body, encrypted response in the same
HTTP response. No inbound channel needed on the client.

### New API

- shade.files.rpcRoute(opts?) — Hono app exposing POST /rpc.
- shade.files.httpClient(peer, opts) — request-response FileClient.
- FilesNamespace.serve(handler, { inlineOnly: true }) — skip streams-
  bridge (and its configureTransfers pre-condition); also skip
  channel-based dispatch so requests aren't double-dispatched.

### Limitations (v1)

Inline only (≤ 256 KiB). Streamed reads/writes throw clear errors
directing to shade.files.client(peer) on a server-to-server deploy.

### Tests

7 integration tests in tests/integration/http-rpc.test.ts covering
round-trip + negative cases (sender header, empty/garbage body,
maxBodyBytes, rpcRoute-without-serve).

### Symmetry

Mirrors @shade/server's shade-auth-middleware: encrypted envelope in
request body, decrypted via existing ratchet, response in same HTTP
roundtrip. No WebSocket, no SSE, no outbound from server.

Wire-compatible. Source-compatible. Lockstep bump to 4.1.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -5,6 +5,252 @@ All notable changes to Shade are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] — 2026-05-03 — Browser-friendly HTTP RPC for @shade/files
+
+The default `shade.files.client(peer)` requires both peers to be
+mutually addressable over HTTP — the response to a `list` / `read` /
+etc. round-trips through `Shade.deliverControlEnvelope`, which POSTs
+to the peer's `/v1/transfer/control` endpoint. **That doesn't work
+for browsers** — a tab can't host an HTTP server, so the server
+cannot call back outbound.
+
+This release ships a parallel request-response transport. One POST per
+RPC, encrypted envelope in the request body, encrypted response in the
+same HTTP response. Mirrors the way `@shade/server`'s
+`shade-auth-middleware` works for prekey writes.
+
+### Added
+
+#### `@shade/files`
+- `createFilesRpcRoute(shade, handler, options?)` — Hono app exposing
+  `POST /rpc`. Reads `X-Shade-Sender-Address`, decrypts the envelope
+  via the existing ratchet session, dispatches through the attached
+  `FileHandler`, encrypts the result, and returns it in the same HTTP
+  response. Transport-level failures (no session, undecryptable, body
+  too big) return JSON `{ error }` with appropriate 4xx; application-
+  level failures ship encrypted `RpcError` envelopes.
+- `createFilesHttpClient(shade, peer, options)` — request-response
+  `FileClient` for browser-style consumers. Each method (list / stat /
+  mkdir / delete / move / getThumbnail / custom / write inline / read
+  inline) does one HTTP POST and parses the encrypted response. No
+  inbound channel required.
+- `shade.files.rpcRoute(opts?)` — namespace-side getter for the route.
+  Throws if no handler has been attached via `shade.files.serve(...)`
+  first.
+- `shade.files.httpClient(peer, opts)` — namespace-side getter for the
+  client.
+- `FilesNamespace.serve(handler, { inlineOnly: true })` — opt-out flag
+  that skips the streams-bridge setup. Required for HTTP-RPC-only
+  servers (which don't need `configureTransfers({ resolveBaseUrl })`).
+  In `inlineOnly` mode the channel-based dispatcher is also not
+  attached, so requests are dispatched only by the rpc-route — avoids
+  double-dispatch when a browser client and a server-to-server client
+  share the same Shade instance.
+- `ShadeBridge` (exported) gains a `receive(peer, envelope)` member
+  matching `Shade.receive` so server-side rpc-route can decrypt
+  inbound envelopes through the structural surface.
+
+### Wire contract
+
+```
+POST /rpc HTTP/1.1
+Content-Type: application/octet-stream
+X-Shade-Sender-Address: alice@example.com
+
+<wire-encoded ShadeEnvelope wrapping JSON-encoded RpcRequest>
+
+────
+
+200 OK
+Content-Type: application/octet-stream
+
+<wire-encoded ShadeEnvelope wrapping JSON-encoded RpcResponse | RpcError>
+```
+
+### Limitations (v1)
+
+- **Inline payloads only** (≤ 256 KiB). `write` of larger inputs
+  throws `ConflictError` directing callers to `shade.files.client(peer)`
+  on a server-to-server deployment. Streamed `read` results throw
+  `InternalFileError` for the same reason.
+- The X3DH first-message must ride the same RPC route — set
+  `acceptFirstMessage: true` on `rpcRoute({ acceptFirstMessage: true })`
+  when the browser client's first-ever call doubles as the handshake.
+
+### Tests
+
+- `tests/integration/http-rpc.test.ts` — round-trip via HTTP
+  (list / mkdir / stat / write / read / delete) plus negative cases
+  (streamed write rejected, missing sender header, empty body, garbage
+  body, body past `maxBodyBytes`, `rpcRoute()` without `serve()`).
+
+### Migration
+
+`4.0.x → 4.1.0` is wire-compatible and source-compatible. The HTTP
+RPC route is purely additive — no existing code path changes. To
+adopt:
+
+```ts
+// server (was)
+await shade.files.serve(handlerConfig);
+
+// server (HTTP-RPC mode)
+await shade.files.serve(handlerConfig, { inlineOnly: true });
+app.route('/api/v1/shade-files', shade.files.rpcRoute());
+
+// browser client
+const fs = shade.files.httpClient(serverAddress, { rpcUrl: '...' });
+```
+
+## [4.0.2] — 2026-05-03 — Consumer-strict reader-shape fixes
+
+`4.0.1` shipped the `tsc --noEmit` gate that compiles each package
+internally against `lib: ["ES2022"]`. That gate did not catch types
+that only fail when *consumer* code (running with `lib: ["DOM"]` +
+`exactOptionalPropertyTypes`) tries to assign a native browser type
+into one of our locally-defined narrower types.
+
+This release adds a consumer-strict smoke test to the pre-publish
+gate and fixes every collision that smoke uncovered.
+
+### Fixed
+
+#### `@shade/files`
+- `inline-threshold.ts`: rewrote the local `MinimalReader<T>` interface
+  as an explicit disjoint union (`{ done: false; value: T } | { done:
+  true; value?: T | undefined }`) so it accepts every native reader
+  shape — `bun-types` (`value?: undefined`), `lib.dom` (`value?: T`),
+  and `node:stream/web`. The previous flat shape was rejected by
+  consumer projects with `exactOptionalPropertyTypes: true` because
+  the present-branch required `value: T`. **Fixes "Type
+  ReadableStreamReadResult<Uint8Array> is not assignable to
+  { value: Uint8Array | undefined; done: boolean }".**
+- `client/streams-bridge.ts`, `server/streams-bridge.ts`: stash the
+  `setTimeout(...)` return value in a local before calling `.unref?.()`
+  through an explicit `{ unref?: () => void }` cast. The previous
+  fluent `.unref?.()` failed under `lib: ["DOM"]` because DOM types
+  `setTimeout` to `number`, which has no `.unref` even as an optional
+  property.
+
+#### `@shade/sdk`
+- `background.ts`: same `setTimeout` / `setInterval` `.unref?.()` fix.
+
+### Tooling
+
+- New `tests/consumer-strict/` — a tiny "as if I were a downstream app"
+  TypeScript project with its own `tsconfig.json`:
+  `lib: ["ES2022", "DOM", "DOM.Iterable"]`, `types: ["bun-types"]`,
+  `exactOptionalPropertyTypes: true`, `strict: true`,
+  `paths`-mapped to the workspace's `packages/*/src/index.ts`.
+  Three smoke files exercise `@shade/files`, `@shade/sdk`, and
+  `@shade/key-transparency` against the consumer-strict tsconfig.
+- `scripts/typecheck-all.ts` now runs the consumer-strict smoke after
+  the per-package internal type-check. Both must pass before
+  `prepublish:check` (and therefore `publish:dry` / `publish:all`)
+  succeeds.
+
+### Migration
+
+`4.0.1 → 4.0.2` is wire-compatible and source-compatible. No API shape
+changed; only internal typing was tightened.
+
+## [4.0.1] — 2026-05-03 — Strict-TS publishability fixes
+
+`4.0.0` shipped TypeScript source files as the published `main` /
+`types`, which meant every consumer's `tsc` had to compile our code
+under their own strict settings. Several files only compiled inside
+the monorepo (where peer-dep cycles resolve via workspace links and
+the `lib` array doesn't include `DOM`). This release makes all 24
+packages compile cleanly under the strict-flagged tsconfig that ships
+with the repo, and wires a `bun run typecheck` gate into both the
+`publish:dry` and `publish:all` flows so this category of bug cannot
+recur.
+
+### Fixed
+
+#### `@shade/key-transparency`
+- Removed unused imports `IndexAbsenceProof`, `IndexInclusionProof`
+  (`src/manager.ts`), `nodeHash` (`src/index-tree.ts`).
+- `IndexProofWire` is now exported (was a private type that
+  `noUnusedLocals` flagged).
+- Added missing `tsconfig.json` so the package can be type-checked
+  in isolation.
+
+#### `@shade/sdk`
+- KT verifier wiring: `fetchLatestSTH()` and `fetchConsistencyProof()`
+  now have explicit return types (`Promise<STHWire>` and
+  `Promise<{ proof: string[] }>`) so consumers don't see
+  `Promise<unknown>` from `res.json()`.
+- `STHWire` type is now imported from `@shade/key-transparency`.
+- `thumbnail.ts`: cast `globalThis` through `unknown` first when
+  reading optional DOM globals (`OffscreenCanvas`, `createImageBitmap`)
+  so consumer projects that include `lib.dom` don't reject our
+  narrower local types as "insufficiently overlapping".
+
+#### `@shade/files`
+- **Broke the `@shade/sdk` ↔ `@shade/files` dependency cycle.**
+  `@shade/files` no longer imports `Shade` from `@shade/sdk` — every
+  callsite uses a new local `ShadeBridge` interface defined in
+  `src/integration/shade-bridge.ts`. This is the structural surface
+  Shade must satisfy: `myAddress`, `send`, `onMessage`, `upload`,
+  `onIncomingTransfer`, `getFingerprintFor` (required) plus
+  `getObservability`, `deliverControlEnvelope` (optional). The Shade
+  class structurally implements every member, so
+  `createFilesNamespace(this)` from the SDK side compiles regardless
+  of how many copies of `@shade/sdk` a consumer's package manager
+  hoists. **Fixes "this is not assignable to type 'Shade'"** in
+  consumer builds.
+- `<ShadeFilesProvider>` now takes `files: FilesNamespace` as an
+  explicit prop instead of reading `shade.files`. Consumers pass
+  `shade.files` (or any `createFilesNamespace(...)` result for tests)
+  directly.
+- `ShadeFileRpcChannel.send` now raises a clear error when
+  `deliverControlEnvelope` is undefined instead of producing an
+  implicit-undefined-call error at compile time.
+
+#### `@shade/storage-encrypted`
+- Replaced `KeyUsage` (a `lib.dom` type) with a local
+  `WebCryptoKeyUsage` union so the package compiles under
+  `lib: ["ES2022"]` without DOM.
+- Fixed `tsconfig.json` `rootDir` so package-level `bunx tsc` works.
+
+#### `@shade/transport-bridge`
+- `sse-bridge.ts`: cast `res.body.getReader()` to
+  `ReadableStreamDefaultReader<Uint8Array>` so the strict reader-type
+  parity check in the consume loop passes.
+
+#### `@shade/keychain` / `@shade/dashboard`
+- Fixed `tsconfig.json` `rootDir` and `include` so the packages can
+  type-check standalone (and so `vite.config.ts` doesn't get pulled
+  into the dashboard's `rootDir`).
+
+#### `@shade/widgets`
+- Removed unused `ThumbnailMime` import in
+  `components/transfer/ThumbnailPreview.tsx`.
+
+### Tooling
+
+- New `scripts/typecheck-all.ts` — runs `bunx tsc --noEmit` against
+  every workspace package's `tsconfig.json` and fails if any reports
+  errors.
+- New `bun run typecheck` script.
+- `publish:dry` and `publish:all` now run `prepublish:check`
+  (`typecheck` + `test`) before any package is packed or published.
+- `scripts/publish-shade.sh` calls the typecheck-all gate before
+  invoking the publisher.
+
+### Migration
+
+`4.0.0 → 4.0.1` is wire-compatible and source-compatible with one
+exception:
+
+- `<ShadeFilesProvider>` requires a `files` prop. Previously
+  `<ShadeFilesProvider shade={shade}>...</ShadeFilesProvider>` worked;
+  it now must be `<ShadeFilesProvider shade={shade} files={shade.files}>`.
+
+No on-disk schema changes. No package-version-pin changes outside
+the lockstep `4.0.0 → 4.0.1` bump.
+
 ## [4.0.0] — 2026-05-03 — General Availability
 
 Shade 4.0 is the first GA-marked release: every plan from V3.1 through

README.md

@@ -3,37 +3,82 @@
 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.
 
 > **4.0.0 — General Availability.** All V3.1 → V3.12 work is merged,
-> the cross-platform vector suite is green on TS + Kotlin, the threat
-> model has been refreshed for every new surface, and the core stack
-> (X3DH, ratchet, storage encryption, recovery, WebRTC P2P, Key
-> Transparency) has been packaged for external review. The wire
-> format is **unchanged from 0.4.x** — 4.0 peers interoperate with
-> 0.4.x peers byte-for-byte. See
+> the cross-platform vector suite is green on TS + Kotlin (1000 / 1000
+> + 11 / 11), the threat model has been refreshed for every new
+> surface, and the core stack (X3DH, ratchet, storage encryption,
+> recovery, WebRTC P2P, Key Transparency) has been packaged for
+> external review. The wire format is **unchanged from 0.4.x** — 4.0
+> peers interoperate with 0.4.x peers byte-for-byte. See
 > [MIGRATION.md § 0.3.x → 4.0](./MIGRATION.md#migrating-from-03x-to-40-ga)
 > for the upgrade path and [CHANGELOG.md § 4.0.0](./CHANGELOG.md) for
 > the consolidated release notes. Voice / Video have been moved to
 > [V5.0](./docs/V5.0.md), to be built on top of the frozen 4.0
 > baseline.
 
+## Status
+
+| Area | 4.0 status | Pointers |
+|------|-----------|----------|
+| Protocol core (X3DH + ratchet + sender keys) | ✅ Done — frozen | [`packages/shade-core`](./packages/shade-core) |
+| Storage encryption (V3.2) | ✅ Done — opt-in `EncryptedSQLiteStorage` / `EncryptedPostgresStorage`, key sources: passphrase / OS keychain / app-injected | [`docs/storage-encryption.md`](./docs/storage-encryption.md) |
+| Fingerprint gates & trust UX (V3.3) | ✅ Done — `Shade.beforeFirstLargeFile / beforeBackupImport / beforeNewDeviceTrust` | [`docs/trust-ux.md`](./docs/trust-ux.md) |
+| Observability v2 (V3.4) | ✅ Done — OpenTelemetry-shaped events, `/metrics`, observer dashboard | [`docs/observability.md`](./docs/observability.md) |
+| Android parity & cross-platform CI (V3.5) | ✅ Done — TS + Kotlin vector-gate live; Android `KeystoreStorage` is post-GA | [`android/shade-android/README.md`](./android/shade-android/README.md), [`docs/cross-platform.md`](./docs/cross-platform.md) |
+| Async store-and-forward (V3.6) | ✅ Done — `@shade/inbox` + `@shade/inbox-server` | [`docs/inbox.md`](./docs/inbox.md) |
+| Transport bridge (V3.7) | ✅ Done — SSE / long-poll / WS adapters | [`docs/transport.md`](./docs/transport.md) |
+| Web Workers crypto (V3.8) | ✅ Done — lane keys never cross the thread boundary | [`docs/web-workers.md`](./docs/web-workers.md) |
+| Rich file metadata + thumbnails (V3.9) | ✅ Done — in `@shade/files` | [`docs/files.md`](./docs/files.md) |
+| Social key recovery (V3.10) | ✅ Done — Shamir + AEAD-gated reconstruction + guardian widgets | [`docs/recovery.md`](./docs/recovery.md) |
+| WebRTC P2P transport (V3.11) | ✅ Done — `RTCDataChannel` with `MultiTransportFallback([webrtc, http])` | [`docs/webrtc.md`](./docs/webrtc.md) |
+| Key Transparency (V3.12) | ✅ Done — opt-in Merkle log, signed STH, witness gossip | [`docs/key-transparency.md`](./docs/key-transparency.md) |
+| External crypto review | 🟡 Bundle ready — review window open after tag | [`docs/audit/REVIEW-BUNDLE.md`](./docs/audit/REVIEW-BUNDLE.md) |
+| Soak (≥ 2 weeks under load) | 🟡 Harness shipped — operator runs it | [`scripts/soak.ts`](./scripts/soak.ts) (`bun run soak --hours 336`) |
+| Voice / Video / Broadcast | 🔜 V5.0 — built on top of frozen 4.0 stack | [`docs/V5.0.md`](./docs/V5.0.md) |
+
 ## What you get
 
+**Protocol core**
 - **X3DH** initial key agreement (works asynchronously via prekey bundles)
 - **Double Ratchet** for per-message forward secrecy and post-compromise security
-- **Self-authenticated prekey server** (Hono, Docker-ready) with rate limiting, metrics, health checks
-- **Persistent storage backends**: SQLite (zero-config) and PostgreSQL (Drizzle)
+- **Sender keys** for group ratchet (1:N broadcast key derivation)
 - **Identity rotation** with grace period for old sessions
 - **Safety numbers** (Signal-style fingerprints) for out-of-band verification
 - **Constant-time comparisons** and **memory zeroization** for hardened operation
-- **Binary wire format** that's significantly smaller than JSON
+- **Binary wire format** (`@shade/proto`) — significantly smaller than JSON
+
+**Storage**
+- **Persistent backends**: SQLite (zero-config, `bun:sqlite`) and PostgreSQL (Drizzle, FOR UPDATE SKIP LOCKED)
 - **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`)
-- **WebRTC P2P transport (V3.11)** — opt-in `RTCDataChannel` upload path with public-STUN defaults, TURN-relay support, glare-safe peer pool, and automatic `MultiTransportFallback` back to HTTP when NAT traversal fails (`@shade/transport-webrtc`, [docs/webrtc.md](./docs/webrtc.md))
-- **Web Workers crypto** — AEAD, HKDF, HMAC, X25519, Ed25519 and per-lane stream state run in a dedicated worker. 100 MB+ uploads stay smooth without frame drops, lane keys never cross the thread boundary (`@shade/crypto-web/worker`, [docs/web-workers.md](./docs/web-workers.md))
-- **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`)
-- **Async store-and-forward** — deliver to offline recipients via a relay that holds ciphertext-only blobs with TTL, idempotent PUT, signed fetch/ack, and an `onMessageQueued` push-trigger hook (`@shade/inbox` + `@shade/inbox-server`)
-- **Social key recovery** — Shamir-split your identity to `n` guardians; any threshold-many `k` together restore it on a new device. No centralized recovery agent; OOB-fingerprint gate on every guardian release; AES-GCM authenticates the reconstruction (`@shade/recovery` + `<RecoverySetup />` / `<RecoveryRequest />` / `<RecoveryApprove />` widgets, [docs/recovery.md](./docs/recovery.md))
-- **Key Transparency (V3.12)** — opt-in append-only Merkle log over the prekey server. Every `register` / `delete` becomes a signed leaf; every bundle-fetch carries an inclusion proof; an Ed25519-signed Tree Head ties roots to a fixed `log_id`. A `LightWitness` cross-checks STHs across clients so a malicious server that splits its view or rewrites history is caught (`@shade/key-transparency`, [docs/key-transparency.md](./docs/key-transparency.md))
+- **At-rest encryption (V3.2, opt-in)** — AES-256-GCM under per-(table,column) DEKs; key sources: passphrase (scrypt), OS keychain (`@shade/keychain`), or app-injected. Online re-key, no downtime.
+
+**Servers**
+- **Self-authenticated prekey server** (`@shade/server`, Hono, Docker-ready) with rate limiting, metrics, health checks
+- **Async store-and-forward relay** (`@shade/inbox-server`) — TTL-bound ciphertext blobs, signed PUT/FETCH/ACK, idempotent on `(address, msgId)`, per-recipient quota
+- **Bridge transports** (`@shade/transport-bridge`) — WS → SSE → long-poll fallback chain for clients that can't keep a WebSocket open. Same `IncomingMessage` shape across all three.
+- **Standalone container** — one image bundles prekey + inbox + bridge + transfer + KT + observer
+
+**Trust UX**
+- **Fingerprint gates (V3.3)** — `Shade.beforeFirstLargeFile(threshold, handler)`, `beforeBackupImport`, `beforeNewDeviceTrust`. Gates raise `FingerprintNotVerifiedError` on the operations that matter, default-warn TOFU otherwise.
+- **`<FingerprintCompare />` / `<FingerprintGate />`** widgets for the matching UI side.
+
+**File transfer & filesystem**
+- **E2EE file transfers** (`@shade/streams` + `@shade/transfer`) — multi-lane chunked uploads/downloads with resume, integrity checks (per-lane sha256 + overall sha256), HTTP/WS fallback, `MultiTransportFallback` for N-ary demotion
+- **WebRTC P2P transport (V3.11, opt-in)** — `RTCDataChannel` chunk path with public-STUN defaults, TURN-relay support, glare-safe peer pool, automatic fallback to HTTP when NAT traversal fails (`@shade/transport-webrtc`)
+- **Web Workers crypto (V3.8, opt-in)** — AEAD, HKDF, HMAC, X25519, Ed25519 and per-lane stream state run in a dedicated worker. 100 MB+ uploads stay smooth without frame drops; lane keys never cross the thread boundary (`@shade/crypto-web/worker`)
+- **E2EE filesystem RPC** (`@shade/files`) — typed `list/stat/mkdir/delete/move/read/write/getThumbnail` + custom ops, with rate-limit, retention, fingerprint-gate, and metrics hooks. React hooks under `@shade/files/react`.
+
+**Recovery**
+- **Social key recovery (V3.10)** — Shamir-split your identity to `n` guardians; any threshold-many `k` together restore it on a new device. No centralized recovery agent; OOB-fingerprint gate per guardian release; AES-GCM-authenticated reconstruction (`@shade/recovery` + `<RecoverySetup />` / `<RecoveryRequest />` / `<RecoveryApprove />`)
+
+**Verifiable distribution**
+- **Key Transparency (V3.12, opt-in)** — append-only Merkle log over the prekey server. Every `register` / `delete` becomes a signed leaf; every bundle-fetch carries an inclusion proof; an Ed25519-signed Tree Head ties roots to a fixed `log_id`. A `LightWitness` cross-checks STHs across clients so a malicious server that splits its view or rewrites history is caught (`@shade/key-transparency`).
+
+**Observability**
+- **Live observability** — OpenTelemetry-shaped events, bundled dashboard SPA + embeddable React widgets to see what's happening between every step (`@shade/observability` + `@shade/observer` + `@shade/dashboard`)
+
+**Tooling**
+- **CLI** — `shade init` scaffolder, `shade migrate-storage` (V3.2), `shade rotate-storage-key`, `shade fingerprint`, `shade rotate`, `shade peer`, `shade dashboard`, `shade doctor`, `shade backup` (`@shade/cli`)
+- **Soak harness** — `bun run soak --hours 336` for the 2-week GA-stable window (`scripts/soak.ts`)
 
 ## Quick start
 
@@ -84,7 +129,38 @@ 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:
+### Opt-in surfaces (V3.x → 4.0 GA)
+
+All of these are off by default. Wire them only where you need them.
+
+```ts
+// V3.3 — Fingerprint gates: enforce verification on the operations that matter
+shade.beforeFirstLargeFile(10 * 1024 * 1024, async ({ peer, fingerprint }) => {
+  return await ui.confirmSafetyNumberMatches(peer, fingerprint);
+});
+shade.beforeBackupImport(async ({ embeddedFingerprint }) => { /* ... */ });
+shade.beforeNewDeviceTrust(async ({ peer, oldFp, newFp }) => { /* ... */ });
+
+// V3.8 — Web Workers crypto: opt-in, lane keys stay off the main thread
+shade.configureWorkerCrypto({
+  workerUrl: new URL('@shade/crypto-web/worker', import.meta.url),
+});
+
+// V3.11 — WebRTC P2P transport: file transfers ride RTCDataChannel where NAT allows
+import { nativeRtcFactory } from '@shade/transport-webrtc';
+shade.configureWebRTC({
+  factory: nativeRtcFactory(),
+  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+});
+
+// V3.12 — Key Transparency: detect server-side bundle swaps
+const shade = await createShade({
+  prekeyServer: 'https://shade.example.com',
+  keyTransparency: { mode: 'observe-strict', logPublicKey: PINNED_KEY_BYTES_32 },
+});
+```
+
+### Files RPC (`@shade/files`)
 
 ```ts
 // Server side — Bob exposes a virtual filesystem
@@ -97,13 +173,13 @@ const stop = await shade.files.serve({
 
 // 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
+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:
+### Lower-level access
 
 ```ts
 import { ShadeSessionManager } from '@shade/core';
@@ -117,20 +193,43 @@ const manager = new ShadeSessionManager(
 await manager.initialize();
 ```
 
+### At-rest encryption (V3.2)
+
+```ts
+import { KeyManager, EncryptedSQLiteStorage } from '@shade/storage-encrypted';
+
+const km = await KeyManager.open({
+  kind: 'passphrase',
+  passphrase: process.env.SHADE_STORAGE_PASSPHRASE!,
+  salt: loadSaltFromDisk(),
+});
+const storage = await EncryptedSQLiteStorage.open({
+  dbPath: '/data/shade-client.db',
+  keyManager: km,
+});
+```
+
+To migrate an existing 0.3.x SQLite DB in place:
+
+```bash
+shade migrate-storage \
+  --key-source passphrase \
+  --passphrase "$SHADE_STORAGE_PASSPHRASE" \
+  --salt-file /data/shade-client.db.salt
+```
+
 ## Architecture — keys vs. payloads
 
-Shade splits the network into two planes. The **prekey server** only
-sees public keys; **everything else** rides the encrypted Double
-Ratchet between peers. If you remember nothing else from this README,
-remember this picture:
+Shade splits the network into a **public-key plane** (the prekey
+server) and an **encrypted plane** (everything else). The prekey
+server only sees public key material. If you remember nothing else
+from this README, remember this picture:
 
 ```
-              Shade Prekey Server (Hono, public keys only)
+              Shade Prekey Container (Hono — public keys only)
                            │
-                  POST /v1/keys/register   (signed)
-                  GET  /v1/keys/bundle/:address
-                  POST /v1/keys/replenish  (signed)
-                  DELETE /v1/keys/:address (signed)
+        /v1/keys/*     /v1/inbox/*     /v1/bridge/*     /v1/transfer/*
+        /v1/kt/*       /metrics       /healthz   /ready
                            │
         ┌──────────────────┴──────────────────┐
         │                                     │
@@ -142,11 +241,20 @@ remember this picture:
         │◄── Double Ratchet messages ────────►│   ← end-to-end,
         │   (ratchet 0x02 / chunks 0x11)      │     never on the
         │                                     │     prekey server
-        │◄── @shade/transfer chunks ─────────►│
-        │   POST /v1/transfer/:id/chunk        │   ← peer-to-peer
-        │   GET  /v1/transfer/:id/state        │     HTTP, opaque
-        │                                     │     ciphertext
+        │
+        │◄── @shade/transfer chunks ─────────►│   ← peer-to-peer
+        │   POST /v1/transfer/:id/chunk        │     HTTP, opaque
+        │   GET  /v1/transfer/:id/state        │     ciphertext
+        │
+        │◄── @shade/inbox blobs (offline) ───►│   ← TTL-bound
+        │   POST /v1/inbox/:address            │     ciphertext-only
+        │   POST /v1/inbox/:address/fetch      │     relay
+        │
+        │◄── @shade/transport-webrtc ────────►│   ← optional P2P
+        │   RTCDataChannel `shade-transfer/v1` │     `MultiTransportFallback`
+        │                                     │     auto-demotes to HTTP
     SQLiteStorage / PostgresStorage       SQLiteStorage / PostgresStorage
+    + EncryptedSQLiteStorage (V3.2)       + EncryptedSQLiteStorage (V3.2)
         (private keys + sessions)             (private keys + sessions)
 ```
 
@@ -155,17 +263,23 @@ remember this picture:
 - Identity public keys (Ed25519 + X25519)
 - Signed prekeys + one-time prekey bundles
 - Registration / replenish / delete writes, all Ed25519-signed
-- Operator-only metrics, `/health`, and the optional observer
-  dashboard
+- (V3.6) Inbox ciphertext blobs with TTL — same container, separate
+  routes; the relay only sees `address || msgId || ciphertext-bytes`
+- (V3.7) Bridge transports (SSE / long-poll / WS) — also delivered by
+  the same Hono app for clients that can't hold a WebSocket
+- (V3.12, opt-in) KT inclusion proofs + signed tree heads on
+  `/v1/kt/*` — verifiable distribution
+- Operator-only metrics and the optional observer dashboard
 
 ### What does **not** go via the prekey server
 
 - **Message plaintext, ever.** Encrypted ratchet envelopes flow peer-
   to-peer over whatever transport you choose (HTTP, WebSocket, your
-  own broker).
+  own broker, or the inbox relay above — which carries ciphertext only).
 - **File chunks.** `@shade/transfer` POSTs ciphertext directly to the
   receiver's `/v1/transfer/:streamId/chunk` route — the prekey server
-  is not involved.
+  is not involved. With V3.11 + `configureWebRTC()`, chunks ride
+  `RTCDataChannel` peer-to-peer; the relay is bypassed entirely.
 - **Identity private keys.** They never leave the device's storage.
 - **Filesystem RPC.** `@shade/files` rides the Double Ratchet for
   control + small payloads, then promotes to direct `@shade/transfer`
@@ -176,6 +290,8 @@ remember this picture:
 The prekey server is metadata-bearing (see `THREAT-MODEL.md § 2`):
 it sees who registers, who fetches whose bundle, and when. It does
 **not** see message contents, transfer contents, or session state.
+**V3.12 Key Transparency** (opt-in) makes its bundle distribution
+*verifiable* so a malicious server that swaps a bundle is caught.
 
 For the full threat model and mitigations, read
 [THREAT-MODEL.md](./THREAT-MODEL.md). For deployment-time guarantees,
@@ -183,53 +299,84 @@ read [docs/PRODUCTION-CHECKLIST.md](./docs/PRODUCTION-CHECKLIST.md).
 
 ## Packages
 
+All packages publish in lockstep at `4.0.0`.
+
 | Package | Purpose |
 |---------|---------|
-| `@shade/core` | Protocol logic (X3DH, Double Ratchet, session manager, errors, events) |
+| `@shade/core` | Protocol logic (X3DH, Double Ratchet, sender keys, session manager, errors, events) |
+| `@shade/proto` | Compact binary wire format (`0x01` PreKeyMessage, `0x02` RatchetMessage, `0x11` StreamChunk) |
 | `@shade/crypto-web` | SubtleCrypto + @noble/curves provider, in-memory storage. Includes the V3.8 Web Workers entrypoint (`@shade/crypto-web/worker`) — drop-in `WorkerCryptoProvider` plus `createEncryptStream` / `createDecryptStream` TransformStream factories |
-| `@shade/storage-sqlite` | Persistent SQLite storage (zero-config, bun:sqlite) |
-| `@shade/storage-postgres` | PostgreSQL storage with Drizzle for shared databases |
-| `@shade/server` | Prekey server (Hono routes, auth, rate limit, health, metrics) |
-| `@shade/transport` | HTTP + WebSocket transport wrappers with auto-encryption |
+| `@shade/observability` | OpenTelemetry-shaped event bus consumed by `@shade/observer`, server hooks, and the dashboard |
+| `@shade/keychain` | OS keychain bindings (libsecret / Keychain / Credential Manager) used by `@shade/storage-encrypted` and the CLI |
+| `@shade/key-transparency` | Key Transparency (V3.12) — RFC 6962-style append-only Merkle log, address-index commitment, signed tree heads, and a `LightWitness` for split-view detection. Opt-in on both server and client. |
+| `@shade/storage-sqlite` | Persistent SQLite storage (zero-config, `bun:sqlite`); also ships `SqliteInboxStore` |
+| `@shade/storage-postgres` | PostgreSQL storage with Drizzle for shared databases; also ships `PostgresInboxStore` + `PostgresKTLogStore` |
+| `@shade/storage-encrypted` | At-rest encryption (V3.2) — `EncryptedSQLiteStorage` / `EncryptedPostgresStorage`, `KeyManager`, online re-key |
+| `@shade/streams` | Multi-lane chunk encryption — HKDF-derived per-lane keys, deterministic AES-GCM nonces, streaming SHA-256, file metadata + thumbnails (V3.9) |
+| `@shade/transport` | HTTP + WebSocket transport wrappers with auto-encryption; KT-verifying `fetchBundleVerified` |
 | `@shade/transport-bridge` | WS → SSE → long-poll fallback chain (V3.7) — single `IncomingMessage` shape across transports for clients that can't keep a WebSocket open |
 | `@shade/transport-webrtc` | V3.11 P2P chunk transport via `RTCDataChannel`. Plugs into `@shade/transfer` as an `ITransferTransport`; signaling rides Shade's own ratchet. Memory factory + native (`globalThis.RTCPeerConnection`) factory included; `MultiTransportFallback([webrtc, http])` wired automatically when `shade.configureWebRTC()` is called. |
-| `@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/recovery` | Social key recovery (V3.10) — Shamir-split identity to `n` guardians; threshold-many `k` reconstruct on a new device. AES-GCM-authenticated reconstruction; OOB-fingerprint gate per guardian release |
-| `@shade/key-transparency` | Key Transparency (V3.12) — RFC 6962-style append-only Merkle log, address-index commitment, signed tree heads, and a `LightWitness` for split-view detection. Opt-in on both server and client. See [docs/key-transparency.md](./docs/key-transparency.md) |
+| `@shade/server` | Prekey server (Hono routes, auth, rate limit, health, metrics). `createPrekeyServerWithKT(...)` opts into V3.12 KT mode |
 | `@shade/inbox-server` | Async store-and-forward relay (V3.6) — Hono routes, signed PUT/FETCH/DELETE, per-recipient TTL + quota, idempotent on `(address, msgId)`. Bundles into the same standalone container as the prekey server |
 | `@shade/inbox` | Inbox client + durable outgoing queue + receive cursor + push-trigger hook (`onMessageQueued`); composes on top of `Shade.send`/`Shade.receive` for offline-recipient delivery |
+| `@shade/transfer` | Transfer engine on top of streams: parallel lanes, resume, HTTP + WS transport with auto-fallback, `MultiTransportFallback` (N-ary demotion), 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 under `@shade/files/react` |
+| `@shade/recovery` | Social key recovery (V3.10) — Shamir-split identity to `n` guardians; threshold-many `k` reconstruct on a new device. AES-GCM-authenticated reconstruction; OOB-fingerprint gate per guardian release |
 | `@shade/observer` | Live debugger backend (snapshot, SSE, dashboard) — see [README](./packages/shade-observer/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.files` namespace |
-| `@shade/cli` | `shade init` scaffolder + utilities (fingerprint, rotate, peer, dashboard, doctor) |
+| `@shade/sdk` | High-level wrapper with `createShade()` one-liner, auto-publish, auto-establish, auto-replenish, `Shade.files` namespace, fingerprint gates, KT integration, WebRTC opt-in |
+| `@shade/widgets` | Embeddable React widgets — fingerprint compare/gate, recovery setup/request/approve, transfer uploader/downloader, observer panels |
+| `@shade/cli` | `shade init` scaffolder + utilities (fingerprint, rotate, peer, dashboard, doctor, backup, migrate-storage, rotate-storage-key) |
 
 ## Shade as a modular toolkit
 
-Shade is split into packages so each project can depend on **only what it needs**—encrypted messaging, file transfer, prekey hosting, or lower-level building blocks. You do not need one giant stack for every use case.
+Shade is split into packages so each project can depend on **only what it needs**—encrypted messaging, file transfer, prekey hosting, social recovery, KT verification, or lower-level building blocks. You do not need one giant stack for every use case.
 
 For a **plain-language map** (which packages to add, what the prekey server does vs your own wiring, and where to start in code), see **[docs/SHADE-BY-SCENARIO.md](./docs/SHADE-BY-SCENARIO.md)**.
 
 ## Publishing
 
-All packages publish to a self-hosted Gitea npm registry on `gt.zyon.no`.
+All packages publish to a self-hosted Gitea npm registry on `gt.zyon.no`. The Docker image of the standalone container ships at `gt.zyon.no/stian/shade-prekey:<tag>`.
 
 ```bash
 # Bump all packages in lockstep
-bun run version 1.1.0
+bun run version 4.0.1
 
-# Dry-run (pack all tarballs without publishing)
+# Dry-run (pack all tarballs without publishing) — no token required
 bun run publish:dry
 
-# Real publish (requires GITEA_TOKEN env var)
+# Real publish — interactive (prompts for GITEA_TOKEN, checks
+# registry for conflicts, publishes via scripts/publish-all.ts)
 bun run publish:all
 
-# Or via CI: push a git tag v1.1.0 and .gitea/workflows/publish.yml runs
+# Build + push the standalone Docker image
+bun run scripts/build-docker.ts -- --tag 4.0.1 --push
 ```
 
+The interactive `scripts/publish-shade.sh` is the human entrypoint;
+`scripts/publish-all.ts` is the headless variant used by CI and
+`publish:dry`. They share a single `PACKAGES` list (24 entries at
+4.0.0) so the two flows can never drift.
+
+## Soak / GA-stable
+
+Before tagging `4.0.0` as `latest` and recommending production
+upgrades, run the combined soak harness for ≥ 2 weeks:
+
+```bash
+# Full GA window (V4.0 §Soak): 14 days × 24 hours
+bun run soak --hours 336
+
+# Smoke (~3 minutes — ratchet ping-pong, integrity check)
+bun run soak:smoke
+```
+
+The harness fans out N concurrent ratchet pairs, ping-pongs at
+~400 ops/sec/pair, and reports cumulative counters every minute.
+Any exception in any pair is captured and re-raised at shutdown so
+silent failures cannot hide. Wrap it in `systemd-run --user`,
+`nohup`, or a Gitea scheduled job for the actual 2-week window.
+
 ## Security properties
 
 | Property | Description |
@@ -242,27 +389,57 @@ bun run publish:all
 | **Memory zeroization** | Key material is zeroed after use (best-effort in JS) |
 | **Identity verification** | Safety numbers (60 digits) for out-of-band comparison |
 | **Identity rotation** | 7-day grace period for old sessions during rotation |
+| **At-rest encryption** *(V3.2, opt-in)* | AES-256-GCM under per-(table, column) DEKs; AAD binds `(table, column, pk)`; passphrase / OS keychain / app-injected master key; online re-key |
+| **Fingerprint gates** *(V3.3)* | `Shade.beforeFirstLargeFile / beforeBackupImport / beforeNewDeviceTrust` raise `FingerprintNotVerifiedError` on the operations that matter; defaults to TOFU + warning when no gate is registered |
+| **Async store-and-forward** *(V3.6)* | Relay only sees `address || msgId || ciphertext`; idempotent PUT; signed FETCH/ACK; TTL-bounded |
+| **Web-Worker key isolation** *(V3.8)* | Lane keys, identity keys, and ratchet chain keys live inside a dedicated worker; main thread only ferries plaintext via transferable buffers; idle terminate releases worker memory |
+| **Social key recovery** *(V3.10)* | Shamir over GF(2^8); AEAD-authenticated reconstruction (forged shares fail); guardian-side fingerprint gate before share release |
+| **WebRTC P2P transport** *(V3.11)* | Same Double Ratchet authenticates SDP/ICE signaling; chunk frames AEAD-bound to `streamId/laneId/seq`; deterministic glare resolution; `MultiTransportFallback` auto-demotes to HTTP |
 | **Key Transparency** *(V3.12, opt-in)* | Append-only Merkle log + signed tree heads + witness gossip — split-view and history-rewrite are detected by clients |
 
 ## Documentation
 
+**Operator + integrator**
+
 - [docs/SHADE-BY-SCENARIO.md](./docs/SHADE-BY-SCENARIO.md) — **Modular toolkit**: pick packages by scenario (messages, files, browser, ops)
 - [docs/PRODUCTION-CHECKLIST.md](./docs/PRODUCTION-CHECKLIST.md) — Pre-flight gates for going to production
+- [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) — Full deployment guide (Docker, env vars, PostgreSQL, backup, Dokploy)
+- [docs/ROADMAP.md](./docs/ROADMAP.md) — V3.x → 4.0 GA → V5.0 trajectory
+
+**Per-surface deep-dives**
+
 - [docs/files.md](./docs/files.md) — `@shade/files` API + design (filesystem RPC, custom ops, hooks, React)
-- [docs/recovery.md](./docs/recovery.md) — `@shade/recovery` social key recovery (V3.10): Shamir setup, guardian-side gates, threshold tuning
 - [docs/streams.md](./docs/streams.md) — `@shade/streams` + `@shade/transfer` deep dive (incl. hardening + retention)
 - [docs/inbox.md](./docs/inbox.md) — `@shade/inbox` + `@shade/inbox-server` async store-and-forward relay (V3.6)
 - [docs/transport.md](./docs/transport.md) — `@shade/transport-bridge` SSE / long-poll / WS bridge layer (V3.7)
+- [docs/web-workers.md](./docs/web-workers.md) — V3.8 Web Workers crypto: setup, bundler recipes (Vite/Webpack/Rollup), Safari notes, lifecycle, threat-model
+- [docs/recovery.md](./docs/recovery.md) — `@shade/recovery` social key recovery (V3.10): Shamir setup, guardian-side gates, threshold tuning
 - [docs/webrtc.md](./docs/webrtc.md) — `@shade/transport-webrtc` P2P transport (V3.11): NAT-traversal, TURN config, glare resolution, wire format, multi-fallback wiring
 - [docs/key-transparency.md](./docs/key-transparency.md) — `@shade/key-transparency` (V3.12): operator + client onboarding, witness role, recovery procedures
-- [docs/V3.12-DESIGN.md](./docs/V3.12-DESIGN.md) — V3.12 design notat (threat model, RFC 6962 vs CONIKS choice, freshness model, open-questions resolution)
-- [docs/web-workers.md](./docs/web-workers.md) — V3.8 Web Workers crypto: setup, bundler recipes (Vite/Webpack/Rollup), Safari notes, lifecycle, threat-model
+- [docs/storage-encryption.md](./docs/storage-encryption.md) — V3.2 at-rest encryption: design, key sources, rotation
+- [docs/trust-ux.md](./docs/trust-ux.md) — V3.3 fingerprint gates: when each fires, handler patterns, widget integration
+- [docs/observability.md](./docs/observability.md) — V3.4 event bus + dashboard
+- [docs/cross-platform.md](./docs/cross-platform.md) — V3.5 Android parity + cross-platform vector regime
+
+**Threat model + audit**
+
 - [SECURITY.md](./SECURITY.md) — Reporting vulnerabilities, security policy, threat-/test-matrix
-- [THREAT-MODEL.md](./THREAT-MODEL.md) — Honest threat model and assumptions
+- [THREAT-MODEL.md](./THREAT-MODEL.md) — Honest threat model and assumptions (12 numbered sections + residual-risks table)
+- [docs/audit/REVIEW-BUNDLE.md](./docs/audit/REVIEW-BUNDLE.md) — External crypto-review entrypoint (scope, build instructions, reporting)
+- [docs/audit/SCOPE.md](./docs/audit/SCOPE.md) — One-page audit-scope summary
+
+**Migration + history**
+
+- [MIGRATION.md](./MIGRATION.md) — How to replace existing crypto with Shade + the [0.3.x → 4.0 upgrade path](./MIGRATION.md#migrating-from-03x-to-40-ga)
+- [CHANGELOG.md](./CHANGELOG.md) — `4.0.0` GA section + every prior release
+- [docs/archive/](./docs/archive/) — V2.1 / V2.2 / V2.3 backlog and V3.1 → V3.12 implementation plans (all `Status: Done`)
+- [docs/V5.0.md](./docs/V5.0.md) — Voice / Video / Broadcast (post-GA, built on the frozen 4.0 stack)
+
+**Examples**
+
 - [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
 
@@ -274,15 +451,30 @@ docker run -d \
   -v my-project-shade:/data \
   -p 3900:3900 \
   -e SHADE_OBSERVER_TOKEN=change-me-to-at-least-16-chars \
-  gt.zyon.no/stian/shade-prekey:latest
+  gt.zyon.no/stian/shade-prekey:4.0.0
 ```
 
 The container includes:
+
 - **Prekey server** — `/v1/keys/*` REST API
-- **Observer dashboard** — `/shade-observer/dashboard/` (off unless token is set)
+- **Inbox relay (V3.6)** — `/v1/inbox/*` async store-and-forward; enable
+  with `SHADE_INBOX_DB_PATH=/data/inbox.db` (or `SHADE_INBOX_PG_URL`).
+  `SHADE_INBOX_PRUNE_INTERVAL_MINUTES` controls TTL prune cadence.
+- **Bridge transports (V3.7)** — `/v1/bridge/{stream,poll,ws}` SSE +
+  long-poll + WS adapters for clients that can't keep a WebSocket open.
+- **Transfer routes** — `/v1/transfer/*` chunk + state + control routes
+  for `@shade/transfer`.
+- **Key Transparency (V3.12)** — `/v1/kt/*` exposes `log_id`, latest +
+  historical STH, and consistency proofs. Enable with
+  `SHADE_KT_*` env vars; off by default.
+- **Observer dashboard** — `/shade-observer/dashboard/` (off unless
+  `SHADE_OBSERVER_TOKEN` is set)
 - **OpenAPI spec** — `/openapi.yaml` and interactive `/docs` viewer
+  (covers all 27 routes — prekey, inbox, bridge, transfer, KT,
+  observer, `/metrics`, `/healthz`, `/ready`)
 - **Prometheus metrics** — `/metrics`
-- **Health check** — `/health`
+- **Health probes** — `/health` (full), `/healthz` (liveness),
+  `/ready` (readiness)
 - **Stale cleanup** — purges inactive identities automatically
 
 See [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) for the full deployment guide, environment variables, PostgreSQL config, backup strategy, and Dokploy instructions.

docs/archive/V2.1.md

@@ -1,8 +1,11 @@
 # Shade V2.1 — Improvements (infrastructure, storage, operations, security)
 
-This document describes **improvements** agreed for next-generation work on Shade: clearer product story, stronger storage, mobile parity, operational hardening, transfer abuse, and a formal security narrative.
+**Status:** Done — superseded by the V3.1 → V3.12 plans, all of which
+landed in the 4.0 GA release. This document is preserved as historical
+context for the original V2.1 backlog; the concrete deliverables live
+under [`docs/archive/V3.*.md`](./).
 
-**Audience:** **Maintainers and contributors** implementing the changes. Add status fields as items land in code/docs.
+This document describes **improvements** agreed for next-generation work on Shade: clearer product story, stronger storage, mobile parity, operational hardening, transfer abuse, and a formal security narrative.
 
 ---
 

docs/archive/V2.2.md

@@ -1,8 +1,10 @@
 # Shade V2.2 — Feature plan: product, platform, and developer experience
 
-This document gathers **planned features** that extend Shade beyond today’s core (X3DH + Double Ratchet + Streams/transfer): groups, asynchronous delivery, richer file UX, web workers, CLI, API docs, and scaffolding.
+**Status:** Done — superseded by V3.6 (inbox), V3.7 (bridge), V3.8
+(workers), V3.9 (file metadata), V3.10 (recovery), V3.12 (KT). All
+landed in the 4.0 GA release; see [`docs/ROADMAP.md`](../ROADMAP.md).
 
-Add optional per-feature status (Idea / Design / IMP / Done).
+This document gathers **planned features** that extend Shade beyond today’s core (X3DH + Double Ratchet + Streams/transfer): groups, asynchronous delivery, richer file UX, web workers, CLI, API docs, and scaffolding.
 
 ---
 

docs/archive/V2.3.md

@@ -1,5 +1,9 @@
 # Shade V2.3 — Tillit, retention, integrasjon og observability
 
+**Status:** Done — superseded by V3.3 (trust UX), V3.4 (observability),
+V3.10 (recovery), V3.12 (KT). Alt levert i 4.0 GA — se
+[`docs/ROADMAP.md`](../ROADMAP.md).
+
 Dette dokumentet beskriver **høyere ambisjonsnivå** og **plattformkryssende** arbeid: brukertilfeller der tillit må være **eksplisitt**, data må **utkrympes**/ryddes automatisk, apper må **enkelt koble seg på** kjente transportmønstre, og drift må **observere** uten å lekke innhold.
 
 ---

docs/archive/V3.12-DESIGN.md

@@ -1,6 +1,6 @@
 # V3.12 — Key Transparency: Designnotat
 
-**Status:** Approved (in-tree review — markeres `Design` i ROADMAP)
+**Status:** Done — implementert i `@shade/key-transparency` 0.4.0, frosset i 4.0 GA.
 **Forfatter:** Shade-teamet
 **Reviewer-mål:** ekstern crypto-orientert reviewer før produksjons-deploy.
 **Implementasjons-target:** `@shade/key-transparency` + utvidelser i

docs/files.md

@@ -53,6 +53,111 @@ if (result.kind === 'inline') console.log(result.bytes.byteLength);
 else for await (const _chunk of /* result.stream */) { /* ... */ }
 ```
 
+## HTTP RPC — browser-friendly request-response (4.1+)
+
+The default `shade.files.client(peer)` requires both peers to be mutually
+addressable over HTTP — the response to a `list`/`read` etc. round-trips
+through `Shade.deliverControlEnvelope`, which POSTs to the peer's
+`/v1/transfer/control` endpoint. **That doesn't work for browsers** —
+a tab can't host an HTTP server, so the server cannot call back outbound.
+
+`@shade/files` 4.1 ships a parallel **request-response** transport that
+lets browser-style clients fully consume the file-RPC surface without
+any inbound channel. It mirrors the way `@shade/server`'s
+`shade-auth-middleware` works: one POST per RPC, encrypted envelope in
+the request body, encrypted response in the same HTTP response.
+
+### Server side — mount the RPC route
+
+```ts
+// 1. Register the file handler. `inlineOnly: true` skips the
+//    streams-bridge (which would require @shade/transfer).
+await shade.files.serve(handlerConfig, { inlineOnly: true });
+
+// 2. Mount the route on your Hono app under any base path.
+app.route('/api/v1/shade-files', shade.files.rpcRoute());
+//                                         ^^^^^^^^^^^^^^
+//                                         POST <base>/rpc
+```
+
+`rpcRoute()` accepts:
+
+| Option              | Default | Purpose                                                                                            |
+|---------------------|---------|----------------------------------------------------------------------------------------------------|
+| `maxBodyBytes`      | 1 MiB   | Max request body. The protocol caps inline payloads at 256 KiB; the headroom is for base64 inflation + custom-op envelopes. |
+| `acceptFirstMessage`| `false` | Accept `0x01` PreKeyMessage envelopes — required when the RPC route also doubles as the X3DH handshake (browser's first-ever request). |
+
+### Browser client
+
+```ts
+import { createShade } from '@shade/sdk';
+
+const shade = await createShade({
+  prekeyServer: 'https://shade.example.com',
+  storage: 'memory',
+  address: 'alice@example.com',
+});
+
+const fs = shade.files.httpClient('bob@example.com', {
+  rpcUrl: 'https://dispatch.example.com/api/v1/shade-files/rpc',
+  // Optional: thread CSRF / auth tokens, override fetch, etc.
+  headers: { 'X-CSRF-Token': csrfToken },
+});
+
+await fs.mkdir('/photos');
+await fs.write('/photos/cover.png', new Uint8Array([/* ... */]), {
+  contentType: 'image/png',
+});
+const result = await fs.read('/photos/cover.png');
+```
+
+### What works in HTTP-RPC mode
+
+- `list`, `stat`, `mkdir`, `delete`, `move`, `getThumbnail`, `custom<K>` — full parity.
+- `write` — **inline only** (≤ 256 KiB plaintext). Larger inputs throw `ConflictError`.
+- `read` — **inline only**. If the server returns a streamed `read` result, the client throws `InternalFileError` directing callers to the stateful pathway.
+
+### Wire contract
+
+```
+POST /rpc HTTP/1.1
+Content-Type: application/octet-stream
+X-Shade-Sender-Address: alice@example.com
+
+<wire-encoded ShadeEnvelope (0x01 first-time, 0x02 after) wrapping
+ JSON-encoded RpcRequest>
+
+────
+
+200 OK
+Content-Type: application/octet-stream
+
+<wire-encoded ShadeEnvelope (0x02) wrapping JSON-encoded RpcResponse | RpcError>
+```
+
+Transport-level failures (no session, undecryptable envelope, body too
+big) return JSON `{ "error": "..." }` with appropriate 4xx status.
+Application-level failures (file not found, permission denied) ship
+encrypted `RpcError` envelopes — the client maps them back to typed
+`FileError` subclasses (`NotFoundError`, `ConflictError`, etc.).
+
+### Symmetry with `@shade/server`
+
+The shape mirrors `@shade/server`'s shade-auth-middleware: encrypted
+envelope rides the request body, server decrypts via the existing
+ratchet session, performs the protected operation, returns an encrypted
+envelope in the response. No bidirectional channel required, no
+WebSocket, no SSE.
+
+### When to use which
+
+| Setup                                         | Use                                           |
+|-----------------------------------------------|-----------------------------------------------|
+| Browser client ↔ Bun/Hono server              | `httpClient()` + `rpcRoute()`                 |
+| Server ↔ server (both can host HTTP)          | `client()` (default) — supports streams       |
+| Service-worker / extension ↔ server           | `httpClient()` (no inbound listener)          |
+| CLI / daemon ↔ daemon                         | Either; `client()` if you need streams        |
+
 ## Op surface
 
 | Op             | Args                                     | Result                                  |

package.json

@@ -16,8 +16,10 @@
     "version": "bun run scripts/bump-version.ts",
     "soak": "bun run scripts/soak.ts",
     "soak:smoke": "bun run scripts/soak.ts --hours 0.05 --pairs 4",
-    "publish:dry": "DRY_RUN=1 bun run scripts/publish-all.ts",
-    "publish:all": "bash scripts/publish-shade.sh",
+    "typecheck": "bun run scripts/typecheck-all.ts",
+    "prepublish:check": "bun run typecheck",
+    "publish:dry": "bun run prepublish:check && DRY_RUN=1 bun run scripts/publish-all.ts",
+    "publish:all": "bun run prepublish:check && bash scripts/publish-shade.sh",
     "build:docker": "bun run scripts/build-docker.ts",
     "publish:docker": "bun run scripts/build-docker.ts -- --push"
   },

packages/shade-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/cli",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/cli.ts",
   "bin": {

packages/shade-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/core",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-crypto-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/crypto-web",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-dashboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/dashboard",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

packages/shade-dashboard/tsconfig.json

@@ -8,5 +8,5 @@
     "module": "ESNext",
     "moduleResolution": "bundler"
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src"]
 }

packages/shade-files/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/files",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-files/src/client/client.ts

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import {
   KIND_CUSTOM_V1,
   KIND_DELETE_V1,
@@ -184,7 +184,7 @@ export interface CreateFileClientOptions {
  * transfers that carry the actual bytes.
  */
 export function createFileClient(
-  shade: Shade,
+  shade: ShadeBridge,
   channel: ShadeFileRpcChannel,
   pending: PendingRpcRegistry,
   peerAddress: string,

packages/shade-files/src/client/http-client.ts

@@ -0,0 +1,399 @@
+/**
+ * Browser-friendly request-response `FileClient` for `@shade/files`.
+ *
+ * The default `shade.files.client(peer)` ships RPC envelopes via
+ * `Shade.send` + `Shade.deliverControlEnvelope`, which means the
+ * server has to be able to call back outbound to the client. That
+ * doesn't work for browser tabs (no inbound HTTP listener). This
+ * client posts each RPC envelope to a single server endpoint and
+ * reads the encrypted response from the same HTTP response — pure
+ * request-response, no inbound channel required.
+ *
+ * Inline payloads only (≤ 256 KiB). For larger reads/writes, use the
+ * stateful path: `shade.files.client(peer)` server-to-server, with
+ * `@shade/transfer` chunk routes for content I/O.
+ *
+ * @see {@link createFilesRpcRoute} for the matching server-side route.
+ */
+import type { ZodTypeAny } from 'zod';
+import { decodeEnvelope, encodeEnvelope as encodeWireEnvelope } from '@shade/proto';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
+import {
+  encodeEnvelope as encodeRpcEnvelope,
+  tryParseEnvelope,
+} from '../protocol/envelope-codec.js';
+import {
+  KIND_CUSTOM_V1,
+  KIND_DELETE_V1,
+  KIND_GET_THUMBNAIL_V1,
+  KIND_LIST_V1,
+  KIND_MKDIR_V1,
+  KIND_MOVE_V1,
+  KIND_READ_V1,
+  KIND_STAT_V1,
+  KIND_WRITE_V1,
+} from '../protocol/kinds.js';
+import {
+  CustomArgsSchema,
+  CustomResultSchema,
+  DeleteArgsSchema,
+  DeleteResultSchema,
+  GetThumbnailArgsSchema,
+  GetThumbnailResultSchema,
+  ListArgsSchema,
+  ListResultSchema,
+  MkdirArgsSchema,
+  MkdirResultSchema,
+  MoveArgsSchema,
+  MoveResultSchema,
+  ReadArgsSchema,
+  ReadResultSchema,
+  StatArgsSchema,
+  StatResultSchema,
+  WriteArgsSchema,
+  WriteResultSchema,
+  type ListResult,
+  type MkdirResult,
+  type DeleteResult,
+  type MoveResult,
+  type StatResult,
+  type ThumbnailSize,
+  type WriteResult,
+} from '../schemas/ops.js';
+import {
+  fileErrorFromPayload,
+  CancelledError,
+  InternalFileError,
+  ConflictError,
+} from '../schemas/errors.js';
+import { buildRpcRequest } from '../protocol/rpc-builder.js';
+import { decideInline, INLINE_THRESHOLD, type WriteSource } from './inline-threshold.js';
+import { base64ToBytes, bytesToBase64 } from '../protocol/canonical.js';
+import type {
+  FileClient,
+  ReadOpts,
+  ReadOutput,
+  ThumbnailResult,
+  WriteOpts,
+  CreateFileClientOptions,
+  BaseOpts,
+} from './client.js';
+
+export interface FilesHttpClientOptions
+  extends Omit<CreateFileClientOptions, 'streamsBridge' | 'ioTimeoutMs'> {
+  /**
+   * Server endpoint that hosts `createFilesRpcRoute(...)`. Typically:
+   * `https://server.example.com/api/v1/shade-files/rpc`.
+   */
+  rpcUrl: string;
+  /**
+   * Optional `fetch` override. Defaults to `globalThis.fetch`. Wire a
+   * custom `fetch` to thread auth-cookies, CSRF tokens, or
+   * service-worker interception.
+   */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Extra HTTP headers applied to every RPC POST. Useful for app-level
+   * auth (CSRF, session cookies via custom header, etc.) — these are
+   * orthogonal to the ratchet authentication on the envelope itself.
+   */
+  headers?: Record<string, string>;
+}
+
+interface RoundTripOpts {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  idempotencyKey?: string;
+}
+
+/**
+ * Create a request-response `FileClient` bound to `peerAddress` and a
+ * server-side RPC URL. The session must already be established
+ * (via `shade.initSessionFromBundle(peerAddress, bundle)` or an
+ * incoming first-message). Otherwise the first RPC will fail with
+ * "decrypt failed: no session for peer".
+ */
+export function createFilesHttpClient(
+  shade: ShadeBridge,
+  peerAddress: string,
+  options: FilesHttpClientOptions,
+): FileClient {
+  const rpcUrl = options.rpcUrl;
+  const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const extraHeaders = options.headers ?? {};
+  const defaultTimeoutMs = options.defaultTimeoutMs ?? 30_000;
+  const signRequest = options.signRequest;
+  const senderAddress = shade.myAddress;
+
+  /**
+   * Encrypt + POST + decrypt + parse one RPC round-trip.
+   *
+   * Throws a typed `FileError` subclass when the server returns an
+   * encrypted `RpcError`, or `InternalFileError` for transport-level
+   * failures (network, 4xx/5xx, malformed body).
+   */
+  async function roundTrip<TResult>(
+    kind: string,
+    op: 'list' | 'stat' | 'mkdir' | 'delete' | 'move' | 'read' | 'write' | 'getThumbnail' | 'custom',
+    args: unknown,
+    resultSchema: ZodTypeAny,
+    opts: RoundTripOpts | undefined,
+  ): Promise<TResult> {
+    const requestEnv = await buildRpcRequest({
+      senderAddress,
+      kind,
+      op,
+      args,
+      ...(opts?.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
+      ...(signRequest !== undefined ? { signRequest } : {}),
+    });
+
+    const plaintext = encodeRpcEnvelope(requestEnv);
+    const ratchetEnvelope = await shade.send(peerAddress, plaintext);
+    const wireBytes = encodeWireEnvelope(ratchetEnvelope);
+
+    const ac = new AbortController();
+    const timeoutMs = opts?.timeoutMs ?? defaultTimeoutMs;
+    const timer = setTimeout(
+      () => ac.abort(new Error(`RPC timeout after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    (timer as unknown as { unref?: () => void }).unref?.();
+    if (opts?.signal !== undefined) {
+      const userSignal = opts.signal;
+      if (userSignal.aborted) ac.abort(userSignal.reason);
+      else userSignal.addEventListener('abort', () => ac.abort(userSignal.reason), { once: true });
+    }
+
+    let response: Response;
+    try {
+      // Wrap the wire bytes in a Blob so the body type satisfies the
+      // common-denominator `BodyInit` across DOM, Bun, and node-fetch
+      // (some runtimes accept `Uint8Array` directly, others don't).
+      // Cast through `unknown` because TS's `bun-types` and `lib.dom`
+      // disagree about whether `Uint8Array<ArrayBufferLike>` is itself
+      // a `BlobPart`; the runtime accepts it on every platform.
+      response = await fetchFn(rpcUrl, {
+        method: 'POST',
+        body: new Blob([wireBytes as unknown as ArrayBuffer]),
+        signal: ac.signal,
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'X-Shade-Sender-Address': senderAddress,
+          ...extraHeaders,
+        },
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if ((err as Error).name === 'AbortError') {
+        throw new CancelledError(`RPC ${kind} aborted: ${(err as Error).message}`);
+      }
+      throw new InternalFileError(`RPC ${kind} fetch failed: ${(err as Error).message}`);
+    }
+    clearTimeout(timer);
+
+    if (!response.ok) {
+      let body: { error?: string } | null = null;
+      try {
+        body = (await response.json()) as { error?: string };
+      } catch {
+        /* server emitted non-JSON body */
+      }
+      throw new InternalFileError(
+        `RPC ${kind} → ${response.status} ${response.statusText}: ${
+          body?.error ?? '(no error body)'
+        }`,
+      );
+    }
+
+    const ab = await response.arrayBuffer();
+    if (ab.byteLength === 0) {
+      throw new InternalFileError(`RPC ${kind}: empty response body`);
+    }
+
+    let responseRatchet;
+    try {
+      responseRatchet = decodeEnvelope(new Uint8Array(ab));
+    } catch (err) {
+      throw new InternalFileError(
+        `RPC ${kind}: response body is not a valid wire envelope: ${(err as Error).message}`,
+      );
+    }
+    let responsePlaintext: string;
+    try {
+      responsePlaintext = await shade.receive(peerAddress, responseRatchet);
+    } catch (err) {
+      throw new InternalFileError(
+        `RPC ${kind}: response decrypt failed: ${(err as Error).message}`,
+      );
+    }
+    const classified = tryParseEnvelope(responsePlaintext);
+    if (classified === null) {
+      throw new InternalFileError(
+        `RPC ${kind}: response plaintext is not a valid @shade/files envelope`,
+      );
+    }
+    if (classified.kind === 'error') {
+      throw fileErrorFromPayload(classified.envelope.error);
+    }
+    if (classified.kind !== 'response') {
+      throw new InternalFileError(
+        `RPC ${kind}: unexpected response envelope kind: ${classified.kind}`,
+      );
+    }
+    if (classified.envelope.id !== requestEnv.id) {
+      throw new InternalFileError(
+        `RPC ${kind}: response correlation id mismatch (got ${classified.envelope.id}, expected ${requestEnv.id})`,
+      );
+    }
+    return resultSchema.parse(classified.envelope.result) as TResult;
+  }
+
+  return {
+    async list(path, opts): Promise<ListResult> {
+      const args = ListArgsSchema.parse({
+        path,
+        ...(opts?.cursor !== undefined ? { cursor: opts.cursor } : {}),
+        ...(opts?.pageSize !== undefined ? { pageSize: opts.pageSize } : {}),
+        ...(opts?.filter !== undefined ? { filter: opts.filter } : {}),
+      });
+      return await roundTrip<ListResult>(
+        KIND_LIST_V1,
+        'list',
+        args,
+        ListResultSchema,
+        opts,
+      );
+    },
+
+    async stat(path, opts): Promise<StatResult> {
+      const args = StatArgsSchema.parse({ path });
+      return await roundTrip<StatResult>(KIND_STAT_V1, 'stat', args, StatResultSchema, opts);
+    },
+
+    async mkdir(path, opts): Promise<MkdirResult> {
+      const args = MkdirArgsSchema.parse({
+        path,
+        ...(opts?.recursive !== undefined ? { recursive: opts.recursive } : {}),
+      });
+      return await roundTrip<MkdirResult>(
+        KIND_MKDIR_V1,
+        'mkdir',
+        args,
+        MkdirResultSchema,
+        opts,
+      );
+    },
+
+    async delete(path, opts): Promise<DeleteResult> {
+      const args = DeleteArgsSchema.parse({
+        path,
+        ...(opts?.recursive !== undefined ? { recursive: opts.recursive } : {}),
+      });
+      return await roundTrip<DeleteResult>(
+        KIND_DELETE_V1,
+        'delete',
+        args,
+        DeleteResultSchema,
+        opts,
+      );
+    },
+
+    async move(src, dst, opts): Promise<MoveResult> {
+      const args = MoveArgsSchema.parse({
+        src,
+        dst,
+        ...(opts?.overwrite !== undefined ? { overwrite: opts.overwrite } : {}),
+      });
+      return await roundTrip<MoveResult>(KIND_MOVE_V1, 'move', args, MoveResultSchema, opts);
+    },
+
+    async read(path, opts: ReadOpts = {}): Promise<ReadOutput> {
+      const args = ReadArgsSchema.parse({
+        path,
+        ...(opts.range !== undefined ? { range: opts.range } : {}),
+        ...(opts.preferInline !== undefined ? { preferInline: opts.preferInline } : {}),
+      });
+      const wire = await roundTrip<import('../schemas/ops.js').ReadResult>(
+        KIND_READ_V1,
+        'read',
+        args,
+        ReadResultSchema,
+        opts,
+      );
+      if (wire.kind !== 'inline') {
+        // The HTTP RPC route does not service streamed reads — there is
+        // no place to stream from in pure request-response.
+        throw new InternalFileError(
+          `http RPC client received a streamed read (size ${wire.size}). Use shade.files.client(peer) on a server-to-server deployment, or pass { preferInline: true } when the file is known to fit inline.`,
+        );
+      }
+      const bytes = base64ToBytes(wire.bytesB64);
+      const out: ReadOutput = {
+        kind: 'inline',
+        bytes,
+        size: wire.size,
+        sha256: wire.sha256,
+        ...(wire.contentType !== undefined ? { contentType: wire.contentType } : {}),
+      };
+      return out;
+    },
+
+    async write(path, input: WriteSource, opts: WriteOpts = {}): Promise<WriteResult> {
+      const decision = await decideInline(input);
+      const overwrite = opts.overwrite ?? false;
+      const contentType = opts.contentType ?? decision.contentType;
+
+      if (decision.kind !== 'inline') {
+        throw new ConflictError(
+          `http RPC client supports inline writes only (≤ ${INLINE_THRESHOLD} bytes). The supplied input was promoted to streams (size ${decision.size ?? 'unknown'}). Use shade.files.client(peer) for streamed writes, or pre-buffer the input below the inline threshold.`,
+        );
+      }
+      const args = WriteArgsSchema.parse({
+        kind: 'inline',
+        path,
+        bytesB64: bytesToBase64(decision.bytes),
+        ...(contentType !== undefined ? { contentType } : {}),
+        overwrite,
+      });
+      return await roundTrip<WriteResult>(
+        KIND_WRITE_V1,
+        'write',
+        args,
+        WriteResultSchema,
+        opts,
+      );
+    },
+
+    async getThumbnail(path, size: ThumbnailSize, opts): Promise<ThumbnailResult> {
+      const args = GetThumbnailArgsSchema.parse({
+        path,
+        size,
+        ...(opts?.format !== undefined ? { format: opts.format } : {}),
+      });
+      const raw = await roundTrip<import('../schemas/ops.js').GetThumbnailResult>(
+        KIND_GET_THUMBNAIL_V1,
+        'getThumbnail',
+        args,
+        GetThumbnailResultSchema,
+        opts,
+      );
+      return {
+        bytes: base64ToBytes(raw.bytesB64),
+        format: raw.format,
+        width: raw.width,
+        height: raw.height,
+        sha256: raw.sha256,
+      };
+    },
+
+    async custom(name, args, opts?: BaseOpts): Promise<unknown> {
+      const wireArgs = CustomArgsSchema.parse({ name, args });
+      return await roundTrip(KIND_CUSTOM_V1, 'custom', wireArgs, CustomResultSchema, opts);
+    },
+
+    close(): void {
+      // Stateless — nothing to release. Exists for FileClient symmetry.
+    },
+  } as FileClient;
+}

packages/shade-files/src/client/inline-threshold.ts

@@ -161,15 +161,33 @@ async function peekStream(stream: ReadableStream<Uint8Array>): Promise<InlineDec
   }
 }
 
-interface MinimalReader {
-  read(): Promise<{ value: Uint8Array | undefined; done: boolean }>;
+/**
+ * Structural mirror of WHATWG `ReadableStreamDefaultReader<Uint8Array>`.
+ *
+ * The disjoint union shape with `value?: T | undefined` is the lowest
+ * common denominator across every lib environment we care about:
+ * - `bun-types` emits `{ done: true; value?: undefined }`
+ * - `lib.dom`   emits `{ done: true; value?: T }`
+ * - `node:stream/web` emits the union form
+ *
+ * `value?: T | undefined` is assignable from all three. A flat
+ * `{ value?: T; done: boolean }` is rejected by
+ * `exactOptionalPropertyTypes` because the present branches require
+ * `value: T`. Defining it as an explicit union avoids the trap.
+ */
+type MinimalReadResult<T> =
+  | { done: false; value: T }
+  | { done: true; value?: T | undefined };
+
+interface MinimalReader<T> {
+  read(): Promise<MinimalReadResult<T>>;
   cancel(reason?: unknown): Promise<void>;
   releaseLock(): void;
 }
 
 function reconstructStream(
   prefix: Uint8Array[],
-  reader: MinimalReader,
+  reader: MinimalReader<Uint8Array>,
 ): ReadableStream<Uint8Array> {
   let prefixIdx = 0;
   return new ReadableStream<Uint8Array>({

packages/shade-files/src/client/streams-bridge.ts

@@ -142,13 +142,14 @@ export async function createClientStreamsBridge(
     }
 
     parked.set(readStreamId, arrival);
-    setTimeout(() => {
+    const t = setTimeout(() => {
       const stale = parked.get(readStreamId);
       if (stale === arrival) {
         parked.delete(readStreamId);
         void handle.abort('rpc-timeout').catch(() => undefined);
       }
-    }, parkedReadTtlMs).unref?.();
+    }, parkedReadTtlMs);
+    (t as unknown as { unref?: () => void }).unref?.();
   });
 
   function cleanupWaiter(w: PendingReadWaiter): void {

packages/shade-files/src/index.ts

@@ -183,6 +183,19 @@ export { MAX_SIGNATURE_AGE_MS } from './server/handler.js';
 export { createFilesNamespace } from './integration/files-namespace.js';
 export type { FilesNamespace } from './integration/files-namespace.js';
 
+// Request-response HTTP transport — for browser-style consumers
+// (one HTTP POST per RPC, no inbound channel needed). See
+// `docs/files.md § HTTP RPC`.
+export { createFilesRpcRoute } from './server/rpc-route.js';
+export type { FilesRpcRouteOptions } from './server/rpc-route.js';
+export { createFilesHttpClient } from './client/http-client.js';
+export type { FilesHttpClientOptions } from './client/http-client.js';
+
+// Shared structural surface @shade/files needs from a Shade instance —
+// exposed so consumers building custom Shade-shaped bridges can verify
+// they implement every required member.
+export type { ShadeBridge } from './integration/shade-bridge.js';
+
 // Integration helpers — wire handler + pending registry onto a channel
 export { attachFileHandler } from './integration/wire-server.js';
 export { attachClientRouting } from './integration/wire-client.js';

packages/shade-files/src/integration/files-namespace.ts

@@ -4,13 +4,16 @@
  * so a single Shade can simultaneously serve files AND consume them from
  * peers without paying the setup cost twice.
  */
-import type { Shade } from '@shade/sdk';
+import type { Hono } from 'hono';
+import type { ShadeBridge } from './shade-bridge.js';
 import {
   attachClientRouting,
   attachFileHandler,
   createClientStreamsBridge,
   createFileClient,
   createFileHandler,
+  createFilesHttpClient,
+  createFilesRpcRoute,
   createServerStreamsBridge,
   PendingRpcRegistry,
   ShadeFileRpcChannel,
@@ -19,22 +22,79 @@ import {
   type FileClient,
   type FileHandler,
   type FileHandlerConfig,
+  type FilesHttpClientOptions,
+  type FilesRpcRouteOptions,
   type ServerStreamsBridge,
 } from '../index.js';
 import { IdempotencyCache } from '../server/idempotency-cache.js';
 
+export interface ServeOptions {
+  /**
+   * Skip the streams bridge setup. Required for deployments that only
+   * use the HTTP RPC route ({@link FilesNamespace.rpcRoute}) — those
+   * deployments don't need to configure `@shade/transfer` because the
+   * RPC route only services inline payloads (≤ 256 KiB). Without this
+   * flag, `serve()` calls `createServerStreamsBridge(shade)` which
+   * eagerly instantiates the transfer engine and fails when
+   * `configureTransfers({ resolveBaseUrl })` has not been called.
+   *
+   * Default: `false` (build the streams bridge — full server-to-server
+   * stack with streamed reads/writes).
+   */
+  inlineOnly?: boolean;
+}
+
 export interface FilesNamespace {
   /**
    * Register a file handler. Throws if a handler is already attached on
    * this Shade — only one server per Shade. The returned function detaches
    * the handler and tears down its idempotency / retention timers.
+   *
+   * Pass `{ inlineOnly: true }` for HTTP-RPC-only deployments to skip
+   * the streams-bridge setup (and the implied `configureTransfers`
+   * pre-condition).
    */
-  serve(handler: FileHandlerConfig): Promise<() => Promise<void>>;
+  serve(
+    handler: FileHandlerConfig,
+    options?: ServeOptions,
+  ): Promise<() => Promise<void>>;
   /**
    * Build a typed file client for `peer`. Multiple concurrent clients to
    * different peers share the same channel + streams bridge.
+   *
+   * Use this for **server-to-server** deployments where both peers can
+   * receive inbound HTTP. For browser clients (no inbound listener),
+   * use {@link httpClient} instead.
    */
   client(peer: string, opts?: Omit<CreateFileClientOptions, 'streamsBridge'>): Promise<FileClient>;
+  /**
+   * Build a request-response `FileClient` for browser-style consumers.
+   * Each RPC is one HTTP POST to the supplied `rpcUrl`; the encrypted
+   * response rides back in the same response body. No inbound channel
+   * required on the client side.
+   *
+   * Inline payloads only (≤ 256 KiB). Streamed reads/writes throw a
+   * clear error directing callers to {@link client} instead.
+   *
+   * Pre-condition: the session for `peer` must already be established
+   * (typically via `shade.initSessionFromBundle(peer, bundle)`).
+   */
+  httpClient(peer: string, opts: FilesHttpClientOptions): FileClient;
+  /**
+   * Mount the server-side request-response RPC route. Returns a Hono
+   * app exposing `POST /rpc` that accepts encrypted file-RPC envelopes
+   * and returns encrypted responses in the same HTTP roundtrip.
+   *
+   * Mount under any base path:
+   * ```ts
+   * app.route('/api/v1/shade-files', shade.files.rpcRoute());
+   * ```
+   *
+   * Requires `shade.files.serve(...)` to have been called first —
+   * the route dispatches incoming requests through the attached
+   * handler.
+   */
+  rpcRoute(opts?: FilesRpcRouteOptions): Hono;
   /** Tear down channel + bridges. After destroy(), serve()/client() throw. */
   destroy(): Promise<void>;
 }
@@ -54,7 +114,7 @@ interface NamespaceState {
  * Construct a `FilesNamespace` bound to a Shade instance. The SDK's
  * `Shade.files` getter calls this lazily and memoizes the result.
  */
-export function createFilesNamespace(shade: Shade): FilesNamespace {
+export function createFilesNamespace(shade: ShadeBridge): FilesNamespace {
   const state: NamespaceState = {
     channel: new ShadeFileRpcChannel(shade),
     pending: new PendingRpcRegistry(),
@@ -71,24 +131,39 @@ export function createFilesNamespace(shade: Shade): FilesNamespace {
   }
 
   return {
-    async serve(handlerConfig) {
+    async serve(handlerConfig, options = {}) {
       ensureAlive();
       if (state.serverHandler !== null) {
         throw new Error('FilesNamespace: a handler is already registered (one per Shade)');
       }
-      // Lazy server-side streams bridge.
-      if (state.serverBridge === null) {
+      // Lazy server-side streams bridge — skip when the deployment is
+      // HTTP-RPC-only and does not need `@shade/transfer` wired up.
+      if (!options.inlineOnly && state.serverBridge === null) {
         state.serverBridge = await createServerStreamsBridge(shade);
       }
       const inheritedObservability = shade.getObservability?.();
       const handler = createFileHandler(shade, {
         ...handlerConfig,
-        streamsBridge: state.serverBridge,
+        ...(state.serverBridge !== null
+          ? { streamsBridge: state.serverBridge }
+          : {}),
         ...(handlerConfig.observability === undefined && inheritedObservability !== undefined
           ? { observability: inheritedObservability }
           : {}),
       });
-      const detach = attachFileHandler(state.channel, handler);
+      // In inlineOnly mode, the rpc-route is the sole inbound path —
+      // do NOT also subscribe the channel's onMessage handler to this
+      // file handler, because that would cause every incoming request
+      // to be dispatched twice (once by the rpc-route's direct call,
+      // once by the channel's onMessage handler) and the channel-side
+      // response would attempt an outbound POST via
+      // `deliverControlEnvelope`, which is exactly the path that fails
+      // for browser clients.
+      const detach: () => void = options.inlineOnly
+        ? () => {
+            /* no channel subscription to detach */
+          }
+        : attachFileHandler(state.channel, handler);
       state.serverHandler = handler;
       state.serverDetach = detach;
 
@@ -131,6 +206,21 @@ export function createFilesNamespace(shade: Shade): FilesNamespace {
       });
     },
 
+    httpClient(peer, opts) {
+      ensureAlive();
+      return createFilesHttpClient(shade, peer, opts);
+    },
+
+    rpcRoute(opts = {}) {
+      ensureAlive();
+      if (state.serverHandler === null) {
+        throw new Error(
+          'FilesNamespace.rpcRoute(): no handler attached. Call shade.files.serve(...) before mounting the RPC route.',
+        );
+      }
+      return createFilesRpcRoute(shade, state.serverHandler, opts);
+    },
+
     async destroy() {
       if (state.destroyed) return;
       state.destroyed = true;

packages/shade-files/src/integration/shade-bridge.ts

@@ -0,0 +1,73 @@
+/**
+ * Structural surface @shade/files needs from a Shade instance.
+ *
+ * Defining this locally — instead of `import type { Shade } from '@shade/sdk'`
+ * — breaks the @shade/sdk ↔ @shade/files dependency cycle. Without this
+ * break, a consumer that installs @shade/sdk from a registry ends up with
+ * two distinct `Shade` classes in `node_modules` (one from
+ * `@shade/sdk/node_modules/@shade/files/.../Shade`, one from
+ * `@shade/sdk/Shade`). TypeScript treats them as nominally different types,
+ * raising `this is not assignable to Shade` from inside SDK methods that
+ * pass `this` into `createFilesNamespace`.
+ *
+ * The Shade class structurally implements every member listed below, so
+ * `createFilesNamespace(this)` from the SDK side compiles regardless of
+ * how many copies of @shade/sdk a consumer's package manager installs.
+ *
+ * Member signatures match Shade's exactly so this is a structural
+ * subtype, not a parallel API.
+ */
+import type { ShadeEnvelope } from '@shade/core';
+import type {
+  IncomingTransfer,
+  TransferHandle,
+  TransferOptions,
+} from '@shade/transfer';
+import type { ObservabilityHook } from '@shade/observability';
+
+export interface ShadeBridge {
+  /** Address that names this Shade instance to peers. */
+  readonly myAddress: string;
+
+  /** Encrypt + send `plaintext` to `peer`; returns the wire envelope. */
+  send(peer: string, plaintext: string): Promise<ShadeEnvelope>;
+
+  /**
+   * Decrypt an inbound envelope from `peer` and return the plaintext.
+   * Used by the request-response RPC route on the server side.
+   */
+  receive(peer: string, envelope: ShadeEnvelope): Promise<string>;
+
+  /**
+   * Subscribe to incoming ratchet plaintext. Returns an unsubscribe.
+   * Handlers may be sync or async; async handlers are awaited in
+   * registration order.
+   */
+  onMessage(
+    handler: (from: string, plaintext: string) => void | Promise<void>,
+  ): () => void;
+
+  /**
+   * Upload bytes via the SDK's transfer engine. Required when the bridge
+   * is used with `streams` content I/O (read/write > 256 KiB).
+   */
+  upload(opts: TransferOptions): Promise<TransferHandle>;
+
+  /** Subscribe to incoming transfers initiated by a peer. */
+  onIncomingTransfer(
+    handler: (incoming: IncomingTransfer) => void | Promise<void>,
+  ): Promise<() => void>;
+
+  /** Fingerprint accessor for the trust-gate hooks. */
+  getFingerprintFor(peer: string): Promise<string>;
+
+  /**
+   * Optional inheritable observability bus. Files inherits the bus when
+   * the SDK passes one in via the namespace; otherwise files runs without
+   * observability hooks.
+   */
+  getObservability?(): ObservabilityHook | undefined;
+
+  /** Optional control-envelope passthrough used by the WebRTC bridge. */
+  deliverControlEnvelope?(peer: string, envelope: ShadeEnvelope): Promise<void>;
+}

packages/shade-files/src/protocol/rpc-builder.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared RPC-request construction.
+ *
+ * Both the channel-based `FileClient` (`createFileClient`) and the
+ * HTTP-based `FilesHttpClient` build identical `RpcRequest` envelopes
+ * — they differ only in *transport* (channel.send → ratchet via
+ * Shade.send/onMessage vs HTTP POST → ratchet via single
+ * request-response). This module is the single source of truth for
+ * the wire shape so the two clients can never drift.
+ */
+import type { ZodTypeAny } from 'zod';
+import {
+  KIND_DELETE_V1,
+  KIND_GET_THUMBNAIL_V1,
+  KIND_LIST_V1,
+  KIND_MKDIR_V1,
+  KIND_MOVE_V1,
+  KIND_READ_V1,
+  KIND_STAT_V1,
+  KIND_WRITE_V1,
+  MUTATION_OPS,
+  type StandardOp,
+} from './kinds.js';
+import { generateIdempotencyKey, generateRequestId } from './correlate.js';
+import { canonicalRpcBytes, hashArgs } from './canonical.js';
+import type { RpcRequest } from '../schemas/envelope.js';
+
+export const KIND_BY_OP: Record<StandardOp, string> = {
+  list: KIND_LIST_V1,
+  stat: KIND_STAT_V1,
+  mkdir: KIND_MKDIR_V1,
+  delete: KIND_DELETE_V1,
+  move: KIND_MOVE_V1,
+  read: KIND_READ_V1,
+  write: KIND_WRITE_V1,
+  getThumbnail: KIND_GET_THUMBNAIL_V1,
+};
+
+export type SignRequest = (canonicalBytes: Uint8Array) => Promise<string> | string;
+
+export interface BuildRpcRequestOptions {
+  /** Address that this RPC call originates from. */
+  senderAddress: string;
+  /** RPC kind — `KIND_*_V1` constants for standard ops, `KIND_CUSTOM_V1` otherwise. */
+  kind: string;
+  /** Op classifier so mutations get an auto-generated idempotency key. */
+  op: StandardOp | 'custom';
+  /** Validated args object. The caller is responsible for `Zod.parse(args)`. */
+  args: unknown;
+  /** Caller-supplied idempotency key. Mutations get one auto-generated. */
+  idempotencyKey?: string;
+  /** Optional Ed25519-style signer over the canonical bytes. */
+  signRequest?: SignRequest;
+}
+
+/**
+ * Build a single `RpcRequest` envelope. Generates `id`, `signedAt`,
+ * idempotency key (mutations only), and the canonical signature.
+ */
+export async function buildRpcRequest(
+  options: BuildRpcRequestOptions,
+): Promise<RpcRequest> {
+  const { senderAddress, kind, op, args, signRequest } = options;
+  const requestId = generateRequestId();
+  const isMutation = MUTATION_OPS.has(op);
+  const idempotencyKey =
+    options.idempotencyKey ?? (isMutation ? generateIdempotencyKey() : undefined);
+  const signedAt = Date.now();
+
+  let sig = 'unsigned';
+  if (signRequest !== undefined) {
+    const canonical = canonicalRpcBytes({
+      address: senderAddress,
+      signedAt,
+      kind,
+      id: requestId,
+      argsHash: hashArgs(args),
+    });
+    sig = await signRequest(canonical);
+  }
+
+  const env: RpcRequest = {
+    kind,
+    id: requestId,
+    args,
+    ...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
+    sig,
+    signedAt,
+  };
+  return env;
+}
+
+/**
+ * Helper for the typed standard ops: validates args via the supplied Zod
+ * schema, calls {@link buildRpcRequest}, and forwards the result.
+ *
+ * The HTTP and channel clients both call this from each op-method to
+ * guarantee identical wire-shape. Custom ops use {@link buildRpcRequest}
+ * directly because they ship `KIND_CUSTOM_V1` plus runtime-validated args.
+ */
+export async function buildStandardRpcRequest<TArgs>(
+  schema: { parse(input: unknown): TArgs },
+  rawArgs: unknown,
+  options: Omit<BuildRpcRequestOptions, 'kind' | 'op' | 'args'> & {
+    op: StandardOp;
+  },
+): Promise<{ request: RpcRequest; args: TArgs }> {
+  const args = schema.parse(rawArgs) as TArgs;
+  const kind = KIND_BY_OP[options.op];
+  const request = await buildRpcRequest({
+    ...options,
+    kind,
+    op: options.op,
+    args,
+  });
+  return { request, args };
+}
+
+/**
+ * Validate a returned RpcResponse `result` against the supplied schema.
+ * Centralised so the HTTP and channel clients fail-loudly with the same
+ * error type when a server returns an off-spec response.
+ */
+export function parseResult<T>(schema: ZodTypeAny, raw: unknown): T {
+  return schema.parse(raw) as T;
+}

packages/shade-files/src/react/ShadeFilesProvider.tsx

@@ -1,17 +1,23 @@
 import React, { createContext, useContext, useMemo } from 'react';
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import type { FilesNamespace } from '../integration/files-namespace.js';
 
 export interface ShadeFilesContextValue {
-  shade: Shade;
+  shade: ShadeBridge;
   files: FilesNamespace;
 }
 
 const ShadeFilesContext = createContext<ShadeFilesContextValue | null>(null);
 
 export interface ShadeFilesProviderProps {
-  /** Initialized `Shade` instance. `files` namespace is read off it lazily. */
-  shade: Shade;
+  /** Initialized `Shade` instance (or any `ShadeBridge`-shaped object). */
+  shade: ShadeBridge;
+  /**
+   * The `FilesNamespace` to expose to children. Pass `shade.files` from
+   * `@shade/sdk`, or a `createFilesNamespace(...)` result for tests /
+   * custom bridges.
+   */
+  files: FilesNamespace;
   children: React.ReactNode;
 }
 
@@ -20,8 +26,8 @@ export interface ShadeFilesProviderProps {
  * `<ShadeRuntimeProvider>` in `@shade/widgets` so file-RPC consumers
  * don't pull in the widget tree.
  */
-export function ShadeFilesProvider({ shade, children }: ShadeFilesProviderProps): React.ReactElement {
-  const value = useMemo<ShadeFilesContextValue>(() => ({ shade, files: shade.files }), [shade]);
+export function ShadeFilesProvider({ shade, files, children }: ShadeFilesProviderProps): React.ReactElement {
+  const value = useMemo<ShadeFilesContextValue>(() => ({ shade, files }), [shade, files]);
   return React.createElement(ShadeFilesContext.Provider, { value }, children);
 }
 

packages/shade-files/src/rpc/channel.ts

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import {
   encodeEnvelope,
   looksLikeFileEnvelope,
@@ -35,7 +35,7 @@ export class ShadeFileRpcChannel {
   private readonly unsubscribe: () => void;
   private destroyed = false;
 
-  constructor(private readonly shade: Shade) {
+  constructor(private readonly shade: ShadeBridge) {
     this.unsubscribe = shade.onMessage(async (from, plaintext) => {
       if (!looksLikeFileEnvelope(plaintext)) return;
       const classified = tryParseEnvelope(plaintext);
@@ -72,6 +72,11 @@ export class ShadeFileRpcChannel {
     if (this.destroyed) throw new Error('ShadeFileRpcChannel: destroyed');
     const plaintext = encodeEnvelope(envelope);
     const ratchetEnvelope = await this.shade.send(peerAddress, plaintext);
+    if (this.shade.deliverControlEnvelope === undefined) {
+      throw new Error(
+        'ShadeFileRpcChannel: shade.deliverControlEnvelope is required — call shade.configureTransfers({ resolveBaseUrl }) before using the files namespace.',
+      );
+    }
     await this.shade.deliverControlEnvelope(peerAddress, ratchetEnvelope);
   }
 

packages/shade-files/src/server/handler-context.ts

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import type { StandardOp } from '../protocol/kinds.js';
 
 export type OpKind = StandardOp | `custom:${string}`;
@@ -42,7 +42,7 @@ export function buildOpContext<TArgs>(args: {
   signal: AbortSignal;
   idempotencyKey: string | undefined;
   attemptNumber: number;
-  shade: Shade;
+  shade: ShadeBridge;
 }): OpContext<TArgs> {
   return {
     op: args.op,

packages/shade-files/src/server/handler.ts

@@ -1,4 +1,4 @@
-import type { Shade } from '@shade/sdk';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
 import type { ZodTypeAny } from 'zod';
 import {
   MUTATION_OPS,
@@ -215,7 +215,7 @@ const OP_SCHEMAS: Record<StandardOp, OpSchemaPair> = {
  * via `Shade.files.serve(...)` in the SDK).
  */
 export function createFileHandler(
-  shade: Shade,
+  shade: ShadeBridge,
   config: FileHandlerConfig,
 ): FileHandler {
   const idempotency = new IdempotencyCache(config.idempotency);

packages/shade-files/src/server/rpc-route.ts

@@ -0,0 +1,218 @@
+/**
+ * Request-response RPC route for `@shade/files`.
+ *
+ * Mounts a single `POST /rpc` Hono endpoint that accepts an encrypted
+ * `RpcRequest` envelope, dispatches it through the file handler, and
+ * returns the encrypted `RpcResponse` (or `RpcError`) envelope in the
+ * SAME HTTP response.
+ *
+ * This is the browser-friendly transport: the server never needs to
+ * make outbound calls back to the client, so a browser tab — which
+ * cannot host an HTTP server — can fully consume `@shade/files`.
+ *
+ * ### Wire contract
+ *
+ * Request:
+ * ```
+ * POST <mount>/rpc HTTP/1.1
+ * Content-Type: application/octet-stream
+ * X-Shade-Sender-Address: <peer address>
+ *
+ * <wire-encoded ShadeEnvelope (0x01 PreKeyMessage or 0x02 RatchetMessage)
+ *  containing JSON-encoded RpcRequest>
+ * ```
+ *
+ * Response (success):
+ * ```
+ * 200 OK
+ * Content-Type: application/octet-stream
+ *
+ * <wire-encoded ShadeEnvelope (0x02 RatchetMessage)
+ *  containing JSON-encoded RpcResponse | RpcError>
+ * ```
+ *
+ * Response (transport-level failure — no session, undecryptable, etc.):
+ * ```
+ * 4xx
+ * Content-Type: application/json
+ *
+ * { "error": "..." }
+ * ```
+ *
+ * ### Symmetry with shade-auth-middleware
+ *
+ * The shape mirrors `@shade/server`'s shade-auth-middleware: an
+ * encrypted envelope rides the request body, the server decrypts via
+ * the existing ratchet session, performs the protected operation,
+ * and returns an encrypted envelope in the response. No bidirectional
+ * channel required.
+ *
+ * @see {@link createFilesHttpClient} for the matching browser client.
+ */
+import { Hono } from 'hono';
+import { decodeEnvelope, encodeEnvelope } from '@shade/proto';
+import type { ShadeBridge } from '../integration/shade-bridge.js';
+import {
+  encodeEnvelope as encodeRpcEnvelope,
+  tryParseEnvelope,
+} from '../protocol/envelope-codec.js';
+import type { FileHandler } from './handler.js';
+import type { RpcError, RpcRequest, RpcResponse } from '../schemas/envelope.js';
+import { KIND_ERROR_V1 } from '../protocol/kinds.js';
+
+export interface FilesRpcRouteOptions {
+  /**
+   * Maximum request body size in bytes. Default 1 MiB. Inline payloads
+   * are capped at 256 KiB by the protocol; the headroom is for
+   * custom-op payloads and base64 inflation.
+   */
+  maxBodyBytes?: number;
+  /**
+   * Allow this server to accept the very first message (PreKeyMessage,
+   * `0x01`) over the RPC route. Disabled by default — most browser
+   * clients establish a session via `shade.initSessionFromBundle`
+   * before the first RPC. Enable when you want the RPC route to also
+   * be the X3DH carrier (uncommon but supported).
+   */
+  acceptFirstMessage?: boolean;
+}
+
+const DEFAULT_MAX_BODY_BYTES = 1 * 1024 * 1024;
+
+/**
+ * Build a Hono app with a single `POST /rpc` route. Mount under any
+ * base path: `app.route('/api/v1/shade-files', shade.files.rpcRoute())`.
+ *
+ * The `handler` must already be attached (typically via
+ * `shade.files.serve(handlerConfig)`); this route only ships the
+ * transport — it does not register a new file handler.
+ */
+export function createFilesRpcRoute(
+  shade: ShadeBridge,
+  handler: FileHandler,
+  options: FilesRpcRouteOptions = {},
+): Hono {
+  const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+  const app = new Hono();
+
+  app.post('/rpc', async (c) => {
+    const senderAddress = c.req.header('X-Shade-Sender-Address');
+    if (senderAddress === undefined || senderAddress === '') {
+      return c.json({ error: 'missing X-Shade-Sender-Address header' }, 400);
+    }
+
+    const contentLengthHeader = c.req.header('Content-Length');
+    if (contentLengthHeader !== undefined) {
+      const contentLength = Number.parseInt(contentLengthHeader, 10);
+      if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
+        return c.json(
+          { error: `body exceeds maxBodyBytes (${contentLength} > ${maxBodyBytes})` },
+          413,
+        );
+      }
+    }
+
+    let bodyBytes: Uint8Array;
+    try {
+      const ab = await c.req.arrayBuffer();
+      if (ab.byteLength > maxBodyBytes) {
+        return c.json(
+          { error: `body exceeds maxBodyBytes (${ab.byteLength} > ${maxBodyBytes})` },
+          413,
+        );
+      }
+      bodyBytes = new Uint8Array(ab);
+    } catch (err) {
+      return c.json({ error: `failed to read request body: ${(err as Error).message}` }, 400);
+    }
+
+    if (bodyBytes.byteLength === 0) {
+      return c.json({ error: 'empty request body' }, 400);
+    }
+
+    // Decode the wire envelope. `decodeEnvelope` handles both `0x01`
+    // PreKeyMessage and `0x02` RatchetMessage shapes.
+    let plaintext: string;
+    try {
+      const envelope = decodeEnvelope(bodyBytes);
+      // First-message gate: only allow `prekey` envelopes when the
+      // operator has explicitly opted in.
+      if (options.acceptFirstMessage !== true && envelope.type === 'prekey') {
+        return c.json(
+          {
+            error:
+              'PreKeyMessage envelopes are not accepted on this RPC route — establish the session first via shade.initSessionFromBundle, or set acceptFirstMessage: true',
+          },
+          400,
+        );
+      }
+      plaintext = await shade.receive(senderAddress, envelope);
+    } catch (err) {
+      // Decryption failure — could be no session, corrupted envelope,
+      // or sender address mismatch. Treat as 401 since the envelope is
+      // self-authenticating: a valid sender would decrypt cleanly.
+      return c.json({ error: `decrypt failed: ${(err as Error).message}` }, 401);
+    }
+
+    // Parse the plaintext as an RpcRequest.
+    const classified = tryParseEnvelope(plaintext);
+    if (classified === null) {
+      return c.json({ error: 'plaintext is not a valid @shade/files envelope' }, 400);
+    }
+    if (classified.kind !== 'request') {
+      // Cancel envelopes are silently dropped — RPC route is request/
+      // response only. Cancellation across HTTP is achieved via
+      // AbortController on the client side, not protocol-level.
+      if (classified.kind === 'cancel') {
+        handler.handleCancel(senderAddress, classified.envelope);
+        // No response body — the cancel was best-effort.
+        return new Response(null, { status: 204 });
+      }
+      return c.json(
+        { error: `unexpected envelope kind on RPC route: ${classified.kind}` },
+        400,
+      );
+    }
+
+    const request: RpcRequest = classified.envelope;
+
+    // Dispatch through the file handler.
+    let result: RpcResponse | RpcError;
+    try {
+      result = await handler.handleRequest(senderAddress, request);
+    } catch (err) {
+      // Should never happen — handler.handleRequest catches its own
+      // errors and returns RpcError. If it didn't, that's a bug; emit
+      // a generic transport-level RpcError so the client can surface
+      // it deterministically.
+      result = {
+        kind: KIND_ERROR_V1,
+        id: request.id,
+        error: {
+          code: 'INTERNAL',
+          message: `handler raised: ${(err as Error).message}`,
+        },
+      };
+    }
+
+    // Encrypt the response and return it as wire bytes.
+    let responseBytes: Uint8Array;
+    try {
+      const responsePlaintext = encodeRpcEnvelope(result);
+      const responseEnvelope = await shade.send(senderAddress, responsePlaintext);
+      responseBytes = encodeEnvelope(responseEnvelope);
+    } catch (err) {
+      return c.json(
+        { error: `failed to encrypt response: ${(err as Error).message}` },
+        500,
+      );
+    }
+
+    return new Response(new Blob([responseBytes as unknown as ArrayBuffer]), {
+      status: 200,
+      headers: { 'Content-Type': 'application/octet-stream' },
+    });
+  });
+
+  return app;
+}

packages/shade-files/src/server/streams-bridge.ts

@@ -168,13 +168,14 @@ export async function createServerStreamsBridge(
 
     // No waiter yet — park.
     parked.set(writeId, arrived);
-    setTimeout(() => {
+    const parkTimer = setTimeout(() => {
       const stale = parked.get(writeId);
       if (stale === arrived) {
         parked.delete(writeId);
         void handle.abort('rpc-timeout').catch(() => undefined);
       }
-    }, parkedWriteTtlMs).unref?.();
+    }, parkedWriteTtlMs);
+    (parkTimer as unknown as { unref?: () => void }).unref?.();
   });
 
   function cleanupWaiter(w: PendingWaiter): void {

packages/shade-files/tests/integration/http-rpc.test.ts

@@ -0,0 +1,321 @@
+import { describe, expect, test } from 'bun:test';
+import { createShade } from '@shade/sdk';
+import {
+  createPrekeyServer,
+  MemoryPrekeyStore,
+  PrekeyServerEvents,
+} from '@shade/server';
+import { SubtleCryptoProvider } from '@shade/crypto-web';
+
+const crypto = new SubtleCryptoProvider();
+
+/**
+ * Stand up a prekey server + two Shades + Bob's file handler + RPC route
+ * mounted on Bun.serve, then return Alice's HTTP-only `FileClient`.
+ *
+ * Mirrors the request-response setup a browser client would use against a
+ * Bun-style server.
+ */
+async function setupHttpRig(opts: {
+  bobHandler: Parameters<NonNullable<Awaited<ReturnType<typeof createShade>>['files']>['serve']>[0];
+}) {
+  // 1. Prekey server.
+  const prekeyEvents = new PrekeyServerEvents();
+  const prekey = createPrekeyServer({
+    crypto,
+    store: new MemoryPrekeyStore(),
+    disableRateLimit: true,
+    events: prekeyEvents,
+  });
+  const prekeyServer = Bun.serve({ port: 0, fetch: prekey.fetch });
+  const prekeyUrl = `http://localhost:${prekeyServer.port}`;
+
+  // 2. Two Shades. Alice plays the browser client (no transferRoute);
+  //    Bob is the server.
+  const alice = await createShade({ prekeyServer: prekeyUrl, address: 'alice' });
+  const bob = await createShade({ prekeyServer: prekeyUrl, address: 'bob' });
+
+  // 3. Bob: register file handler (HTTP-only — no streams) + mount
+  //    the RPC route.
+  await bob.files.serve(opts.bobHandler, { inlineOnly: true });
+  const rpcRoute = bob.files.rpcRoute({ acceptFirstMessage: true });
+  const bobServer = Bun.serve({ port: 0, fetch: rpcRoute.fetch });
+  const rpcUrl = `http://localhost:${bobServer.port}/rpc`;
+
+  // 5. Alice: build the HTTP-only file client.
+  const fs = alice.files.httpClient('bob', { rpcUrl, defaultTimeoutMs: 5000 });
+
+  return {
+    alice,
+    bob,
+    fs,
+    rpcUrl,
+    teardown: async () => {
+      await alice.shutdown();
+      await bob.shutdown();
+      bobServer.stop();
+      prekeyServer.stop();
+    },
+  };
+}
+
+describe('@shade/files HTTP RPC — round-trip', () => {
+  test('list → mkdir → stat → write inline → read inline → delete via httpClient', async () => {
+    interface VfsEntry {
+      kind: 'file' | 'dir';
+      bytes?: Uint8Array;
+      contentType?: string;
+    }
+    const vfs = new Map<string, VfsEntry>([
+      ['/', { kind: 'dir' }],
+      ['/photos', { kind: 'dir' }],
+    ]);
+
+    const rig = await setupHttpRig({
+      bobHandler: {
+        list: async (ctx) => {
+          const prefix = ctx.path.endsWith('/') ? ctx.path : `${ctx.path}/`;
+          const entries = Array.from(vfs.entries())
+            .filter(([p]) => p.startsWith(prefix) && p !== ctx.path && !p.slice(prefix.length).includes('/'))
+            .map(([p, e]) => ({
+              name: p.slice(prefix.length) || p,
+              kind: e.kind,
+              size: e.bytes?.byteLength ?? 0,
+              mtime: 0,
+              metadata: {},
+            }));
+          return { entries, hasMore: false };
+        },
+        stat: async (ctx) => {
+          const e = vfs.get(ctx.path);
+          if (!e) throw new (await import('../../src/index.js')).NotFoundError(`stat ${ctx.path}`);
+          return {
+            name: ctx.path.split('/').pop() ?? ctx.path,
+            kind: e.kind,
+            size: e.bytes?.byteLength ?? 0,
+            mtime: 0,
+            metadata: {},
+            ...(e.contentType !== undefined ? { contentType: e.contentType } : {}),
+          };
+        },
+        mkdir: async (ctx) => {
+          vfs.set(ctx.path, { kind: 'dir' });
+          return { entry: { name: ctx.path.split('/').pop() ?? ctx.path, kind: 'dir' as const, size: 0, mtime: 0, metadata: {} } };
+        },
+        delete: async (ctx) => {
+          if (!vfs.has(ctx.path)) {
+            throw new (await import('../../src/index.js')).NotFoundError(`delete ${ctx.path}`);
+          }
+          vfs.delete(ctx.path);
+          return { deletedCount: 1 };
+        },
+        read: async (ctx) => {
+          const e = vfs.get(ctx.path);
+          if (!e || e.kind !== 'file' || !e.bytes) {
+            throw new (await import('../../src/index.js')).NotFoundError(`read ${ctx.path}`);
+          }
+          // Omit sha256 — dispatcher computes it from the bytes.
+          return {
+            kind: 'inline' as const,
+            bytes: e.bytes,
+            ...(e.contentType !== undefined ? { contentType: e.contentType } : {}),
+          };
+        },
+        write: async (ctx) => {
+          if (ctx.args.content.kind !== 'inline') {
+            throw new (await import('../../src/index.js')).ConflictError('streams not supported in this test handler');
+          }
+          vfs.set(ctx.args.path, {
+            kind: 'file',
+            bytes: ctx.args.content.bytes,
+            ...(ctx.args.contentType !== undefined ? { contentType: ctx.args.contentType } : {}),
+          });
+          return {
+            entry: {
+              name: ctx.args.path.split('/').pop() ?? ctx.args.path,
+              kind: 'file' as const,
+              size: ctx.args.content.bytes.byteLength,
+              mtime: 0,
+              metadata: {},
+              ...(ctx.args.contentType !== undefined ? { contentType: ctx.args.contentType } : {}),
+            },
+          };
+        },
+      },
+    });
+
+    try {
+      // list
+      const listed = await rig.fs.list('/');
+      expect(listed.entries.map((e) => e.name).sort()).toContain('photos');
+
+      // mkdir
+      await rig.fs.mkdir('/docs');
+      const stat = await rig.fs.stat('/docs');
+      expect(stat.kind).toBe('dir');
+
+      // write inline
+      const payload = new TextEncoder().encode('hello browser-friendly world');
+      const writeResult = await rig.fs.write('/docs/greeting.txt', payload, {
+        contentType: 'text/plain',
+      });
+      expect(writeResult.entry.size).toBe(payload.byteLength);
+
+      // read inline
+      const readResult = await rig.fs.read('/docs/greeting.txt');
+      expect(readResult.kind).toBe('inline');
+      if (readResult.kind === 'inline') {
+        expect(new TextDecoder().decode(readResult.bytes)).toBe('hello browser-friendly world');
+        expect(readResult.contentType).toBe('text/plain');
+      }
+
+      // delete
+      const del = await rig.fs.delete('/docs/greeting.txt');
+      expect(del.deletedCount).toBe(1);
+
+      // stat the deleted path → typed NotFoundError
+      const { NotFoundError } = await import('../../src/index.js');
+      await expect(rig.fs.stat('/docs/greeting.txt')).rejects.toBeInstanceOf(NotFoundError);
+    } finally {
+      await rig.teardown();
+    }
+  });
+
+  test('streamed write (> 256 KiB) is rejected with a clear error', async () => {
+    const rig = await setupHttpRig({
+      bobHandler: {
+        write: async () => ({
+          entry: { name: 'unused', kind: 'file' as const, size: 0, mtime: 0, metadata: {} },
+        }),
+      },
+    });
+    try {
+      const big = new Uint8Array(257 * 1024);
+      const { ConflictError } = await import('../../src/index.js');
+      await expect(rig.fs.write('/big.bin', big)).rejects.toBeInstanceOf(ConflictError);
+    } finally {
+      await rig.teardown();
+    }
+  });
+
+  test('rpcRoute() throws when no handler is attached', async () => {
+    // Don't call shade.files.serve(...) — rpcRoute() should refuse.
+    const prekeyEvents = new PrekeyServerEvents();
+    const prekey = createPrekeyServer({
+      crypto,
+      store: new MemoryPrekeyStore(),
+      disableRateLimit: true,
+      events: prekeyEvents,
+    });
+    const prekeyServer = Bun.serve({ port: 0, fetch: prekey.fetch });
+    const bob = await createShade({
+      prekeyServer: `http://localhost:${prekeyServer.port}`,
+      address: 'bob',
+    });
+    try {
+      expect(() => bob.files.rpcRoute()).toThrow(/no handler attached/);
+    } finally {
+      await bob.shutdown();
+      prekeyServer.stop();
+    }
+  });
+
+  test('missing X-Shade-Sender-Address header → 400', async () => {
+    const rig = await setupHttpRig({
+      bobHandler: {
+        stat: async () => ({
+          name: '_', kind: 'dir' as const, size: 0, mtime: 0, metadata: {},
+        }),
+      },
+    });
+    try {
+      const res = await fetch(rig.rpcUrl, {
+        method: 'POST',
+        body: new Uint8Array([0]),
+      });
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).toMatch(/X-Shade-Sender-Address/);
+    } finally {
+      await rig.teardown();
+    }
+  });
+
+  test('empty body → 400', async () => {
+    const rig = await setupHttpRig({
+      bobHandler: {
+        stat: async () => ({
+          name: '_', kind: 'dir' as const, size: 0, mtime: 0, metadata: {},
+        }),
+      },
+    });
+    try {
+      const res = await fetch(rig.rpcUrl, {
+        method: 'POST',
+        headers: { 'X-Shade-Sender-Address': 'alice' },
+      });
+      expect(res.status).toBe(400);
+    } finally {
+      await rig.teardown();
+    }
+  });
+
+  test('garbage body → 401 decrypt failure', async () => {
+    const rig = await setupHttpRig({
+      bobHandler: {
+        stat: async () => ({
+          name: '_', kind: 'dir' as const, size: 0, mtime: 0, metadata: {},
+        }),
+      },
+    });
+    try {
+      const res = await fetch(rig.rpcUrl, {
+        method: 'POST',
+        headers: { 'X-Shade-Sender-Address': 'alice' },
+        body: new Uint8Array([0x02, 0xff, 0xff, 0xff]),
+      });
+      // 400 from envelope decode failure or 401 from decrypt failure.
+      expect([400, 401]).toContain(res.status);
+    } finally {
+      await rig.teardown();
+    }
+  });
+
+  test('body past maxBodyBytes → 413', async () => {
+    const prekeyEvents = new PrekeyServerEvents();
+    const prekey = createPrekeyServer({
+      crypto,
+      store: new MemoryPrekeyStore(),
+      disableRateLimit: true,
+      events: prekeyEvents,
+    });
+    const prekeyServer = Bun.serve({ port: 0, fetch: prekey.fetch });
+    const bob = await createShade({
+      prekeyServer: `http://localhost:${prekeyServer.port}`,
+      address: 'bob',
+    });
+    await bob.files.serve(
+      {
+        stat: async () => ({
+          name: '_', kind: 'dir' as const, size: 0, mtime: 0, metadata: {},
+        }),
+      },
+      { inlineOnly: true },
+    );
+    const route = bob.files.rpcRoute({ maxBodyBytes: 1024 });
+    const server = Bun.serve({ port: 0, fetch: route.fetch });
+    try {
+      const big = new Uint8Array(2048);
+      const res = await fetch(`http://localhost:${server.port}/rpc`, {
+        method: 'POST',
+        headers: { 'X-Shade-Sender-Address': 'alice' },
+        body: big,
+      });
+      expect(res.status).toBe(413);
+    } finally {
+      await bob.shutdown();
+      server.stop();
+      prekeyServer.stop();
+    }
+  });
+});

packages/shade-inbox-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/inbox-server",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-inbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/inbox",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-key-transparency/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/key-transparency",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-key-transparency/src/index-tree.ts

@@ -21,7 +21,7 @@
  * the dataset grows enough that flat re-hash becomes a bottleneck.
  */
 
-import { leafHash, nodeHash, emptyRootHash } from './hashes.js';
+import { leafHash, emptyRootHash } from './hashes.js';
 import { sha256Sync } from './sha256.js';
 import { constantTimeEqual } from './util.js';
 import { mth, auditPath, recomputeRootFromAuditPath } from './log.js';

packages/shade-key-transparency/src/manager.ts

@@ -24,8 +24,6 @@ import { MerkleLog, auditPath } from './log.js';
 import {
   AddressIndex,
   type AddressIndexEntry,
-  type IndexAbsenceProof,
-  type IndexInclusionProof,
 } from './index-tree.js';
 import {
   type SignedTreeHead,

packages/shade-key-transparency/src/proof.ts

@@ -111,7 +111,7 @@ interface IndexAbsenceWire {
   } | null;
 }
 
-type IndexProofWire = IndexInclusionWire | IndexAbsenceWire;
+export type IndexProofWire = IndexInclusionWire | IndexAbsenceWire;
 
 interface BundleInclusionWire {
   kind: 'inclusion' | 'tombstone';

packages/shade-key-transparency/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}

packages/shade-keychain/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/keychain",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-keychain/tsconfig.json

@@ -1,4 +1,5 @@
 {
   "extends": "../../tsconfig.json",
-  "include": ["src/**/*", "tests/**/*"]
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
 }

packages/shade-observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/observability",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-observer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/observer",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-proto/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/proto",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-recovery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/recovery",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/sdk",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-sdk/src/background.ts

@@ -96,7 +96,7 @@ export class BackgroundTasks {
         this.hooks.onError?.(err as Error, 'prune-files');
       }
     }, this.pruneFilesIntervalMs);
-    this.pruneFilesTimer.unref?.();
+    (this.pruneFilesTimer as unknown as { unref?: () => void }).unref?.();
   }
 
   stop(): void {

packages/shade-sdk/src/shade.ts

@@ -21,7 +21,7 @@ import {
 import { encodeEnvelope, decodeEnvelope, inspectEnvelopeType } from '@shade/proto';
 import { ShadeFetchTransport, type KTVerifierOptions } from '@shade/transport';
 import { LightWitness } from '@shade/key-transparency';
-import type { SignedTreeHead } from '@shade/key-transparency';
+import type { SignedTreeHead, STHWire } from '@shade/key-transparency';
 import {
   TransferEngine,
   ShadeTransferHttpTransport,
@@ -217,15 +217,15 @@ export class Shade {
         maxStaleMs: this.config.keyTransparency.maxStaleMs,
         maxStored: this.config.keyTransparency.witnessMaxStored,
         fetcher: {
-          async fetchLatestSTH() {
+          async fetchLatestSTH(): Promise<STHWire> {
             const res = await fetch(`${baseUrl}/v1/kt/sth`);
             if (!res.ok) throw new Error(`KT /sth: ${res.status}`);
-            return res.json();
+            return (await res.json()) as STHWire;
           },
-          async fetchConsistencyProof(from, to) {
+          async fetchConsistencyProof(from, to): Promise<{ proof: string[] }> {
             const res = await fetch(`${baseUrl}/v1/kt/consistency?from=${from}&to=${to}`);
             if (!res.ok) throw new Error(`KT /consistency: ${res.status}`);
-            return res.json();
+            return (await res.json()) as { proof: string[] };
           },
         },
       });

packages/shade-sdk/src/thumbnail.ts

@@ -59,12 +59,16 @@ interface CreateImageBitmapFn {
 }
 
 function getOffscreenCanvasCtor(): OffscreenCanvasCtor | null {
-  const g = globalThis as { OffscreenCanvas?: OffscreenCanvasCtor };
+  const g = globalThis as unknown as { OffscreenCanvas?: OffscreenCanvasCtor };
   return g.OffscreenCanvas ?? null;
 }
 
 function getCreateImageBitmap(): CreateImageBitmapFn | null {
-  const g = globalThis as { createImageBitmap?: CreateImageBitmapFn };
+  // `globalThis.createImageBitmap` (when DOM lib is loaded) has a wider
+  // signature than our minimal `CreateImageBitmapFn`. Cast through
+  // `unknown` so consumer tsconfigs that include "DOM" don't reject the
+  // narrower local type as "insufficiently overlapping".
+  const g = globalThis as unknown as { createImageBitmap?: CreateImageBitmapFn };
   return g.createImageBitmap ?? null;
 }
 

packages/shade-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/server",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-storage-encrypted/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/storage-encrypted",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-storage-encrypted/src/crypto/aead.ts

@@ -11,11 +11,23 @@
 
 const NONCE_LEN = 12;
 
+// Local mirror of the WebCrypto KeyUsage union — avoids depending on
+// `lib.dom` (we run on Bun + plain ES2022) while keeping API parity.
+type WebCryptoKeyUsage =
+  | 'encrypt'
+  | 'decrypt'
+  | 'sign'
+  | 'verify'
+  | 'deriveKey'
+  | 'deriveBits'
+  | 'wrapKey'
+  | 'unwrapKey';
+
 function bs(u: Uint8Array): ArrayBuffer {
   return u as unknown as ArrayBuffer;
 }
 
-async function importKey(key: Uint8Array, usages: KeyUsage[]): Promise<CryptoKey> {
+async function importKey(key: Uint8Array, usages: WebCryptoKeyUsage[]): Promise<CryptoKey> {
   if (key.length !== 32) throw new Error(`AES-256-GCM key must be 32 bytes, got ${key.length}`);
   return globalThis.crypto.subtle.importKey('raw', bs(key), 'AES-GCM', false, usages);
 }

packages/shade-storage-encrypted/tsconfig.json

@@ -1,4 +1,5 @@
 {
   "extends": "../../tsconfig.json",
-  "include": ["src/**/*", "tests/**/*"]
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
 }

packages/shade-storage-postgres/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/storage-postgres",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-storage-sqlite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/storage-sqlite",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-streams/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/streams",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transfer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transfer",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transport-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transport-bridge",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transport-bridge/src/sse-bridge.ts

@@ -127,7 +127,7 @@ export class SseBridge implements BridgeTransport {
     if (!res.body) {
       throw new BridgeError('SSE response has no body');
     }
-    this.currentReader = res.body.getReader();
+    this.currentReader = res.body.getReader() as ReadableStreamDefaultReader<Uint8Array>;
     this.connected = true;
   }
 

packages/shade-transport-webrtc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transport-webrtc",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-transport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/transport",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-widgets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shade/widgets",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/shade-widgets/src/components/transfer/ThumbnailPreview.tsx

@@ -2,7 +2,6 @@ import React, { useEffect, useRef, useState } from 'react';
 import {
   isAllowedThumbnailMime,
   THUMBNAIL_MAX_BYTES,
-  type ThumbnailMime,
 } from '@shade/sdk';
 import { useShadeRuntimeTheme } from '../../ShadeRuntimeProvider.js';
 

scripts/publish-shade.sh

@@ -127,6 +127,10 @@ export GITEA_TOKEN="$TOKEN"
 
 cd "$SHADE_DIR"
 echo
-echo "Kjører bun run publish:all i $SHADE_DIR"
+echo "Type-check (strict TS) før publish ..."
 echo "----------------------------------------"
-bun run publish:all
+bun run scripts/typecheck-all.ts
+echo
+echo "Kjører scripts/publish-all.ts i $SHADE_DIR"
+echo "----------------------------------------"
+bun run scripts/publish-all.ts

scripts/typecheck-all.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+/**
+ * Pre-publish gate — type-check every workspace package against the
+ * monorepo's strict tsconfig.
+ *
+ * Required before any publish. The Bun test runner is intentionally
+ * permissive (it transpiles, doesn't type-check), so without this gate
+ * a package can pass `bun test` and still ship code that fails to
+ * compile in a downstream consumer's strict TS project.
+ *
+ *   Usage:
+ *     bun run scripts/typecheck-all.ts          # check every package
+ *     bun run scripts/typecheck-all.ts core sdk # check only listed
+ *
+ * Exit code 0 if every package compiles, 1 otherwise.
+ */
+import { readdirSync, statSync, existsSync } from 'fs';
+import { join } from 'path';
+import { $ } from 'bun';
+
+const ROOT = join(import.meta.dir, '..');
+const PACKAGES_DIR = join(ROOT, 'packages');
+
+const filter = new Set(process.argv.slice(2));
+
+const packages = readdirSync(PACKAGES_DIR).filter((name) => {
+  const p = join(PACKAGES_DIR, name);
+  if (!statSync(p).isDirectory()) return false;
+  if (!existsSync(join(p, 'tsconfig.json'))) return false;
+  if (filter.size > 0 && !filter.has(name) && !filter.has(name.replace(/^shade-/, ''))) {
+    return false;
+  }
+  return true;
+});
+
+let failures = 0;
+const failed: { pkg: string; out: string }[] = [];
+
+for (const pkg of packages) {
+  const dir = join(PACKAGES_DIR, pkg);
+  const proc = Bun.spawnSync(['bunx', 'tsc', '--noEmit', '-p', 'tsconfig.json'], {
+    cwd: dir,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const stdout = proc.stdout.toString();
+  const stderr = proc.stderr.toString();
+  const out = (stdout + stderr)
+    .split('\n')
+    .filter((l) => !/^Resolving|^Resolved|^Saved/.test(l))
+    .join('\n')
+    .trim();
+
+  if (proc.exitCode === 0 && out.length === 0) {
+    console.log(`  ✓ ${pkg}`);
+  } else {
+    failures++;
+    failed.push({ pkg, out });
+    console.log(`  ✗ ${pkg}`);
+  }
+}
+
+console.log();
+
+// Step 2 — consumer-strict smoke. Compiles a tiny "as if I were a
+// downstream app" project against our public API surface under the
+// consumer-likely tsconfig (`lib: ["DOM"]` + `exactOptionalPropertyTypes`).
+// Catches type-bugs that ONLY surface when our internal narrower types
+// meet a consumer's standard-library types — the class of bug `tsc`
+// inside our own packages does not see (because our packages compile
+// against `lib: ["ES2022"]` only).
+if (filter.size === 0) {
+  console.log('Consumer-strict smoke (lib: DOM, exactOptional, paths→workspace) ...');
+  const consumerDir = join(ROOT, 'tests', 'consumer-strict');
+  if (existsSync(join(consumerDir, 'tsconfig.json'))) {
+    const proc = Bun.spawnSync(['bunx', 'tsc', '--noEmit', '-p', 'tsconfig.json'], {
+      cwd: consumerDir,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    const out = (proc.stdout.toString() + proc.stderr.toString())
+      .split('\n')
+      .filter((l) => !/^Resolving|^Resolved|^Saved/.test(l))
+      .join('\n')
+      .trim();
+    if (proc.exitCode === 0 && out.length === 0) {
+      console.log('  ✓ consumer-strict');
+    } else {
+      failures++;
+      failed.push({ pkg: 'consumer-strict', out });
+      console.log('  ✗ consumer-strict');
+    }
+  }
+  console.log();
+}
+
+if (failures === 0) {
+  console.log(`All ${packages.length} packages type-check cleanly.`);
+  process.exit(0);
+}
+
+console.error(`${failures} of ${packages.length} packages failed:\n`);
+for (const f of failed) {
+  console.error(`── ${f.pkg} ──`);
+  console.error(f.out);
+  console.error();
+}
+process.exit(1);

tests/consumer-strict/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["bun-types"],
+    "ignoreDeprecations": "6.0",
+    "baseUrl": ".",
+    "paths": {
+      "@shade/core": ["../../packages/shade-core/src/index.ts"],
+      "@shade/proto": ["../../packages/shade-proto/src/index.ts"],
+      "@shade/crypto-web": ["../../packages/shade-crypto-web/src/index.ts"],
+      "@shade/observability": ["../../packages/shade-observability/src/index.ts"],
+      "@shade/keychain": ["../../packages/shade-keychain/src/index.ts"],
+      "@shade/key-transparency": ["../../packages/shade-key-transparency/src/index.ts"],
+      "@shade/storage-sqlite": ["../../packages/shade-storage-sqlite/src/index.ts"],
+      "@shade/storage-postgres": ["../../packages/shade-storage-postgres/src/index.ts"],
+      "@shade/storage-encrypted": ["../../packages/shade-storage-encrypted/src/index.ts"],
+      "@shade/streams": ["../../packages/shade-streams/src/index.ts"],
+      "@shade/transport": ["../../packages/shade-transport/src/index.ts"],
+      "@shade/transport-bridge": ["../../packages/shade-transport-bridge/src/index.ts"],
+      "@shade/transport-webrtc": ["../../packages/shade-transport-webrtc/src/index.ts"],
+      "@shade/server": ["../../packages/shade-server/src/index.ts"],
+      "@shade/inbox-server": ["../../packages/shade-inbox-server/src/index.ts"],
+      "@shade/inbox": ["../../packages/shade-inbox/src/index.ts"],
+      "@shade/transfer": ["../../packages/shade-transfer/src/index.ts"],
+      "@shade/files": ["../../packages/shade-files/src/index.ts"],
+      "@shade/recovery": ["../../packages/shade-recovery/src/index.ts"],
+      "@shade/observer": ["../../packages/shade-observer/src/index.ts"],
+      "@shade/dashboard": ["../../packages/shade-dashboard/src/index.ts"],
+      "@shade/sdk": ["../../packages/shade-sdk/src/index.ts"],
+      "@shade/widgets": ["../../packages/shade-widgets/src/index.ts"]
+    }
+  },
+  "include": ["./*.ts"]
+}

tests/consumer-strict/use-files.ts

@@ -0,0 +1,43 @@
+/**
+ * Consumer-strict smoke for `@shade/files`.
+ *
+ * Compiled with `lib: ["ES2022", "DOM"]` + `exactOptionalPropertyTypes` +
+ * `skipLibCheck: false` to mimic a downstream consumer like Dispatch.
+ * Catches the class of bug where our internal narrower types (e.g. a
+ * locally-defined `MinimalReader`) reject native browser types
+ * (e.g. `ReadableStreamDefaultReader`) the consumer would naturally
+ * pass in.
+ *
+ * If this file fails to compile, the published packages will fail in
+ * any consumer's strict tsc — pre-publish gate must catch it.
+ */
+import { decideInline, type WriteSource } from '@shade/files';
+
+declare const blob: Blob;
+declare const stream: ReadableStream<Uint8Array>;
+declare const bytes: Uint8Array;
+
+async function smoke(): Promise<void> {
+  // Each branch of WriteSource must round-trip through decideInline()
+  // when given the natively-typed inputs a browser app would supply.
+  const sources: WriteSource[] = [
+    bytes,
+    blob,
+    stream,
+    { stream, size: 1024 },
+    { stream, size: 1024, contentType: 'image/png' },
+  ];
+  for (const src of sources) {
+    const decision = await decideInline(src);
+    if (decision.kind === 'streams') {
+      const reader = decision.stream.getReader();
+      const { value, done } = await reader.read();
+      if (!done && value !== undefined) {
+        void value.byteLength;
+      }
+      reader.releaseLock();
+    }
+  }
+}
+
+void smoke;

tests/consumer-strict/use-key-transparency.ts

@@ -0,0 +1,42 @@
+/**
+ * Consumer-strict smoke for `@shade/key-transparency`.
+ *
+ * The package was the source of the 4 noUnusedLocals + the IndexProofWire
+ * privacy bug in 4.0.0. This smoke imports every public type and
+ * exercises the witness-fetcher contract that the SDK plugs into.
+ */
+import {
+  LightWitness,
+  type SignedTreeHead,
+  type STHWire,
+  type WitnessFetcher,
+} from '@shade/key-transparency';
+
+declare const crypto: import('@shade/core').CryptoProvider;
+declare const logPublicKey: Uint8Array;
+
+async function smoke(): Promise<void> {
+  const fetcher: WitnessFetcher = {
+    async fetchLatestSTH(): Promise<STHWire> {
+      const res = await fetch('https://shade.example.com/v1/kt/sth');
+      return (await res.json()) as STHWire;
+    },
+    async fetchConsistencyProof(
+      from: number,
+      to: number,
+    ): Promise<{ proof: string[] }> {
+      const res = await fetch(
+        `https://shade.example.com/v1/kt/consistency?from=${from}&to=${to}`,
+      );
+      return (await res.json()) as { proof: string[] };
+    },
+  };
+  const witness = new LightWitness({ crypto, logPublicKey, fetcher });
+  void witness;
+}
+
+void smoke;
+
+// Verify the type is reachable with no `any` leak.
+declare const sth: SignedTreeHead;
+void sth.treeSize;

tests/consumer-strict/use-sdk.ts

@@ -0,0 +1,50 @@
+/**
+ * Consumer-strict smoke for `@shade/sdk`.
+ *
+ * Exercises the high-level `createShade()` flow + the V3.x opt-in
+ * surfaces (KT, WebRTC, fingerprint gates). Compiles under DOM-lib +
+ * exactOptionalPropertyTypes to flag any private-type leaks like the
+ * `Promise<unknown>` on `fetchLatestSTH` that 4.0.0 shipped.
+ */
+import {
+  createShade,
+  type Shade,
+  type ShadeConfig,
+  type ShadeWebRtcConfig,
+} from '@shade/sdk';
+
+declare const factory: ShadeWebRtcConfig['factory'];
+
+async function smoke(): Promise<void> {
+  const config: ShadeConfig = {
+    prekeyServer: 'https://shade.example.com',
+    storage: 'memory',
+    address: 'alice@example.com',
+    keyTransparency: {
+      mode: 'observe-strict',
+      logPublicKey: new Uint8Array(32),
+    },
+  };
+  const shade: Shade = await createShade(config);
+
+  const env = await shade.send('bob', 'hi');
+  void env;
+
+  shade.onMessage(async (from: string, plaintext: string) => {
+    void from;
+    void plaintext;
+  });
+
+  await shade.beforeFirstLargeFile(10 * 1024 * 1024, async (ctx) => {
+    void ctx.peerAddress;
+    void ctx.fingerprint;
+    void ctx.gate;
+    return true;
+  });
+
+  shade.configureWebRTC({ factory });
+
+  void (await shade.fingerprint);
+}
+
+void smoke;