HMAC認証とセキュリティ

FastOGのHMAC-SHA256認証を使用して、HMAC署名付きOG画像URLを保護します。このガイドでは、各リクエストの署名、検証、トラブルシューティングについて説明します。これにより、動的な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バックエンド
  • バニラNode.js
  • フロントエンド統合パターン（SSG、SSR、クライアントサイド）
  • テストとデバッグ
  • よくある落とし穴

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• バニラ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}" />

Eコマース商品

商品ページ用の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. 署名が小文字の16進数（64文字）であることを確認します

📖 追加リソース

• APIリファレンス — 完全なAPIドキュメント
• セキュリティのベストプラクティス — 詳細なセキュリティガイド
• ナレッジベース — 技術的な実装の詳細

❓ FAQ

Q: なぜヘッダーではなくクエリパラメータを使うのですか？
A: OG画像はソーシャルネットワークのクローラー（LinkedIn、Twitter、Facebook）によって取得されますが、これらのクローラーはカスタムヘッダーを送信しません。署名はURL内に含める必要があります。

Q: 同じ署名を複数のリクエストに使用できますか？
A: はい。署名は正確なクエリ（sを除く）から計算されるため、パラメータが変わらない限り、同じ署名付きURLは有効なままです。パラメータ（keyを含む）を変更した場合は、再署名する必要があります。

Q: すべてのテンプレートでリクエストに署名する必要がありますか？
A: はい。/api/v1/ogへのすべてのリクエストにはHMAC署名が必要です。

Q: HMACシークレットが漏洩した場合はどうなりますか？
A: ダッシュボードでAPIキーを失効させ、新しいものを作成してください。各APIキーには独自のHMACシークレットがあります。

Q: 内部サービス向けにHMAC検証を無効化できますか？
A: カスタムソリューションについてはサポートにお問い合わせください。HMAC検証はすべてのパブリックAPIエンドポイントで必須です。

🆘 サポート

お困りですか？

• 完全なコード例については、JavaScriptチュートリアル をご確認ください
• アルゴリズムの詳細については、HMAC署名ガイド をご確認ください
• [email protected] までサポートにお問い合わせください

関連情報

• ドキュメント — FastOGの全ガイドとリファレンス
• 無料OG画像テスター — アカウントなしでプレビュー
• クイックスタートガイド — 5分で使い始める
• HMAC署名ガイド — アルゴリズムの詳細
• HMAC検証 — サーバーサイドでの検証