@ibgib/space-gib 0.0.1 → 0.0.2

package/src/server/serve-gib/handlers/ws/sync-upgrade.handler.mts

@@ -1,498 +1,24 @@
 /**
  * @module handlers/ws/sync-upgrade.handler
  *
- * Handles WebSocket upgrades for the sync protocol.
- * Implements a challenge/response handshake using Keystone identity.
+ * Concrete implementation of the serve-gib WebSocket Sync Peer wrapper.
+ * Decoupled from core protocols by extending SyncUpgradeHandlerBase.
  */
 
-import { IncomingMessage } from 'node:http';
-import { Socket } from 'node:net';
-
-import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
-import { getIbGibAddr, getIbAndGib } from '@ibgib/ts-gib/dist/helper.mjs';
-import { validateIbGibAddr } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
-import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
-import { KeystoneIbGib_V1 } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
-import { parseKeystoneIb } from '@ibgib/core-gib/dist/keystone/keystone-helpers.mjs';
-import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { IbGibSpaceResultIbGib, IbGibSpaceResultData, IbGibSpaceResultRel8ns } from '@ibgib/core-gib/dist/witness/space/space-types.mjs';
-
-import { GLOBAL_LOG_A_LOT } from '../../constants.mjs';
-import {
-    encodeTextFrame, decodeTextFrame, encodeCloseFrame, performHandshake
-} from './ws-helper.mjs';
+import { SyncUpgradeHandlerBase } from './sync-upgrade-handler-base.mjs';
 import { API_PATH_REGEXES } from '../../../path-constants.mjs';
-import { ServeGibHandlerWithMetaspaceBase } from '../handler-base.mjs';
-import { ParamsWithDomain, RequestContext, ResponseResult, ServeGibHttpMethod } from '../../types.mjs';
-import { SESSION_KEYSTONE_POLICY, checkHandshakeSolution } from '../../../../common/keystone-policies.mjs';
-import { AuthChallengeMessage, AuthFailMessage, AuthInitMessage, AuthOkMessage, AuthProofMessage, HandshakeMessage } from './ws-types.mjs';
-
-const logalot = GLOBAL_LOG_A_LOT || true;
+import { ServeGibHttpMethod } from '../../types.mjs';
 
 /**
- * Handles WebSocket upgrades for sync by validating against Keystone identity.
- *
- * Reuses ServeGibHandlerWithMetaspaceBase to ensure consistent metaspace
- * initialization from the request context.
+ * SyncChannelHandler manages the WebSocket Connect and Transport channel.
+ * Delegates 100% of connect handshake, signature verify, and sync turns to
+ * SyncPeerWebSocketReceiver_V1.
  */
