security

Files (1)

• SKILL.md

SKILL.md (first lines)

# Security Guidelines

## CRITICAL PRINCIPLES

1. **Validate at the edge**, JSON Schema validation on all API endpoints
2. **Sanitize HTML fields**, validate other input without rewriting it as HTML
3. **Verify webhook signatures**, always verify Stripe, Slack, Terra webhooks
4. **Use secure ObjectId conversion**, always use
   `ObjectId.createFromHexString()` with try/catch
5. **Fail securely**, never expose internal errors to clients, log details,
   return generic messages
6. **Least privilege**, use RBAC permissions to restrict protected routes
7. **Secrets in env only**, all secrets MUST be validated at startup

## Example Patterns (Fastify + JSON Schema + MongoDB)

### API Validation

```javascript
// Good: Fastify route with schema validation
fastify.post('/api/users', {
  schema: {
    body: {
      type: 'object',
      required: ['email', 'password'],
      properties: {
        email: { type: 'string', format: 'email' },
        password: { type: 'string', minLength: 8 }
      }
    }
  },
  handler: async (request, reply) => {
    // Data is already validated
    const { email, password } = request.body
  }
})

// Bad: No validation
fastify.post('/api/users', async (request, reply) => {
  const { email, password } = request.body // Unsafe!
})
```

### Security Headers

**Use @fastify/helmet for security headers:**

```javascript
import helmet from '@fastify/helmet'
// Fastify with @fastify/helmet
fastify.register(helmet, {
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      connectSrc: ["'self'", 'https://api.example.com']
    }
  }
})
```

### Safe MongoDB ObjectId Conversion

Catch ObjectId conversion failures separately from database failures. Let
operational errors reach the application's logging and server-error handler.

```javascript
// Good: Safe ObjectId conversion
let objectId
try {
  objectId = ObjectId.createFromHexString(id)
} catch (err) {
  return reply.code(400).send({ error: 'Invalid ID format' })
}
const doc = await mongo.collection('files').findOne({ _id: objectId })

// Bad: Unsafe conversion (can crash server)
const uncheckedObjectId = ObjectId.createFromHexString(untrustedId)
```

### Webhook Signature Verification

**Always verify webhook signatures for Stripe, Slack, Terra:**

```javascript
import config from '../../config.js'

// Good: Verify Stripe webhook signature
function verifyWebhook(req, secret, stripe, fastify) {
  if (!req.rawBody) {
    throw new fastify.httpErrors.badRequest('No body supplied')
  }
  try {
    const signature = req.headers['stripe-signature']
    return stripe.webhooks.constructEvent(req.rawBody, signature, secret)
  } catch (err) {
    req.log.error('Webhook signature verification failed', err.message)
    throw new fastify.httpErrors.unauthorized('Invalid signature')
  }
}

// Use in route
fastify.post('/stripe/webhook', async (req, reply) => {
  const event = fastify.stripe.verifyWebhook(
    req,
    config.STRIPE_EVENTS_SIGNING_SECRET,
    fastify.stripe.api,
    fastify
  )
  // Process verified event
})
```

## Authentication & Authorization

Register `@fastify/jwt` and use `await request.jwtVerify()` in an async
authentication hook, or return its promise. Verification must finish
successfully before the protected handler runs; rejection must stop the
request. Registration alone does not protect routes. Follow the
[JWT verification examples](https://github.com/fastify/fastify-jwt#usage).

From ioncache/ioncache-ai-tools, MIT.

More from ioncache/ioncache-ai-tools