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>

examples/07-streams-upload/README.md

@@ -0,0 +1,28 @@
+# Example 07 — E2EE file upload with Shade Streams
+
+Two Bun processes, both running real `Shade` instances. Alice uploads a file
+to Bob; the file is chunked, encrypted per-chunk under a per-lane key, sent
+over HTTP across 4 parallel lanes, and verified end-to-end.
+
+## Files
+
+- `prekey-server.ts` — boots a `@shade/server` prekey server on port 9991.
+- `bob-receiver.ts` — Bob's Shade runtime + a Bun HTTP server that mounts
+  `Shade.transferRoute()`. Saves incoming files to `./received/`.
+- `alice-sender.ts` — Alice's Shade runtime; uploads a file to Bob.
+
+## Run
+
+```bash
+# Terminal 1 — prekey server
+bun run examples/07-streams-upload/prekey-server.ts
+
+# Terminal 2 — Bob (receiver)
+bun run examples/07-streams-upload/bob-receiver.ts
+
+# Terminal 3 — Alice (sender)
+bun run examples/07-streams-upload/alice-sender.ts ./path/to/file
+```
+
+The receiver writes the decrypted file to `./received/<filename>` and prints
+the matching sha256.

examples/07-streams-upload/alice-sender.ts

@@ -0,0 +1,54 @@
+/**
+ * Alice — sender. Uploads a local file to Bob using 4 parallel lanes,
+ * 1 MiB chunks, and the default HTTP transport. Prints sender-side
+ * progress + the verified sha256 on completion.
+ *
+ * Usage:
+ *   bun run examples/07-streams-upload/alice-sender.ts <path/to/file>
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { createShade } from '@shade/sdk';
+
+const PREKEY_URL = 'http://localhost:9991';
+const BOB_BASE_URL = 'http://localhost:9992';
+
+const filePath = process.argv[2];
+if (filePath === undefined || filePath === '') {
+  console.error('usage: alice-sender.ts <path/to/file>');
+  process.exit(2);
+}
+
+const bytes = await readFile(filePath);
+const name = basename(filePath);
+
+const alice = await createShade({ prekeyServer: PREKEY_URL, address: 'alice' });
+
+alice.configureTransfers({
+  resolveBaseUrl: async (peer) => {
+    if (peer === 'bob') return BOB_BASE_URL;
+    throw new Error(`unknown peer ${peer}`);
+  },
+});
+
+console.log(`[alice] uploading ${name} (${bytes.length} bytes) → bob`);
+
+const handle = await alice.upload({
+  to: 'bob',
+  input: new Uint8Array(bytes),
+  lanes: 4,
+  chunkSize: 1024 * 1024,
+  metadata: { name },
+  onProgress: (p) => {
+    const pct = p.percent !== undefined ? `${(p.percent * 100).toFixed(1)}%` : '—';
+    const mbps = (p.bytesPerSecond / (1024 * 1024)).toFixed(2);
+    process.stdout.write(`\r[alice] ${pct}   ${mbps} MB/s   ${p.bytesSent}/${p.bytesTotal ?? '?'} B`);
+  },
+});
+
+const result = await handle.done();
+process.stdout.write('\n');
+console.log(`[alice] done — ${result.bytesSent} B in ${result.durationMs.toFixed(0)} ms`);
+console.log(`[alice] sha256 = ${result.sha256}`);
+
+await alice.shutdown();

examples/07-streams-upload/bob-receiver.ts

@@ -0,0 +1,36 @@
+/**
+ * Bob — receiver. Boots a Shade runtime and mounts the transfer route on
+ * port 9992. Incoming uploads are decrypted, integrity-checked, and saved
+ * to ./received/<filename>.
+ */
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createShade } from '@shade/sdk';
+
+const PREKEY_URL = 'http://localhost:9991';
+const PORT = 9992;
+const OUT_DIR = join(import.meta.dir, 'received');
+mkdirSync(OUT_DIR, { recursive: true });
+
+const bob = await createShade({ prekeyServer: PREKEY_URL, address: 'bob' });
+
+bob.configureTransfers({
+  resolveBaseUrl: async () => {
+    throw new Error('bob is receive-only');
+  },
+});
+
+bob.onIncomingTransfer(async (incoming) => {
+  const name = incoming.metadata.name ?? incoming.streamId;
+  const path = join(OUT_DIR, name.replace(/[^a-zA-Z0-9._-]/g, '_'));
+  console.log(`[bob] incoming "${name}" from ${incoming.from} → ${path}`);
+  const handle = await incoming.accept({ output: { kind: 'file', path } });
+  void handle.done().then((result) => {
+    console.log(`[bob] done "${name}" — ${result.bytesSent} B, sha256=${result.sha256}`);
+  });
+});
+
+const app = await bob.transferRoute();
+Bun.serve({ port: PORT, fetch: app.fetch });
+console.log(`Bob's transfer endpoint listening on http://localhost:${PORT}`);
+console.log(`Saving incoming files to ${OUT_DIR}`);

