tetherdb 0.1.0

package/dist/server/lock.d.cts

@@ -0,0 +1,56 @@
+/**
+ * Metadata recorded inside the server lockfile.
+ */
+export interface ServerLockInfo {
+    /** Process identifier running the server. */
+    pid: number;
+    /** Port number the server is bound to. */
+    port: number;
+    /** Host interface the server is bound to. */
+    host: string;
+    /** Storage backend type ('sqlite', 'file', or 'memory'). */
+    backend: string;
+    /** Epoch timestamp when the server acquired the lock. */
+    startedAt: number;
+}
+/**
+ * Handle representing an active exclusive server lock.
+ */
+export interface ServerLockHandle {
+    /** Lock metadata information. */
+    readonly info: ServerLockInfo;
+    /** Path to the active lockfile on disk. */
+    readonly lockPath: string;
+    /** Releases the lock and removes the lockfile. */
+    release(): void;
+}
+/**
+ * Checks whether a given operating system process ID is currently alive.
+ *
+ * @param pid - Process ID to check.
+ * @returns `true` if the process is active; otherwise `false`.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Reads active server lock metadata from a storage base directory if present and live.
+ * Stale locks from terminated processes are ignored.
+ *
+ * @param baseDir - Storage base directory.
+ * @returns ServerLockInfo if an active server is running, or `null`.
+ */
+export declare function readServerLock(baseDir: string): ServerLockInfo | null;
+/**
+ * Acquires an exclusive server lock on the specified directory to prevent multiple instances
+ * from running against the same data storage.
+ *
+ * @param baseDir - Directory path where the lockfile will be maintained.
+ * @param details - Port, host, and backend details to write to the lockfile.
+ * @returns ServerLockHandle representing the active lock.
+ * @throws TetherServerError if another active server already holds the lock.
+ */
+export declare function acquireServerLock(baseDir: string, details: {
+    port: number;
+    host: string;
+    backend: string;
+}): ServerLockHandle;
+//# sourceMappingURL=lock.d.ts.map

package/dist/server/lock.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Metadata recorded inside the server lockfile.
+ */
+export interface ServerLockInfo {
+    /** Process identifier running the server. */
+    pid: number;
+    /** Port number the server is bound to. */
+    port: number;
+    /** Host interface the server is bound to. */
+    host: string;
+    /** Storage backend type ('sqlite', 'file', or 'memory'). */
+    backend: string;
+    /** Epoch timestamp when the server acquired the lock. */
+    startedAt: number;
+}
+/**
+ * Handle representing an active exclusive server lock.
+ */
+export interface ServerLockHandle {
+    /** Lock metadata information. */
+    readonly info: ServerLockInfo;
+    /** Path to the active lockfile on disk. */
+    readonly lockPath: string;
+    /** Releases the lock and removes the lockfile. */
+    release(): void;
+}
+/**
+ * Checks whether a given operating system process ID is currently alive.
+ *
+ * @param pid - Process ID to check.
+ * @returns `true` if the process is active; otherwise `false`.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Reads active server lock metadata from a storage base directory if present and live.
+ * Stale locks from terminated processes are ignored.
+ *
+ * @param baseDir - Storage base directory.
+ * @returns ServerLockInfo if an active server is running, or `null`.
+ */
+export declare function readServerLock(baseDir: string): ServerLockInfo | null;
+/**
+ * Acquires an exclusive server lock on the specified directory to prevent multiple instances
+ * from running against the same data storage.
+ *
+ * @param baseDir - Directory path where the lockfile will be maintained.
+ * @param details - Port, host, and backend details to write to the lockfile.
+ * @returns ServerLockHandle representing the active lock.
+ * @throws TetherServerError if another active server already holds the lock.
+ */
+export declare function acquireServerLock(baseDir: string, details: {
+    port: number;
+    host: string;
+    backend: string;
+}): ServerLockHandle;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/server/lock.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASnD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAarE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvD,gBAAgB,CAyDlB"}

package/dist/server/rate-limiter.d.cts

