DeployStack Docs
Backend Development

API Security

This document outlines critical security patterns and best practices for developing secure APIs in the DeployStack Backend. Following these guidelines ensures consistent security behavior and prevents common vulnerabilities.

Overview

Security in API development requires careful consideration of the order in which validation and authorization occur. The DeployStack Backend uses Fastify's hook system to implement security controls, and understanding the proper hook usage is crucial for maintaining security.

The Critical Security Pattern: Authorization Before Validation

The Problem

A common security anti-pattern occurs when authorization checks happen after input validation. This can lead to:

  • Information Disclosure: Unauthorized users receive validation errors instead of proper 403 Forbidden responses
  • Inconsistent Error Responses: Some endpoints return 400 (validation errors) while others return 403 (authorization errors)
  • Security Through Obscurity Violation: API structure and validation rules are leaked to unauthorized users

Real-World Example

Consider this test failure that led to the discovery of this pattern:

// Test expectation
expect(response.status).toBe(403); // Expected: Forbidden

// Actual result  
expect(response.status).toBe(400); // Received: Bad Request (validation error)

The test was sending invalid data to a protected endpoint, expecting a 403 Forbidden response. Instead, it received a 400 Bad Request because validation ran before authorization.

Fastify Hook Execution Order

Understanding Fastify's hook execution order is essential for proper security implementation:

1. onRequest          ← Use for early authentication setup
2. preParsing         ← Use for request preprocessing  
3. preValidation      ← ✅ USE FOR AUTHORIZATION
4. preHandler         ← Use for post-validation processing
5. Route Handler      ← Your business logic

Key Security Principle

Authorization must happen in preValidation to ensure it runs before schema validation.

Correct Implementation Patterns

✅ Secure Pattern: preValidation for Authorization

import { requireGlobalAdmin } from '../../../middleware/roleMiddleware';

// Reusable Schema Constants
const REQUEST_SCHEMA = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1, description: 'Name is required' },
    value: { type: 'string', description: 'Value field' }
  },
  required: ['name', 'value'],
  additionalProperties: false
} as const;

const SUCCESS_RESPONSE_SCHEMA = {
  type: 'object',
  properties: {
    success: { type: 'boolean' },
    message: { type: 'string' }
  },
  required: ['success', 'message']
} as const;

const ERROR_RESPONSE_SCHEMA = {
  type: 'object',
  properties: {
    success: { type: 'boolean', default: false },
    error: { type: 'string' }
  },
  required: ['success', 'error']
} as const;

// TypeScript interfaces
interface RequestBody {
  name: string;
  value: string;
}

interface SuccessResponse {
  success: boolean;
  message: string;
}

interface ErrorResponse {
  success: boolean;
  error: string;
}

export default async function secureRoute(server: FastifyInstance) {
  server.post('/protected-endpoint', {
    preValidation: requireGlobalAdmin(), // ✅ CORRECT: Runs before validation
    schema: {
      tags: ['Protected'],
      summary: 'Protected endpoint',
      description: 'Requires admin permissions',
      security: [{ cookieAuth: [] }],
      
      // Fastify validation schema
      body: REQUEST_SCHEMA,
      
      // OpenAPI documentation (same schema, reused)
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: REQUEST_SCHEMA
          }
        }
      },
      
      response: {
        200: {
          ...SUCCESS_RESPONSE_SCHEMA,
          description: 'Success'
        },
        401: {
          ...ERROR_RESPONSE_SCHEMA,
          description: 'Unauthorized'
        },
        403: {
          ...ERROR_RESPONSE_SCHEMA,
          description: 'Forbidden'
        },
        400: {
          ...ERROR_RESPONSE_SCHEMA,
          description: 'Bad Request'
        }
      }
    }
  }, async (request, reply) => {
    // If we reach here, user is authorized AND input is validated
    const validatedData = request.body as RequestBody;
    
    // Your business logic here
    const successResponse: SuccessResponse = {
      success: true,
      message: 'Operation completed successfully'
    };
    const jsonString = JSON.stringify(successResponse);
    return reply.status(200).type('application/json').send(jsonString);
  });
}

❌ Insecure Pattern: preHandler for Authorization

