create-ampless 1.0.0-alpha.94 → 1.0.0-alpha.95

package/dist/templates/_shared/docs/plugin-author-guide.ja.md

@@ -88,7 +88,7 @@ ampless プラグインは `AmplessPlugin` オブジェクトを返す TypeScrip
   Lambda (`hooks`) でやる
 - **admin ルート / server ルート / コンテンツフィールドの追加** —
   Phase 6b 予約
-- **secret の読み書き**。`secretSettings` capability は Phase 6a 予約。
+- **Admin routes / server routes / content fields.** Phase 6b 予約。
   `settings.public` に credential を置かないこと
 
 ---
@@ -702,6 +702,19 @@ stored 値 (validated)
 
 ---
 
+## 9a. Secret settings: `ctx.secret<T>(key)` (Phase 6a)
+
+Secret settings を使うと、trusted プラグインが認証情報 (Webhook 署名 secret・SMTP パスワード・外部 API トークン等) を admin UI 経由で保存・ローテーションできます。**公開サイトやブラウザ側コードに値が流れることはありません**。
+
+詳しいリファレンスは [`packages/ampless/docs/plugin-author-guide.md`](../../packages/ampless/docs/plugin-author-guide.md) §9a を参照してください。概要:
+
+- `settings.secret` は `trust_level: 'trusted'` + `'secretSettings'` capability 必須。
+- フィールド型は `PluginSecretField` = `Omit<PluginTextField, 'default'> | Omit<PluginTextareaField, 'default'>`。`default` は型レベルで禁止。fallback は closure-private 変数で保持。
+- hook 内で `await ctx.secret<string>('signingSecret')` で読む。per-invocation キャッシュ済み。
+- admin UI が「保存済み」表示 (`••••••••`) + Replace + Clear を提供。値は取得・表示されない。
+
+---
+
 ## 10. ウォークスルー: GA4 を Phase 1 から Phase 2 に移行する
 
 Phase 1 の GA4 プラグインは measurement ID を constructor 引数で受けていました。Phase 2 では後方互換のためにその引数を残しつつ、値は `ctx.setting()` 経由で読みます。

package/dist/templates/_shared/docs/plugin-author-guide.md

@@ -93,6 +93,7 @@ surfaces:
 | `ogImage` | `/og/[slug]` route | request-time, in public Lambda | Existing |
 | `hooks` | trust_level-matched processor Lambda | async, on SQS event | Existing |
 | `settings.public` | `/admin/plugins` form | declarative manifest | 2 |
+| `settings.secret` | `/admin/plugins` secret section | declarative manifest, trusted Lambda only | 6a |
 
 A few surfaces don't exist yet — they're reserved for later phases
 and aren't shaped by `definePlugin` today:
@@ -111,8 +112,6 @@ and aren't shaped by `definePlugin` today:
   work belongs there.
 - **Admin routes / server routes / content fields.** Reserved for
   Phase 6b.
-- **Secrets.** The `secretSettings` capability is reserved for
-  Phase 6a; nothing in `settings.public` should be a credential.
 
 ---
 
@@ -906,6 +905,108 @@ plugin's own `instanceId`.
 
 ---
 
