Part 4: Authentication and Authorization in gRPC

The $75,000 Security Lesson

In March 2022, I deployed a gRPC microservices system for a fintech client. Authentication was "on my todo list." Within 72 hours, an attacker discovered an unprotected gRPC endpoint and drained test funds from merchant accounts. While it was test money, the incident cost approximately $75,000 in emergency security audits, legal reviews, and implementation time.

The mistake? I assumed gRPC services behind a firewall didn't need authentication. I was catastrophically wrong. This part covers everything I learned from that painful lesson.

Authentication Strategies for gRPC

1. JWT-Based Authentication (My Standard)

// protos/common/auth.proto
syntax = "proto3";

package common.auth.v1;

message AuthToken {
  string access_token = 1;
  string refresh_token = 2;
  int64 expires_at = 3;
}

message User {
  string id = 1;
  string email = 2;
  repeated string roles = 3;
  map<string, string> permissions = 4;
}

JWT Service Implementation

// src/services/auth.service.ts
import jwt from 'jsonwebtoken';
import bcrypt from 'bcrypt';
import { logger } from '@config/logger';

export interface JWTPayload {
  userId: string;
  email: string;
  roles: string[];
  permissions: Record<string, boolean>;
}

export interface TokenPair {
  accessToken: string;
  refreshToken: string;
  expiresAt: number;
}

export class AuthService {
  private readonly ACCESS_TOKEN_SECRET: string;
  private readonly REFRESH_TOKEN_SECRET: string;
  private readonly ACCESS_TOKEN_EXPIRY = '15m'; // 15 minutes
  private readonly REFRESH_TOKEN_EXPIRY = '7d'; // 7 days

  constructor() {
    this.ACCESS_TOKEN_SECRET = process.env.JWT_ACCESS_SECRET || 'change-me';
    this.REFRESH_TOKEN_SECRET = process.env.JWT_REFRESH_SECRET || 'change-me-too';

    if (process.env.NODE_ENV === 'production') {
      if (this.ACCESS_TOKEN_SECRET === 'change-me' || this.REFRESH_TOKEN_SECRET === 'change-me-too') {
        throw new Error('JWT secrets must be set in production');
      }
    }
  }

  async hashPassword(password: string): Promise<string> {
    const saltRounds = 12;
    return bcrypt.hash(password, saltRounds);
  }

  async verifyPassword(password: string, hash: string): Promise<boolean> {
    return bcrypt.compare(password, hash);
  }

  generateTokenPair(payload: JWTPayload): TokenPair {
    const accessToken = jwt.sign(payload, this.ACCESS_TOKEN_SECRET, {
      expiresIn: this.ACCESS_TOKEN_EXPIRY,
      issuer: 'grpc-ecommerce',
      audience: 'grpc-services',
    });

    const refreshToken = jwt.sign(
      { userId: payload.userId },
      this.REFRESH_TOKEN_SECRET,
      {
        expiresIn: this.REFRESH_TOKEN_EXPIRY,
        issuer: 'grpc-ecommerce',
        audience: 'grpc-services',
      }
    );

    // Calculate expiration time (15 minutes from now)
    const expiresAt = Date.now() + 15 * 60 * 1000;

    logger.info('Token pair generated', { userId: payload.userId });

    return {
      accessToken,
      refreshToken,
      expiresAt,
    };
  }

  verifyAccessToken(token: string): JWTPayload {
    try {
      const decoded = jwt.verify(token, this.ACCESS_TOKEN_SECRET, {
        issuer: 'grpc-ecommerce',
        audience: 'grpc-services',
      }) as JWTPayload;

      return decoded;
    } catch (error) {
      logger.warn('Access token verification failed', { error });
      throw new Error('Invalid or expired access token');
    }
  }

  verifyRefreshToken(token: string): { userId: string } {
    try {
      const decoded = jwt.verify(token, this.REFRESH_TOKEN_SECRET, {
        issuer: 'grpc-ecommerce',
        audience: 'grpc-services',
      }) as { userId: string };

      return decoded;
    } catch (error) {
      logger.warn('Refresh token verification failed', { error });
      throw new Error('Invalid or expired refresh token');
    }
  }

  refreshTokenPair(refreshToken: string, user: JWTPayload): TokenPair {
    // Verify refresh token
    this.verifyRefreshToken(refreshToken);

    // Generate new token pair
    return this.generateTokenPair(user);
  }
}

Authentication Interceptor

// src/grpc/interceptors/auth.interceptor.ts
import * as grpc from '@grpc/grpc-js';
import { AuthService } from '@services/auth.service';
import { logger } from '@config/logger';

export interface AuthContext {
  userId: string;
  email: string;
  roles: string[];
  permissions: Record<string, boolean>;
}

// Extend ServerCall to include authContext
declare module '@grpc/grpc-js' {
  interface ServerUnaryCall<RequestType, ResponseType> {
    authContext?: AuthContext;
  }
  interface ServerWritableStream<RequestType, ResponseType> {
    authContext?: AuthContext;
  }
  interface ServerReadableStream<RequestType, ResponseType> {
    authContext?: AuthContext;
  }
  interface ServerDuplexStream<RequestType, ResponseType> {
    authContext?: AuthContext;
  }
}

const authService = new AuthService();

// Public endpoints that don't require authentication
const PUBLIC_METHODS = [
  '/auth.v1.AuthService/Login',
  '/auth.v1.AuthService/Register',
  '/auth.v1.AuthService/RefreshToken',
  '/health.v1.HealthService/Check',
];

export function authInterceptor(
  call: grpc.ServerUnaryCall<any, any> | grpc.ServerWritableStream<any, any>,
  callback: grpc.sendUnaryData<any> | undefined,
  next: () => void
): void {
  const method = call.getPath();

  // Skip authentication for public endpoints
  if (PUBLIC_METHODS.includes(method)) {
    return next();
  }

  try {
    // Extract token from metadata
    const metadata = call.metadata;
    const authHeader = metadata.get('authorization');

    if (!authHeader || authHeader.length === 0) {
      const error: grpc.ServiceError = {
        name: 'Unauthenticated',
        message: 'Missing authentication token',
        code: grpc.status.UNAUTHENTICATED,
      };

      if (callback) {
        return callback(error);
      } else {
        (call as grpc.ServerWritableStream<any, any>).destroy(error);
        return;
      }
    }

    // Parse Bearer token
    const token = authHeader[0].toString();
    const bearerMatch = token.match(/^Bearer (.+)$/);

    if (!bearerMatch) {
      const error: grpc.ServiceError = {
        name: 'Unauthenticated',
        message: 'Invalid authentication token format',
        code: grpc.status.UNAUTHENTICATED,
      };

      if (callback) {
        return callback(error);
      } else {
        (call as grpc.ServerWritableStream<any, any>).destroy(error);
        return;
      }
    }

    const jwtToken = bearerMatch[1];

    // Verify token
    const payload = authService.verifyAccessToken(jwtToken);

    // Attach auth context to call
    call.authContext = {
      userId: payload.userId,
      email: payload.email,
      roles: payload.roles,
      permissions: payload.permissions,
    };

    logger.debug('Authentication successful', {
      userId: payload.userId,
      method,
    });

    next();
  } catch (error) {
    logger.warn('Authentication failed', { error, method });

    const grpcError: grpc.ServiceError = {
      name: 'Unauthenticated',
      message: error instanceof Error ? error.message : 'Authentication failed',
      code: grpc.status.UNAUTHENTICATED,
    };

    if (callback) {
      callback(grpcError);
    } else {
      (call as grpc.ServerWritableStream<any, any>).destroy(grpcError);
    }
  }
}

Using Auth Interceptor in Server

// src/grpc/server.ts
import * as grpc from '@grpc/grpc-js';
import { authInterceptor } from './interceptors/auth.interceptor';

export class GrpcServer {
  private server: grpc.Server;