export default async function insecureRoute(server: FastifyInstance) {
  server.post('/protected-endpoint', {
    schema: {
      // Schema definition...
      body: {
        type: 'object',
        properties: {
          name: { type: 'string', minLength: 1 },
          value: { type: 'string' }
        },
        required: ['name', 'value'],
        additionalProperties: false
      }
    },
    preHandler: requireGlobalAdmin(), // ❌ WRONG: Runs after validation
  }, async (request, reply) => {
    // This handler may never be reached if validation fails first
  });
}

Security Implications

With Incorrect Pattern (preHandler)

Request Flow:
1. Request received
2. Schema validation runs → Returns 400 if invalid
3. Authorization check (never reached if validation fails)
4. Handler execution

Result: Unauthorized users get validation errors, leaking API structure.

With Correct Pattern (preValidation)

Request Flow:
1. Request received  
2. Authorization check → Returns 401/403 if unauthorized
3. Schema validation (only for authorized users)
4. Handler execution

Result: Unauthorized users always get proper 401/403 responses.

Authorization Middleware Usage

Available Middleware Functions

The DeployStack Backend provides several authorization middleware functions:

// Role-based authorization
requireGlobalAdmin()     // Requires 'global_admin' role
requireRole('role_id')   // Requires specific role

// Permission-based authorization  
requirePermission('permission.name')           // Requires specific permission
requireAnyPermission(['perm1', 'perm2'])      // Requires any of the permissions

// Team-aware permission authorization
requireTeamPermission('permission.name')       // Requires permission within team context
requireTeamPermission('permission.name', getTeamIdFn) // Custom team ID extraction

// Ownership-based authorization
requireOwnershipOrAdmin(getUserIdFromRequest) // User owns resource OR is admin

// Dual authentication (Cookie + OAuth2)
requireAuthenticationAny()                    // Accept either cookie or OAuth2 Bearer token
requireOAuthScope('scope.name')               // Enforce OAuth2 scope requirements

Dual Authentication Support

For endpoints that support both web users (cookies) and CLI users (OAuth2 Bearer tokens), use the dual authentication middleware:

import { requireAuthenticationAny, requireOAuthScope } from '../../middleware/oauthMiddleware';

export default async function dualAuthRoute(server: FastifyInstance) {
  server.get('/dual-auth-endpoint', {
    preValidation: [
      requireAuthenticationAny(),     // Accept either auth method
      requireOAuthScope('your:scope') // Enforce OAuth2 scope
    ],
    schema: {
      security: [
        { cookieAuth: [] },    // Cookie authentication
        { bearerAuth: [] }     // OAuth2 Bearer token
      ]
    }
  }, async (request, reply) => {
    // Endpoint accessible via both authentication methods
    const authType = request.tokenPayload ? 'oauth2' : 'cookie';
    const userId = request.user!.id;
  });
}

For detailed OAuth2 implementation, see the Backend OAuth Implementation Guide and Backend Security Policy.

Team-Aware Permission System

For endpoints that operate within team contexts (e.g., /teams/:teamId/resource), use the team-aware permission middleware:

import { requireTeamPermission } from '../../../middleware/roleMiddleware';

// Reusable Schema Constants
const CREATE_RESOURCE_SCHEMA = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1, description: 'Name is required' },
    description: { type: 'string', description: 'Optional description' }
  },
  required: ['name'],
  additionalProperties: false
} as const;

const SUCCESS_RESPONSE_SCHEMA = {
  type: 'object',
  properties: {
    success: { type: 'boolean' },
    message: { type: 'string' }
  },
  required: ['success', 'message']
} as const;

const ERROR_RESPONSE_SCHEMA = {
  type: 'object',
  properties: {
    success: { type: 'boolean', default: false },
    error: { type: 'string' }
  },
  required: ['success', 'error']
} as const;

// TypeScript interfaces
interface CreateResourceRequest {
  name: string;
  description?: string;
}

interface SuccessResponse {
  success: boolean;
  message: string;
}

interface ErrorResponse {
  success: boolean;
  error: string;
}

