apiVersion: capsule.dev/v0.1
kind: Capsule
name: scnmnt-security-middleware
version: 0.1.0
type: adapter
purpose:
summary: 'Provides a set of reusable security middleware for an Echo HTTP server,
including secure headers, body limits, source origin validation, and CSRF protection.
It ensures that API endpoints are protected against common web vulnerabilities.
'
owns:
- HTTP security header configuration (X-Frame-Options, CSP, etc.)
- Request body size limiting
- Source origin validation to prevent cross-site requests
- CSRF token generation, cookie management, and validation
does_not_own:
- User authentication (beyond CSRF token validation)
- Specific API business logic
- Application configuration outside of security settings
interfaces:
provides:
- kind: library
name: security.Middleware
description: Echo middleware for various security features.
- kind: http_api
name: /api/session
description: Endpoint to retrieve a CSRF token for client-side use.
requires:
- kind: env
name: SECURITY_SECURE_COOKIES
description: Boolean flag to determine if CSRF cookies should be marked as secure.
agent:
summary_for_ai: 'An agent working on this capsule would focus on implementing and
testing HTTP security best practices. They should be familiar with web security
concepts like CSRF, XSS, and origin policies, and how to apply them as middleware.
'
avoid:
- Implementing any business logic unrelated to security
- Direct database access
verification:
invariants:
- CSRF tokens must be unique, securely generated, and correctly validated.
- Cross-site requests (except safe methods) must be rejected.
- Secure headers must be consistently applied to all responses.
x-reuse:
notes: 'The `csrfCookieName` (`_scenemint_csrf`), `csrfTokenBytes`, and `maxBodyBytes`
constants are hardcoded. Error messages returned by the middleware are hardcoded
in Chinese and would need localization or generalization. The capsule is tightly
coupled with the Echo HTTP framework.
'
x-reconstruct:
install: install.json