  constructor() {
    this.server = new grpc.Server({
      // Enable interceptors
      interceptors: [authInterceptor],
      'grpc.max_receive_message_length': 10 * 1024 * 1024,
      'grpc.max_send_message_length': 10 * 1024 * 1024,
    });

    this.registerServices();
  }

  // ... rest of the server implementation
}

Client Authentication

// src/client/grpc-client.ts
import * as grpc from '@grpc/grpc-js';
import { OrderServiceClient } from '@generated/order/v1/order';

export class AuthenticatedGrpcClient {
  private client: OrderServiceClient;
  private accessToken: string;

  constructor(serverAddress: string, accessToken: string) {
    this.accessToken = accessToken;
    
    this.client = new OrderServiceClient(
      serverAddress,
      grpc.credentials.createInsecure() // Use createSsl() in production
    );
  }

  private createAuthMetadata(): grpc.Metadata {
    const metadata = new grpc.Metadata();
    metadata.add('authorization', `Bearer ${this.accessToken}`);
    return metadata;
  }

  async createOrder(request: CreateOrderRequest): Promise<Order> {
    return new Promise((resolve, reject) => {
      this.client.createOrder(
        request,
        this.createAuthMetadata(),
        (error, response) => {
          if (error) {
            reject(error);
          } else {
            resolve(response);
          }
        }
      );
    });
  }

  async getOrder(orderId: string): Promise<Order> {
    return new Promise((resolve, reject) => {
      this.client.getOrder(
        { id: orderId },
        this.createAuthMetadata(),
        (error, response) => {
          if (error) {
            reject(error);
          } else {
            resolve(response);
          }
        }
      );
    });
  }

  // Update access token
  updateToken(newToken: string): void {
    this.accessToken = newToken;
  }
}

Authorization Strategies

1. Role-Based Access Control (RBAC)

// src/utils/rbac.ts
export enum Role {
  ADMIN = 'admin',
  MANAGER = 'manager',
  USER = 'user',
  GUEST = 'guest',
}

export enum Permission {
  // Order permissions
  ORDER_CREATE = 'order:create',
  ORDER_READ = 'order:read',
  ORDER_UPDATE = 'order:update',
  ORDER_DELETE = 'order:delete',
  ORDER_READ_ALL = 'order:read:all',
  
  // Product permissions
  PRODUCT_CREATE = 'product:create',
  PRODUCT_READ = 'product:read',
  PRODUCT_UPDATE = 'product:update',
  PRODUCT_DELETE = 'product:delete',
  
  // User permissions
  USER_CREATE = 'user:create',
  USER_READ = 'user:read',
  USER_UPDATE = 'user:update',
  USER_DELETE = 'user:delete',
}

// Role to permissions mapping
export const rolePermissions: Record<Role, Permission[]> = {
  [Role.ADMIN]: [
    // Full access to everything
    Permission.ORDER_CREATE,
    Permission.ORDER_READ,
    Permission.ORDER_UPDATE,
    Permission.ORDER_DELETE,
    Permission.ORDER_READ_ALL,
    Permission.PRODUCT_CREATE,
    Permission.PRODUCT_READ,
    Permission.PRODUCT_UPDATE,
    Permission.PRODUCT_DELETE,
    Permission.USER_CREATE,
    Permission.USER_READ,
    Permission.USER_UPDATE,
    Permission.USER_DELETE,
  ],
  [Role.MANAGER]: [
    // Can manage orders and products
    Permission.ORDER_CREATE,
    Permission.ORDER_READ,
    Permission.ORDER_UPDATE,
    Permission.ORDER_READ_ALL,
    Permission.PRODUCT_CREATE,
    Permission.PRODUCT_READ,
    Permission.PRODUCT_UPDATE,
  ],
  [Role.USER]: [
    // Can only manage own orders
    Permission.ORDER_CREATE,
    Permission.ORDER_READ,
    Permission.PRODUCT_READ,
  ],
  [Role.GUEST]: [
    // Read-only access
    Permission.PRODUCT_READ,
  ],
};

export function hasPermission(roles: string[], permission: Permission): boolean {
  for (const role of roles) {
    const permissions = rolePermissions[role as Role] || [];
    if (permissions.includes(permission)) {
      return true;
    }
  }
  return false;
}

