@mantleframework/security

Security headers middleware and webhook signature validation for Lambda handlers.

securityHeaders(options?)

Middy middleware that adds security headers to all API Gateway responses. Runs in the after phase for successful responses and in the onError phase for error responses. Headers set by the handler take precedence over defaults.

import { securityHeaders } from '@mantleframework/security'

// Used internally by Mantle's handler pipeline
const middleware = securityHeaders({
  csp: "default-src 'self'",
  frameOptions: 'SAMEORIGIN',
})

Default Headers

Header	Default Value
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
X-XSS-Protection	1; mode=block
Strict-Transport-Security	max-age=31536000; includeSubDomains
Cache-Control	no-store

SecurityHeadersOptions

interface SecurityHeadersOptions {
  frameOptions?: string                   // Override X-Frame-Options (default: 'DENY')
  csp?: string                            // Set Content-Security-Policy header
  customHeaders?: Record<string, string>  // Custom headers to merge (can override defaults)
}

Webhook Signature Validation

Timing-safe HMAC signature validation for webhook payloads. All functions throw UnauthorizedError from @mantleframework/errors on failure.

validateWebhookSignature(options)

Generic HMAC webhook signature validation with configurable algorithm and prefix.

import { validateWebhookSignature } from '@mantleframework/security'

validateWebhookSignature({
  payload: rawBody,
  signature: signatureHeader,
  secret: webhookSecret,
  algorithm: 'sha256',
  prefix: 'sha256=',
  headerName: 'X-Signature',
})

WebhookValidationOptions

interface WebhookValidationOptions {
  payload: string | Buffer    // Raw request body
  signature: string           // Signature header value
  secret: string              // HMAC secret
  algorithm?: string          // HMAC algorithm (default: 'sha256')
  prefix?: string             // Prefix stripped before comparison (default: '')
  headerName?: string         // Header name for error messages (default: 'X-Signature')
}

validateGitHubWebhook(payload, signatureHeader, secret)

Validate a GitHub webhook signature (X-Hub-Signature-256). GitHub signs payloads using HMAC-SHA256 with a sha256= prefix.

import { validateGitHubWebhook } from '@mantleframework/security'

validateGitHubWebhook(rawBody, headers['x-hub-signature-256'], secret)

validateStripeWebhook(payload, signatureHeader, secret, toleranceSeconds?)

Validate a Stripe webhook signature (Stripe-Signature). Parses the t=<timestamp>,v1=<hex> header format and includes replay protection via timestamp age validation.

import { validateStripeWebhook } from '@mantleframework/security'

validateStripeWebhook(rawBody, headers['stripe-signature'], endpointSecret)

// Custom tolerance (default: 300 seconds)
validateStripeWebhook(rawBody, headers['stripe-signature'], endpointSecret, 600)

Parameters:

Parameter	Type	Default	Description
payload	string | Buffer	-	Raw request body
signatureHeader	string	-	Value of the Stripe-Signature header
secret	string	-	Stripe webhook endpoint secret
toleranceSeconds	number	300	Maximum age of the timestamp in seconds