가맹점 API 명세

const user = await coinpg.createOrGetUser('user-1001', '홍길동');
console.log(user.external_user_id, user.deposit_address);

const user = await coinpg.getUser('user-1001');
console.log(user.deposit_address, user.deposited);

const balance = await coinpg.getBalance();
console.log(balance.available);

let cursor;
do {
  const page = await coinpg.listTransactions({ userId: 'user-1001', limit: 50, cursor });
  const deposits = page.transactions.filter(tx => tx.type === 'deposit' && tx.status === 'confirmed');
  console.log(deposits); // 조회만 수행. 장부 반영은 거래 id로 중복 방지.
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

// savedOrder: 호출 전에 가맹점 DB에 저장한 주문·요청 본문·멱등 키
// savePayoutId: 가맹점에서 구현하는 DB 저장 함수
const payout = await coinpg.requestPayout(savedOrder.body, savedOrder.idempotencyKey);
await savePayoutId(savedOrder.id, payout.id);

// savedOrder: 지급 ID 저장 후 가맹점 DB에서 다시 읽은 주문
const payout = await coinpg.getPayout(savedOrder.payoutId);
console.log(payout.status); // confirmed 또는 failed일 때만 주문 종료

const result = await coinpg.request('/webhook');
console.log(result.webhook);

const result = await coinpg.request('/webhook', { method: 'DELETE' });
console.log(result.changed);

// Node.js >= 22.18.0. See docs/WEBHOOK_SIGNATURE_VERIFICATION.md.
// This receiver durably queues notifications; it does not credit balances.
import { createHmac, timingSafeEqual } from "node:crypto";
import { mkdirSync } from "node:fs";
import { createServer } from "node:http";
import { dirname, resolve } from "node:path";
import { DatabaseSync } from "node:sqlite";
import { pathToFileURL } from "node:url";

const MAX_BODY_BYTES = 64 * 1024;
const EVENT_TYPES = new Set(["deposit.confirmed", "payout.confirmed", "payout.failed"]);

class RequestError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

export function parseSigningKeys(json) {
  const source = JSON.parse(json);
  if (!source || typeof source !== "object" || Array.isArray(source)) {
    throw new Error("WEBHOOK_KEYS_JSON must be an object.");
  }
  const keys = new Map();
  for (const [id, entry] of Object.entries(source)) {
    if (!/^whk_[1-9][0-9]*$/u.test(id) || !entry || typeof entry !== "object" || Array.isArray(entry) ||
        typeof entry.secret !== "string" || !/^[A-Za-z0-9_-]{43}$/u.test(entry.secret) ||
        (entry.valid_until !== undefined && typeof entry.valid_until !== "string")) {
      throw new Error("Invalid webhook key configuration.");
    }
    const bytes = Buffer.from(entry.secret, "base64url");
    const validUntilMs = entry.valid_until === undefined ? Infinity : Date.parse(entry.valid_until);
    if (bytes.length !== 32 || bytes.toString("base64url") !== entry.secret ||
        Number.isNaN(validUntilMs)) {
      throw new Error("Invalid webhook secret or valid_until.");
    }
    keys.set(id, { bytes, validUntilMs });
  }
  if (keys.size === 0) throw new Error("At least one webhook signing key is required.");
  return keys;
}

export function verifyWebhook(rawBody, headers, keys, nowMs = Date.now()) {
  const eventId = headers["x-coinpg-event-id"];
  const eventType = headers["x-coinpg-event-type"];
  const timestamp = headers["x-coinpg-timestamp"];
  const keyId = headers["x-coinpg-key-id"];
  const signature = headers["x-coinpg-signature"];
  if (typeof eventId !== "string" || !eventId || eventId.length > 512 ||
      typeof eventType !== "string" || !EVENT_TYPES.has(eventType) ||
      typeof timestamp !== "string" || !/^[0-9]{1,13}$/u.test(timestamp) ||
      typeof keyId !== "string" || typeof signature !== "string" ||
      !/^v1=[A-Za-z0-9_-]{43}$/u.test(signature)) {
    throw new RequestError(401, "Invalid webhook headers.");
  }
  const key = keys.get(keyId);
  if (!key || key.validUntilMs < nowMs ||
      Math.abs(Math.floor(nowMs / 1000) - Number(timestamp)) > 300) {
    throw new RequestError(401, "Unknown/expired key or timestamp outside tolerance.");
  }
  const expected = createHmac("sha256", key.bytes)
    .update(`${timestamp}.${eventId}.`, "utf8")
    .update(rawBody)
    .digest();
  const actual = Buffer.from(signature.slice(3), "base64url");
  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
    throw new RequestError(401, "Invalid webhook signature.");
  }
  let event;
  try {
    event = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(rawBody));
  } catch {
    throw new RequestError(400, "Invalid JSON body.");
  }
  if (!event || typeof event !== "object" || Array.isArray(event) ||
      event.id !== eventId || event.type !== eventType ||
      typeof event.created_at !== "string" || !Number.isFinite(Date.parse(event.created_at)) ||
      !event.data || typeof event.data !== "object" || Array.isArray(event.data)) {
    throw new RequestError(400, "Invalid event envelope.");
  }
  return event;
}