export function hasAnyRole(userRoles: string[], requiredRoles: Role[]): boolean {
  return requiredRoles.some(role => userRoles.includes(role));
}

export function hasAllRoles(userRoles: string[], requiredRoles: Role[]): boolean {
  return requiredRoles.every(role => userRoles.includes(role));
}

Authorization Interceptor

// src/grpc/interceptors/authorization.interceptor.ts
import * as grpc from '@grpc/grpc-js';
import { Permission, hasPermission } from '@utils/rbac';
import { logger } from '@config/logger';

// Method to required permissions mapping
const methodPermissions: Record<string, Permission[]> = {
  // Order methods
  '/order.v1.OrderService/CreateOrder': [Permission.ORDER_CREATE],
  '/order.v1.OrderService/GetOrder': [Permission.ORDER_READ],
  '/order.v1.OrderService/ListOrders': [Permission.ORDER_READ],
  '/order.v1.OrderService/UpdateOrderStatus': [Permission.ORDER_UPDATE],
  '/order.v1.OrderService/CancelOrder': [Permission.ORDER_DELETE],
  
  // Product methods
  '/product.v1.ProductService/GetProduct': [Permission.PRODUCT_READ],
  '/product.v1.ProductService/ListProducts': [Permission.PRODUCT_READ],
  '/product.v1.ProductService/CreateProduct': [Permission.PRODUCT_CREATE],
  '/product.v1.ProductService/UpdateProduct': [Permission.PRODUCT_UPDATE],
  '/product.v1.ProductService/DeleteProduct': [Permission.PRODUCT_DELETE],
};

export function authorizationInterceptor(
  call: grpc.ServerUnaryCall<any, any> | grpc.ServerWritableStream<any, any>,
  callback: grpc.sendUnaryData<any> | undefined,
  next: () => void
): void {
  const method = call.getPath();
  const authContext = call.authContext;

  // If no auth context, skip (auth interceptor will handle)
  if (!authContext) {
    return next();
  }

  // Get required permissions for this method
  const requiredPermissions = methodPermissions[method];

  // If no permissions required, allow
  if (!requiredPermissions || requiredPermissions.length === 0) {
    return next();
  }

  // Check if user has at least one required permission
  const hasAccess = requiredPermissions.some(permission =>
    hasPermission(authContext.roles, permission)
  );

  if (!hasAccess) {
    logger.warn('Authorization failed', {
      userId: authContext.userId,
      method,
      requiredPermissions,
      userRoles: authContext.roles,
    });

    const error: grpc.ServiceError = {
      name: 'PermissionDenied',
      message: 'Insufficient permissions',
      code: grpc.status.PERMISSION_DENIED,
    };

    if (callback) {
      callback(error);
    } else {
      (call as grpc.ServerWritableStream<any, any>).destroy(error);
    }
    return;
  }

  logger.debug('Authorization successful', {
    userId: authContext.userId,
    method,
  });

  next();
}

Resource-Level Authorization

// src/services/order.service.ts
import * as grpc from '@grpc/grpc-js';
import { Permission, hasPermission } from '@utils/rbac';

export class OrderService {
  async getOrder(orderId: string, authContext: AuthContext): Promise<Order> {
    const order = await this.orderRepository.findById(orderId);

    if (!order) {
      throw {
        code: grpc.status.NOT_FOUND,
        message: `Order ${orderId} not found`,
      };
    }

    // Check ownership or admin permission
    const canReadAll = hasPermission(authContext.roles, Permission.ORDER_READ_ALL);
    const isOwner = order.userId === authContext.userId;

    if (!canReadAll && !isOwner) {
      throw {
        code: grpc.status.PERMISSION_DENIED,
        message: 'You do not have permission to view this order',
      };
    }

    return order;
  }

