@muhkoo/connect 0.2.0-alpha.1 → 0.2.0-alpha.2

package/README.md

@@ -1,12 +1,12 @@
 # @muhkoo/connect
 
 Client SDK for the Muhkoo Accelerator. The headline surface is a single
-**`Client`** that hangs everything off three namespaces —
-`client.auth` / `client.storage` / `client.message` — backed by
-end-to-end-encrypted messaging primitives (Double Ratchet + ECDH P-384), a
-turnkey multi-peer `BroadcastChannel`, ZK identity + personal/shared spaces,
-and a Cloudflare-Workers-compatible Groth16 verifier — all bundled from a
-single TypeScript source tree.
+**`Client`** that hangs everything off four namespaces —
+`client.auth` / `client.storage` / `client.message` / `client.space` — 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, and a Cloudflare-Workers-compatible Groth16 verifier — all bundled from
+a single TypeScript source tree.
 
 > Status: alpha. The library is consumed in tree by `../accelerator` and the
 > `../web` SPA.
@@ -140,20 +140,28 @@ await client.storage.delete("todos", "t1");
 const sub = client.message.subscribe("todos", (e) => console.log("update:", e.data));
 await client.message.publish("todos", { id: "t1", done: true });
 await client.message.send("user:abc", { text: "Hello!" });
