Безопасность интеграций: ключи, подписи, минимальные права

mkdir integration-security && cd integration-security
npm init -y && npm pkg set type=module
npm install zod@4.6.6

// Incoming event from a partner: size -> signature -> freshness -> schema -> duplicates.
// The signature is HMAC-SHA256 over "<timestamp>.<raw body>" with a shared secret.
import { createHmac, timingSafeEqual } from "node:crypto";
import * as z from "zod";

const MAX_BODY_BYTES = 64 * 1024;
const TOLERANCE_SECONDS = 300;

const OrderPaid = z.strictObject({
  id: z.string().regex(/^evt_[A-Za-z0-9]{8,32}$/),
  type: z.literal("order.paid"),
  data: z.strictObject({
    orderId: z.string().regex(/^[0-9]{1,12}$/),
    amount: z.number().int().positive().max(100_000_000),
    currency: z.enum(["KZT", "USD"]),
  }),
});

export class RejectedEvent extends Error {
  name = "RejectedEvent";
  constructor(status, reason) {
    super(reason);
    this.status = status;
  }
}

export function sign(secret, timestamp, rawBody) {
  return createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
}

function signatureMatches(secret, timestamp, rawBody, received) {
  const expected = Buffer.from(sign(secret, timestamp, rawBody), "hex");
  const got = Buffer.from(received, "hex");
  return got.length === expected.length && timingSafeEqual(got, expected);
}

const seen = new Set(); // in production: a table with a unique key on the event id

// secrets: [current, previous] — both are accepted while a key is being rotated
export function acceptPartnerEvent(rawBody, headers, secrets, now = Date.now()) {
  if (rawBody.length > MAX_BODY_BYTES) throw new RejectedEvent(413, "body too large");

  const timestamp = headers["x-partner-timestamp"] ?? "";
  const signature = headers["x-partner-signature"] ?? "";
  if (!/^\d{10}$/.test(timestamp) || !/^[0-9a-f]{64}$/.test(signature)) {
    throw new RejectedEvent(401, "missing or malformed signature headers");
  }
  if (!secrets.filter(Boolean).some((s) => signatureMatches(s, timestamp, rawBody, signature))) {
    throw new RejectedEvent(401, "bad signature");
  }
  if (Math.abs(now / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
    throw new RejectedEvent(401, "stale timestamp");
  }

  let json;
  try {
    json = JSON.parse(rawBody.toString("utf8"));
  } catch {
    throw new RejectedEvent(400, "invalid JSON");
  }
  const parsed = OrderPaid.safeParse(json);
  if (!parsed.success) {
    throw new RejectedEvent(422, parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "));
  }

  if (seen.has(parsed.data.id)) return { duplicate: true, event: parsed.data };
  seen.add(parsed.data.id);
  return { duplicate: false, event: parsed.data };
}

$ node --test partner-event.test.mjs
  first: false { orderId: '1042', amount: 15000, currency: 'KZT' } | repeat: true
  after rotation: 401 bad signature
  401 bad signature
  401 missing or malformed signature headers
  401 stale timestamp
  422 data: Unrecognized key: "isAdmin"
  422 data.orderId: Invalid string: must match pattern /^[0-9]{1,12}$/; data.amount: Too small: expected number to be >0; data.currency: Invalid option: expected one of "KZT"|"USD"
  413 body too large
✔ valid event is accepted once, the repeat is marked as duplicate (2.769ms)
✔ an event signed with the previous key passes during rotation (0.452ms)
✔ tampering, stale timestamps, junk and oversized bodies are rejected (0.8696ms)
ℹ tests 3
ℹ pass 3
ℹ fail 0

// Outgoing request to a URL supplied by a user (avatar import, customer webhook URL).
// SSRF defences from the OWASP cheat sheet: scheme allowlist, IP check after DNS,
// connection only to the checked address, no redirects, timeout and size limit.
import { lookup as dnsLookup } from "node:dns";
import { request } from "node:https";
import { BlockList, isIP } from "node:net";

const denied = new BlockList();
for (const [net, prefix] of [
  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
  ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16],
  ["198.18.0.0", 15], ["224.0.0.0", 4], ["240.0.0.0", 4],
]) denied.addSubnet(net, prefix, "ipv4");
for (const [net, prefix] of [
  ["::", 128], ["::1", 128], ["64:ff9b::", 96], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8],
]) denied.addSubnet(net, prefix, "ipv6");

export function isPublicAddress(ip) {
  const family = isIP(ip);
  if (family === 0) return false;
  // BlockList also matches IPv4-mapped IPv6 (::ffff:127.0.0.1) against IPv4 rules
  return !denied.check(ip, family === 4 ? "ipv4" : "ipv6");
}

export class BlockedUrlError extends Error {
  name = "BlockedUrlError";
}

// Every address the name resolves to must be allowed; the socket then connects
// to exactly these addresses, so there is no second, unchecked DNS lookup.
function guardedLookup(isAllowed) {
  return (hostname, options, callback) => {
    dnsLookup(hostname, { all: true }, (err, addresses) => {
      if (err) return callback(err);
      const bad = addresses.find((a) => !isAllowed(a.address));
      if (bad) return callback(new BlockedUrlError(`${hostname} resolves to a blocked address ${bad.address}`));
      if (options.all) return callback(null, addresses);
      callback(null, addresses[0].address, addresses[0].family);
    });
  };
}

export function safeGet(input, { timeoutMs = 5000, maxBytes = 1_000_000, isAllowed = isPublicAddress, ports = ["", "443"] } = {}) {
  let url;
  try {
    url = new URL(input);
  } catch {
    return Promise.reject(new BlockedUrlError("invalid URL"));
  }
  if (url.protocol !== "https:") return Promise.reject(new BlockedUrlError(`scheme ${url.protocol} is not allowed`));
  if (url.username || url.password) return Promise.reject(new BlockedUrlError("credentials in URL are not allowed"));
  if (!ports.includes(url.port)) return Promise.reject(new BlockedUrlError(`port ${url.port} is not allowed`));
  const host = url.hostname.replace(/^\[|\]$/g, "");
  // An IP literal skips DNS, so it is checked here
  if (isIP(host) && !isAllowed(host)) return Promise.reject(new BlockedUrlError(`address ${host} is blocked`));

  return new Promise((resolve, reject) => {
    const req = request(url, {
      method: "GET",
      lookup: guardedLookup(isAllowed),
      signal: AbortSignal.timeout(timeoutMs),
      headers: { "user-agent": "interlab-fetcher/1.0" },
    }, (res) => {
      // node:https does not follow redirects; we do not follow them either
      if (res.statusCode >= 300 && res.statusCode < 400) {
        res.resume();
        return reject(new BlockedUrlError(`redirect to ${res.headers.location} was not followed`));
      }
      const chunks = [];
      let size = 0;
      res.on("data", (chunk) => {
        size += chunk.length;
        if (size > maxBytes) {
          req.destroy(new BlockedUrlError(`response is larger than ${maxBytes} bytes`));
          return;
        }
        chunks.push(chunk);
      });
      res.on("end", () => resolve({ status: res.statusCode, type: res.headers["content-type"], body: Buffer.concat(chunks) }));
      res.on("error", reject);
    });
    req.on("error", reject);
    req.end();
  });
}

$ node --test safe-fetch.test.mjs
  http://example.com/ -> scheme http: is not allowed
  file:///etc/passwd -> scheme file: is not allowed
  https://user:pass@example.com/ -> credentials in URL are not allowed
  https://example.com:8443/ -> port 8443 is not allowed
  https://169.254.169.254/latest/meta-data/ -> address 169.254.169.254 is blocked
  https://0x7f000001/ -> address 127.0.0.1 is blocked
  https://2130706433/admin -> address 127.0.0.1 is blocked
  https://[::ffff:127.0.0.1]/ -> address ::ffff:7f00:1 is blocked
✔ isPublicAddress: private, loopback, link-local and mapped addresses are blocked (5.2406ms)
  https://localhost/ -> localhost resolves to a blocked address ::1
✔ dangerous URLs are rejected before any connection (10.0721ms)
  https://example.com/ -> 200 text/html; charset=utf-8, 577 bytes
✔ a public HTTPS address works (42.96ms)
  /redirect -> BlockedUrlError: redirect to http://169.254.169.254/latest/meta-data/ was not followed
  /big -> BlockedUrlError: response is larger than 1000000 bytes
  /slow -> AbortError: The operation was aborted
✔ redirects are not followed, size and time are limited (529.0931ms)
ℹ tests 4
ℹ pass 4
ℹ fail 0

// Integration log: JSON lines, secrets removed, personal data masked.
const SECRET_KEYS = /authorization|cookie|token|secret|password|api[-_]?key|signature/i;

// Query strings often carry keys (?api_key=…): keep only the origin and path
function stripQuery(value) {
  const url = new URL(value);
  return url.search ? `${url.origin}${url.pathname}?[REDACTED]` : value;
}

function maskEmail(value) {
  const [user, domain] = value.split("@");
  return `${user.slice(0, 1)}***@${domain}`;
}

function maskPhone(value) {
  const digits = value.replace(/\D/g, "");
  return `***${digits.slice(-2)}`;
}

export function redact(value, key = "") {
  if (SECRET_KEYS.test(key)) return "[REDACTED]";
  if (Array.isArray(value)) return value.map((v) => redact(v));
  if (value && typeof value === "object") {
    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redact(v, k)]));
  }
  if (typeof value === "string" && /^https?:\/\//.test(value)) return stripQuery(value);
  if (typeof value === "string" && /^[^@\s]+@[^@\s]+$/.test(value)) return maskEmail(value);
  if (typeof value === "string" && /^phone$/i.test(key)) return maskPhone(value);
  if (typeof value === "string" && /^(name|full_?name)$/i.test(key)) return `${value.slice(0, 1)}***`;
  return value;
}

export function logIntegration(event, fields) {
  // JSON.stringify escapes \r and \n, so a partner's value cannot forge a new log line
  console.log(JSON.stringify({ time: new Date().toISOString(), event, ...redact(fields) }));
}

import { logIntegration } from "./safe-log.mjs";

logIntegration("crm.lead.create", {
  integration: "crm-main",
  status: 401,
  durationMs: 184,
  request: {
    url: "https://crm.example.test/api/v4/leads?api_key=YOUR_API_KEY",
    headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  },
  lead: { name: "Test Client", phone: "+7 701 000 00 42", email: "client@example.test" },
  partnerMessage: "invalid token\nINFO payment ok",
});

$ node safe-log.demo.mjs
{"time":"2026-10-12T03:00:27.507Z","event":"crm.lead.create","integration":"crm-main","status":401,"durationMs":184,"request":{"url":"https://crm.example.test/api/v4/leads?[REDACTED]","headers":{"Authorization":"[REDACTED]","Content-Type":"application/json"}},"lead":{"name":"T***","phone":"***42","email":"c***@example.test"},"partnerMessage":"invalid token\nINFO payment ok"}