  async updateOrderStatus(
    orderId: string,
    newStatus: OrderStatus,
    authContext: AuthContext
  ): Promise<Order> {
    // Only admins and managers can update order status
    if (!hasPermission(authContext.roles, Permission.ORDER_UPDATE)) {
      throw {
        code: grpc.status.PERMISSION_DENIED,
        message: 'You do not have permission to update order status',
      };
    }

    const order = await this.orderRepository.findById(orderId);

    if (!order) {
      throw {
        code: grpc.status.NOT_FOUND,
        message: `Order ${orderId} not found`,
      };
    }

    // Validate status transition
    if (!this.isValidStatusTransition(order.status, newStatus)) {
      throw {
        code: grpc.status.FAILED_PRECONDITION,
        message: `Invalid status transition from ${order.status} to ${newStatus}`,
      };
    }

    const updated = await this.orderRepository.updateStatus(orderId, newStatus);
    
    logger.info('Order status updated', {
      orderId,
      oldStatus: order.status,
      newStatus,
      updatedBy: authContext.userId,
    });

    return updated!;
  }
}

Handler with Authorization

// src/grpc/handlers/order.handler.ts
import * as grpc from '@grpc/grpc-js';
import { OrderService } from '@services/order.service';

export class OrderHandler {
  constructor(private orderService: OrderService) {}

  async getOrder(
    call: grpc.ServerUnaryCall<GetOrderRequest, Order>,
    callback: grpc.sendUnaryData<Order>
  ): Promise<void> {
    try {
      // Auth context is attached by auth interceptor
      if (!call.authContext) {
        return callback({
          code: grpc.status.UNAUTHENTICATED,
          message: 'Authentication required',
        });
      }

      const order = await this.orderService.getOrder(
        call.request.id,
        call.authContext
      );

      callback(null, order);
    } catch (error: any) {
      logger.error('getOrder failed', { error });
      callback(error);
    }
  }

  async updateOrderStatus(
    call: grpc.ServerUnaryCall<UpdateOrderStatusRequest, Order>,
    callback: grpc.sendUnaryData<Order>
  ): Promise<void> {
    try {
      if (!call.authContext) {
        return callback({
          code: grpc.status.UNAUTHENTICATED,
          message: 'Authentication required',
        });
      }

      const { id, status } = call.request;
      
      const order = await this.orderService.updateOrderStatus(
        id,
        status,
        call.authContext
      );

      callback(null, order);
    } catch (error: any) {
      logger.error('updateOrderStatus failed', { error });
      callback(error);
    }
  }
}

API Key Authentication (Service-to-Service)

API Key Service

// src/services/api-key.service.ts
import crypto from 'crypto';
import { database } from '@config/database';
import { redis } from '@config/redis';
import { logger } from '@config/logger';

export interface ApiKey {
  id: string;
  name: string;
  keyHash: string;
  serviceId: string;
  permissions: string[];
  createdAt: Date;
  expiresAt?: Date;
  lastUsedAt?: Date;
}

export class ApiKeyService {
  private readonly CACHE_TTL = 3600; // 1 hour

  generateApiKey(): { key: string; hash: string } {
    // Generate random 32-byte key
    const key = crypto.randomBytes(32).toString('base64');
    
    // Hash the key (store hash, never the plain key)
    const hash = crypto
      .createHash('sha256')
      .update(key)
      .digest('hex');

    return { key, hash };
  }

  async createApiKey(
    name: string,
    serviceId: string,
    permissions: string[],
    expiresAt?: Date
  ): Promise<{ apiKey: ApiKey; plainKey: string }> {
    const { key, hash } = this.generateApiKey();

    const result = await database.query<ApiKey>(
      `INSERT INTO api_keys (name, key_hash, service_id, permissions, expires_at)
       VALUES ($1, $2, $3, $4, $5)
       RETURNING *`,
      [name, hash, serviceId, JSON.stringify(permissions), expiresAt]
    );

    const apiKey = result[0];

    logger.info('API key created', {
      apiKeyId: apiKey.id,
      serviceId,
      name,
    });

    return {
      apiKey,
      plainKey: key, // Return only once, never store plain key
    };
  }

