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>

docs/shade-overview.html

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
-<html lang="no">
+<html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Shade — ende-til-ende kryptering som modul</title>
+  <title>Shade — end-to-end encryption as a module</title>
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
   <link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,400;0,9..144,600;0,9..144,700;1,9..144,400&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;1,8..60,400&display=swap" rel="stylesheet" />
@@ -364,32 +364,32 @@
     <header>
       <h1>Shade</h1>
       <p class="lede">
-        En gjenbrukbar modul for <strong style="color: var(--text); font-weight: 600;">ende-til-ende-kryptert</strong> kommunikasjon i egne apper — med samme type protokoll som brukes i Signal.
+        A reusable module for <strong style="color: var(--text); font-weight: 600;">end-to-end encrypted</strong> communication in your own apps — using the same kind of protocol as Signal.
       </p>
       <div class="badge-row">
         <span class="badge">X3DH</span>
         <span class="badge">Double Ratchet</span>
         <span class="badge">TypeScript</span>
-        <span class="badge">Plattformagnostisk crypto</span>
+        <span class="badge">Platform-agnostic crypto</span>
       </div>
     </header>
 
-    <section id="hva">
-      <h2>Hva gjør prosjektet?</h2>
+    <section id="what">
+      <h2>What does the project do?</h2>
       <p>
-        <strong>Shade</strong> er et monorepo som implementerer sikker meldingskryptering mellom to parter (for eksempel nettleser og server, eller to klienter). Meldingene er kryptert slik at transportlaget (HTTP, WebSocket, e.l.) bare ser uleselige bytes — ikke innholdet.
+        <strong>Shade</strong> is a monorepo that implements secure messaging encryption between two parties (for example browser and server, or two clients). Messages are encrypted so the transport layer (HTTP, WebSocket, etc.) only sees opaque bytes — not the content.
       </p>
       <div class="callout">
-        <strong>Kjerneideen:</strong> Du bygger inn <code>ShadeSessionManager</code> (fra <code>@shade/core</code>) sammen med en <code>CryptoProvider</code> (f.eks. Web Crypto i nettleser/Bun) og lagring. Deretter kan du kalle <code>encrypt</code> / <code>decrypt</code> per motpart, akkurat som i demo-koden <code>demo.ts</code>.
+        <strong>Core idea:</strong> Embed <code>ShadeSessionManager</code> (from <code>@shade/core</code>) together with a <code>CryptoProvider</code> (e.g. Web Crypto in the browser/Bun) and storage. Then call <code>encrypt</code> / <code>decrypt</code> per peer, just like in the demo code <code>demo.ts</code>.
       </div>
       <p>
-        Første melding til noen ny inneholder nøkkelavtale (X3DH). Etterpå bruker hver melding <em>Double Ratchet</em>: nye meldingsnøkler og periodiske DH-steg gir <strong>forward secrecy</strong> (gamle meldinger overlever ikke nøkkellekkasje) og <strong>post-compromise security</strong> (systemet «helbreder» seg over tid etter kompromittering).
+        The first message to someone new performs key agreement (X3DH). After that each message uses the <em>Double Ratchet</em>: fresh message keys and periodic DH steps provide <strong>forward secrecy</strong> (past messages do not survive key compromise) and <strong>post-compromise security</strong> (the system “recovers” over time after a compromise).
       </p>
     </section>
 
-    <section id="pakker">
-      <h2>Pakkene (hvordan det henger sammen)</h2>
-      <div class="tabs" role="tablist" aria-label="Pakkeoversikt">
+    <section id="packages">
+      <h2>Packages (how they fit)</h2>
+      <div class="tabs" role="tablist" aria-label="Package overview">
         <button type="button" class="tab-btn" role="tab" id="tab-core" aria-selected="true" aria-controls="panel-core">shade-core</button>
         <button type="button" class="tab-btn" role="tab" id="tab-crypto" aria-selected="false" aria-controls="panel-crypto">shade-crypto-web</button>
         <button type="button" class="tab-btn" role="tab" id="tab-proto" aria-selected="false" aria-controls="panel-proto">shade-proto</button>
@@ -397,117 +397,117 @@
         <button type="button" class="tab-btn" role="tab" id="tab-server" aria-selected="false" aria-controls="panel-server">shade-server</button>
       </div>
       <div id="panel-core" class="tab-panel active" role="tabpanel" aria-labelledby="tab-core">
-        <p style="margin-top:0"><strong>Protokollen.</strong> X3DH, Double Ratchet, sesjonstyper, feiltyper. Ingen plattformkrypto her — bare grensesnittet <code>CryptoProvider</code>.</p>
+        <p style="margin-top:0"><strong>The protocol.</strong> X3DH, Double Ratchet, session shapes, errors. No platform crypto here — only the <code>CryptoProvider</code> interface.</p>
         <ul>
