Request Signature Authentication

XyPriss provides a powerful request signature authentication system that allows you to secure your APIs using cryptographic signatures. This method ensures that only authorized clients can access your API, requests cannot be tampered with in transit, and replay attacks are prevented.

Quick Start

Enable request signature validation globally by providing a shared secret in your security configuration:

typescript

import { createServer } from "xypriss";

const server = createServer({
    security: {
        requestSignature: {
            secret: "your-super-secret-api-key-12345",
            debug: true, // Enable debug logging in development
        },
    },
});

Client Implementation

Clients must include a cryptographic signature in the XP-Request-Sig header and a timestamp in the X-Timestamp header. The signature is an HMAC-SHA256 hash of the request method, URL, body, and timestamp.

Prepare Data String

Concatenate the components: METHOD + URL + BODY + TIMESTAMP.

Compute HMAC

Generate an HMAC-SHA256 hash of the string using your shared secret.

Send Request

Include the signature and timestamp in the request headers.

XSec-M Client Example

import { Hash } from "xypriss-security";

const signRequest = (
  url: string,
  method: string,
  secret: string,
  body = "",
  timestamp = Date.now(),
) => ({
  signature: Hash.hmac(
    secret,
    `${method.toUpperCase()}${url}${body}${timestamp}`,
    "sha256",
  ),
  timestamp,
});

const { signature, timestamp } = signRequest(
  "/api/data",
  "POST",
  "my-secret",
  '{"key":"val"}',
);

console.log("Signature:", signature);
console.log("Timestamp:", timestamp);

Configuration Options

Customize the validation behavior to fit your security requirements:

typescript

requestSignature: {
    secret: "my-secret-key",
    algorithm: "sha512", // sha256 or sha512
    maxAge: 300000, // 5 minutes validity
    clockSkew: 30000, // 30 seconds tolerance
    headerName: "X-API-Signature", // Custom header
    timestampHeaderName: "X-API-Timestamp",
    includeBody: true,
    includeQuery: true,
}

Advanced Route Filtering

Apply signatures only to specific routes or exclude public endpoints:

typescript

security: {
    routeConfig: {
        requestSignature: {
            includeRoutes: ["/api/webhooks/*", "/api/admin/*"],
            excludeRoutes: ["/api/public/*"],
        },
    },
}

Security Best Practices

Strong Secrets

Always use cryptographically secure random strings for your shared secrets. Never use weak passwords.

Use HTTPS

Signatures prevent tampering but not interception. Always use HTTPS in production to encrypt the headers.

Clock Synchronization

Ensure your server and client clocks are synchronized. Requests will fail with a "Signature expired" error if the time difference exceeds maxAge + clockSkew.

Route Security

Implement fine-grained access control using IP whitelists and blacklists.