認証方式とレート制限

AppCotton の REST API は、用途ごとに複数の認証手段を提供します。フロントエンド（WordPress ログイン中の管理画面／会員ページ）と、サーバー間連携（ビルドパイプラインやヘッドレス配布サイト）で最適な方式を選んでください。
また、API 安全性と安定稼働のため**レート制限（Rate Limiting）**を実施します。

1. 認証方式（Auth Schemes）

1.1 WordPress Nonce（ログイン済みフロントエンド向け）

対象: 管理画面 UI、会員ページ（マイライセンス、ドメイン解除など）
送信ヘッダ:
X-WP-Nonce: <wp_create_nonce('wp_rest') で生成された値>
取得方法（例）: ローカライズされた JS オブジェクト appcotton_params.appcotton_nonce
特徴: WordPress 標準の REST 認証。ユーザー権限が反映されるため、UI 操作の保護に最適。
サンプル

POST /wp-json/appcotton/v1/licenses/deactivate
X-WP-Nonce: 1234567890abcdef
Content-Type: application/json

{"license_key":"LIC-XXXX","domain":"https://example.com"}

1.2 パーソナルアクセストークン（PAT / Bearer Token）

対象: サーバー間連携、CI/CD、配布ポータル
送信ヘッダ:
Authorization: Bearer <your_appcotton_token>
発行: 管理画面「設定＞API キー」から発行（権限・有効期限・IP 制限を設定可能）
権限: scope ベース（例：licenses:read, licenses:write, products:read）
サンプル

GET /wp-json/appcotton/v1/licenses/validate?license_key=LIC-XXXX&domain=https%3A%2F%2Fexample.com
Authorization: Bearer pat_xxx

1.3 HMAC 署名（サーバー間の高信頼チャネル向け）

対象: Webhook 検証、社内サーバーや別基盤からのコール
ヘッダ:
- X-AppCotton-Timestamp: <unix epoch seconds>
- X-AppCotton-Signature: sha256=<hex>
署名方式: signature = HEX( HMAC-SHA256( secret, "{timestamp}.{method}.{path}.{body}" ) )
耐タンパー性: 本文含めて署名、時刻ズレ許容 ±300 秒（リプレイ防止）

1.4 ライセンスキー単体（読み取り専用）

対象: 軽量な自己検証（例：プラグインが自身の有効性を確認）
注意: できる限り PAT または Nonce を推奨。ライセンスキー単体は読み取り系に限定し、活性化/解除などの書き込み操作には使用不可。

2. エンドポイント別の推奨認証

Endpoint	用途	推奨認証
`GET /licenses/validate`	ライセンス検証（読み取り）	Bearer（サーバー間） / Nonce（UI） / ライセンスキー単体（最小限）
`POST /licenses/activate`	ドメインアクティベーション	Bearer / Nonce
`POST /licenses/deactivate`	ドメイン解除	Bearer / Nonce
`GET /products/:id/plans`	プラン一覧取得	Bearer / Nonce
`POST /checkout/upgrade`	差額課金チェックアウト開始	Bearer / Nonce
Webhook 受信	Stripe/外部→AppCotton	HMAC 署名（`X-AppCotton-Signature`）

メモ: Stripe Webhook 等の例外は、IP 制限＋HMAC 署名の併用が推奨です。

3. リクエスト例

3.1 ライセンス検証（サーバー間 / Bearer）

curl -X GET \
  "https://example.com/wp-json/appcotton/v1/licenses/validate?license_key=LIC-XXXX&domain=https%3A%2F%2Fexample.com" \
  -H "Authorization: Bearer pat_xxx"

成功レスポンス

{
  "valid": true,
  "message": "ok",
  "expires_at": "2026-01-31 23:59:59",
  "usage": {
    "used": 2,
    "limit": 3,
    "remaining": 1,
    "activations": [
      {"domain":"https://site-a.com","status":"active"},
      {"domain":"https://site-b.com","status":"active"}
    ]
  },
  "is_activated": true
}

3.2 アクティベーション（UI / Nonce）

curl -X POST "https://example.com/wp-json/appcotton/v1/licenses/activate" \
  -H "X-WP-Nonce: 1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{"license_key":"LIC-XXXX","domain":"https://example.com","site_url":"https://example.com","instance_id":"blog_42"}'