  async verifyApiKey(key: string): Promise<ApiKey | null> {
    const hash = crypto.createHash('sha256').update(key).digest('hex');

    // Try cache first
    const cached = await redis.get<ApiKey>(`apikey:${hash}`);
    if (cached) {
      // Update last used timestamp (async, don't wait)
      this.updateLastUsed(cached.id).catch(() => {});
      return cached;
    }

    // Query database
    const result = await database.query<ApiKey>(
      `SELECT * FROM api_keys 
       WHERE key_hash = $1 
       AND (expires_at IS NULL OR expires_at > NOW())`,
      [hash]
    );

    if (result.length === 0) {
      return null;
    }

    const apiKey = result[0];

    // Cache the API key
    await redis.set(`apikey:${hash}`, apiKey, this.CACHE_TTL);

    // Update last used timestamp (async)
    this.updateLastUsed(apiKey.id).catch(() => {});

    return apiKey;
  }

  private async updateLastUsed(apiKeyId: string): Promise<void> {
    await database.query(
      'UPDATE api_keys SET last_used_at = NOW() WHERE id = $1',
      [apiKeyId]
    );
  }

  async revokeApiKey(id: string): Promise<void> {
    await database.query('DELETE FROM api_keys WHERE id = $1', [id]);
    
    logger.info('API key revoked', { apiKeyId: id });
  }
}

API Key Interceptor

// src/grpc/interceptors/api-key.interceptor.ts
import * as grpc from '@grpc/grpc-js';
import { ApiKeyService } from '@services/api-key.service';
import { logger } from '@config/logger';

const apiKeyService = new ApiKeyService();

export function apiKeyInterceptor(
  call: grpc.ServerUnaryCall<any, any> | grpc.ServerWritableStream<any, any>,
  callback: grpc.sendUnaryData<any> | undefined,
  next: () => void
): void {
  const metadata = call.metadata;
  const apiKey = metadata.get('x-api-key');

  if (!apiKey || apiKey.length === 0) {
    // No API key, continue to JWT auth
    return next();
  }

  const key = apiKey[0].toString();

  apiKeyService
    .verifyApiKey(key)
    .then(apiKeyData => {
      if (!apiKeyData) {
        const error: grpc.ServiceError = {
          name: 'Unauthenticated',
          message: 'Invalid or expired API key',
          code: grpc.status.UNAUTHENTICATED,
        };

        if (callback) {
          return callback(error);
        } else {
          (call as grpc.ServerWritableStream<any, any>).destroy(error);
          return;
        }
      }

      // Attach service context
      call.authContext = {
        userId: apiKeyData.serviceId,
        email: `${apiKeyData.serviceId}@service`,
        roles: ['service'],
        permissions: apiKeyData.permissions.reduce((acc, perm) => {
          acc[perm] = true;
          return acc;
        }, {} as Record<string, boolean>),
      };

      logger.debug('API key authentication successful', {
        serviceId: apiKeyData.serviceId,
        apiKeyId: apiKeyData.id,
      });

      next();
    })
    .catch(error => {
      logger.error('API key verification failed', { error });

      const grpcError: grpc.ServiceError = {
        name: 'Internal',
        message: 'Authentication error',
        code: grpc.status.INTERNAL,
      };

      if (callback) {
        callback(grpcError);
      } else {
        (call as grpc.ServerWritableStream<any, any>).destroy(grpcError);
      }
    });
}

Mutual TLS (mTLS) Authentication

Server Configuration

// src/config/tls.ts
import fs from 'fs';
import * as grpc from '@grpc/grpc-js';
import { logger } from './logger';

export function createSecureServerCredentials(): grpc.ServerCredentials {
  const serverCert = fs.readFileSync(process.env.TLS_CERT_PATH || './certs/server-cert.pem');
  const serverKey = fs.readFileSync(process.env.TLS_KEY_PATH || './certs/server-key.pem');
  const caCert = fs.readFileSync(process.env.TLS_CA_PATH || './certs/ca-cert.pem');

  const credentials = grpc.ServerCredentials.createSsl(
    caCert,
    [
      {
        cert_chain: serverCert,
        private_key: serverKey,
      },
    ],
    true // checkClientCertificate - require client certificate
  );

  logger.info('Secure server credentials created with mTLS');

  return credentials;
}

