@ibgib/space-gib 0.0.1

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

@@ -0,0 +1,498 @@
+/**
+ * @module handlers/ws/sync-upgrade.handler
+ *
+ * Handles WebSocket upgrades for the sync protocol.
+ * Implements a challenge/response handshake using Keystone identity.
+ */
+
+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 { 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;
+
+/**
+ * Handles WebSocket upgrades for sync by validating against Keystone identity.
+ *
+ * Reuses ServeGibHandlerWithMetaspaceBase to ensure consistent metaspace
+ * initialization from the request context.
+ */
+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}]`;
+    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');
+    }
+}

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

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { IncomingMessage } from 'node:http';
+import { Socket } from 'node:net';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+/** Encodes a UTF-8 string as a minimal unmasked WebSocket text frame. */
+export function encodeTextFrame(text: string): Buffer {
+    const payload = Buffer.from(text, 'utf-8');
+    const payloadLen = payload.length;
+
+    let header: Buffer;
+    if (payloadLen < 126) {
+        header = Buffer.alloc(2);
+        header[0] = 0x81; // FIN + opcode 1 (text)
+        header[1] = payloadLen;
+    } else if (payloadLen < 65536) {
+        header = Buffer.alloc(4);
+        header[0] = 0x81;
+        header[1] = 126;
+        header.writeUInt16BE(payloadLen, 2);
+    } else {
+        header = Buffer.alloc(10);
+        header[0] = 0x81;
+        header[1] = 127;
+        header.writeBigUInt64BE(BigInt(payloadLen), 2);
+    }
+
+    return Buffer.concat([header, payload]);
+}
+
+/** Decodes a masked client WebSocket text frame. Returns null for non-text or incomplete frames. */
+export function decodeTextFrame(data: Buffer): string | null {
+    try {
+        if (data.length < 2) { return null; }
+
+        const opcode = data[0] & 0x0f;
+        if (opcode === 0x8) { return null; } // Close
+        if (opcode !== 0x1) { return null; } // Text only
+
+        const masked = (data[1] & 0x80) !== 0;
+        let payloadStart = 2;
+        let payloadLen = data[1] & 0x7f;
+
+        if (payloadLen === 126) {
+            payloadLen = data.readUInt16BE(2);
+            payloadStart = 4;
+        } else if (payloadLen === 127) {
+            payloadLen = Number(data.readBigUInt64BE(2));
+            payloadStart = 10;
+        }
+
+        if (masked) {
+            const maskStart = payloadStart;
+            payloadStart += 4;
+            const mask = data.slice(maskStart, maskStart + 4);
+            const payload = data.slice(payloadStart, payloadStart + payloadLen);
+            for (let i = 0; i < payload.length; i++) {
+                payload[i] ^= mask[i % 4];
+            }
+            return payload.toString('utf-8');
+        }
+
+        return data.slice(payloadStart, payloadStart + payloadLen).toString('utf-8');
+    } catch (error) {
+        console.error(`[ws-helper] decode error: ${extractErrorMsg(error)}`);
+        return null;
+    }
+}
+
+/** Encodes a WebSocket close frame (opcode 0x8) with optional status code. */
+export function encodeCloseFrame(code = 1000): Buffer {
+    const frame = Buffer.alloc(4);
+    frame[0] = 0x88;
+    frame[1] = 2;
+    frame.writeUInt16BE(code, 2);
+    return frame;
+}
+
+/** Performs the RFC 6455 opening handshake. */
+export function performHandshake(req: IncomingMessage, socket: Socket): boolean {
+    try {
+        const key = req.headers['sec-websocket-key'];
+        if (!key) {
+            socket.write('HTTP/1.1 400 Bad Request\r\n\r\nMissing Sec-WebSocket-Key');
+            socket.destroy();
+            return false;
+        }
+
+        const acceptKey = createHash('sha1')
+            .update(key + WS_MAGIC)
+            .digest('base64');
+
+        const response = [
+            'HTTP/1.1 101 Switching Protocols',
+            'Upgrade: websocket',
+            'Connection: Upgrade',
+            `Sec-WebSocket-Accept: ${acceptKey}`,
+            '\r\n',
+        ].join('\r\n');
+
+        socket.write(response);
+        return true;
+    } catch (error) {
+        console.error(`[ws-helper] handshake error: ${extractErrorMsg(error)}`);
+        socket.destroy();
+        return false;
+    }
+}

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

@@ -0,0 +1,53 @@
+import { KeystoneIbGib_V1 } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
+
+export type HandshakeMessageType =
+    'auth-challenge-init' |
+    'auth-init' |
+    'auth-challenge' |
+    'auth-proof' |
+    'auth-ok' |
+    'auth-fail';
+
+export interface HandshakeMessageBase {
+    type: HandshakeMessageType;
+}
+
+export interface AuthChallengeInitMessage extends HandshakeMessageBase {
+    type: 'auth-challenge-init';
+    challengeUuid: string;
+}
+
+export interface AuthInitMessage extends HandshakeMessageBase {
+    type: 'auth-init';
+    sAddr: string;
+}
+
+export interface AuthChallengeMessage extends HandshakeMessageBase {
+    type: 'auth-challenge';
+    challengeUuid: string;
+    demandedIds: string[];
+}
+
+export interface AuthProofMessage extends HandshakeMessageBase {
+    type: 'auth-proof';
+    proofFrame: KeystoneIbGib_V1;
+}
+
+export interface AuthOkMessage extends HandshakeMessageBase {
+    type: 'auth-ok';
+}
+
+export interface AuthFailMessage extends HandshakeMessageBase {
+    type: 'auth-fail';
+    message: string;
+    errors?: string[];
+}
+
+export type HandshakeMessage =
+    AuthChallengeInitMessage |
+    AuthInitMessage |
+    AuthChallengeMessage |
+    AuthProofMessage |
+    AuthOkMessage |
+    AuthFailMessage;
+

package/src/server/serve-gib/serve-gib-helpers.mts

@@ -0,0 +1,32 @@
+/**
+ * @module serve-gib/serve-gib-helpers
+ * 
+ * General purpose helper functions for the serve-gib framework.
+ */
+
+/**
+ * Validates and coerces a boolean query parameter in place on the queryParams object.
+ * 
+ * @param queryParams The parsed query parameters object
+ * @param key The specific key to validate and coerce
+ * @param errors Array to push error messages into if validation fails
+ */
+export function validateAndCoerceBooleanQueryParam(
+    queryParams: any,
+    key: string,
+    errors: string[]
+): void {
+    const rawVal = queryParams[key];
+    if (typeof rawVal === 'string' &&
+        (rawVal.toLowerCase() === 'true' || rawVal.toLowerCase() === 'false')
+    ) {
+        queryParams[key] = rawVal.toLowerCase() === 'true';
+    } else if (typeof rawVal === 'boolean') {
+        // do nothing, it's already a boolean
+    } else if (rawVal !== undefined) {
+        errors.push(`invalid value for "${key}". typeof should either be string or boolean. (E: c28ef87a2d4b4a6faef9a2c8db05b637)`);
+    } else {
+        // It's undefined, which means it wasn't provided in the URL.
+        // We do not error here because default parameters apply later or it may be optional.
+    }
+}