api-security

What this skill does

# API Security Skill

> **USE WHEN:** Designing, implementing, or auditing REST, GraphQL, or gRPC APIs for security vulnerabilities.
> **DO NOT USE FOR:** General API design patterns (use rest-api/graphql skills), authentication setup (use jwt/oauth2 skills).

## OWASP API Security Top 10:2023

| Rank | Vulnerability | Description |
|------|---------------|-------------|
| **API1** | Broken Object Level Authorization (BOLA) | IDOR, accessing other users' resources |
| **API2** | Broken Authentication | Weak auth, token flaws |
| **API3** | Broken Object Property Level Authorization | Mass assignment, excessive data exposure |
| **API4** | Unrestricted Resource Consumption | No rate limiting, DoS |
| **API5** | Broken Function Level Authorization | Admin functions exposed |
| **API6** | Unrestricted Access to Sensitive Business Flows | Automated abuse |
| **API7** | Server Side Request Forgery (SSRF) | Internal resource access |
| **API8** | Security Misconfiguration | CORS, headers, verbose errors |
| **API9** | Improper Inventory Management | Shadow APIs, outdated versions |
| **API10** | Unsafe Consumption of APIs | Trusting third-party APIs |

## API1: Broken Object Level Authorization (BOLA)

```typescript
// Bad: No ownership check
app.get('/api/orders/:id', async (req, res) => {
  const order = await Order.findById(req.params.id);
  res.json(order);
});

// Good: Verify ownership
app.get('/api/orders/:id', authenticate, async (req, res) => {
  const order = await Order.findOne({
    _id: req.params.id,
    userId: req.user.id  // Filter by current user
  });

  if (!order) {
    return res.status(404).json({ error: 'Order not found' });
  }

  res.json(order);
});

// Good: Use UUIDs instead of sequential IDs
// Harder to enumerate, though NOT a substitute for auth
GET /api/orders/550e8400-e29b-41d4-a716-446655440000
```

## API3: Broken Object Property Level Authorization

```typescript
// Bad: Mass assignment
app.put('/api/users/:id', async (req, res) => {
  await User.findByIdAndUpdate(req.params.id, req.body);  // Can set isAdmin!
});

// Good: Explicit field whitelist
const updateSchema = z.object({
  name: z.string().optional(),
  email: z.string().email().optional(),
  // isAdmin NOT allowed
});

app.put('/api/users/:id', async (req, res) => {
  const data = updateSchema.parse(req.body);
  await User.findByIdAndUpdate(req.params.id, data);
});

// Bad: Excessive data exposure
app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  res.json(user);  // Includes password hash, internal fields
});

// Good: DTOs with explicit fields
app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  res.json({
    id: user.id,
    name: user.name,
    email: user.email
    // Exclude: passwordHash, internalNotes, etc.
  });
});
```

## API4: Unrestricted Resource Consumption

```typescript
// Good: Rate limiting
import rateLimit from 'express-rate-limit';

// Global rate limit
const globalLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 min
  max: 100,
  standardHeaders: true
});

// Stricter for auth endpoints
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5,
  skipSuccessfulRequests: true
});

app.use('/api/', globalLimiter);
app.use('/api/auth/', authLimiter);

// Good: Pagination limits
const listSchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20)
});

app.get('/api/items', async (req, res) => {
  const { page, limit } = listSchema.parse(req.query);
  const items = await Item.find()
    .skip((page - 1) * limit)
    .limit(limit);
  res.json({ items, page, limit });
});

// Good: Request size limits
app.use(express.json({ limit: '100kb' }));
app.use(express.urlencoded({ limit: '100kb', extended: true }));
```

## API7: Server Side Request Forgery (SSRF)

```typescript
// Bad: Unvalidated URL fetch
app.post('/api/fetch', async (req, res) => {
  const response = await fetch(req.body.url);  // Can access internal services!
  res.json(await response.json());
});

// Good: URL validation and allowlist
const ALLOWED_HOSTS = ['api.example.com', 'cdn.example.com'];

function validateUrl(urlString: string): URL {
  const url = new URL(urlString);

  if (!['http:', 'https:'].includes(url.protocol)) {
    throw new Error('Invalid protocol');
  }

  if (!ALLOWED_HOSTS.includes(url.hostname)) {
    throw new Error('Host not allowed');
  }

  // Block private IPs
  const privateRanges = [
    /^127\./,
    /^10\./,
    /^172\.(1[6-9]|2[0-9]|3[01])\./,
    /^192\.168\./,
    /^169\.254\./,
    /^localhost$/i
  ];

  if (privateRanges.some(r => r.test(url.hostname))) {
    throw new Error('Private addresses not allowed');
  }

  return url;
}
```

## API8: Security Misconfiguration

```typescript
// Good: CORS configuration
import cors from 'cors';

const corsOptions = {
  origin: (origin, callback) => {
    const allowedOrigins = ['https://myapp.com', 'https://admin.myapp.com'];
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  maxAge: 86400  // 24 hours
};

app.use(cors(corsOptions));

// Good: Error handling without leaking info
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error('Error:', err);  // Log full error internally

  if (process.env.NODE_ENV === 'production') {
    res.status(500).json({ error: 'Internal server error' });
  } else {
    res.status(500).json({
      error: err.message,
      stack: err.stack
    });
  }
});

// Good: Remove fingerprinting headers
app.disable('x-powered-by');
```

## GraphQL Security

### Query Depth & Complexity Limiting

```typescript
import { createComplexityLimitRule } from 'graphql-validation-complexity';
import depthLimit from 'graphql-depth-limit';

const server = new ApolloServer({
  schema,
  validationRules: [
    depthLimit(5),  // Max query depth
    createComplexityLimitRule(1000, {  // Max complexity
      onCost: (cost) => console.log('Query cost:', cost),
      createError: (max, actual) =>
        new GraphQLError(`Query too complex: ${actual}. Max: ${max}`)
    })
  ]
});
```

### Disable Introspection in Production

```typescript
import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';

const server = new ApolloServer({
  schema,
  introspection: process.env.NODE_ENV !== 'production',
  plugins: process.env.NODE_ENV === 'production'
    ? [ApolloServerPluginLandingPageDisabled()]
    : []
});
```

### Batching Attack Prevention

```typescript
// Limit batch size
const server = new ApolloServer({
  schema,
  allowBatchedHttpRequests: true,  // Or false to disable
});

// Custom batching limit
app.use('/graphql', (req, res, next) => {
  if (Array.isArray(req.body) && req.body.length > 10) {
    return res.status(400).json({ error: 'Batch size exceeds limit' });
  }
  next();
});
```

### Query Allowlisting (Persisted Queries)

```typescript
import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting';

// In production, only allow pre-registered queries
const server = new ApolloServer({
  schema,
  persistedQueries: {
    cache: new KeyValueCache(),  // Redis recommended
  },
  plugins: [
    {
      async requestDidStart() {
        return {
          async didResolveOperation({ request }) {
            if (process.env.NODE_ENV === 'production' && !request.extensions?.persistedQuery) {
              throw new GraphQLError('Only persisted queries allowed');
            }
          }
        };
      }
    }
  ]
});
```

## JWT Security Best Practices

```typescript
import jwt from 'jsonwebtoke