-          <li><code>ShadeSessionManager</code> — høynivå-API: <code>initialize</code>, <code>createPreKeyBundle</code>, <code>initSessionFromBundle</code>, <code>encrypt</code>, <code>decrypt</code></li>
-          <li>Symmetrisk kryptering: <strong>AES-256-GCM</strong> med AAD fra ratchet-header</li>
+          <li><code>ShadeSessionManager</code> — high-level API: <code>initialize</code>, <code>createPreKeyBundle</code>, <code>initSessionFromBundle</code>, <code>encrypt</code>, <code>decrypt</code></li>
+          <li>Symmetric encryption: <strong>AES-256-GCM</strong> with AAD from the ratchet header</li>
         </ul>
       </div>
       <div id="panel-crypto" class="tab-panel" role="tabpanel" aria-labelledby="tab-crypto" hidden>
-        <p style="margin-top:0"><strong>Implementasjon av crypto for web/Bun/Node</strong> via SubtleCrypto — X25519, Ed25519, HKDF, HMAC, tilfeldige bytes.</p>
+        <p style="margin-top:0"><strong>Crypto implementation for web/Bun/Node</strong> via SubtleCrypto — X25519, Ed25519, HKDF, HMAC, random bytes.</p>
         <ul>
-          <li>Gjør det mulig å bruke <code>shade-core</code> i nettleser og i servere som støtter Web Crypto</li>
-          <li>Kommentarer i koden peker på fremtidig Android (f.eks. Tink) som egen provider</li>
+          <li>Lets you use <code>shade-core</code> in the browser and on servers that support Web Crypto</li>
+          <li>Comments in source point toward future Android (e.g. Tink) as a separate provider</li>
         </ul>
       </div>
       <div id="panel-proto" class="tab-panel" role="tabpanel" aria-labelledby="tab-proto" hidden>
-        <p style="margin-top:0"><strong>Binært wire-format</strong> for meldinger: versjon + type + lengdeprefiksede felt (big-endian).</p>
+        <p style="margin-top:0"><strong>Binary wire format</strong> for messages: version + type + length-prefixed fields (big-endian).</p>
         <ul>
           <li>Type <code>0x01</code> = PreKeyMessage, <code>0x02</code> = RatchetMessage</li>
-          <li>Brukes når du vil serialisere <code>ShadeEnvelope</code> effektivt over nettet</li>
+          <li>Use when you want to serialize <code>ShadeEnvelope</code> efficiently on the wire</li>
         </ul>
       </div>
       <div id="panel-transport" class="tab-panel" role="tabpanel" aria-labelledby="tab-transport" hidden>
-        <p style="margin-top:0"><strong>Transportadaptere</strong> — ikke selve krypteringen, men hvordan du sender bytes (f.eks. fetch eller WebSocket).</p>
+        <p style="margin-top:0"><strong>Transport adapters</strong> — not encryption itself, but how you move bytes (e.g. fetch or WebSocket).</p>
         <ul>
-          <li>Kobler applikasjonen din til den kanalen du allerede bruker</li>
+          <li>Hooks your application to the channel you already use</li>
         </ul>
       </div>
       <div id="panel-server" class="tab-panel" role="tabpanel" aria-labelledby="tab-server" hidden>
-        <p style="margin-top:0"><strong>Prekey-server (Hono)</strong> — lagrer offentlige nøkler slik at Alice kan starte samtale mens Bob er «offline».</p>
+        <p style="margin-top:0"><strong>Prekey server (Hono)</strong> — stores public keys so Alice can start a conversation while Bob is “offline”.</p>
         <ul>
-          <li><code>POST /v1/keys/register</code> — registrer identitet + bundle</li>
-          <li><code>GET /v1/keys/bundle/:address</code> — hent bundle (forbruker én engangsnøkkel om tilgjengelig)</li>
-          <li><code>POST /v1/keys/replenish</code> — etterfyll engangsnøkler</li>
+          <li><code>POST /v1/keys/register</code> — register identity + bundle</li>
+          <li><code>GET /v1/keys/bundle/:address</code> — fetch bundle (consumes one-time prekey when available)</li>
+          <li><code>POST /v1/keys/replenish</code> — replenish one-time prekeys</li>
         </ul>
       </div>
     </section>
 
-    <section id="nokler">
-      <h2>Nøkler i korthet</h2>
+    <section id="keys-in-brief">
+      <h2>Keys at a glance</h2>
       <div class="accordion" id="key-acc">
         <div class="acc-item">
           <button type="button" class="acc-trigger" aria-expanded="true" aria-controls="acc-identity" id="btn-identity">
-            Identitetsnøkkel (langvarig)
+            Identity key (long-term)
           </button>
           <div class="acc-panel" id="acc-identity" role="region" aria-labelledby="btn-identity">
