@onebun/core 0.1.1 → 0.1.2

package/src/ws-guards.test.ts

@@ -0,0 +1,334 @@
+/**
+ * WebSocket Guards Tests
+ */
+
+import {
+  describe,
+  it,
+  expect,
+} from 'bun:test';
+
+import type { WsClientData, WsHandlerMetadata } from './ws.types';
+
+import {
+  WsAuthGuard,
+  WsPermissionGuard,
+  WsRoomGuard,
+  WsAnyPermissionGuard,
+  WsServiceGuard,
+  WsAllGuards,
+  WsAnyGuard,
+  WsExecutionContextImpl,
+  executeGuards,
+  createGuard,
+} from './ws-guards';
+import { WsHandlerType } from './ws.types';
+
+describe('ws-guards', () => {
+  // Helper to create mock client data
+  const createClient = (overrides: Partial<WsClientData> = {}): WsClientData => ({
+    id: 'test-client',
+    rooms: [],
+    connectedAt: Date.now(),
+    auth: null,
+    metadata: {},
+    ...overrides,
+  });
+
+  // Helper to create mock handler metadata
+  const createHandler = (): WsHandlerMetadata => ({
+    type: WsHandlerType.MESSAGE,
+    pattern: 'test:*',
+    handler: 'handleTest',
+    params: [],
+  });
+
+  // Helper to create execution context
+  const createContext = (client: WsClientData) =>
+    new WsExecutionContextImpl(
+      client,
+      {} as never, // mock socket
+      {},
+      createHandler(),
+      {},
+    );
+
+  describe('WsAuthGuard', () => {
+    const guard = new WsAuthGuard();
+
+    it('should allow authenticated clients', () => {
+      const client = createClient({
+        auth: { authenticated: true },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it('should reject unauthenticated clients', () => {
+      const client = createClient({
+        auth: { authenticated: false },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(false);
+    });
+
+    it('should reject clients without auth data', () => {
+      const client = createClient({ auth: null });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(false);
+    });
+  });
+
+  describe('WsPermissionGuard', () => {
+    it('should allow clients with required permission', () => {
+      const guard = new WsPermissionGuard('admin');
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['admin', 'user'] },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it('should reject clients without required permission', () => {
+      const guard = new WsPermissionGuard('admin');
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['user'] },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(false);
+    });
+
+    it('should require all permissions when array is provided', () => {
+      const guard = new WsPermissionGuard(['admin', 'moderator']);
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['admin'] },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(false);
+    });
+
+    it('should allow when client has all required permissions', () => {
+      const guard = new WsPermissionGuard(['admin', 'moderator']);
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['admin', 'moderator', 'user'] },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+  });
+
+  describe('WsRoomGuard', () => {
+    it('should allow clients in the required room', () => {
+      const guard = new WsRoomGuard('vip');
+      const client = createClient({
+        rooms: ['general', 'vip'],
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it('should reject clients not in the required room', () => {
+      const guard = new WsRoomGuard('vip');
+      const client = createClient({
+        rooms: ['general'],
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(false);
+    });
+  });
+
+  describe('WsAnyPermissionGuard', () => {
+    it('should allow clients with any of the permissions', () => {
+      const guard = new WsAnyPermissionGuard(['admin', 'moderator']);
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['moderator'] },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it('should reject clients without any of the permissions', () => {
+      const guard = new WsAnyPermissionGuard(['admin', 'moderator']);
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['user'] },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(false);
+    });
+  });
+
+  describe('WsServiceGuard', () => {
+    it('should allow allowed services', () => {
+      const guard = new WsServiceGuard('payment-service');
+      const client = createClient({
+        auth: { authenticated: true, serviceId: 'payment-service' },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+
+    it('should reject non-allowed services', () => {
+      const guard = new WsServiceGuard('payment-service');
+      const client = createClient({
+        auth: { authenticated: true, serviceId: 'other-service' },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(false);
+    });
+
+    it('should allow multiple services', () => {
+      const guard = new WsServiceGuard(['payment-service', 'billing-service']);
+      const client = createClient({
+        auth: { authenticated: true, serviceId: 'billing-service' },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+  });
+
+  describe('WsAllGuards', () => {
+    it('should pass when all guards pass', async () => {
+      const guard = new WsAllGuards([new WsAuthGuard(), new WsPermissionGuard('admin')]);
+
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['admin'] },
+      });
+      const context = createContext(client);
+
+      expect(await guard.canActivate(context)).toBe(true);
+    });
+
+    it('should fail when any guard fails', async () => {
+      const guard = new WsAllGuards([new WsAuthGuard(), new WsPermissionGuard('admin')]);
+
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['user'] },
+      });
+      const context = createContext(client);
+
+      expect(await guard.canActivate(context)).toBe(false);
+    });
+  });
+
+  describe('WsAnyGuard', () => {
+    it('should pass when any guard passes', async () => {
+      const guard = new WsAnyGuard([new WsPermissionGuard('admin'), new WsRoomGuard('vip')]);
+
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['user'] },
+        rooms: ['vip'],
+      });
+      const context = createContext(client);
+
+      expect(await guard.canActivate(context)).toBe(true);
+    });
+
+    it('should fail when all guards fail', async () => {
+      const guard = new WsAnyGuard([new WsPermissionGuard('admin'), new WsRoomGuard('vip')]);
+
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['user'] },
+        rooms: ['general'],
+      });
+      const context = createContext(client);
+
+      expect(await guard.canActivate(context)).toBe(false);
+    });
+  });
+
+  describe('executeGuards', () => {
+    it('should execute guard classes', async () => {
+      const client = createClient({
+        auth: { authenticated: true },
+      });
+      const context = createContext(client);
+
+      const result = await executeGuards([WsAuthGuard], context);
+      expect(result).toBe(true);
+    });
+
+    it('should execute guard instances', async () => {
+      const client = createClient({
+        auth: { authenticated: true, permissions: ['admin'] },
+      });
+      const context = createContext(client);
+
+      const result = await executeGuards([new WsPermissionGuard('admin')], context);
+      expect(result).toBe(true);
+    });
+
+    it('should return true when no guards', async () => {
+      const context = createContext(createClient());
+      const result = await executeGuards([], context);
+      expect(result).toBe(true);
+    });
+  });
+
+  describe('createGuard', () => {
+    it('should create custom guard from function', () => {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      const CustomGuard = createGuard((ctx) => {
+        return (ctx.getClient().metadata as { customCheck?: boolean }).customCheck === true;
+      });
+
+      const guard = new CustomGuard();
+      const client = createClient({
+        metadata: { customCheck: true },
+      });
+      const context = createContext(client);
+
+      expect(guard.canActivate(context)).toBe(true);
+    });
+  });
+
+  describe('WsExecutionContextImpl', () => {
+    it('should provide access to client data', () => {
+      const client = createClient({ id: 'test-id' });
+      const context = createContext(client);
+
+      expect(context.getClient().id).toBe('test-id');
+    });
+
+    it('should provide access to message data', () => {
+      const client = createClient();
+      const data = { text: 'hello' };
+      const context = new WsExecutionContextImpl(
+        client,
+        {} as never,
+        data,
+        createHandler(),
+        {},
+      );
+
+      expect(context.getData<{ text: string }>()).toEqual(data);
+    });
+
+    it('should provide access to pattern params', () => {
+      const client = createClient();
+      const params = { roomId: '123' };
+      const context = new WsExecutionContextImpl(
+        client,
+        {} as never,
+        {},
+        createHandler(),
+        params,
+      );
+
+      expect(context.getPatternParams()).toEqual(params);
+    });
+  });
+});

package/src/ws-guards.ts

@@ -0,0 +1,298 @@
+/**
+ * WebSocket Guards
+ *
+ * Guards for authorizing WebSocket connections and message handling.
+ */
+
+import type {
+  WsClientData,
+  WsGuard,
+  WsExecutionContext,
+  WsHandlerMetadata,
+} from './ws.types';
+import type { ServerWebSocket } from 'bun';
+
+
+// ============================================================================
+// Execution Context Implementation
+// ============================================================================
+
+/**
+ * Implementation of WsExecutionContext
+ */
+export class WsExecutionContextImpl implements WsExecutionContext {
+  constructor(
+    private client: WsClientData,
+    private socket: ServerWebSocket<WsClientData>,
+    private data: unknown,
+    private handler: WsHandlerMetadata,
+    private patternParams: Record<string, string>,
+  ) {}
+
+  getClient(): WsClientData {
+    return this.client;
+  }
+
+  getSocket(): ServerWebSocket<WsClientData> {
+    return this.socket;
+  }
+
+  getData<T = unknown>(): T {
+    return this.data as T;
+  }
+
+  getHandler(): WsHandlerMetadata {
+    return this.handler;
+  }
+
+  getPatternParams(): Record<string, string> {
+    return this.patternParams;
+  }
+}
+
+// ============================================================================
+// Built-in Guards
+// ============================================================================
+
+/**
+ * Guard that requires client to be authenticated
+ *
+ * @example
+ * ```typescript
+ * @UseWsGuards(WsAuthGuard)
+ * @OnMessage('protected:*')
+ * handleProtectedMessage(@Client() client: WsClientData) {
+ *   // Only authenticated clients can reach here
+ * }
+ * ```
+ */
+export class WsAuthGuard implements WsGuard {
+  canActivate(context: WsExecutionContext): boolean {
+    const client = context.getClient();
+
+    return client.auth?.authenticated === true;
+  }
+}
+
+/**
+ * Guard that requires specific permission(s)
+ *
+ * @example
+ * ```typescript
+ * // Single permission
+ * @UseWsGuards(new WsPermissionGuard('admin'))
+ * @OnMessage('admin:*')
+ * handleAdminMessage() { }
+ *
+ * // Multiple permissions (all required)
+ * @UseWsGuards(new WsPermissionGuard(['admin', 'moderator']))
+ * @OnMessage('super:*')
+ * handleSuperMessage() { }
+ * ```
+ */
+export class WsPermissionGuard implements WsGuard {
+  private requiredPermissions: string[];
+
+  constructor(permissions: string | string[]) {
+    this.requiredPermissions = Array.isArray(permissions) ? permissions : [permissions];
+  }
+
+  canActivate(context: WsExecutionContext): boolean {
+    const client = context.getClient();
+    const clientPermissions = client.auth?.permissions || [];
+
+    return this.requiredPermissions.every((p) => clientPermissions.includes(p));
+  }
+}
+
+/**
+ * Guard that requires client to be in a specific room
+ *
+ * @example
+ * ```typescript
+ * @UseWsGuards(new WsRoomGuard('vip'))
+ * @OnMessage('vip:*')
+ * handleVipMessage() { }
+ * ```
+ */
+export class WsRoomGuard implements WsGuard {
+  constructor(private roomName: string) {}
+
+  canActivate(context: WsExecutionContext): boolean {
+    const client = context.getClient();
+
+    return client.rooms.includes(this.roomName);
+  }
+}
+
+/**
+ * Guard that allows any of multiple permissions
+ *
+ * @example
+ * ```typescript
+ * @UseWsGuards(new WsAnyPermissionGuard(['admin', 'moderator']))
+ * @OnMessage('manage:*')
+ * handleManageMessage() { }
+ * ```
+ */
+export class WsAnyPermissionGuard implements WsGuard {
+  private permissions: string[];
+
+  constructor(permissions: string[]) {
+    this.permissions = permissions;
+  }
+
+  canActivate(context: WsExecutionContext): boolean {
+    const client = context.getClient();
+    const clientPermissions = client.auth?.permissions || [];
+
+    return this.permissions.some((p) => clientPermissions.includes(p));
+  }
+}
+
+/**
+ * Guard that requires a specific service ID (for inter-service communication)
+ *
+ * @example
+ * ```typescript
+ * @UseWsGuards(new WsServiceGuard('payment-service'))
+ * @OnMessage('payment:webhook')
+ * handlePaymentWebhook() { }
+ * ```
+ */
+export class WsServiceGuard implements WsGuard {
+  private allowedServices: string[];
+
+  constructor(services: string | string[]) {
+    this.allowedServices = Array.isArray(services) ? services : [services];
+  }
+
+  canActivate(context: WsExecutionContext): boolean {
+    const client = context.getClient();
+    const serviceId = client.auth?.serviceId;
+
+    if (!serviceId) {
+      return false;
+    }
+
+    return this.allowedServices.includes(serviceId);
+  }
+}
+
+/**
+ * Composite guard that requires all guards to pass
+ *
+ * @example
+ * ```typescript
+ * @UseWsGuards(new WsAllGuards([
+ *   new WsAuthGuard(),
+ *   new WsPermissionGuard('admin')
+ * ]))
+ * @OnMessage('admin:*')
+ * handleAdminMessage() { }
+ * ```
+ */
+export class WsAllGuards implements WsGuard {
+  constructor(private guards: WsGuard[]) {}
+
+  async canActivate(context: WsExecutionContext): Promise<boolean> {
+    for (const guard of this.guards) {
+      const result = await guard.canActivate(context);
+      if (!result) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}
+
+/**
+ * Composite guard that requires any guard to pass
+ *
+ * @example
+ * ```typescript
+ * @UseWsGuards(new WsAnyGuard([
+ *   new WsPermissionGuard('admin'),
+ *   new WsServiceGuard('internal-service')
+ * ]))
+ * @OnMessage('internal:*')
+ * handleInternalMessage() { }
+ * ```
+ */
+export class WsAnyGuard implements WsGuard {
+  constructor(private guards: WsGuard[]) {}
+
+  async canActivate(context: WsExecutionContext): Promise<boolean> {
+    for (const guard of this.guards) {
+      const result = await guard.canActivate(context);
+      if (result) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+}
+
+// ============================================================================
+// Guard Execution Helper
+// ============================================================================
+
+/**
+ * Execute a list of guards
+ *
+ * @param guards - Array of guard classes or instances
+ * @param context - Execution context
+ * @returns Whether all guards passed
+ */
+export async function executeGuards(
+  guards: (Function | WsGuard)[],
+  context: WsExecutionContext,
+): Promise<boolean> {
+  for (const guard of guards) {
+    let guardInstance: WsGuard;
+
+    // Check if it's already an instance
+    if (typeof guard === 'function') {
+      // Create instance from class
+      guardInstance = new (guard as new () => WsGuard)();
+    } else {
+      guardInstance = guard;
+    }
+
+    const result = await guardInstance.canActivate(context);
+    if (!result) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Create a custom guard from a function
+ *
+ * @param fn - Guard function
+ * @returns Guard class
+ *
+ * @example
+ * ```typescript
+ * const CustomGuard = createGuard((ctx) => {
+ *   return ctx.getClient().metadata.customCheck === true;
+ * });
+ *
+ * @UseWsGuards(CustomGuard)
+ * @OnMessage('custom:*')
+ * handleCustomMessage() { }
+ * ```
+ */
+export function createGuard(
+  fn: (context: WsExecutionContext) => boolean | Promise<boolean>,
+): new () => WsGuard {
+  return class implements WsGuard {
+    canActivate(context: WsExecutionContext): boolean | Promise<boolean> {
+      return fn(context);
+    }
+  };
+}