-export interface SyncUpgradeQueryParams {
-    sAddr: string;
-    solution: string;
-}
-
-export interface SyncUpgradeRequestContext extends RequestContext<ParamsWithDomain, SyncUpgradeQueryParams> {
-    sAddr_tjp?: IbGibAddr;
-    demandedIds?: string[];
-}
-
-export class SyncUpgradeHandler extends ServeGibHandlerWithMetaspaceBase<ParamsWithDomain, SyncUpgradeQueryParams> {
-    protected override lc: string = `[${SyncUpgradeHandler.name}]`;
+export class SyncChannelHandler extends SyncUpgradeHandlerBase {
+    protected override lc: string = `[${SyncChannelHandler.name}]`;
     protected override method: ServeGibHttpMethod = 'GET';
-    protected override regex = API_PATH_REGEXES.SYNC_WS;
-
-    /**
-     * Entry point for WebSocket upgrades.
-     * Orchestrates the upgrade, handshake, and keystone authorization.
-     * @returns true if the upgrade was handled (even if it failed auth), false if path mismatch.
-     */
-    async handleUpgrade(reqCtx: RequestContext<ParamsWithDomain>, socket: Socket, head: Buffer): Promise<boolean> {
-        const lc_fn = `${this.lc}[handleUpgrade]`;
-        try {
-            if (logalot) { console.log(`${lc_fn} starting... (I: d772c676239f1f0a823c14a8063d4826)`); }
-
-            // 1. Initial validation
-            if (!this.canHandleRoute(reqCtx)) {
-                if (logalot) { console.log(`${lc_fn} path/method mismatch. (I: 234198c0f649dfdf0e2d21f86b3ff826)`); }
-                return false;
-            }
-
-            const ctx = reqCtx as SyncUpgradeRequestContext;
-
-            // Populate params (e.g. domain info) from the request context
-            ctx.params = await this.parseParams(ctx);
-            ctx.queryParams = await this.parseQueryParams(ctx);
-
-            // 2. Initialize Metaspace Context (bootstrapDomainMetaspace)
-            await this.initConcreteContext(ctx);
-
-            // 2b. Perform upfront picket-fence pre-filter validation
-            await this.validateUpfrontHandshake(ctx);
-
-            // 3. RFC 6455 Handshake
-            const ok = performHandshake(ctx as any as IncomingMessage, socket);
-            if (!ok) { return true; }
-
-            // 4. Setup Auth Challenge
-            const challengeUuid = await getUUID();
-
-            socket.write(encodeTextFrame(JSON.stringify({
-                type: 'auth-challenge-init',
-                challengeUuid
-            })));
-
-            socket.on('data', async (data: Buffer) => {
-                await this.handleUpgrade_socketDataHandler({
-                    reqCtx: ctx,
-                    challengeUuid,
-                    socket,
-                    data,
-                })
-            });
-
-            return true;
-        } catch (error) {
-            console.error(`${lc_fn} fatal: ${extractErrorMsg(error)}`);
-            socket.destroy();
-            return true;
-        }
-    }
-
-    protected async handleUpgrade_socketDataHandler({
-        reqCtx,
-        challengeUuid,
-        socket,
-        data,
-    }: {
-        reqCtx: SyncUpgradeRequestContext,
-        challengeUuid: string,
-        socket: Socket,
-        data: Buffer,
-    }): Promise<any> {
-        const lc = `[${this.handleUpgrade_socketDataHandler.name}]`;
-        if (logalot) { console.log(`${lc} starting... (I: 3ba9a857899f0479030e323b755fe826)`); }
-        try {
-            debugger; //
-            const text = decodeTextFrame(data);
-            if (text === null) {
-                socket.write(encodeCloseFrame());
-                socket.end();
-                return; /* <<<< returns early */
-            }
-
-            const msg = JSON.parse(text) as HandshakeMessage;
-            switch (msg.type) {
-                case 'auth-init':
-                    await this.handleUpgrade_socketDataHandler_authInit({
-                        reqCtx,
-                        challengeUuid,
-                        socket,
-                        msg,
-                    })
-                    break;
-
-
-                case 'auth-proof':
-                    await this.handleUpgrade_socketDataHandler_authProof({
-                        reqCtx,
-                        challengeUuid,
-                        socket,
-                        msg,
-                    });
-                    break;
-
-                default:
-                    if (logalot) { console.log(`${lc} unexpected message type: ${msg.type}`); }
-                    throw new Error(`unknown msg.type ${msg.type} (E: 8143084554d848f48801fcd5dc5fc826)`);
-            }
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            socket.write(encodeTextFrame(JSON.stringify({
-                type: 'auth-fail',
-                message: extractErrorMsg(error)
-            } as AuthFailMessage)));
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
-    protected async handleUpgrade_socketDataHandler_authInit({
-        reqCtx,
-        challengeUuid,
-        socket,
-        msg,
-    }: {
-        reqCtx: SyncUpgradeRequestContext,
-        challengeUuid: string,
-        socket: Socket,
-        msg: AuthInitMessage,
-    }): Promise<any> {
-        const lc = `${this.lc}[${this.handleUpgrade_socketDataHandler_authInit.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: 9ef8c8b892f82c7f98e34168f89c4826)`); }
-
-            const { sAddr } = msg;
-            if (logalot) { console.log(`${lc} auth-init for ${sAddr}`); }
-
-            // Load authorized S frame from context's metaspace
-            const metaspace = reqCtx.metaspace!;
-            const space = await metaspace.getLocalUserSpace({ lock: false });
-            if (!space) { throw new Error("No space."); }
-
-            let authorizedS: KeystoneIbGib_V1;
-            try {
-                authorizedS = await this.getSessionKeystone({ metaspace, space, sAddr });
-                if (logalot) { console.log(`${lc} loaded authorizedS:`, JSON.stringify(authorizedS).slice(0, 200) + '...'); }
-            } catch (error) {
-                console.warn(`${lc} session keystone not found: ${extractErrorMsg(error)}`);
-                socket.write(encodeTextFrame(JSON.stringify({
-                    type: 'auth-fail',
-                    message: 'Session keystone not found on server. Did you complete Step 4?'
-                } as AuthFailMessage)));
-                return; /* <<<< returns early */
-            }
-
-            // Identify handshake pool and select demanded IDs
-            const handshakePool = (authorizedS.data?.challengePools ?? []).find(p => p.id === SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID);
-            if (!handshakePool) {
-                socket.write(encodeTextFrame(JSON.stringify({
-                    type: 'auth-fail',
-                    message: `Session keystone missing "${SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID}" pool`
-                } as AuthFailMessage)));
-                return; /* <<<< returns early */
-            }
-
-            const challengeIds = Object.keys(handshakePool.challenges);
-            const demandedIds = challengeIds.sort(() => 0.5 - Math.random()).slice(0, SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.SERVER_DEMAND_COUNT);
-            reqCtx.demandedIds = demandedIds;
-
-            socket.write(encodeTextFrame(JSON.stringify({
-                type: 'auth-challenge',
-                challengeUuid,
-                demandedIds
-            } as AuthChallengeMessage)));
-
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
-
-    /**
-     * At this point, the session keystone (S^Stjp) according to the server only
-     * has the first frame (tjp) persisted. But the client has successfully
-     * initiated the handshake, so it provided the one manual challenge.
-     *
-     * We (the server) then sent the client some challenge ids and said to the
-     * client "Hey, solve the keystone with these challenges included."
-     *
-     * So now, the client has sent the next evolution of the session keystone,
-     * S^S1.Stjp, with those challenge ids included.
-     */
-    protected async handleUpgrade_socketDataHandler_authProof({
-        reqCtx,
-        challengeUuid,
-        socket,
-        msg,
-    }: {
-        reqCtx: SyncUpgradeRequestContext,
-        challengeUuid: string,
-        socket: Socket,
-        msg: AuthProofMessage,
-    }): Promise<any> {
-        const lc = `${this.lc}[${this.handleUpgrade_socketDataHandler_authProof.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: b0c185793602f4e4d862785e906cdd26)`); }
-            const { proofFrame } = msg;
-            if (logalot) { console.log(`${lc} verifying auth-proof...`); }
-
-            const sAddr_proofFrame = getIbGibAddr({ ibGib: proofFrame });
-
-            // need to get the tip of session keystone
-            const metaspace = reqCtx.metaspace!;
-            const space = await metaspace.getLocalUserSpace({ lock: false });
-            if (!space) { throw new Error(`(UNEXPECTED) no default local user space? (E: 1443da451007921b2da9d2c8b15a4826)`); }
-            const sAddr_tjp = reqCtx.sAddr_tjp;
-            if (!sAddr_tjp) {
-                throw new Error("Missing upfront verified session keystone TJP address (E: cb1998fa7c4a11f5ee87b001a4e126a1)");
-            }
-            /**
-             * this is the latest/tip addr for session keystone that the server
-             * is currently aware of.
-             *
-             * NOTE: We do NOT (!!!) trust the incoming session keystone to
-             * drive what the client thinks it the latest addr. Not only is this
-             * in the control of a would-be attacker, the client could just be
-             * out of date with a race condition.
-             */
-            const sAddr_latest = await metaspace.getLatestAddr({ tjpAddr: sAddr_tjp, space });
-            if (!sAddr_latest) {
-                socket.write(encodeTextFrame(JSON.stringify({
-                    type: 'auth-fail',
-                    message: 'Authorized session keystone tip not found'
-                } as AuthFailMessage)));
-                return; /* <<<< returns early */
-            }
-            const sKeystone_latest = await this.getSessionKeystone({
-                sAddr: sAddr_latest,
-                metaspace,
-                space,
-            });
-
-            const keystoneService = new KeystoneService_V1();
-            const validationErrors = await keystoneService.validate({
-                prevIbGib: sKeystone_latest,
-                currentIbGib: proofFrame,
-            });
-
-            if (validationErrors && validationErrors.length > 0) {
-                socket.write(encodeTextFrame(JSON.stringify({
-                    type: 'auth-fail',
-                    message: 'Proof validation failed',
-                    errors: validationErrors
-                } as AuthFailMessage)));
-                return; /* <<<< returns early */
-            }
-
-            const proofs = proofFrame.data.proofs ?? [];
-            const proof = proofs.find(p => p.claim?.verb === SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.VERB);
-            if (!proof || proof.claim?.target !== challengeUuid) {
-                socket.write(encodeTextFrame(JSON.stringify({
-                    type: 'auth-fail',
-                    message: 'Proof target mismatch or missing handshake claim'
-                } as AuthFailMessage)));
-                return; /* <<<< returns early */
-            }
-
-            // Ensure that all of our demanded challenge ids are present in the proof solutions
-            const demandedIds = reqCtx.demandedIds;
-            if (!demandedIds || demandedIds.length === 0) {
-                socket.write(encodeTextFrame(JSON.stringify({
-                    type: 'auth-fail',
-                    message: 'Server missing active handshake challenge state'
-                } as AuthFailMessage)));
-                return; /* <<<< returns early */
-            }
-
-            const solvedIds = new Set(proof.solutions?.map(s => s.challengeId) ?? []);
-            const missingIds = demandedIds.filter(id => !solvedIds.has(id));
-            if (missingIds.length > 0) {
-                socket.write(encodeTextFrame(JSON.stringify({
-                    type: 'auth-fail',
-                    message: `Proof is missing demanded solutions: ${missingIds.join(', ')}`
-                } as AuthFailMessage)));
-                return; /* <<<< returns early */
-            }
-
-            // Persist the newly validated evolved session keystone tip to the server space
-            await metaspace.put({ ibGibs: [proofFrame], space });
-
-            if (logalot) { console.log(`${lc} auth successful for ${sAddr_proofFrame} (I: 6d02c649f55c81cfe8f11988f44bca26)`); }
-            socket.write(encodeTextFrame(JSON.stringify({ type: 'auth-ok' } as AuthOkMessage)));
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
-    protected async getSessionKeystone({
-        metaspace,
-        space,
-        sAddr,
-    }: {
-        metaspace: NonNullable<RequestContext['metaspace']>,
-        space: any,
-        sAddr: string,
-    }): Promise<KeystoneIbGib_V1> {
-        const lc = `${this.lc}[${this.getSessionKeystone.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: cb9af0e14d3345bfbc0be35728de7c26)`); }
-
-            const resGet = await metaspace.get({ addrs: [sAddr], space });
-
-            // Validate result
-            if (resGet.success && resGet.ibGibs && resGet.ibGibs.length === 1) {
-                return resGet.ibGibs[0] as KeystoneIbGib_V1;
-            } else {
-                // Robust error handling using rawResultIbGib
-                const resIbGib = resGet.rawResultIbGib as IbGibSpaceResultIbGib<IbGib_V1, IbGibSpaceResultData, IbGibSpaceResultRel8ns>;
-                const addrsNotFound = resIbGib?.data?.addrsNotFound ?? 'unknown';
-                throw new Error(`couldn't find all addrs. addrsNotFound: ${addrsNotFound}? resGet.errorMsg: ${resGet.errorMsg}. space.ib: ${space.ib} (E: f3c87e2b19794358a9e701cd59b8eb26)`);
-            }
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
-    protected async validateUpfrontHandshake(reqCtx: SyncUpgradeRequestContext): Promise<void> {
-        const lc = `${this.lc}[${this.validateUpfrontHandshake.name}]`;
-        const sAddr = reqCtx.queryParams?.sAddr;
-        const solution = reqCtx.queryParams?.solution;
-
-        if (!sAddr || !solution) {
-            throw new Error(`Missing upfront handshake parameters (sAddr, solution) (E: 8a4c9a724ddf59998199ec87a9ee126)`);
-        }
-
-        const metaspace = reqCtx.metaspace!;
-        const space = await metaspace.getLocalUserSpace({ lock: false });
-        if (!space) { throw new Error("No space."); }
-
-        const authorizedS = await this.getSessionKeystone({ metaspace, space, sAddr });
-        const isValid = await checkHandshakeSolution(authorizedS, solution);
-        if (!isValid) {
-            throw new Error(`Upfront handshake solution verification failed (E: 804c98a724ddf59998199ec87a9ee127)`);
-        }
-
-        // Store secure TJP address of the verified session keystone in reqCtx
-        const past = authorizedS.rel8ns?.past;
-        const tjpAddr = (past && past.length > 0) ? past[0] : getIbGibAddr({ ibGib: authorizedS });
-        reqCtx.sAddr_tjp = tjpAddr;
-
-        if (logalot) { console.log(`${lc} Upfront picket-fence verification succeeded for ${sAddr}!`); }
-    }
-
-    protected override async parseParamsImpl(reqCtx: RequestContext<ParamsWithDomain>): Promise<ParamsWithDomain | undefined> {
-        const lc = `${this.lc}[${this.parseParamsImpl.name}]`;
-        try {
-            const match = reqCtx.pathname.match(this.regex);
-            if (!match) return undefined;
-            const domainIb = decodeURIComponent(match[1]);
-            const domainGib = decodeURIComponent(match[2]);
-            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
-
-            return {
-                domainInfo: this.getDomainInfo({ domainAddr })
-            };
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        }
-    }
-
-    protected override async parseQueryParams(
-        reqCtx: RequestContext<ParamsWithDomain, SyncUpgradeQueryParams>
-    ): Promise<SyncUpgradeQueryParams | undefined> {
-        const lc = `${this.lc}[${this.parseQueryParams.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: 3ed5ba8d47af31f538fbdb484cfdb826)`); }
-
-            const sAddrRaw = reqCtx.url.searchParams.get('sAddr');
-            const sAddr = sAddrRaw ? decodeURIComponent(sAddrRaw) : undefined;
-            const solution = reqCtx.url.searchParams.get('solution') ?? undefined;
-
-            const queryParams: Partial<SyncUpgradeQueryParams> = {};
-            if (sAddr !== undefined) { queryParams.sAddr = sAddr; }
-            if (solution !== undefined) { queryParams.solution = solution; }
-
-            if (Object.keys(queryParams).length > 0) {
-                const validationErrors = await this.validateQueryParams({ queryParams });
-                if (validationErrors.length === 0) {
-                    return queryParams as SyncUpgradeQueryParams;
-                } else {
-                    throw new Error(`invalid query params. validationErrors: ${validationErrors.join(', ')} (E: 9355f8a9643803f52f2241f1c7f39826)`);
-                }
-            } else {
-                return undefined;
-            }
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
-    protected override async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
-        const errors: string[] = [];
-        if (!queryParams) {
-            return ["Missing query parameters: sAddr, solution"];
-        }
-
-        if (!queryParams.sAddr) {
-            errors.push("Missing sAddr");
-        } else {
-            try {
-                const decodedSAddr = queryParams.sAddr;
-
-                // use validateIbGibAddr to ensure that it's a valid address.
-                const addrErrors = validateIbGibAddr({ addr: decodedSAddr }) ?? [];
-                if (addrErrors.length > 0) {
-                    errors.push(`Invalid sAddr: ${addrErrors.join(', ')}`);
-                } else {
-                    // get the ib and ensure that it is a keystone ib using parseKeystoneIb (will throw if invalid)
-                    const { ib } = getIbAndGib({ ibGibAddr: decodedSAddr });
-                    parseKeystoneIb({ ib });
-                }
-            } catch (error) {
-                errors.push(`Invalid sAddr: ${extractErrorMsg(error)}`);
-            }
-        }
-
-        if (!queryParams.solution) {
-            errors.push("Missing solution");
-        }
-        return errors;
-    }
-
-    protected override async handleRouteImpl(reqCtx: RequestContext<ParamsWithDomain>): Promise<ResponseResult | undefined> {
-        return this.error(400, 'WS endpoint requires upgrade');
-    }
+    protected override regex: RegExp = API_PATH_REGEXES.SYNC_WS;
 }
