@muhkoo/connect 0.10.13-alpha.0 → 0.11.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.13-alpha.0";
+const VERSION = "0.11.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);
@@ -3769,6 +3771,30 @@ function rpIdUsableForOrigin(rpId, host) {
         return false;
     return h === rpId || h.endsWith(`.${rpId}`);
 }
+/**
+ * Would {@link AuthNamespace.loginWithPasskey} accept a factor recorded with
+ * this `rpId`, from `host`?
+ *
+ * This is deliberately NOT the same as {@link rpIdUsableForOrigin}. That answers
+ * a raw WebAuthn question and is `false` for a missing rpId. But a factor with
+ * NO recorded rpId predates per-origin enrolment, and `loginWithPasskey`
+ * resolves it as `params.rpId ?? host` — so it IS usable, from anywhere.
+ *
+ * Callers deciding "should I even try a passkey here?" must use this one.
+ * Reaching for `rpIdUsableForOrigin` instead silently excludes every legacy
+ * passkey holder, which has locked real users out of production twice.
+ *
+ * The `?? host` fallback applies to nullish only, matching `loginWithPasskey`:
+ * an empty-string rpId stays unusable rather than resolving to the host.
+ */
+function passkeyUsableFromOrigin(rpId, host) {
+    const h = host ?? defaultRpId();
+    if (!h)
+        return false;
+    if (rpId == null)
+        return true;
+    return rpIdUsableForOrigin(rpId, h);
+}
 /** Thrown when the account's passkey belongs to a different origin. Callers
  *  should treat this as "no passkey here" and fall back to another factor. */
 class PasskeyOriginError extends Error {
@@ -3997,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);
@@ -4011,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));
 }
@@ -4035,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 {
@@ -4080,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();
@@ -4720,9 +4746,11 @@ class HostedAuth {
     /**
      * The account's paired devices. Session-authed.
      *
-     * UI copy note (spec §10.6): removing a device signs it out and forces a full
-     * re-approval, but it **does not take back the encryption key the device
-     * already holds**. Say so — users will assume otherwise.
+     * UI copy note (spec §10.6): removing a device forces a full re-approval next
+     * time, but be careful what you promise. It does NOT sign the device out —
+     * the server returns `session_revoked: false`, and that session runs until it
+     * expires — and it cannot take back the master seed the device already holds.
+     * Users assume "remove" means "locked out immediately"; it does not.
      */
     async listPairedDevices() {
         const res = await this.deviceApi("GET", "/api/auth/devices", undefined, true);
@@ -4740,7 +4768,15 @@ class HostedAuth {
             };
         });
     }
-    /** Remove a paired device and revoke its session. Session-authed. */
+    /**
+     * Un-pair a device. Session-authed.
+     *
+     * It stops being a "known" device, so pairing it again needs full approval
+     * with a fresh factor. It does NOT end that device's current session — the
+     * server reports `session_revoked: false` — and it cannot take back the
+     * master seed the device already holds. Do not write UI copy promising an
+     * immediate sign-out; users will assume it and be wrong.
+     */
     async revokePairedDevice(id) {
         if (!id)
             throw new DevicePairingError("error", { message: "revokePairedDevice: `id` is required." });
@@ -5136,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) {
@@ -5313,7 +5351,34 @@ class ZkAuth {
             return { user, unlocked: true };
         try {
             const factors = await this.listFactors();
-            if (factors.some((f) => f.type === "passkey")) {
+            // Only auto-attempt when a passkey is usable from THIS origin.
+            //
+            // Passkeys are per-origin, and an account's passkey may belong to a
+            // different host entirely (hosted-auth enrolment records
+            // `auth.muhkoo.dev`, so a user who added a passkey there is
+            // mismatched on every app host). Attempting anyway means
+            // `loginWithPasskey` does an unauthenticated vault read for a
+            // passkey this origin doesn't have. Today that returns a decoy with
+            // no `prfSalt`, so it fails the guard before touching WebAuthn — the
+            // silence is incidental. Once the decoy is reshaped to be
+            // indistinguishable (it must carry `prfSalt` to stop being an
+            // account-enumeration oracle) that same call would sail through and
+            // fire a modal `navigator.credentials.get()` at page load, on every
+            // boot, for a credential that does not exist. `resume()` is awaited
+            // inside every app's readiness gate, so that dialog lands on the
+            // splash screen before the user has asked for anything.
+            //
+            // `listFactors` is session-authenticated and returns real records,
+            // so decoys never appear here — this reads true rpIds.
+            //
+            // `passkeyUsableFromOrigin`, NOT `rpIdUsableForOrigin`: a factor
+            // with no recorded rpId predates per-origin enrolment and is still
+            // usable (`loginWithPasskey` resolves it as `params.rpId ?? host`).
+            // The raw predicate is false for undefined, so using it here would
+            // skip exactly those users — the regression that locked legacy
+            // passkey holders out of production twice.
+            const host = defaultRpId();
+            if (factors.some((f) => f.type === "passkey" && passkeyUsableFromOrigin(f.rpId, host))) {
                 await this.loginWithPasskey(user.username);
             }
         }
@@ -5400,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);
@@ -5428,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);
@@ -5456,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);
@@ -5474,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);
@@ -5555,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(),
         });
@@ -5584,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);
@@ -5663,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. */
@@ -5682,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.
@@ -5789,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));
     }
@@ -6129,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) {
@@ -6253,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;
+            }
         };
     }
     // -------------------------------------------------------------------------
@@ -8241,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;
@@ -8277,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,
     };
 }
@@ -8295,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);
 }
 
@@ -10815,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();
@@ -10823,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. */
@@ -11020,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)
@@ -11325,6 +11545,894 @@ 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. */
+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
+            // Our own writes echo back. Dropping the cache is cheap and keeping a
+            // stale entry is not, so this does not try to filter them out.
+            this.cache.clear();
+            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));
+    }
+    // ---- 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`. */
+    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 {
+            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;
+    }
+    async openDirById(id, key) {
+        const hit = this.cache.get(id);
+        if (hit)
+            return hit;
+        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() };
+        const open = { id, key, node };
+        this.cache.set(id, open);
+        return open;
+    }
+    /** 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, 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, 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);
+}
+
 /**
  * `ChatKeyVault` — SDK-owned lifecycle for a member's long-lived ratchet/space
  * keypair (the connect `KeyStore` entry keyed by the member id / username).
@@ -12543,6 +13651,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}. */
@@ -12564,6 +13674,8 @@ class Client {
     db;
     /** File storage — `client.storage.writeFile(...)`, etc. */
     storage;
+    /** Filesystem over the personal space: directories, versions, real paths. */
+    vfs;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     message;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
@@ -12663,6 +13775,94 @@ 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);
+                },
+            },
+        });
         // 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.
@@ -13601,5 +14801,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, 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_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$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, 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