sietch 0.8.0 → 0.9.0

package/dist/sync-engine.js

@@ -27,7 +27,7 @@ import * as encoding from 'lib0/encoding';
 import * as decoding from 'lib0/decoding';
 import { messageYjsSyncStep1, messageYjsSyncStep2, messageYjsUpdate, writeSyncStep1, } from 'y-protocols/sync';
 import { keyExchangeInitiate, keyExchangeRespond, } from './crypto.js';
-import { SyncError, PeerConnectionError } from './errors.js';
+import { SyncError, PeerConnectionError, HandshakeRejectedError } from './errors.js';
 // ── Protocol Constants ─────────────────────────────────────
 const SYNC_PROTOCOL = '/sietch/sync/1.0.0';
 const AUTH_PROTOCOL = '/sietch/auth/1.0.0';
@@ -251,6 +251,18 @@ export class SyncEngine {
     denialTrackers = new Map();
     /** Per-peer escalating ban state: tracks disconnect count and cooldown expiry. */
     aclBanState = new Map();
+    /**
+     * Optional server-side application authorization hook, invoked during
+     * PQ auth handshake after key exchange completes and before the peer
+     * is admitted to sync. See AMD-002 / FR-67.
+     */
+    onPeerHandshake = undefined;
+    /**
+     * Optional client-side factory that produces the `handshakeMetadata`
+     * trailer for outgoing auth frames. Called once per handshake
+     * (including reconnects). See AMD-002 / FR-67.
+     */
+    handshakeMetadataProvider = undefined;
     constructor(yjsEngine, identity, acl, obs) {
         this.yjsEngine = yjsEngine;
         this.identity = identity;
@@ -269,6 +281,27 @@ export class SyncEngine {
     registerQueryHandler(handler) {
         this.queryHandler = handler;
     }
+    /**
+     * Install a server-side application authorization hook. Called during
+     * PQ auth handshake; see {@link HandshakeHook}. Typically set by
+     * `SietchServer` from the `onPeerHandshake` option.
+     *
+     * @req FR-67
+     */
+    setOnPeerHandshake(hook) {
+        this.onPeerHandshake = hook;
+    }
+    /**
+     * Install a client-side factory that produces opaque application
+     * metadata for the auth handshake trailer. Called once per handshake,
+     * including on reconnect (so the factory may refresh short-lived
+     * tokens). See AMD-002.
+     *
+     * @req FR-67
+     */
+    setHandshakeMetadataProvider(provider) {
+        this.handshakeMetadataProvider = provider;
+    }
     /**
      * Initialize the libp2p node.
      */
@@ -406,12 +439,21 @@ export class SyncEngine {
     }
     /**
      * Connect to a server peer (WebSocket or TCP).
+     *
+     * If `opts.handshakeMetadata` is provided, it is installed as the
+     * per-handshake factory for the client-side auth trailer. Subsequent
+     * reconnects also invoke the factory (so it may refresh short-lived
+     * tokens). See AMD-002 / FR-67.
      */
     // @req FR-40
     // @req FR-33
-    async connectServer(url) {
+    // @req FR-67
+    async connectServer(url, opts) {
         if (!this.node)
             throw new SyncError('Sync engine not initialized', 'SYNC_NOT_INIT');
+        if (opts?.handshakeMetadata) {
+            this.setHandshakeMetadataProvider(opts.handshakeMetadata);
+        }
         try {
             const ma = multiaddr(url);
             const conn = await this.node.dial(ma);
@@ -432,6 +474,11 @@ export class SyncEngine {
             this.obs.events.emit('sync', this.getStatus());
         }
         catch (err) {
+            // Preserve HandshakeRejectedError identity so callers can distinguish
+            // app-level rejection from generic connection failure.
+            if (err instanceof HandshakeRejectedError) {
+                throw err;
+            }
             throw new PeerConnectionError(`Failed to connect to server: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
@@ -933,8 +980,14 @@ export class SyncEngine {
                         case messageYjsSyncStep2:
                         case messageYjsSyncStep2V2: {
                             const update = decoding.readVarUint8Array(decoder);
-                            // ACL write gate
+                            // ACL read gate for SyncStep2 (protocol handshake).
+                            // SyncStep2 is a mandatory Yjs sync response, not an application
+                            // write. Gate on read permission so read-only peers complete the
+                            // handshake. Update content is only applied when the peer also
+                            // has write permission — read-only peers' payloads are silently
+                            // dropped to prevent state contamination.
                             // @req FR-36
+                            let applyUpdate = true;
                             if (this.acl.hasAcl(subtreeId)) {
                                 const identityId = peer.identityPeerId;
                                 if (!identityId) {
@@ -943,27 +996,36 @@ export class SyncEngine {
                                         return;
                                     break;
                                 }
-                                const check = this.acl.checkWrite(subtreeId, identityId);
-                                if (!check.allowed) {
-                                    this.obs.logger.warn({ subtreeId, peerId, identityId }, 'SyncStep2 rejected: write denied');
+                                const readCheck = this.acl.checkRead(subtreeId, identityId);
+                                if (!readCheck.allowed) {
+                                    this.obs.logger.warn({ subtreeId, peerId, identityId }, 'SyncStep2 rejected: read denied');
                                     if (await this.handleAclDenial(peerId, subtreeId, framedStream))
                                         return;
                                     break;
                                 }
+                                const writeCheck = this.acl.checkWrite(subtreeId, identityId);
+                                if (!writeCheck.allowed) {
+                                    // Read-only peer: accept the handshake message but do not
+                                    // apply its update content to the server's Y.Doc.
+                                    applyUpdate = false;
+                                    this.obs.logger.debug({ subtreeId, peerId, identityId }, 'SyncStep2 accepted from read-only peer (update content dropped)');
+                                }
                             }
                             peer.syncedSubtrees.add(subtreeId);
-                            try {
-                                if (msgType === messageYjsSyncStep2V2) {
-                                    await this.yjsEngine.applyUpdateV2(subtreeId, update, peerId);
+                            if (applyUpdate) {
+                                try {
+                                    if (msgType === messageYjsSyncStep2V2) {
+                                        await this.yjsEngine.applyUpdateV2(subtreeId, update, peerId);
+                                    }
+                                    else {
+                                        await this.yjsEngine.applyUpdate(subtreeId, update, peerId);
+                                    }
                                 }
-                                else {
-                                    await this.yjsEngine.applyUpdate(subtreeId, update, peerId);
+                                catch (updateErr) {
+                                    this.obs.logger.warn({ subtreeId, peerId, size: update.byteLength, err: updateErr }, 'failed to apply SyncStep2 (malformed Yjs data)');
+                                    break;
                                 }
                             }
-                            catch (updateErr) {
-                                this.obs.logger.warn({ subtreeId, peerId, size: update.byteLength, err: updateErr }, 'failed to apply SyncStep2 (malformed Yjs data)');
-                                break;
-                            }
                             // Emit per-subtree sync status: SyncStep2 received → 'synced'
                             this.emitSubtreeStatus({
                                 subtreeId,
@@ -981,8 +1043,15 @@ export class SyncEngine {
                         case messageYjsUpdate:
                         case messageYjsUpdateV2: {
                             const update = decoding.readVarUint8Array(decoder);
-                            // ACL write gate
+                            // ACL gate (symmetric with SyncStep2 — see AMD-001).
+                            // Read-capable peers without write permission complete the
+                            // frame exchange with their payload silently dropped. They
+                            // do NOT count toward the ACL denial threshold. This matches
+                            // the SyncStep2 rule and closes the first-connect race where
+                            // a peer's pendingOps flush would otherwise trip the ban
+                            // counter before an out-of-band grant lands.
                             // @req FR-36
+                            let applyUpdate = true;
                             if (this.acl.hasAcl(subtreeId)) {
                                 const identityId = peer.identityPeerId;
                                 if (!identityId) {
@@ -991,15 +1060,27 @@ export class SyncEngine {
                                         return;
                                     break;
                                 }
-                                const check = this.acl.checkWrite(subtreeId, identityId);
-                                if (!check.allowed) {
-                                    this.obs.logger.warn({ subtreeId, peerId, identityId }, 'update rejected: write denied');
+                                const readCheck = this.acl.checkRead(subtreeId, identityId);
+                                if (!readCheck.allowed) {
+                                    this.obs.logger.warn({ subtreeId, peerId, identityId }, 'update rejected: read denied');
                                     if (await this.handleAclDenial(peerId, subtreeId, framedStream))
                                         return;
                                     break;
                                 }
+                                const writeCheck = this.acl.checkWrite(subtreeId, identityId);
+                                if (!writeCheck.allowed) {
+                                    // Read-only peer: accept the frame (mark synced) but drop
+                                    // the payload without applying or relaying.
+                                    applyUpdate = false;
+                                    this.obs.logger.info({ subtreeId, peerId, identityId, size: update.byteLength }, 'update dropped from read-only peer (no write permission)');
+                                }
                             }
                             peer.syncedSubtrees.add(subtreeId);
+                            if (!applyUpdate) {
+                                // Read-only peer: do not apply, do not relay. Fall through
+                                // to next frame.
+                                break;
+                            }
                             try {
                                 if (msgType === messageYjsUpdateV2) {
                                     await this.yjsEngine.applyUpdateV2(subtreeId, update, peerId);
@@ -1138,11 +1219,22 @@ export class SyncEngine {
             const remoteMlKem = new Uint8Array(data.subarray(mlKemStart, mlKemStart + ML_KEM_768_PUB_SIZE));
             // Parse optional identity peerId (backward-compatible extension)
             let remoteIdentityPeerId;
-            const idOffset = mlKemStart + ML_KEM_768_PUB_SIZE;
-            if (data.length > idOffset) {
-                const idLen = data[idOffset];
-                if (data.length >= idOffset + 1 + idLen) {
-                    remoteIdentityPeerId = new TextDecoder().decode(data.subarray(idOffset + 1, idOffset + 1 + idLen));
+            let cursor = mlKemStart + ML_KEM_768_PUB_SIZE;
+            if (data.length > cursor) {
+                const idLen = data[cursor];
+                if (data.length >= cursor + 1 + idLen) {
+                    remoteIdentityPeerId = new TextDecoder().decode(data.subarray(cursor + 1, cursor + 1 + idLen));
+                    cursor = cursor + 1 + idLen;
+                }
+            }
+            // Parse optional handshakeMetadata trailer (AMD-002 / FR-67).
+            // Backward-compatible: older clients omit this; parser stops at
+            // end-of-frame. Format: [handshakeMetaLen(2 BE)][handshakeMeta].
+            let remoteHandshakeMeta = new Uint8Array(0);
+            if (data.length >= cursor + 2) {
+                const metaLen = (data[cursor] << 8) | data[cursor + 1];
+                if (data.length >= cursor + 2 + metaLen) {
+                    remoteHandshakeMeta = new Uint8Array(data.subarray(cursor + 2, cursor + 2 + metaLen));
                 }
             }
             // Store identity BEFORE PQ exchange — survives even if PQ throws
@@ -1159,7 +1251,34 @@ export class SyncEngine {
             };
             const keypair = this.identity.getKeypair();
             const { shared, encapsulated } = keyExchangeInitiate(keypair.kem, remotePublicKey);
-            // PQ exchange succeeded — store shared secret
+            // Application authorization hook (AMD-002 / FR-67). Invoked after
+            // key exchange succeeds and BEFORE the peer is marked authenticated.
+            // Rejection closes the connection with a type=3 AppRejected frame
+            // and leaves `authenticated = false`. `aclBanState` is NOT touched —
+            // handshake rejection is distinct from per-peer ACL denial escalation.
+            if (this.onPeerHandshake && senderPeerId) {
+                try {
+                    const decision = await this.onPeerHandshake({
+                        peerId: senderPeerId,
+                        identityPeerId: remoteIdentityPeerId,
+                        handshakeMetadata: remoteHandshakeMeta,
+                    });
+                    if (decision && decision.accept === false) {
+                        const reason = decision.reason ?? 'application rejected handshake';
+                        this.obs.logger.warn({ peerId: senderPeerId, identityPeerId: remoteIdentityPeerId, reason }, 'PQ auth rejected by onPeerHandshake');
+                        this.sendAuthRejection(s, reason);
+                        return;
+                    }
+                }
+                catch (hookErr) {
+                    const reason = hookErr instanceof Error ? hookErr.message : String(hookErr);
+                    this.obs.logger.warn({ peerId: senderPeerId, identityPeerId: remoteIdentityPeerId, err: hookErr }, 'PQ auth rejected: onPeerHandshake threw');
+                    this.sendAuthRejection(s, reason);
+                    return;
+                }
+            }
+            // PQ exchange succeeded and hook (if any) admitted the peer —
+            // store shared secret and mark authenticated.
             if (senderPeerId) {
                 const peer = this.peers.get(senderPeerId);
                 if (peer) {
@@ -1208,6 +1327,33 @@ export class SyncEngine {
             }
         }
     }
+    /**
+     * Send a type=3 AppRejected auth response and close the stream.
+     *
+     * Wire format: `[type=3] [reasonLen(2 BE)] [reason_utf8]`.
+     *
+     * Distinct from type=2 (success) and from PQ key-exchange failure
+     * (which uses the error path of `handleAuthStream`). Only `onPeerHandshake`
+     * rejection or throw reaches this path. Does not touch `aclBanState`.
+     *
+     * @req FR-67
+     */
+    sendAuthRejection(s, reason) {
+        try {
+            const reasonBytes = new TextEncoder().encode(reason);
+            const reasonLen = Math.min(reasonBytes.length, 0xffff);
+            const frame = new Uint8Array(1 + 2 + reasonLen);
+            frame[0] = 3; // type: application rejected
+            frame[1] = (reasonLen >> 8) & 0xff;
+            frame[2] = reasonLen & 0xff;
+            frame.set(reasonBytes.subarray(0, reasonLen), 3);
+            s.sendData(new Uint8ArrayList(frame));
+            s.sendCloseWrite();
+        }
+        catch {
+            /* stream may already be broken */
+        }
+    }
     // ── Sync Operations ───────────────────────────────────────
     /**
      * Perform PQ auth handshake with a peer.
@@ -1240,18 +1386,47 @@ export class SyncEngine {
                 ownPeerIdBytes = new TextEncoder().encode(this.identity.getPublicIdentity().peerId);
             }
             catch { /* identity not initialized — skip */ }
-            const msgLen = 1 + 2 + x25519Pub.length + mlKemPub.length
-                + (ownPeerIdBytes.length > 0 ? 1 + ownPeerIdBytes.length : 0);
+            // Optional handshakeMetadata trailer (AMD-002 / FR-67). Called per
+            // handshake so short-lived tokens can be refreshed on reconnect.
+            // Copy into a fresh ArrayBuffer-backed Uint8Array so downstream
+            // wire-format code sees a stable, non-shared buffer type.
+            let handshakeMeta = new Uint8Array(0);
+            if (this.handshakeMetadataProvider) {
+                try {
+                    const result = await this.handshakeMetadataProvider();
+                    if (result instanceof Uint8Array) {
+                        const len = Math.min(result.byteLength, 0xffff);
+                        const copy = new Uint8Array(len);
+                        copy.set(result.subarray(0, len));
+                        handshakeMeta = copy;
+                    }
+                }
+                catch (metaErr) {
+                    this.obs.logger.warn({ peerId, err: metaErr }, 'handshakeMetadataProvider threw — proceeding with empty metadata');
+                }
+            }
+            const idTrailerLen = ownPeerIdBytes.length > 0 ? 1 + ownPeerIdBytes.length : 0;
+            const metaTrailerLen = handshakeMeta.length > 0 ? 2 + handshakeMeta.length : 0;
+            const msgLen = 1 + 2 + x25519Pub.length + mlKemPub.length + idTrailerLen + metaTrailerLen;
             const msg = new Uint8Array(msgLen);
             msg[0] = 1; // type: key exchange request
             msg[1] = (x25519Pub.length >> 8) & 0xff;
             msg[2] = x25519Pub.length & 0xff;
             msg.set(x25519Pub, 3);
             msg.set(mlKemPub, 3 + x25519Pub.length);
+            let writeCursor = 3 + x25519Pub.length + mlKemPub.length;
             if (ownPeerIdBytes.length > 0) {
-                const idOffset = 3 + x25519Pub.length + mlKemPub.length;
-                msg[idOffset] = ownPeerIdBytes.length;
-                msg.set(ownPeerIdBytes, idOffset + 1);
+                msg[writeCursor] = ownPeerIdBytes.length;
+                msg.set(ownPeerIdBytes, writeCursor + 1);
+                writeCursor += 1 + ownPeerIdBytes.length;
+            }
+            if (handshakeMeta.length > 0) {
+                // handshakeMeta trailer is only included when identity trailer is
+                // present, to preserve parser positional assumptions. In practice
+                // identity is always set during server connection.
+                msg[writeCursor] = (handshakeMeta.length >> 8) & 0xff;
+                msg[writeCursor + 1] = handshakeMeta.length & 0xff;
+                msg.set(handshakeMeta, writeCursor + 2);
             }
             s.sendData(new Uint8ArrayList(msg));
             s.sendCloseWrite();
@@ -1299,6 +1474,22 @@ export class SyncEngine {
                     this.obs.logger.warn({ peerId, identityPeerId: serverIdentityPeerId }, 'PQ key exchange failed, trusting Noise channel');
                 }
             }
+            else if (respType === 3) {
+                // [type=3] [reasonLen(2 BE)] [reason_utf8]
+                // Application-layer rejection from server.onPeerHandshake.
+                // Distinct from PQ key-exchange failure: this is terminal, we do
+                // NOT fall back to Noise. Leaves peer.authenticated = false.
+                // @req FR-67
+                let reason = 'application rejected handshake';
+                if (data.length >= 3) {
+                    const reasonLen = (data[1] << 8) | data[2];
+                    if (data.length >= 3 + reasonLen) {
+                        reason = new TextDecoder().decode(data.subarray(3, 3 + reasonLen));
+                    }
+                }
+                this.obs.logger.warn({ peerId, reason }, 'auth handshake rejected by server application hook');
+                throw new HandshakeRejectedError(`Server rejected handshake: ${reason}`, reason);
+            }
             else if (respType === 0) {
                 this.obs.logger.warn({ peerId }, 'auth handshake rejected by server');
                 // Still trust Noise channel for sync
@@ -1307,6 +1498,11 @@ export class SyncEngine {
             }
         }
         catch (err) {
+            // HandshakeRejectedError is terminal — do NOT fall back to Noise.
+            // @req FR-67
+            if (err instanceof HandshakeRejectedError) {
+                throw err;
+            }
             this.obs.logger.debug({ peerId, err }, 'auth handshake failed, trusting Noise channel');
             // Fallback: trust the Noise channel encryption
             peer.authenticated = true;
@@ -1427,6 +1623,32 @@ export class SyncEngine {
         await this.sendAuthoritativeReset(subtreeId, stream);
         return false;
     }
+    /**
+     * Reset per-peer ACL ban state for the named peer.
+     *
+     * Supports applications that perform out-of-band authorization (e.g.,
+     * validating a JWT and granting ACL via a separate HTTP route) and need
+     * to resume sync without waiting for the 5-minute clean-session window.
+     *
+     * Clears both the escalating ban state and the in-window denial tracker.
+     * Returns `{ cleared, priorDisconnects }` for observability; the caller
+     * can tell whether a ban was actually in effect.
+     *
+     * Exposed publicly via `SietchServer.clearAclBan(peerId)`.
+     *
+     * @req FR-36
+     */
+    clearAclBan(peerId) {
+        const prior = this.aclBanState.get(peerId);
+        const hadTracker = this.denialTrackers.has(peerId);
+        this.aclBanState.delete(peerId);
+        this.denialTrackers.delete(peerId);
+        const cleared = prior !== undefined || hadTracker;
+        if (cleared) {
+            this.obs.logger.info({ peerId, priorDisconnects: prior?.disconnects ?? 0 }, 'ACL ban state cleared by application');
+        }
+        return { cleared, priorDisconnects: prior?.disconnects ?? 0 };
+    }
     async sendAuthoritativeReset(subtreeId, stream) {
         const doc = await this.yjsEngine.getSubdoc(subtreeId);
         const fullState = Y.encodeStateAsUpdateV2(doc);