-            <strong>Ed25519</strong> brukes til å signere den «signerte prekeyen». <strong>X25519</strong> brukes i Diffie-Hellman i X3DH og i ratchet. Én identitet per enhet/bruker i typisk oppsett.
+            <strong>Ed25519</strong> signs the “signed prekey”. <strong>X25519</strong> is used in Diffie–Hellman in X3DH and in the ratchet. One identity per device/user is typical.
           </div>
         </div>
         <div class="acc-item">
           <button type="button" class="acc-trigger" aria-expanded="false" aria-controls="acc-spk" id="btn-spk">
-            Signert prekey (mediumvarig, roteres)
+            Signed prekey (medium-lived, rotated)
           </button>
           <div class="acc-panel" id="acc-spk" role="region" aria-labelledby="btn-spk" hidden>
-            X25519-nøkkel som publiseres og signeres med identiteten. Mottaker verifiserer signaturen før DH. I koden anbefales rotasjon omtrent hver 1–7 dag.
+            An X25519 key that is published and signed by the identity. The recipient verifies the signature before DH. The codebase recommends rotation on the order of 1–7 days.
           </div>
         </div>
         <div class="acc-item">
           <button type="button" class="acc-trigger" aria-expanded="false" aria-controls="acc-otpk" id="btn-otpk">
-            Engangsnøkler (one-time prekeys)
+            One-time prekeys
           </button>
           <div class="acc-panel" id="acc-otpk" role="region" aria-labelledby="btn-otpk" hidden>
-            Valgfrie, men viktige for ekstra sikkerhet: hver hentet bundle kan inkludere én engangsnøkkel som slettes etter bruk (<code>processPreKeyMessage</code> fjerner den fra lager). Gir bedre beskyttelse mot visse angrep når mange klienter kobler til samme mottaker.
+            Optional but important for stronger security: each fetched bundle can include one one-time key that is removed after use (<code>processPreKeyMessage</code> clears it from storage). Improves protection against certain attacks when many clients connect to the same recipient.
           </div>
         </div>
       </div>
     </section>
 
-    <section id="flyt">
-      <h2>Interaktiv flyt: fra null til kryptert melding</h2>
+    <section id="flow-demo">
+      <h2>Interactive flow: zero to encrypted message</h2>
       <p>
-        Klikk «Neste» for å gå gjennom rekkefølgen slik Shade er bygget. Dette speiler <code>ShadeSessionManager</code> og demoen i repoet.
+        Click “Next step” to walk through the sequence as Shade builds it. This mirrors <code>ShadeSessionManager</code> and the demo in the repo.
       </p>
       <div class="flow">
-        <h3>Sesjon og meldinger</h3>
+        <h3>Sessions and messages</h3>
         <div class="flow-steps" id="flow-steps"></div>
         <div class="flow-actions">
-          <button type="button" class="btn" id="flow-next">Neste steg</button>
-          <button type="button" class="btn btn-secondary" id="flow-reset">Start på nytt</button>
+          <button type="button" class="btn" id="flow-next">Next step</button>
+          <button type="button" class="btn btn-secondary" id="flow-reset">Start over</button>
         </div>
       </div>
     </section>
 
     <section id="x3dh-ratchet">
-      <h2>X3DH og Double Ratchet (kort forklart)</h2>
+      <h2>X3DH and Double Ratchet (brief)</h2>
       <p>
-        <strong>X3DH</strong> løser problemet «jeg vil snakke med Bob nå, men Bob svarer ikke før senere». Bob legger ut en <em>prekey bundle</em> på serveren. Alice henter den, gjør 3 eller 4 DH-operasjoner (avhengig av om engangsnøkkel brukes), og deriverer en felles rot-nøkkel som begge kan rekonstruere uten at serveren kjenner hemmeligheten.
+        <strong>X3DH</strong> solves “I want to talk to Bob now, but Bob may not reply until later”. Bob publishes a <em>prekey bundle</em> on the server. Alice fetches it, runs 3 or 4 DH operations (depending on whether a one-time key is used), and derives a shared root key both parties can reconstruct — without the server learning the secret.
       </p>
       <p>
-        <strong>Double Ratchet</strong> bruker den roten som startpunkt. For hver melding (eller ved nye DH-nøkler) avledes nye nøkler; meldinger på ledningen er AES-GCM med autentisering (AAD binder kryptoteksten til ratchet-header). Protokollen håndterer også meldinger i feil rekkefølge innenfor grenser (<code>MAX_SKIP</code>).
+        <strong>Double Ratchet</strong> uses that root as a starting point. For each message (or when new DH keys spin), keys are derived; on the wire payloads are AES-GCM with authentication (AAD binds ciphertext to the ratchet header). The protocol also tolerates messages arriving out of order within limits (<code>MAX_SKIP</code>).
       </p>
       <p>
