@korala/auth

HMAC authentication utilities for the Korala document signing API.

Installation

npm install @korala/auth

Usage

Sign API requests

import { signRequest } from '@korala/auth';

const { signature, timestamp } = signRequest({
  method: 'POST',
  path: '/api/v1/documents',
  body: JSON.stringify({ name: 'Contract' }),
  secret: 'your-api-secret',
});

// Use in request headers
fetch('https://api.korala.ai/api/v1/documents', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-id',
    'X-Timestamp': String(timestamp),
    'X-Signature': signature,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Contract' }),
});

Verify webhook signatures

import { verifyWebhookSignature } from '@korala/auth';

const isValid = verifyWebhookSignature({
  payload: rawBody,
  signature: headers['x-signature'],
  timestamp: headers['x-timestamp'],
  secret: webhookSecret,
});

Note: Most users should use @korala/api-client which handles authentication automatically. This package is for advanced use cases or custom HTTP clients.

API

| Function | Description | |----------|-------------| | signRequest(opts) | Generate HMAC signature + timestamp for an API request | | verifySignature(opts) | Verify an incoming API request signature | | signWebhookPayload(payload, secret) | Sign a webhook payload | | verifyWebhookSignature(opts) | Verify a webhook delivery signature | | computeSignature(message, secret) | Low-level HMAC-SHA256 computation | | getTimestamp() | Get current Unix timestamp in seconds | | isTimestampValid(timestamp, maxAge?) | Check if a timestamp is within the allowed window |

Documentation

Full documentation at docs.korala.ai.

License

MIT