@qwickapps/server 1.4.0 → 1.5.0

package/dist/plugins/devices/stores/postgres-store.js

@@ -0,0 +1,199 @@
+/**
+ * PostgreSQL Device Store
+ *
+ * Device storage implementation using PostgreSQL.
+ * Supports multi-tenant isolation via org_id.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+/**
+ * Create a PostgreSQL device store
+ *
+ * @param config Configuration including a pg Pool instance
+ * @returns DeviceStore implementation
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { postgresDeviceStore } from '@qwickapps/server';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = postgresDeviceStore({ pool });
+ * ```
+ */
+export function postgresDeviceStore(config) {
+    const { pool: poolOrFn, tableName = 'devices', schema = 'public', autoCreateTables = true, } = config;
+    // Helper to get pool (supports lazy initialization via function)
+    const getPool = () => {
+        const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+        return pool;
+    };
+    const devicesTableFull = `"${schema}"."${tableName}"`;
+    return {
+        name: 'postgres',
+        async initialize() {
+            if (!autoCreateTables)
+                return;
+            // Create devices table
+            await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${devicesTableFull} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          org_id UUID,
+          user_id UUID,
+          adapter_type VARCHAR(50) NOT NULL,
+          name VARCHAR(255) NOT NULL,
+          token_hash VARCHAR(64) NOT NULL,
+          token_prefix VARCHAR(12),
+          token_expires_at TIMESTAMPTZ NOT NULL,
+          last_seen_at TIMESTAMPTZ,
+          last_ip INET,
+          is_active BOOLEAN DEFAULT true,
+          metadata JSONB DEFAULT '{}',
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW(),
+          deleted_at TIMESTAMPTZ
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_org ON ${devicesTableFull}(org_id) WHERE deleted_at IS NULL;
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_user ON ${devicesTableFull}(user_id) WHERE deleted_at IS NULL;
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_token ON ${devicesTableFull}(token_hash) WHERE is_active = true AND deleted_at IS NULL;
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_adapter ON ${devicesTableFull}(adapter_type);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_expires ON ${devicesTableFull}(token_expires_at) WHERE deleted_at IS NULL;
+      `);
+        },
+        async getById(id) {
+            const result = await getPool().query(`SELECT * FROM ${devicesTableFull} WHERE id = $1 AND deleted_at IS NULL`, [id]);
+            return result.rows[0] || null;
+        },
+        async getByTokenHash(tokenHash) {
+            const result = await getPool().query(`SELECT * FROM ${devicesTableFull}
+         WHERE token_hash = $1
+           AND is_active = true
+           AND deleted_at IS NULL
+           AND token_expires_at > NOW()`, [tokenHash]);
+            return result.rows[0] || null;
+        },
+        async create(input) {
+            const result = await getPool().query(`INSERT INTO ${devicesTableFull}
+         (org_id, user_id, adapter_type, name, token_hash, token_prefix, token_expires_at, metadata)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+         RETURNING *`, [
+                input.org_id || null,
+                input.user_id || null,
+                input.adapterType,
+                input.name,
+                input.tokenHash,
+                input.tokenPrefix,
+                input.tokenExpiresAt,
+                JSON.stringify(input.metadata || {}),
+            ]);
+            return result.rows[0];
+        },
+        async update(id, input) {
+            const updates = [];
+            const values = [];
+            let paramIndex = 1;
+            if (input.name !== undefined) {
+                updates.push(`name = $${paramIndex++}`);
+                values.push(input.name);
+            }
+            if (input.is_active !== undefined) {
+                updates.push(`is_active = $${paramIndex++}`);
+                values.push(input.is_active);
+            }
+            if (input.metadata !== undefined) {
+                updates.push(`metadata = $${paramIndex++}`);
+                values.push(JSON.stringify(input.metadata));
+            }
+            if (updates.length === 0) {
+                return this.getById(id);
+            }
+            updates.push(`updated_at = NOW()`);
+            values.push(id);
+            const result = await getPool().query(`UPDATE ${devicesTableFull}
+         SET ${updates.join(', ')}
+         WHERE id = $${paramIndex} AND deleted_at IS NULL
+         RETURNING *`, values);
+            return result.rows[0] || null;
+        },
+        async delete(id) {
+            // Soft delete
+            const result = await getPool().query(`UPDATE ${devicesTableFull}
+         SET deleted_at = NOW(), is_active = false, updated_at = NOW()
+         WHERE id = $1 AND deleted_at IS NULL`, [id]);
+            return (result.rowCount ?? 0) > 0;
+        },
+        async search(params) {
+            const { org_id, user_id, adapter_type, is_active, query, page = 1, limit = 20, sortBy = 'created_at', sortOrder = 'desc', } = params;
+            const conditions = ['deleted_at IS NULL'];
+            const values = [];
+            let paramIndex = 1;
+            if (org_id) {
+                conditions.push(`org_id = $${paramIndex++}`);
+                values.push(org_id);
+            }
+            if (user_id) {
+                conditions.push(`user_id = $${paramIndex++}`);
+                values.push(user_id);
+            }
+            if (adapter_type) {
+                conditions.push(`adapter_type = $${paramIndex++}`);
+                values.push(adapter_type);
+            }
+            if (is_active !== undefined) {
+                conditions.push(`is_active = $${paramIndex++}`);
+                values.push(is_active);
+            }
+            if (query) {
+                conditions.push(`LOWER(name) LIKE $${paramIndex++}`);
+                values.push(`%${query.toLowerCase()}%`);
+            }
+            const whereClause = `WHERE ${conditions.join(' AND ')}`;
+            // Validate sort column to prevent SQL injection
+            const validSortColumns = ['name', 'created_at', 'last_seen_at'];
+            const sortColumn = validSortColumns.includes(sortBy) ? sortBy : 'created_at';
+            const sortDir = sortOrder === 'asc' ? 'ASC' : 'DESC';
+            const offset = (page - 1) * limit;
+            // Get total count
+            const countResult = await getPool().query(`SELECT COUNT(*) FROM ${devicesTableFull} ${whereClause}`, values);
+            const countRow = countResult.rows[0];
+            const total = countRow ? parseInt(countRow.count, 10) : 0;
+            // Get devices
+            const result = await getPool().query(`SELECT * FROM ${devicesTableFull} ${whereClause}
+         ORDER BY ${sortColumn} ${sortDir}
+         LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`, [...values, limit, offset]);
+            return {
+                devices: result.rows,
+                total,
+                page,
+                limit,
+                totalPages: Math.ceil(total / limit),
+            };
+        },
+        async updateLastSeen(id, ip) {
+            if (ip) {
+                await getPool().query(`UPDATE ${devicesTableFull} SET last_seen_at = NOW(), last_ip = $1 WHERE id = $2`, [ip, id]);
+            }
+            else {
+                await getPool().query(`UPDATE ${devicesTableFull} SET last_seen_at = NOW() WHERE id = $1`, [id]);
+            }
+        },
+        async updateToken(id, tokenHash, tokenPrefix, expiresAt) {
+            const result = await getPool().query(`UPDATE ${devicesTableFull}
+         SET token_hash = $1, token_prefix = $2, token_expires_at = $3, updated_at = NOW()
+         WHERE id = $4 AND deleted_at IS NULL`, [tokenHash, tokenPrefix, expiresAt, id]);
+            return (result.rowCount ?? 0) > 0;
+        },
+        async cleanupExpired() {
+            // Deactivate expired tokens
+            const result = await getPool().query(`UPDATE ${devicesTableFull}
+         SET is_active = false, updated_at = NOW()
+         WHERE token_expires_at < NOW() AND is_active = true AND deleted_at IS NULL`);
+            return result.rowCount ?? 0;
+        },
+        async shutdown() {
+            // Pool is managed externally, nothing to do here
+        },
+    };
+}
+//# sourceMappingURL=postgres-store.js.map

package/dist/plugins/devices/stores/postgres-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-store.js","sourceRoot":"","sources":["../../../../src/plugins/devices/stores/postgres-store.ts"],"names":[],"mappings":"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"}

package/dist/plugins/devices/token-utils.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Device Token Utilities
+ *
+ * Utilities for generating, hashing, and verifying device tokens.
+ * Adapted from QwickForge's device-tokens implementation.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export interface DeviceTokenPair {
+    /** Raw token to return to client (store securely!) */
+    token: string;
+    /** Hashed token to store in database */
+    hash: string;
+    /** First 8 characters for identification */
+    prefix: string;
+}
+export interface TokenVerificationResult {
+    /** Whether the token is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Generate a cryptographically secure device token
+ *
+ * Returns both the raw token (to send to client) and the hash (to store in DB).
+ * The raw token should be shown to the user ONCE and never stored server-side.
+ *
+ * Token format: `<prefix>_<32 bytes base64url>`
+ *
+ * @param prefix - Token prefix for identification (e.g., 'qwf_dev', 'qwb_mob')
+ * @returns Token pair with raw token, hash, and display prefix
+ */
+export declare function generateDeviceToken(prefix: string): Promise<DeviceTokenPair>;
+/**
+ * Generate a short-lived pairing code for device registration
+ *
+ * Used for device pairing flow. User enters this code in web/mobile UI.
+ * Format: 6 uppercase alphanumeric characters (e.g., 'A1B2C3')
+ *
+ * @returns 6-character pairing code
+ */
+export declare function generatePairingCode(): string;
+/**
+ * Hash a token using SHA-256
+ *
+ * We use SHA-256 instead of bcrypt for tokens because:
+ * 1. Tokens are high-entropy (32 random bytes)
+ * 2. No need for slow hashing (not user passwords)
+ * 3. Faster verification for high-throughput API calls
+ *
+ * @param token - Raw token to hash
+ * @returns Hex-encoded SHA-256 hash
+ */
+export declare function hashToken(token: string): Promise<string>;
+/**
+ * Verify a token against its stored hash
+ *
+ * Constant-time comparison to prevent timing attacks.
+ *
+ * @param token - Raw token from client
+ * @param storedHash - Hash from database
+ * @returns Verification result
+ */
+export declare function verifyToken(token: string, storedHash: string): Promise<TokenVerificationResult>;
+/**
+ * Validate token format (prefix and length)
+ *
+ * Checks if token matches expected format before attempting verification.
+ * Useful for fast rejection of malformed tokens.
+ *
+ * @param token - Token to validate
+ * @param expectedPrefix - Expected token prefix
+ * @returns True if format is valid
+ */
+export declare function isValidTokenFormat(token: string, expectedPrefix: string): boolean;
+/**
+ * Check if token is expired
+ *
+ * @param expiresAt - Expiration timestamp
+ * @returns True if token is expired
+ */
+export declare function isTokenExpired(expiresAt: Date): boolean;
+/**
+ * Calculate token expiration date
+ *
+ * @param daysValid - Number of days token should be valid (default: 90)
+ * @returns Expiration timestamp
+ */
+export declare function getTokenExpiration(daysValid?: number): Date;
+export declare const DeviceTokens: {
+    generate: typeof generateDeviceToken;
+    generatePairingCode: typeof generatePairingCode;
+    hash: typeof hashToken;
+    verify: typeof verifyToken;
+    isValidFormat: typeof isValidTokenFormat;
+    isExpired: typeof isTokenExpired;
+    getExpiration: typeof getTokenExpiration;
+};
+//# sourceMappingURL=token-utils.d.ts.map

package/dist/plugins/devices/token-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-utils.d.ts","sourceRoot":"","sources":["../../../src/plugins/devices/token-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,iCAAiC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiBlF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAU5C;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG9D;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,uBAAuB,CAAC,CAsBlC;AAMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAqBjF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,IAAI,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,GAAE,MAAW,GAAG,IAAI,CAI/D;AAMD,eAAO,MAAM,YAAY;;;;;;;;CAQxB,CAAC"}

package/dist/plugins/devices/token-utils.js

@@ -0,0 +1,162 @@
+/**
+ * Device Token Utilities
+ *
+ * Utilities for generating, hashing, and verifying device tokens.
+ * Adapted from QwickForge's device-tokens implementation.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import crypto from 'crypto';
+// ═══════════════════════════════════════════════════════════════════════════
+// Token Generation
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Generate a cryptographically secure device token
+ *
+ * Returns both the raw token (to send to client) and the hash (to store in DB).
+ * The raw token should be shown to the user ONCE and never stored server-side.
+ *
+ * Token format: `<prefix>_<32 bytes base64url>`
+ *
+ * @param prefix - Token prefix for identification (e.g., 'qwf_dev', 'qwb_mob')
+ * @returns Token pair with raw token, hash, and display prefix
+ */
+export async function generateDeviceToken(prefix) {
+    // Generate 32 bytes of random data
+    const randomBytes = crypto.randomBytes(32);
+    // Convert to base64url (URL-safe, no padding)
+    const tokenSecret = randomBytes.toString('base64url');
+    // Combine prefix with secret
+    const token = `${prefix}_${tokenSecret}`;
+    // Hash the token for storage
+    const hash = await hashToken(token);
+    // Get first 8 chars of full token for display
+    const displayPrefix = token.substring(0, 8);
+    return { token, hash, prefix: displayPrefix };
+}
+/**
+ * Generate a short-lived pairing code for device registration
+ *
+ * Used for device pairing flow. User enters this code in web/mobile UI.
+ * Format: 6 uppercase alphanumeric characters (e.g., 'A1B2C3')
+ *
+ * @returns 6-character pairing code
+ */
+export function generatePairingCode() {
+    const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Avoid confusing chars (0, O, I, 1)
+    let code = '';
+    for (let i = 0; i < 6; i++) {
+        const randomIndex = crypto.randomInt(0, chars.length);
+        code += chars[randomIndex];
+    }
+    return code;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Token Hashing
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Hash a token using SHA-256
+ *
+ * We use SHA-256 instead of bcrypt for tokens because:
+ * 1. Tokens are high-entropy (32 random bytes)
+ * 2. No need for slow hashing (not user passwords)
+ * 3. Faster verification for high-throughput API calls
+ *
+ * @param token - Raw token to hash
+ * @returns Hex-encoded SHA-256 hash
+ */
+export async function hashToken(token) {
+    const hash = crypto.createHash('sha256').update(token).digest('hex');
+    return hash;
+}
+/**
+ * Verify a token against its stored hash
+ *
+ * Constant-time comparison to prevent timing attacks.
+ *
+ * @param token - Raw token from client
+ * @param storedHash - Hash from database
+ * @returns Verification result
+ */
+export async function verifyToken(token, storedHash) {
+    try {
+        // Hash the provided token
+        const tokenHash = await hashToken(token);
+        // Constant-time comparison
+        const valid = crypto.timingSafeEqual(Buffer.from(tokenHash, 'hex'), Buffer.from(storedHash, 'hex'));
+        if (!valid) {
+            return { valid: false, error: 'Invalid token' };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : 'Token verification failed',
+        };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Token Validation
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Validate token format (prefix and length)
+ *
+ * Checks if token matches expected format before attempting verification.
+ * Useful for fast rejection of malformed tokens.
+ *
+ * @param token - Token to validate
+ * @param expectedPrefix - Expected token prefix
+ * @returns True if format is valid
+ */
+export function isValidTokenFormat(token, expectedPrefix) {
+    // Check prefix
+    if (!token.startsWith(`${expectedPrefix}_`)) {
+        return false;
+    }
+    // Extract secret part
+    const secret = token.slice(expectedPrefix.length + 1);
+    // Validate length (32 bytes base64url = 43 characters)
+    if (secret.length !== 43) {
+        return false;
+    }
+    // Validate characters (base64url: A-Za-z0-9_-)
+    const base64urlPattern = /^[A-Za-z0-9_-]+$/;
+    if (!base64urlPattern.test(secret)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if token is expired
+ *
+ * @param expiresAt - Expiration timestamp
+ * @returns True if token is expired
+ */
+export function isTokenExpired(expiresAt) {
+    return new Date() > expiresAt;
+}
+/**
+ * Calculate token expiration date
+ *
+ * @param daysValid - Number of days token should be valid (default: 90)
+ * @returns Expiration timestamp
+ */
+export function getTokenExpiration(daysValid = 90) {
+    const expiresAt = new Date();
+    expiresAt.setDate(expiresAt.getDate() + daysValid);
+    return expiresAt;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Exports
+// ═══════════════════════════════════════════════════════════════════════════
+export const DeviceTokens = {
+    generate: generateDeviceToken,
+    generatePairingCode,
+    hash: hashToken,
+    verify: verifyToken,
+    isValidFormat: isValidTokenFormat,
+    isExpired: isTokenExpired,
+    getExpiration: getTokenExpiration,
+};
+//# sourceMappingURL=token-utils.js.map

package/dist/plugins/devices/token-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-utils.js","sourceRoot":"","sources":["../../../src/plugins/devices/token-utils.ts"],"names":[],"mappings":"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"}