@ibgib/node-gib 0.0.10 → 0.0.14

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

@@ -0,0 +1,233 @@
+/**
+ * @module handlers/ws/sync-upgrade-handler-base
+ *
+ * Highly generic, reusable base class in serve-gib for handling WebSocket upgrades,
+ * mapping socket streams to isomorphic SyncPeers, and checking upfront connect handshakes.
+ */
+
+import { IncomingMessage } from 'node:http';
+import { Socket } from 'node:net';
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr, getIbAndGib } from '@ibgib/ts-gib/dist/helper.mjs';
+import { validateIbGibAddr } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+import { parseKeystoneIb } from '@ibgib/core-gib/dist/keystone/keystone-helpers.mjs';
+import { SyncPeerWebSocketReceiver_V1, IWebSocketWrapper } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-peer-websocket-receiver-v1.mjs';
+import { validateUpfrontConnect } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
+import { SyncSagaCoordinator } from '@ibgib/core-gib/dist/sync/sync-saga-coordinator.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../constants.mjs';
+import {
+    encodeTextFrame, decodeTextFrame, encodeCloseFrame, performConnect,
+    WebSocketFrameDecoder
+} from './ws-helper.mjs';
+import { ServeGibHandlerWithMetaspaceBase } from '../handler-base.mjs';
+import { ParamsWithDomain, RequestContext, ResponseResult, ServeGibHttpMethod } from '../../types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface SyncChannelQueryParams {
+    sAddr: string;
+    solution: string;
+}
+
+export interface SyncChannelRequestContext extends RequestContext<ParamsWithDomain, SyncChannelQueryParams> {
+}
+
+/**
+ * Reusable server-side upgrade handler plumbing.
+ * Binds raw node socket streams to platform-agnostic receiver peers.
+ */
+export abstract class SyncUpgradeHandlerBase extends ServeGibHandlerWithMetaspaceBase<ParamsWithDomain, SyncChannelQueryParams> {
+    protected override lc: string = `[${SyncUpgradeHandlerBase.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+
+    /**
+     * Entry point for WebSocket upgrades.
+     * Orchestrates the upgrade, upfront validation, and registers the Receiver peer.
+     */
+    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...`); }
+
+            // 1. Initial routing checks
+            if (!this.canHandleRoute(reqCtx)) {
+                return false;
+            }
+
+            const ctx = reqCtx as SyncChannelRequestContext;
+
+            // Extract route parameters & query parameters
+            ctx.params = await this.parseParams(ctx);
+            ctx.queryParams = await this.parseQueryParams(ctx);
+
+            // 2. Bootstrap multi-tenant domain metaspace context
+            await this.initConcreteContext(ctx);
+
+            const metaspace = ctx.metaspace!;
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error("No default local user space found."); }
+
+            // 3. Upfront picket-fence pre-filter validation
+            const queryParams = ctx.queryParams!;
+            await validateUpfrontConnect({
+                sAddr: queryParams.sAddr,
+                solution: queryParams.solution,
+                space,
+                metaspace
+            });
+
+            // 4. Perform standard RFC 6455 Connect H andshake Upgrade
+            const ok = performConnect(ctx as any as IncomingMessage, socket);
+            if (!ok) { return true; }
+
+            // 5. Instantiate and initialize isomorphic WebSocket Receiver Peer
+            const receiverPeer = new SyncPeerWebSocketReceiver_V1({
+                classname: 'SyncPeerWebSocketReceiver_V1'
+            });
+
+            const localCoordinator = new SyncSagaCoordinator();
+            await receiverPeer.initializeOpts({
+                localCoordinator,
+                localMetaspace: metaspace,
+                localSpace: space,
+                sagaId: undefined, // Resolved dynamically inside runtime turns
+            });
+
+            // Handle raw socket errors to prevent unhandled 'error' crash (e.g. ECONNRESET)
+            socket.on('error', (err) => {
+                if (logalot) { console.warn(`[SyncUpgradeHandlerBase] Socket error: ${extractErrorMsg(err)}`); }
+                try {
+                    socket.destroy();
+                } catch (e) {
+                    // ignore
+                }
+            });
+
+            // 6. Map standard Node.js Socket to platform-agnostic IWebSocketWrapper
+            const socketWrapper: IWebSocketWrapper = {
+                send(data: string): void {
+                    if (socket.writable) {
+                        try {
+                            socket.write(encodeTextFrame(data));
+                        } catch (e) {
+                            if (logalot) { console.warn(`[SyncUpgradeHandlerBase] failed to write message frame: ${extractErrorMsg(e)}`); }
+                        }
+                    }
+                },
+                onMessage(callback: (data: string) => void): void {
+                    const decoder = new WebSocketFrameDecoder();
+                    socket.on('data', (buf) => {
+                        try {
+                            decoder.addChunk(buf);
+                            let frameText = decoder.nextFrame();
+                            while (frameText !== null) {
+                                callback(frameText);
+                                frameText = decoder.nextFrame();
+                            }
+                        } catch (error) {
+                            if (logalot) { console.warn(`[SyncUpgradeHandlerBase] closing connection due to decoder error: ${extractErrorMsg(error)}`); }
+                            if (socket.writable) {
+                                try {
+                                    socket.write(encodeCloseFrame());
+                                } catch (e) {
+                                    // ignore
+                                }
+                            }
+                            socket.end();
+                        }
+                    });
+                },
+                onClose(callback: () => void): void {
+                    socket.on('close', callback);
+                },
+                close(): void {
+                    if (socket.writable) {
+                        try {
+                            socket.write(encodeCloseFrame());
+                        } catch (e) {
+                            // ignore
+                        }
+                    }
+                    socket.end();
+                }
+            };
+
+            // Bind peer receiver to handle all socket messages (connect & runtime)
+            await receiverPeer.bindSocket(socketWrapper);
+
+            return true;
+        } catch (error) {
+            console.error(`${lc_fn} upgrade failure: ${extractErrorMsg(error)}`);
+            socket.destroy();
+            return true;
+        }
+    }
+
+    protected override async parseParamsImpl(reqCtx: RequestContext<ParamsWithDomain>): Promise<ParamsWithDomain | undefined> {
+        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 })
+        };
+    }
+
+    protected override async parseQueryParams(
+        reqCtx: RequestContext<ParamsWithDomain, SyncChannelQueryParams>
+    ): Promise<SyncChannelQueryParams | undefined> {
+        const sAddrRaw = reqCtx.url.searchParams.get('sAddr');
+        const sAddr = sAddrRaw ? decodeURIComponent(sAddrRaw) : undefined;
+        const solution = reqCtx.url.searchParams.get('solution') ?? undefined;
+
+        const queryParams: Partial<SyncChannelQueryParams> = {};
+        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 SyncChannelQueryParams;
+            } else {
+                throw new Error(`invalid query params: ${validationErrors.join(', ')}`);
+            }
+        }
+        return undefined;
+    }
+
+    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;
+                const addrErrors = validateIbGibAddr({ addr: decodedSAddr }) ?? [];
+                if (addrErrors.length > 0) {
+                    errors.push(`Invalid sAddr: ${addrErrors.join(', ')}`);
+                } else {
+                    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/serve-gib/handlers/ws/sync-upgrade.handler.mts

@@ -0,0 +1,24 @@
+/**
+ * @module handlers/ws/sync-upgrade.handler
+ *
+ * Concrete implementation of the serve-gib WebSocket Sync Peer wrapper.
+ * Decoupled from core protocols by extending SyncUpgradeHandlerBase.
+ */
+
+import { SyncUpgradeHandlerBase } from './sync-upgrade-handler-base.mjs';
+import { API_PATH_REGEXES } from '../../path-constants.mjs';
+import { ServeGibHttpMethod } from '../../types.mjs';
+
+/**
+ * SyncChannelHandler manages the WebSocket Connect and Transport channel.
+ * Delegates 100% of connect handshake, signature verify, and sync turns to
+ * SyncPeerWebSocketReceiver_V1.
+ */
+export class SyncChannelHandler extends SyncUpgradeHandlerBase {
+    protected override lc: string = `[${SyncChannelHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+    protected override regex: RegExp = API_PATH_REGEXES.SYNC_WS;
+}
+
+/** Keep naming backward-compatible for server registrations */
+export const SyncUpgradeHandler = SyncChannelHandler;

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

@@ -0,0 +1,216 @@
+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 connect handshake. */
+export function performConnect(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] 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);
+    private fragments: Buffer[] = [];
+
+    /** Adds new data chunk from TCP socket. */
+    addChunk(chunk: Buffer): void {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+    }
+
+    /**
+     * Parses the next complete text message, assembling fragments if necessary.
+     * Returns:
+     * - `string` if a complete text message was assembled/decoded (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 {
+        while (true) {
+            if (this.buffer.length < 2) {
+                return null;
+            }
+
+            const firstByte = this.buffer[0];
+            const fin = (firstByte & 0x80) !== 0;
+            const opcode = firstByte & 0x0f;
+
+            if (opcode === 0x8) {
+                throw new Error('Close frame received');
+            }
+
+            const isContinuation = opcode === 0x0;
+            const isText = opcode === 0x1;
+
+            if (!isContinuation && !isText) {
+                throw new Error(`Unsupported WebSocket opcode: 0x${opcode.toString(16)}`);
+            }
+
+            // Protocol checks
+            if (isContinuation && this.fragments.length === 0) {
+                throw new Error('Continuation frame received without an active message.');
+            }
+            if (isText && this.fragments.length > 0) {
+                throw new Error('New message frame received before previous one completed.');
+            }
+
+            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;
+            }
+
+            // Consume frame from buffer
+            const frameData = this.buffer.subarray(0, totalFrameLen);
+            this.buffer = this.buffer.subarray(totalFrameLen);
+
+            let payloadStart = headerLen;
+            let payload: Buffer;
+            if (masked) {
+                const mask = frameData.subarray(payloadStart, payloadStart + 4);
+                payloadStart += 4;
+                payload = Buffer.from(frameData.subarray(payloadStart));
+                for (let i = 0; i < payload.length; i++) {
+                    payload[i] ^= mask[i % 4];
+                }
+            } else {
+                payload = Buffer.from(frameData.subarray(payloadStart));
+            }
+
+            this.fragments.push(payload);
+
+            if (fin) {
+                const completePayload = Buffer.concat(this.fragments);
+                this.fragments = [];
+                return completePayload.toString('utf-8');
+            }
+            
+            // Loop again to process any subsequent frames already inside the TCP buffer
+        }
+    }
+}

package/src/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/serve-gib/identity-index/identity-index-constants.mts

@@ -0,0 +1,3 @@
+export const DEFAULT_IDENTITY_INDEX_DIR_NAME = 'identity_index';
+export const DEFAULT_EMAIL_HASHES_SUBDIR = 'email_hashes';
+export const DEFAULT_IDENTITY_INDEX_SALT = 'ibgib_identity_salt_default_v1';

package/src/serve-gib/identity-index/identity-index-helpers.mts

@@ -0,0 +1,85 @@
+import * as path from 'path';
+import { hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { KEYSTONE_EMAIL_REGEXP } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { DEFAULT_EMAIL_HASHES_SUBDIR, DEFAULT_IDENTITY_INDEX_SALT } from './identity-index-constants.mjs';
+
+/**
+ * Validates an email address against length constraints and KEYSTONE_EMAIL_REGEXP.
+ * Returns an array of error message strings (empty `[]` if valid).
+ */
+export function validateEmail({ email }: { email: any }): string[] {
+    const errors: string[] = [];
+    if (!email || typeof email !== 'string') {
+        errors.push('Email must be a non-empty string.');
+        return errors;
+    }
+    const trimmed = email.trim();
+    if (trimmed.length < 3) {
+        errors.push('Email length must be at least 3 characters.');
+    }
+    if (trimmed.length > 254) {
+        errors.push('Email length must not exceed 254 characters.');
+    }
+    if (!KEYSTONE_EMAIL_REGEXP.test(trimmed)) {
+        errors.push(`Email '${trimmed}' is not a valid email format.`);
+    }
+    return errors;
+}
+
+/**
+ * Normalizes an email string (lowercased and trimmed).
+ */
+export function normalizeEmail(email: string): string {
+    if (!email || typeof email !== 'string') { return ''; }
+    return email.trim().toLowerCase();
+}
+
+/**
+ * Computes SHA256 privacy hash of an email string:
+ * `SHA256(normalizeEmail(email) + salt)` using `hash` from `@ibgib/helper-gib`.
+ */
+export async function getIdentityEmailHash({
+    email,
+    salt = process.env.IDENTITY_INDEX_SALT || DEFAULT_IDENTITY_INDEX_SALT,
+}: {
+    email: string;
+    salt?: string;
+}): Promise<string> {
+    const validationErrors = validateEmail({ email });
+    if (validationErrors.length > 0) {
+        throw new Error(`Invalid email address: ${validationErrors.join(', ')} (E: 69a68886b1dab2f4f85c3e884031d326)`);
+    }
+    const normalized = normalizeEmail(email);
+    const emailHash = await hash({ s: `${normalized}${salt}` });
+    return emailHash;
+}
+
+/**
+ * Returns the sharded directory path and truncated filename for an email hash.
+ *
+ * Full Hash (e.g. 64 chars): `abcdef12345...`
+ * Subfolders: `ab/cd/ef`
+ * Truncated filename: `12345....json` (strips the leading 6 characters that form the 3 subfolder pairs).
+ */
+export function getShardedIndexPath({
+    baseDir,
+    emailHash,
+}: {
+    baseDir: string;
+    emailHash: string;
+}): { folderPath: string; filePath: string; filename: string } {
+    if (!emailHash || emailHash.length < 7) {
+        throw new Error(`Invalid email hash string '${emailHash}'. Must be at least 7 characters. (E: 7aeb7885a7f1b4576899db283516d826)`);
+    }
+
+    const f1 = emailHash.slice(0, 2);
+    const f2 = emailHash.slice(2, 4);
+    const f3 = emailHash.slice(4, 6);
+    const remainingHash = emailHash.slice(6);
+    const filename = `${remainingHash}.json`;
+
+    const folderPath = path.join(baseDir, DEFAULT_EMAIL_HASHES_SUBDIR, f1, f2, f3);
+    const filePath = path.join(folderPath, filename);
+
+    return { folderPath, filePath, filename };
+}