@ampless/plugin-webhook 0.2.0-alpha.5 → 0.2.0-alpha.50

package/README.ja.md

@@ -0,0 +1,134 @@
+> English: [README.md](./README.md)
+> 
+
+# @ampless/plugin-webhook
+
+ampless イベントを 1 つ以上の外部 URL に POST で通知します。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+
+**trusted** Lambda で実行されます — 署名シークレットを admin UI から管理できるため、再デプロイなしでキーローテーションが可能です。
+
+## インストール
+
+```bash
+npm install @ampless/plugin-webhook@alpha
+```
+
+## 設定
+
+`cms.config.ts` に記述します：
+
+```ts
+import webhookPlugin from '@ampless/plugin-webhook'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    webhookPlugin({
+      endpoints: [
+        {
+          url: 'https://example.com/hooks/ampless',
+          secret: process.env.WEBHOOK_SECRET,
+          events: ['content.published', 'content.unpublished', 'content.deleted'],
+        },
+        {
+          url: 'https://discord.com/api/webhooks/.../...',
+          // secret なし — Discord は署名を検証しない
+          events: ['content.published'],
+        },
+      ],
+    }),
+  ],
+})
+```
+
+| オプション | デフォルト | 備考 |
+|---|---|---|
+| `endpoints[].url` | 必須 | POST 先の HTTPS エンドポイント |
+| `endpoints[].secret` | なし | 設定時、本文を HMAC-SHA-256 で署名して `X-Ampless-Signature` ヘッダーで送信 |
+| `endpoints[].events` | すべての `content.*` | このエンドポイントを発火するイベント種別を絞り込む |
+| `endpoints[].headers` | `{}` | 全リクエストにマージされる追加ヘッダー |
+| `endpoints[].timeoutMs` | `5000` | リクエストごとのタイムアウト |
+| `url`（トップレベル） | なし | 単一エンドポイントのショートカット。`endpoints: [{ url, secret }]` と同等 |
+| `secret`（トップレベル） | なし | トップレベルの `url` と対で使用 |
+
+## リクエスト形式
+
+```http
+POST /hooks/ampless HTTP/1.1
+Host: example.com
+Content-Type: application/json
+X-Ampless-Event: content.published
+X-Ampless-Signature: sha256=<hex>
+
+{
+  "type": "content.published",
+  "payload": {
+    "siteId": "default",
+    "postId": "post-001",
+    "slug": "hello",
+    "title": "Hello",
+    "status": "published",
+    "publishedAt": "2026-04-30T00:00:00.000Z",
+    "tags": ["intro"]
+  },
+  "timestamp": "2026-04-30T00:00:01.000Z"
+}
+```
+
+## 署名の検証（Node.js）
+
+```ts
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+function verify(rawBody: string, signatureHeader: string, secret: string): boolean {
+  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
+  const a = Buffer.from(expected)
+  const b = Buffer.from(signatureHeader)
+  if (a.length !== b.length) return false
+  return timingSafeEqual(a, b)
+}
+```
+
+HMAC は必ず JSON パース前の**生のリクエストボディ**に対して計算し、定数時間比較を使用してください。
+
+## 署名シークレット（admin 管理）
+
+Phase 6a から、Webhook プラグインは admin 管理の署名シークレットをサポートします。再デプロイなしで HMAC キーをローテーションできます。
+
+### admin UI でのシークレット設定
+
+1. `/admin/plugins/webhook` → **Secret settings** を開く。
+2. 署名シークレットを入力して **Save** をクリック。
+3. 数秒以内に新しいキーが有効になります — `git push` も Amplify リビルドも不要。
+
+### シークレットの適用ルール
+
+- **admin シークレットが設定済み** → **すべての** エンドポイントに一律適用。キーのローテーションを 1 箇所で管理できるため、本番環境ではこの方式を推奨します。
+- **admin シークレット未設定** → 各エンドポイントはコンストラクタのオプションで渡した per-endpoint `secret` にフォールバック（[設定](#設定) 参照）。初期セットアップに使い、本番移行後は admin 管理に切り替えてください。
+
+コンストラクタの per-endpoint `secret` はクロージャ内にのみ保持され、プラグインマニフェストや公開成果物には**絶対に含まれません** — 設計上サーバーサイドに留まります。
+
+### シークレットのローテーション
+
+1. 新しいシークレットを生成（例: `openssl rand -hex 32`）。
+2. 受信側を旧・新シークレットの両方で一時的に検証できるように更新（デュアル検証）。
+3. admin UI で **Replace** → 新シークレットを入力 → **Save**。
+4. 飛行中の Webhook がすべて処理されたら（約 30 秒）、受信側から旧シークレットを削除。
+
+### 受信側での署名検証
+
+receiver 側の実装は [署名の検証（Node.js）](#署名の検証nodejs) を参照してください — admin UI 経由か コンストラクタ経由かに関わらず、検証コードは同一です。
+
+## リトライ動作
+
+いずれかのエンドポイントが 2xx 以外のレスポンスを返した場合（またはタイムアウトした場合）、プラグインは例外を投げます。トラストレベルプロセッサーの Lambda が SQS に再スローし、デッドレターキューに移動するまで最大 3 回リトライされます。同じイベントが複数回配信される可能性があるため、冪等な受信側を推奨します。
+
+## 発火するイベント
+
+- `content.created` — 新規投稿（任意のステータス）
+- `content.published` — ステータスが `draft` → `published` に変化、または公開済み投稿が挿入された
+- `content.unpublished` — ステータスが `published` → `draft` に変化、または公開済み投稿が削除された
+- `content.updated` — 任意の MODIFY（公開 / 非公開への遷移時にも `published` / `unpublished` と同時に発火）
+- `content.deleted` — 投稿が削除された

package/README.md

@@ -1,10 +1,13 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+
 # @ampless/plugin-webhook
 
 POST ampless events to one or more external URLs.
 
 > **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
 
-Runs in the **untrusted** Lambda — it makes outbound HTTPS calls and never touches AWS data, so a compromised webhook receiver can't pivot into your CMS.
+Runs in the **trusted** Lambda so it can access the admin-managed signing secret for zero-deploy key rotation.
 
 ## Install
 
@@ -90,6 +93,34 @@ function verify(rawBody: string, signatureHeader: string, secret: string): boole
 
 Always compute the HMAC over the **raw request body** before any JSON parsing, and use a constant-time comparison.
 
+## Signing secret (admin-managed)
+
+Since Phase 6a the webhook plugin supports an admin-managed signing secret that lets you rotate the HMAC key without redeploying.
+
+### Setting the secret in the admin UI
+
+1. Open `/admin/plugins/webhook` → **Secret settings**.
+2. Enter your signing secret and click **Save**.
+3. The new key is active within seconds — no `git push`, no Amplify rebuild.
+
+### How the secret applies
+
+- **Admin secret is set** → applied to **all** endpoints uniformly. This is the recommended production setup because it gives you a single place to rotate the key.
+- **Admin secret is not set** → each endpoint falls back to its per-endpoint `secret` from the constructor options (see [Configure](#configure) below). Use this for initial setup before you've migrated to admin-managed.
+
+The per-endpoint constructor `secret` is closure-private and is **never** included in the plugin manifest or any public artifact — it stays server-side by construction.
+
+### Rotating the secret
+
+1. Generate a new secret (e.g. `openssl rand -hex 32`).
+2. Update your receiver to accept both old and new secrets for a brief window (dual-verify).
+3. Paste the new secret in the admin UI → **Replace** → **Save**.
+4. Once all in-flight webhooks have drained (~30 s), remove the old secret from your receiver.
+
+### Verifying the signature on the receiver
+
+See [Verifying the signature](#verifying-the-signature-nodejs) below for the receiver-side implementation — the verification code is identical regardless of whether the key came from the admin UI or from the constructor.
+
 ## Retry behavior
 
 When any endpoint returns a non-2xx response (or times out), the plugin throws. The trust-level processor Lambda re-throws to SQS, which retries the message up to 3 times before moving it to the dead-letter queue. Idempotent receivers are recommended — the same event can be delivered more than once.

package/dist/index.d.ts

@@ -29,16 +29,21 @@ interface WebhookEndpoint {
     timeoutMs?: number;
 }
 interface WebhookPluginOptions {
-    endpoints?: WebhookEndpoint[];
-    /** Backwards-compatible single-endpoint shortcut. */
-    url?: string;
-    secret?: string;
+    endpoints: WebhookEndpoint[];
 }
 /**
  * Webhook plugin. Posts a JSON envelope to one or more external URLs
- * whenever a subscribed event fires. Runs in the untrusted Lambda — it
- * needs no AWS data access, only outbound HTTPS.
+ * whenever a subscribed event fires. Runs in the trusted Lambda so it
+ * can access the admin-managed signing secret via `ctx.secret()`.
+ *
+ * Secret priority (per dispatch call):
+ *   1. Admin-managed `signingSecret` (set from `/admin/plugins/webhook`):
+ *      applied uniformly to **all** endpoints — enables zero-deploy key
+ *      rotation.
+ *   2. Per-endpoint `secret` from the constructor options (closure-private
+ *      fallback): used when the admin secret has not been saved yet.
+ *      Recommended for initial setup; rotate to admin-managed in production.
  */
-declare function webhookPlugin(options?: WebhookPluginOptions): AmplessPlugin;
+declare function webhookPlugin(options: WebhookPluginOptions): AmplessPlugin;
 
 export { type WebhookEndpoint, type WebhookPluginOptions, webhookPlugin as default, signPayload };

package/dist/index.js

@@ -1,5 +1,7 @@
 // src/index.ts
-import { definePlugin } from "ampless";
+import {
+  definePlugin
+} from "ampless";
 
 // src/sign.ts
 import { createHmac } from "crypto";
@@ -15,8 +17,8 @@ var ALL_CONTENT_EVENTS = [
   "content.unpublished",
   "content.deleted"
 ];
-function webhookPlugin(options = {}) {
-  const endpoints = normalizeEndpoints(options);
+function webhookPlugin(options) {
+  const endpoints = options.endpoints;
   const subscribed = /* @__PURE__ */ new Set();
   for (const ep of endpoints) {
     const events = ep.events ?? ALL_CONTENT_EVENTS;
@@ -24,31 +26,42 @@ function webhookPlugin(options = {}) {
   }
   const hooks = {};
   for (const eventType of subscribed) {
-    hooks[eventType] = async (event) => {
-      await dispatch(endpoints, event);
+    hooks[eventType] = async (event, ctx) => {
+      const adminSecret = await ctx.secret("signingSecret");
+      await dispatch(endpoints, event, adminSecret);
     };
   }
   return definePlugin({
     name: "webhook",
+    packageName: "@ampless/plugin-webhook",
     apiVersion: 1,
-    trust_level: "untrusted",
+    trust_level: "trusted",
+    capabilities: ["eventHooks", "secretSettings"],
+    settings: {
+      secret: [
+        {
+          type: "text",
+          key: "signingSecret",
+          maxLength: 256,
+          label: { en: "Signing secret", ja: "\u7F72\u540D\u30B7\u30FC\u30AF\u30EC\u30C3\u30C8" },
+          description: {
+            en: "HMAC-SHA-256 signing secret applied to all webhook endpoints. When set, overrides the per-endpoint constructor secret. Rotate here without redeploying.",
+            ja: "\u3059\u3079\u3066\u306E Webhook \u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u306B\u9069\u7528\u3059\u308B HMAC-SHA-256 \u7F72\u540D\u30B7\u30FC\u30AF\u30EC\u30C3\u30C8\u3002\u8A2D\u5B9A\u3059\u308B\u3068\u30B3\u30F3\u30B9\u30C8\u30E9\u30AF\u30BF\u5074\u306E per-endpoint secret \u3088\u308A\u512A\u5148\u3055\u308C\u307E\u3059\u3002\u518D\u30C7\u30D7\u30ED\u30A4\u4E0D\u8981\u3067\u3053\u3053\u304B\u3089\u66F4\u65B0\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
+          }
+        }
+      ]
+    },
     hooks
   });
 }
-function normalizeEndpoints(options) {
-  const list = [];
-  if (options.url) list.push({ url: options.url, secret: options.secret });
-  if (options.endpoints) list.push(...options.endpoints);
-  return list;
-}
-async function dispatch(endpoints, event) {
+async function dispatch(endpoints, event, adminSecret) {
   const body = JSON.stringify({
     type: event.type,
     payload: event.payload,
     timestamp: event.timestamp
   });
   const results = await Promise.allSettled(
-    endpoints.filter((ep) => (ep.events ?? ALL_CONTENT_EVENTS).includes(event.type)).map((ep) => postOne(ep, body, event.type))
+    endpoints.filter((ep) => (ep.events ?? ALL_CONTENT_EVENTS).includes(event.type)).map((ep) => postOne(ep, body, event.type, adminSecret))
   );
   const failures = results.filter((r) => r.status === "rejected");
   if (failures.length > 0) {
@@ -56,14 +69,15 @@ async function dispatch(endpoints, event) {
     throw new Error(`webhook plugin: ${failures.length} endpoint(s) failed \u2014 ${messages}`);
   }
 }
-async function postOne(endpoint, body, eventType) {
+async function postOne(endpoint, body, eventType, adminSecret) {
   const headers = {
     "Content-Type": "application/json",
     "X-Ampless-Event": eventType,
     ...endpoint.headers ?? {}
   };
-  if (endpoint.secret) {
-    headers["X-Ampless-Signature"] = signPayload(endpoint.secret, body);
+  const effectiveSecret = adminSecret ?? endpoint.secret;
+  if (effectiveSecret) {
+    headers["X-Ampless-Signature"] = signPayload(effectiveSecret, body);
   }
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), endpoint.timeoutMs ?? 5e3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/plugin-webhook",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.50",
   "description": "Webhook plugin for ampless — POST events to external URLs",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,8 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -25,13 +26,27 @@
   "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook#readme",
   "bugs": "https://github.com/heavymoons/ampless/issues",
   "dependencies": {
-    "ampless": "0.2.0-alpha.5"
+    "ampless": "1.0.0-alpha.49"
   },
   "keywords": [
     "ampless",
     "plugin",
+    "ampless-plugin",
     "webhook"
   ],
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "webhook",
+    "trustLevel": "trusted",
+    "capabilities": [
+      "eventHooks",
+      "secretSettings"
+    ],
+    "displayName": {
+      "en": "Webhook",
+      "ja": "Webhook"
+    }
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",