export default async function teamResourceRoute(server: FastifyInstance) {
  server.post('/teams/:teamId/resources', {
    preValidation: requireTeamPermission('resources.create'), // ✅ Team-aware authorization
    schema: {
      tags: ['Team Resources'],
      summary: 'Create team resource',
      description: 'Creates a resource within the specified team context',
      security: [{ cookieAuth: [] }],
      
      params: {
        type: 'object',
        properties: {
          teamId: { type: 'string', minLength: 1 }
        },
        required: ['teamId'],
        additionalProperties: false
      },
      
      body: CREATE_RESOURCE_SCHEMA,
      
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: CREATE_RESOURCE_SCHEMA
          }
        }
      },
      
      response: {
        201: {
          ...SUCCESS_RESPONSE_SCHEMA,
          description: 'Resource created successfully'
        },
        401: {
          ...ERROR_RESPONSE_SCHEMA,
          description: 'Unauthorized'
        },
        403: {
          ...ERROR_RESPONSE_SCHEMA,
          description: 'Forbidden - Not team member or insufficient permissions'
        },
        400: {
          ...ERROR_RESPONSE_SCHEMA,
          description: 'Bad Request'
        }
      }
    }
  }, async (request, reply) => {
    const { teamId } = request.params as { teamId: string };
    const resourceData = request.body as CreateResourceRequest;
    
    // User is guaranteed to be:
    // 1. Authenticated
    // 2. A member of the specified team
    // 3. Have the 'resources.create' permission within that team
    // 4. Input is validated
    
    // Your business logic here
    const successResponse: SuccessResponse = {
      success: true,
      message: `Resource "${resourceData.name}" created successfully`
    };
    const jsonString = JSON.stringify(successResponse);
    return reply.status(201).type('application/json').send(jsonString);
  });
}

How Team-Aware Permissions Work

The requireTeamPermission() middleware performs these security checks in order:

  1. Authentication Check: Verifies user is logged in
  2. Team ID Extraction: Gets team ID from URL params (:teamId) or custom function
  3. Global Admin Bypass: Global admins can access any team's resources
  4. Team Membership: Verifies user belongs to the specified team
  5. Team Role Lookup: Gets user's role within that team (team_admin or team_user)
  6. Permission Check: Verifies the team role has the required permission

Team Permission Security Model

// Global Admin - Can access any team's resources
if (userRole?.id === 'global_admin') {
  // Check if global admin role has the permission
  return globalPermissions.includes(permission);
}

// Team Member - Must be member with appropriate role
const teamMembership = await TeamService.getTeamMembership(teamId, userId);
const teamRole = teamMembership.role; // 'team_admin' or 'team_user'

// Check if team role has required permission
const rolePermissions = ROLE_DEFINITIONS[teamRole];
return rolePermissions.includes(permission);

Error Responses for Team Permissions

Team-aware endpoints return specific error messages:

// 401 - Not authenticated
{
  "success": false,
  "error": "Authentication required"
}

// 403 - Not a team member
{
  "success": false,
  "error": "You are not a member of this team"
}

// 403 - Team member but insufficient permissions
{
  "success": false,
  "error": "Insufficient permissions for this team operation",
  "required_permission": "resources.create",
  "user_team_role": "team_user"
}

// 400 - Invalid team ID
{
  "success": false,
  "error": "Team ID is required"
}

Permission-based authorization is the preferred approach for most endpoints as it provides:

  • Granular Control: Fine-grained access control per feature
  • Scalability: Easy to add new permissions without role changes
  • Flexibility: Users can have different permission combinations
  • Maintainability: Clear separation between authentication and authorization

Current Permission Structure

The system includes these MCP-related permissions:

// MCP Categories (Admin-only operations)
'mcp.categories.view'     // View category listings
'mcp.categories.create'   // Create new categories
'mcp.categories.edit'     // Modify existing categories
'mcp.categories.delete'   // Remove categories

// MCP Servers (User-accessible operations)
'mcp.servers.read'        // List and search servers (all authenticated users)
'mcp.servers.global.view' // View global server details (admin-only)
'mcp.servers.global.create' // Create global servers (admin-only)
'mcp.servers.global.edit'   // Modify global servers (admin-only)
'mcp.servers.global.delete' // Delete global servers (admin-only)

// MCP Team Servers
'mcp.servers.team.view_all' // View all team servers (admin-only)

// MCP Versions
'mcp.versions.manage'     // Manage server versions (admin-only)

Permission Assignment by Role

// Global Admin - Full access to all MCP features
global_admin: [
  'mcp.servers.read',           // Basic server access
  'mcp.servers.global.view',    // Global server management
  'mcp.servers.global.create',
  'mcp.servers.global.edit', 
  'mcp.servers.global.delete',
  'mcp.servers.team.view_all',  // Cross-team visibility
  'mcp.categories.view',        // Category management
  'mcp.categories.create',
  'mcp.categories.edit',
  'mcp.categories.delete',
  'mcp.versions.manage'         // Version management
]

// Global User - Basic server access only
global_user: [
  'mcp.servers.read'            // Can list and search servers
]

// Team Admin - Basic server access (team servers managed separately)
team_admin: [
  'mcp.servers.read'            // Can list and search servers
]

// Team User - Basic server access
team_user: [
  'mcp.servers.read'            // Can list and search servers
]

Correct Usage Examples

// Global admin only
server.delete('/admin/users/:id', {
  preValidation: requireGlobalAdmin(),
  schema: { /* ... */ }
}, handler);

// Specific permission required
server.post('/settings/bulk', {
  preValidation: requirePermission('settings.edit'),
  schema: { /* ... */ }
}, handler);

// User can access own data OR admin can access any
server.get('/users/:id/profile', {
  preValidation: requireOwnershipOrAdmin(getUserIdFromParams),
  schema: { /* ... */ }
}, handler);

Error Response Consistency

Proper Error Response Structure

All authorization errors should follow this structure:

// 401 Unauthorized (not authenticated)
{
  success: false,
  error: "Authentication required"
}

// 403 Forbidden (authenticated but insufficient permissions)
{
  success: false,
  error: "Insufficient permissions",
  required_permission: "settings.edit" // Optional: what was required
}

Response Status Code Guidelines

  • 401 Unauthorized: User is not authenticated (no valid session)
  • 403 Forbidden: User is authenticated but lacks required permissions
  • 400 Bad Request: Input validation failed (only for authorized users)

Testing Security Properly

Test Authorization Before Validation

describe('Security Tests', () => {
  it('should return 403 for unauthorized users regardless of input validity', async () => {
    // Test with invalid data - should still get 403, not 400
    const response = await request(server)
      .post('/protected-endpoint')
      .set('Cookie', unauthorizedUserCookie)
      .send({ invalid: 'data' }); // Intentionally invalid

    expect(response.status).toBe(403); // Should be 403, not 400
    expect(response.body.error).toContain('permission');
  });

  it('should return 400 for authorized users with invalid input', async () => {
    // Test with invalid data - authorized user should get validation error
    const response = await request(server)
      .post('/protected-endpoint')
      .set('Cookie', authorizedUserCookie)
      .send({ invalid: 'data' }); // Intentionally invalid

    expect(response.status).toBe(400); // Now validation error is appropriate
    expect(response.body.error).toContain('validation');
  });
});

Advanced Security Patterns

Multiple Authorization Checks

For complex authorization requirements:

// Multiple checks in sequence
server.post('/complex-endpoint', {
  preValidation: [
    requireAuthentication(),     // Must be logged in
    requireRole('team_member'),  // Must have team role
    requirePermission('data.write') // Must have write permission
  ],
  schema: { /* ... */ }
}, handler);

Conditional Authorization

// Different auth requirements based on request
async function conditionalAuth(request: FastifyRequest, reply: FastifyReply) {
  const { action } = request.body as { action: string };
  
  if (action === 'delete') {
    return requireGlobalAdmin()(request, reply);
  } else {
    return requirePermission('data.edit')(request, reply);
  }
}

server.post('/conditional-endpoint', {
  preValidation: conditionalAuth,
  schema: { /* ... */ }
}, handler);

Security Checklist

Before deploying any protected endpoint, verify:

  • Authorization uses preValidation, not preHandler
  • Unauthorized users get 401/403, never validation errors
  • Tests verify proper status codes for unauthorized access
  • Error responses don't leak sensitive information
  • Schema validation only runs for authorized users
  • Documentation reflects security requirements

API Pagination Guide

Complete guide to implementing pagination in DeployStack Backend APIs, including best practices, patterns, and examples.

API Documentation Generation

Complete guide to generating OpenAPI specifications, Swagger documentation, and API testing tools for DeployStack Backend development.