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/protocol/canonical.ts

@@ -0,0 +1,72 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+
+/**
+ * Canonical bytes for an `@shade/files` RPC request signature.
+ *
+ *   "rpc\0addr=<sender>\0at=<signedAt>\0kind=<kind>\0id=<id>\0argsHash=<hex>\0"
+ *
+ * Mirror of `canonicalControlBytes` in `@shade/sdk/src/streams-bridge.ts:188`.
+ * The signature binds the (sender, op kind, request id, args, signedAt)
+ * tuple — defense-in-depth on top of Double Ratchet authentication.
+ */
+export function canonicalRpcBytes(args: {
+  address: string;
+  signedAt: number;
+  kind: string;
+  id: string;
+  argsHash: Uint8Array;
+}): Uint8Array {
+  const enc = new TextEncoder();
+  const fields = [
+    `rpc\0`,
+    `addr=${args.address}\0`,
+    `at=${args.signedAt}\0`,
+    `kind=${args.kind}\0`,
+    `id=${args.id}\0`,
+    `argsHash=${bytesToHex(args.argsHash)}\0`,
+  ];
+  return enc.encode(fields.join(''));
+}
+
+/**
+ * Stable canonical-JSON serialization for hashing args. Sorts object keys
+ * recursively so two equivalent inputs hash to identical bytes regardless
+ * of property order.
+ */
+export function canonicalJsonStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalJsonStringify(v)).join(',')}]`;
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  const parts: string[] = [];
+  for (const key of keys) {
+    if (obj[key] === undefined) continue;
+    parts.push(`${JSON.stringify(key)}:${canonicalJsonStringify(obj[key])}`);
+  }
+  return `{${parts.join(',')}}`;
+}
+
+/** Hash args via canonical-JSON → SHA-256 (32 bytes). */
+export function hashArgs(args: unknown): Uint8Array {
+  const enc = new TextEncoder();
+  return sha256(enc.encode(canonicalJsonStringify(args)));
+}
+
+export function bytesToHex(b: Uint8Array): string {
+  return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+export function bytesToBase64(b: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < b.length; i++) bin += String.fromCharCode(b[i]!);
+  return btoa(bin);
+}
+
+export function base64ToBytes(s: string): Uint8Array {
+  const bin = atob(s);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}

packages/shade-files/src/protocol/correlate.ts

@@ -0,0 +1,32 @@
+/**
+ * Generate a correlation ID — 16 random bytes, base64url-encoded (22 chars
+ * after stripping padding). Same shape as `RequestIdSchema`.
+ *
+ * Uses `globalThis.crypto.getRandomValues` so it works in Bun, Node ≥19,
+ * and browsers without any platform-specific imports.
+ */
+export function generateRequestId(): string {
+  const buf = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(buf);
+  return base64UrlEncode(buf);
+}
+
+/** Same as `generateRequestId` — distinct name for callsite clarity. */
+export function generateIdempotencyKey(): string {
+  return generateRequestId();
+}
+
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!);
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function base64UrlDecode(s: string): Uint8Array {
+  const padded = s.replace(/-/g, '+').replace(/_/g, '/');
+  const pad = padded.length % 4 === 0 ? '' : '='.repeat(4 - (padded.length % 4));
+  const bin = atob(padded + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}

packages/shade-files/src/protocol/envelope-codec.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import {
+  RpcCancelSchema,
+  RpcErrorSchema,
+  RpcRequestSchema,
+  RpcResponseSchema,
+  type RpcCancel,
+  type RpcEnvelope,
+  type RpcError,
+  type RpcRequest,
+  type RpcResponse,
+} from '../schemas/envelope.js';
+import { KIND_PREFIX } from './version.js';
+
+/** Tagged classification of any incoming envelope. */
+export type ClassifiedEnvelope =
+  | { kind: 'request'; envelope: RpcRequest }
+  | { kind: 'response'; envelope: RpcResponse }
+  | { kind: 'error'; envelope: RpcError }
+  | { kind: 'cancel'; envelope: RpcCancel };
+
+const RpcAnySchema = z.union([
+  RpcRequestSchema,
+  RpcResponseSchema,
+  RpcErrorSchema,
+  RpcCancelSchema,
+]);
+
+/** Encode an envelope to JSON plaintext for `Shade.send`. */
+export function encodeEnvelope(env: RpcEnvelope): string {
+  return JSON.stringify(env);
+}
+
+/**
+ * Quick-detection: does this plaintext look like an `@shade/files` envelope?
+ * Used by `ShadeFileRpcChannel` to skip non-files messages cheaply.
+ */
+export function looksLikeFileEnvelope(plaintext: string): boolean {
+  return plaintext.includes(KIND_PREFIX);
+}
+
+/**
+ * Parse and classify an incoming plaintext. Returns null on any malformed
+ * input — the channel ignores those silently (could be a different
+ * protocol on the same Shade.send pipe).
+ */
+export function tryParseEnvelope(plaintext: string): ClassifiedEnvelope | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(plaintext);
+  } catch {
+    return null;
+  }
+  const result = RpcAnySchema.safeParse(raw);
+  if (!result.success) return null;
+  return classify(result.data);
+}
+
+export function classify(env: RpcEnvelope): ClassifiedEnvelope {
+  if (env.kind === 'shade.fs.cancel/v1') {
+    return { kind: 'cancel', envelope: env as RpcCancel };
+  }
+  if (env.kind === 'shade.fs.error/v1') {
+    return { kind: 'error', envelope: env as RpcError };
+  }
+  if (env.kind.endsWith('.response')) {
+    return { kind: 'response', envelope: env as RpcResponse };
+  }
+  return { kind: 'request', envelope: env as RpcRequest };
+}

packages/shade-files/src/protocol/kinds.ts

@@ -0,0 +1,53 @@
+/** Canonical kind names for v1 ops. */
+export const KIND_LIST_V1 = 'shade.fs.list/v1' as const;
+export const KIND_STAT_V1 = 'shade.fs.stat/v1' as const;
+export const KIND_MKDIR_V1 = 'shade.fs.mkdir/v1' as const;
+export const KIND_DELETE_V1 = 'shade.fs.delete/v1' as const;
+export const KIND_MOVE_V1 = 'shade.fs.move/v1' as const;
+export const KIND_READ_V1 = 'shade.fs.read/v1' as const;
+export const KIND_WRITE_V1 = 'shade.fs.write/v1' as const;
+export const KIND_GET_THUMBNAIL_V1 = 'shade.fs.getThumbnail/v1' as const;
+export const KIND_CUSTOM_V1 = 'shade.fs.custom/v1' as const;
+
+export const KIND_ERROR_V1 = 'shade.fs.error/v1' as const;
+export const KIND_CANCEL_V1 = 'shade.fs.cancel/v1' as const;
+
+/** Compute the response kind from a request kind: `'shade.fs.foo/v1'` → `'shade.fs.foo/v1.response'`. */
+export function responseKindOf<K extends string>(kind: K): `${K}.response` {
+  return `${kind}.response`;
+}
+
+/** Standard op identifier — used in `OpContext.op`. */
+export type StandardOp =
+  | 'list'
+  | 'stat'
+  | 'mkdir'
+  | 'delete'
+  | 'move'
+  | 'read'
+  | 'write'
+  | 'getThumbnail';
+
+const KIND_TO_OP: Record<string, StandardOp> = {
+  [KIND_LIST_V1]: 'list',
+  [KIND_STAT_V1]: 'stat',
+  [KIND_MKDIR_V1]: 'mkdir',
+  [KIND_DELETE_V1]: 'delete',
+  [KIND_MOVE_V1]: 'move',
+  [KIND_READ_V1]: 'read',
+  [KIND_WRITE_V1]: 'write',
+  [KIND_GET_THUMBNAIL_V1]: 'getThumbnail',
+};
+
+export function opOfKind(kind: string): StandardOp | null {
+  return KIND_TO_OP[kind] ?? null;
+}
+
+/** Mutation ops require an idempotency key on retries. */
+export const MUTATION_OPS = new Set<StandardOp | 'custom'>([
+  'mkdir',
+  'delete',
+  'move',
+  'write',
+  'custom',
+]);

packages/shade-files/src/protocol/version.ts

@@ -0,0 +1,24 @@
+/** Wire-protocol version. Bump when introducing breaking changes. */
+export const SHADE_FILES_VERSION = '0.2.0';
+
+/** Substring every `@shade/files` plaintext starts with — used by the channel filter. */
+export const KIND_PREFIX = 'shade.fs';
+
+/** Currently-supported op kinds. Extend when introducing new versions. */
+export const SUPPORTED_KINDS = [
+  'shade.fs.list/v1',
+  'shade.fs.stat/v1',
+  'shade.fs.mkdir/v1',
+  'shade.fs.delete/v1',
+  'shade.fs.move/v1',
+  'shade.fs.read/v1',
+  'shade.fs.write/v1',
+  'shade.fs.getThumbnail/v1',
+  'shade.fs.custom/v1',
+] as const;
+export type SupportedKind = (typeof SUPPORTED_KINDS)[number];
+
+const SUPPORTED_KIND_SET = new Set<string>(SUPPORTED_KINDS);
+export function isSupportedKind(kind: string): kind is SupportedKind {
+  return SUPPORTED_KIND_SET.has(kind);
+}