examples/07-streams-upload/prekey-server.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal Shade prekey server for the streams example.
+ * Run on port 9991 — both Alice and Bob register here.
+ */
+import { createPrekeyServer, MemoryPrekeyStore } from '@shade/server';
+import { SubtleCryptoProvider } from '@shade/crypto-web';
+
+const crypto = new SubtleCryptoProvider();
+const server = createPrekeyServer({
+  crypto,
+  store: new MemoryPrekeyStore(),
+  disableRateLimit: true,
+});
+
+const port = 9991;
+Bun.serve({ port, fetch: server.fetch });
+console.log(`Prekey server listening on http://localhost:${port}`);

examples/08-files-browser/README.md

@@ -0,0 +1,31 @@
+# 08 — Files Browser (E2EE filesystem RPC)
+
+Two-process demo of `@shade/files`: Alice (CLI) talks to Bob (file server) over
+Double Ratchet–encrypted RPC. Bob's filesystem is rooted at `./files-root/`.
+
+## Run
+
+```sh
+# Terminal 1 — prekey server
+bun run examples/08-files-browser/prekey-server.ts
+
+# Terminal 2 — Bob's file server
+bun run examples/08-files-browser/bob-server.ts
+
+# Terminal 3 — Alice issues commands
+bun run examples/08-files-browser/alice-cli.ts mkdir /docs
+bun run examples/08-files-browser/alice-cli.ts upload ./README.md /docs/readme.md
+bun run examples/08-files-browser/alice-cli.ts list /docs
+bun run examples/08-files-browser/alice-cli.ts stat /docs/readme.md
+bun run examples/08-files-browser/alice-cli.ts download /docs/readme.md /tmp/out.md
+bun run examples/08-files-browser/alice-cli.ts delete /docs/readme.md
+```
+
+## What it shows
+
+* Standard ops: `list`, `stat`, `mkdir`, `delete`, `move`.
+* Content I/O: `read`/`write` with automatic inline (≤ 256 KiB) /
+  streams (> 256 KiB) routing — handled transparently by the SDK.
+* sha256 paritet: streaming downloads return the verified hash.
+* Two ratchets, end-to-end encrypted. No content ever leaves either
+  process unencrypted.

examples/08-files-browser/alice-cli.ts

