feat(files): @shade/files 0.3.0 — E2EE filesystem RPC primitive

M-Files-1..6 land the full files-RPC layer + everything 0.3.0 needs to
ship. Apps keep their own UI; this layer ships the typed RPC, the
streams bridge for content I/O, and production hooks (rate limit,
retention, fingerprint gate, metrics).

@shade/files (NEW)
- Standard ops: list/stat/mkdir/delete/move/read/write/getThumbnail with
  Zod-validated wire schemas + clean user-handler types.
- Custom ops: typed via TypeScript declaration merging on CustomOpsMap
  + per-op Zod schemas; client.custom('app.foo', {...}) is fully typed.
- Content I/O: inline (≤ 256 KiB plaintext) base64-in-RPC; streams
  (> 256 KiB) ride @shade/transfer via userMetadata.shadeFilesWriteId
  / shadeFilesReadStreamId correlation. Server-side TransformStream
  bridges accept inbound transfers immediately (engine rejects chunks
  that arrive before accept) and park the readable for the matching
  RPC.
- Directory ops: walk(path, opts) async-iterable depth-first walker;
  uploadDirectory()/downloadDirectory() with bounded concurrency pool
  (default 4, cap 16), aggregated progress, abort.
- Production hooks (callback-based, vendor-neutral): rate-limit (op +
  byte), idempotency cache (LRU + TTL + in-flight de-dupe), path
  policy (traversal + percent-decode hardening), fingerprint gate
  (required/optional/reject), pluggable Ed25519 sig verification with
  ±5 min replay window, onMetric sink (standard names).
- React hooks (subpath @shade/files/react): ShadeFilesProvider,
  useShadeFiles, useFileList, useFileTransfer/Upload/Download.
- Shade.files.serve(handler) + Shade.files.client(peer) high-level
  entrypoint in @shade/sdk; lazy + memoized; one handler per Shade.

Wire format bump
- @shade/proto wire VERSION 0x01 → 0x02. Length prefixes changed from
  u16 to u32. The previous u16 silently truncated payloads above
  64 KiB — a hard correctness ceiling that blocked inline file ops
  up to 256 KiB. Wire-incompatible with 0.2.x peers; new sessions
  only. Cross-platform Kotlin port (android/shade-android) updated to
  match; test-vectors/wire-format.json regenerated.

Concurrency safety
- ShadeSessionManager.encrypt/.decrypt now run under per-peer mutex.
  Concurrent decryptions of the same peer raced ratchet state
  (manifested as sporadic "Failed to decrypt — wrong key or tampered
  data" under load — surfaced once concurrent uploadDirectory pumped
  many writes in flight). Encrypt was already serialized via
  Shade.send's encryptChains; decrypt is now serialized at the
  manager layer too.

@shade/streams extension
- StreamMetadata.userMetadata?: Record<string, string> for
  application-level key/value pairs that round-trip verbatim through
  stream-init plaintext. Used by @shade/files for write/read
  correlation; available to any consumer.

@shade/sdk extension
- Shade.files getter (lazy + memoized).
- BackgroundHooks.onPruneFiles + periodic timer (default 5 min) +
  BackgroundTasks.setHook(name, fn) for runtime hook registration.

Bundles in-flight 0.2.0 work
- packages/shade-streams/, packages/shade-transfer/, related
  shade-sdk streams-bridge + shade-widgets transfer hooks were
  uncommitted prior to this session. Including them keeps the
  workspace consistent at 0.3.0 since @shade/files depends on them.

Tests
- 74 new tests in @shade/files (572 → 646 workspace pass; 0 fail;
  3× stable). Coverage spans unit (inline-threshold + concurrency),
  integration (read-write inline + streams up to 1 MiB, walk +
  upload/download directory, custom-op, metrics, SDK namespace
  end-to-end), and security (tampered-envelope sig verification,
  replay window, fingerprint gate, rate-limit + quota).

Release artifacts
- All packages bumped to 0.3.0 via scripts/bump-version.ts.
- scripts/publish-all.ts PACKAGES updated with shade-files in
  topological order (after shade-transfer, before shade-sdk).
- bun run publish:dry clean (14 packed, 0 failed).
- examples/08-files-browser/ — three-process CLI demo (prekey + Bob
  server + Alice CLI) covering list/stat/mkdir/delete/upload/download.
- docs/files.md — full API + design doc.
- CHANGELOG.md 0.3.0 entry.

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

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

