HMAC-автентифікація та безпека

Захистіть ваші HMAC-підписані URL-адреси OG-зображень за допомогою HMAC-SHA256 автентифікації FastOG. Цей посібник охоплює підписання, перевірку та усунення неполадок кожного запиту, щоб ви могли генерувати динамічні Open Graph зображення на льоту — з обмеженням за підпискою та без обмежень на рендеринг (без щомісячної квоти на рендери та без додаткової оплати за перевищення). Зареєструйтеся, оберіть тарифний план Dynamic API, а потім створіть ваш API-ключ і HMAC-секрет у панелі керування (платні рендери API є чистими). Підпишіть запит на вашому сервері один раз та інтегруйте за лічені хвилини.

🚀 Швидкий старт

Новачок у HMAC-підписуванні? Почніть тут:

1. Посібник зі швидкого старту — налаштуйтеся за 5 хвилин
2. Підручник з JavaScript — повний посібник для розробників Node.js/Next.js
3. Усі підручники за фреймворками — оберіть свій стек:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Покажчик документації

Основні концепції

• Посібник із HMAC-підпису — Повний довідник із деталями алгоритму, вимогами та прикладами на JavaScript, PHP і Python
• Перевірка HMAC — Деталі серверної реалізації, функції безпеки та відповіді з помилками

Навчальні посібники

• Навчальний посібник JavaScript/Node.js — Вичерпний посібник, що охоплює:

  • Швидкий старт (5 хвилин)
  • Next.js App Router (3 патерни)
  • Next.js Pages Router
  • Бекенд на Express.js
  • Vanilla Node.js
  • Патерни інтеграції у фронтенді (SSG, SSR, клієнтський рендеринг)
  • Тестування та налагодження
  • Типові помилки

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Vanilla Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Швидкий довідник

Алгоритм

method = "GET"
path = "/api/v1/og"
canonicalQuery = every query param EXCEPT `s` (including `key`): array values sorted too; each pair rfc3986Encode(key)=rfc3986Encode(value); pairs sorted lexicographically and joined with "&"

message = method + path + "\n" + canonicalQuery
signature = hex(HMAC-SHA256(message, hmac_secret))

URL: /api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>

Параметри запиту

Коди помилок

🎯 Варіанти використання

Записи в блозі

Генеруйте динамічні OG-зображення для записів у блозі:

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});

// <meta property="og:image" content="{ogUrl}" />

Товари в інтернет-магазині

Створюйте OG-зображення для сторінок товарів:

const ogUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});

Відгуки клієнтів

Генеруйте OG-зображення для цитат із відгуками:

const ogUrl = generateSignedOgUrl({
    template: "testimonial",
    author_name: user.name,
    author_avatar: user.avatarUrl,
    quote: user.bio,
});

🔐 Безпека

Рекомендовані практики

1. Зберігайте секрети надійно — використовуйте змінні середовища або менеджер секретів
2. Ніколи не передавайте HMAC-секрет у клієнтський код — підписуйте лише на сервері
3. Використовуйте HTTPS — це запобігає атакам типу MITM
4. Періодично змінюйте секрети — особливо якщо вони могли бути скомпрометовані
5. Відстежуйте невдалі підписи — повторні невдачі можуть свідчити про атаки
6. Ізоляція користувачів — кожен API-ключ має власний HMAC-секрет

Отримання вашого HMAC-секрету

1. Перейдіть до Панель керування → API-ключі
2. Створіть новий API-ключ
3. Скопіюйте HMAC-секрет (показується лише один раз!)
4. Збережіть його у змінних середовища

# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Тестування

Згенерувати тестову URL-адресу

# Node.js
node -e "
const crypto = require('crypto');
const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
const all = { title: 'Test', key: 'sk_quick_123abc' };
const pairs = [];
for (const [k, v] of Object.entries(all)) for (const vv of Array.isArray(v) ? v : [v]) pairs.push(enc(k) + '=' + enc(vv));
pairs.sort();
const canonical = pairs.join('&');
const sig = crypto.createHmac('sha256', 'YOUR_HMAC_SECRET').update('GET/api/v1/og\n' + canonical).digest('hex');
console.log('https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=' + sig);
"

Тестування за допомогою curl

curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>"

Очікувані відповіді

• ✅ Дійсний підпис → Повертає OG-зображення (або 422, якщо параметри шаблону недійсні)
• ❌ Недійсний підпис → {"code": "invalid_signature"}
• ❌ Відсутні параметри → {"code": "missing_signature"}

🛠 Усунення несправностей

Підпис не збігається

1. Переконайтеся, що ви використовуєте правильний HMAC-секрет (перевірте API-ключ у панелі керування)
2. Перевірте канонічний запит: усі параметри запиту, окрім s (включно з key), значення закодовані за RFC3986, ключі відсортовані лексикографічно
3. Переконайтеся, що підпис — це нижній регістр шістнадцяткового коду (64 символи)

📖 Додаткові ресурси

• Довідник API — Повна документація API
• Кращі практики безпеки — Детальний посібник із безпеки
• База знань — Технічні деталі впровадження

❓ FAQ

П: Чому параметри запиту, а не заголовки?
В: OG-зображення отримуються краулерами соціальних мереж (LinkedIn, Twitter, Facebook), які не надсилають власні заголовки. Підпис ОБОВ'ЯЗКОВО має бути в URL.

П: Чи можна використовувати той самий підпис для кількох запитів?
В: Так. Підпис обчислюється з точного запиту (мінус s), тому той самий підписаний URL залишається дійсним, доки параметри не змінюються. Змініть будь-який параметр (включно з key) — і вам доведеться підписати запит заново.

П: Чи потрібно підписувати запити для всіх шаблонів?
В: Так. Усі запити до /api/v1/og вимагають HMAC-підписів.

П: Що станеться, якщо мій HMAC-секрет буде скомпрометовано?
В: Відкличте API-ключ у панелі керування та створіть новий. Кожен API-ключ має власний HMAC-секрет.

П: Чи можу я вимкнути HMAC-валідацію для внутрішніх сервісів?
В: Зверніться до підтримки щодо індивідуальних рішень. HMAC-валідація є обов'язковою для всіх публічних API-ендпоінтів.

🆘 Підтримка

Потрібна допомога?

• Перегляньте JavaScript-підручник з повними прикладами коду
• Ознайомтеся з посібником з HMAC-підписів для деталей алгоритму
• Зв’яжіться з підтримкою за адресою [email protected]

Пов’язані матеріали

• Документація — усі посібники та довідники FastOG
• Безкоштовний тестер OG-зображень — попередній перегляд без облікового запису
• Посібник із швидкого старту — налаштування за 5 хвилин
• Посібник із підпису HMAC — деталі алгоритму
• Перевірка HMAC — перевірка на стороні сервера