@muhkoo/connect 0.14.0-alpha.5 → 0.14.0-alpha.7

package/README.md

@@ -2,9 +2,9 @@
 
 Client SDK for the Muhkoo Accelerator. The headline surface is a single
 **`Client`** that hangs everything off its namespaces —
-`client.auth` / `client.kv` / `client.db` / `client.storage` /
-`client.message` / `client.space` / `client.agents` / `client.functions` —
-backed by
+`client.auth` / `client.kv` / `client.db` / `client.storage` / `client.vfs` /
+`client.vcs` / `client.message` / `client.space` / `client.agents` /
+`client.functions` / `client.accessTokens` / `client.offline` — backed by
 end-to-end-encrypted messaging (fan-out group channels with history, plus Double
 Ratchet + ECDH P-384 for direct messages), ZK identity + personal/shared spaces,
 server-side Programmable Agents, developer-authored serverless functions, and an
@@ -21,10 +21,12 @@ See [`CHANGELOG.md`](./CHANGELOG.md) for what's new.
 - **`Client`** — the unified entry point. `new Client({ apiKey, baseUrl })`
   exposes, over one shared session: `auth` (ZK register/login), `kv` (per-user
   encrypted key/value), `db` (the app's scalable database), `storage` (encrypted
-  files), `message` (pub/sub + E2E direct messages), `space` (fan-out group
-  channels with history), `agents` (server-side Programmable Agents), and
-  `functions` (developer-authored serverless functions). This is the supported
-  surface; everything below is a building block it composes.
+  files), `vfs` + `vcs` (the encrypted filesystem and its history), `message`
+  (pub/sub + E2E direct messages), `space` (fan-out group channels with
+  history), `agents` (server-side Programmable Agents), `functions`
+  (developer-authored serverless functions), `accessTokens` (scoped machine
+  credentials), and `offline` (CRDT sync). This is the supported surface;
+  everything below is a building block it composes.
 
 - **App-describing decorators** — `@MuhkooAgent` / `@MuhkooSpace` / `@MuhkooDB` /
   `@MuhkooFunction` annotate a plain class with your app's agent-facing surface;
@@ -46,11 +48,26 @@ See [`CHANGELOG.md`](./CHANGELOG.md) for what's new.
 - **`PersonalSpaceClient`** — HTTP client for the accelerator's
   `/api/personal/:commitment/*` ZK-gated KV API. Generates a fresh Groth16
   proof per request using snarkjs and the `preimagePoK` circuit.
+- **`FileStorage` + `ShardClient`** — the chunked AES-256-GCM + Reed–Solomon
+  layer under `client.storage`. A read fetches only the **data** shards and
+  reaches for parity solely when one is actually missing: RS needs `dataShards`
+  of `dataShards + parityShards`, so pulling all of them and discarding the
+  parity cost six round trips where four would do. Concurrent shard reads then
+  **coalesce** into a single `POST /api/shards/batch`, which is what stops a
+  project costing one request per shard — a shard is not a file, and a project is
+  thousands of small modules. Callers are unchanged (`getShard` still asks for
+  one shard); `batchShards: false` forces one-at-a-time, and a deployment without
+  the route is detected and permanently degraded to it. Read concurrency was
+  raised to match, because batching with too few reads in flight trades
+  parallelism for round trips and is worse than not batching at all. Opening the
+  same 519-file project in the Muhkoo IDE went from 2,086 requests to 22: 18.4s →
+  8.8s in Chromium, 37.5s → 14.9s in Brave, which filters every request and so
+  paid the round-trip cost hardest.
 - **`wrapWithPassphrase` / `unwrapWithPassphrase`** — PBKDF2-SHA256 (200k
   iterations) + AES-256-GCM passphrase wrap. Pairs naturally with
   `PersonalSpaceClient` for client-side payload encryption.
 - **`verifyGroth16` / `initBn128Wasm`** — universal Groth16 verifier driven by
-  bn128.wasm. Runs anywhere WebAssembly does (Node, browsers, CF Workers).
+  bn128.wasm. Runs anywhere WebAssembly does (Node, browsers, edge runtimes).
   Used by the accelerator's `verifyZkAuthProof`.
 - ZK building blocks re-exported from `crypto/ZeroKnowledge` (`Field`,
   `Poseidon`, `PreimagePoK`, `HashKnowledge`, `AuthPublicInput`,
@@ -72,7 +89,7 @@ the `exports` field in `package.json`:
 
 The `workers` build deliberately excludes anything that pulls in
 `snarkjs` / `ffjavascript` transitive deps (which need `URL.createObjectURL`
-and other APIs workerd doesn't expose):
+and other APIs edge runtimes don't expose):
 
 - `ZeroKnowledge.ts` — `Field`, `Poseidon`, `PreimagePoK`, `verifyPreimagePoK`,
   etc.
@@ -88,8 +105,8 @@ The `workers` build keeps `KeyStore`, `DoubleRatchet`, `EncryptedSession`,
 Types in `dist/connect.d.ts` (bundled from the flat `src/browser/index.ts`
 entry) include everything from all three runtimes so consumers can reference
 types even when the runtime impl is absent for their target. Calling
-`verifyGroth16` / `initBn128Wasm` works under workerd; importing
-`PersonalSpaceClient` and calling it in a worker will fail at runtime.
+`verifyGroth16` / `initBn128Wasm` works in the `workers` build; importing
+`PersonalSpaceClient` and calling it there will fail at runtime.
 
 ### Bare specifiers and snarkjs
 
@@ -101,10 +118,17 @@ chat app provides `snarkjs` via an esm.sh import map; Node consumers add
 ## Installation
 
 ```bash
-npm install @muhkoo/connect
-# or: yarn add @muhkoo/connect / pnpm add @muhkoo/connect
+npm install @muhkoo/connect@alpha
+# or: yarn add @muhkoo/connect@alpha / pnpm add @muhkoo/connect@alpha
 ```
 
+Ask for the **`alpha`** tag explicitly. `latest` still points at the older
+`0.13.2-alpha.0` line, so a bare `npm install @muhkoo/connect` installs a build
+without the surface documented here. Two published builds are deprecated and
+should not be pinned: `0.14.0-alpha.0` (reports the wrong version at runtime)
+and `0.14.0-alpha.3` (shipped with no type declarations, so every SDK type
+resolves to `any`).
+
 ESM-only, with bundled type declarations. `snarkjs` is an **optional peer
 dependency** — install it only if you use the ZK-proof features
 (`PersonalSpaceClient`, shared-space writes, client-side proof generation):
@@ -117,8 +141,8 @@ npm install snarkjs
 
 ### The unified client (recommended)
 
-`Client` is the supported entry point. One object, one app key, three
-namespaces — `auth`, `storage`, `message` — all sharing a single session.
+`Client` is the supported entry point. One object, one app key, and every
+namespace sharing a single session.
 
 ```typescript
 import { Client } from "@muhkoo/connect";
@@ -146,8 +170,8 @@ const user = await client.auth.zk.login("alice", "correct horse battery staple")
 // the server stores only ciphertext.
 await client.kv.set("todos", "t1", { title: "Buy groceries", completed: false });
 const todo = await client.kv.get("todos", "t1");
-const ids  = await client.storage.list("todos");
-await client.storage.delete("todos", "t1");
+const ids  = await client.kv.list("todos");
+await client.kv.delete("todos", "t1");
 
 // Message — realtime pub/sub + end-to-end-encrypted direct messages.
 const sub = client.message.subscribe("todos", (e) => console.log("update:", e.data));
@@ -170,7 +194,7 @@ online).
 message once with a shared group key so the server can persist + replay it.
 `createChannel(name)` mints + registers a channel (you become its first
 key-holder); `joinChannel(name)` resolves an existing one and is admitted by the
-app's **keeper** — a server-side process (the app's Durable Object) that holds
+app's **keeper** — a server-side process the platform runs per app, which holds
 the channel's group key and re-issues it to newcomers — so a channel is joinable
 even when no human member is online. The message **relay** stays blind (it only
 ever sees opaque, ECIES-wrapped key blobs); the **keeper** does hold group keys,
@@ -281,6 +305,97 @@ call. Persist the token across reloads with a custom `sessionStore` (e.g. a
 `localStorage`-backed one); identity material is never persisted — `unlock()`
 re-derives it from the password when you need to decrypt or message.
 
+### Staying signed in — the `device` factor
+
+The master seed is memory-only by design, which is what makes a forgotten
+password unrecoverable and a stolen disk uninteresting. It also means a page
+reload leaves the client holding a valid session and nothing to decrypt with,
+and it means a CLI runs a full ZK login — circuit download and proof — on every
+invocation. Persisting the seed would fix both and give away the whole property.
+
+A `device` factor is the middle path. A random key is generated locally, the
+seed is wrapped under it, and **only the ciphertext goes to the vault**. The key
+never leaves the machine that made it, and the server holds a blob it cannot
+open. Revoking the factor makes that local key inert immediately — which a
+stored seed can never be, because nothing can reach out and un-store it.
+
+```typescript
+// Pair once, while signed in. Store `deviceKey` with the tightest permissions
+// available: for as long as the factor exists it is equivalent to the seed.
+const { factorId, deviceKey } = await client.auth.zk.enrollDevice("Matt's laptop");
+
+// Later, with no password typed: recovers the seed AND a session.
+const user = await client.auth.zk.loginWithDevice(username, factorId, deviceKey);
+//    └ { username, commitment }
+
+// Seed only — for a host that already holds a session token on disk.
+await client.auth.zk.unlockWithDevice(username, factorId, deviceKey);
+
+await client.auth.zk.listDevices();           // [{ id, label, createdAt }], newest first
+await client.auth.zk.revokeDevice(factorId);  // access withdrawn immediately
+```
+
+The two recovery methods are not interchangeable. `unlockWithDevice` establishes
+the **encryption identity only**, which suits a CLI that already has a session
+token on disk. A browser generally does not: its session expires while the
+pairing is still perfectly valid, leaving it able to decrypt everything and
+unable to make an authenticated call. `loginWithDevice` derives the ZK identity
+from the recovered seed and proves it, exactly as `recoverWithPhrase` does — the
+seed has always been sufficient to authenticate, and withholding that only meant
+re-typing a password to prove something already known.
+
+A revoked pairing throws **`DeviceRevokedError`**, exported from the package
+root. It is typed because the correct response is specific and the wrong one is
+harmful: discard the stored key and fall back to a password. Retrying cannot
+succeed — the factor is gone from the vault — and silently re-pairing would undo
+a revocation someone performed on purpose. A *wrong* key is distinguishable: it
+fails to decrypt rather than failing to resolve.
+
+```typescript
+import { DeviceRevokedError } from "@muhkoo/connect";
+
+try {
+  await client.auth.zk.loginWithDevice(username, factorId, deviceKey);
+} catch (err) {
+  if (err instanceof DeviceRevokedError) {
+    forgetStoredKey();     // never re-pair on the user's behalf
+    showPasswordForm();
+  } else throw err;
+}
+```
+
+### Hosted sign-in (`client.auth.hosted`)
+
+`client.auth.hosted` sends the browser to Muhkoo's own sign-in page (PKCE
+authorization code in, session + seed out), so an app never handles a password
+and gets passkeys, Google and recovery for free. `redirectUri` must be
+registered for the app in the portal.
+
+```typescript
+await client.auth.hosted.login({ appId, redirectUri: "https://yourapp.com/callback" });
+// …on the callback route:
+if (client.auth.hosted.isCallback()) {
+  const user = await client.auth.hosted.handleCallback();
+}
+```
+
+A viewer who ticked *"Keep me signed in on this browser"* has a `device` factor
+on the auth origin, so the hosted page can complete the flow without asking for
+anything. That is the behaviour an app must be able to switch off at exactly one
+moment — its own sign-out. Without `prompt`, clicking "sign in" straight after
+signing out would resume the remembered pairing and look like the sign-out did
+nothing:
+
+```typescript
+await client.auth.hosted.login({ appId, redirectUri, prompt: "login" });
+// forces the credential screen even on a remembered browser
+```
+
+The name is borrowed from the OIDC parameter that solves the same problem. Note
+that the remembered pairing lives on the auth origin only: `localStorage` is
+per-origin, so sharing a registrable domain buys an app nothing here, and the
+key that opens the seed is never handed to a developer app.
+
 > The sections below document the lower-level building blocks the client is
 > composed from (`BroadcastChannel`, `EncryptedSession`, `PersonalSpaceClient`,
 > the Groth16 verifier, …). Reach for them directly only when you need control
@@ -392,7 +507,7 @@ const ok = await verifyGroth16(
 );
 ```
 
-Initialize once at boot. For CF Workers, pass a pre-compiled
+Initialize once at boot. On an edge runtime, pass a pre-compiled
 `WebAssembly.Module` to skip runtime compilation:
 `await initBn128Wasm(myWasmModule)`.
 
@@ -424,15 +539,20 @@ src/
   browser/        rollup entrypoint for the browser build
   server/         rollup entrypoint for the server / default build
   workers/        rollup entrypoint for the workers build (+ groth16-verifier + bundled bn128.wasm)
+  core/           the unified Client: Client, HttpClient, Session, namespaces/
+  auth/           ZK identity derivation, AuthClient, device/passkey stores
+  spaces/         Space, SpaceCipher, SpaceKeyring (fan-out group encryption)
   crypto/         KeyStore, DoubleRatchet, DoubleRatchetManager, Authenticator, ZeroKnowledge
   sessions/       EncryptedSession, BroadcastChannel
   transport/      WSTransport
   personal/       PersonalSpaceClient + wrap.ts (excluded from workers build)
+  storage/        FileStorage, ShardClient, SharedSpaceClient, Reed-Solomon codec
+  vfs/  vcs/      the encrypted filesystem and its history (client.vfs / client.vcs)
+  offline/  p2p/  CRDT offline sync; WebRTC peer shard exchange
   events/         EventCore + EventCoreEvents
   messaging/      Message, Packet, decorators
   types/          shared type defs (incl. zk.ts with PREIMAGE_POK_VERIFICATION_KEY)
   network/        legacy Network class (not exported from any build)
-  storage/        Reed-Solomon Storage (not exported from any build)
   utilities/      Logger, base58, ID generation, decorators
 ```
 
@@ -458,10 +578,10 @@ yarn lint               # eslint ./src
 - Node >= 20
 - All three builds rely on globalThis-level WebCrypto (`crypto.subtle`,
   `crypto.getRandomValues`), available natively in modern browsers, Node 16+,
-  Bun, Deno, and CF Workers.
+  Bun, Deno, and edge runtimes.
 - The bn128.wasm verifier needs runtime `WebAssembly.compile()` available
-  (true for all of the above; on CF Workers, pre-compile via wrangler's
-  `.wasm` import if you want to skip startup cost).
+  (true for all of the above; on an edge runtime, hand in a module compiled at
+  build time if you want to skip the startup cost).
 
 ## License
 

package/dist/browser/index.js

@@ -4242,11 +4242,24 @@ class FileStorage {
         this.chunkSize = opts.chunkSize ?? 4 * 1024 * 1024;
         this.dataShards = opts.dataShards ?? 4;
         this.parityShards = opts.parityShards ?? 2;
-        // Shard reads coalesce into batches, so this is no longer a cap on
-        // requests — it is how many hashes are available to batch together. Too
-        // low and each batch is small and serial, which is strictly worse than
-        // not batching at all.
-        this.concurrency = Math.max(1, opts.concurrency ?? 16);
+        // Shard reads coalesce into batches, so this is not a cap on requests —
+        // it is how many hashes are available to batch together.
+        //
+        // 8 because nothing measurable argues for more.
+        //
+        // Raising it to 16 (walk at 24) looked 23% slower over three runs each,
+        // and reverting looked like it restored the win — until a third set of
+        // three landed on the same numbers as the RAISED setting. Pooled, the
+        // configurations are indistinguishable: the run-to-run spread on a
+        // 519-file project is 13.9-20.9s, far wider than any difference between
+        // them. Three samples could not have resolved it and should not have
+        // been trusted to.
+        //
+        // What IS established is the floor: too low and each batch is small and
+        // serial, which is worse than not batching at all. Above that the setting
+        // stops mattering at this scale, so it stays at the simpler value. Moving
+        // it needs a sample large enough to see past that spread.
+        this.concurrency = Math.max(1, opts.concurrency ?? 8);
         this.rsWasmModule = opts.rsWasmModule;
         if (this.chunkSize < 1)
             throw new Error("FileStorage: chunkSize must be >= 1 byte");
@@ -5500,7 +5513,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.14.0-alpha.5";
+const VERSION = "0.14.0-alpha.7";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -12421,10 +12434,13 @@ const MAX_DEPTH = 64;
  * project does not open a request per directory. Browsers cap concurrency per
  * origin anyway, so a larger number mostly moves the queue.
  */
-/** Directory records fetched in parallel while walking. Raised alongside the
- *  shard read concurrency: the walk is what discovers the files whose shards
- *  then batch together, so a narrow walk throttles everything downstream. */
-const WALK_CONCURRENCY = 24;
+/** Directory records fetched in parallel while walking.
+ *
+ *  Kept at 8 alongside the shard read concurrency. Raising both to 24/16 was
+ *  neither better nor worse once enough samples were taken — the spread between
+ *  runs is wider than the difference between the settings — so this stays at the
+ *  simpler value. See FileStorage's note. */
+const WALK_CONCURRENCY = 8;
 /**
  * `Promise.all` with a ceiling, preserving input order.
  *