@@ -0,0 +1,251 @@
+/**
+ * Client-side bridge between `@shade/files` content RPC ops and the
+ * `@shade/transfer` engine.
+ *
+ * Two responsibilities, mirror-image of `server/streams-bridge.ts`:
+ *  1. **Outbound writes (client → server, > 256 KiB).** When `FileClient.write`
+ *     promotes to the streams path, this bridge calls `shade.upload(...)`
+ *     with `userMetadata.shadeFilesWriteId = <id>` so the server can
+ *     correlate the inbound transfer with the parallel `write` RPC.
+ *
+ *  2. **Inbound reads (server → client, > 256 KiB).** When `FileClient.read`
+ *     gets a `{ kind: 'streams', streamId, ... }` RPC response, it asks
+ *     this bridge for the matching incoming transfer's plaintext stream.
+ *     The bridge subscribes to `shade.onIncomingTransfer` once and, on
+ *     each transfer tagged with `userMetadata.shadeFilesReadStreamId`,
+ *     **immediately** calls `accept(...)` (the engine rejects chunks that
+ *     arrive before accept), pipes plaintext into a TransformStream, and
+ *     parks the readable side until the matching read RPC awaits it.
+ */
+import type { TransferHandle, TransferProgress } from '@shade/transfer';
+import { generateRequestId } from '../protocol/correlate.js';
+import { OperationTimeoutError } from '../schemas/errors.js';
+import {
+  META_KEY_READ_STREAM_ID,
+  META_KEY_WRITE_ID,
+  type StreamsBridgeShade,
+} from '../server/streams-bridge.js';
+
+export interface AwaitReadOptions {
+  /** Sender address — must match `incoming.from` for delivery. */
+  expectedFrom: string;
+  signal: AbortSignal;
+  /** Hard deadline (ms from now). Default 60_000. */
+  timeoutMs?: number;
+}
+
+export interface ParkedRead {
+  from: string;
+  /** Plaintext stream. The bridge already accepted the transfer. */
+  readable: ReadableStream<Uint8Array>;
+  /** Resolves when the transfer fully completes (verified sha256 available). */
+  done: Promise<{ sha256: string; bytesSent: number }>;
+  /** Underlying transfer handle — for abort propagation. */
+  handle: TransferHandle;
+  arrivedAt: number;
+}
+
+export interface ClientStreamsBridge {
+  /**
+   * Generate a fresh writeId, kick `shade.upload(...)` to `peer` with that
+   * id stamped in `userMetadata`, and return both the id (for the parallel
+   * RPC envelope) and the transfer handle (for `done()`/`abort()`).
+   */
+  initiateWrite(opts: {
+    peer: string;
+    stream: ReadableStream<Uint8Array>;
+    size: number;
+    contentType?: string;
+    name?: string;
+    signal?: AbortSignal;
+    onProgress?: (p: TransferProgress) => void;
+  }): Promise<{ writeId: string; handle: TransferHandle }>;
+
+  /**
+   * Wait for an inbound transfer carrying `userMetadata.shadeFilesReadStreamId
+   * === streamId` from `expectedFrom`. Resolves with the parked entry whose
+   * `readable` can be consumed by the caller.
+   */
+  awaitRead(streamId: string, opts: AwaitReadOptions): Promise<ParkedRead>;
+
+  destroy(): Promise<void>;
+}
+
+interface PendingReadWaiter {
+  resolve: (parked: ParkedRead) => void;
+  reject: (err: unknown) => void;
+  expectedFrom: string;
+  timer: ReturnType<typeof setTimeout> | null;
+  abortListener: (() => void) | null;
+  signal: AbortSignal;
+}
+
+export interface CreateClientStreamsBridgeOptions {
+  /** Default deadline for `awaitRead` if the caller doesn't supply one. */
+  defaultAwaitReadTimeoutMs?: number;
+  /** How long to retain a parked transfer waiting for its RPC. Default 60_000. */
+  parkedReadTtlMs?: number;
+}
+
+export async function createClientStreamsBridge(
+  shade: StreamsBridgeShade,
+  options: CreateClientStreamsBridgeOptions = {},
+): Promise<ClientStreamsBridge> {
+  const parkedReadTtlMs = options.parkedReadTtlMs ?? 60_000;
+  const defaultAwaitTimeoutMs = options.defaultAwaitReadTimeoutMs ?? 60_000;
+
+  const parked = new Map<string, ParkedRead>();
+  const waiters = new Map<string, PendingReadWaiter>();
+  let destroyed = false;
+
+  const unsubscribe = await shade.onIncomingTransfer(async (incoming) => {
+    const readStreamId = incoming.metadata.userMetadata?.[META_KEY_READ_STREAM_ID];
+    if (readStreamId === undefined) return;
+
+    const ts = new TransformStream<Uint8Array, Uint8Array>();
+    let handle: TransferHandle;
+    try {
+      handle = await incoming.accept({
+        output: { kind: 'pipe', pipeTo: ts.writable },
+      });
+    } catch (err) {
+      console.error('[shade-files client streams-bridge] accept failed:', err);
+      return;
+    }
+
+    const arrival: ParkedRead = {
+      from: incoming.from,
+      readable: ts.readable,
+      done: handle.done().then((r) => ({ sha256: r.sha256, bytesSent: r.bytesSent })),
+      handle,
+      arrivedAt: Date.now(),
+    };
+    arrival.done.catch(() => {
+      /* swallow until consumer awaits */
+    });
+
+    const waiter = waiters.get(readStreamId);
+    if (waiter !== undefined) {
+      waiters.delete(readStreamId);
+      cleanupWaiter(waiter);
+      if (incoming.from !== waiter.expectedFrom) {
+        void handle.abort('sender-mismatch').catch(() => undefined);
+        waiter.reject(
+          new Error(
+            `streams-bridge: readStreamId=${readStreamId} delivered by ${incoming.from}, expected ${waiter.expectedFrom}`,
+          ),
+        );
+        return;
+      }
+      waiter.resolve(arrival);
+      return;
+    }
+
+    parked.set(readStreamId, arrival);
+    setTimeout(() => {
+      const stale = parked.get(readStreamId);
+      if (stale === arrival) {
+        parked.delete(readStreamId);
+        void handle.abort('rpc-timeout').catch(() => undefined);
+      }
+    }, parkedReadTtlMs).unref?.();
+  });
+
+  function cleanupWaiter(w: PendingReadWaiter): void {
+    if (w.timer !== null) clearTimeout(w.timer);
+    if (w.abortListener !== null) {
+      w.signal.removeEventListener('abort', w.abortListener);
+    }
+  }
+
+  return {
+    async initiateWrite(opts) {
+      if (destroyed) throw new Error('streams-bridge: destroyed');
+      const writeId = generateRequestId();
+      const transferOpts: import('@shade/transfer').TransferOptions = {
+        to: opts.peer,
+        input: opts.stream,
+        metadata: {
+          ...(opts.name !== undefined ? { name: opts.name } : {}),
+          ...(opts.contentType !== undefined ? { contentType: opts.contentType } : {}),
+          sizeBytes: opts.size,
+          userMetadata: { [META_KEY_WRITE_ID]: writeId },
+        },
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+        ...(opts.onProgress !== undefined ? { onProgress: opts.onProgress } : {}),
+      };
+      const handle = await shade.upload(transferOpts);
+      return { writeId, handle };
+    },
+
+    async awaitRead(streamId, opts) {
+      if (destroyed) throw new Error('streams-bridge: destroyed');
+      const ready = parked.get(streamId);
+      if (ready !== undefined) {
+        parked.delete(streamId);
+        if (ready.from !== opts.expectedFrom) {
+          void ready.handle.abort('sender-mismatch').catch(() => undefined);
+          throw new Error(
+            `streams-bridge: readStreamId=${streamId} delivered by ${ready.from}, expected ${opts.expectedFrom}`,
+          );
+        }
+        return ready;
+      }
+      if (waiters.has(streamId)) {
+        throw new Error(`streams-bridge: readStreamId=${streamId} already awaited`);
+      }
+      const timeoutMs = opts.timeoutMs ?? defaultAwaitTimeoutMs;
+      return await new Promise<ParkedRead>((resolve, reject) => {
+        const w: PendingReadWaiter = {
+          resolve,
+          reject,
+          expectedFrom: opts.expectedFrom,
+          timer: null,
+          abortListener: null,
+          signal: opts.signal,
+        };
+        w.timer = setTimeout(() => {
+          if (waiters.get(streamId) === w) {
+            waiters.delete(streamId);
+            cleanupWaiter(w);
+            reject(new OperationTimeoutError(`streams-bridge: readStreamId=${streamId} timed out after ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+        if (opts.signal.aborted) {
+          cleanupWaiter(w);
+          reject(opts.signal.reason ?? new Error('aborted before await'));
+          return;
+        }
+        const onAbort = (): void => {
+          if (waiters.get(streamId) === w) {
+            waiters.delete(streamId);
+            cleanupWaiter(w);
+            reject(opts.signal.reason ?? new Error('aborted'));
+          }
+        };
+        w.abortListener = onAbort;
+        opts.signal.addEventListener('abort', onAbort, { once: true });
+        waiters.set(streamId, w);
+      });
+    },
+
+    async destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      unsubscribe();
+      for (const w of waiters.values()) {
+        cleanupWaiter(w);
+        w.reject(new Error('streams-bridge: destroyed'));
+      }
+      waiters.clear();
+      for (const p of parked.values()) {
+        try {
+          await p.handle.abort('bridge-destroyed');
+        } catch {
+          /* swallow */
+        }
+      }
+      parked.clear();
+    },
+  };
+}