@@ -0,0 +1,108 @@
+/**
+ * Alice — the file CLIENT. Demonstrates the typed `@shade/files` API:
+ *
+ *   bun run examples/08-files-browser/alice-cli.ts list /
+ *   bun run examples/08-files-browser/alice-cli.ts mkdir /docs
+ *   bun run examples/08-files-browser/alice-cli.ts upload ./README.md /docs/readme.md
+ *   bun run examples/08-files-browser/alice-cli.ts download /docs/readme.md ./out.md
+ *   bun run examples/08-files-browser/alice-cli.ts stat /docs/readme.md
+ *   bun run examples/08-files-browser/alice-cli.ts delete /docs/readme.md
+ */
+import { readFile, writeFile, stat as fsstat } from 'node:fs/promises';
+import { createShade } from '@shade/sdk';
+
+const PREKEY = 'http://localhost:9992';
+const ALICE_BASE_URL = 'http://localhost:9993';
+const BOB_BASE_URL = 'http://localhost:9994';
+
+const alice = await createShade({ prekeyServer: PREKEY, address: 'alice' });
+alice.configureTransfers({
+  resolveBaseUrl: async (peer) => {
+    if (peer === 'bob') return BOB_BASE_URL;
+    throw new Error(`alice: unknown peer ${peer}`);
+  },
+});
+const app = await alice.transferRoute();
+Bun.serve({ port: 9993, fetch: app.fetch });
+
+const fs = await alice.files.client('bob', { defaultTimeoutMs: 30_000 });
+
+const [cmd, ...args] = process.argv.slice(2);
+try {
+  switch (cmd) {
+    case 'list': {
+      const path = args[0] ?? '/';
+      const result = await fs.list(path);
+      for (const e of result.entries) {
+        console.log(`${e.kind === 'dir' ? 'd' : '-'}  ${String(e.size).padStart(10)}  ${e.name}`);
+      }
+      break;
+    }
+    case 'stat': {
+      const path = args[0]!;
+      const e = await fs.stat(path);
+      console.log(JSON.stringify(e, null, 2));
+      break;
+    }
+    case 'mkdir': {
+      const path = args[0]!;
+      const r = await fs.mkdir(path, { recursive: true });
+      console.log(`created ${r.entry.name}`);
+      break;
+    }
+    case 'delete': {
+      const path = args[0]!;
+      const r = await fs.delete(path, { recursive: true });
+      console.log(`deleted ${r.deletedCount} entrie(s)`);
+      break;
+    }
+    case 'upload': {
+      const localPath = args[0]!;
+      const remotePath = args[1]!;
+      const bytes = new Uint8Array(await readFile(localPath));
+      const s = await fsstat(localPath);
+      console.log(`uploading ${s.size} bytes → ${remotePath}`);
+      const r = await fs.write(remotePath, bytes, { overwrite: true });
+      console.log(`done — remote size: ${r.entry.size}`);
+      break;
+    }
+    case 'download': {
+      const remotePath = args[0]!;
+      const localPath = args[1]!;
+      const result = await fs.read(remotePath);
+      if (result.kind === 'inline') {
+        await writeFile(localPath, result.bytes);
+        console.log(`downloaded ${result.bytes.byteLength} bytes (inline) sha256=${result.sha256}`);
+      } else {
+        const reader = result.stream.getReader();
+        const chunks: Uint8Array[] = [];
+        let total = 0;
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (value !== undefined) {
+            chunks.push(value);
+            total += value.byteLength;
+          }
+        }
+        reader.releaseLock();
+        const out = new Uint8Array(total);
+        let offset = 0;
+        for (const c of chunks) {
+          out.set(c, offset);
+          offset += c.byteLength;
+        }
+        await writeFile(localPath, out);
+        await result.done();
+        console.log(`downloaded ${total} bytes (streamed) sha256=${result.sha256}`);
+      }
+      break;
+    }
+    default:
+      console.error('Usage: alice-cli.ts <list|stat|mkdir|delete|upload|download> [args...]');
+      process.exit(1);
+  }
+} finally {
+  await alice.shutdown();
+  process.exit(0);
+}

examples/08-files-browser/bob-server.ts

@@ -0,0 +1,170 @@
+/**
+ * Bob — the file SERVER. Mounts a virtual filesystem rooted in this
+ * directory's `./files-root/` dir (created on first run) and serves it
+ * over `@shade/files` E2EE RPC.
+ *
+ * Demonstrates: list/stat/mkdir/delete/move + read/write inline+streams.
+ */
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { join, basename, dirname } from 'node:path';
+import { createShade } from '@shade/sdk';
+import {
+  ConflictError,
+  NotFoundError,
+  type FileEntry,
+  type UserReadResult,
+} from '@shade/files';
+
+const ROOT = join(import.meta.dir, 'files-root');
+await mkdir(ROOT, { recursive: true });
+
+const PREKEY = 'http://localhost:9992';
+const BOB_BASE_URL = 'http://localhost:9994';
+const ALICE_BASE_URL = 'http://localhost:9993';
+
+const bob = await createShade({ prekeyServer: PREKEY, address: 'bob' });
+bob.configureTransfers({
+  resolveBaseUrl: async (peer) => {
+    if (peer === 'alice') return ALICE_BASE_URL;
+    throw new Error(`bob: unknown peer ${peer}`);
+  },
+});
+const app = await bob.transferRoute();
+Bun.serve({ port: 9994, fetch: app.fetch });
+console.log(`[bob] listening on ${BOB_BASE_URL}, files at ${ROOT}`);
+
+function safePath(remote: string): string {
+  // Strip leading slash + reject any '..' (the dispatcher already does
+  // this, but we defend in depth).
+  const segments = remote.split('/').filter((s) => s !== '' && s !== '..');
+  return join(ROOT, ...segments);
+}
+
+await bob.files.serve({
+  list: async (ctx) => {
+    const local = safePath(ctx.path);
+    let names: string[];
+    try {
+      names = await readdir(local);
+    } catch {
+      throw new NotFoundError(ctx.path);
+    }
+    const entries: FileEntry[] = [];
+    for (const name of names) {
+      const s = await stat(join(local, name));
+      entries.push({
+        name,
+        kind: s.isDirectory() ? 'dir' : 'file',
+        size: s.isDirectory() ? 0 : s.size,
+        mtime: s.mtimeMs,
+        metadata: {},
+      });
+    }
+    return { entries, hasMore: false };
+  },
+  stat: async (ctx) => {
+    let s: import('node:fs').Stats;
+    try {
+      s = await stat(safePath(ctx.path));
+    } catch {
+      throw new NotFoundError(ctx.path);
+    }
+    return {
+      name: basename(ctx.path),
+      kind: s.isDirectory() ? 'dir' : 'file',
+      size: s.isDirectory() ? 0 : s.size,
+      mtime: s.mtimeMs,
+      metadata: {},
+    };
+  },
+  mkdir: async (ctx) => {
+    const local = safePath(ctx.path);
+    await mkdir(local, { recursive: ctx.args.recursive });
+    return {
+      entry: {
+        name: basename(ctx.path),
+        kind: 'dir',
+        size: 0,
+        mtime: Date.now(),
+        metadata: {},
+      },
+    };
+  },
+  delete: async (ctx) => {
+    await rm(safePath(ctx.path), { recursive: ctx.args.recursive, force: false });
+    return { deletedCount: 1 };
+  },
+  move: async (ctx) => {
+    await rename(safePath(ctx.args.src), safePath(ctx.args.dst));
+    return {
+      entry: {
+        name: basename(ctx.args.dst),
+        kind: 'file',
+        size: 0,
+        mtime: Date.now(),
+        metadata: {},
+      },
+    };
+  },
+  read: async (ctx): Promise<UserReadResult> => {
+    const local = safePath(ctx.path);
+    const s = await stat(local);
+    if (s.isDirectory()) throw new ConflictError(`${ctx.path} is a directory`);
+    if (s.size <= 256 * 1024) {
+      const bytes = new Uint8Array(await readFile(local));
+      return { kind: 'inline', bytes };
+    }
+    // Stream the file.
+    const sha256 = await computeSha256OfFile(local);
+    const stream = Readable.toWeb(createReadStream(local)) as ReadableStream<Uint8Array>;
+    return { kind: 'streams', stream, size: s.size, sha256 };
+  },
+  write: async (ctx) => {
+    const local = safePath(ctx.args.path);
+    await mkdir(dirname(local), { recursive: true });
+    if (ctx.args.content.kind === 'inline') {
+      await writeFile(local, ctx.args.content.bytes);
+    } else {
+      // Drain stream → temp buffer → file. For huge files use createWriteStream.
+      const reader = ctx.args.content.stream.getReader();
+      const chunks: Uint8Array[] = [];
+      let total = 0;
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value !== undefined) {
+          chunks.push(value);
+          total += value.byteLength;
+        }
+      }
+      reader.releaseLock();
+      const out = new Uint8Array(total);
+      let offset = 0;
+      for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+      }
+      await writeFile(local, out);
+      // Verify integrity (optional)
+      await ctx.args.content.sha256;
+    }
+    const s = await stat(local);
+    return {
+      entry: {
+        name: basename(ctx.args.path),
+        kind: 'file',
+        size: s.size,
+        mtime: s.mtimeMs,
+        metadata: {},
+      },
+    };
+  },
+});
+
+async function computeSha256OfFile(path: string): Promise<string> {
+  const { sha256 } = await import('@noble/hashes/sha2.js');
+  const data = new Uint8Array(await readFile(path));
+  return Array.from(sha256(data), (b) => b.toString(16).padStart(2, '0')).join('');
+}

examples/08-files-browser/prekey-server.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal Shade prekey server for the files-browser example.
+ * Run on port 9992 — both Alice and Bob register here.
+ */
+import { createPrekeyServer, MemoryPrekeyStore } from '@shade/server';
+import { SubtleCryptoProvider } from '@shade/crypto-web';
+
+const crypto = new SubtleCryptoProvider();
+const server = createPrekeyServer({
+  crypto,
+  store: new MemoryPrekeyStore(),
+  disableRateLimit: true,
+});
+
+const port = 9992;
+Bun.serve({ port, fetch: server.fetch });
+console.log(`[prekey] listening on http://localhost:${port}`);