+
+// Space — fan-out group channels with persisted history (group chat).
+const space = await client.space.joinChannel("project-x"); // or createChannel(...)
+space.onMessage((e) => console.log(e.from, e.message.body));
+await space.sendMessage("Hi everyone");
+const { messages } = await space.history({ limit: 100 });
 ```
 
-`subscribe(subject)` / `publish(subject, data)` are plaintext fan-out to
-everyone on that subject. `send("user:<id>", …)` is an **end-to-end-encrypted**
-direct message (Double Ratchet); the recipient receives it by subscribing to
-their *own* id — `client.message.subscribe("user:<me>", …)`. Both modes ride a
-shared-space room websocket under the hood (opened with a short-lived signed
-ticket); E2E delivery needs both parties online, like any ratchet.
-
-For full **group rooms** (multi-peer E2E chat + room-scoped file sharing), use
-`client.message.room(name)` — a shared-space handle exposing the group channel
-(`connect`/`on`/`send`/`announce`/`peers`/`sendRaw`) plus
-`putFile`/`getFile`. `subscribe`/`publish`/`send` are conveniences layered over
-this same room primitive.
+`client.message` is lightweight realtime: `subscribe`/`publish` are plaintext
+fan-out; `send("user:<id>", …)` is an **end-to-end-encrypted** direct message
+(Double Ratchet — forward-secret, ephemeral, no history; both parties must be
+online).
+
+`client.space` is **fan-out group messaging with history**. A channel seals each
+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 trusted, always-available member that re-issues the group
+key — so a channel is joinable even when no one else is online. The relay stays
+blind (it only ever sees opaque, ECIES-wrapped key blobs). The space handle was
+once `Room`; that name is still exported as an alias, and `client.message.room()`
+returns the same handle.
 
 Auth lifecycle:
 

package/dist/browser/index.js

@@ -5305,6 +5305,46 @@ async function importEcdhPublicKey(encoded) {
 }
 /** The space's id is just its encoded ECDH public key. */
 const encodeSpaceId = exportEcdhPublicKey;
+// ---------------------------------------------------------------------------
+// Sender authentication (ECDSA P-384, matching the Double Ratchet path).
+// A fan-out message is signed by its sender's identity ECDSA key so receivers
+// can verify authorship end-to-end — independent of the relay, which only
+// stamps `source` server-side. SHA-256 hash to match `DoubleRatchet`.
+// ---------------------------------------------------------------------------
+const ECDSA_PARAMS = { name: "ECDSA", namedCurve: "P-384" };
+const ECDSA_SIGN = { name: "ECDSA", hash: "SHA-256" };
+/** Encode an ECDSA public `CryptoKey` as a base64url JWK string. */
+async function exportEcdsaPublicKey(key) {
+    const jwk = await getSubtle().exportKey("jwk", key);
+    return toBase64Url(utf8Encode(JSON.stringify(jwk)));
+}
+/** Decode a base64url JWK string back into an ECDSA verify-only public key. */
+async function importEcdsaPublicKey(encoded) {
+    const jwk = JSON.parse(utf8Decode(fromBase64Url(encoded)));
+    return getSubtle().importKey("jwk", jwk, ECDSA_PARAMS, true, ["verify"]);
+}
+/**
+ * Canonical bytes a sender signs (and a receiver re-derives). Binds the claimed
+ * sender + routing + the sealed ciphertext, so a relay can't relabel `source`
+ * and a member can't reuse another's ciphertext under a new envelope.
+ */
+function canonicalMessage(fields) {
+    return [fields.source, fields.target, fields.subject, fields.epoch, fields.iv, fields.ciphertext].join("\n");
+}
+/** 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(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(sigB64), utf8Encode(canonical));
+    }
+    catch {
+        return false;
+    }
+}
 /** Generate a fresh space identity keypair (P-384 ECDH). */
 async function generateSpaceIdentity() {
     const kp = await getSubtle().generateKey(ECDH_PARAMS, true, ["deriveBits"]);
@@ -5533,12 +5573,19 @@ class Space {
         const cipher = this.requireCipher(opts.contentType);
         const message = new Message(payload);
         const headers = await cipher.seal(message.serialize());
-        const packet = new Packet({
-            subject: opts.channel ?? "default",
-            source: this.deps.myId(),
-            target: this.name,
-            headers,
-        });
+        const source = this.deps.myId();
+        const subject = opts.channel ?? "default";
+        // Sign the message with our identity ECDSA key so receivers can verify
+        // authorship end-to-end (independent of the relay's `source` stamp).
+        const authPriv = KeyStore.getInstance().getAuthKeyPair(source)?.privateKey;
+        if (authPriv) {
+            const canonical = canonicalMessage({
+                source, target: this.name, subject,
+                epoch: Number(headers.epoch), iv: String(headers.iv), ciphertext: String(headers.ciphertext),
+            });
+            headers.sig = await signSpaceMessage(canonical, authPriv);
+        }
+        const packet = new Packet({ subject, source, target: this.name, headers });
         this.sendRaw({ spaceMessage: packet.serialize() });
     }
     /** Subscribe to decrypted fan-out messages. Returns an unsubscribe fn. */
@@ -5570,6 +5617,9 @@ class Space {
         if (!res.ok)
             throw new Error(`Space.history: ${res.status} ${res.statusText}`);
         const body = (await res.json());
+        // Warm the member directory once so historical senders' signatures verify.
+        // (refreshDirectory swallows its own transport errors.)
+        await this.deps.keyring?.refreshDirectory();
         const messages = [];
         for (const raw of body.messages ?? []) {
             const decoded = await this.decodeFrame(raw, cipher);
@@ -5605,6 +5655,9 @@ class Space {
         const keyring = this.requireKeyring();
         await keyring.bootstrapNew();
         await this.connect();
+        // Publish our identity in the member directory so peers can verify our
+        // message signatures (the creator never "joins", so register here).
+        await keyring.requestKey().catch(() => { });
         // Admit anyone who requested a key before we were listening.
         if (this.deps.autoAdmit !== false) {
             await keyring.admitPending().catch(() => { });
@@ -5614,6 +5667,10 @@ class Space {
     async admit(memberId, identityEcdhPub) {
         await this.requireKeyring().admit(memberId, identityEcdhPub);
     }
+    /** Invite a user to this (private) channel's membership allowlist. */
+    async invite(username) {
+        await this.requireKeyring().invite(username);
+    }
     /** Rotate to a fresh epoch and re-wrap to the roster (rotate spaces). */
     async rotate(roster) {
         return this.requireKeyring().rotate(roster);
@@ -5656,7 +5713,9 @@ class Space {
         if (f.joinRequest && typeof f.joinRequest === "object") {
             const req = f.joinRequest;
             this.emitEvent("join-request", req);
-            // Auto-admit: if we hold the group key, wrap it for the newcomer.
+            // A new member appeared — refresh the directory so their future
+            // messages verify, and (if we hold the key) auto-admit them.
+            void this.deps.keyring?.refreshDirectory();
             if (this.deps.autoAdmit !== false && this.deps.keyring?.hasAnyKey() && req.memberId !== this.deps.myId()) {
                 void this.deps.keyring.admit(req.memberId, req.identityEcdhPub).catch(() => { });
             }
@@ -5684,6 +5743,13 @@ class Space {
             const packet = Packet.deserialize(packetJson);
             if (!cipher.handles(packet.headers))
                 return null;
+            // Verify sender authenticity end-to-end: the message must be signed
+            // by `source`'s identity ECDSA key (looked up in the member
+            // directory). Drop anything unsigned, signed by an unknown member,
+            // or whose signature doesn't match — this defeats both member
+            // impersonation and a relay rewriting `source`.
+            if (!(await this.verifySender(packet)))
+                return null;
             const serialized = await cipher.open(packet.headers);
             if (serialized === null)
                 return null; // epoch key we don't hold
@@ -5701,6 +5767,34 @@ class Space {
             return null;
         }
     }
+    /**
+     * True if `packet` carries a valid signature by `source`'s identity key.
+     * On a directory cache miss, refresh once (a new member may have just
+     * joined) before giving up. Without a keyring (legacy handle) there's
+     * nothing to verify against → reject.
+     */
+    async verifySender(packet) {
+        const keyring = this.deps.keyring;
+        const sig = packet.headers?.sig;
+        if (!keyring || typeof sig !== "string")
+            return false;
+        let key = keyring.ecdsaKeyFor(packet.source);
+        if (!key) {
+            await keyring.refreshDirectory();
+            key = keyring.ecdsaKeyFor(packet.source);
+            if (!key)
+                return false;
+        }
+        const canonical = canonicalMessage({
+            source: packet.source,
+            target: packet.target,
+            subject: packet.subject,
+            epoch: Number(packet.headers?.epoch ?? 0),
+            iv: String(packet.headers?.iv ?? ""),
+            ciphertext: String(packet.headers?.ciphertext ?? ""),
+        });
+        return verifySpaceMessage(canonical, sig, key);
+    }
     emitEvent(type, detail) {
         this.events.dispatchEvent(new CustomEvent(type, { detail }));
     }
@@ -5930,10 +6024,37 @@ class SpaceKeyring {
     keys = new Map();
     epoch = 0;
     policy;
+    /** Cached member directory: memberId → imported ECDSA verify key. */
+    memberEcdsa = new Map();
     constructor(deps) {
         this.deps = deps;
         this.policy = deps.historyPolicy ?? "static";
     }
+    // -- member directory (for verifying sender signatures) -------------------
+    /** The cached ECDSA verify key for a member, if known. */
+    ecdsaKeyFor(memberId) {
+        return this.memberEcdsa.get(memberId);
+    }
+    /** Refresh the member directory (memberId → ECDSA key) from the roster. */
+    async refreshDirectory() {
+        let roster;
+        try {
+            roster = await this.deps.transport.fetchRoster();
+        }
+        catch {
+            return;
+        }
+        for (const m of roster) {
+            if (!m.identityEcdsaPub || this.memberEcdsa.has(m.memberId))
+                continue;
+            try {
+                this.memberEcdsa.set(m.memberId, await importEcdsaPublicKey(m.identityEcdsaPub));
+            }
+            catch {
+                /* skip malformed entries */
+            }
+        }
+    }
     // -- EpochKeyProvider ------------------------------------------------------
     currentEpoch() {
         return this.epoch;
@@ -5987,11 +6108,16 @@ class SpaceKeyring {
         await this.persist();
     }
     // -- newcomer: request + pull ---------------------------------------------
-    /** Post a join request so an online key-holder can wrap a key for us. */
+    /**
+     * Post a join request so an online key-holder can wrap a key for us. Also
+     * publishes our identity keys in the member directory (so others can verify
+     * our message signatures, and the keeper can wrap to us).
+     */
     async requestKey(desiredEpoch) {
         await this.deps.transport.postJoinRequest({
             memberId: this.deps.memberId,
             identityEcdhPub: this.deps.identityEcdhPub,
+            identityEcdsaPub: this.deps.identityEcdsaPub,
             desiredEpoch,
         });
     }
@@ -6077,6 +6203,10 @@ class SpaceKeyring {
         await this.persist();
         return nextEpoch;
     }
+    /** Add `username` to a private channel's membership allowlist (member-only). */
+    async invite(username) {
+        await this.deps.transport.invite(username);
+    }
 }
 
 /**
@@ -6137,6 +6267,9 @@ class KeyringClient {
     async rotate(nextEpoch) {
         return this.post("/keyring/rotate", { nextEpoch });
     }
+    async invite(username) {
+        await this.post("/keyring/invite", { username });
+    }
     async fetchMetadata() {
         try {
             return await this.get("/metadata");
@@ -6193,7 +6326,9 @@ class SpaceNamespace {
         const historyPolicy = opts.historyPolicy ?? "static";
         const identity = await generateSpaceIdentity();
         // Register the space (server records pubkey + policy; the DO is lazy).
-        await this.deps.http.post(`/api/spaces/${encodeURIComponent(identity.id)}/metadata`, { spacePubKey: identity.id, historyPolicy });
+        // For a private space the server also records the creator (this user) as
+        // 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();
         return space;
@@ -6241,7 +6376,7 @@ class SpaceNamespace {
         const space = await this.createSpace(opts);
         // Register name → id first so a name clash doesn't leave an admitted keeper.
         try {
-            await this.deps.http.post("/api/app/channels", { name, spaceId: space.id });
+            await this.deps.http.post("/api/app/channels", { name, spaceId: space.id, visibility: opts.private ? "private" : "public" });
         }
         catch (err) {
             if (err instanceof HttpError && err.status === 409) {
@@ -6276,7 +6411,7 @@ class SpaceNamespace {
     // -------------------------------------------------------------------------
     async build(spaceId, historyPolicy) {
         const memberId = this.myId();
-        const identityEcdhPub = await this.ensureIdentity(memberId);
+        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
         const transport = new KeyringClient({
             spaceId,
             httpBaseUrl: this.deps.http.baseUrl,
@@ -6285,7 +6420,8 @@ class SpaceNamespace {
         const keyring = new SpaceKeyring({
             spaceId,
             memberId,
-            identityEcdhPub,
+            identityEcdhPub: ecdhPub,
+            identityEcdsaPub: ecdsaPub,
             ownPrivateKey: () => KeyStore.getInstance().getKeyPair(memberId)?.privateKey ?? null,
             transport,
             cache: this.deps.cache,
@@ -6302,14 +6438,15 @@ class SpaceNamespace {
             historyPolicy,
         });
     }
-    /** Ensure the member has an identity ECDH keypair; return its public key. */
+    /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
     async ensureIdentity(memberId) {
         const store = KeyStore.getInstance();
         if (!store.getKeyPair(memberId)) {
             await store.generateOwnKeyPair(memberId);
         }
-        const pub = store.getKeyPair(memberId).publicKey;
-        return exportEcdhPublicKey(pub);
+        const ecdhPub = await exportEcdhPublicKey(store.getKeyPair(memberId).publicKey);
+        const ecdsaPub = await exportEcdsaPublicKey(store.getAuthKeyPair(memberId).publicKey);
+        return { ecdhPub, ecdsaPub };
     }
     async fetchPolicy(spaceId) {
         const meta = await new KeyringClient({