@qwickapps/server 1.3.1 → 1.5.0

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

@@ -0,0 +1,264 @@
+/**
+ * Token Utilities Tests
+ *
+ * Unit tests for device token generation, hashing, and verification.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  generateDeviceToken,
+  generatePairingCode,
+  hashToken,
+  verifyToken,
+  isValidTokenFormat,
+  isTokenExpired,
+  getTokenExpiration,
+} from '../token-utils.js';
+
+describe('Token Utilities', () => {
+  describe('generateDeviceToken', () => {
+    it('should generate a token with the correct prefix', async () => {
+      const result = await generateDeviceToken('mob');
+      expect(result.token).toMatch(/^mob_/);
+    });
+
+    it('should generate a 43-character secret after prefix', async () => {
+      const result = await generateDeviceToken('mob');
+      const secret = result.token.split('_')[1];
+      expect(secret.length).toBe(43);
+    });
+
+    it('should generate base64url-safe characters', async () => {
+      const result = await generateDeviceToken('test');
+      const secret = result.token.split('_')[1];
+      expect(secret).toMatch(/^[A-Za-z0-9_-]+$/);
+    });
+
+    it('should return a SHA-256 hash (64 hex characters)', async () => {
+      const result = await generateDeviceToken('mob');
+      expect(result.hash).toMatch(/^[a-f0-9]{64}$/);
+    });
+
+    it('should return an 8-character prefix for display', async () => {
+      const result = await generateDeviceToken('mob');
+      expect(result.prefix.length).toBe(8);
+      expect(result.token.startsWith(result.prefix)).toBe(true);
+    });
+
+    it('should generate unique tokens each time', async () => {
+      const result1 = await generateDeviceToken('mob');
+      const result2 = await generateDeviceToken('mob');
+
+      expect(result1.token).not.toBe(result2.token);
+      expect(result1.hash).not.toBe(result2.hash);
+    });
+  });
+
+  describe('generatePairingCode', () => {
+    it('should generate a 6-character code', () => {
+      const code = generatePairingCode();
+      expect(code.length).toBe(6);
+    });
+
+    it('should only contain uppercase alphanumeric characters', () => {
+      const code = generatePairingCode();
+      // Excludes confusing chars: 0, O, I, 1
+      expect(code).toMatch(/^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]+$/);
+    });
+
+    it('should generate unique codes', () => {
+      const codes = new Set<string>();
+      for (let i = 0; i < 100; i++) {
+        codes.add(generatePairingCode());
+      }
+      // Should have mostly unique codes (allowing some collisions)
+      expect(codes.size).toBeGreaterThan(90);
+    });
+  });
+
+  describe('hashToken', () => {
+    it('should return a 64-character hex string', async () => {
+      const hash = await hashToken('test_token');
+      expect(hash.length).toBe(64);
+      expect(hash).toMatch(/^[a-f0-9]+$/);
+    });
+
+    it('should produce consistent hashes for same input', async () => {
+      const hash1 = await hashToken('same_token');
+      const hash2 = await hashToken('same_token');
+      expect(hash1).toBe(hash2);
+    });
+
+    it('should produce different hashes for different input', async () => {
+      const hash1 = await hashToken('token_one');
+      const hash2 = await hashToken('token_two');
+      expect(hash1).not.toBe(hash2);
+    });
+  });
+
+  describe('verifyToken', () => {
+    it('should return valid for matching token and hash', async () => {
+      const token = 'mob_ABC123testtoken';
+      const hash = await hashToken(token);
+
+      const result = await verifyToken(token, hash);
+
+      expect(result.valid).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    it('should return invalid for non-matching token', async () => {
+      const originalHash = await hashToken('original_token');
+
+      const result = await verifyToken('different_token', originalHash);
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe('Invalid token');
+    });
+
+    it('should handle malformed hash gracefully', async () => {
+      const result = await verifyToken('some_token', 'not-a-valid-hex-hash');
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+
+    it('should use constant-time comparison (timing-safe)', async () => {
+      // This test ensures the comparison doesn't leak timing info
+      // We can't directly test timing, but we verify the function uses the correct approach
+      const token = 'mob_securetoken123';
+      const hash = await hashToken(token);
+
+      // Multiple verifications should all succeed
+      for (let i = 0; i < 10; i++) {
+        const result = await verifyToken(token, hash);
+        expect(result.valid).toBe(true);
+      }
+    });
+  });
+
+  describe('isValidTokenFormat', () => {
+    it('should return true for valid token format', () => {
+      // 43 base64url characters after prefix (32 bytes = 43 chars in base64url)
+      const validToken = 'mob_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijk123456';
+      expect(isValidTokenFormat(validToken, 'mob')).toBe(true);
+    });
+
+    it('should return false for wrong prefix', () => {
+      const token = 'mob_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijk123456';
+      expect(isValidTokenFormat(token, 'cpute')).toBe(false);
+    });
+
+    it('should return false for missing underscore', () => {
+      const token = 'mobABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijk123456';
+      expect(isValidTokenFormat(token, 'mob')).toBe(false);
+    });
+
+    it('should return false for too short secret', () => {
+      const token = 'mob_tooshort';
+      expect(isValidTokenFormat(token, 'mob')).toBe(false);
+    });
+
+    it('should return false for too long secret', () => {
+      const token = 'mob_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijk123456extra';
+      expect(isValidTokenFormat(token, 'mob')).toBe(false);
+    });
+
+    it('should return false for invalid characters', () => {
+      const token = 'mob_ABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()123456';
+      expect(isValidTokenFormat(token, 'mob')).toBe(false);
+    });
+
+    it('should accept base64url characters including - and _', () => {
+      const token = 'mob_ABCDEFGHIJKLMNOPQRSTUVWXYZ-_abcdefghij12345';
+      expect(isValidTokenFormat(token, 'mob')).toBe(true);
+    });
+  });
+
+  describe('isTokenExpired', () => {
+    it('should return false for future date', () => {
+      const futureDate = new Date();
+      futureDate.setDate(futureDate.getDate() + 30);
+
+      expect(isTokenExpired(futureDate)).toBe(false);
+    });
+
+    it('should return true for past date', () => {
+      const pastDate = new Date();
+      pastDate.setDate(pastDate.getDate() - 1);
+
+      expect(isTokenExpired(pastDate)).toBe(true);
+    });
+
+    it('should return true for date exactly now (edge case)', () => {
+      const now = new Date();
+      // Slightly in the past to ensure it's expired
+      now.setMilliseconds(now.getMilliseconds() - 1);
+
+      expect(isTokenExpired(now)).toBe(true);
+    });
+  });
+
+  describe('getTokenExpiration', () => {
+    it('should return a date 90 days in the future by default', () => {
+      const now = new Date();
+      const expiration = getTokenExpiration();
+
+      const daysDiff = Math.round(
+        (expiration.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
+      );
+
+      expect(daysDiff).toBe(90);
+    });
+
+    it('should accept custom validity days', () => {
+      const now = new Date();
+      const expiration = getTokenExpiration(30);
+
+      const daysDiff = Math.round(
+        (expiration.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
+      );
+
+      expect(daysDiff).toBe(30);
+    });
+
+    it('should handle 0 days (expires immediately)', () => {
+      const now = new Date();
+      const expiration = getTokenExpiration(0);
+
+      // Should be very close to now
+      const diffMs = Math.abs(expiration.getTime() - now.getTime());
+      expect(diffMs).toBeLessThan(1000); // Within 1 second
+    });
+
+    it('should handle large values', () => {
+      const now = new Date();
+      const expiration = getTokenExpiration(365);
+
+      const daysDiff = Math.round(
+        (expiration.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
+      );
+
+      expect(daysDiff).toBe(365);
+    });
+  });
+
+  describe('integration: generate and verify', () => {
+    it('should generate token that can be verified', async () => {
+      const { token, hash } = await generateDeviceToken('mob');
+
+      const verifyResult = await verifyToken(token, hash);
+
+      expect(verifyResult.valid).toBe(true);
+    });
+
+    it('should reject tampered token', async () => {
+      const { hash } = await generateDeviceToken('mob');
+      const tamperedToken = 'mob_tamperedtokenthatisdifferentfromoriginal';
+
+      const verifyResult = await verifyToken(tamperedToken, hash);
+
+      expect(verifyResult.valid).toBe(false);
+    });
+  });
+});

package/src/plugins/devices/adapters/compute-adapter.ts

@@ -0,0 +1,139 @@
+/**
+ * Compute Device Adapter
+ *
+ * Adapter for computing devices (laptops, desktops, containers).
+ * Used by QwickForge for CLI device management.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  DeviceAdapter,
+  CreateDeviceInput,
+  ValidationResult,
+  Device,
+  ComputeDeviceMetadata,
+} from '../types.js';
+
+/**
+ * Compute adapter configuration
+ */
+export interface ComputeAdapterConfig {
+  /** Token prefix (default: 'qwf_dev') */
+  tokenPrefix?: string;
+  /** Require hostname in metadata */
+  requireHostname?: boolean;
+  /** Allowed OS types (optional, allows all if not specified) */
+  allowedOS?: string[];
+}
+
+/**
+ * Create a compute device adapter
+ *
+ * @param config - Adapter configuration
+ * @returns DeviceAdapter for compute devices
+ *
+ * @example
+ * ```ts
+ * const adapter = computeDeviceAdapter({
+ *   tokenPrefix: 'qwf_dev',
+ *   requireHostname: true,
+ * });
+ * ```
+ */
+export function computeDeviceAdapter(config: ComputeAdapterConfig = {}): DeviceAdapter {
+  const {
+    tokenPrefix = 'qwf_dev',
+    requireHostname = false,
+    allowedOS,
+  } = config;
+
+  return {
+    name: 'compute',
+    tokenPrefix,
+
+    validateDeviceInput(input: CreateDeviceInput): ValidationResult {
+      const errors: string[] = [];
+      const metadata = input.metadata as ComputeDeviceMetadata | undefined;
+
+      // Validate name
+      if (!input.name || input.name.trim().length === 0) {
+        errors.push('Device name is required');
+      }
+
+      if (input.name && input.name.length > 255) {
+        errors.push('Device name must be 255 characters or less');
+      }
+
+      // Validate hostname if required
+      if (requireHostname && (!metadata?.hostname || metadata.hostname.trim().length === 0)) {
+        errors.push('Hostname is required for compute devices');
+      }
+
+      // Validate OS if allowedOS is specified
+      if (allowedOS && metadata?.os) {
+        if (!allowedOS.includes(metadata.os)) {
+          errors.push(`OS '${metadata.os}' is not allowed. Allowed: ${allowedOS.join(', ')}`);
+        }
+      }
+
+      // Validate architecture
+      if (metadata?.arch) {
+        const validArchs = ['x64', 'arm64', 'ia32', 'arm'];
+        if (!validArchs.includes(metadata.arch)) {
+          errors.push(`Invalid architecture '${metadata.arch}'. Valid: ${validArchs.join(', ')}`);
+        }
+      }
+
+      return {
+        valid: errors.length === 0,
+        errors: errors.length > 0 ? errors : undefined,
+      };
+    },
+
+    transformForStorage(input: CreateDeviceInput): Record<string, unknown> {
+      const metadata = (input.metadata || {}) as ComputeDeviceMetadata;
+
+      // Ensure compute-specific defaults
+      return {
+        hostname: metadata.hostname || null,
+        os: metadata.os || null,
+        os_version: metadata.os_version || null,
+        arch: metadata.arch || null,
+        cli_capabilities: metadata.cli_capabilities || [],
+        container_id: metadata.container_id || null,
+        node_version: metadata.node_version || null,
+      };
+    },
+
+    transformFromStorage(row: Record<string, unknown>): Record<string, unknown> {
+      const metadata = (row.metadata || {}) as Record<string, unknown>;
+
+      // Extract compute-specific fields from metadata
+      return {
+        hostname: metadata.hostname,
+        os: metadata.os,
+        os_version: metadata.os_version,
+        arch: metadata.arch,
+        cli_capabilities: metadata.cli_capabilities || [],
+        container_id: metadata.container_id,
+        node_version: metadata.node_version,
+      };
+    },
+
+    async onDeviceCreated(device: Device): Promise<void> {
+      // Optional: Log device creation, send notifications, etc.
+      console.log(`[ComputeAdapter] Device created: ${device.name} (${device.id})`);
+    },
+
+    async onDeviceDeleted(device: Device): Promise<void> {
+      // Optional: Cleanup, revoke certificates, etc.
+      console.log(`[ComputeAdapter] Device deleted: ${device.name} (${device.id})`);
+    },
+
+    async onDeviceVerified(device: Device, ip?: string): Promise<void> {
+      // Optional: Log device verification, track activity
+      console.log(`[ComputeAdapter] Device verified: ${device.name} from ${ip || 'unknown'}`);
+    },
+  };
+}