export function createSecureClientCredentials(): grpc.ChannelCredentials {
  const clientCert = fs.readFileSync(process.env.TLS_CLIENT_CERT_PATH || './certs/client-cert.pem');
  const clientKey = fs.readFileSync(process.env.TLS_CLIENT_KEY_PATH || './certs/client-key.pem');
  const caCert = fs.readFileSync(process.env.TLS_CA_PATH || './certs/ca-cert.pem');

  const credentials = grpc.credentials.createSsl(
    caCert,
    clientKey,
    clientCert
  );

  logger.info('Secure client credentials created with mTLS');

  return credentials;
}

Server with mTLS

// src/grpc/server.ts
import { createSecureServerCredentials } from '@config/tls';

export class GrpcServer {
  async start(port: number = 50051): Promise<void> {
    return new Promise((resolve, reject) => {
      const credentials = process.env.NODE_ENV === 'production'
        ? createSecureServerCredentials()
        : grpc.ServerCredentials.createInsecure();

      this.server.bindAsync(
        `0.0.0.0:${port}`,
        credentials,
        (error, port) => {
          if (error) {
            logger.error('Failed to bind server', { error });
            reject(error);
            return;
          }

          this.server.start();
          logger.info(`gRPC server started on port ${port} with ${
            process.env.NODE_ENV === 'production' ? 'mTLS' : 'insecure'
          } credentials`);
          resolve();
        }
      );
    });
  }
}

Client with mTLS

// src/client/secure-client.ts
import * as grpc from '@grpc/grpc-js';
import { createSecureClientCredentials } from '@config/tls';
import { OrderServiceClient } from '@generated/order/v1/order';

export class SecureGrpcClient {
  private client: OrderServiceClient;

  constructor(serverAddress: string) {
    const credentials = createSecureClientCredentials();
    
    this.client = new OrderServiceClient(serverAddress, credentials);
  }

  // Client methods...
}

Rate Limiting

// src/grpc/interceptors/rate-limit.interceptor.ts
import * as grpc from '@grpc/grpc-js';
import { redis } from '@config/redis';
import { logger } from '@config/logger';

interface RateLimitConfig {
  windowMs: number;  // Time window in milliseconds
  maxRequests: number;  // Max requests per window
}

const rateLimitConfigs: Record<string, RateLimitConfig> = {
  '/order.v1.OrderService/CreateOrder': {
    windowMs: 60000, // 1 minute
    maxRequests: 10,
  },
  '/order.v1.OrderService/ListOrders': {
    windowMs: 60000,
    maxRequests: 100,
  },
  // Default for all other methods
  default: {
    windowMs: 60000,
    maxRequests: 50,
  },
};

export function rateLimitInterceptor(
  call: grpc.ServerUnaryCall<any, any> | grpc.ServerWritableStream<any, any>,
  callback: grpc.sendUnaryData<any> | undefined,
  next: () => void
): void {
  const method = call.getPath();
  const authContext = call.authContext;

  if (!authContext) {
    return next(); // Skip rate limiting for unauthenticated requests
  }

  const config = rateLimitConfigs[method] || rateLimitConfigs.default;
  const key = `ratelimit:${authContext.userId}:${method}`;

  redis
    .get<number>(key)
    .then(async count => {
      const currentCount = count || 0;

      if (currentCount >= config.maxRequests) {
        logger.warn('Rate limit exceeded', {
          userId: authContext.userId,
          method,
          count: currentCount,
          limit: config.maxRequests,
        });

        const error: grpc.ServiceError = {
          name: 'ResourceExhausted',
          message: 'Rate limit exceeded',
          code: grpc.status.RESOURCE_EXHAUSTED,
        };

        if (callback) {
          return callback(error);
        } else {
          (call as grpc.ServerWritableStream<any, any>).destroy(error);
          return;
        }
      }

      // Increment counter
      await redis.set(key, currentCount + 1, Math.ceil(config.windowMs / 1000));

      next();
    })
    .catch(error => {
      logger.error('Rate limit check failed', { error });
      // Allow request if Redis fails
      next();
    });
}

