tetherdb 0.1.0

package/dist/server/storage/storage.d.ts

@@ -0,0 +1,152 @@
+import type { AppStorage } from './app.js';
+import type { UserStorage } from './user.js';
+/**
+ * Configuration options and resource limits for storage engines.
+ */
+export interface StorageOptions {
+    /** Maximum number of active records allowed per table (default: 10,000). */
+    maxRecordsPerTable?: number;
+    /** Maximum allowed payload size in bytes for an individual record (default: 512 KB). */
+    maxRecordSizeBytes?: number;
+    /** Maximum allowed size in bytes for a single change batch payload (default: 5 MB). */
+    maxBatchSizeBytes?: number;
+    /** Maximum number of changelog entries retained per user before compaction (default: 1,000). */
+    maxChangelogEntries?: number;
+    /** Secret key used for signing session tokens. */
+    secret?: string;
+}
+/**
+ * Summary status information describing the storage engine and its contents.
+ */
+export interface StorageStatus {
+    /** Storage persistence type ('sqlite', 'file', or 'memory'). */
+    backend: string;
+    /** Storage base directory if disk-backed. */
+    baseDir?: string;
+    /** Number of registered user accounts. */
+    usersCount: number;
+    /** Number of registered applications. */
+    appsCount: number;
+    /** Detailed statistics per application if queried or available. */
+    apps?: Array<{
+        id: string;
+        tables: string[];
+    }>;
+}
+/**
+ * Result returned by a storage maintenance operation.
+ */
+export interface MaintenanceResult {
+    /** Maintenance action performed ('checkpoint', 'vacuum', 'prune'). */
+    action: 'checkpoint' | 'vacuum' | 'prune';
+    /** Target backend name. */
+    backend: string;
+    /** Optional target application ID. */
+    appId?: string;
+    /** Number of entries or database files affected, if applicable. */
+    affectedCount?: number;
+    /** Human-readable status message. */
+    message: string;
+}
+/**
+ * Top-level storage coordinator managing application namespaces and user accounts.
+ */
+export interface Storage {
+    /** Storage configuration options and resource limits. */
+    readonly options?: StorageOptions;
+    /**
+     * Creates/registers a new application namespace.
+     * Throws an error if an application with the specified ID already exists.
+     *
+     * @param id - Unique application identifier.
+     * @returns Created AppStorage handle.
+     * @throws Error if the application already exists.
+     */
+    createApp(id: string): Promise<AppStorage>;
+    /**
+     * Retrieves an application handle if it exists.
+     *
+     * @param id - Unique application identifier.
+     * @returns AppStorage handle or `undefined` if not found.
+     */
+    getApp(id: string): Promise<AppStorage | undefined>;
+    /**
+     * Lists all registered application handles.
+     *
+     * @returns Array of AppStorage handles.
+     */
+    getApps(): Promise<AppStorage[]>;
+    /**
+     * Creates a new user account with credentials.
+     * Throws an error if a user with the same username already exists.
+     *
+     * @param username - Username for the account.
+     * @param password - Account password.
+     * @returns Created UserStorage handle.
+     * @throws Error if the username is already registered.
+     */
+    createUser(username: string, password: string): Promise<UserStorage>;
+    /**
+     * Retrieves a user handle by user account ID.
+     *
+     * @param id - Unique user identifier.
+     * @returns UserStorage handle or `undefined` if not found.
+     */
+    getUser(id: string): Promise<UserStorage | undefined>;
+    /**
+     * Retrieves a user handle by username.
+     *
+     * @param username - User account username.
+     * @returns UserStorage handle or `undefined` if not found.
+     */
+    getUserByUsername(username: string): Promise<UserStorage | undefined>;
+    /**
+     * Retrieves a user handle by validating a session token.
+     *
+     * @param token - Signed session token.
+     * @returns UserStorage handle if token is valid and active, or `undefined`.
+     */
+    getUserByToken(token: string): Promise<UserStorage | undefined>;
+    /**
+     * Lists all user accounts.
+     *
+     * @returns Array of UserStorage handles.
+     */
+    getUsers(): Promise<UserStorage[]>;
+    /**
+     * Retrieves summary operational status of the storage backend.
+     *
+     * @param appId - Optional application identifier filter.
+     * @returns StorageStatus object.
+     */
+    getStatus(appId?: string): Promise<StorageStatus>;
+    /**
+     * Performs a WAL checkpoint on SQLite databases to truncate WAL files.
+     *
+     * @param appId - Optional target application identifier.
+     * @returns MaintenanceResult describing checkpoint outcome.
+     * @throws TetherServerError if checkpoint is not supported by this backend.
+     */
+    checkpoint(appId?: string): Promise<MaintenanceResult>;
+    /**
+     * Performs database vacuuming to reclaim disk space and defragment storage.
+     *
+     * @param appId - Optional target application identifier.
+     * @returns MaintenanceResult describing vacuum outcome.
+     * @throws TetherServerError if vacuum is not supported by this backend.
+     */
+    vacuum(appId?: string): Promise<MaintenanceResult>;
+    /**
+     * Prunes changelog history entries older than the retention threshold.
+     *
+     * @param appId - Optional target application identifier.
+     * @param keepCount - Optional maximum entries to retain per table/user (defaults to configured limit).
+     * @returns MaintenanceResult describing prune outcome.
+     */
+    prune(appId?: string, keepCount?: number): Promise<MaintenanceResult>;
+    /**
+     * Optional cleanup callback invoked when shutting down the storage engine.
+     */
+    close?(): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/server/storage/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/server/storage/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wFAAwF;IACxF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gGAAgG;IAChG,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,IAAI,CAAC,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,MAAM,EAAE,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC1C,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAElC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAEpD;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEjC;;;;;;;;OAQG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAErE;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAEtE;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAEhE;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEvD;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEtE;;OAEG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/server/storage/table.d.cts

@@ -0,0 +1,45 @@
+import type { ChangeRecord, SnapshotRecord, StoredRecord } from '../../shared/types.cjs';
+import type { AppStorage } from './app.cjs';
+import type { UserStorage } from './user.cjs';
+/**
+ * Table-scoped storage interface for record CRUD and batch mutation processing.
+ */
+export interface TableStorage {
+    /** Table name identifier. */
+    readonly name: string;
+    /** Parent application storage handle. */
+    readonly app: AppStorage;
+    /**
+     * Retrieves a single stored record by ID for a user.
+     *
+     * @param user - Target user handle.
+     * @param id - Record identifier.
+     * @returns Stored record or `undefined` if not found or deleted.
+     */
+    getRecord(user: UserStorage, id: string): Promise<StoredRecord | undefined>;
+    /**
+     * Retrieves all active (non-deleted) records in this table for a user.
+     *
+     * @param user - Target user handle.
+     * @returns Array of snapshot items.
+     */
+    getAllRecords(user: UserStorage): Promise<SnapshotRecord[]>;
+    /**
+     * Applies an array of mutation change operations to this table for a user.
+     *
+     * @param user - Target user handle.
+     * @param changes - Array of change records.
+     * @returns Applied changes and new sequence number.
+     */
+    applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+    /**
+     * Deletes this table and its data across all.
+     *
+     * @returns True if deleted successfully.
+     */
+    delete(): Promise<boolean>;
+}
+//# sourceMappingURL=table.d.ts.map

package/dist/server/storage/table.d.ts

@@ -0,0 +1,45 @@
+import type { ChangeRecord, SnapshotRecord, StoredRecord } from '../../shared/types.js';
+import type { AppStorage } from './app.js';
+import type { UserStorage } from './user.js';
+/**
+ * Table-scoped storage interface for record CRUD and batch mutation processing.
+ */
+export interface TableStorage {
+    /** Table name identifier. */
+    readonly name: string;
+    /** Parent application storage handle. */
+    readonly app: AppStorage;
+    /**
+     * Retrieves a single stored record by ID for a user.
+     *
+     * @param user - Target user handle.
+     * @param id - Record identifier.
+     * @returns Stored record or `undefined` if not found or deleted.
+     */
+    getRecord(user: UserStorage, id: string): Promise<StoredRecord | undefined>;
+    /**
+     * Retrieves all active (non-deleted) records in this table for a user.
+     *
+     * @param user - Target user handle.
+     * @returns Array of snapshot items.
+     */
+    getAllRecords(user: UserStorage): Promise<SnapshotRecord[]>;
+    /**
+     * Applies an array of mutation change operations to this table for a user.
+     *
+     * @param user - Target user handle.
+     * @param changes - Array of change records.
+     * @returns Applied changes and new sequence number.
+     */
+    applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+    /**
+     * Deletes this table and its data across all.
+     *
+     * @returns True if deleted successfully.
+     */
+    delete(): Promise<boolean>;
+}
+//# sourceMappingURL=table.d.ts.map

package/dist/server/storage/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/server/storage/table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAE5E;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE5D;;;;;;OAMG;IACH,YAAY,CACV,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,YAAY,EAAE,GACtB,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExD;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B"}

package/dist/server/storage/user.d.cts

@@ -0,0 +1,45 @@
+/**
+ * User storage handle managing account identity, credentials, tokens, and data lifecycles.
+ */
+export interface UserStorage {
+    /** Unique user account identifier. */
+    readonly id: string;
+    /** Normalized username. */
+    readonly username: string;
+    /** Epoch timestamp when the user account was created. */
+    readonly createdAt: number;
+    /**
+     * Verifies if the provided plaintext password matches the stored credentials.
+     *
+     * @param password - Plaintext password to verify.
+     * @returns True if password matches.
+     */
+    verifyPassword(password: string): Promise<boolean>;
+    /**
+     * Changes the user's password.
+     *
+     * @param newPassword - New plaintext password.
+     */
+    changePassword(newPassword: string): Promise<void>;
+    /**
+     * Creates a signed session token for this user.
+     *
+     * @param expiresInSeconds - Optional duration before token expires.
+     * @returns Signed token string.
+     */
+    createToken(expiresInSeconds?: number): Promise<string>;
+    /**
+     * Verifies if a session token is valid for this user.
+     *
+     * @param token - Token string to verify.
+     * @returns True if valid and not expired.
+     */
+    verifyToken(token: string): Promise<boolean>;
+    /**
+     * Deletes this user account and all of their data across all applications.
+     *
+     * @returns True if deleted successfully.
+     */
+    delete(): Promise<boolean>;
+}
+//# sourceMappingURL=user.d.ts.map

package/dist/server/storage/user.d.ts

@@ -0,0 +1,45 @@
+/**
+ * User storage handle managing account identity, credentials, tokens, and data lifecycles.
+ */
+export interface UserStorage {
+    /** Unique user account identifier. */
+    readonly id: string;
+    /** Normalized username. */
+    readonly username: string;
+    /** Epoch timestamp when the user account was created. */
+    readonly createdAt: number;
+    /**
+     * Verifies if the provided plaintext password matches the stored credentials.
+     *
+     * @param password - Plaintext password to verify.
+     * @returns True if password matches.
+     */
+    verifyPassword(password: string): Promise<boolean>;
+    /**
+     * Changes the user's password.
+     *
+     * @param newPassword - New plaintext password.
+     */
+    changePassword(newPassword: string): Promise<void>;
+    /**
+     * Creates a signed session token for this user.
+     *
+     * @param expiresInSeconds - Optional duration before token expires.
+     * @returns Signed token string.
+     */
+    createToken(expiresInSeconds?: number): Promise<string>;
+    /**
+     * Verifies if a session token is valid for this user.
+     *
+     * @param token - Token string to verify.
+     * @returns True if valid and not expired.
+     */
+    verifyToken(token: string): Promise<boolean>;
+    /**
+     * Deletes this user account and all of their data across all applications.
+     *
+     * @returns True if deleted successfully.
+     */
+    delete(): Promise<boolean>;
+}
+//# sourceMappingURL=user.d.ts.map

package/dist/server/storage/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../../src/server/storage/user.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnD;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,WAAW,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExD;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B"}

package/dist/server/sync.d.cts

@@ -0,0 +1,67 @@
+import type { WebSocket } from 'ws';
+import { type ClientMessage } from '../shared/types.cjs';
+import type { RateLimiter } from './rate-limiter.cjs';
+import type { TetherLogger } from './server.cjs';
+import type { Storage } from './storage/storage.cjs';
+/**
+ * Configuration options for the WebSocket synchronization coordinator.
+ */
+export interface SyncOptions {
+    /** Maximum number of concurrent active connections allowed per user channel (defaults to 20). */
+    maxConcurrentConnectionsPerUser?: number;
+    /** Maximum duration in milliseconds to wait for authentication before terminating socket (defaults to 10,000ms). */
+    authTimeoutMs?: number;
+    /** Optional rate limiter for connection handshakes and invalid token tracking. */
+    rateLimiter?: RateLimiter | null;
+    /** Optional logger instance (or null to suppress internal error logs). */
+    logger?: TetherLogger | null;
+}
+/**
+ * Real-time WebSocket synchronization coordinator managing authentication handshakes,
+ * snapshot/diff delivery, change ingestion, acknowledgments, and peer broadcasts per application and user.
+ */
+export declare class Sync {
+    private readonly storage;
+    private readonly maxConcurrentConnectionsPerUser;
+    private readonly authTimeoutMs;
+    private readonly rateLimiter;
+    private readonly logger;
+    private readonly userClients;
+    private readonly webSocketToClient;
+    private readonly pendingAuthTimers;
+    private readonly webSocketToIp;
+    /**
+     * Initializes a new Sync coordinator instance.
+     *
+     * @param storage - Pluggable backend storage engine.
+     * @param options - Configuration options for concurrency limits, auth timeout, and rate limiting.
+     */
+    constructor(storage: Storage, options?: SyncOptions);
+    /**
+     * Total number of currently active authenticated WebSocket client connections.
+     */
+    get connectedClientsCount(): number;
+    /**
+     * Handles an incoming WebSocket connection, binding message, error, and disconnection events.
+     *
+     * @param webSocket - Active WebSocket connection.
+     * @param clientIp - Remote client IP address.
+     */
+    handleConnection(webSocket: WebSocket, clientIp?: string): void;
+    /**
+     * Routes and executes incoming client protocol messages.
+     *
+     * @param webSocket - The connection that sent the message.
+     * @param msg - Parsed client protocol message.
+     */
+    handleMessage(webSocket: WebSocket, msg: ClientMessage): Promise<void>;
+    private handleAuthMessage;
+    private handleChangeBatchMessage;
+    private handlePingMessage;
+    private cleanupConnection;
+    private send;
+    private performSync;
+    private getAppSnapshot;
+    private broadcastToAppUser;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/server/sync.d.ts

@@ -0,0 +1,67 @@
+import type { WebSocket } from 'ws';
+import { type ClientMessage } from '../shared/types.js';
+import type { RateLimiter } from './rate-limiter.js';
+import type { TetherLogger } from './server.js';
+import type { Storage } from './storage/storage.js';
+/**
+ * Configuration options for the WebSocket synchronization coordinator.
+ */
+export interface SyncOptions {
+    /** Maximum number of concurrent active connections allowed per user channel (defaults to 20). */
+    maxConcurrentConnectionsPerUser?: number;
+    /** Maximum duration in milliseconds to wait for authentication before terminating socket (defaults to 10,000ms). */
+    authTimeoutMs?: number;
+    /** Optional rate limiter for connection handshakes and invalid token tracking. */
+    rateLimiter?: RateLimiter | null;
+    /** Optional logger instance (or null to suppress internal error logs). */
+    logger?: TetherLogger | null;
+}
+/**
+ * Real-time WebSocket synchronization coordinator managing authentication handshakes,
+ * snapshot/diff delivery, change ingestion, acknowledgments, and peer broadcasts per application and user.
+ */
+export declare class Sync {
+    private readonly storage;
+    private readonly maxConcurrentConnectionsPerUser;
+    private readonly authTimeoutMs;
+    private readonly rateLimiter;
+    private readonly logger;
+    private readonly userClients;
+    private readonly webSocketToClient;
+    private readonly pendingAuthTimers;
+    private readonly webSocketToIp;
+    /**
+     * Initializes a new Sync coordinator instance.
+     *
+     * @param storage - Pluggable backend storage engine.
+     * @param options - Configuration options for concurrency limits, auth timeout, and rate limiting.
+     */
+    constructor(storage: Storage, options?: SyncOptions);
+    /**
+     * Total number of currently active authenticated WebSocket client connections.
+     */
+    get connectedClientsCount(): number;
+    /**
+     * Handles an incoming WebSocket connection, binding message, error, and disconnection events.
+     *
+     * @param webSocket - Active WebSocket connection.
+     * @param clientIp - Remote client IP address.
+     */
+    handleConnection(webSocket: WebSocket, clientIp?: string): void;
+    /**
+     * Routes and executes incoming client protocol messages.
+     *
+     * @param webSocket - The connection that sent the message.
+     * @param msg - Parsed client protocol message.
+     */
+    handleMessage(webSocket: WebSocket, msg: ClientMessage): Promise<void>;
+    private handleAuthMessage;
+    private handleChangeBatchMessage;
+    private handlePingMessage;
+    private cleanupConnection;
+    private send;
+    private performSync;
+    private getAppSnapshot;
+    private broadcastToAppUser;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/server/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/server/sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAMnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAQpD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iGAAiG;IACjG,+BAA+B,CAAC,EAAE,MAAM,CAAC;IACzC,oHAAoH;IACpH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,+BAA+B,CAAS;IACzD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwC;IACpE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsC;IACxE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwC;IAC1E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgC;IAE9D;;;;;OAKG;IACH,YAAY,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,EAOtD;IAED;;OAEG;IACH,IAAI,qBAAqB,IAAI,MAAM,CAElC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,SAAc,GAAG,IAAI,CA2EnE;IAED;;;;;OAKG;IACG,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B3E;YAIa,iBAAiB;YA0HjB,wBAAwB;IA+DtC,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,IAAI;YAME,WAAW;YA8CX,cAAc;IAa5B,OAAO,CAAC,kBAAkB;CAgB3B"}

package/dist/server/validate.d.cts

@@ -0,0 +1,113 @@
+/**
+ * Security, input validation, and sanitization utilities for the TetherDB server.
+ * Protects server-side storage and synchronization from injection and traversal attacks.
+ *
+ * @module tetherdb/server/validate
+ */
+/** Minimum allowed username character length. */
+export declare const MIN_USERNAME_LENGTH = 4;
+/** Maximum allowed username character length. */
+export declare const MAX_USERNAME_LENGTH = 128;
+/** Minimum allowed password character length. */
+export declare const MIN_PASSWORD_LENGTH = 4;
+/** Maximum allowed password character length. */
+export declare const MAX_PASSWORD_LENGTH = 512;
+/** Maximum allowable future timestamp drift in milliseconds (5 minutes). */
+export declare const MAX_FUTURE_TIMESTAMP_DRIFT_MS: number;
+/**
+ * Validates a change timestamp, ensuring it is a valid finite epoch number
+ * and does not exceed the maximum allowable future drift.
+ *
+ * @param timestamp - The epoch timestamp in milliseconds.
+ * @param maxFutureDriftMs - Optional maximum allowable future drift in ms (defaults to 5 minutes).
+ * @returns The validated timestamp.
+ * @throws TetherServerError if timestamp is not finite, is non-positive, or exceeds drift bounds.
+ */
+export declare function validateTimestamp(timestamp: number, maxFutureDriftMs?: number): number;
+/**
+ * Validates a user ID string ensuring it is safe for filesystem use.
+ *
+ * @param userId - The user ID to validate.
+ * @returns The validated user ID.
+ * @throws TetherServerError if the user ID is invalid or contains unsafe characters.
+ */
+export declare function validateUserId(userId: string): string;
+/**
+ * Validates an application namespace identifier.
+ *
+ * @param appId - The application ID to validate.
+ * @returns The validated application ID.
+ * @throws TetherServerError if the application ID is invalid.
+ */
+export declare function validateAppId(appId: string): string;
+/**
+ * Validates a table name ensuring it is safe for filesystem use.
+ *
+ * @param tableName - The table name to validate.
+ * @returns The validated table name.
+ * @throws TetherServerError if the table name is invalid.
+ */
+export declare function validateTableName(tableName: string): string;
+/**
+ * Validates a record ID ensuring it is a non-empty string within size limits.
+ *
+ * @param id - The record identifier to validate.
+ * @returns The validated record ID.
+ * @throws TetherServerError if the record ID is invalid or exceeds max length.
+ */
+export declare function validateRecordId(id: string): string;
+/**
+ * Normalizes a username by trimming whitespace and converting to lowercase.
+ *
+ * @param username - The raw username string.
+ * @returns The normalized username (lowercase and trimmed).
+ */
+export declare function normalizeUsername(username: string): string;
+/**
+ * Validates and normalizes a username for account creation or authentication.
+ * Usernames must be between 4 and 128 characters long.
+ *
+ * @param username - The username to validate.
+ * @returns The validated and normalized username (trimmed and lowercase).
+ * @throws TetherServerError if the username is invalid or out of length bounds.
+ */
+export declare function validateUsername(username: string): string;
+/**
+ * Normalizes a password by trimming surrounding whitespace.
+ *
+ * @param password - The raw password string.
+ * @returns The normalized password (trimmed).
+ */
+export declare function normalizePassword(password: string): string;
+/**
+ * Validates a password for user account creation or authentication.
+ *
+ * @param password - The password string to validate.
+ * @returns The validated password.
+ * @throws TetherServerError if the password is not a string, is empty, or exceeds length bounds.
+ */
+export declare function validatePassword(password: string): string;
+/**
+ * Validates a client correlation or batch ID.
+ *
+ * @param id - The batch or client identifier.
+ * @param name - Identifier type description (e.g. 'batchId', 'clientId').
+ * @returns The validated ID.
+ * @throws TetherServerError if the identifier format is invalid.
+ */
+export declare function validateIdentifier(id: string, name?: string): string;
+/**
+ * Estimates the byte size of an arbitrary JavaScript value or object when serialized.
+ *
+ * @param value - The value to measure.
+ * @returns Size in bytes.
+ */
+export declare function calculateByteSize(value: unknown): number;
+/**
+ * Calculates a 2-character hex/hash bucket for directory partitioning by user ID.
+ *
+ * @param userId - Unique user identifier.
+ * @returns 2-character bucket string (e.g. 'f4', '0a').
+ */
+export declare function getUserBucket(userId: string): string;
+//# sourceMappingURL=validate.d.ts.map