package/src/plugins/devices/adapters/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Device Adapters
+ *
+ * Export all built-in device adapters.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { computeDeviceAdapter } from './compute-adapter.js';
+export type { ComputeAdapterConfig } from './compute-adapter.js';
+
+export { mobileDeviceAdapter } from './mobile-adapter.js';
+export type { MobileAdapterConfig } from './mobile-adapter.js';

package/src/plugins/devices/adapters/mobile-adapter.ts

@@ -0,0 +1,179 @@
+/**
+ * Mobile Device Adapter
+ *
+ * Adapter for mobile devices (phones, tablets).
+ * Used by QwickBot for mobile app device management.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  DeviceAdapter,
+  CreateDeviceInput,
+  ValidationResult,
+  Device,
+  MobileDeviceMetadata,
+} from '../types.js';
+
+/**
+ * Mobile adapter configuration
+ */
+export interface MobileAdapterConfig {
+  /** Token prefix (default: 'qwb_mob') */
+  tokenPrefix?: string;
+  /** Require device model in metadata */
+  requireDeviceModel?: boolean;
+  /** Require app version in metadata */
+  requireAppVersion?: boolean;
+  /** Allowed OS names (optional, allows all if not specified) */
+  allowedOS?: string[];
+  /** Minimum app version (optional, uses semver) */
+  minAppVersion?: string;
+}
+
+/**
+ * Compare semver versions (simplified)
+ */
+function compareSemver(v1: string, v2: string): number {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 > p2) return 1;
+    if (p1 < p2) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Create a mobile device adapter
+ *
+ * @param config - Adapter configuration
+ * @returns DeviceAdapter for mobile devices
+ *
+ * @example
+ * ```ts
+ * const adapter = mobileDeviceAdapter({
+ *   tokenPrefix: 'qwb_mob',
+ *   requireDeviceModel: true,
+ *   allowedOS: ['iOS', 'Android'],
+ * });
+ * ```
+ */
+export function mobileDeviceAdapter(config: MobileAdapterConfig = {}): DeviceAdapter {
+  const {
+    tokenPrefix = 'qwb_mob',
+    requireDeviceModel = false,
+    requireAppVersion = false,
+    allowedOS,
+    minAppVersion,
+  } = config;
+
+  return {
+    name: 'mobile',
+    tokenPrefix,
+
+    validateDeviceInput(input: CreateDeviceInput): ValidationResult {
+      const errors: string[] = [];
+      const metadata = input.metadata as MobileDeviceMetadata | undefined;
+
+      // Validate name
+      if (!input.name || input.name.trim().length === 0) {
+        errors.push('Device name is required');
+      }
+
+      if (input.name && input.name.length > 255) {
+        errors.push('Device name must be 255 characters or less');
+      }
+
+      // Validate device model if required
+      if (requireDeviceModel && (!metadata?.device_model || metadata.device_model.trim().length === 0)) {
+        errors.push('Device model is required for mobile devices');
+      }
+
+      // Validate app version if required
+      if (requireAppVersion && (!metadata?.app_version || metadata.app_version.trim().length === 0)) {
+        errors.push('App version is required for mobile devices');
+      }
+
+      // Validate OS if allowedOS is specified
+      if (allowedOS && metadata?.os_name) {
+        if (!allowedOS.includes(metadata.os_name)) {
+          errors.push(`OS '${metadata.os_name}' is not supported. Supported: ${allowedOS.join(', ')}`);
+        }
+      }
+
+      // Validate minimum app version
+      if (minAppVersion && metadata?.app_version) {
+        if (compareSemver(metadata.app_version, minAppVersion) < 0) {
+          errors.push(`App version ${metadata.app_version} is below minimum required version ${minAppVersion}`);
+        }
+      }
+
+      // Validate screen dimensions if provided
+      if (metadata?.screen_width !== undefined && metadata.screen_width <= 0) {
+        errors.push('Screen width must be a positive number');
+      }
+
+      if (metadata?.screen_height !== undefined && metadata.screen_height <= 0) {
+        errors.push('Screen height must be a positive number');
+      }
+
+      return {
+        valid: errors.length === 0,
+        errors: errors.length > 0 ? errors : undefined,
+      };
+    },
+
+    transformForStorage(input: CreateDeviceInput): Record<string, unknown> {
+      const metadata = (input.metadata || {}) as MobileDeviceMetadata;
+
+      // Ensure mobile-specific defaults
+      return {
+        device_model: metadata.device_model || null,
+        os_name: metadata.os_name || null,
+        os_version: metadata.os_version || null,
+        app_version: metadata.app_version || null,
+        push_token: metadata.push_token || null,
+        screen_width: metadata.screen_width || null,
+        screen_height: metadata.screen_height || null,
+      };
+    },
+
+    transformFromStorage(row: Record<string, unknown>): Record<string, unknown> {
+      const metadata = (row.metadata || {}) as Record<string, unknown>;
+
+      // Extract mobile-specific fields from metadata
+      return {
+        device_model: metadata.device_model,
+        os_name: metadata.os_name,
+        os_version: metadata.os_version,
+        app_version: metadata.app_version,
+        push_token: metadata.push_token,
+        screen_width: metadata.screen_width,
+        screen_height: metadata.screen_height,
+      };
+    },
+
+    async onDeviceCreated(device: Device): Promise<void> {
+      // Optional: Log device creation, track in analytics, etc.
+      console.log(`[MobileAdapter] Device registered: ${device.name} (${device.id})`);
+    },
+
+    async onDeviceDeleted(device: Device): Promise<void> {
+      // Optional: Unregister push token, cleanup, etc.
+      const metadata = device.metadata as MobileDeviceMetadata;
+      if (metadata?.push_token) {
+        console.log(`[MobileAdapter] Should unregister push token for device: ${device.id}`);
+      }
+      console.log(`[MobileAdapter] Device deleted: ${device.name} (${device.id})`);
+    },
+
+    async onDeviceVerified(device: Device, ip?: string): Promise<void> {
+      // Optional: Log device verification, track activity
+      console.log(`[MobileAdapter] Device verified: ${device.name} from ${ip || 'unknown'}`);
+    },
+  };
+}