External API

/**
 * MAPD External API — Signing Client (distributable)
 * ==================================================
 *
 * A single, self-contained JavaScript module that signs requests to the MAPD
 * External API (`/api/external/v1/*`) using the HMAC-SHA256 scheme the API
 * expects. Copy this file into your own server-side project and use it as-is —
 * it has no dependencies beyond Node.js built-in modules and runs on Node >= 18.
 *
 * ────────────────────────────────────────────────────────────────────────────
 *  SERVER-SIDE ONLY — NEVER EXPOSE YOUR SECRET IN A BROWSER
 * ────────────────────────────────────────────────────────────────────────────
 * Your API secret (`mdsk_v1_*`) is a bearer credential. Anyone who obtains it
 * can impersonate your integration. Sign requests exclusively in a trusted
 * server-side environment. Do NOT bundle this file into browser/front-end code,
 * embed the secret in a mobile app, or commit it to source control.
 *
 * How the signature works (must match the server verifier exactly):
 *   Each request carries four headers:
 *     x-md-key        Your public key         (mdpk_v1_<24 hex chars>)
 *     x-md-timestamp  Unix epoch SECONDS      (integer string)
 *     x-md-nonce      Single-use hex nonce    (>= 16 lowercase hex chars)
 *     x-md-signature  HMAC-SHA256 hex digest  (64 lowercase hex chars)
 *
 *   Signing key = SHA-256(apiSecret) interpreted as raw bytes:
 *     signingKey = Buffer.from(sha256_hex(apiSecret), 'hex')
 *
 *   Canonical string (UTF-8, fields joined with a single '\n'):
 *     1. UPPERCASE HTTP method            e.g. "POST"
 *     2. path + query, exactly as sent    e.g. "/api/external/v1/shows/demo?page=2"
 *     3. timestamp                        the x-md-timestamp value
 *     4. nonce                            the x-md-nonce value
 *     5. body hash                        lowercase hex SHA-256 of the raw body bytes
 *                                         (SHA-256 of the empty string when there is no body)
 *
 *   signature = HMAC-SHA256(signingKey, canonicalString) as lowercase hex.
 *
 *   The server rejects requests whose timestamp is more than 5 minutes from its
 *   clock, and rejects a nonce it has seen before — so generate a fresh nonce
 *   per request (the default) and keep your clock in sync (e.g. NTP).
 *
 * @example
 *   import { createMapdApiClient } from "./mapd-api-client.js"
 *
 *   const client = createMapdApiClient({
 *     apiKey: process.env.MAPD_API_KEY,      // mdpk_v1_...  (public key)
 *     apiSecret: process.env.MAPD_API_SECRET, // mdsk_v1_...  (keep server-side!)
 *     baseUrl: "https://your-mapd-host.example.com",
 *   })
 *
 *   // GET (no body)
 *   const res = await client.request("/api/external/v1/shows/my-show/attendees?page=1")
 *   const attendees = await res.json()
 *
 *   // POST (JSON body) — set content-type yourself; the body is signed verbatim
 *   const created = await client.request("/api/external/v1/shows/my-show/attendees", {
 *     method: "POST",
 *     headers: { "content-type": "application/json" },
 *     body: JSON.stringify({ firstName: "Ada", lastName: "Lovelace" }),
 *   })
 *
 * @module mapd-api-client
 */

import { createHash, createHmac, randomBytes } from "node:crypto"

/** HTTP header carrying the public API key. */
export const HEADER_API_KEY = "x-md-key"
/** HTTP header carrying the Unix epoch-seconds timestamp. */
export const HEADER_TIMESTAMP = "x-md-timestamp"
/** HTTP header carrying the single-use request nonce. */
export const HEADER_NONCE = "x-md-nonce"
/** HTTP header carrying the HMAC-SHA256 signature. */
export const HEADER_SIGNATURE = "x-md-signature"

const DEFAULT_NONCE_LENGTH_BYTES = 16

/**
 * @typedef {Object} MapdApiClientConfig
 * @property {string} apiKey    Public key, `mdpk_v1_<24 hex chars>`.
 * @property {string} apiSecret Secret key, `mdsk_v1_*`. SERVER-SIDE ONLY.
 * @property {string} baseUrl   Absolute base URL of the MAPD host, e.g.
 *                              `https://your-mapd-host.example.com`.
 * @property {typeof fetch} [fetchImpl]     Custom fetch (defaults to global `fetch`).
 * @property {() => string} [nonceFactory]  Custom nonce generator (defaults to
 *                                          16 random bytes as hex). Must return a
 *                                          fresh lowercase hex string per request.
 * @property {() => number} [nowFactory]    Custom clock in ms (defaults to `Date.now`).
 */

/** @returns {string} lowercase hex SHA-256 of the given secret. */
function sha256Hex(value) {
  return createHash("sha256").update(value, "utf8").digest("hex")
}

/** @returns {string} lowercase hex SHA-256 of the raw request body bytes. */
function hashBodyBytes(bodyBytes) {
  return createHash("sha256").update(bodyBytes).digest("hex")
}

/** @returns {string} a fresh single-use nonce (16 random bytes as hex). */
function defaultNonceFactory() {
  return randomBytes(DEFAULT_NONCE_LENGTH_BYTES).toString("hex")
}

/**
 * Build the canonical string that is signed. Fields are joined with a single
 * newline in this exact order: method, path+query, timestamp, nonce, body hash.
 *
 * @param {string} method       HTTP method (case-insensitive; upcased here).
 * @param {string} pathWithQuery Path plus query string, exactly as sent.
 * @param {string} timestamp    Unix epoch-seconds string.
 * @param {string} nonce        Single-use nonce.
 * @param {string} bodyHash     Lowercase hex SHA-256 of the raw body bytes.
 * @returns {string}
 */
function buildCanonicalString(method, pathWithQuery, timestamp, nonce, bodyHash) {
  return [method.toUpperCase(), pathWithQuery, timestamp, nonce, bodyHash].join("\n")
}

function sanitizePath(path) {
  return path.startsWith("/") ? path : `/${path}`
}

/**
 * Create a signing client bound to a single API key pair and host.
 *
 * @param {MapdApiClientConfig} config
 * @returns {{ request: (path: string, init?: RequestInit) => Promise<Response> }}
 */
export function createMapdApiClient(config) {
  if (!config || !config.apiKey || !config.apiSecret || !config.baseUrl) {
    throw new Error("createMapdApiClient requires apiKey, apiSecret, and baseUrl")
  }

  const fetchImpl = config.fetchImpl ?? fetch
  const nowFactory = config.nowFactory ?? Date.now
  const nonceFactory = config.nonceFactory ?? defaultNonceFactory
  const baseUrl = new URL(config.baseUrl)
  const apiKey = config.apiKey
  // Signing key = the raw bytes of SHA-256(secret), NOT the secret itself.
  const signingKey = Buffer.from(sha256Hex(config.apiSecret), "hex")

  /**
   * Sign and send a request. `path` may be absolute (`/api/...`) or relative;
   * it is resolved against `baseUrl`. The body (if any) is signed verbatim, so
   * pass a fully-serialized body and set `content-type` yourself.
   *
   * @param {string} path
   * @param {RequestInit} [init]
   * @returns {Promise<Response>}
   */
  async function request(path, init) {
    const targetUrl = new URL(sanitizePath(path), baseUrl)
    const unsignedRequest = new Request(targetUrl, init)
    const bodyBytes = Buffer.from(await unsignedRequest.clone().arrayBuffer())

    const nonce = nonceFactory()
    const timestamp = String(Math.floor(nowFactory() / 1000))
    const bodyHash = hashBodyBytes(bodyBytes)
    const pathWithQuery = targetUrl.pathname + targetUrl.search
    const canonical = buildCanonicalString(
      unsignedRequest.method,
      pathWithQuery,
      timestamp,
      nonce,
      bodyHash,
    )
    const signature = createHmac("sha256", signingKey).update(canonical, "utf8").digest("hex")

    const headers = new Headers(unsignedRequest.headers)
    headers.set(HEADER_API_KEY, apiKey)
    headers.set(HEADER_TIMESTAMP, timestamp)
    headers.set(HEADER_NONCE, nonce)
    headers.set(HEADER_SIGNATURE, signature)

    const signedRequest = new Request(unsignedRequest, { headers })
    return fetchImpl(signedRequest)
  }

  return { request }
}