Complete Server with All Interceptors

// src/grpc/server.ts
import * as grpc from '@grpc/grpc-js';
import { authInterceptor } from './interceptors/auth.interceptor';
import { authorizationInterceptor } from './interceptors/authorization.interceptor';
import { apiKeyInterceptor } from './interceptors/api-key.interceptor';
import { rateLimitInterceptor } from './interceptors/rate-limit.interceptor';

export class GrpcServer {
  private server: grpc.Server;

  constructor() {
    this.server = new grpc.Server({
      // Chain interceptors (executed in order)
      interceptors: [
        apiKeyInterceptor,      // 1. Try API key auth first
        authInterceptor,        // 2. Then JWT auth
        authorizationInterceptor, // 3. Check permissions
        rateLimitInterceptor,   // 4. Rate limiting
      ],
      'grpc.max_receive_message_length': 10 * 1024 * 1024,
      'grpc.max_send_message_length': 10 * 1024 * 1024,
    });

    this.registerServices();
  }

  // ... rest of implementation
}

Best Practices from Production

1. Token Rotation

// Automatically refresh tokens before expiry
class TokenManager {
  private accessToken: string;
  private refreshToken: string;
  private expiresAt: number;
  private refreshInterval?: NodeJS.Timeout;

  constructor(tokens: TokenPair) {
    this.accessToken = tokens.accessToken;
    this.refreshToken = tokens.refreshToken;
    this.expiresAt = tokens.expiresAt;

    // Refresh 2 minutes before expiry
    this.scheduleRefresh();
  }

  private scheduleRefresh(): void {
    const refreshTime = this.expiresAt - Date.now() - 2 * 60 * 1000;

    if (refreshTime > 0) {
      this.refreshInterval = setTimeout(async () => {
        await this.refresh();
      }, refreshTime);
    }
  }

  private async refresh(): Promise<void> {
    try {
      // Call refresh endpoint
      const newTokens = await authClient.refreshToken(this.refreshToken);
      
      this.accessToken = newTokens.accessToken;
      this.refreshToken = newTokens.refreshToken;
      this.expiresAt = newTokens.expiresAt;

      this.scheduleRefresh();

      logger.info('Tokens refreshed successfully');
    } catch (error) {
      logger.error('Token refresh failed', { error });
      // Implement re-authentication logic
    }
  }

  getAccessToken(): string {
    return this.accessToken;
  }

  destroy(): void {
    if (this.refreshInterval) {
      clearTimeout(this.refreshInterval);
    }
  }
}

2. Audit Logging

// Log all security-related events
export function auditInterceptor(
  call: grpc.ServerUnaryCall<any, any> | grpc.ServerWritableStream<any, any>,
  callback: grpc.sendUnaryData<any> | undefined,
  next: () => void
): void {
  const method = call.getPath();
  const authContext = call.authContext;
  const startTime = Date.now();

  const originalCallback = callback;
  
  if (callback) {
    callback = (error, response) => {
      const duration = Date.now() - startTime;

      logger.info('gRPC call completed', {
        method,
        userId: authContext?.userId,
        duration,
        success: !error,
        error: error?.message,
      });

      originalCallback!(error, response);
    };
  }

  next();
}

Key Takeaways

1. Defense in Depth: Use multiple security layers (authentication + authorization + rate limiting)

2. JWT Best Practices: Short-lived access tokens (15 min), longer refresh tokens (7 days)

3. mTLS for Services: Use mutual TLS for service-to-service communication

4. API Keys for Services: Service accounts should use API keys, not user JWT

5. Rate Limiting: Protect against abuse and DoS attacks

6. Audit Everything: Log all authentication and authorization events

7. Never Trust: Validate every request, even from internal services

My Lesson: The $75,000 incident taught me that security isn't optional. Implement it from day one.

---

Next: Part 5: Error Handling and Interceptors in gRPC

Series Navigation: gRPC 101 Series