Secure Endpoint Client

A TypeScript library providing an encrypted and HMAC-signed HTTP client built on top of Axios. It simplifies secure communication with backend APIs by handling encryption, authentication, CSRF protection, and token management automatically.

Features

• 🔐 End-to-End Encryption: Encrypt request/response payloads using AES encryption
• 🔑 HMAC Authentication: Sign requests with HMAC for message authenticity verification
• 🛡️ CSRF Protection: Built-in Cross-Site Request Forgery token handling
• 🎫 Token Management: Automatic access token injection and refresh
• 📦 Type-Safe: Full TypeScript support with comprehensive type definitions
• ⚡ Lightweight: Minimal dependencies with only essential packages (axios, crypto-js, uuid)
• 🎯 Flexible API: Supports multiple response envelope formats

Installation

npm install secure-endpoint-client

Or with yarn:

yarn add secure-endpoint-client

Quick Start

import { SecureApi } from "secure-endpoint-client";

const api = new SecureApi({
  baseURL: "https://api.example.com",
  getAccessToken: () => localStorage.getItem("accessToken"),
  getHmacSecret: () => localStorage.getItem("hmacSecret"),
  csrfCookieName: "XSRF-TOKEN",
});

// Make a secure API call
const response = await api.get("/user/profile", {
  responseTransformer: (res) => res.data,
});

Configuration

SecureApiOptions

interface SecureApiOptions {
  // Base URL for all requests
  baseURL: string;

  // Function to retrieve the current access token
  getAccessToken?: () => string | null;

  // Function to retrieve the HMAC secret key
  getHmacSecret?: () => string | null;

  // Function to update the HMAC secret (called when server provides new secret)
  setHmacSecret?: (secret: string | null) => void;

  // Routes that should authenticate with the server first
  bootstrapRoutes?: string[];

  // Name of the CSRF cookie to watch for
  csrfCookieName?: string;

  // Request timeout in milliseconds
  timeout?: number;

  // Callback when unauthorized (401) response received
  onUnauthorized?: () => void;
}

Usage Examples

Basic GET Request

const user = await api.get("/users/123");

POST with Encryption

const newUser = await api.post("/users", {
  name: "John Doe",
  email: "[email protected]",
});

Custom Response Transformer

const data = await api.get("/dashboard", {
  responseTransformer: (response) => response.data.payload,
});

Handle Unauthorized Responses

const api = new SecureApi({
  baseURL: "https://api.example.com",
  getAccessToken: () => localStorage.getItem("token"),
  onUnauthorized: () => {
    // Redirect to login or refresh token
    window.location.href = "/login";
  },
});

HMAC Secret Rotation

const api = new SecureApi({
  baseURL: "https://api.example.com",
  getHmacSecret: () => sessionStorage.getItem("hmacSecret"),
  setHmacSecret: (secret) => {
    if (secret) {
      sessionStorage.setItem("hmacSecret", secret);
    } else {
      sessionStorage.removeItem("hmacSecret");
    }
  },
});

API Methods

All methods return a Promise that resolves to the response data:

GET Request

api.get<T>(url: string, options?: AxiosRequestConfig)

POST Request

api.post<T>(url: string, data?: any, options?: AxiosRequestConfig)

PUT Request

api.put<T>(url: string, data?: any, options?: AxiosRequestConfig)

DELETE Request

api.delete<T>(url: string, options?: AxiosRequestConfig)

PATCH Request

api.patch<T>(url: string, data?: any, options?: AxiosRequestConfig)

Request/Response Flow

1. Authentication: Access token is automatically added to request headers
2. HMAC Signing: Request body is signed with HMAC using the shared secret
3. Encryption: Payload is optionally encrypted before sending
4. CSRF Token: CSRF token from cookies is included in request headers
5. Response Handling: Response is decrypted and validated before returning to caller
6. Error Handling: Unauthorized errors trigger the onUnauthorized callback

Security Considerations

• Keep HMAC secrets secure and never expose them in client-side code
• Use HTTPS in production to prevent man-in-the-middle attacks
• Rotate HMAC secrets periodically using the setHmacSecret callback
• Store tokens securely (avoid localStorage for highly sensitive apps)
• The library does not store sensitive data; manage token/secret lifecycle in your application

TypeScript Support

Full TypeScript support is included. The library exports comprehensive type definitions:

import type {
  SecureApiOptions,
  ApiEnvelope,
  ResponseTransformer,
} from "secure-endpoint-client";

Browser Compatibility

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT