@jmruthers/pace-core 0.5.181 → 0.5.183

package/src/types/index.ts

@@ -2,27 +2,61 @@
  * @file Types Module Exports
  * @package @jmruthers/pace-core
  * @module Types
- * @since 0.1.0
+ * @since 1.0.0
  * 
  * Complete collection of type definitions for the PACE Core library.
- * Use this import path when you need access to types not included in the main export.
+ * Types are organized by domain for better discoverability and maintainability.
  * 
  * @example
- * // Specialized type imports
- * import { User, Event, AccessLevel } from '@jmruthers/pace-core/types';
- * 
- * // For common types, prefer the main export:
- * import { ButtonProps, CardProps } from '@jmruthers/pace-core';
+ * // Import from specific domain
+ * import { User, Session } from '@jmruthers/pace-core/types/auth';
+ * import { Event, EventTheme } from '@jmruthers/pace-core/types/event';
+ * import { Organisation, OrganisationRole } from '@jmruthers/pace-core/types/organisation';
+ * import { RBACPermissionCheckParams } from '@jmruthers/pace-core/rbac/types/functions';
  */
 
-// Core type exports
-export * from './unified';
+// Core types (branded types, errors, primitives)
+export * from './core';
+
+// Domain-specific types
+export * from './auth';
+export * from './event';
+export * from './organisation';
+export * from './file-reference';
+export * from './validation';
+export * from './security';
 export * from './supabase';
 export * from './database';
 export * from './guards';
-export * from './validation';
-export * from './theme';
-export * from './security';
-export * from './auth';
 
-// Type declarations are handled via module augmentation in individual files
+// RBAC function types (from rbac module)
+// Note: RPCFunction is exported from ./supabase, so we exclude it from rbac/types/functions to avoid conflict
+export type {
+  RBACPermissionCheckParams,
+  RBACPermissionCheckResult,
+  RBACPermissionsGetParams,
+  RBACPermissionsGetResult,
+  RBACAccessValidateParams,
+  RBACAccessValidateResult,
+  RBACPageAccessCheckParams,
+  RBACRoleGrantParams,
+  RBACRoleGrantResult,
+  RBACRoleRevokeParams,
+  RBACRoleRevokeResult,
+  RBACRolesListParams,
+  RBACRolesListResult,
+  RBACRoleValidateParams,
+  RBACRoleValidateResult,
+  RBACSessionTrackParams,
+  RBACSessionTrackResult,
+  RBACAuditLogParams,
+  RBACAuditLogResult,
+  PermissionSource,
+  AccessLevelContext,
+  SessionType,
+  AuditEventType,
+  RBACContext,
+  RBACResult,
+  RBACFunctionResponse,
+  RBACErrorCode,
+} from '../rbac/types/functions';

package/src/types/lodash.debounce.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Type declaration for lodash.debounce
+ * @package @jmruthers/pace-core
+ */
+declare module 'lodash.debounce' {
+  function debounce<T extends (...args: unknown[]) => unknown>(
+    func: T,
+    wait?: number,
+    options?: { leading?: boolean; maxWait?: number; trailing?: boolean }
+  ): T & { cancel(): void; flush(): void };
+  
+  export = debounce;
+  export default debounce;
+}
+

package/src/types/organisation.ts

@@ -2,9 +2,13 @@
  * @file Organisation Types
  * @package @jmruthers/pace-core
  * @module Types/Organisation
- * @since 0.4.0
+ * @since 1.0.0
+ * 
+ * Type definitions for organisations, memberships, roles, and organisation context.
  */
 
