@muhkoo/connect 0.10.14-alpha.0 → 0.12.0-alpha.0

package/dist/server/index.js

@@ -72,7 +72,7 @@ function randomBytes(n) {
 /** Length of the AES key in bytes. */
 const AES_GCM_KEY_BYTES = 32;
 /** Length of the AES-GCM IV in bytes (WebCrypto-recommended). */
-const AES_GCM_IV_BYTES = 12;
+const AES_GCM_IV_BYTES$1 = 12;
 /** Length of the AES-GCM authentication tag in bytes (appended to ciphertext). */
 const AES_GCM_TAG_BYTES = 16;
 /**
@@ -113,8 +113,8 @@ function assertKey(key) {
     }
 }
 function assertIv(iv) {
-    if (iv.byteLength !== AES_GCM_IV_BYTES) {
-        throw new Error(`aes-gcm: iv must be ${AES_GCM_IV_BYTES} bytes (got ${iv.byteLength})`);
+    if (iv.byteLength !== AES_GCM_IV_BYTES$1) {
+        throw new Error(`aes-gcm: iv must be ${AES_GCM_IV_BYTES$1} bytes (got ${iv.byteLength})`);
     }
 }
 
@@ -443,7 +443,7 @@ function fromHex(hex) {
     return out;
 }
 /** Encode a byte array as a standard base64 string. */
-function toBase64$1(bytes) {
+function toBase64$2(bytes) {
     let binary = "";
     for (let i = 0; i < bytes.length; i++) {
         binary += String.fromCharCode(bytes[i]);
@@ -451,7 +451,7 @@ function toBase64$1(bytes) {
     return btoa(binary);
 }
 /** Decode a standard base64 string to bytes. */
-function fromBase64$1(b64) {
+function fromBase64$2(b64) {
     const binary = atob(b64);
     const ab = new ArrayBuffer(binary.length);
     const out = new Uint8Array(ab);
@@ -461,13 +461,13 @@ function fromBase64$1(b64) {
 }
 /** Encode a byte array as a base64url string (no padding). */
 function toBase64Url(bytes) {
-    return toBase64$1(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return toBase64$2(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 /** Decode a base64url string (with or without padding) to bytes. */
 function fromBase64Url(b64url) {
     const padded = b64url.replace(/-/g, "+").replace(/_/g, "/") +
         "=".repeat((4 - (b64url.length % 4)) % 4);
-    return fromBase64$1(padded);
+    return fromBase64$2(padded);
 }
 /** Concatenate any number of byte arrays into a single Uint8Array. */
 function concatBytes(...arrays) {
@@ -1045,10 +1045,10 @@ class KeyStore {
     async packDehydratedKeys(id) {
         const dehydrated = await this.dehydrateKeyPair(id);
         const combined = JSON.stringify(dehydrated);
-        return toBase64$1(new TextEncoder().encode(combined));
+        return toBase64$2(new TextEncoder().encode(combined));
     }
     async hydrateFromPacked(id, masterKey) {
-        const decoded = utf8Decode(fromBase64$1(masterKey));
+        const decoded = utf8Decode(fromBase64$2(masterKey));
         const dehydrated = JSON.parse(decoded);
         await this.hydrateKeyPair(id, dehydrated);
     }
@@ -1158,7 +1158,7 @@ class DoubleRatchet {
         }
         const [messageKey, newChainKey] = await this.symmetricRatchet(this.state.sendChainKey);
         this.state.sendChainKey = newChainKey;
-        const iv = randomBytes(AES_GCM_IV_BYTES);
+        const iv = randomBytes(AES_GCM_IV_BYTES$1);
         const encrypted = await encryptAesGcm(messageKey, iv, utf8Encode(plaintext));
         const cipherTextWithTag = toHex(encrypted);
         appLogger.debug(`Encrypt: plaintextLength=${plaintext.length}, ciphertextLength=${encrypted.byteLength}`);
@@ -1878,8 +1878,8 @@ class ChunkCipher {
      */
     generateKeyMaterial() {
         return {
-            key: toBase64$1(randomBytes(AES_GCM_KEY_BYTES)),
-            iv: toBase64$1(randomBytes(AES_GCM_IV_BYTES)),
+            key: toBase64$2(randomBytes(AES_GCM_KEY_BYTES)),
+            iv: toBase64$2(randomBytes(AES_GCM_IV_BYTES$1)),
         };
     }
     /**
@@ -1888,7 +1888,7 @@ class ChunkCipher {
      * GCM behavior).
      */
     async encryptChunk(plaintext, material) {
-        return encryptAesGcm(fromBase64$1(material.key), fromBase64$1(material.iv), plaintext);
+        return encryptAesGcm(fromBase64$2(material.key), fromBase64$2(material.iv), plaintext);
     }
     /**
      * Inverse of {@link encryptChunk}. Throws if the auth tag fails — that
@@ -1897,7 +1897,7 @@ class ChunkCipher {
      */
     async decryptChunk(ciphertext, material) {
         try {
-            return await decryptAesGcm(fromBase64$1(material.key), fromBase64$1(material.iv), ciphertext);
+            return await decryptAesGcm(fromBase64$2(material.key), fromBase64$2(material.iv), ciphertext);
         }
         catch {
             // WebCrypto throws a vague OperationError on GCM tag mismatch.
@@ -1961,7 +1961,7 @@ async function wrapWithPassphrase(passphrase, plaintext) {
         throw new Error("wrapWithPassphrase: passphrase must be a non-empty string");
     }
     const salt = randomBytes(SALT_BYTES);
-    const iv = randomBytes(AES_GCM_IV_BYTES);
+    const iv = randomBytes(AES_GCM_IV_BYTES$1);
     const key = await deriveAesKeyFromPassphrase(passphrase, salt, PBKDF2_DEFAULT_ITERATIONS);
     const ciphertext = await encryptAesGcm(key, iv, plaintext);
     return {
@@ -2449,8 +2449,10 @@ class AuthClient {
     /** Passkeys are per-origin: naming the caller's host returns THAT origin's
      *  passkey instead of whichever was enrolled first (which WebAuthn would
      *  refuse). Ignored for other factor types. */
-    rpId) {
-        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault`, this.json("POST", { username, factorType, verifyToken, rpId }));
+    rpId, 
+    /** Device factors are selected by id — a user may have many machines. */
+    factorId) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault`, this.json("POST", { username, factorType, verifyToken, rpId, factorId }));
         return await this.parse("vaultRead", res);
     }
     /**
@@ -2891,20 +2893,20 @@ async function wrapKeyFromBytes(keyMaterial, info) {
 async function wrapSeed(seed, key) {
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, seed);
-    return { iv: toBase64(iv), ct: toBase64(new Uint8Array(ct)) };
+    return { iv: toBase64$1(iv), ct: toBase64$1(new Uint8Array(ct)) };
 }
 /** Decrypt a wrapped seed. Throws (AES-GCM tag failure) on a wrong key. */
 async function unwrapSeed(wrapped, key) {
-    const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(wrapped.iv) }, key, fromBase64(wrapped.ct));
+    const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64$1(wrapped.iv) }, key, fromBase64$1(wrapped.ct));
     return new Uint8Array(pt);
 }
-function toBase64(bytes) {
+function toBase64$1(bytes) {
     let s = "";
     for (let i = 0; i < bytes.length; i++)
         s += String.fromCharCode(bytes[i]);
     return btoa(s);
 }
-function fromBase64(b64) {
+function fromBase64$1(b64) {
     const s = atob(b64);
     const out = new Uint8Array(s.length);
     for (let i = 0; i < s.length; i++)
@@ -2962,20 +2964,20 @@ async function sealSeed(seed) {
     const key = await crypto.subtle.importKey("raw", ktRaw, { name: "AES-GCM" }, false, ["encrypt"]);
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, key, seed));
-    const envelope = { v: 1, iv: toBase64(iv), ct: toBase64(ct) };
+    const envelope = { v: 1, iv: toBase64$1(iv), ct: toBase64$1(ct) };
     return {
-        sealedKeys: toBase64(TE$1.encode(JSON.stringify(envelope))),
+        sealedKeys: toBase64$1(TE$1.encode(JSON.stringify(envelope))),
         fragmentKey: base64UrlEncode(ktRaw),
     };
 }
 /** Recover the master seed from the sealed envelope + the fragment key. */
 async function unsealSeed(sealedKeys, fragmentKey) {
-    const envelope = JSON.parse(TD$1.decode(fromBase64(sealedKeys)));
+    const envelope = JSON.parse(TD$1.decode(fromBase64$1(sealedKeys)));
     if (envelope.v !== 1)
         throw new Error(`Unsupported handoff envelope version ${envelope.v}`);
     const ktRaw = base64UrlDecode(fragmentKey);
     const key = await crypto.subtle.importKey("raw", ktRaw, { name: "AES-GCM" }, false, ["decrypt"]);
-    const seed = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(envelope.iv) }, key, fromBase64(envelope.ct));
+    const seed = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64$1(envelope.iv) }, key, fromBase64$1(envelope.ct));
     return new Uint8Array(seed);
 }
 // ---- v2: ECDH device pairing ----------------------------------------------
@@ -3026,7 +3028,7 @@ const PAIRING_CODE_ITERATIONS = 200_000;
 async function generateDevicePairingKeypair() {
     const pair = (await crypto.subtle.generateKey(PAIRING_CURVE, false, ["deriveBits"]));
     const raw = new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey));
-    return { publicKeyB64: toBase64(raw), privateKey: pair.privateKey };
+    return { publicKeyB64: toBase64$1(raw), privateKey: pair.privateKey };
 }
 /**
  * (Hosted-page side) Seal the master seed *to a device's* pairing public key.
@@ -3047,8 +3049,8 @@ async function sealSeedToDevice(seed, devicePublicKeyB64) {
     const key = await deriveDeviceSealKey(ephemeral.privateKey, devicePub, epkRaw, devicePubRaw, ["encrypt"]);
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, key, seed));
-    const envelope = { v: 2, epk: toBase64(epkRaw), iv: toBase64(iv), ct: toBase64(ct) };
-    return toBase64(TE$1.encode(JSON.stringify(envelope)));
+    const envelope = { v: 2, epk: toBase64$1(epkRaw), iv: toBase64$1(iv), ct: toBase64$1(ct) };
+    return toBase64$1(TE$1.encode(JSON.stringify(envelope)));
 }
 /**
  * (Device side) Recover the master seed from a v2 envelope using the ephemeral
@@ -3206,7 +3208,7 @@ function importPairingPublicKey(raw) {
  */
 function fromBase64Loose(s) {
     const norm = s.replace(/-/g, "+").replace(/_/g, "/");
-    return fromBase64(norm.padEnd(Math.ceil(norm.length / 4) * 4, "="));
+    return fromBase64$1(norm.padEnd(Math.ceil(norm.length / 4) * 4, "="));
 }
 /** Generate a PKCE verifier + S256 challenge for the authorize→token exchange. */
 async function generatePkce() {
@@ -3219,10 +3221,10 @@ function randomState() {
     return base64UrlEncode(crypto.getRandomValues(new Uint8Array(16)));
 }
 function base64UrlEncode(bytes) {
-    return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return toBase64$1(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function base64UrlDecode(s) {
-    return fromBase64(s.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(s.length / 4) * 4, "="));
+    return fromBase64$1(s.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(s.length / 4) * 4, "="));
 }
 
 /**
@@ -3233,7 +3235,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.10.14-alpha.0";
+const VERSION = "0.12.0-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -3686,8 +3688,8 @@ function gatedBlind(input) {
  * unblind each, concatenate, HKDF with the gated-factor domain separation.
  */
 async function gatedWrapKey(input, blind, evaluatedB64, evaluated2B64) {
-    const out1 = oprfFinalize(input, blind, fromBase64(evaluatedB64));
-    const out2 = oprfFinalize(input, blind, fromBase64(evaluated2B64));
+    const out1 = oprfFinalize(input, blind, fromBase64$1(evaluatedB64));
+    const out2 = oprfFinalize(input, blind, fromBase64$1(evaluated2B64));
     const ikm = new Uint8Array(out1.length + out2.length);
     ikm.set(out1);
     ikm.set(out2, out1.length);
@@ -4021,13 +4023,13 @@ async function persistDeviceIdentity(v) {
     const plain = TE.encode(JSON.stringify({
         username: v.username,
         commitment: v.commitment,
-        seed: toBase64(v.seed),
+        seed: toBase64$1(v.seed),
         pairedAt: v.pairedAt,
     }));
     const bridge = keystoreBridge();
     let envelope;
     if (bridge) {
-        envelope = { v: 1, ks: 1, ct: await bridge.wrap(toBase64(plain)) };
+        envelope = { v: 1, ks: 1, ct: await bridge.wrap(toBase64$1(plain)) };
     }
     else {
         const key = await wrapKey(true);
@@ -4035,7 +4037,7 @@ async function persistDeviceIdentity(v) {
             throw new DeviceStoreUnavailableError("no IndexedDB for the wrapping key");
         const iv = crypto.getRandomValues(new Uint8Array(12));
         const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, key, plain));
-        envelope = { v: 1, iv: toBase64(iv), ct: toBase64(ct) };
+        envelope = { v: 1, iv: toBase64$1(iv), ct: toBase64$1(ct) };
     }
     blobs.set(DEVICE_IDENTITY_STORAGE_KEY, JSON.stringify(envelope));
 }
@@ -4059,18 +4061,18 @@ async function loadDeviceIdentity() {
         if (envelope.ks === 1) {
             if (!bridge)
                 return null; // sealed by the native shell; nothing else can open it
-            plain = fromBase64(await bridge.unwrap(envelope.ct));
+            plain = fromBase64$1(await bridge.unwrap(envelope.ct));
         }
         else {
             const key = await wrapKey(false);
             if (!key || !envelope.iv)
                 return null;
-            plain = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(envelope.iv) }, key, fromBase64(envelope.ct)));
+            plain = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64$1(envelope.iv) }, key, fromBase64$1(envelope.ct)));
         }
         const parsed = JSON.parse(TD.decode(plain));
         if (!parsed?.username || !parsed?.commitment || !parsed?.seed)
             return null;
-        const seed = fromBase64(parsed.seed);
+        const seed = fromBase64$1(parsed.seed);
         if (seed.length !== 32)
             return null;
         return {
@@ -4104,7 +4106,7 @@ async function clearDeviceIdentity() {
 async function fingerprintOf(publicKey) {
     const raw = new Uint8Array(await crypto.subtle.exportKey("raw", publicKey));
     const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", raw));
-    return toBase64(digest).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return toBase64$1(digest).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 async function loadOrCreateIdentityKey() {
     const vault = keyVault();
@@ -5170,6 +5172,8 @@ class VaultUnavailableError extends Error {
  * ZK identity auth. One instance per {@link Client}; reads/writes the shared
  * {@link SessionState}.
  */
+/** HKDF label separating a device wrap key from every other use of the seed. */
+const DEVICE_WRAP_INFO = "muhkoo-device-key-v1";
 class ZkAuth {
     deps;
     constructor(deps) {
@@ -5461,7 +5465,7 @@ class ZkAuth {
                 const { verifyToken, email: verified } = await this.deps.auth.emailOtpVerify({ token, code });
                 const input = await emailFactorInput(username, verified);
                 const { blind, blinded } = gatedBlind(input);
-                const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "email", "enroll", verifyToken);
+                const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64$1(blinded), "email", "enroll", verifyToken);
                 const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
                 const wrapped = await wrapSeed(seed, key);
                 await this.deps.auth.vaultPutFactor(token, { id: "email", type: "email", wrap: wrapped.ct, iv: wrapped.iv, params: { email: verified }, createdAt: Date.now() }, verifyToken);
@@ -5489,7 +5493,7 @@ class ZkAuth {
                 }
                 const input = await emailFactorInput(username, email);
                 const { blind, blinded } = gatedBlind(input);
-                const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "email", "recover", verifyToken);
+                const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64$1(blinded), "email", "recover", verifyToken);
                 const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
                 const seed = await unwrapSeed({ iv: factor.iv, ct: factor.wrap }, key);
                 const identity = await deriveIdentityFromSeed(seed);
@@ -5517,7 +5521,7 @@ class ZkAuth {
         const { verifyToken, sub, emailHint } = await this.deps.auth.googleVerify({ idToken, token });
         const input = await googleFactorInput(username, sub);
         const { blind, blinded } = gatedBlind(input);
-        const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "google", "enroll", verifyToken);
+        const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64$1(blinded), "google", "enroll", verifyToken);
         const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
         const wrapped = await wrapSeed(seed, key);
         await this.deps.auth.vaultPutFactor(token, { id: "google", type: "google", wrap: wrapped.ct, iv: wrapped.iv, params: { sub, emailHint: emailHint ?? undefined }, createdAt: Date.now() }, verifyToken);
@@ -5535,7 +5539,7 @@ class ZkAuth {
             throw new Error("No Google account is linked to this username.");
         const input = await googleFactorInput(username, sub);
         const { blind, blinded } = gatedBlind(input);
-        const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "google", "recover", verifyToken);
+        const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64$1(blinded), "google", "recover", verifyToken);
         const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
         const seed = await unwrapSeed({ iv: factor.iv, ct: factor.wrap }, key);
         const identity = await deriveIdentityFromSeed(seed);
@@ -5616,11 +5620,11 @@ class ZkAuth {
         const key = await wrapKeyFromBytes(prfOutput, "muhkoo-passkey-wrap");
         const wrapped = await wrapSeed(seed, key);
         await this.deps.auth.vaultPutFactor(token, {
-            id: `passkey:${toBase64(credentialId).slice(0, 16)}`,
+            id: `passkey:${toBase64$1(credentialId).slice(0, 16)}`,
             type: "passkey",
             wrap: wrapped.ct,
             iv: wrapped.iv,
-            params: { credentialId: toBase64(credentialId), prfSalt: toBase64(prfSalt), rpId },
+            params: { credentialId: toBase64$1(credentialId), prfSalt: toBase64$1(prfSalt), rpId },
             label: opts?.label ?? "Passkey",
             createdAt: Date.now(),
         });
@@ -5645,7 +5649,7 @@ class ZkAuth {
         // to enroll a passkey for this origin.
         if (!rpIdUsableForOrigin(rpId, host))
             throw new PasskeyOriginError();
-        const prfOutput = await evaluatePasskeyPrf(rpId, fromBase64(params.credentialId), fromBase64(params.prfSalt));
+        const prfOutput = await evaluatePasskeyPrf(rpId, fromBase64$1(params.credentialId), fromBase64$1(params.prfSalt));
         const key = await wrapKeyFromBytes(prfOutput, "muhkoo-passkey-wrap");
         const seed = await unwrapSeed({ iv: factor.iv, ct: factor.wrap }, key);
         const identity = await deriveIdentityFromSeed(seed);
@@ -5724,7 +5728,107 @@ class ZkAuth {
      */
     get seedBase64() {
         const seed = this.deps.session.seed;
-        return seed ? toBase64(seed) : null;
+        return seed ? toBase64$1(seed) : null;
+    }
+    /**
+     * Pair this machine, so it can unlock the account later without a password.
+     *
+     * Generates a random 32-byte key, wraps the master seed under it, and stores
+     * only the CIPHERTEXT in the vault as a `device` factor. The key is returned
+     * for the caller to persist locally and is never sent anywhere.
+     *
+     * The split is the point: the seed itself never lands on disk, and the
+     * server holds a blob it cannot open. Revoking the factor
+     * ({@link revokeDevice}) makes the local key inert immediately — which a
+     * stored master seed can never be, because nothing can reach out and
+     * un-store it.
+     *
+     * Returns the factor id and the key, both base64. Losing the key just means
+     * re-pairing; leaking it is equivalent to leaking the seed for as long as
+     * the factor exists, so store it with the tightest permissions available.
+     */
+    async enrollDevice(label) {
+        const seed = this.deps.session.seed;
+        const token = this.deps.session.token;
+        if (!seed || !token)
+            throw new Error("Sign in first to pair this device.");
+        const keyBytes = randomSeed(); // 32 bytes of CSPRNG
+        const key = await wrapKeyFromBytes(keyBytes, DEVICE_WRAP_INFO);
+        const wrapped = await wrapSeed(seed, key);
+        // 128 bits of id, so reading a factor by id is not an enumeration surface.
+        const factorId = `device:${toBase64$1(randomSeed()).replace(/[+/=]/g, "").slice(0, 22)}`;
+        await this.deps.auth.vaultPutFactor(token, {
+            id: factorId,
+            type: "device",
+            wrap: wrapped.ct,
+            iv: wrapped.iv,
+            label,
+            createdAt: Date.now(),
+        });
+        return { factorId, deviceKey: toBase64$1(keyBytes) };
+    }
+    /**
+     * Unlock using a key stored by {@link enrollDevice}.
+     *
+     * Fetches the wrapped seed and opens it locally. Establishes the encryption
+     * identity only — pair it with a session for calls that need one.
+     *
+     * Throws distinguishably: a REVOKED factor is gone from the vault and says
+     * so, where a wrong key fails to decrypt. A machine that has had its access
+     * withdrawn should be able to tell you that, not just "decryption failed".
+     */
+    async unlockWithDevice(username, factorId, deviceKey) {
+        const { factor } = await this.deps.auth.vaultRead(username, "device", undefined, undefined, factorId);
+        if (!factor) {
+            throw new Error("This device is no longer paired — its access was revoked. Sign in again to re-pair.");
+        }
+        if (!factor.wrap || !factor.iv)
+            throw new Error("The stored device factor is incomplete; re-pair this device.");
+        const key = await wrapKeyFromBytes(fromBase64$1(deviceKey), DEVICE_WRAP_INFO);
+        const seed = await unwrapSeed({ iv: factor.iv, ct: factor.wrap }, key);
+        this.deps.session.setSeed(seed);
+    }
+    /** Paired machines, newest first. Metadata only — never the ciphertext. */
+    async listDevices() {
+        const token = this.deps.session.token;
+        if (!token)
+            throw new Error("Sign in first to list paired devices.");
+        const { factors } = await this.deps.auth.vaultFactors(token);
+        return factors
+            .filter((f) => f.type === "device")
+            .map((f) => ({ id: f.id, label: f.label, createdAt: f.createdAt }))
+            .sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0));
+    }
+    /** Withdraw a machine's access. Its stored key stops working immediately. */
+    async revokeDevice(factorId) {
+        const token = this.deps.session.token;
+        if (!token)
+            throw new Error("Sign in first to revoke a device.");
+        const { deleted } = await this.deps.auth.vaultDeleteFactor(token, factorId);
+        return deleted;
+    }
+    /**
+     * Restore an unlocked identity from a seed you already hold.
+     *
+     * The inverse of {@link seedBase64}, for hosts that persist the seed
+     * themselves rather than re-deriving it from a password: a CLI holding it in
+     * a 0600 file, a server-side tool, a test. Without this the seed is a
+     * one-way export and anything outside a browser has to run a full ZK login —
+     * circuits download and proof — on every single invocation.
+     *
+     * Establishes the ENCRYPTION identity only. It does not authenticate: pair
+     * it with a session token (`sessionStore`) for calls that need one.
+     *
+     * Treat a persisted seed as the master credential it is. It is not scoped
+     * and cannot be revoked server-side the way a session token can — rotating
+     * it means moving the identity.
+     */
+    unlockWithSeed(seedBase64) {
+        const seed = fromBase64$1(seedBase64);
+        if (seed.length !== 32) {
+            throw new Error(`auth.zk.unlockWithSeed: expected a 32-byte seed, got ${seed.length}`);
+        }
+        this.deps.session.setSeed(seed);
     }
     // -------------------------------------------------------------------------
     /** Poseidon commitment for an identity — the value the server stores. */
@@ -5743,8 +5847,8 @@ class ZkAuth {
     async passwordWrapKey(username, password) {
         const pre = passwordPreHash(username, password);
         const { blind, blinded } = oprfBlind(pre);
-        const { evaluated } = await this.deps.auth.oprfEvaluate(username, toBase64(blinded));
-        return wrapKeyFromOprf(oprfFinalize(pre, blind, fromBase64(evaluated)));
+        const { evaluated } = await this.deps.auth.oprfEvaluate(username, toBase64$1(blinded));
+        return wrapKeyFromOprf(oprfFinalize(pre, blind, fromBase64$1(evaluated)));
     }
     /**
      * Try to recover the master seed from the password factor.
@@ -5850,16 +5954,16 @@ class StorageCipher {
     /** Seal a JSON-serializable value into an {@link EncryptedEnvelope}. */
     async encrypt(value) {
         const key = await this.keyPromise;
-        const iv = randomBytes(AES_GCM_IV_BYTES);
+        const iv = randomBytes(AES_GCM_IV_BYTES$1);
         const plaintext = utf8Encode(JSON.stringify(value));
         const ciphertext = await encryptAesGcm(key, iv, plaintext);
-        return { _enc: "a256gcm", iv: toBase64$1(iv), ct: toBase64$1(ciphertext) };
+        return { _enc: "a256gcm", iv: toBase64$2(iv), ct: toBase64$2(ciphertext) };
     }
     /** Open an {@link EncryptedEnvelope} back into the original value. */
     async decrypt(envelope) {
         const key = await this.keyPromise;
-        const iv = fromBase64$1(envelope.iv);
-        const ciphertext = fromBase64$1(envelope.ct);
+        const iv = fromBase64$2(envelope.iv);
+        const ciphertext = fromBase64$2(envelope.ct);
         const plaintext = await decryptAesGcm(key, iv, ciphertext);
         return JSON.parse(utf8Decode(plaintext));
     }
@@ -6190,6 +6294,8 @@ class WSTransport extends EventCore {
  */
 class KvNamespace {
     deps;
+    /** One personal-space socket, shared by every subscriber. */
+    feed = null;
     cipher = null;
     cipherIdentity = null;
     constructor(deps) {
@@ -6314,22 +6420,64 @@ class KvNamespace {
         if (!token)
             throw new Error("client.kv.on: not signed in.");
         const commitment = this.commitment();
-        const url = `${this.deps.wsBaseUrl}/api/personal/${encodeURIComponent(commitment)}/websocket?session=${encodeURIComponent(token)}`;
+        `${this.deps.wsBaseUrl}/api/personal/${encodeURIComponent(commitment)}/websocket?session=${encodeURIComponent(token)}`;
         // Ride a WSTransport rather than a bare socket: it keeps the (otherwise
         // idle) personal-space feed warm with heartbeat pings, auto-reconnects
         // if it drops, and namespaces its events by `id` so this feed never
         // crosses wires with chat/space transports on the shared EventCore bus.
-        const transport = new WSTransport({ url, id: `personal:${commitment}` });
-        const onMessage = (e) => {
-            void this.dispatchChange(e.detail, handler);
-        };
-        transport.on(EventCoreEvents.MESSAGE, onMessage);
-        // Fire-and-forget: the realtime feed is best-effort, and the transport
-        // queues nothing it needs before CONNECTED (server→client only).
-        void transport.connect();
+        return this.onRaw((raw) => {
+            void this.dispatchChange(raw, handler);
+        });
+    }
+    /**
+     * Subscribe to the personal space's raw change feed.
+     *
+     * Every key this user owns crosses this socket, not only `client.kv`
+     * collections — the VFS keeps its directory records here too. Consumers get
+     * the frame untouched: no decryption, no offline-cache merge, because the
+     * value's meaning depends on which subsystem wrote it.
+     *
+     * The transport is SHARED and reference-counted. `WSTransport` namespaces
+     * its events by `id`, so two transports with the same id would cross wires
+     * on the shared event bus — and a second socket to the same Durable Object
+     * would be pure waste besides.
+     */
+    onRaw(handler) {
+        if (typeof globalThis.WebSocket !== "function") {
+            throw new Error("client.kv.onRaw: no `WebSocket` global available in this runtime.");
+        }
+        const token = this.deps.session.token;
+        if (!token)
+            throw new Error("client.kv.onRaw: not signed in.");
+        const commitment = this.commitment();
+        if (!this.feed) {
+            const url = `${this.deps.wsBaseUrl}/api/personal/${encodeURIComponent(commitment)}/websocket?session=${encodeURIComponent(token)}`;
+            // Ride a WSTransport rather than a bare socket: it keeps the
+            // (otherwise idle) feed warm with heartbeat pings, auto-reconnects
+            // if it drops, and namespaces its events by `id`.
+            const transport = new WSTransport({ url, id: `personal:${commitment}` });
+            const handlers = new Set();
+            const onMessage = (e) => {
+                for (const fn of handlers)
+                    fn(e.detail);
+            };
+            transport.on(EventCoreEvents.MESSAGE, onMessage);
+            // Fire-and-forget: the feed is best-effort, and the transport queues
+            // nothing it needs before CONNECTED (server→client only).
+            void transport.connect();
+            this.feed = { transport, handlers, onMessage };
+        }
+        const feed = this.feed;
+        feed.handlers.add(handler);
         return () => {
-            transport.off(EventCoreEvents.MESSAGE, onMessage);
-            transport.disconnect();
+            feed.handlers.delete(handler);
+            // Last subscriber out closes the socket, so an app that unsubscribes
+            // everything is not left holding an open connection.
+            if (feed.handlers.size === 0 && this.feed === feed) {
+                feed.transport.off(EventCoreEvents.MESSAGE, feed.onMessage);
+                feed.transport.disconnect();
+                this.feed = null;
+            }
         };
     }
     // -------------------------------------------------------------------------
@@ -8302,12 +8450,12 @@ function canonicalMessage(fields) {
 /** Sign the canonical bytes with the sender's ECDSA identity private key. */
 async function signSpaceMessage(canonical, ecdsaPriv) {
     const sig = await getSubtle().sign(ECDSA_SIGN, ecdsaPriv, utf8Encode(canonical));
-    return toBase64$1(new Uint8Array(sig));
+    return toBase64$2(new Uint8Array(sig));
 }
 /** Verify a signature over the canonical bytes against the sender's ECDSA key. */
 async function verifySpaceMessage(canonical, sigB64, ecdsaPub) {
     try {
-        return await getSubtle().verify(ECDSA_SIGN, ecdsaPub, fromBase64$1(sigB64), utf8Encode(canonical));
+        return await getSubtle().verify(ECDSA_SIGN, ecdsaPub, fromBase64$2(sigB64), utf8Encode(canonical));
     }
     catch {
         return false;
@@ -8338,13 +8486,13 @@ async function wrapSpaceKey(kSpace, epoch, recipientEcdhPub) {
     const eph = await getSubtle().generateKey(ECDH_PARAMS, true, ["deriveBits"]);
     const shared = new Uint8Array(await getSubtle().deriveBits({ name: "ECDH", public: recipientEcdhPub }, eph.privateKey, P384_BITS));
     const wrapKey = await deriveBitsHkdf(shared, WRAP_INFO, AES_GCM_KEY_BYTES, utf8Encode(`epoch:${epoch}`));
-    const iv = randomBytes(AES_GCM_IV_BYTES);
+    const iv = randomBytes(AES_GCM_IV_BYTES$1);
     const ciphertext = await encryptAesGcm(wrapKey, iv, kSpace);
     return {
         epoch,
         ephemeralPub: await exportEcdhPublicKey(eph.publicKey),
-        iv: toBase64$1(iv),
-        ciphertext: toBase64$1(ciphertext),
+        iv: toBase64$2(iv),
+        ciphertext: toBase64$2(ciphertext),
         alg: WRAP_ALG,
     };
 }
@@ -8356,23 +8504,23 @@ async function unwrapSpaceKey(wrapped, ownEcdhPriv) {
     const ephPub = await importEcdhPublicKey(wrapped.ephemeralPub);
     const shared = new Uint8Array(await getSubtle().deriveBits({ name: "ECDH", public: ephPub }, ownEcdhPriv, P384_BITS));
     const wrapKey = await deriveBitsHkdf(shared, WRAP_INFO, AES_GCM_KEY_BYTES, utf8Encode(`epoch:${wrapped.epoch}`));
-    return decryptAesGcm(wrapKey, fromBase64$1(wrapped.iv), fromBase64$1(wrapped.ciphertext));
+    return decryptAesGcm(wrapKey, fromBase64$2(wrapped.iv), fromBase64$2(wrapped.ciphertext));
 }
 // ---------------------------------------------------------------------------
 // Message sealing
 // ---------------------------------------------------------------------------
 /** Seal an already-serialized message string under the group key. */
 async function sealSerialized(kSpace, serialized) {
-    const iv = randomBytes(AES_GCM_IV_BYTES);
+    const iv = randomBytes(AES_GCM_IV_BYTES$1);
     const ciphertext = await encryptAesGcm(kSpace, iv, utf8Encode(serialized));
-    return { iv: toBase64$1(iv), ciphertext: toBase64$1(ciphertext) };
+    return { iv: toBase64$2(iv), ciphertext: toBase64$2(ciphertext) };
 }
 /**
  * Open a sealed payload back into its serialized message string. Throws (GCM
  * tag failure) on the wrong group key or a tampered ciphertext.
  */
 async function openSerialized(kSpace, iv, ciphertext) {
-    const plaintext = await decryptAesGcm(kSpace, fromBase64$1(iv), fromBase64$1(ciphertext));
+    const plaintext = await decryptAesGcm(kSpace, fromBase64$2(iv), fromBase64$2(ciphertext));
     return utf8Decode(plaintext);
 }
 
@@ -10876,6 +11024,16 @@ class SpaceNamespace {
      * Create a new space: generate its keypair (public key = id), register
      * metadata, mint the initial group key, and connect. Returns the open Space.
      */
+    /**
+     * Create a space.
+     *
+     * `messaging: false` registers the space and stops there — no group-key
+     * bootstrap and no WebSocket. Use it for a space that only ever holds
+     * FILES: each chunk carries its own key inside its manifest, so the group
+     * keyring buys nothing, and opening a socket makes the write path depend on
+     * a live connection. That dependency is wrong for a CLI, and it is what made
+     * the first VFS write hang forever instead of failing.
+     */
     async createSpace(opts = {}) {
         const historyPolicy = opts.historyPolicy ?? "static";
         const identity = await generateSpaceIdentity();
@@ -10884,7 +11042,8 @@ class SpaceNamespace {
         // its first member — so the metadata POST must carry the user session.
         await this.deps.http.post(`/api/spaces/${encodeURIComponent(identity.id)}/metadata`, { spacePubKey: identity.id, historyPolicy, visibility: opts.private ? "private" : "public" });
         const space = await this.build(identity.id, historyPolicy);
-        await space.create();
+        if (opts.messaging !== false)
+            await space.create();
         return space;
     }
     /** Join an existing space by id (its public key). Resolves once a key arrives. */
@@ -11081,7 +11240,7 @@ class SpaceNamespace {
                 console.info(`[muhkoo:vault] ensureIdentity: unlocked=${!!seed} vault=${!!this.deps.chatKeys}`);
             if (this.deps.chatKeys && seed) {
                 try {
-                    await this.deps.chatKeys.ensure(memberId, toBase64$1(seed));
+                    await this.deps.chatKeys.ensure(memberId, toBase64$2(seed));
                 }
                 catch (e) {
                     if (staging)
@@ -11386,6 +11545,1807 @@ class AccessTokensNamespace {
     }
 }
 
+/**
+ * Wire types for the VFS metadata layer.
+ *
+ * ## What is stored where
+ *
+ * The filesystem is a graph of **directory records**, one per directory, each
+ * held under a personal-space KV key and encrypted client-side. A record lists
+ * only its immediate children — so listing a directory is one fetch, and you
+ * only ever pay for the subtrees you actually open.
+ *
+ * File CONTENT is not here. Bytes are written with `client.storage.writeFile`
+ * exactly as any other file — into a real Space, with a real gated manifest —
+ * and the entry keeps the returned `FileManifest` as its handle.
+ * `client.storage.readByManifest(manifest)` then reconstructs the bytes from
+ * the content-addressed shard store with no space membership or directory
+ * lookup needed, which is what makes a file shareable by handing over the
+ * handle alone.
+ *
+ * This supersedes the flat personal mirror `writeFile` already maintains
+ * (`{spaceId, manifest}` keyed by manifest id): the same metadata, in the same
+ * personal space, arranged as a tree you can actually navigate.
+ *
+ * ## Why directories have stable random ids, not content hashes
+ *
+ * A git-style tree keys each directory by the hash of its contents, so writing
+ * one file rewrites every ancestor up to the root. Here a directory's id is
+ * random and permanent, so a file write touches exactly ONE record — its
+ * parent — and renaming or moving a directory edits only the parent entry
+ * while the whole subtree underneath stays byte-identical and untouched.
+ *
+ * ## Why a directory's key lives in its parent
+ *
+ * Only the root key is derived from the master seed. Every other directory has
+ * a random key stored in its parent's entry, which chains capabilities
+ * downward: handing someone `{id, key}` for `/apps/my-app` lets them walk that
+ * subtree and nothing else, because no key can be derived upward. That is the
+ * seam group-sharing hangs off later without re-encrypting the filesystem.
+ */
+/** Personal-space KV key holding a directory record. */
+const dirKey = (id) => `vfs/d/${id}`;
+/** Personal-space KV key holding one file's prior versions. */
+const historyKey = (id) => `vfs/h/${id}`;
+/** The root directory's id is fixed — it is the one node reached without a parent. */
+const ROOT_ID = "root";
+/** HKDF label for the seed-derived root key. Sits alongside `muhkoo-storage-v1`. */
+const VFS_ROOT_INFO = "muhkoo-vfs-v1";
+/** Raised when the master seed is not held, so the root key cannot be derived. */
+class VfsLockedError extends Error {
+    constructor() {
+        // Named rather than generic because the caller's remedy is specific and
+        // not guessable from a failed decrypt: re-authenticate to recover the
+        // seed. A page reload alone loses it — it is memory-only, never stored.
+        super("VFS is locked: the master seed is not in memory. Sign in again to unlock.");
+        this.name = "VfsLockedError";
+    }
+}
+/** Raised for a path that does not exist. */
+class VfsNotFoundError extends Error {
+    constructor(path) {
+        super(`VFS: ${path} does not exist`);
+        this.name = "VfsNotFoundError";
+    }
+}
+/** Raised when an operation would clobber or misuse an existing entry. */
+class VfsConflictError extends Error {
+    constructor(message) {
+        super(`VFS: ${message}`);
+        this.name = "VfsConflictError";
+    }
+}
+
+/**
+ * Sealing for VFS metadata records.
+ *
+ * Every directory and history record is AES-256-GCM encrypted before it leaves
+ * the process, so the server holds ciphertext and never learns a filename, a
+ * directory shape, or a file size. The manifests inside carry their own chunk
+ * keys, which is why the metadata must be sealed too: a readable directory
+ * record would hand over the keys to its files.
+ */
+const AES_GCM_IV_BYTES = 12;
+const AES_KEY_BYTES = 32;
+function toBase64(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s);
+}
+function fromBase64(b64) {
+    const s = atob(b64);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+/** A fresh random key for a newly created directory. */
+function newDirKey() {
+    return randomBytes(AES_KEY_BYTES);
+}
+/**
+ * A fresh random id.
+ *
+ * Ids are opaque and never derived from names or contents — a predictable id
+ * would leak the directory structure through the KV key, which is the one part
+ * of a record the server does see.
+ */
+function newId() {
+    return toBase64(randomBytes(16)).replace(/[+/=]/g, "").slice(0, 22);
+}
+/** The root key, derived from the master seed. The only key not stored in a parent. */
+/**
+ * The key a project's repository objects are sealed with.
+ *
+ * Per project, not one key for everything: commits, trees and refs describe a
+ * single project's history, and deriving per slug keeps that blast radius small
+ * if a key is ever shared to collaborate on one project.
+ */
+async function deriveRepoKey(seed, slug) {
+    return deriveBitsHkdf(seed, `${VFS_ROOT_INFO}:vcs:${slug}`, AES_KEY_BYTES);
+}
+async function deriveRootKey(seed) {
+    return deriveBitsHkdf(seed, VFS_ROOT_INFO, AES_KEY_BYTES);
+}
+async function seal(key, value) {
+    const iv = randomBytes(AES_GCM_IV_BYTES);
+    const plaintext = new TextEncoder().encode(JSON.stringify(value));
+    const ct = await encryptAesGcm(key, iv, plaintext);
+    return { v: 1, iv: toBase64(iv), ct: toBase64(ct) };
+}
+/**
+ * Open a sealed record. Returns null for anything that is not a well-formed
+ * envelope, so a missing or corrupt record reads as "absent" rather than
+ * throwing — the caller can then rebuild it. A WRONG KEY still throws, because
+ * silently treating an undecryptable directory as empty would present the user
+ * with an empty filesystem and then let a write overwrite the real one.
+ */
+async function unseal(key, record) {
+    if (!record || typeof record !== "object")
+        return null;
+    const r = record;
+    if (typeof r.iv !== "string" || typeof r.ct !== "string")
+        return null;
+    const plaintext = await decryptAesGcm(key, fromBase64(r.iv), fromBase64(r.ct));
+    return JSON.parse(new TextDecoder().decode(plaintext));
+}
+
+/**
+ * Absolute POSIX paths for the VFS.
+ *
+ * A path is a lookup route, not a stored value: nothing in the metadata records
+ * a full path, only a name inside its parent directory. That is what makes
+ * renaming or moving a directory a single-record edit instead of a rewrite of
+ * every descendant.
+ */
+/** Absolute, single leading slash, no `.` / `..`, no trailing slash. Root is `/`. */
+function normalizePath(input) {
+    const out = [];
+    for (const part of input.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..")
+            out.pop();
+        else
+            out.push(part);
+    }
+    return "/" + out.join("/");
+}
+/** Path split into its segments. `/` yields `[]`. */
+function segments(path) {
+    return normalizePath(path).split("/").filter(Boolean);
+}
+/**
+ * Resolve `path` against a working directory, POSIX-style.
+ *
+ * An absolute path ignores the cwd; a relative one hangs off it; `..` climbs
+ * and stops at the root rather than escaping it. This is the single place
+ * relativity is interpreted, so every VFS method behaves the same way — a
+ * filesystem where `cat a.txt` and `list("a")` disagreed about what "here"
+ * means would be worse than having no cwd at all.
+ */
+function resolveFrom(cwd, path) {
+    if (path.startsWith("/"))
+        return normalizePath(path);
+    return normalizePath(`${cwd}/${path}`);
+}
+function dirname(path) {
+    const p = normalizePath(path);
+    const i = p.lastIndexOf("/");
+    return i <= 0 ? "/" : p.slice(0, i);
+}
+function basename(path) {
+    const p = normalizePath(path);
+    return p.slice(p.lastIndexOf("/") + 1);
+}
+function join(...parts) {
+    return normalizePath(parts.join("/"));
+}
+/**
+ * Is `path` inside `dir` (at any depth)? A directory is never "under" itself,
+ * which is what makes it usable as the guard against moving a directory into
+ * its own subtree.
+ */
+function isUnder(path, dir) {
+    const p = normalizePath(path);
+    const d = normalizePath(dir);
+    if (p === d)
+        return false;
+    return d === "/" ? true : p.startsWith(d + "/");
+}
+/**
+ * Reject names that would make a path ambiguous or unrepresentable.
+ *
+ * `/` would forge a nesting level, and `.` / `..` would resolve to a different
+ * directory on the next lookup — a file literally named `..` could never be
+ * addressed again.
+ */
+function assertValidName(name) {
+    if (!name)
+        throw new Error("VFS: name cannot be empty");
+    if (name === "." || name === "..")
+        throw new Error(`VFS: "${name}" is not a usable name`);
+    if (name.includes("/"))
+        throw new Error(`VFS: name cannot contain "/" (got ${JSON.stringify(name)})`);
+}
+/**
+ * MIME type for a filename.
+ *
+ * Stored with the content rather than guessed at read time, because whatever
+ * eventually serves these bytes — a preview, a static host — sends this as the
+ * `Content-Type`, and a browser will refuse to run a module or apply a
+ * stylesheet labelled `application/octet-stream`.
+ */
+function contentTypeFor(name) {
+    const ext = name.slice(name.lastIndexOf(".") + 1).toLowerCase();
+    switch (ext) {
+        case "html":
+        case "htm": return "text/html; charset=utf-8";
+        case "css": return "text/css; charset=utf-8";
+        case "js":
+        case "mjs":
+        case "jsx": return "text/javascript; charset=utf-8";
+        case "ts":
+        case "tsx": return "text/typescript; charset=utf-8";
+        case "json": return "application/json; charset=utf-8";
+        case "md": return "text/markdown; charset=utf-8";
+        case "txt": return "text/plain; charset=utf-8";
+        case "svg": return "image/svg+xml";
+        case "png": return "image/png";
+        case "jpg":
+        case "jpeg": return "image/jpeg";
+        case "gif": return "image/gif";
+        case "webp": return "image/webp";
+        case "avif": return "image/avif";
+        case "ico": return "image/x-icon";
+        case "woff2": return "font/woff2";
+        case "woff": return "font/woff";
+        case "wasm": return "application/wasm";
+        case "map": return "application/json";
+        default: return "application/octet-stream";
+    }
+}
+
+/**
+ * Glob matching for VFS paths.
+ *
+ * A deliberately small dialect — `*`, `**`, `?`, and `{a,b}` — because these
+ * cover what a project actually asks for (`**\/*.tsx`, `src/*.css`) and every
+ * addition beyond them is a new way for a pattern to mean something the caller
+ * did not expect.
+ */
+/** `*` stops at a separator; `**` crosses them. That distinction is the whole point. */
+function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                // `**/` should also match zero directories, so `/**/x` finds `/x`.
+                if (pattern[i + 2] === "/") {
+                    out += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    out += ".*";
+                    i += 1;
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else if (c === "{") {
+            const close = pattern.indexOf("}", i);
+            if (close === -1) {
+                out += "\\{";
+            }
+            else {
+                const alts = pattern.slice(i + 1, close).split(",");
+                out += `(?:${alts.map(escapeLiteral).join("|")})`;
+                i = close;
+            }
+        }
+        else {
+            out += escapeLiteral(c);
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+function escapeLiteral(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * `client.vfs` — a real filesystem over Muhkoo primitives.
+ *
+ * Metadata is a graph of encrypted directory records in the user's personal
+ * space; file content is chunked, encrypted and stored in the global
+ * content-addressed shard store, referenced by manifest. See `types.ts` for
+ * why directories carry stable random ids and why each key lives in its parent.
+ *
+ * ## Consistency
+ *
+ * Every mutation is a read-modify-write of exactly ONE directory record, so a
+ * write cannot leave the tree half-updated: either the parent names the new
+ * child or it does not. Two tabs writing different directories never conflict;
+ * two tabs writing the SAME directory resolve last-writer-wins at the personal
+ * space, which carries an HLC per key. Orphaned records (a directory whose
+ * parent entry lost the race) are unreachable rather than corrupting — they
+ * cost storage until a future sweep, which is the trade this shape makes in
+ * exchange for single-record writes.
+ */
+const DEFAULT_HISTORY_LIMIT = 20;
+class VfsNamespace {
+    deps;
+    rootKey = null;
+    /**
+     * Decrypted directory records, by id.
+     *
+     * The file tree re-lists constantly while typing, and every miss is a
+     * network round trip plus a decrypt. Invalidated precisely on write rather
+     * than by TTL — a stale directory listing shows files that are not there.
+     */
+    cache = new Map();
+    historyLimit;
+    constructor(deps) {
+        this.deps = deps;
+        this.historyLimit = deps.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+    }
+    /**
+     * The working directory relative paths resolve against.
+     *
+     * Kept here rather than left to each caller so that a CLI, a script and the
+     * SDK all agree on what "here" means — the alternative is every consumer
+     * re-implementing `cd`, and disagreeing about `..`.
+     */
+    _cwd = "/";
+    /** The current working directory. Always absolute. */
+    get cwd() {
+        return this._cwd;
+    }
+    /**
+     * Change the working directory.
+     *
+     * Verifies the target is a real directory, so a typo fails here — where the
+     * message can name the path — rather than turning every later relative path
+     * into a confusing "does not exist".
+     */
+    async cd(path) {
+        const target = this.resolve(path);
+        if (target !== "/") {
+            const found = await this.find(target);
+            if (!found)
+                throw new VfsNotFoundError(target);
+            if (found.entry.kind !== "dir")
+                throw new VfsConflictError(`${target} is not a directory`);
+        }
+        this._cwd = target;
+        return target;
+    }
+    /** Resolve a path against the working directory. Absolute paths pass through. */
+    resolve(path) {
+        return resolveFrom(this._cwd, path);
+    }
+    /** True when the master seed is held, so the root key can be derived. */
+    get unlocked() {
+        return this.deps.seed() !== null;
+    }
+    /**
+     * Drop every cached record.
+     *
+     * Call after signing in as someone else — the cache is keyed by directory
+     * id with no notion of whose filesystem it came from, and serving one
+     * identity's directories to another would be the worst possible bug here.
+     */
+    clearCache() {
+        this.cache.clear();
+        this.rootKey = null;
+        this._cwd = "/"; // a different identity's tree has different directories
+    }
+    /**
+     * Call `handler` when this filesystem changes somewhere else — another tab,
+     * another machine, the CLI.
+     *
+     * Deliberately a NOTIFICATION, not a diff: the frame names a record id, and
+     * a record id is not a path (paths are resolved by walking, and the walk is
+     * what the change may have invalidated). So the cache is dropped and the
+     * caller re-reads whatever it is actually showing. Trying to translate a
+     * record id back into a path would mean maintaining a reverse index that
+     * could itself go stale.
+     *
+     * Returns an unsubscribe function. A runtime with no socket (a CLI) gets a
+     * no-op rather than an error — watching is an optimisation, never required
+     * for correctness.
+     */
+    watch(handler) {
+        if (!this.deps.subscribe)
+            return () => { };
+        return this.deps.subscribe((raw) => {
+            let frame;
+            try {
+                frame = typeof raw === "string" ? JSON.parse(raw) : raw;
+            }
+            catch {
+                return;
+            }
+            if (frame?._t !== "change" || typeof frame.key !== "string")
+                return;
+            if (!frame.key.startsWith("vfs/"))
+                return; // someone else's data on the shared feed
+            // Drop only the record that changed.
+            //
+            // Clearing everything looked cheap and is not: our own writes echo
+            // back, so a sync that writes a few hundred files emptied the cache
+            // a few hundred times, and every path resolution in flight went back
+            // to the network for the root and every directory below it. The key
+            // names the record, so there is no need to guess.
+            const id = frame.key.startsWith("vfs/d/") ? frame.key.slice("vfs/d/".length) : null;
+            if (id)
+                this.cache.delete(id);
+            else
+                this.cache.clear(); // a shape we do not recognise: be safe
+            handler();
+        });
+    }
+    // ---- reads --------------------------------------------------------------
+    async exists(path) {
+        return (await this.find(path)) !== null;
+    }
+    async stat(path) {
+        const found = await this.find(path);
+        if (!found)
+            throw new VfsNotFoundError(this.resolve(path));
+        return toStat(this.resolve(path), found.name, found.entry);
+    }
+    /** Immediate children of a directory. One record fetch. */
+    async list(path = ".") {
+        const dir = await this.openDir(path);
+        const base = this.resolve(path);
+        return Object.entries(dir.node.entries)
+            .map(([name, entry]) => toStat(join(base, name), name, entry))
+            .sort(byDirsThenName);
+    }
+    /**
+     * Every file path under a prefix, depth-first.
+     *
+     * Deliberately separate from `list`: this walks the whole subtree, which is
+     * one fetch per directory. Fine for a project, wrong as a default.
+     */
+    async walk(path = ".") {
+        const out = [];
+        const visit = async (dirPath) => {
+            for (const entry of await this.list(dirPath)) {
+                if (entry.kind === "dir")
+                    await visit(entry.path);
+                else
+                    out.push(entry.path);
+            }
+        };
+        await visit(this.resolve(path));
+        return out;
+    }
+    async readFile(path) {
+        const entry = await this.expectFile(path);
+        return this.deps.content.read(entry.manifest);
+    }
+    async readText(path) {
+        return new TextDecoder().decode(await this.readFile(path));
+    }
+    /**
+     * A file's manifest — the handle itself, without reading the bytes.
+     *
+     * Version control records manifests rather than content, so a commit costs
+     * a hash and a reference, not a copy.
+     */
+    async statManifest(path) {
+        const entry = await this.expectFile(path);
+        return { manifest: entry.manifest, size: entry.size };
+    }
+    /**
+     * Read content by its manifest, wherever it came from.
+     *
+     * A merge needs the COMMON ANCESTOR's version of a file, which by definition
+     * is not in the working tree any more. The manifest is the whole capability,
+     * so no path lookup is involved.
+     */
+    async readByManifest(manifest) {
+        return this.deps.content.read(manifest);
+    }
+    /**
+     * Pin content that something other than the working tree depends on.
+     *
+     * A commit references a manifest, so it is an OWNER of that content — without
+     * a reference of its own, deleting the file from the working tree would free
+     * shards the history still needs, and checking out an older commit would find
+     * the content gone. (It did, in test.)
+     */
+    async retainManifest(manifest) {
+        await this.deps.content.retain(manifest);
+    }
+    /**
+     * Point a path at content that already exists.
+     *
+     * This is how a checkout restores a file: the bytes are in the shard store
+     * already, so nothing is uploaded or downloaded — only the directory record
+     * changes. Takes a reference, because a second path now depends on those
+     * shards.
+     */
+    async writeManifest(path, manifest, size) {
+        const target = this.resolve(path);
+        const name = basename(target);
+        assertValidName(name);
+        await this.mkdir(dirname(target), { recursive: true });
+        const parent = await this.openDir(dirname(target));
+        const prior = parent.node.entries[name];
+        if (prior?.kind === "dir")
+            throw new VfsConflictError(`${target} is a directory`);
+        await this.deps.content.retain(manifest);
+        const entry = {
+            kind: "file",
+            id: prior?.id ?? newId(),
+            manifest,
+            size,
+            mtime: Date.now(),
+            versions: prior?.versions ?? 0,
+        };
+        await this.mutate(parent, (node) => {
+            node.entries[name] = entry;
+        });
+        return toStat(target, name, entry);
+    }
+    // ---- writes -------------------------------------------------------------
+    /**
+     * Create a directory. `recursive` creates missing parents and tolerates an
+     * existing target, matching `mkdir -p`.
+     */
+    async mkdir(path, opts = {}) {
+        const target = this.resolve(path);
+        if (target === "/")
+            return;
+        const parts = segments(target);
+        let current = "/";
+        for (let i = 0; i < parts.length; i++) {
+            const name = parts[i];
+            const isLast = i === parts.length - 1;
+            const next = join(current, name);
+            const existing = (await this.openDir(current)).node.entries[name];
+            if (existing) {
+                if (existing.kind === "file")
+                    throw new VfsConflictError(`${next} is a file`);
+                if (isLast && !opts.recursive)
+                    throw new VfsConflictError(`${next} already exists`);
+            }
+            else {
+                if (!isLast && !opts.recursive)
+                    throw new VfsNotFoundError(current);
+                await this.createDir(current, name);
+            }
+            current = next;
+        }
+    }
+    /**
+     * Write a file, creating parent directories as needed.
+     *
+     * The previous version is pushed onto the file's history record before the
+     * directory entry is replaced, so an interrupted write can lose the new
+     * version but never the old one.
+     */
+    async writeFile(path, data, opts = {}) {
+        const target = this.resolve(path);
+        const name = basename(target);
+        assertValidName(name);
+        const parentPath = dirname(target);
+        await this.mkdir(parentPath, { recursive: true });
+        const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+        const { manifest, size } = await this.deps.content.write(bytes, {
+            name,
+            type: opts.type ?? contentTypeFor(name),
+        });
+        const parent = await this.openDir(parentPath);
+        const prior = parent.node.entries[name];
+        if (prior?.kind === "dir")
+            throw new VfsConflictError(`${target} is a directory`);
+        const id = prior?.id ?? newId();
+        let versions = prior?.versions ?? 0;
+        if (prior)
+            versions = await this.pushHistory(parent, id, prior);
+        const entry = { kind: "file", id, manifest, size, mtime: Date.now(), versions };
+        await this.mutate(parent, (node) => {
+            node.entries[name] = entry;
+        });
+        return toStat(target, name, entry);
+    }
+    /**
+     * Delete a file, or a directory when `recursive`.
+     *
+     * `keepContent` removes the entry WITHOUT releasing its shards. A checkout
+     * needs that: the file is leaving the working tree, but commits still
+     * reference the same manifest, and releasing would free content history
+     * depends on.
+     */
+    async delete(path, opts = {}) {
+        const target = this.resolve(path);
+        if (target === "/")
+            throw new VfsConflictError("the root directory cannot be deleted");
+        const name = basename(target);
+        const parent = await this.openDir(dirname(target));
+        const entry = parent.node.entries[name];
+        if (!entry)
+            throw new VfsNotFoundError(target);
+        if (entry.kind === "dir") {
+            const child = await this.openDirById(entry.id, fromBase64(entry.key));
+            const empty = Object.keys(child.node.entries).length === 0;
+            if (!empty && !opts.recursive)
+                throw new VfsConflictError(`${target} is not empty`);
+            await this.purge(child);
+        }
+        else if (opts.keepContent) {
+            await this.deps.store.delete(historyKey(entry.id)).catch(() => { });
+        }
+        else {
+            await this.releaseFile(parent, entry);
+        }
+        await this.mutate(parent, (node) => {
+            delete node.entries[name];
+        });
+    }
+    /**
+     * Move or rename. Works across directories, which is the same operation:
+     * detach the entry from one parent and attach it to another.
+     *
+     * A directory move is O(1) regardless of how much is inside it — the
+     * subtree records are not touched at all, because nothing in them records
+     * its own path.
+     */
+    async rename(from, to) {
+        const src = this.resolve(from);
+        const dst = this.resolve(to);
+        if (src === dst)
+            return;
+        if (src === "/")
+            throw new VfsConflictError("the root directory cannot be moved");
+        if (isUnder(dst, src))
+            throw new VfsConflictError(`cannot move ${src} into itself`);
+        const dstName = basename(dst);
+        assertValidName(dstName);
+        const srcParent = await this.openDir(dirname(src));
+        const entry = srcParent.node.entries[basename(src)];
+        if (!entry)
+            throw new VfsNotFoundError(src);
+        await this.mkdir(dirname(dst), { recursive: true });
+        const dstParent = await this.openDir(dirname(dst));
+        if (dstParent.node.entries[dstName])
+            throw new VfsConflictError(`${dst} already exists`);
+        // Attach before detaching. If the second write fails the entry is
+        // reachable from both parents — visible and fixable. The other order
+        // would lose the subtree entirely.
+        const moved = { ...entry, mtime: Date.now() };
+        await this.mutate(dstParent, (node) => {
+            node.entries[dstName] = moved;
+        });
+        // Re-open: same-parent moves mutated the record we are about to edit.
+        const detachFrom = await this.openDir(dirname(src));
+        await this.mutate(detachFrom, (node) => {
+            delete node.entries[basename(src)];
+        });
+    }
+    /**
+     * Copy a file or a directory tree.
+     *
+     * Copying a FILE moves no bytes: content is immutable and content-addressed,
+     * so the new entry simply points at the same manifest. A 200 MB asset
+     * duplicates in one small metadata write, and the shard store already holds
+     * exactly one copy of it.
+     *
+     * The copy gets a NEW file id, so it does not inherit or share history —
+     * two paths sharing an id would mean saving one silently pushed a version
+     * onto the other.
+     */
+    async copy(from, to) {
+        const src = this.resolve(from);
+        const dst = this.resolve(to);
+        if (src === "/")
+            throw new VfsConflictError("the root directory cannot be copied");
+        if (src === dst)
+            throw new VfsConflictError(`${dst} already exists`);
+        if (isUnder(dst, src))
+            throw new VfsConflictError(`cannot copy ${src} into itself`);
+        const found = await this.find(src);
+        if (!found)
+            throw new VfsNotFoundError(src);
+        const dstName = basename(dst);
+        assertValidName(dstName);
+        await this.mkdir(dirname(dst), { recursive: true });
+        const dstParent = await this.openDir(dirname(dst));
+        if (dstParent.node.entries[dstName])
+            throw new VfsConflictError(`${dst} already exists`);
+        const copied = await this.cloneEntry(found.entry);
+        await this.mutate(dstParent, (node) => {
+            node.entries[dstName] = copied;
+        });
+        return toStat(dst, dstName, copied);
+    }
+    /**
+     * Paths matching a glob, relative to the whole filesystem.
+     *
+     * Matching happens on the client over a walk of the tree, so the cost is one
+     * record fetch per directory — cheap for a project, and worth knowing before
+     * pointing it at the root of a large filesystem. Use `walk` when the prefix
+     * already narrows it.
+     */
+    async glob(pattern, opts = {}) {
+        const re = globToRegExp(this.resolve(pattern));
+        return (await this.walk(opts.from ?? ".")).filter((path) => re.test(path));
+    }
+    /**
+     * Delete metadata records no longer reachable from the root.
+     *
+     * These accumulate because every write touches exactly one record: if two
+     * tabs edit the same directory, last-writer-wins at the personal space can
+     * leave a child whose parent entry lost the race. Unreachable is harmless —
+     * it is invisible and undecryptable-by-nobody — but it costs storage, so
+     * this reclaims it.
+     *
+     * Deliberately explicit, never automatic: a sweep racing another tab's
+     * in-flight write could delete a record that is about to be referenced.
+     * Run it when the filesystem is idle.
+     */
+    async sweep(opts = {}) {
+        const root = await this.root();
+        const reachable = new Set();
+        const visit = async (dir) => {
+            reachable.add(dirKey(dir.id));
+            for (const entry of Object.values(dir.node.entries)) {
+                if (entry.kind === "dir") {
+                    await visit(await this.openDirById(entry.id, fromBase64(entry.key)));
+                }
+                else {
+                    reachable.add(historyKey(entry.id));
+                }
+            }
+        };
+        await visit(root);
+        // Only ever consider OUR records: the personal space is shared with
+        // chat keys, space keys and the legacy file mirror, and a sweep that
+        // reached beyond its own namespace would be a data-loss bug.
+        const mine = (await this.deps.store.list()).filter((k) => /^vfs\/[dh]\//.test(k));
+        const orphans = mine.filter((k) => !reachable.has(k));
+        // A root that read as EMPTY while orphans exist is the shape of a failed
+        // load, not of a fresh filesystem — deleting here would wipe a tree we
+        // merely failed to reach. Refuse unless the caller insists.
+        const rootEmpty = Object.keys(root.node.entries).length === 0;
+        if (rootEmpty && orphans.length && !opts.force) {
+            throw new VfsConflictError(`refusing to sweep ${orphans.length} record(s) with an empty root — ` +
+                "this looks like a failed load rather than an empty filesystem; pass { force: true } if it really is empty");
+        }
+        for (const key of orphans)
+            await this.deps.store.delete(key).catch(() => { });
+        return { removed: orphans };
+    }
+    // ---- history ------------------------------------------------------------
+    /** Prior versions of a file, newest first. One record fetch. */
+    async history(path) {
+        const entry = await this.expectFile(path);
+        const record = await this.readHistory(await this.openDir(dirname(path)), entry.id);
+        return record.versions.map(({ size, mtime }) => ({ size, mtime }));
+    }
+    /**
+     * Restore a prior version, where 0 is the most recent one.
+     *
+     * The current version is pushed onto history first, so restoring is itself
+     * undoable rather than a one-way door.
+     */
+    async restore(path, index = 0) {
+        const target = this.resolve(path);
+        const name = basename(target);
+        const parent = await this.openDir(dirname(target));
+        const entry = parent.node.entries[name];
+        if (!entry || entry.kind !== "file")
+            throw new VfsNotFoundError(target);
+        const record = await this.readHistory(parent, entry.id);
+        const version = record.versions[index];
+        if (!version)
+            throw new VfsNotFoundError(`${target} version ${index}`);
+        const versions = await this.pushHistory(parent, entry.id, entry);
+        const restored = {
+            kind: "file",
+            id: entry.id,
+            manifest: version.manifest,
+            size: version.size,
+            mtime: Date.now(),
+            versions,
+        };
+        await this.mutate(parent, (node) => {
+            node.entries[name] = restored;
+        });
+        return toStat(target, name, restored);
+    }
+    // ---- internals ----------------------------------------------------------
+    async expectFile(path) {
+        const found = await this.find(path);
+        if (!found)
+            throw new VfsNotFoundError(this.resolve(path));
+        if (found.entry.kind !== "file")
+            throw new VfsConflictError(`${this.resolve(path)} is a directory`);
+        return found.entry;
+    }
+    /** Resolve a path to its entry, or null. Root has no entry of its own. */
+    async find(path) {
+        const target = this.resolve(path);
+        if (target === "/")
+            return null;
+        const parent = await this.openDirOrNull(dirname(target));
+        if (!parent)
+            return null;
+        const name = basename(target);
+        const entry = parent.node.entries[name];
+        return entry ? { name, entry } : null;
+    }
+    async root() {
+        const seed = this.deps.seed();
+        if (!seed)
+            throw new VfsLockedError();
+        if (!this.rootKey)
+            this.rootKey = await deriveRootKey(seed);
+        return this.openDirById(ROOT_ID, this.rootKey);
+    }
+    /** Open a directory by path, creating nothing. Throws if it is missing. */
+    async openDir(path) {
+        const dir = await this.openDirOrNull(path);
+        if (!dir)
+            throw new VfsNotFoundError(this.resolve(path));
+        return dir;
+    }
+    async openDirOrNull(path) {
+        let dir = await this.root();
+        for (const name of segments(this.resolve(path))) {
+            const entry = dir.node.entries[name];
+            if (!entry || entry.kind !== "dir")
+                return null;
+            dir = await this.openDirById(entry.id, fromBase64(entry.key));
+        }
+        return dir;
+    }
+    openDirById(id, key) {
+        const hit = this.cache.get(id);
+        if (hit)
+            return hit;
+        // The PROMISE goes in the cache, not the resolved value.
+        //
+        // Reading a project means resolving hundreds of paths that share the
+        // same handful of directories. Caching only the settled value leaves
+        // every concurrent reader to miss and fire its own request for the same
+        // record — which is how loading one project turned into thousands of
+        // identical `vfs/d/<id>` fetches, most of them in flight at once.
+        const pending = (async () => {
+            const raw = await this.deps.store.get(dirKey(id));
+            // An absent record is an EMPTY directory, not an error: the root
+            // exists before anything has been written to it, and a directory is
+            // created by its parent naming it rather than by its own record
+            // appearing.
+            const node = (await unseal(key, raw)) ?? { v: 1, entries: {}, mtime: Date.now() };
+            return { id, key, node };
+        })().catch((err) => {
+            // A failed read must not be remembered, or one blip poisons the
+            // directory for the life of the session.
+            if (this.cache.get(id) === pending)
+                this.cache.delete(id);
+            throw err;
+        });
+        this.cache.set(id, pending);
+        return pending;
+    }
+    /** Apply an edit to a directory record and persist it. */
+    async mutate(dir, edit) {
+        edit(dir.node);
+        dir.node.mtime = Date.now();
+        await this.deps.store.put(dirKey(dir.id), await seal(dir.key, dir.node));
+        this.cache.set(dir.id, Promise.resolve(dir));
+    }
+    async createDir(parentPath, name) {
+        assertValidName(name);
+        const parent = await this.openDir(parentPath);
+        const entry = { kind: "dir", id: newId(), key: toBase64(newDirKey()), mtime: Date.now() };
+        await this.mutate(parent, (node) => {
+            node.entries[name] = entry;
+        });
+    }
+    /** Recursively remove a subtree's records. Best-effort: unreachable ≠ fatal. */
+    async purge(dir) {
+        for (const entry of Object.values(dir.node.entries)) {
+            if (entry.kind === "dir") {
+                await this.purge(await this.openDirById(entry.id, fromBase64(entry.key)));
+            }
+            else {
+                await this.releaseFile(dir, entry);
+            }
+        }
+        this.cache.delete(dir.id);
+        await this.deps.store.delete(dirKey(dir.id)).catch(() => { });
+    }
+    /**
+     * Deep-copy an entry. Files reuse their manifest (no bytes move); each
+     * directory gets a fresh id and key, so the copy is independent of the
+     * original — writing into one must never appear in the other.
+     */
+    async cloneEntry(entry) {
+        if (entry.kind === "file") {
+            // Same bytes, second owner: take a reference so deleting either one
+            // leaves the other readable.
+            await this.deps.content.retain(entry.manifest);
+            return { kind: "file", id: newId(), manifest: entry.manifest, size: entry.size, mtime: Date.now(), versions: 0 };
+        }
+        const source = await this.openDirById(entry.id, fromBase64(entry.key));
+        const clone = { kind: "dir", id: newId(), key: toBase64(newDirKey()), mtime: Date.now() };
+        const node = { v: 1, entries: {}, mtime: Date.now() };
+        for (const [name, child] of Object.entries(source.node.entries)) {
+            node.entries[name] = await this.cloneEntry(child);
+        }
+        const open = { id: clone.id, key: fromBase64(clone.key), node };
+        await this.deps.store.put(dirKey(open.id), await seal(open.key, node));
+        this.cache.set(open.id, Promise.resolve(open));
+        return clone;
+    }
+    /**
+     * Let go of a file's bytes: the current manifest and every retained
+     * version, then the history record itself.
+     */
+    async releaseFile(parent, entry) {
+        const record = await this.readHistory(parent, entry.id).catch(() => ({ v: 1, versions: [] }));
+        const manifests = [entry.manifest, ...record.versions.map((v) => v.manifest)];
+        for (const manifest of manifests)
+            await this.deps.content.release(manifest).catch(() => { });
+        await this.deps.store.delete(historyKey(entry.id)).catch(() => { });
+    }
+    async readHistory(parent, fileId) {
+        const raw = await this.deps.store.get(historyKey(fileId));
+        return (await unseal(parent.key, raw)) ?? { v: 1, versions: [] };
+    }
+    /** Push `entry` onto its history record. Returns the new version count. */
+    async pushHistory(parent, fileId, entry) {
+        const record = await this.readHistory(parent, fileId);
+        record.versions.unshift({ manifest: entry.manifest, size: entry.size, mtime: entry.mtime });
+        // Bounded, because this is a single stored value. Unchanged chunks are
+        // deduped by the content-addressed shard store, so the cost of keeping
+        // versions is this record's own growth — which is what the cap bounds.
+        const evicted = record.versions.slice(this.historyLimit);
+        record.versions = record.versions.slice(0, this.historyLimit);
+        // A version that falls off the end is unreachable — release its shards
+        // or the cap bounds the record's size while the storage grows forever.
+        for (const v of evicted)
+            await this.deps.content.release(v.manifest).catch(() => { });
+        await this.deps.store.put(historyKey(fileId), await seal(parent.key, record));
+        return record.versions.length;
+    }
+}
+function toStat(path, name, entry) {
+    return {
+        path,
+        name,
+        kind: entry.kind,
+        size: entry.kind === "file" ? entry.size : 0,
+        mtime: entry.mtime,
+        versions: entry.kind === "file" ? (entry.versions ?? 0) : 0,
+    };
+}
+/** Directories first, then alphabetical — what every file explorer does. */
+function byDirsThenName(a, b) {
+    if (a.kind !== b.kind)
+        return a.kind === "dir" ? -1 : 1;
+    return a.name.localeCompare(b.name);
+}
+
+/**
+ * Content addressing for repository objects.
+ *
+ * The hash must depend only on MEANING, never on serialisation accidents — two
+ * clients that build the same tree have to agree on its hash, or history forks
+ * for no reason. So keys are sorted and the encoding is fixed here rather than
+ * left to `JSON.stringify`'s insertion order.
+ */
+/** Canonical JSON: object keys sorted, recursively. */
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}
+/** SHA-256 of an object's canonical form, hex. */
+async function hashObject(value) {
+    const bytes = new TextEncoder().encode(canonical(value));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Three-way line merge.
+ *
+ * Given a common ancestor and two descendants, produce the combined text — or
+ * report the regions where both sides changed the same lines differently.
+ *
+ * The server cannot do any of this: it holds ciphertext and cannot compare
+ * versions, so merging is entirely a client concern and has to be exact here.
+ */
+/**
+ * Longest common subsequence, as a list of matched index pairs.
+ *
+ * Classic dynamic programming. Fine for source files; a file with hundreds of
+ * thousands of lines would want a smarter algorithm, and would also be a strange
+ * thing to merge.
+ */
+function lcs(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const table = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const pairs = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            pairs.push([i, j]);
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return pairs;
+}
+/**
+ * Lines of `base` that BOTH sides left untouched.
+ *
+ * These are the anchors the merge is built around: between two consecutive
+ * anchors, each side has some (possibly empty) replacement, and comparing those
+ * replacements is the entire decision.
+ */
+function stableAnchors(base, ours, theirs) {
+    const ourMatch = new Map(lcs(base, ours));
+    const theirMatch = new Map(lcs(base, theirs));
+    const anchors = [];
+    for (let b = 0; b < base.length; b++) {
+        const o = ourMatch.get(b);
+        const t = theirMatch.get(b);
+        if (o !== undefined && t !== undefined)
+            anchors.push([b, o, t]);
+    }
+    return anchors;
+}
+const same = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+/**
+ * Merge `ours` and `theirs` over their common ancestor `base`.
+ *
+ * A region where only one side changed takes that side. A region where both
+ * made the SAME change takes it once — two people fixing the same typo is not a
+ * conflict. Only genuinely divergent edits conflict.
+ */
+function merge3(base, ours, theirs) {
+    const anchors = stableAnchors(base, ours, theirs);
+    const out = [];
+    const conflicts = [];
+    let b = 0;
+    let o = 0;
+    let t = 0;
+    const settle = (ourSlice, theirSlice, baseSlice) => {
+        if (same(ourSlice, theirSlice)) {
+            out.push(...ourSlice); // identical edits, or no edit
+        }
+        else if (same(ourSlice, baseSlice)) {
+            out.push(...theirSlice); // only they changed it
+        }
+        else if (same(theirSlice, baseSlice)) {
+            out.push(...ourSlice); // only we changed it
+        }
+        else {
+            conflicts.push({ line: out.length + 1, ours: ourSlice, theirs: theirSlice });
+            out.push(...ourSlice); // markers are added by the caller
+        }
+    };
+    for (const [ab, ao, at] of anchors) {
+        settle(ours.slice(o, ao), theirs.slice(t, at), base.slice(b, ab));
+        out.push(base[ab]);
+        b = ab + 1;
+        o = ao + 1;
+        t = at + 1;
+    }
+    settle(ours.slice(o), theirs.slice(t), base.slice(b));
+    return { lines: out, conflicts };
+}
+/**
+ * Merge to text, writing conflict markers where the sides diverged.
+ *
+ * Markers rather than a bespoke format: they are what every developer already
+ * knows how to resolve, and resolving becomes ordinary editing.
+ */
+function merge3Text(base, ours, theirs, labels = { ours: "ours", theirs: "theirs" }) {
+    const split = (s) => (s === "" ? [] : s.split("\n"));
+    const anchors = stableAnchors(split(base), split(ours), split(theirs));
+    const B = split(base);
+    const O = split(ours);
+    const T = split(theirs);
+    const out = [];
+    let conflicted = false;
+    let b = 0;
+    let o = 0;
+    let t = 0;
+    const settle = (ourSlice, theirSlice, baseSlice) => {
+        if (same(ourSlice, theirSlice))
+            out.push(...ourSlice);
+        else if (same(ourSlice, baseSlice))
+            out.push(...theirSlice);
+        else if (same(theirSlice, baseSlice))
+            out.push(...ourSlice);
+        else {
+            conflicted = true;
+            out.push(`<<<<<<< ${labels.ours}`, ...ourSlice, "=======", ...theirSlice, `>>>>>>> ${labels.theirs}`);
+        }
+    };
+    for (const [ab, ao, at] of anchors) {
+        settle(O.slice(o, ao), T.slice(t, at), B.slice(b, ab));
+        out.push(B[ab]);
+        b = ab + 1;
+        o = ao + 1;
+        t = at + 1;
+    }
+    settle(O.slice(o), T.slice(t), B.slice(b));
+    return { text: out.join("\n"), conflicted };
+}
+
+/** Storage keys. Namespaced per project so repositories cannot collide. */
+const objectKey = (slug, hash) => `vcs/${slug}/obj/${hash}`;
+const refKey = (slug, name) => `vcs/${slug}/refs/${name}`;
+const headKey = (slug) => `vcs/${slug}/HEAD`;
+const refsIndexKey = (slug) => `vcs/${slug}/refs`;
+/** An in-progress merge: what to make the second parent when it is committed. */
+const mergeKey = (slug) => `vcs/${slug}/MERGE`;
+const DEFAULT_BRANCH = "main";
+class VcsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VcsError";
+    }
+}
+
+/** A project's repository. One per `/apps/<slug>`. */
+/**
+ * Types never worth attempting a three-way merge on.
+ *
+ * NOT application/octet-stream: that is the UNKNOWN case, which is what every
+ * extensionless text file gets labelled, so it must reach the content sniff
+ * rather than being rejected on the label.
+ */
+const BINARY_TYPE = /^(image|audio|video|font)\/|^application\/(wasm|zip|pdf|x-tar|gzip)/;
+/**
+ * Does this look like text a person could resolve conflict markers in?
+ *
+ * A NUL byte is the classic tell and the one git uses — no textual encoding we
+ * care about produces one. Invalid UTF-8 is the other: decoding it would
+ * corrupt the file on write-back even if the merge itself succeeded.
+ */
+function looksTextual(bytes) {
+    if (bytes.includes(0))
+        return false;
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Compare two path → entry maps into a change list. */
+function comparePaths(before, after) {
+    const changes = [];
+    for (const [path, entry] of after) {
+        const was = before.get(path);
+        if (!was)
+            changes.push({ path, kind: "added" });
+        else if (was.manifest.id !== entry.manifest.id)
+            changes.push({ path, kind: "modified" });
+    }
+    for (const path of before.keys())
+        if (!after.has(path))
+            changes.push({ path, kind: "removed" });
+    return changes.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+class Repo {
+    slug;
+    deps;
+    constructor(slug, deps) {
+        this.slug = slug;
+        this.deps = deps;
+    }
+    get root() {
+        return `/apps/${this.slug}`;
+    }
+    // ---- objects ------------------------------------------------------------
+    /** Store an object, returning its hash and whether it was new. */
+    async put(value) {
+        const hash = await hashObject(value);
+        // Content-addressed, so re-writing an identical object is a no-op —
+        // worth skipping because an unchanged directory is written on every
+        // commit that touches any of its siblings.
+        const existing = await this.deps.store.get(objectKey(this.slug, hash));
+        if (existing)
+            return { hash, created: false };
+        await this.deps.store.put(objectKey(this.slug, hash), await seal(await this.deps.key(), value));
+        return { hash, created: true };
+    }
+    async get(hash) {
+        const raw = await this.deps.store.get(objectKey(this.slug, hash));
+        const value = raw ? await unseal(await this.deps.key(), raw) : null;
+        if (!value)
+            throw new VcsError(`object ${hash.slice(0, 8)} is missing from this repository`);
+        return value;
+    }
+    // ---- refs ---------------------------------------------------------------
+    async head() {
+        const raw = await this.deps.store.get(headKey(this.slug));
+        const value = raw ? await unseal(await this.deps.key(), raw) : null;
+        return value ?? { branch: DEFAULT_BRANCH };
+    }
+    async setHead(head) {
+        await this.deps.store.put(headKey(this.slug), await seal(await this.deps.key(), head));
+    }
+    async readRef(name) {
+        const raw = await this.deps.store.get(refKey(this.slug, name));
+        return raw ? await unseal(await this.deps.key(), raw).then((v) => v?.commit ?? null) : null;
+    }
+    async writeRef(name, commit) {
+        await this.deps.store.put(refKey(this.slug, name), await seal(await this.deps.key(), { commit }));
+        // The personal space has no prefix listing, so branches are tracked in
+        // an index. Kept append-only-ish: losing a name here loses the branch.
+        const names = new Set(await this.branches());
+        names.add(name);
+        await this.deps.store.put(refsIndexKey(this.slug), await seal(await this.deps.key(), { names: [...names].sort() }));
+    }
+    /** Every branch name in this repository. */
+    async branches() {
+        const raw = await this.deps.store.get(refsIndexKey(this.slug));
+        const value = raw ? await unseal(await this.deps.key(), raw) : null;
+        return value?.names ?? [];
+    }
+    /** The commit HEAD resolves to, or null in an empty repository. */
+    async current() {
+        const head = await this.head();
+        return "detached" in head ? head.detached : this.readRef(head.branch);
+    }
+    // ---- commit -------------------------------------------------------------
+    /**
+     * Freeze the working tree as a commit.
+     *
+     * Trees are written bottom-up so a directory's hash is known before its
+     * parent references it. Nothing is written to the shard store: file entries
+     * carry the manifest the VFS already holds.
+     */
+    async commit(message, parents) {
+        if (!message.trim())
+            throw new VcsError("a commit needs a message");
+        const tree = await this.writeTree(this.root);
+        const parent = await this.current();
+        // Finish an interrupted merge: the recorded other side becomes the
+        // second parent. Losing this would produce a single-parent commit, and
+        // the merge would look as though it never happened — the branches would
+        // still appear diverged.
+        const pending = parents ? null : await this.pendingMerge();
+        const resolved = parents ?? (pending ? [parent, pending.theirs] : parent ? [parent] : []);
+        if (!parents && !pending && parent) {
+            const previous = await this.get(parent);
+            // An empty commit is almost always a mistake — the user believes
+            // they saved something they did not.
+            if (previous.tree === tree)
+                throw new VcsError("nothing to commit — the project is unchanged");
+        }
+        const commit = {
+            v: 1,
+            tree,
+            parents: resolved,
+            message: message.trim(),
+            author: this.deps.author(),
+            at: Date.now(),
+        };
+        const { hash } = await this.put(commit);
+        await this.advance(hash);
+        if (pending)
+            await this.deps.store.delete(mergeKey(this.slug)).catch(() => { });
+        return hash;
+    }
+    /** Move whatever HEAD points at onto a new commit. */
+    async advance(hash) {
+        const head = await this.head();
+        if ("detached" in head)
+            await this.setHead({ detached: hash });
+        else
+            await this.writeRef(head.branch, hash);
+    }
+    /** The other side of a merge that stopped for conflicts, if any. */
+    async pendingMerge() {
+        const raw = await this.deps.store.get(mergeKey(this.slug));
+        return raw ? await unseal(await this.deps.key(), raw) : null;
+    }
+    /** Write a directory and everything under it, returning the tree's hash. */
+    async writeTree(path) {
+        const entries = {};
+        for (const entry of await this.deps.vfs.list(path)) {
+            if (entry.kind === "dir") {
+                entries[entry.name] = { kind: "tree", hash: await this.writeTree(entry.path) };
+            }
+            else {
+                const stat = await this.deps.vfs.statManifest(entry.path);
+                entries[entry.name] = { kind: "file", manifest: stat.manifest, size: entry.size };
+            }
+        }
+        const { hash, created } = await this.put({ v: 1, entries });
+        // A NEW tree means this directory's contents are newly recorded, so the
+        // repository takes its own reference to their content. Without it, a
+        // later working-tree delete frees shards the commit still needs and the
+        // history becomes unreadable.
+        //
+        // Retaining per new tree rather than per changed FILE slightly
+        // over-retains — an unchanged file in a directory whose sibling changed
+        // gets a second reference. That errs towards keeping content, which is
+        // the correct direction to err in.
+        if (created) {
+            for (const entry of Object.values(entries)) {
+                if (entry.kind === "file")
+                    await this.deps.vfs.retainManifest(entry.manifest);
+            }
+        }
+        return hash;
+    }
+    // ---- history ------------------------------------------------------------
+    /** Commits reachable from HEAD, newest first. */
+    async log(limit = 50) {
+        const start = await this.current();
+        if (!start)
+            return [];
+        const out = [];
+        const seen = new Set();
+        // Breadth-first over parents so a merge's two sides both appear, and
+        // `seen` keeps a diamond from listing the shared history twice.
+        const queue = [start];
+        while (queue.length && out.length < limit) {
+            const hash = queue.shift();
+            if (seen.has(hash))
+                continue;
+            seen.add(hash);
+            const commit = await this.get(hash);
+            out.push({
+                hash,
+                message: commit.message,
+                author: commit.author,
+                at: commit.at,
+                parents: commit.parents,
+            });
+            queue.push(...commit.parents);
+        }
+        return out.sort((a, b) => b.at - a.at);
+    }
+    // ---- diff ---------------------------------------------------------------
+    /**
+     * What changed between two commits.
+     *
+     * Identical subtree hashes prune the walk: an untouched directory is one
+     * comparison regardless of how much is inside it. That is the payoff for
+     * content-addressing the trees.
+     */
+    async diff(fromHash, toHash) {
+        const from = fromHash ? (await this.get(fromHash)).tree : null;
+        const to = (await this.get(toHash)).tree;
+        const changes = [];
+        await this.diffTrees(from, to, "", changes);
+        return changes.sort((a, b) => (a.path < b.path ? -1 : 1));
+    }
+    async diffTrees(fromHash, toHash, prefix, out) {
+        if (fromHash === toHash)
+            return; // identical subtrees: nothing below can differ
+        const from = fromHash ? await this.get(fromHash) : { entries: {} };
+        const to = toHash ? await this.get(toHash) : { entries: {} };
+        for (const name of new Set([...Object.keys(from.entries), ...Object.keys(to.entries)])) {
+            const a = from.entries[name];
+            const b = to.entries[name];
+            const path = `${prefix}/${name}`;
+            if (a && b && a.kind === "tree" && b.kind === "tree") {
+                await this.diffTrees(a.hash, b.hash, path, out);
+            }
+            else if (a?.kind === "tree" || b?.kind === "tree") {
+                // A directory replaced by a file (or the reverse) — recurse both
+                // sides so every affected path is reported, not just the name.
+                await this.diffTrees(a?.kind === "tree" ? a.hash : null, b?.kind === "tree" ? b.hash : null, path, out);
+                if (a?.kind === "file")
+                    out.push({ path, kind: "removed" });
+                if (b?.kind === "file")
+                    out.push({ path, kind: "added" });
+            }
+            else if (!a && b) {
+                out.push({ path, kind: "added" });
+            }
+            else if (a && !b) {
+                out.push({ path, kind: "removed" });
+            }
+            else if (a?.kind === "file" && b?.kind === "file" && a.manifest.id !== b.manifest.id) {
+                out.push({ path, kind: "modified" });
+            }
+        }
+    }
+    // ---- checkout -----------------------------------------------------------
+    /**
+     * Replace the working tree with a commit's.
+     *
+     * Moves no file content: entries carry manifests the shard store already
+     * holds, so this rewrites directory records only.
+     */
+    /**
+     * What has changed since the last commit.
+     *
+     * Compares the WORKING TREE against HEAD without writing any objects: the
+     * common case is answering "anything to commit?", and a `status` that
+     * quietly stored a tree object every time would litter the repository with
+     * trees for states nobody chose to keep.
+     */
+    async status() {
+        const head = await this.current();
+        const before = head ? await this.filesOf(head) : new Map();
+        const after = await this.workingFiles();
+        return comparePaths(before, after);
+    }
+    /** The working tree as a path → entry map, mirroring `filesOf`. */
+    async workingFiles() {
+        const out = new Map();
+        for (const abs of await this.deps.vfs.walk(this.root)) {
+            const stat = await this.deps.vfs.statManifest(abs);
+            out.set(abs.slice(this.root.length), { kind: "file", manifest: stat.manifest, size: stat.size });
+        }
+        return out;
+    }
+    /**
+     * Turn what a person typed into a commit hash.
+     *
+     * Accepts a branch name, `HEAD`, a full or abbreviated hash, and trailing
+     * `^` / `~n` to walk back through parents — so `show abc123^` means "the
+     * commit before that one" the way anyone who has used git expects.
+     */
+    async resolve(rev) {
+        const m = /^(.*?)((?:\^|~\d+)*)$/.exec(rev.trim());
+        if (!m)
+            throw new VcsError(`cannot understand "${rev}"`);
+        const [, base, steps] = m;
+        let hash = null;
+        if (!base || base === "HEAD")
+            hash = await this.current();
+        else if (await this.readRef(base))
+            hash = await this.readRef(base);
+        else
+            hash = await this.expand(base);
+        if (!hash)
+            throw new VcsError(`no commit matches "${rev}"`);
+        for (const step of steps.match(/\^|~\d+/g) ?? []) {
+            const back = step === "^" ? 1 : Number(step.slice(1));
+            for (let i = 0; i < back; i++) {
+                const parents = (await this.get(hash)).parents;
+                if (!parents.length)
+                    throw new VcsError(`"${rev}" reaches past the first commit`);
+                hash = parents[0]; // first parent: the branch you were on
+            }
+        }
+        return hash;
+    }
+    /** A hash prefix a person typed → the one commit it names. */
+    async expand(prefix) {
+        if (!/^[0-9a-f]{4,}$/.test(prefix))
+            return null;
+        const keys = await this.deps.store.list();
+        const wanted = objectKey(this.slug, prefix);
+        const hits = keys.filter((k) => k.startsWith(wanted));
+        // Ambiguous is an error, not a coin toss — acting on the wrong commit
+        // is exactly the kind of mistake version control exists to prevent.
+        if (hits.length > 1)
+            throw new VcsError(`"${prefix}" matches ${hits.length} objects — use more characters`);
+        if (!hits.length)
+            return null;
+        const hash = hits[0].slice(objectKey(this.slug, "").length);
+        // Objects include trees; only a commit is a valid revision.
+        const object = await this.get(hash);
+        return object && "tree" in object ? hash : null;
+    }
+    /**
+     * Put one file back to the way it was in a commit.
+     *
+     * Scoped to a path on purpose — recovering one file you broke should not
+     * mean rewinding everything else you have done since.
+     */
+    async restore(path, rev = "HEAD") {
+        const hash = await this.resolve(rev);
+        const files = await this.filesOf(hash);
+        const key = path.startsWith(this.root) ? path.slice(this.root.length) : path.startsWith("/") ? path : `/${path}`;
+        const entry = files.get(key);
+        if (!entry)
+            throw new VcsError(`${key} is not in ${rev}`);
+        await this.deps.vfs.writeManifest(this.abs(key), entry.manifest, entry.size);
+    }
+    async checkout(commitHash, opts = {}) {
+        await this.guardWorkingTree(opts.discardChanges);
+        await this.materialise(commitHash);
+        // DETACHED on purpose: committing from a historical state must not
+        // silently rewrite whichever branch you happened to be on. `switchTo`
+        // is how you re-attach.
+        await this.setHead({ detached: commitHash });
+    }
+    /** Make the working tree match a commit, leaving HEAD alone. */
+    async materialise(commitHash) {
+        const commit = await this.get(commitHash);
+        const wanted = new Map();
+        await this.collect(commit.tree, "", wanted);
+        // Remove what the commit does not have BEFORE writing what it does —
+        // otherwise a file replaced by a directory of the same name collides.
+        for (const abs of await this.deps.vfs.walk(this.root)) {
+            const path = abs.slice(this.root.length);
+            // keepContent: history still references these manifests.
+            if (!wanted.has(path))
+                await this.deps.vfs.delete(abs, { keepContent: true }).catch(() => { });
+        }
+        for (const [path, entry] of wanted) {
+            await this.deps.vfs.writeManifest(this.abs(path), entry.manifest, entry.size);
+        }
+    }
+    /** Project-relative path → absolute VFS path. */
+    abs(path) {
+        return `${this.root}${path}`;
+    }
+    async collect(treeHash, prefix, out) {
+        const tree = await this.get(treeHash);
+        for (const [name, entry] of Object.entries(tree.entries)) {
+            const path = `${prefix}/${name}`;
+            if (entry.kind === "tree")
+                await this.collect(entry.hash, path, out);
+            else
+                out.set(path, entry);
+        }
+    }
+    // ---- branches -----------------------------------------------------------
+    /** Create a branch at a commit (HEAD by default). Does not switch to it. */
+    async branch(name, at) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._\/-]*$/.test(name))
+            throw new VcsError(`"${name}" is not a usable branch name`);
+        if (await this.readRef(name))
+            throw new VcsError(`branch "${name}" already exists`);
+        const commit = at ?? (await this.current());
+        if (!commit)
+            throw new VcsError("cannot branch an empty repository — commit something first");
+        await this.writeRef(name, commit);
+        return commit;
+    }
+    /**
+     * Move onto a branch, bringing the working tree with it.
+     *
+     * Unlike {@link checkout}, this ATTACHES head: later commits advance the
+     * branch. Checking out a bare commit deliberately does not, so that
+     * committing from a historical state cannot silently rewrite a branch.
+     */
+    async switchTo(name, opts = {}) {
+        const commit = await this.readRef(name);
+        if (!commit)
+            throw new VcsError(`no branch named "${name}"`);
+        await this.guardWorkingTree(opts.discardChanges);
+        await this.materialise(commit);
+        await this.setHead({ branch: name });
+    }
+    /**
+     * Refuse to overwrite work that was never recorded.
+     *
+     * Moving between commits REPLACES the working tree, so uncommitted edits
+     * are gone — and unlike an ordinary overwrite, the person did not ask for
+     * anything to be written. Naming the files is the point: "you have changes"
+     * with no list leaves them guessing what they are about to lose.
+     */
+    async guardWorkingTree(discard) {
+        if (discard)
+            return;
+        const pending = await this.status();
+        if (!pending.length)
+            return;
+        const names = pending.slice(0, 5).map((c) => c.path).join(", ");
+        const more = pending.length > 5 ? `, and ${pending.length - 5} more` : "";
+        throw new VcsError(`${pending.length} uncommitted change(s) would be lost: ${names}${more}. ` +
+            "Commit them first, or pass { discardChanges: true } to throw them away.");
+    }
+    /** The branch HEAD is on, or null when detached. */
+    async currentBranch() {
+        const head = await this.head();
+        return "detached" in head ? null : head.branch;
+    }
+    // ---- merge --------------------------------------------------------------
+    /**
+     * Merge another branch into the current one.
+     *
+     * Every part of this is client-side by necessity: the server holds
+     * ciphertext and cannot compare versions, so base, ours and theirs are all
+     * fetched and decrypted here.
+     */
+    async merge(name, opts = {}) {
+        const theirs = await this.readRef(name);
+        if (!theirs)
+            throw new VcsError(`no branch named "${name}"`);
+        // A merge writes to the working tree as freely as a switch does.
+        await this.guardWorkingTree(opts.discardChanges);
+        const ours = await this.current();
+        if (!ours)
+            throw new VcsError("nothing to merge into — commit something first");
+        if (ours === theirs)
+            return { kind: "up-to-date", conflicts: [] };
+        const base = await this.mergeBase(ours, theirs);
+        if (base === theirs)
+            return { kind: "up-to-date", conflicts: [] };
+        if (base === ours) {
+            // Fast-forward: our history is contained in theirs, so there is
+            // nothing to combine — just move.
+            await this.materialise(theirs);
+            await this.advance(theirs);
+            return { kind: "fast-forward", commit: theirs, conflicts: [] };
+        }
+        const [baseFiles, ourFiles, theirFiles] = await Promise.all([
+            base ? this.filesOf(base) : new Map(),
+            this.filesOf(ours),
+            this.filesOf(theirs),
+        ]);
+        const conflicts = [];
+        for (const path of new Set([...ourFiles.keys(), ...theirFiles.keys(), ...baseFiles.keys()])) {
+            const b = baseFiles.get(path);
+            const o = ourFiles.get(path);
+            const t = theirFiles.get(path);
+            const conflict = await this.settlePath(path, b, o, t);
+            if (conflict)
+                conflicts.push(conflict);
+        }
+        if (conflicts.length) {
+            // Record what to merge with, so finishing is just: fix the files,
+            // then commit. Losing this would silently produce a commit with one
+            // parent, and the merge would appear never to have happened.
+            await this.deps.store.put(mergeKey(this.slug), await seal(await this.deps.key(), { theirs, name }));
+            return { kind: "conflicted", conflicts };
+        }
+        const commit = await this.commit(`Merge ${name}`, [ours, theirs]);
+        return { kind: "merged", commit, conflicts: [] };
+    }
+    /** Decide one path. Returns a conflict when it cannot be settled. */
+    async settlePath(path, b, o, t) {
+        const id = (f) => f?.manifest.id;
+        if (id(o) === id(t))
+            return null; // already agree
+        if (!o && !b && t)
+            return this.take(path, t); // only they added it
+        if (!t && !b && o)
+            return null; // only we added it
+        if (id(o) === id(b)) { // only they touched it
+            if (!t) {
+                await this.deps.vfs.delete(this.abs(path), { keepContent: true }).catch(() => { });
+                return null;
+            }
+            return this.take(path, t);
+        }
+        if (id(t) === id(b))
+            return null; // only we touched it
+        // Both sides moved. A file one side deleted and the other edited is not
+        // a merge decision a tool should make silently.
+        if (!o || !t)
+            return { path, reason: "modify-delete" };
+        // Definitely-binary types are rejected WITHOUT reading them — merging
+        // bytes line-by-line produces corruption, not a result, and these files
+        // are exactly the large ones.
+        if (BINARY_TYPE.test(o.manifest.type ?? "") || BINARY_TYPE.test(t.manifest.type ?? "")) {
+            return { path, reason: "binary" };
+        }
+        const [baseBytes, ourBytes, theirBytes] = await Promise.all([
+            b ? this.deps.vfs.readByManifest(b.manifest) : Promise.resolve(new Uint8Array()),
+            this.deps.vfs.readByManifest(o.manifest),
+            this.deps.vfs.readByManifest(t.manifest),
+        ]);
+        // Then judge by CONTENT, not by the declared type.
+        //
+        // The type is a hint we do not own: a content store may omit it, and
+        // plenty of real text files carry no extension to derive one from
+        // (Makefile, LICENSE, .gitignore, .env). Trusting it alone turned every
+        // one of those into an unmergeable false conflict.
+        if (![ourBytes, theirBytes, baseBytes].every(looksTextual))
+            return { path, reason: "binary" };
+        const decode = (bytes) => new TextDecoder().decode(bytes);
+        const { text, conflicted } = merge3Text(decode(baseBytes), decode(ourBytes), decode(theirBytes));
+        await this.deps.vfs.writeFile(this.abs(path), text);
+        return conflicted ? { path, reason: "content" } : null;
+    }
+    async take(path, entry) {
+        await this.deps.vfs.writeManifest(this.abs(path), entry.manifest, entry.size);
+        return null;
+    }
+    /**
+     * The most recent commit reachable from both.
+     *
+     * Walks our ancestry into a set, then theirs breadth-first until it hits it —
+     * so the first match is the nearest, which is what a three-way merge needs.
+     */
+    async mergeBase(a, b) {
+        const ancestors = new Set();
+        const collect = async (start) => {
+            const queue = [start];
+            while (queue.length) {
+                const hash = queue.shift();
+                if (ancestors.has(hash))
+                    continue;
+                ancestors.add(hash);
+                queue.push(...(await this.get(hash)).parents);
+            }
+        };
+        await collect(a);
+        const queue = [b];
+        const seen = new Set();
+        while (queue.length) {
+            const hash = queue.shift();
+            if (seen.has(hash))
+                continue;
+            seen.add(hash);
+            if (ancestors.has(hash))
+                return hash;
+            queue.push(...(await this.get(hash)).parents);
+        }
+        return null;
+    }
+    /** Every file in a commit, by path. */
+    async filesOf(commitHash) {
+        const commit = await this.get(commitHash);
+        const out = new Map();
+        await this.collect(commit.tree, "", out);
+        return out;
+    }
+}
+/**
+ * Version control over the VFS.
+ *
+ * One repository per project, addressed by slug — the same slug the VFS stores
+ * that project's working tree under. `client.vcs.open("my-app")` is the whole
+ * entry point.
+ */
+class VcsNamespace {
+    deps;
+    repos = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The repository for one project. Cheap and cached; creates nothing. */
+    open(slug) {
+        let repo = this.repos.get(slug);
+        if (!repo) {
+            repo = new Repo(slug, {
+                vfs: this.deps.vfs,
+                store: this.deps.store,
+                key: async () => {
+                    const seed = this.deps.seed();
+                    if (!seed)
+                        throw new VcsError("client.vcs: no session — sign in first.");
+                    return deriveRepoKey(seed, slug);
+                },
+                author: this.deps.author,
+            });
+            this.repos.set(slug, repo);
+        }
+        return repo;
+    }
+}
+
 /**
  * `ChatKeyVault` — SDK-owned lifecycle for a member's long-lived ratchet/space
  * keypair (the connect `KeyStore` entry keyed by the member id / username).
@@ -12604,6 +14564,8 @@ class DbCache {
  * `FileStorage`, `EncryptedSession`, `Network`, …) remain exported and usable
  * directly, but the client is the supported, ergonomic surface.
  */
+/** Personal-space key holding the id of the space VFS content is written to. */
+const VFS_SPACE_KEY = "vfs/space";
 /** The hosted Muhkoo Accelerator — the default {@link ClientOptions.baseUrl}. */
 const DEFAULT_BASE_URL = "https://api.muhkoo.dev";
 /** The hosted auth SPA — the default {@link ClientOptions.authBaseUrl}. */
@@ -12625,6 +14587,10 @@ class Client {
     db;
     /** File storage — `client.storage.writeFile(...)`, etc. */
     storage;
+    /** Filesystem over the personal space: directories, versions, real paths. */
+    vfs;
+    /** Version control over the VFS: commits, branches, merges — per project. */
+    vcs;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     message;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
@@ -12724,6 +14690,103 @@ class Client {
             deferShardUpload,
         });
         this.message = new MessageNamespace({ http: this.http, session: this.session, wsBaseUrl });
+        // The VFS stores its metadata in the personal space — the same place
+        // `storage.writeFile` already mirrors `{spaceId, manifest}` to, only
+        // arranged as a navigable tree instead of a flat index keyed by file id.
+        //
+        // Content still goes through `storage.writeFile` untouched, into a real
+        // Space with a real gated manifest. The space is created once, lazily,
+        // and its id recorded in the personal space: a filesystem that has never
+        // been written to should not cost a space.
+        const personalStore = {
+            get: async (key) => {
+                const c = this.session.commitment;
+                if (!c)
+                    throw new Error("client.vfs: no session — sign in first.");
+                const res = await this.http.post(`/api/personal/${encodeURIComponent(c)}/kv/${encodeURIComponent(key)}/get`, {});
+                return res?.value ?? null;
+            },
+            put: async (key, value) => {
+                const c = this.session.commitment;
+                if (!c)
+                    throw new Error("client.vfs: no session — sign in first.");
+                await this.http.post(`/api/personal/${encodeURIComponent(c)}/kv/${encodeURIComponent(key)}`, { value });
+            },
+            delete: async (key) => {
+                const c = this.session.commitment;
+                if (!c)
+                    throw new Error("client.vfs: no session — sign in first.");
+                await this.http.del(`/api/personal/${encodeURIComponent(c)}/kv/${encodeURIComponent(key)}`);
+            },
+            list: async () => {
+                const c = this.session.commitment;
+                if (!c)
+                    throw new Error("client.vfs: no session — sign in first.");
+                const res = await this.http.post(`/api/personal/${encodeURIComponent(c)}/list`, {});
+                return res?.keys ?? [];
+            },
+        };
+        let contentSpace = null;
+        const resolveContentSpace = () => {
+            // Cached as the PROMISE, not the value: two concurrent first writes
+            // would otherwise each create a space and one would be orphaned.
+            if (!contentSpace) {
+                contentSpace = (async () => {
+                    const existing = await personalStore.get(VFS_SPACE_KEY);
+                    if (typeof existing === "string" && existing)
+                        return this.space.get(existing);
+                    // `messaging: false` — this space only ever holds files, and
+                    // file chunks carry their own keys, so it needs no group
+                    // keyring and no socket. Creating it the normal way opens a
+                    // WebSocket, which made the first write hang indefinitely.
+                    const space = await this.space.createSpace({ private: true, messaging: false });
+                    await personalStore.put(VFS_SPACE_KEY, space.id);
+                    return space;
+                })().catch((err) => {
+                    contentSpace = null; // let the next write retry
+                    throw err;
+                });
+            }
+            return contentSpace;
+        };
+        this.vfs = new VfsNamespace({
+            store: personalStore,
+            seed: () => this.session.seed,
+            // Share the personal space's socket with `client.kv` rather than
+            // opening a second one to the same Durable Object.
+            subscribe: (handler) => this.kv.onRaw(handler),
+            content: {
+                // `putFile` needs no WebSocket and commits the shards, so the
+                // bytes are metered to the owning app and reference-counted for
+                // GC. `storage.writeFile` would additionally index the manifest
+                // in the space — a second, diverging source of truth for a file
+                // whose handle the VFS already holds.
+                write: async (data, meta) => {
+                    const space = await resolveContentSpace();
+                    const { manifest, stat } = await space.putFile(data, { name: meta.name, type: meta.type });
+                    return { manifest, size: stat.size };
+                },
+                // Reads go through the manifest alone — no space needed. That is
+                // the capability path, so it keeps working for a file whose
+                // handle was shared from someone else's filesystem.
+                read: async (manifest) => (await this.storage.readByManifest(manifest)).data,
+                release: async (manifest) => {
+                    await (await resolveContentSpace()).releaseFile(manifest);
+                },
+                retain: async (manifest) => {
+                    await (await resolveContentSpace()).commitFile(manifest);
+                },
+            },
+        });
+        // Sealed into the SAME personal store as the VFS metadata, so a project
+        // and its history live or die together — there is no way to end up with
+        // commits whose working tree is gone, or the reverse.
+        this.vcs = new VcsNamespace({
+            vfs: this.vfs,
+            store: personalStore,
+            seed: () => this.session.seed,
+            author: () => this.session.commitment ?? "unknown",
+        });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
         // by client.kv), so a returning member hydrates without a fresh keyring
         // round-trip. The server only ever sees ciphertext.
@@ -13662,5 +15725,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
     default: loadRsWasm
 });
 
-export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReauthRequiredError, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes, configureDeviceStore, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, log, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$1 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES$1 as AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_BASE_URL, DEFAULT_BRANCH, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReauthRequiredError, ReedSolomonCodec, Repo, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, VcsError, VcsNamespace, VfsLockedError, VfsNamespace, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes, configureDeviceStore, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$2 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, log, manifestToStat, materializeRow, merge3, merge3Text, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$2 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map