tisura 0.0.1-0

package/README.md

@@ -0,0 +1,95 @@
+# Sentinel SDK
+
+This project contains the code for [tisura](https://www.npmjs.com/package/tisura) npm package.
+It provides modules for parsing network packets, proving statements, managing connections, and handling TLS operations.
+
+## Installation
+
+```bash
+npm install tisura
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { Tisura } from 'tisura';
+
+const client = new Tisura({
+  dbHost: "localhost",
+  dbName: "your_database",
+  dbUser: "your_username",
+  dbPassword: "your_password",
+  dbPort: 5432,
+  tlsVersion: "1.3"
+});
+```
+
+### Parsing Network Packets
+
+```typescript
+// Get and parse packets from database
+const parseClient = client.parse;
+const packets = await parseClient.getPackets();
+const appData = await parseClient.getAppData();
+```
+
+### Creating TLS connection
+
+```typescript
+// Get and parse packets from database
+const tlsClient = client.tls;
+await tlsClient.init();
+const tlsConn = await tlsClient.TlsConnection();
+```
+
+### Available Modules
+
+The SDK consists of several modules:
+
+- **Parse**: Network packet parsing and analysis
+- **Prove**: Statement proving and verification (coming soon)
+- **Connect**: Connection management (coming soon)
+- **TLS**: TLS operations with WASM implementation
+
+### Module-specific Imports
+
+You can import specific modules directly:
+
+```typescript
+import { ParseClient } from 'tisura/parse';
+// import { ProveClient } from 'tisura/prove';    // Coming soon
+// import { ConnectClient } from 'tisura/connect'; // Coming soon
+import { TLSClient } from 'tisura/tls';
+```
+
+## Configuration
+
+The SDK requires the following configuration parameters:
+
+```typescript
+interface TisuraConfig {
+  dbHost?: string;      // Database host
+  dbName?: string;      // Database name
+  dbUser?: string;      // Database username
+  dbPassword?: string;  // Database password
+  dbPort?: number;      // Database port
+  tlsVersion?: string;  // TLS version ("1.2" or "1.3")
+}
+```
+
+## Development
+
+### Install, build and run tests
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+```

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import { TisuraBase, TisuraConfig } from "./config";
+import { ParseClient } from "./parse";
+export declare class Tisura extends TisuraBase {
+    parse: ParseClient;
+    constructor(config: TisuraConfig);
+}

package/dist/client.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tisura = void 0;
+const config_1 = require("./config");
+const parse_1 = require("./parse");
+// import { ProveClient } from "./prove";
+// import { ConnectClient } from "./connect";
+// import { TLSClient } from "./tls";
+class Tisura extends config_1.TisuraBase {
+    parse;
+    // public prove: ProveClient;
+    // public connect: ConnectClient;
+    // public tls: TLSClient;
+    constructor(config) {
+        super(config);
+        this.parse = new parse_1.ParseClient(this.config);
+        // this.prove = new ProveClient(this.config);
+        // this.connect = new ConnectClient(this.config);
+        // this.tls = new TLSClient(this.config);
+    }
+}
+exports.Tisura = Tisura;

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import { Pool } from "pg";
+export interface TisuraConfig {
+    dbHost?: string;
+    dbName?: string;
+    dbUser?: string;
+    dbPassword?: string;
+    dbPort?: number;
+    tlsVersion?: string;
+}
+export declare class TisuraBase {
+    protected config: TisuraConfig;
+    constructor(config: TisuraConfig);
+    protected getPool(): Pool;
+}

package/dist/config.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TisuraBase = void 0;
+const pg_1 = require("pg");
+class TisuraBase {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    getPool() {
+        return new pg_1.Pool({
+            host: this.config.dbHost,
+            database: this.config.dbName,
+            user: this.config.dbUser,
+            password: this.config.dbPassword,
+            port: this.config.dbPort,
+        });
+    }
+}
+exports.TisuraBase = TisuraBase;

package/dist/connect/index.d.ts

@@ -0,0 +1 @@
+export declare function connectToServer(url: string): void;

package/dist/connect/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectToServer = connectToServer;
+function connectToServer(url) {
+    console.log(`Connecting to ${url}...`);
+}

package/dist/parse/db.d.ts

@@ -0,0 +1,6 @@
+import { Pool } from "pg";
+import { PacketInfo } from "./types";
+/**
+ * Reads rows from the "captures" table and returns an array of PacketInfo.
+ */
+export declare function readPacketsFromDb(pool: Pool): Promise<PacketInfo[]>;

package/dist/parse/db.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPacketsFromDb = readPacketsFromDb;
+/**
+ * Reads rows from the "captures" table and returns an array of PacketInfo.
+ */
+async function readPacketsFromDb(pool) {
+    try {
+        // Query the database
+        const result = await pool.query(`
+      SELECT
+        id,
+        timestamp,
+        source_ip,
+        source_port,
+        destination_ip,
+        destination_port,
+        protocol,
+        length,
+        payload
+      FROM captures
+      ORDER BY id;
+    `);
+        // Map each row to a PacketInfo object
+        const packets = result.rows.map((row) => {
+            // In Node.js, 'timestamp' column often comes as a Date object.
+            // Python's row[1].timestamp() returned float seconds from epoch.
+            // We'll replicate that by dividing Date.getTime() by 1000.
+            const epochSeconds = row.timestamp.getTime() / 1000;
+            return {
+                timestamp: epochSeconds,
+                sourceIp: row.source_ip,
+                sourcePort: row.source_port,
+                destinationIp: row.destination_ip,
+                destinationPort: row.destination_port,
+                protocol: row.protocol,
+                length: row.length,
+                // 'payload' from Postgres may be a Buffer in Node. Convert to Uint8Array.
+                payload: new Uint8Array(row.payload),
+            };
+        });
+        return packets;
+    }
+    finally {
+        // Close the pool to free up resources
+        await pool.end();
+    }
+}

package/dist/parse/index.d.ts

@@ -0,0 +1,7 @@
+import { TisuraBase, TisuraConfig } from "../config";
+import { PacketInfo, ApplicationData } from "./types";
+export declare class ParseClient extends TisuraBase {
+    constructor(config: TisuraConfig);
+    getPackets(): Promise<PacketInfo[]>;
+    getAppData(): Promise<ApplicationData[]>;
+}

package/dist/parse/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseClient = void 0;
+const config_1 = require("../config");
+const parser_1 = require("./parser");
+const db_1 = require("./db");
+class ParseClient extends config_1.TisuraBase {
+    constructor(config) {
+        super(config);
+    }
+    async getPackets() {
+        const pool = this.getPool();
+        const packets = await (0, db_1.readPacketsFromDb)(pool);
+        return packets;
+    }
+    async getAppData() {
+        const packets = await this.getPackets();
+        const parser = new parser_1.Parser(packets, this.config.tlsVersion);
+        const appData = parser.run();
+        return appData;
+    }
+}
+exports.ParseClient = ParseClient;

package/dist/parse/parser.d.ts

@@ -0,0 +1,55 @@
+import { PacketInfo, Stream, TLSRecord, ApplicationData } from "./types";
+export declare class Parser {
+    private packets;
+    private tlsVersion?;
+    streams: Stream[];
+    records: TLSRecord[];
+    appData: ApplicationData[];
+    /**
+     * In TLS 1.2, we track a client sequence number for Application Data records
+     */
+    clientSeqNum: number;
+    constructor(packets: PacketInfo[], tlsVersion?: string);
+    /**
+     * Run the parser, orchestrating the steps:
+     * 1) Reassemble TCP streams and parse out TLS records
+     * 2) Combine all records into a single list (ordered by time)
+     * 3) Filter to find TLS Application Data
+     */
+    run(): ApplicationData[];
+    /**
+     * Reassemble TCP packets into streams and parse TLS records simultaneously
+     */
+    private reassembleAndParse;
+    /**
+     * Combine all parsed records from the streams into one flat list (sorted by time).
+     */
+    private combineStreams;
+    /**
+     * Extract TLS parameters (e.g., random, cipher_suite) from a Handshake record
+     * if it's ClientHello or ServerHello.
+     *
+     * - If ClientHello, returns [clientRandom, null]
+     * - If ServerHello, returns [serverRandom, cipherSuiteNumber]
+     */
+    private extractTlsParams;
+    /**
+     * Filter out only TLS Application Data records (0x17).
+     * Includes logic for TLS 1.2 vs. TLS 1.3 as per the Python version.
+     */
+    private filterAppData;
+    /**
+     * Get a directed stream ID from a given packet.
+     * Returns a tuple: ((srcIp, srcPort), (dstIp, dstPort))
+     * or null if not TCP.
+     */
+    private getDirectedStreamId;
+    /**
+     * Convert a StreamID to a string for use as a Map key.
+     */
+    private streamIdToString;
+    /**
+     * Concatenate two Uint8Arrays
+     */
+    private concatUint8Arrays;
+}

package/dist/parse/parser.js

@@ -0,0 +1,348 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Parser = void 0;
+const HEADER_LENGTH = 5;
+class Parser {
+    packets;
+    tlsVersion;
+    // Internal state
+    streams = [];
+    records = [];
+    appData = [];
+    /**
+     * In TLS 1.2, we track a client sequence number for Application Data records
+     */
+    clientSeqNum = 0;
+    constructor(packets, tlsVersion) {
+        this.packets = packets;
+        this.tlsVersion = tlsVersion;
+    }
+    /**
+     * Run the parser, orchestrating the steps:
+     * 1) Reassemble TCP streams and parse out TLS records
+     * 2) Combine all records into a single list (ordered by time)
+     * 3) Filter to find TLS Application Data
+     */
+    run() {
+        this.streams = this.reassembleAndParse();
+        this.records = this.combineStreams();
+        this.appData = this.filterAppData();
+        return this.appData;
+    }
+    /**
+     * Reassemble TCP packets into streams and parse TLS records simultaneously
+     */
+    reassembleAndParse() {
+        // Use a Map keyed by the stream ID stringified.
+        // (Alternatively, you could store by the actual tuple, but strings are simpler.)
+        const partialRecords = new Map();
+        // Map of streamIDString -> Stream
+        const streamsMap = new Map();
+        for (const pkt of this.packets) {
+            if (pkt.protocol !== "TCP") {
+                continue;
+            }
+            const streamId = this.getDirectedStreamId(pkt);
+            if (!streamId) {
+                continue;
+            }
+            const streamIdKey = this.streamIdToString(streamId);
+            if (!partialRecords.has(streamIdKey)) {
+                partialRecords.set(streamIdKey, {
+                    data: new Uint8Array(0),
+                    firstTime: null,
+                    lastTime: null,
+                    neededLength: null,
+                });
+            }
+            if (!streamsMap.has(streamIdKey)) {
+                streamsMap.set(streamIdKey, { records: [], streamId });
+            }
+            const partial = partialRecords.get(streamIdKey);
+            const pktTime = pkt.timestamp;
+            // Append new data
+            partial.data = this.concatUint8Arrays(partial.data, pkt.payload);
+            partial.lastTime = pktTime;
+            if (partial.firstTime === null) {
+                partial.firstTime = pktTime;
+            }
+            // Process complete records
+            // We need at least 5 bytes to parse the record header (TLS).
+            while (partial.data.length >= HEADER_LENGTH) {
+                // If we haven't identified the record length yet
+                if (partial.neededLength === null) {
+                    const contentType = partial.data[0];
+                    // The total TLS record length is in bytes 3-4 (big-endian).
+                    const length = (partial.data[3] << 8) | partial.data[4];
+                    partial.neededLength = HEADER_LENGTH + length; // header (5) + payload
+                }
+                // If we have a complete record
+                if (partial.data.length >= partial.neededLength) {
+                    const recordData = partial.data.slice(0, partial.neededLength);
+                    const contentType = recordData[0];
+                    const record = {
+                        fullRecord: recordData,
+                        contentType,
+                        streamId,
+                        firstPacketTime: partial.firstTime,
+                        lastPacketTime: partial.lastTime,
+                    };
+                    if (contentType === 0x16) {
+                        // Handshake
+                        const handshakeType = recordData.length > 5 ? recordData[5] : null;
+                        console.log(`[PARSER] Found handshake type: ${handshakeType}`);
+                        if (handshakeType === 2) {
+                            // ServerHello
+                            console.log(`[PARSER] ServerHello in stream ${this.streamIdToString(streamId)}`);
+                        }
+                    }
+                    console.log(`[PARSER] New record: type=0x${contentType.toString(16).padStart(2, "0")}, stream=${this.streamIdToString(streamId)}`);
+                    console.log(`[PARSER] Time span: ${partial.firstTime} -> ${partial.lastTime}`);
+                    // Add record to the corresponding Stream
+                    const streamObj = streamsMap.get(streamIdKey);
+                    streamObj.records.push(record);
+                    // Remove this record's data
+                    partial.data = partial.data.slice(partial.neededLength);
+                    // Reset neededLength
+                    partial.neededLength = null;
+                    // Reset first_time to the last_time for the next record
+                    partial.firstTime = partial.lastTime;
+                }
+                else {
+                    // Need more data for this record
+                    break;
+                }
+            }
+        }
+        // Return an array of Streams
+        return Array.from(streamsMap.values());
+    }
+    /**
+     * Combine all parsed records from the streams into one flat list (sorted by time).
+     */
+    combineStreams() {
+        const combinedRecords = this.streams.flatMap((stream) => stream.records);
+        // Sort by last_packet_time
+        combinedRecords.sort((a, b) => a.lastPacketTime - b.lastPacketTime);
+        return combinedRecords;
+    }
+    /**
+     * Extract TLS parameters (e.g., random, cipher_suite) from a Handshake record
+     * if it's ClientHello or ServerHello.
+     *
+     * - If ClientHello, returns [clientRandom, null]
+     * - If ServerHello, returns [serverRandom, cipherSuiteNumber]
+     */
+    extractTlsParams(handshakeRecord) {
+        // Handshake layer starts after the first 5 bytes (TLS header)
+        const hsData = handshakeRecord.slice(5);
+        const hsType = hsData[0];
+        const hsLength = (hsData[1] << 16) | (hsData[2] << 8) | hsData[3];
+        const body = hsData.slice(4, 4 + hsLength);
+        // Typically 32 bytes of random data
+        const randomSize = 32;
+        const random = body.slice(2, 2 + randomSize);
+        if (hsType === 0x01) {
+            // ClientHello
+            return [random, null];
+        }
+        else if (hsType === 0x02) {
+            // ServerHello
+            const sessionIdLength = body[34];
+            const start = 35 + sessionIdLength;
+            const end = start + 2;
+            const cipherSuite = (body[start] << 8) | body[start + 1];
+            return [random, cipherSuite];
+        }
+        // If not recognized, return defaults
+        return [new Uint8Array(0), null];
+    }
+    /**
+     * Filter out only TLS Application Data records (0x17).
+     * Includes logic for TLS 1.2 vs. TLS 1.3 as per the Python version.
+     */
+    filterAppData() {
+        console.log(`[PARSER] Filtering ${this.records.length} TLS records for application data`);
+        const appData = [];
+        // ------------------------------------
+        // COMMON STATE
+        // ------------------------------------
+        let clientPort = null;
+        let clientToServerStreamId = null;
+        let tlsParams = {
+            clientRandom: new Uint8Array(0),
+            serverRandom: new Uint8Array(0),
+            cipherSuite: 0,
+        };
+        // TLS 1.2 tracking
+        let clientCcsSent = false;
+        let saveClientAppData = false;
+        // TLS 1.3 tracking
+        let clientAppDataAfterKeyUpdate = false;
+        this.clientSeqNum = 0;
+        for (let i = 0; i < this.records.length; i++) {
+            const record = this.records[i];
+            let isClient = false;
+            if (clientPort !== null) {
+                // If the source port matches the known client port
+                isClient = record.streamId[0][1] === clientPort;
+            }
+            // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            // TLS 1.2 LOGIC
+            // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            if (this.tlsVersion === "1.2") {
+                if (record.contentType === 0x16) {
+                    // Handshake
+                    const payload = record.fullRecord.slice(5);
+                    if (payload.length === 0) {
+                        continue;
+                    }
+                    const hsType = payload[0];
+                    if (hsType === 0x01) {
+                        // ClientHello
+                        clientPort = record.streamId[0][1];
+                        clientToServerStreamId = record.streamId;
+                        saveClientAppData = false;
+                        console.log(`[TLS 1.2] Found ClientHello from client port ${clientPort} at record #${i}`);
+                        const [clientRandom, _] = this.extractTlsParams(record.fullRecord);
+                        tlsParams = {
+                            clientRandom,
+                            serverRandom: new Uint8Array(0),
+                            cipherSuite: 0,
+                        };
+                    }
+                    else if (hsType === 0x02) {
+                        // ServerHello
+                        const [serverRandom, cipherSuite] = this.extractTlsParams(record.fullRecord);
+                        tlsParams = {
+                            clientRandom: tlsParams.clientRandom,
+                            serverRandom,
+                            cipherSuite: cipherSuite || 0,
+                        };
+                    }
+                    else {
+                        // Possibly an encrypted handshake message (e.g. Finished)
+                        if (isClient && clientCcsSent && !saveClientAppData) {
+                            // The next handshake record from client after CCS is the client Finished
+                            saveClientAppData = true;
+                            clientCcsSent = false;
+                            this.clientSeqNum = 0;
+                            console.log(`[TLS 1.2] Detected Client Finished (encrypted) at record #${i}. Now capturing client app data.`);
+                        }
+                    }
+                }
+                else if (record.contentType === 0x14) {
+                    // ChangeCipherSpec (TLS 1.2)
+                    if (isClient) {
+                        clientCcsSent = true;
+                        console.log(`[TLS 1.2] Client CCS at record #${i} => waiting for client Finished.`);
+                    }
+                }
+                else if (record.contentType === 0x17) {
+                    // Application Data
+                    if (isClient && saveClientAppData) {
+                        console.log(`[TLS 1.2] Capturing client app data at record #${i}`);
+                        // client→server app data
+                        this.clientSeqNum += 1;
+                        appData.push({
+                            tlsRecord: record,
+                            seqNum: this.clientSeqNum,
+                            tlsParams,
+                        });
+                    }
+                }
+                // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                // TLS 1.3 LOGIC
+                // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            }
+            else if (this.tlsVersion == "1.3") {
+                if (record.contentType === 0x16) {
+                    // Handshake
+                    const payload = record.fullRecord.slice(5);
+                    if (payload.length === 0)
+                        continue;
+                    const hsType = payload[0];
+                    if (hsType === 0x01) {
+                        // ClientHello
+                        clientPort = record.streamId[0][1];
+                        clientToServerStreamId = record.streamId;
+                    }
+                }
+                else if (record.contentType === 0x14) {
+                    // In TLS 1.3, 0x14 can be KeyUpdate or a dummy CCS
+                    const payload = record.fullRecord.slice(5);
+                    if (isClient && payload.length > 0 && payload[0] === 0x01) {
+                        // Suppose this indicates a KeyUpdate from client
+                        clientAppDataAfterKeyUpdate = true;
+                        saveClientAppData = false;
+                        this.clientSeqNum = 0;
+                    }
+                }
+                else if (record.contentType === 0x17) {
+                    // Application Data in TLS 1.3
+                    const isClientToServer = clientToServerStreamId &&
+                        record.streamId[0][0] === clientToServerStreamId[0][0] &&
+                        record.streamId[0][1] === clientToServerStreamId[0][1] &&
+                        record.streamId[1][0] === clientToServerStreamId[1][0] &&
+                        record.streamId[1][1] === clientToServerStreamId[1][1];
+                    if (isClientToServer && clientAppDataAfterKeyUpdate) {
+                        if (saveClientAppData) {
+                            appData.push({
+                                tlsRecord: record,
+                                seqNum: this.clientSeqNum,
+                                tlsParams: {
+                                    clientRandom: new Uint8Array(0),
+                                    serverRandom: new Uint8Array(0),
+                                    cipherSuite: 0,
+                                },
+                            });
+                            this.clientSeqNum++;
+                        }
+                        else {
+                            saveClientAppData = true;
+                            continue;
+                        }
+                    }
+                }
+            }
+            else {
+                console.log("[PARSER] Error: `tlsVersion` should be either 1.2 or 1.3.");
+            }
+        }
+        // Warn if we never identified a client port
+        if (clientPort === null) {
+            console.log("[PARSER] Warning: Could not identify client port");
+        }
+        return appData;
+    }
+    /**
+     * Get a directed stream ID from a given packet.
+     * Returns a tuple: ((srcIp, srcPort), (dstIp, dstPort))
+     * or null if not TCP.
+     */
+    getDirectedStreamId(pkt) {
+        if (pkt.protocol === "TCP") {
+            const src = [pkt.sourceIp, pkt.sourcePort];
+            const dst = [pkt.destinationIp, pkt.destinationPort];
+            return [src, dst];
+        }
+        return null;
+    }
+    /**
+     * Convert a StreamID to a string for use as a Map key.
+     */
+    streamIdToString(streamId) {
+        const [[srcIp, srcPort], [dstIp, dstPort]] = streamId;
+        return `${srcIp}:${srcPort}->${dstIp}:${dstPort}`;
+    }
+    /**
+     * Concatenate two Uint8Arrays
+     */
+    concatUint8Arrays(a, b) {
+        const c = new Uint8Array(a.length + b.length);
+        c.set(a, 0);
+        c.set(b, a.length);
+        return c;
+    }
+}
+exports.Parser = Parser;