+import type { OrganisationId, UserId } from './core';
+
 export interface Organisation {
   id: string;
   name: string;
@@ -22,8 +26,8 @@ export interface Organisation {
 
 export interface OrganisationMembership {
   id: string;
-  user_id: string;
-  organisation_id: string;
+  user_id: UserId;
+  organisation_id: OrganisationId;
   role: 'org_admin' | 'leader' | 'member' | 'supporter';
   status: 'active' | 'inactive' | 'suspended';
   granted_at: string;
@@ -36,7 +40,7 @@ export interface OrganisationMembership {
 }
 
 export interface UserProfile {
-  id: string;
+  id: UserId;
   email: string;
   full_name?: string;
   created_at: string;
@@ -44,7 +48,7 @@ export interface UserProfile {
 }
 
 export interface OrganisationSettings {
-  organisation_id: string;
+  organisation_id: OrganisationId;
   logo_url?: string;
   primary_color?: string;
   secondary_color?: string;
@@ -67,7 +71,7 @@ export interface OrganisationSettings {
 
 export interface OrganisationInvitation {
   id: string;
-  organisation_id: string;
+  organisation_id: OrganisationId;
   email: string;
   role: 'supporter' | 'member' | 'leader' | 'org_admin';
   invited_by?: string;
@@ -169,8 +173,8 @@ export type OrganisationPermission =
 // Enhanced security types
 export interface OrganisationAccessLog {
   id: string;
-  user_id: string;
-  organisation_id: string;
+  user_id: UserId;
+  organisation_id: OrganisationId;
   action: string;
   details: Record<string, unknown>;
   created_at: string;
@@ -180,6 +184,6 @@ export interface SecureQueryOptions {
   table: string;
   select: string;
   filters?: Record<string, unknown>;
-  organisationId: string;
-  userId?: string;
+  organisationId: OrganisationId;
+  userId?: UserId;
 } 

package/src/types/supabase.ts

@@ -1,20 +1,24 @@
 /**
  * @file Supabase Integration Types
+ * @package @jmruthers/pace-core
+ * @module Types/Supabase
+ * @since 1.0.0
  * 
- * TypeScript interfaces for Supabase client operations with standard types.
+ * TypeScript interfaces for Supabase client operations and RPC function types.
  */
 
-import type {
-  User,
-  Session,
-  AuthError,
-  PermissionError,
-  UserPermissions,
-  AccessLevel,
-  PermissionString,
-} from './unified';
-
 import type { SupabaseClient } from '@supabase/supabase-js';
+import type { User, Session, AuthError } from './auth';
+import type { PermissionError } from './core';
+import type { PermissionString } from './core';
+
+/**
+ * User permissions interface
+ */
+export interface UserPermissions {
+  permissions: string[];
+  roles: string[];
+}
 
 /**
  * Standard Supabase client - no custom wrapper needed
@@ -84,12 +88,6 @@ export interface PermissionOperations {
     appName: string
   ): Promise<{ data: null; error: PermissionError | null }>;
 
-  setUserAccessLevel(
-    userId: string,
-    accessLevel: AccessLevel,
-    eventId: string,
-    appName: string
-  ): Promise<{ data: null; error: PermissionError | null }>;
 }
 
 // ============================================================================

package/src/utils/__tests__/secureErrors.unit.test.ts

@@ -15,7 +15,7 @@ import {
   generateRequestId, 
   logSecurityEvent 
 } from '../security/secureErrors';
-import { AuthErrorCode } from '../../types/unified';
+import { AuthErrorCode } from '../../types/core';
 
 // Mock the Logger module
 vi.mock('../core/logger', () => {

package/src/utils/__tests__/validationUtils.unit.test.ts

@@ -2,7 +2,6 @@ import { describe, it, expect, vi } from 'vitest';
 import { z } from 'zod';
 import {
   validateUserInput,
-  sanitizeUserInput_deprecated,
   emailSchema,
   passwordSchema,
   usernameSchema,
@@ -11,20 +10,6 @@ import {
   urlSchema
 } from '../validation/validationUtils';
 
-// Mock the Logger module
-vi.mock('../core/logger', () => {
-  const mockLoggerInstance = {
-    warn: vi.fn(),
-  };
-  return {
-    createLogger: vi.fn(() => mockLoggerInstance),
-  };
-});
-
-// Get the mock instance after mock is set up
-import { createLogger } from '../core/logger';
-const getMockLogger = () => createLogger('test');
-
 // Mock sanitization functions
 vi.mock('../validation/sanitization', () => ({
   sanitizeUserInput: vi.fn((input: string) => `sanitized_${input}`),
@@ -92,20 +77,6 @@ describe('validationUtils', () => {
     });
   });
 
-  describe('sanitizeUserInput_deprecated', () => {
-    it('should call sanitizeUserInput and log deprecation warning', () => {
-      vi.clearAllMocks();
-      
-      const result = sanitizeUserInput_deprecated('test input');
-
-      expect(result).toBe('sanitized_test input');
-      const logger = getMockLogger();
-      expect(vi.mocked(logger.warn)).toHaveBeenCalledWith(
-        'sanitizeUserInput is deprecated. Use sanitizeUserInput from lib/sanitization instead.'
-      );
-    });
-  });
-
   describe('emailSchema', () => {
     it('should validate valid email addresses', () => {
       const validEmails = [

package/src/utils/app/appNameResolver.ts

@@ -9,7 +9,7 @@ const log = createLogger('AppNameResolver');
 
 interface PackageJson {
   name: string;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 /**

package/src/utils/audit/audit.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  auditLogger,
+  logAuthEvent,
+  logPermissionEvent,
+  logSecurityEvent,
+  logAuditEvent
+} from './audit';
+
+describe('audit logger utility', () => {
+  beforeEach(() => {
+    auditLogger.clearEvents();
+    vi.useRealTimers();
+  });
+
+  it('attaches timestamps to every raw log entry', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2024-01-01T00:00:00Z'));
+
+    auditLogger.log({ type: 'auth', action: 'login', severity: 'high' });
+
+    const [event] = auditLogger.getEvents();
+    expect(event).toMatchObject({ type: 'auth', action: 'login', severity: 'high' });
+    expect(event.timestamp).toBe(Date.now());
+  });
+
+  it('filters security events without mutating the original queue', async () => {
+    await auditLogger.logAuthEvent({ event: 'login', userId: 'user-1' });
+    await auditLogger.logSecurityEvent({ event: 'policy_violation', data: { ip: '127.0.0.1' } });
+    await auditLogger.logPermissionEvent({ event: 'role_grant', userId: 'user-2' });
+
+    const securityEvents = await auditLogger.getSecurityEvents();
+    expect(securityEvents).toHaveLength(1);
+    expect(securityEvents[0]).toMatchObject({ type: 'security', event: 'policy_violation' });
+
+    const allEvents = auditLogger.getEvents();
+    expect(allEvents).toHaveLength(3);
+    expect(allEvents).not.toBe(securityEvents); // defensive copy for getEvents
+  });
+
+  it('records structured data through the async wrappers', async () => {
+    await auditLogger.logPermissionEvent({ event: 'role_update', userId: 'user-123', data: { scope: 'org' } });
+
+    const [permissionEvent] = auditLogger.getEvents();
+    expect(permissionEvent).toMatchObject({
+      type: 'permission',
+      event: 'role_update',
+      userId: 'user-123',
+      data: { scope: 'org' }
+    });
+    expect(typeof permissionEvent.timestamp).toBe('number');
+  });
+
+  it('routes the public helper functions through the shared logger instance', () => {
+    logAuthEvent('login_attempt', 'alpha', { method: 'password' });
+    logPermissionEvent('grant_role', 'beta', { role: 'leader' });
+    logSecurityEvent('rate_limit', 'system', { ip: '127.0.0.1' });
+    logAuditEvent('generic_event', 'gamma');
+
+    const events = auditLogger.getEvents();
+    expect(events).toHaveLength(4);
+    expect(events.map(event => event.type)).toEqual(['auth', 'permission', 'security', 'auth']);
+    expect(events[3]).toMatchObject({ action: 'generic_event', user: 'gamma' });
+  });
+});

package/src/utils/device/deviceFingerprint.test.ts

@@ -0,0 +1,171 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { generateDeviceFingerprint, validateDeviceFingerprint, type DeviceFingerprint } from './deviceFingerprint';
+import { secureStorage } from '../security/secureStorage';
+
+vi.mock('../security/secureStorage', () => ({
+  secureStorage: {
+    setItem: vi.fn()
+  }
+}));
+
+describe('device fingerprinting utilities', () => {
+  const setItemMock = secureStorage.setItem as ReturnType<typeof vi.fn>;
+  const originalCreateElement = document.createElement.bind(document);
+  let createElementSpy: ReturnType<typeof vi.spyOn>;
+  let intlSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    setItemMock.mockReset();
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2024-01-01T00:00:00Z'));
+
+    Object.defineProperty(window.navigator, 'userAgent', {
+      value: 'TestAgent/1.0',
+      configurable: true
+    });
+    Object.defineProperty(window.navigator, 'language', {
+      value: 'en-GB',
+      configurable: true
+    });
+    Object.defineProperty(window.navigator, 'platform', {
+      value: 'MacIntel',
+      configurable: true
+    });
+    Object.defineProperty(window, 'screen', {
+      value: { width: 1920, height: 1080, colorDepth: 24 },
+      configurable: true
+    });
+
+    intlSpy = vi.spyOn(Intl, 'DateTimeFormat').mockImplementation(() => ({
+      resolvedOptions: () => ({ timeZone: 'UTC' })
+    }) as Intl.DateTimeFormat);
+
+    createElementSpy = vi.spyOn(document, 'createElement').mockImplementation(tagName => {
+      if (tagName === 'canvas') {
+        const ctx2d = {
+          textBaseline: '',
+          font: '',
+          fillStyle: '',
+          fillRect: vi.fn(),
+          fillText: vi.fn()
+        } as unknown as CanvasRenderingContext2D;
+
+        const debugInfo = {
+          UNMASKED_VENDOR_WEBGL: 'vendorConst',
+          UNMASKED_RENDERER_WEBGL: 'rendererConst'
+        };
+
+        const gl = {
+          getExtension: vi.fn(() => debugInfo),
+          getParameter: vi.fn((param: string) =>
+            param === debugInfo.UNMASKED_VENDOR_WEBGL ? 'ExampleVendor' : 'ExampleRenderer'
+          )
+        } as unknown as WebGLRenderingContext;
+
+        return {
+          getContext: (type: string) => {
+            if (type === '2d') return ctx2d;
+            if (type === 'webgl' || type === 'experimental-webgl') return gl;
+            return null;
+          },
+          toDataURL: () => 'data:image/png;base64,fingerprint'
+        } as unknown as HTMLCanvasElement;
+      }
+      return originalCreateElement(tagName);
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    createElementSpy.mockRestore();
+    intlSpy.mockRestore();
+  });
+
+  it('captures deterministic device details and persists the fingerprint payload', () => {
+    const fingerprint = generateDeviceFingerprint();
+
+    expect(fingerprint.components).toMatchObject({
+      language: 'en-GB',
+      platform: 'MacIntel',
+      screen: '1920x1080x24',
+      timezone: 'UTC'
+    });
+    // userAgent is a hashed value, length depends on the hash
+    expect(fingerprint.components.userAgent).toBeTruthy();
+    expect(typeof fingerprint.components.userAgent).toBe('string');
+    expect(fingerprint.entropy).toBeGreaterThan(0);
+
+    expect(setItemMock).toHaveBeenCalledTimes(1);
+    const [storageKey, storedValue] = setItemMock.mock.calls[0];
+    expect(storageKey).toBe('device_fingerprint');
+    expect(JSON.parse(storedValue)).toMatchObject({ hash: fingerprint.hash, components: fingerprint.components });
+  });
+
+  it('falls back gracefully when fingerprinting fails', () => {
+    // Mock all potential failure points to ensure fallback is triggered
+    createElementSpy.mockImplementation(() => {
+      throw new Error('canvas unavailable');
+    });
+    
+    // Also mock navigator properties to throw to ensure complete failure
+    const originalUserAgent = Object.getOwnPropertyDescriptor(window.navigator, 'userAgent');
+    Object.defineProperty(window.navigator, 'userAgent', {
+      get: () => { throw new Error('userAgent unavailable'); },
+      configurable: true
+    });
+
+    const fallback = generateDeviceFingerprint();
+
+    expect(fallback.hash).toMatch(/^fallback_/);
+    expect(fallback.entropy).toBe(1);
+    expect(setItemMock).not.toHaveBeenCalled();
+    
+    // Restore original userAgent
+    if (originalUserAgent) {
+      Object.defineProperty(window.navigator, 'userAgent', originalUserAgent);
+    }
+  });
+
+  it('validates stored fingerprints with age and confidence thresholds', () => {
+    const baseComponents = {
+      userAgent: 'ua',
+      language: 'lang',
+      platform: 'platform',
+      screen: 'screen',
+      timezone: 'tz'
+    } as DeviceFingerprint['components'];
+
+    const stored: DeviceFingerprint = {
+      hash: 'stored',
+      timestamp: Date.now(),
+      components: baseComponents,
+      entropy: 3
+    };
+
+    const current: DeviceFingerprint = {
+      hash: 'current',
+      timestamp: Date.now(),
+      components: { ...baseComponents, screen: 'screen', timezone: 'tz', platform: 'platform-modified' },
+      entropy: 3
+    };
+
+    const freshResult = validateDeviceFingerprint(stored, current);
+    expect(freshResult.isValid).toBe(true);
+    expect(freshResult.confidence).toBe(80);
+    expect(freshResult.reasons).toEqual(['Component mismatch: platform']);
+
+    const staleResult = validateDeviceFingerprint(
+      { ...stored, timestamp: Date.now() - 31 * 24 * 60 * 60 * 1000 },
+      current
+    );
+    expect(staleResult.isValid).toBe(false);
+    expect(staleResult.reasons).toContain('Fingerprint too old');
+
+    const divergent = validateDeviceFingerprint(stored, {
+      ...current,
+      components: { ...baseComponents, language: 'other', platform: 'alt', screen: 'another' }
+    });
+    expect(divergent.isValid).toBe(false);
+    expect(divergent.reasons).toContain('Device signature changed significantly');
+  });
+});

package/src/utils/dynamic/dynamicUtils.ts

@@ -22,9 +22,10 @@ export const loadLodash = async (): Promise<{
   debounce: DebounceFunction;
   throttle: ThrottleFunction;
 }> => {
+  // Using type assertions for dynamic imports - these modules don't have consistent type exports
   const [debounceModule, throttleModule] = await Promise.all([
-    import('lodash.debounce' as any),
-    import('lodash.throttle' as any)
+    import('lodash.debounce') as Promise<{ default?: DebounceFunction } & { [key: string]: unknown }>,
+    import('lodash.throttle') as Promise<{ default?: ThrottleFunction } & { [key: string]: unknown }>
   ]);
   
   return {

package/src/utils/file-reference/index.ts

@@ -7,12 +7,14 @@ import {
   FileUploadOptions, 
   FileReferenceService, 
   FileUploadResult,
-  FileCategory 
+  FileCategory,
+  FileMetadata
 } from '../../types/file-reference';
 import { uploadFile, getPublicUrl, getSignedUrl, deleteFile, extractFileMetadata } from '../storage/helpers';
 import { setOrganisationContext } from '../context/organisationContext';
 import { invalidateFileDisplayCache } from '../../hooks/useFileDisplay';
 import { createLogger } from '../core/logger';
+import { assertAppId } from '../../types/core';
 
 const log = createLogger('FileReferenceService');
 
@@ -287,7 +289,8 @@ export class FileReferenceServiceImpl implements FileReferenceService {
       }
 
       // Fetch full file reference data for each ID
-      const ids = data.map((item: any) => item.id);
+      // RPC returns array of objects with at least an 'id' property
+      const ids = data.map((item: { id: string }) => item.id);
       const { data: fullData, error: fetchError } = await this.supabase
         .from('file_references')
         .select('*')
@@ -390,8 +393,15 @@ export class FileReferenceServiceImpl implements FileReferenceService {
 
       // Construct FileReference objects from RPC response
       // This avoids RLS issues with direct queries - the RPC already validated permissions
+      interface RpcFileItem {
+        id: string;
+        file_path: string;
+        file_metadata: { category?: string; app_id?: string; [key: string]: unknown };
+        is_public?: boolean;
+        created_at?: string;
+      }
       const fileReferences: FileReference[] = data
-        .filter((item: any) => {
+        .filter((item: RpcFileItem) => {
           // Verify category matches (defensive check)
           const fileCategory = item.file_metadata?.category;
           const matches = fileCategory === category;
@@ -404,16 +414,25 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           }
           return matches && item.id && item.file_path && item.file_metadata;
         })
-        .map((item: any) => {
+        .map((item: RpcFileItem) => {
+          // Extract file name and type from file_path
+          const fileName = item.file_path.split('/').pop() || 'unknown';
+          const fileType = fileName.split('.').pop() || 'unknown';
+          
           // Construct complete FileReference from RPC response + function parameters
           const fileRef: FileReference = {
             id: item.id,
             table_name: table_name,
             record_id: record_id,
             file_path: item.file_path,
-            file_metadata: item.file_metadata || {},
+            file_metadata: {
+              fileName,
+              fileType,
+              category: (item.file_metadata?.category as FileCategory) || FileCategory.GENERAL_DOCUMENTS,
+              ...(item.file_metadata || {}),
+            } as FileMetadata,
             organisation_id: organisation_id,
-            app_id: item.file_metadata?.app_id || '', // May not be in metadata, use empty string
+            app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(''), // May not be in metadata, use empty string
             is_public: item.is_public ?? false,
             created_at: item.created_at || new Date().toISOString(),
             updated_at: item.created_at || new Date().toISOString() // RPC doesn't return updated_at, use created_at

package/src/utils/security/secureErrors.ts

@@ -2,7 +2,7 @@
  * @file Secure error handling utilities
  */
 
-import { AuthError, AuthErrorCode, RequestId } from '../../types/unified';
+import { AuthError, AuthErrorCode, RequestId } from '../../types/core';
 import { createLogger } from '../core/logger';
 
 const log = createLogger('Security');