export function createWebhookReceiver({ keys, databasePath }) {
  mkdirSync(dirname(databasePath), { recursive: true });
  const db = new DatabaseSync(databasePath);
  db.exec(`
    PRAGMA journal_mode = WAL;
    PRAGMA synchronous = FULL;
    PRAGMA busy_timeout = 1000;
    CREATE TABLE IF NOT EXISTS coinpg_webhook_inbox (
      event_id TEXT PRIMARY KEY,
      event_type TEXT NOT NULL,
      raw_body BLOB NOT NULL,
      received_at TEXT NOT NULL,
      processed_at TEXT
    );
  `);
  const insert = db.prepare(`
    INSERT INTO coinpg_webhook_inbox (event_id, event_type, raw_body, received_at)
    VALUES (?, ?, ?, ?) ON CONFLICT(event_id) DO NOTHING
  `);
  const respond = (res, status, body) => {
    if (res.writableEnded || res.destroyed) return;
    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
    res.end(JSON.stringify(body));
  };
  const server = createServer((req, res) => {
    if (req.url === "/healthz" && req.method === "GET") {
      respond(res, 200, { ok: true });
      return;
    }
    if (req.url !== "/webhooks/coinpg") {
      respond(res, 404, { error: "Not found." });
      req.resume();
      return;
    }
    if (req.method !== "POST") {
      res.setHeader("allow", "POST");
      respond(res, 405, { error: "Use POST." });
      req.resume();
      return;
    }
    if (req.headers["content-type"]?.split(";", 1)[0].trim() !== "application/json") {
      respond(res, 415, { error: "Content-Type: application/json is required." });
      req.resume();
      return;
    }
    const chunks = [];
    let size = 0;
    let rejected = false;
    req.on("data", (chunk) => {
      if (rejected) return;
      size += chunk.length;
      if (size > MAX_BODY_BYTES) {
        rejected = true;
        chunks.length = 0;
        respond(res, 413, { error: "Body exceeds 64 KiB." });
        return;
      }
      chunks.push(chunk);
    });
    req.on("error", () => respond(res, 400, { error: "Request interrupted." }));
    req.on("end", () => {
      if (rejected) return;
      try {
        const rawBody = Buffer.concat(chunks);
        const event = verifyWebhook(rawBody, req.headers, keys);
        // SQLite commits this single INSERT before replying. A worker must later
        // process pending inbox rows; HTTP retries are not that worker.
        const result = insert.run(event.id, event.type, rawBody, new Date().toISOString());
        respond(res, 200, { received: true, duplicate: Number(result.changes) === 0 });
      } catch (error) {
        respond(res, error instanceof RequestError ? error.status : 503, {
          error: error instanceof RequestError ? error.message : "Inbox unavailable; retry later.",
        });
      }
    });
  });
  server.requestTimeout = 10_000;
  server.headersTimeout = 10_000;
  server.on("close", () => db.close());
  return server;
}

if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
  const keys = parseSigningKeys(process.env.WEBHOOK_KEYS_JSON ?? "{}");
  const port = Number(process.env.PORT ?? 4000);
  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("Invalid PORT.");
  const server = createWebhookReceiver({
    keys,
    databasePath: resolve(process.env.WEBHOOK_INBOX_PATH ?? ".coinpg/merchant-webhook-inbox.sqlite"),
  });
  server.listen(port, "127.0.0.1", () => {
    console.log(`Webhook receiver: http://127.0.0.1:${port}/webhooks/coinpg`);
  });
  const stop = () => server.close();
  process.once("SIGINT", stop);
  process.once("SIGTERM", stop);
}

export WEBHOOK_KEYS_JSON='{"whk_1":{"secret":"<발급받은 signing_secret>"}}'
export WEBHOOK_INBOX_PATH='./.coinpg/merchant-webhook-inbox.sqlite'
PORT=4000 node merchant-webhook-server.mjs