@@ -0,0 +1,81 @@
+/**
+ * Configuration options for a RateLimiter instance.
+ */
+export interface RateLimiterOptions {
+    /** Time window in milliseconds (defaults to 60,000ms / 1 minute). */
+    windowMs?: number;
+    /** Maximum number of allowed requests within the time window. */
+    maxRequests?: number;
+    /** Number of consecutive failures before applying progressive backoff (defaults to 3). */
+    maxFailures?: number;
+    /** Initial backoff duration in milliseconds after exceeding maxFailures (defaults to 1,000ms). */
+    initialBackoffMs?: number;
+    /** Maximum backoff duration in milliseconds (defaults to 900,000ms / 15 minutes). */
+    maxBackoffMs?: number;
+    /** Maximum number of tracking entries kept in memory before evicting (defaults to 10,000). */
+    maxEntries?: number;
+}
+/**
+ * In-memory sliding-window rate limiter with failure-based exponential backoff.
+ */
+export declare class RateLimiter {
+    private readonly store;
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly maxFailures;
+    private readonly initialBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly maxEntries;
+    /**
+     * Initializes a new RateLimiter instance.
+     *
+     * @param options - Configuration options for window size, request limits, and backoff.
+     */
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Returns the current number of tracked keys in memory.
+     */
+    get size(): number;
+    /**
+     * Checks whether the given key is currently rate limited or blocked by backoff cooldown.
+     *
+     * @param key - Identifier (e.g. IP address or username).
+     * @param now - Current timestamp in milliseconds (defaults to Date.now()).
+     * @returns `true` if requests for this key are limited; `false` otherwise.
+     */
+    isLimited(key: string, now?: number): boolean;
+    /**
+     * Consumes one attempt for the given key if not currently limited.
+     *
+     * @param key - Identifier.
+     * @param now - Current timestamp in milliseconds.
+     * @returns `true` if request was allowed and consumed; `false` if rate limited.
+     */
+    consume(key: string, now?: number): boolean;
+    /**
+     * Records a failed attempt for the given key and applies progressive exponential backoff.
+     *
+     * @param key - Identifier.
+     * @param now - Current timestamp in milliseconds.
+     * @returns Cooldown duration in milliseconds if blocked, or 0 if under failure threshold.
+     */
+    recordFailure(key: string, now?: number): number;
+    /**
+     * Resets all failure counters and request tracking for the given key.
+     *
+     * @param key - Identifier to reset.
+     */
+    reset(key: string): void;
+    /**
+     * Clears all stored rate limit entries.
+     */
+    clear(): void;
+    /**
+     * Purges expired entries from the internal store.
+     *
+     * @param now - Current timestamp in milliseconds.
+     */
+    cleanup(now?: number): void;
+    private setEntry;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/server/rate-limiter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Configuration options for a RateLimiter instance.
+ */
+export interface RateLimiterOptions {
+    /** Time window in milliseconds (defaults to 60,000ms / 1 minute). */
+    windowMs?: number;
+    /** Maximum number of allowed requests within the time window. */
+    maxRequests?: number;
+    /** Number of consecutive failures before applying progressive backoff (defaults to 3). */
+    maxFailures?: number;
+    /** Initial backoff duration in milliseconds after exceeding maxFailures (defaults to 1,000ms). */
+    initialBackoffMs?: number;
+    /** Maximum backoff duration in milliseconds (defaults to 900,000ms / 15 minutes). */
+    maxBackoffMs?: number;
+    /** Maximum number of tracking entries kept in memory before evicting (defaults to 10,000). */
+    maxEntries?: number;
+}
+/**
+ * In-memory sliding-window rate limiter with failure-based exponential backoff.
+ */
+export declare class RateLimiter {
+    private readonly store;
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly maxFailures;
+    private readonly initialBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly maxEntries;
+    /**
+     * Initializes a new RateLimiter instance.
+     *
+     * @param options - Configuration options for window size, request limits, and backoff.
+     */
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Returns the current number of tracked keys in memory.
+     */
+    get size(): number;
+    /**
+     * Checks whether the given key is currently rate limited or blocked by backoff cooldown.
+     *
+     * @param key - Identifier (e.g. IP address or username).
+     * @param now - Current timestamp in milliseconds (defaults to Date.now()).
+     * @returns `true` if requests for this key are limited; `false` otherwise.
+     */
+    isLimited(key: string, now?: number): boolean;
+    /**
+     * Consumes one attempt for the given key if not currently limited.
+     *
+     * @param key - Identifier.
+     * @param now - Current timestamp in milliseconds.
+     * @returns `true` if request was allowed and consumed; `false` if rate limited.
+     */
+    consume(key: string, now?: number): boolean;
+    /**
+     * Records a failed attempt for the given key and applies progressive exponential backoff.
+     *
+     * @param key - Identifier.
+     * @param now - Current timestamp in milliseconds.
+     * @returns Cooldown duration in milliseconds if blocked, or 0 if under failure threshold.
+     */
+    recordFailure(key: string, now?: number): number;
+    /**
+     * Resets all failure counters and request tracking for the given key.
+     *
+     * @param key - Identifier to reset.
+     */
+    reset(key: string): void;
+    /**
+     * Clears all stored rate limit entries.
+     */
+    clear(): void;
+    /**
+     * Purges expired entries from the internal store.
+     *
+     * @param now - Current timestamp in milliseconds.
+     */
+    cleanup(now?: number): void;
+    private setEntry;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/server/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/server/rate-limiter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;;OAIG;IACH,YAAY,OAAO,GAAE,kBAAuB,EAO3C;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,OAAO,CAchD;IAED;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,OAAO,CAsB9C;IAED;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,MAAM,CAyBnD;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEvB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;;;OAIG;IACH,OAAO,CAAC,GAAG,SAAa,GAAG,IAAI,CAM9B;IAID,OAAO,CAAC,QAAQ;CAYjB"}

package/dist/server/server.d.cts

@@ -0,0 +1,206 @@
+import * as http from 'node:http';
+import { WebSocketServer } from 'ws';
+import type { Storage, UserStorage } from './storage/index.cjs';
+import { Sync } from './sync.cjs';
+/**
+ * Rate limiting and resource control options for authentication endpoints and sync streams.
+ */
+export interface RateLimitOptions {
+    /** Maximum login attempts per IP within the time window (defaults to 100). */
+    ipLoginMaxRequests?: number;
+    /** Maximum login attempts per target username within the time window (defaults to 20). */
+    userLoginMaxRequests?: number;
+    /** Maximum registration attempts per IP within the time window (defaults to 100). */
+    ipRegisterMaxRequests?: number;
+    /** Maximum WebSocket connection handshakes per IP within the time window (defaults to 100). */
+    ipSyncMaxRequests?: number;
+    /** Maximum concurrent active WebSocket 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;
+    /** Sliding window duration in milliseconds (defaults to 60,000ms / 1 minute). */
+    windowMs?: number;
+    /** Consecutive failed attempts before progressive backoff begins (defaults to 5). */
+    maxFailures?: number;
+    /** Initial backoff duration in milliseconds (defaults to 1,000ms). */
+    initialBackoffMs?: number;
+    /** Maximum backoff duration in milliseconds (defaults to 900,000ms / 15 minutes). */
+    maxBackoffMs?: number;
+}
+/**
+ * Options for configuring Cross-Origin Resource Sharing (CORS) on HTTP endpoints.
+ */
+export interface CorsOptions {
+    /**
+     * Allowed origin(s). Can be `'*'` for unrestricted access, a specific origin string (e.g. `'https://example.com'`),
+     * an array of allowed origin strings, `true` to reflect the request's `Origin` header, or `false` to disable CORS headers.
+     * Defaults to `'*'`.
+     */
+    origin?: string | string[] | boolean;
+    /** Whether to set `Access-Control-Allow-Credentials: true` (defaults to false). */
+    credentials?: boolean;
+    /** Allowed request headers for preflight OPTIONS checks (defaults to `['Content-Type', 'Authorization']`). */
+    allowedHeaders?: string[];
+    /** Exposed response headers (Access-Control-Expose-Headers). */
+    exposedHeaders?: string[];
+    /** Maximum age in seconds to cache preflight responses (Access-Control-Max-Age). */
+    maxAge?: number;
+}
+/**
+ * Pluggable logger interface for TetherServer logging.
+ */
+export interface TetherLogger {
+    /** Logs debug information. */
+    debug(message: string, ...args: unknown[]): void;
+    /** Logs operational information. */
+    info(message: string, ...args: unknown[]): void;
+    /** Logs warning conditions. */
+    warn(message: string, ...args: unknown[]): void;
+    /** Logs error conditions. */
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Configuration options for the TetherServer.
+ */
+export interface TetherServerOptions {
+    /** Custom storage instance. Defaults to MemoryStorage if not defined. */
+    storage?: Storage;
+    /** Base path for HTTP REST endpoints (defaults to ''). */
+    basePath?: string;
+    /** Path for WebSocket upgrade requests (defaults to '/sync'). */
+    webSocketPath?: string;
+    /** Whether user self-registration is allowed via `/auth/register` (defaults to true). */
+    allowRegistration?: boolean;
+    /** Rate limiting options for auth and sync endpoints, or `false` to disable rate limiting (defaults to true). */
+    rateLimiting?: boolean | RateLimitOptions;
+    /** Whether to trust the `X-Forwarded-For` header for resolving client IP addresses (defaults to false). */
+    trustProxy?: boolean;
+    /** CORS options for HTTP endpoints, `false` to disable CORS headers, or `true` for default permissive CORS (defaults to true). */
+    cors?: boolean | CorsOptions;
+    /** Optional custom logger instance, or `false` to silence internal server logs (defaults to `console`). */
+    logger?: TetherLogger | false;
+}
+/**
+ * Options for starting the standard server launcher.
+ */
+export interface StartServerOptions extends TetherServerOptions {
+    /** Port number to bind (defaults to 8080 or PORT environment variable). */
+    port?: number;
+    /** Host interface to bind (defaults to '0.0.0.0'). */
+    host?: string;
+}
+/**
+ * Result returned when launching a server using `startServer()`.
+ */
+export interface RunningServer {
+    /** The TetherServer instance. */
+    server: TetherServer;
+    /** The running Node.js HTTP server instance. */
+    httpServer: http.Server;
+    /** Bound port number. */
+    port: number;
+    /** Bound host address. */
+    host: string;
+    /** Closes both HTTP and WebSocket server cleanly. */
+    close(): Promise<void>;
+}
+/**
+ * Starts a complete standalone HTTP & WebSocket synchronization server.
+ *
+ * @param options - Start options including port, host, storage, and limits.
+ * @returns Handle to the running server.
+ */
+export declare function startServer(options?: StartServerOptions): Promise<RunningServer>;
+/**
+ * Unified HTTP and WebSocket server handling authentication endpoints (`/auth/register`, `/auth/login`)
+ * and real-time streaming connections (`/sync`).
+ */
+export declare class TetherServer {
+    /** Underlying storage engine for users, apps, and tables. */
+    readonly storage: Storage;
+    /** Real-time synchronization connection and broadcast coordinator. */
+    readonly sync: Sync;
+    /** Base path for HTTP REST endpoints. */
+    readonly basePath: string;
+    /** Path for WebSocket upgrade requests. */
+    readonly webSocketPath: string;
+    readonly trustProxy: boolean;
+    private readonly allowRegistration;
+    private readonly corsConfig;
+    private readonly logger;
+    private readonly ipLoginLimiter;
+    private readonly userLoginLimiter;
+    private readonly ipRegisterLimiter;
+    private _httpServer;
+    private _webSocketServer;
+    private lockHandle;
+    /**
+     * Initializes a new TetherServer instance.
+     *
+     * @param options - Configuration options for storage, endpoints, and rate limiting.
+     */
+    constructor(options?: TetherServerOptions);
+    /**
+     * Active Node.js HTTP server instance, or `null` if not listening.
+     */
+    get httpServer(): http.Server | null;
+    /**
+     * Active WebSocketServer instance, or `null` if not listening.
+     */
+    get webSocketServer(): WebSocketServer | null;
+    /**
+     * Declares an application and its tables.
+     * Registers the application and any declared tables if not already present.
+     *
+     * @param appId - Application identifier.
+     * @param tables - Array of table names.
+     */
+    declareApp(appId: string, tables?: string[]): Promise<void>;
+    /**
+     * Declares a user account with the specified username and password.
+     * Creates the user if not already registered, or updates the existing user's password.
+     *
+     * @param username - Username for the account.
+     * @param password - Plaintext password for the account.
+     * @returns UserStorage handle for the declared user.
+     */
+    declareUser(username: string, password: string): Promise<UserStorage>;
+    /**
+     * Attaches WebSocket synchronization handling to an existing HTTP server.
+     *
+     * @param server - The HTTP server instance to attach to.
+     */
+    attach(server: http.Server): void;
+    /**
+     * Starts the HTTP and WebSocket server listening on the specified port and host.
+     *
+     * @param port - Port number to bind. Defaults to 8080.
+     * @param host - Host interface to bind. Defaults to '0.0.0.0'.
+     * @returns The active Node.js HTTP server instance.
+     */
+    listen(port?: number, host?: string): Promise<http.Server>;
+    /**
+     * Closes active HTTP server and WebSocket server listeners.
+     */
+    close(): Promise<void>;
+    /**
+     * Handles incoming HTTP requests for authentication and discovery endpoints.
+     *
+     * @param req - Incoming HTTP request.
+     * @param res - Server HTTP response.
+     * @returns `true` if the request was handled by TetherDB; `false` if the path did not match.
+     */
+    handleHttpRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<boolean>;
+    private getCorsHeaders;
+    private sendJson;
+    private readJsonBody;
+    private handleOptions;
+    private handleHealth;
+    private handleReady;
+    private handleMetrics;
+    private handleRegister;
+    private handleLogin;
+    private readCredentials;
+    private getClientIp;
+}
+//# sourceMappingURL=server.d.ts.map