+## 9a. Secret settings: `ctx.secret<T>(key)` (Phase 6a)
+
+Secret settings let trusted plugins store and rotate credentials
+(webhook signing secrets, SMTP passwords, external API tokens)
+through the admin UI **without exposing them to the public site or
+browser-side code**.
+
+### Why a separate API from `settings.public`?
+
+Values in `settings.public` are designed to flow to the public
+runtime: they're mirrored to `public/site-settings.json` and read
+by `ctx.setting()` inside sync render surfaces. That flow is
+intentional for analytics measurement IDs, consent category names,
+etc. — but completely wrong for a webhook signing secret.
+
+`settings.secret` has a structurally different storage model:
+
+- Stored in the `PluginSecret` DynamoDB model (separate from KvStore).
+- Admin/editor groups can **write and delete** but have **no read
+  authorization** — the AppSync schema does not generate
+  `getPluginSecret` or `listPluginSecrets` queries for those groups.
+- Only the trusted-processor Lambda IAM role can read, via DDB
+  `GetItem` directly.
+- Never queried by the site-settings mirror path.
+- Never passed to any public-render surface
+  (`publicHead`, `publicBodyEnd`, `publicBodyForPost`,
+  `publicHtmlForPost`) — those surfaces only see `ctx.setting()`.
+
+### Requirements
+
+`settings.secret` requires:
+
+1. `trust_level: 'trusted'` — untrusted Lambdas have no DDB read
+   access to the PluginSecret table. `definePlugin()` throws if you
+   declare `settings.secret` with any other trust level.
+2. `'secretSettings'` in `capabilities` — required so admin UI and
+   future allow-lists can gate the capability. Omitting it produces
+   a console warning (same pattern as `'schema'` vs `publicBodyForPost`).
+
+### Declaring secret fields
+
+```ts
+import { definePlugin } from 'ampless'
+
+export default function webhookPlugin(opts?: { signingSecret?: string }) {
+  // Keep any constructor-provided secret as a closure-private fallback.
+  // It is NEVER exposed in the manifest or the stored descriptor.
+  const constructorSecret = opts?.signingSecret
+
+  return definePlugin({
+    name: 'webhook',
+    apiVersion: 1,
+    trust_level: 'trusted',
+    capabilities: ['eventHooks', 'secretSettings'],
+    settings: {
+      secret: [
+        {
+          type: 'text',
+          key: 'signingSecret',
+          label: { en: 'Webhook signing secret', ja: 'Webhook 署名 secret' },
+          maxLength: 256,
+          required: false,
+          // NO `default` — secret fields forbid it at the type level.
+          // Use a closure-private fallback instead (see below).
+        },
+      ],
+    },
+    hooks: {
+      async 'content.published'(event, ctx) {
+        const storedSecret = await ctx.secret<string>('signingSecret')
+        const secret = storedSecret ?? constructorSecret
+        if (!secret) return
+        // ... use secret to sign and POST
+      },
+    },
+  })
+}
+```
+
+### Important: no `default` on secret fields
+
+The type `PluginSecretField` is defined as `Omit<PluginTextField,
+'default'> | Omit<PluginTextareaField, 'default'>` — the `default`
+property is **removed at the type level**. Use a closure-private
+fallback variable instead; never put credentials in the manifest.
+
+### Reading secrets: `ctx.secret<T>(key)`
+
+`ctx.secret<T>(key)` is only available in trusted hook handlers.
+Returns `undefined` when no value has been saved by admin. Results
+are per-invocation cached; cache keys are namespaced by
+`${instanceId ?? name}:${fieldKey}`.
+
+### Admin UI
+
+When `settings.secret` is declared, the admin plugin settings page
+renders a **Secret settings** section below the public fields.
+Admins see `••••••••` for stored values and can Replace or Clear
+without deploying. Rotation takes effect within ~5–10 seconds.
+
+---
+
 ## 10. Walk-through: migrating GA4 from Phase 1 to Phase 2
 
 The Phase 1 GA4 plugin took the measurement ID through a

package/dist/templates/_shared/package.json

@@ -25,21 +25,21 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.12",
-    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.3",
-    "@ampless/plugin-gtm": "^0.2.0-alpha.11",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.28",
-    "@ampless/plugin-plausible": "^0.2.0-alpha.11",
-    "@ampless/plugin-reading-time": "^0.1.0-alpha.1",
-    "@ampless/plugin-rss": "^0.2.0-alpha.28",
-    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.7",
-    "@ampless/plugin-seo": "^0.2.0-alpha.28",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.28",
-    "@ampless/admin": "^1.0.0-alpha.57",
-    "@ampless/backend": "^1.0.0-alpha.45",
-    "@ampless/runtime": "^1.0.0-alpha.36",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.13",
+    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.4",
+    "@ampless/plugin-gtm": "^0.2.0-alpha.12",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.29",
+    "@ampless/plugin-plausible": "^0.2.0-alpha.12",
+    "@ampless/plugin-reading-time": "^0.1.0-alpha.2",
+    "@ampless/plugin-rss": "^0.2.0-alpha.29",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.8",
+    "@ampless/plugin-seo": "^0.2.0-alpha.29",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.29",
+    "@ampless/admin": "^1.0.0-alpha.58",
+    "@ampless/backend": "^1.0.0-alpha.46",
+    "@ampless/runtime": "^1.0.0-alpha.37",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.28",
+    "ampless": "^1.0.0-alpha.29",
     "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ampless",
-  "version": "1.0.0-alpha.94",
+  "version": "1.0.0-alpha.95",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",