エラーレスポンス（例）

{
  "success": false,
  "error": "activation_limit_reached",
  "message": "Activation limit reached for this license.",
  "usage": {"used": 3, "limit": 3, "remaining": 0}
}

4. CORS・ドメイン正規化

CORS: WordPress の REST CORS 設定または独自ヘッダで許可オリジンを絞り込み
例）Access-Control-Allow-Origin: https://your-frontend.example
ドメイン正規化:
- 保存時は scheme + host（https://example.com）を推奨
- 比較時は lowercase、末尾 / の扱い統一、www 取り扱いポリシー（固定 or 同一視）を 一元化
リプレイ防止: HMAC 時は X-AppCotton-Timestamp の時刻差チェック（±300s 以内）

5. レート制限（Rate Limiting）

5.1 基本ポリシー（デフォルト）

スライディングウィンドウ + バースト許容
- 読み取り系（GET）: 60 req / 1 min / IP or Token（バースト 20）
- 書き込み系（POST/PUT/PATCH/DELETE）: 20 req / 1 min / IP or Token（バースト 10）
- 高コスト系（チェックアウト開始・大量検証）: 10 req / 5 min / Token
単位: 原則、Token（Bearer or Nonce ユーザー）優先、未認証は IP 単位
429 応答: 上限超過時は HTTP 429 Too Many Requests とし、ヘッダで残量・復帰目安を返します。
- X-RateLimit-Limit: 60
- X-RateLimit-Remaining: 0
- X-RateLimit-Reset: <unix epoch seconds>
- Retry-After: <seconds>

例：429 応答

{
  "error": "rate_limited",
  "message": "Too many requests. Please retry later."
}

5.2 グレイス & 優遇

管理者ロール・サーバー間の信頼トークンには緩和または除外を設定可能（設定画面でトグル）。
Webhook エンドポイントは送信元固定 + HMAC 検証を満たす場合に緩和可。

6. エラーハンドリング（共通仕様）

JSON 形式（原則）

{
  "success": false,
  "error": "activation_limit_reached",
  "message": "Activation limit reached for this license.",
  "hint": "Deactivate one domain from My Page to free a seat.",
  "trace_id": "ac_20251111_7f8d1",
  "docs": "https://your-site.example/docs/common-errors"
}

error: 機械可読なエラーコード
例）invalid_nonce, unauthorized, forbidden, not_found, rate_limited,
　validation_failed, activation_limit_reached, license_expired
trace_id: サポート対応向けにログ突合
docs: 該当ドキュメント URL を返却可能

7. セキュリティ実装チェックリスト

X-WP-Nonce の検証（wp_verify_nonce）
Bearer Token の検証（有効期限/Scope/IP 制限）
HMAC 署名の検証（ボディ・メソッド・パスを含む、時刻差判定）
権限チェック（ユーザー／トークン scope → エンドポイントごと）
入力バリデーション（license_key, domain, product_id, plan_id など）
ドメイン正規化と比較ロジックの一元化
レート制限（429 と Retry-After の送出）
監査ログ（失敗と成功の要点、PII は最小化）
CORS 制御（許可オリジンの限定）
エラー統一（エラーコードとメッセージの整合）

8. 構成例（推奨）

設定画面
- API キー管理（発行／失効／Scope／有効期限／IP Allowlist）
- レート制限のしきい値（読取／書込／高コスト系別）
- CORS 許可オリジン
- ドメイン正規化ポリシー（www 取り扱い、末尾スラッシュ）
ログ/可観測性
- trace_id 付与、429/4xx の可視化、Webhook 検証ログ

9. 互換性・フォールバック

WordPress ログインがないヘッドレス配布サイトは Bearer を利用
既存クライアントがライセンスキー単体で検証している場合は読み取り専用の互換を維持（将来的に Bearer への移行を推奨）

10. まとめ

UI/管理画面は Nonce
サーバー間は Bearer（PAT）
Webhookは HMAC 署名
読み取り専用の簡易検証としてライセンスキー単体は可（将来は縮小予定）
すべての呼び出しでレート制限と一貫したエラー仕様を適用します。

Single Post