+
+/** Keep naming backward-compatible for server registrations */
+export const SyncUpgradeHandler = SyncChannelHandler;

package/src/server/serve-gib/handlers/ws/ws-helper.mts

@@ -79,8 +79,8 @@ export function encodeCloseFrame(code = 1000): Buffer {
     return frame;
 }
 
-/** Performs the RFC 6455 opening handshake. */
-export function performHandshake(req: IncomingMessage, socket: Socket): boolean {
+/** Performs the RFC 6455 opening connect handshake. */
+export function performConnect(req: IncomingMessage, socket: Socket): boolean {
     try {
         const key = req.headers['sec-websocket-key'];
         if (!key) {
@@ -104,8 +104,85 @@ export function performHandshake(req: IncomingMessage, socket: Socket): boolean
         socket.write(response);
         return true;
     } catch (error) {
-        console.error(`[ws-helper] handshake error: ${extractErrorMsg(error)}`);
+        console.error(`[ws-helper] connect error: ${extractErrorMsg(error)}`);
         socket.destroy();
         return false;
     }
 }
+
+/**
+ * Stateful WebSocket text frame decoder that aggregates incoming TCP chunks
+ * and decodes full RFC 6455 frames.
+ */
+export class WebSocketFrameDecoder {
+    private buffer: Buffer = Buffer.alloc(0);
+
+    /** Adds new data chunk from TCP socket. */
+    addChunk(chunk: Buffer): void {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+    }
+
+    /**
+     * Parses the next complete text frame from the accumulated buffer.
+     * Returns:
+     * - `string` if a complete text frame was decoded successfully (and consumes those bytes).
+     * - `null` if the buffer is incomplete or we need more data.
+     * - `throws Error` on protocol errors or close frames.
+     */
+    nextFrame(): string | null {
+        if (this.buffer.length < 2) {
+            return null;
+        }
+
+        const opcode = this.buffer[0] & 0x0f;
+        if (opcode === 0x8) {
+            throw new Error('Close frame received');
+        }
+        if (opcode !== 0x1) {
+            throw new Error(`Unsupported WebSocket opcode: 0x${opcode.toString(16)}`);
+        }
+
+        const secondByte = this.buffer[1];
+        const masked = (secondByte & 0x80) !== 0;
+        let payloadLen = secondByte & 0x7f;
+        let headerLen = 2;
+
+        if (payloadLen === 126) {
+            if (this.buffer.length < 4) {
+                return null;
+            }
+            payloadLen = this.buffer.readUInt16BE(2);
+            headerLen = 4;
+        } else if (payloadLen === 127) {
+            if (this.buffer.length < 10) {
+                return null;
+            }
+            payloadLen = Number(this.buffer.readBigUInt64BE(2));
+            headerLen = 10;
+        }
+
+        const maskLen = masked ? 4 : 0;
+        const totalFrameLen = headerLen + maskLen + payloadLen;
+
+        if (this.buffer.length < totalFrameLen) {
+            return null;
+        }
+
+        const frameData = this.buffer.subarray(0, totalFrameLen);
+        this.buffer = this.buffer.subarray(totalFrameLen);
+
+        let payloadStart = headerLen;
+        if (masked) {
+            const mask = frameData.subarray(payloadStart, payloadStart + 4);
+            payloadStart += 4;
+            const payload = Buffer.from(frameData.subarray(payloadStart));
+            for (let i = 0; i < payload.length; i++) {
+                payload[i] ^= mask[i % 4];
+            }
+            return payload.toString('utf-8');
+        } else {
+            const payload = frameData.subarray(payloadStart);
+            return payload.toString('utf-8');
+        }
+    }
+}