Skip to main content

Network Access Control Implementation Summary

Overview​

This document provides a comprehensive overview of the network-based access control system implemented in the Kai platform. The system allows administrators to configure which API endpoints can be accessed from internal versus external networks through a user-friendly admin interface.

Key Implementation Principle: No Hardcoded Restrictions​

IMPORTANT: THE SYSTEM HAS ZERO HARDCODED ACCESS RESTRICTIONS.

The single most important design principle of our implementation is that no API endpoint has its access level hardcoded in the source code:

  • Any endpoint can be configured to be internal-only or external-allowed
  • Even sensitive operations (like "update analytics", "clear data", or "system configuration")
  • All access settings are stored in database tables, completely separate from code
  • Administrators have complete control through the admin interface
  • Changes take effect immediately without requiring code changes or redeployment

Architecture Components​

1. Database Models​

Two primary database models store all access control configurations:

// Internal network definitions
interface InternalNetwork {
  id: string;
  cidr: string;          // CIDR notation (e.g., "10.0.0.0/8")
  description: string;   // Human-readable description
  createdAt: Date;
  updatedAt: Date;
}

// Endpoint access rules
interface EndpointAccessRule {
  id: string;
  path: string;          // API endpoint path
  method: string;        // HTTP method (GET, POST, PUT, DELETE)
  allowInternal: boolean; // Whether internal networks can access
  allowExternal: boolean; // Whether external networks can access
  createdAt: Date;
  updatedAt: Date;
}

2. Network Detection Utilities (utils/network.ts)​

Utilities for identifying the source network of requests:

// Check if a request comes from an internal network
export function isInternalRequest(req: Request): boolean {
  const clientIP = req.ip || req.socket.remoteAddress;
  const internalNetworks = getInternalNetworksFromDatabase();
  
  return internalNetworks.some(network => isInCIDR(clientIP, network.cidr));
}

// Check if an IP falls within a CIDR range
export function isInCIDR(ip: string, cidr: string): boolean {
  // Implementation with proper CIDR validation
}

// Network access types enum
export enum NetworkAccessType {
  ANY = 'any',
  INTERNAL_ONLY = 'internal-only',
  EXTERNAL_ALLOWED = 'external-allowed'
}

3. Enhanced Authorization Middleware (middleware/auth.middleware.ts)​

Extended the existing authorization system to support network-based access control:

export const authorize = (options: { 
  roles?: string[], 
  accessType?: NetworkAccessType 
}) => {
  return (req: Request, res: Response, next: NextFunction) => {
    // Existing role-based checks
    if (options.roles && !req.user?.roles.some(role => options.roles?.includes(role))) {
      return next(new AuthorizationError('Insufficient role permissions'));
    }
    
    // Network-based access check
    if (options.accessType === NetworkAccessType.INTERNAL_ONLY) {
      const endpointRule = getEndpointRuleFromDatabase(req.path, req.method);
      
      // If endpoint is configured as internal-only and request is external
      if (endpointRule.allowExternal === false && !isInternalRequest(req)) {
        return next(new AuthorizationError('This endpoint is only accessible from internal networks'));
      }
    }
    
    next();
  };
};

4. Admin Interface (components/NetworkAccessPanel.tsx)​

User interface for administrators to configure network access settings:

  • Internal networks management: Add, view, and remove CIDR ranges
  • Endpoint access control: Toggle internal/external access for any endpoint
  • Search and filter: Quickly find specific endpoints
  • Real-time updates: Changes take effect immediately

5. API Routes Integration​

Applying network-based access control to API endpoints:

// Example of applying network access control to routes
router.delete('/data', 
  authMiddleware, 
  authorize({ 
    roles: ['admin'], 
    accessType: NetworkAccessType.INTERNAL_ONLY 
  }), 
  asyncHandler(analyticsController.clearAnalyticsData)
);

Configuration​

Admin Dashboard Configuration​

Administrators can configure all aspects of network access control through the admin dashboard:

  1. Navigate to Settings > Network Access
  2. Define internal networks using CIDR notation (e.g., 10.0.0.0/8)
  3. Configure access permissions for any API endpoint:
    • Toggle internal access on/off
    • Toggle external access on/off
    • Changes take effect immediately

Environment Configuration​

For deployment environments, basic configuration can be set via environment variables:

# .env file
INTERNAL_NETWORKS=127.0.0.1/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
TRUST_PROXY=true

Security Implementation​

Multi-layered Security​

Network access control adds another layer to the security model:

  1. Authentication: Verifies user identity (JWT tokens)
  2. Role-based Authorization: Checks user has required role
  3. Network-based Authorization: Checks request comes from allowed network type
  4. Rate Limiting: Protects against abuse (separate system)

Fail-Secure Design​

The system is designed to fail securely:

  • Requests default to "external" if source determination fails
  • System applies most restrictive rules in case of ambiguity
  • All decision points are thoroughly logged

Edge Case Handling​

The implementation handles various edge cases:

  • Proxy configurations (X-Forwarded-For headers)
  • IPv4 and IPv6 addresses
  • VPN connections
  • Cloud provider network configurations

While no restrictions are hardcoded, the system provides sensible default configurations:

Endpoint CategoryDefault AccessExamples
AuthenticationExternal/api/auth/login, /api/auth/register
Public dataExternal/api/materials, /api/search
User accountExternal/api/users/me, /api/profile
Admin viewsExternal/api/admin/dashboard, /api/admin/analytics
System configInternal/api/admin/settings, /api/admin/system
Data deletionInternal/api/admin/analytics/data (DELETE)
Security opsInternal/api/admin/users (PUT/DELETE)

These defaults can be changed at any time through the admin interface.

Complete Configurability​

The most important aspect of this implementation is that all endpoint access restrictions are fully configurable through the admin interface:

  • No special coding required to change access rules
  • Any endpoint can be made internal-only or external-allowed
  • All configuration is stored in the database, not in code
  • Updates take effect immediately without deployments

Conclusion​

The network access control system provides a flexible, admin-configurable approach to restricting API endpoints based on network source. Administrators have complete control over which endpoints are accessible from internal versus external networks through an intuitive admin interface, with no hardcoded restrictions in the codebase.

  • API Reference: Complete list of API endpoints with recommended access settings
  • Network Access Control Guide: User guide for administrators