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

package/dist/connect.d.ts

@@ -1897,7 +1897,7 @@ interface AuthSuccess {
 /** A vault factor record (M1.0 + M2 gated types). Wrap/iv are base64 AES-GCM; absent for phrase. */
 interface VaultFactor {
     id: string;
-    type: "password" | "passkey" | "phrase-marker" | "email" | "google";
+    type: "password" | "passkey" | "phrase-marker" | "email" | "google" | "device";
     wrap?: string;
     iv?: string;
     params?: Record<string, unknown>;
@@ -2009,7 +2009,9 @@ declare 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?: string): Promise<{
+    rpId?: string, 
+    /** Device factors are selected by id — a user may have many machines. */
+    factorId?: string): Promise<{
         factor: VaultFactor | null;
     }>;
     /**
@@ -2966,10 +2968,6 @@ interface ZkAuthDeps {
     circuits: CircuitUrls;
     session: SessionState;
 }
-/**
- * ZK identity auth. One instance per {@link Client}; reads/writes the shared
- * {@link SessionState}.
- */
 declare class ZkAuth {
     private readonly deps;
     constructor(deps: ZkAuthDeps);
@@ -3184,6 +3182,63 @@ declare class ZkAuth {
      * passwordless (passkey) login, both of which recover the same seed.
      */
     get seedBase64(): string | 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.
+     */
+    enrollDevice(label: string): Promise<{
+        factorId: string;
+        deviceKey: string;
+    }>;
+    /**
+     * 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".
+     */
+    unlockWithDevice(username: string, factorId: string, deviceKey: string): Promise<void>;
+    /** Paired machines, newest first. Metadata only — never the ciphertext. */
+    listDevices(): Promise<Array<{
+        id: string;
+        label?: string;
+        createdAt?: number;
+    }>>;
+    /** Withdraw a machine's access. Its stored key stops working immediately. */
+    revokeDevice(factorId: string): Promise<boolean>;
+    /**
+     * 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: string): void;
     /** Poseidon commitment for an identity — the value the server stores. */
     private commitmentFor;
     /**
@@ -3766,6 +3821,8 @@ interface StorageChangeEvent<T = unknown> {
 }
 declare class KvNamespace {
     private readonly deps;
+    /** One personal-space socket, shared by every subscriber. */
+    private feed;
     private cipher;
     private cipherIdentity;
     constructor(deps: KvNamespaceDeps);
@@ -3789,6 +3846,20 @@ declare class KvNamespace {
      * Requires a `WebSocket` global (browsers; Node 22+ or a `ws` shim).
      */
     on<T = unknown>(event: "change", handler: (e: StorageChangeEvent<T>) => void): () => void;
+    /**
+     * 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: (frame: unknown) => void): () => void;
     private dispatchChange;
     /** Decode a stored value: decrypt envelopes, pass plaintext through. */
     private decode;
@@ -4915,9 +4986,20 @@ declare 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.
+     */
     createSpace(opts?: {
         historyPolicy?: HistoryPolicy;
         private?: boolean;
+        messaging?: boolean;
     }): Promise<Space>;
     /** Join an existing space by id (its public key). Resolves once a key arrives. */
     joinSpace(spaceId: string, opts?: {
@@ -5379,6 +5461,318 @@ declare class AccessTokensNamespace {
     private path;
 }
 
+/**
+ * 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.
+ */
+
+/** What `stat` and `list` hand back — a path-addressed view of an entry. */
+interface VfsStat {
+    path: string;
+    name: string;
+    kind: "file" | "dir";
+    size: number;
+    mtime: number;
+    versions: number;
+}
+/** The personal-space blob store the VFS persists through. */
+interface VfsStore {
+    get(key: string): Promise<unknown | null>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Every key in the store — the personal space is shared, so this is NOT VFS-only. */
+    list(): Promise<string[]>;
+}
+
+/**
+ * `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.
+ */
+
+/**
+ * The slice of content storage the VFS needs.
+ *
+ * Narrow on purpose: the VFS knows how to name and arrange things, not how to
+ * shard them. The adapter in `Client` resolves the content space and calls
+ * `client.storage.writeFile` unchanged — the file still lands in a real Space
+ * with a real gated manifest, and the VFS just keeps the handle somewhere
+ * better than a flat mirror.
+ */
+interface VfsContentStore {
+    write(data: Uint8Array | Blob, meta: {
+        name: string;
+        type: string;
+    }): Promise<{
+        manifest: FileManifest;
+        size: number;
+    }>;
+    read(manifest: FileManifest): Promise<Uint8Array>;
+    /**
+     * Drop a reference to a manifest's shards.
+     *
+     * Shards are content-addressed and reference-counted, so deleting a file is
+     * not enough to reclaim the bytes — without this, every version ever
+     * written stays on disk and billed forever. Best-effort: a failure here
+     * leaks storage but must not block the delete.
+     */
+    release(manifest: FileManifest): Promise<void>;
+    /**
+     * Take an ADDITIONAL reference to shards that already exist.
+     *
+     * Needed when a manifest gains a second owner without new bytes being
+     * written — copying a file. Without it the copy holds a handle to shards
+     * with a refcount of one, and deleting the original frees the bytes out
+     * from under it.
+     */
+    retain(manifest: FileManifest): Promise<void>;
+}
+interface VfsNamespaceDeps {
+    store: VfsStore;
+    /**
+     * Subscribe to the personal space's raw change feed, if the runtime has one.
+     * Optional so the VFS works headlessly (a CLI, a test) with no socket.
+     */
+    subscribe?: (handler: (frame: unknown) => void) => () => void;
+    content: VfsContentStore;
+    /** The in-memory master seed, or null when locked. Read per call — it can change. */
+    seed: () => Uint8Array | null;
+    /** Versions retained per file. */
+    historyLimit?: number;
+}
+declare class VfsNamespace {
+    private readonly deps;
+    private rootKey;
+    /**
+     * 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.
+     */
+    private cache;
+    private readonly historyLimit;
+    constructor(deps: VfsNamespaceDeps);
+    /**
+     * 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 `..`.
+     */
+    private _cwd;
+    /** The current working directory. Always absolute. */
+    get cwd(): string;
+    /**
+     * 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".
+     */
+    cd(path: string): Promise<string>;
+    /** Resolve a path against the working directory. Absolute paths pass through. */
+    resolve(path: string): string;
+    /** True when the master seed is held, so the root key can be derived. */
+    get unlocked(): boolean;
+    /**
+     * 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(): void;
+    /**
+     * 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: () => void): () => void;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<VfsStat>;
+    /** Immediate children of a directory. One record fetch. */
+    list(path?: string): Promise<VfsStat[]>;
+    /**
+     * 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.
+     */
+    walk(path?: string): Promise<string[]>;
+    readFile(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
+    /**
+     * Create a directory. `recursive` creates missing parents and tolerates an
+     * existing target, matching `mkdir -p`.
+     */
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    writeFile(path: string, data: Uint8Array | string | Blob, opts?: {
+        type?: string;
+    }): Promise<VfsStat>;
+    /** Delete a file, or a directory when `recursive`. */
+    delete(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    rename(from: string, to: string): Promise<void>;
+    /**
+     * 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.
+     */
+    copy(from: string, to: string): Promise<VfsStat>;
+    /**
+     * 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.
+     */
+    glob(pattern: string, opts?: {
+        from?: string;
+    }): Promise<string[]>;
+    /**
+     * 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.
+     */
+    sweep(opts?: {
+        force?: boolean;
+    }): Promise<{
+        removed: string[];
+    }>;
+    /** Prior versions of a file, newest first. One record fetch. */
+    history(path: string): Promise<Array<{
+        size: number;
+        mtime: number;
+    }>>;
+    /**
+     * 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.
+     */
+    restore(path: string, index?: number): Promise<VfsStat>;
+    private expectFile;
+    /** Resolve a path to its entry, or null. Root has no entry of its own. */
+    private find;
+    private root;
+    /** Open a directory by path, creating nothing. Throws if it is missing. */
+    private openDir;
+    private openDirOrNull;
+    private openDirById;
+    /** Apply an edit to a directory record and persist it. */
+    private mutate;
+    private createDir;
+    /** Recursively remove a subtree's records. Best-effort: unreachable ≠ fatal. */
+    private purge;
+    /**
+     * 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.
+     */
+    private cloneEntry;
+    /**
+     * Let go of a file's bytes: the current manifest and every retained
+     * version, then the history record itself.
+     */
+    private releaseFile;
+    private readHistory;
+    /** Push `entry` onto its history record. Returns the new version count. */
+    private pushHistory;
+}
+
 /** The hosted Muhkoo Accelerator — the default {@link ClientOptions.baseUrl}. */
 declare const DEFAULT_BASE_URL = "https://api.muhkoo.dev";
 /** The hosted auth SPA — the default {@link ClientOptions.authBaseUrl}. */
@@ -5476,6 +5870,8 @@ declare class Client {
     readonly db: DbNamespace;
     /** File storage — `client.storage.writeFile(...)`, etc. */
     readonly storage: StorageNamespace;
+    /** Filesystem over the personal space: directories, versions, real paths. */
+    readonly vfs: VfsNamespace;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     readonly message: MessageNamespace;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */