@qwickapps/server 1.4.0 → 1.5.0

package/src/plugins/devices/stores/postgres-store.ts

@@ -0,0 +1,304 @@
+/**
+ * PostgreSQL Device Store
+ *
+ * Device storage implementation using PostgreSQL.
+ * Supports multi-tenant isolation via org_id.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  DeviceStore,
+  Device,
+  CreateDeviceInput,
+  UpdateDeviceInput,
+  DeviceSearchParams,
+  DeviceListResponse,
+  PostgresDeviceStoreConfig,
+} from '../types.js';
+
+// Pool interface (from pg package)
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+}
+
+/**
+ * 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: PostgresDeviceStoreConfig): DeviceStore {
+  const {
+    pool: poolOrFn,
+    tableName = 'devices',
+    schema = 'public',
+    autoCreateTables = true,
+  } = config;
+
+  // Helper to get pool (supports lazy initialization via function)
+  const getPool = (): PgPool => {
+    const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+    return pool as PgPool;
+  };
+
+  const devicesTableFull = `"${schema}"."${tableName}"`;
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      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: string): Promise<Device | null> {
+      const result = await getPool().query(
+        `SELECT * FROM ${devicesTableFull} WHERE id = $1 AND deleted_at IS NULL`,
+        [id]
+      );
+      return (result.rows[0] as Device) || null;
+    },
+
+    async getByTokenHash(tokenHash: string): Promise<Device | null> {
+      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] as Device) || null;
+    },
+
+    async create(
+      input: CreateDeviceInput & {
+        tokenHash: string;
+        tokenPrefix: string;
+        tokenExpiresAt: Date;
+        adapterType: string;
+      }
+    ): Promise<Device> {
+      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] as Device;
+    },
+
+    async update(id: string, input: UpdateDeviceInput): Promise<Device | null> {
+      const updates: string[] = [];
+      const values: unknown[] = [];
+      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] as Device) || null;
+    },
+
+    async delete(id: string): Promise<boolean> {
+      // 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: DeviceSearchParams): Promise<DeviceListResponse> {
+      const {
+        org_id,
+        user_id,
+        adapter_type,
+        is_active,
+        query,
+        page = 1,
+        limit = 20,
+        sortBy = 'created_at',
+        sortOrder = 'desc',
+      } = params;
+
+      const conditions: string[] = ['deleted_at IS NULL'];
+      const values: unknown[] = [];
+      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] as { count: string } | undefined;
+      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 as Device[],
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      };
+    },
+
+    async updateLastSeen(id: string, ip?: string): Promise<void> {
+      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: string,
+      tokenHash: string,
+      tokenPrefix: string,
+      expiresAt: Date
+    ): Promise<boolean> {
+      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(): Promise<number> {
+      // 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(): Promise<void> {
+      // Pool is managed externally, nothing to do here
+    },
+  };
+}

package/src/plugins/devices/token-utils.ts

@@ -0,0 +1,213 @@
+/**
+ * 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';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+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;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 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: string): Promise<DeviceTokenPair> {
+  // 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(): string {
+  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: string): Promise<string> {
+  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: string,
+  storedHash: string
+): Promise<TokenVerificationResult> {
+  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: string, expectedPrefix: string): boolean {
+  // 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: Date): boolean {
+  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: number = 90): Date {
+  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,
+};