Signature

Documentation Index

Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Webhook signature verification
• API request authentication
• Tamper detection

​

Installation

import "github.com/go-mizu/mizu/middlewares/signature"

​

Quick Start

app := mizu.New()

// Verify HMAC-SHA256 signatures
app.Use(signature.New(signature.Options{
    Secret: []byte("your-secret-key"),
    Header: "X-Signature",
}))

​

Configuration

​

Options

​

Examples

​

Basic HMAC Verification

app.Use(signature.New(signature.Options{
    Secret: []byte("webhook-secret"),
    Header: "X-Signature",
}))

​

GitHub Webhook

app.Post("/webhook/github", handler, signature.New(signature.Options{
    Secret:   []byte(os.Getenv("GITHUB_WEBHOOK_SECRET")),
    Header:   "X-Hub-Signature-256",
    Prefix:   "sha256=",
    Algorithm: "sha256",
}))

​

Stripe Webhook

app.Post("/webhook/stripe", handler, signature.New(signature.Options{
    Secret:           []byte(os.Getenv("STRIPE_WEBHOOK_SECRET")),
    Header:           "Stripe-Signature",
    TimestampHeader:  "Stripe-Signature",
    ParseStripeStyle: true,
}))

​

With Timestamp Validation

app.Use(signature.New(signature.Options{
    Secret:             []byte("api-secret"),
    Header:             "X-Signature",
    TimestampHeader:    "X-Timestamp",
    TimestampTolerance: 5 * time.Minute,
}))

​

Per-Client Secrets

app.Use(signature.New(signature.Options{
    Header: "X-Signature",
    GetSecret: func(c *mizu.Ctx) []byte {
        clientID := c.Request().Header.Get("X-Client-ID")
        return getClientSecret(clientID)
    },
}))

​

Custom Signature Format

app.Use(signature.New(signature.Options{
    Secret:    secret,
    Header:    "Authorization",
    Prefix:    "HMAC-SHA256 ",
    Algorithm: "sha256",
    Encoding:  "base64",
}))

​

API Reference

​

Functions

// New creates signature verification middleware
func New(opts Options) mizu.Middleware

// Sign generates signature for data
func Sign(data, secret []byte, algorithm string) string

// Verify checks if signature is valid
func Verify(data, secret []byte, signature, algorithm string) bool

​

Signature Algorithms

​

Creating Signatures (Client Side)

// Go client
func signRequest(body []byte, secret string) string {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    return hex.EncodeToString(mac.Sum(nil))
}

// JavaScript client
async function signRequest(body, secret) {
    const encoder = new TextEncoder();
    const key = await crypto.subtle.importKey(
        'raw', encoder.encode(secret),
        { name: 'HMAC', hash: 'SHA-256' },
        false, ['sign']
    );
    const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(body));
    return Array.from(new Uint8Array(sig))
        .map(b => b.toString(16).padStart(2, '0'))
        .join('');
}

​

Technical Details

​

Implementation Architecture

• Algorithm Support: SHA-1 (legacy), SHA-256 (default), SHA-512
• Encoding Formats: Hexadecimal (default) and Base64
• Signature Verification: Constant-time comparison using hmac.Equal() to prevent timing attacks

​

Core Components

​

Middleware Flow

1. Path & Method Filtering: Checks if request should skip validation based on configured paths and methods
2. Signature Extraction: Retrieves signature from configured header and validates prefix if specified
3. Payload Reading: Uses default body reader or custom PayloadGetter function
4. HMAC Verification: Computes expected signature and performs constant-time comparison
5. Context Storage: Stores verification result in request context for downstream handlers

​

Key Functions

• New(secret): Creates middleware with default options (SHA-256, hex encoding, X-Signature header)
• WithOptions(opts): Creates middleware with custom configuration
• Sign(secret, algo, encoding, payload): Generates HMAC signature for given payload
• GetInfo(c): Retrieves signature verification information from context
• IsValid(c): Quick check if signature was valid

​

Provider-Specific Helpers

• GitHub: X-Hub-Signature-256 header with sha256= prefix
• Stripe: Stripe-Signature header (simplified implementation)
• Slack: Custom payload format combining version, timestamp, and body
• Twilio: SHA-1 with Base64 encoding, URL + sorted form parameters
• AWS: Signature Version 4 (simplified implementation)

​

Security Features

• Constant-Time Comparison: Uses hmac.Equal() to prevent timing attacks
• Body Preservation: Re-wraps request body after reading for downstream handlers
• Configurable Skip Rules: Allows excluding specific paths and HTTP methods
• Custom Error Handling: Supports custom error responses via ErrorHandler

​

Best Practices

• Use SHA-256 or stronger algorithms
• Include timestamp to prevent replay attacks
• Use secure random secrets (32+ bytes)
• Rotate secrets periodically
• Log signature failures for security monitoring

​

Testing

​

Related Middlewares

• keyauth - API key authentication
• jwt - JWT authentication
• hmac - HMAC utilities