-        Spesifikasjoner fra Signal (engelsk): <a href="https://signal.org/docs/specifications/x3dh/" target="_blank" rel="noopener">X3DH</a> · <a href="https://signal.org/docs/specifications/doubleratchet/" target="_blank" rel="noopener">Double Ratchet</a>.
+        Signal specifications (English): <a href="https://signal.org/docs/specifications/x3dh/" target="_blank" rel="noopener">X3DH</a> · <a href="https://signal.org/docs/specifications/doubleratchet/" target="_blank" rel="noopener">Double Ratchet</a>.
       </p>
     </section>
 
-    <section id="gjenbruk">
-      <h2>Bruke Shade i flere prosjekter</h2>
+    <section id="reuse">
+      <h2>Using Shade across projects</h2>
       <p>
-        Tenk på Shade som tre lag du kan kombinere etter behov:
+        Treat Shade as three layers you combine as needed:
       </p>
       <ol>
-        <li><strong>Core + crypto-provider + storage</strong> — selve E2EE-motoren (kan kjøre i klient eller serverprosess som skal dekryptere).</li>
-        <li><strong>Proto</strong> — når du vil ha kompakt binær serialisering.</li>
-        <li><strong>Transport + prekey-server</strong> — når du vil standardisere nøkkelutveksling og kanaler.</li>
+        <li><strong>Core + crypto provider + storage</strong> — the E2EE engine itself (runs in a client or a server process that must decrypt).</li>
+        <li><strong>Proto</strong> — when you want compact binary serialization.</li>
+        <li><strong>Transport + prekey server</strong> — when you want standardized key discovery and channels.</li>
       </ol>
       <p>
-        Referansekjøring: <code class="mono">bun demo.ts</code> i rotmappen viser frontend/backend-flyt med minnelager og ekte kryptoprimitiver.
+        Reference path: <code class="mono">bun demo.ts</code> from the repo root shows a frontend/backend flow with memory storage and real crypto primitives.
       </p>
     </section>
 
     <footer>
-      <p>Shade — oversikt generert som statisk HTML i <code class="mono">docs/shade-overview.html</code>. Åpne filen direkte i nettleseren eller server den statisk.</p>
+      <p>Shade — overview written as static HTML in <code class="mono">docs/shade-overview.html</code>. Open the file directly in the browser or serve it as static assets.</p>
     </footer>
   </div>
 
@@ -561,28 +561,28 @@
       // Flow steps
       var steps = [
         {
-          title: "Initialiser klient",
-          body: "Kall initialize(): last eller generer identitetsnøkkel (Ed25519 + X25519), registrationId og signert prekey.",
+          title: "Initialize client",
+          body: "Call initialize(): load or generate the identity keys (Ed25519 + X25519), registrationId, and signed prekey.",
         },
         {
-          title: "Publiser prekey bundle",
-          body: "Bygg bundle med createPreKeyBundle() / generateOneTimePreKeys() og registrer på prekey-server (eller del ut av band for demo).",
+          title: "Publish prekey bundle",
+          body: "Build a bundle with createPreKeyBundle() / generateOneTimePreKeys() and register it on the prekey server (or share out-of-band for a demo).",
         },
         {
-          title: "Start sesjon mot peer",
-          body: "Hent motpartens bundle, kjør initSessionFromBundle(address, bundle). X3DH kjører og ratchet-sesjon lagres i StorageProvider.",
+          title: "Start session with peer",
+          body: "Fetch the peer bundle, run initSessionFromBundle(address, bundle). X3DH runs and the ratchet session is stored in StorageProvider.",
         },
         {
-          title: "Første encrypt",
-          body: "encrypt() returnerer ShadeEnvelope type 'prekey': inneholder ephemeral nøkkel, prekey-ID-er og første RatchetMessage (AES-GCM).",
+          title: "First encrypt",
+          body: "encrypt() returns a ShadeEnvelope of type 'prekey': includes ephemeral keys, prekey IDs, and the first RatchetMessage (AES-GCM).",
         },
         {
-          title: "Motpart decrypt",
-          body: "decrypt() på PreKeyMessage: gjenskaper samme root key, initReceiverSession, ratchetDecrypt — plaintext ut.",
+          title: "Peer decrypt",
+          body: "decrypt() on PreKeyMessage: restores the same root key, initReceiverSession, ratchetDecrypt — plaintext out.",
         },
         {
-          title: "Videre meldinger",
-          body: "Neste kall til encrypt() gir type 'ratchet'. DH-ratchet steg gir nye kjeder og forbedret sikkerhet over tid.",
+          title: "Further messages",
+          body: "The next encrypt() calls yield type 'ratchet'. DH ratchet steps rotate chains and improve security over time.",
         },
       ];