ampless 1.0.0-alpha.28 → 1.0.0-alpha.29

package/dist/index.d.ts

@@ -292,6 +292,9 @@ type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
  *     scoped to JSON-LD `<script type="application/ld+json">`. Themes
  *     render the descriptors by calling `ampless.publicBodyForPost(post)`
  *     in their post template.
+ *   - `secretSettings`: admin-managed secret settings stored in the isolated
+ *     `PluginSecret` DynamoDB model. Requires `trust_level: 'trusted'`.
+ *     Trusted hooks access secrets via `ctx.secret<T>(key)`.
  *
  * Reserved capabilities are accepted by the type so that plugins can
  * declare future intent, but the runtime does nothing with them yet —
@@ -299,7 +302,7 @@ type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
  * capability today is harmless, but the runtime won't expose any new
  * surface for it until the matching phase ships.
  */
-type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'writePublicAsset' | 'schema' | 'publicHtmlForPost' | 'contentFields' | 'adminPage' | 'serverRoute' | 'secretSettings' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
+type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'writePublicAsset' | 'schema' | 'publicHtmlForPost' | 'secretSettings' | 'contentFields' | 'adminPage' | 'serverRoute' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
 /**
  * Loading strategy for `script` / `inlineScript` descriptors.
  *
@@ -521,6 +524,35 @@ interface PluginRuntimeContext {
      */
     writePublicAsset(key: string, body: string | Uint8Array, contentType: string): Promise<string>;
 }
+/**
+ * Extended runtime context for **trusted** hook handlers. Adds
+ * `secret<T>(key)` — an async accessor that reads from the isolated
+ * `PluginSecret` DynamoDB model (which admin / editor groups cannot
+ * query). The result is per-invocation cached to avoid redundant DDB
+ * calls when the same key is read multiple times inside one hook batch.
+ *
+ * Cache key is `${instanceId ?? name}:${fieldKey}` to prevent
+ * cross-plugin collisions when two plugin instances declare the same
+ * `key` (e.g. both have a `'signingSecret'` field).
+ *
+ * Only available in the trusted processor (`processor-trusted.ts`).
+ * The untrusted processor never constructs a `TrustedPluginRuntimeContext`
+ * — untrusted hook handlers receive plain `PluginRuntimeContext`, which
+ * does not expose `secret`.
+ */
+interface TrustedPluginRuntimeContext extends PluginRuntimeContext {
+    /**
+     * Read a secret value stored under the plugin's namespace in the
+     * `PluginSecret` table. Returns `undefined` when no value has been
+     * saved yet. The generic `T` is a convenience cast (same pattern as
+     * `ctx.setting<T>()`) — values are always stored as strings, so `T`
+     * defaults to `string`.
+     *
+     * Per-invocation cached: calling `ctx.secret('key')` twice within
+     * the same SQS batch hit costs one DDB round-trip.
+     */
+    secret<T = string>(key: string): Promise<T | undefined>;
+}
 /**
  * A font registered with a plugin's OG image renderer. Satori (the engine
  * inside Next.js `ImageResponse`) requires at least one font. We accept
@@ -698,13 +730,41 @@ interface PluginPackageManifest {
     /** Optional docs / repo URL. */
     homepage?: string;
 }
+/**
+ * Secret field types for `settings.secret`. Restricted to `text` /
+ * `textarea` — the only types useful for opaque string secrets
+ * (API keys, signing secrets, SMTP passwords). More complex types
+ * (number, boolean, select, repeatable) are excluded: structured
+ * secrets are out of scope for v1.
+ *
+ * The `default` property is intentionally stripped via `Omit`. If it
+ * were allowed, the default value would propagate into the admin form
+ * props (visible in the browser), static manifests cross-checked by
+ * the runtime, and JS bundles — multiple leak paths for a value that
+ * must stay server-side. Plugin authors that have a constructor-time
+ * fallback value should keep it as a **closure-private variable** that
+ * is never exposed in the manifest (see the plugin author guide for
+ * the "closure-private fallback" pattern).
+ */
+type PluginSecretField = Omit<PluginTextField, 'default'> | Omit<PluginTextareaField, 'default'>;
 /**
  * Per-plugin settings declaration. Phase 2 implements `public`;
- * `secret` is reserved for Phase 6a (admin-only storage; never reaches
- * the public runtime).
+ * Phase 6a adds `secret` (admin-only storage; never reaches the public
+ * runtime or S3 mirror).
  */
 interface PluginSettingsManifest {
     public?: readonly PluginSettingField[];
+    /**
+     * Admin-managed secret settings. Values are stored in the isolated
+     * `PluginSecret` DynamoDB model, which has no `read` authorization
+     * for admin / editor groups — only trusted Lambda IAM can read them.
+     * Secrets never reach the public runtime or the S3 site-settings
+     * mirror. Requires `trust_level: 'trusted'` and the
+     * `'secretSettings'` capability. Declaring this with an untrusted
+     * plugin throws at `definePlugin()` time; declaring it without the
+     * capability warns.
+     */
+    secret?: readonly PluginSecretField[];
 }
 interface AmplessPlugin {
     name: string;
@@ -1382,4 +1442,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/dist/index.js

@@ -212,6 +212,18 @@ function formatPublicAssetUrl(bucket, region, key) {
 
 // src/plugin.ts
 function definePlugin(p) {
+  if (p.settings?.secret && p.settings.secret.length > 0) {
+    if (p.trust_level !== "trusted") {
+      throw new Error(
+        `[ampless] Plugin "${p.name}": settings.secret requires trust_level "trusted" but got "${p.trust_level}". Secret fields are only accessible from the trusted Lambda \u2014 the untrusted and privileged Lambdas have no IAM read access to the PluginSecret table. Either change trust_level to "trusted" or remove settings.secret.`
+      );
+    }
+    if (p.capabilities && !p.capabilities.includes("secretSettings")) {
+      console.warn(
+        `[ampless] Plugin "${p.name}": settings.secret is declared but "secretSettings" is not in capabilities. Add "secretSettings" to capabilities so admin UI and future capability gates can see the declaration.`
+      );
+    }
+  }
   return p;
 }
 

package/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,122 @@ stored 値 (validated)
 
 ---
 
+## 9a. Secret settings: `ctx.secret<T>(key)` (Phase 6a)
+
+Secret settings を使うと、trusted プラグインが認証情報 (Webhook 署名 secret・SMTP パスワード・外部 API トークン等) を admin UI 経由で保存・ローテーションできます。**公開サイトやブラウザ側コードに値が流れることはありません**。
+
+### なぜ `settings.public` と API が違うのか
+
+`settings.public` の値は公開 runtime に流れる設計です。`public/site-settings.json` にミラーされ、`ctx.setting()` で sync render surface から読めます。analytics の measurementId などには適切ですが、Webhook 署名 secret には絶対に使えません。
+
+`settings.secret` はストレージモデルが構造的に異なります:
+
+- KvStore とは **別テーブル** の `PluginSecret` DynamoDB model に保存。
+- admin/editor グループは **書き込み・削除のみ可**。AppSync が `getPluginSecret` / `listPluginSecrets` を生成しない（read 権限がない）。
+- trusted-processor Lambda IAM role だけが DDB `GetItem` で読み取れる。
+- S3 mirror 経路に絶対に流れない（mirror は KvStore のみを query する）。
+- 公開 render surface (`publicHead` など) からは読めない。
+
+### 要件
+
+`settings.secret` には 2 つの要件があります:
+
+1. `trust_level: 'trusted'` — untrusted Lambda には PluginSecret table への DDB read 権限がない。他の trust level で宣言すると `definePlugin()` 時に throw する。
+2. `'secretSettings'` を `capabilities` に含める — admin UI や将来の allow-list から capability を参照できるようにするため必須。省略すると console.warn（`'schema'` vs `publicBodyForPost` の不整合パターンと同じ）。
+
+### secret フィールドの宣言
+
+```ts
+import { definePlugin } from 'ampless'
+
+export default function webhookPlugin(opts?: { signingSecret?: string }) {
+  // constructor から渡された secret は closure-private な fallback として保持。
+  // manifest にも 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,
+          // `default` は型レベルで除外されている。closure-private fallback を使うこと。
+        },
+      ],
+    },
+    hooks: {
+      async 'content.published'(event, ctx) {
+        // ctx.secret() は PluginSecret DDB table から読む。
+        // admin が未保存なら undefined を返す。
+        const storedSecret = await ctx.secret<string>('signingSecret')
+
+        // closure-private fallback: admin が未保存の場合 constructor 引数を使う。
+        // これで既存サイトとの後方互換を維持できる。
+        const secret = storedSecret ?? constructorSecret
+        if (!secret) return
+
+        // ... secret で署名して POST
+      },
+    },
+  })
+}
+```
+
+### 重要: secret フィールドに `default` を書かない
+
+`PluginSecretField` 型は `Omit<PluginTextField, 'default'> | Omit<PluginTextareaField, 'default'>` として定義されており、**`default` プロパティは型レベルで除去**されています。追加しようとすると TypeScript がエラーを出します。
+
+理由: `default` は admin UI のフォーム props (ブラウザに送出される)、静的 manifest の cross-check、JS bundle など複数の経路で漏洩します。認証情報に使えない設計です。
+
+fallback 値がある場合は、プラグイン factory 関数の closure-private 変数として保持してください:
+
+```ts
+// ✓ 正解 — closure-private、manifest に出さない
+const constructorSecret = opts?.signingSecret
+
+// ✗ 誤り — TypeScript エラー、さらに browser にも漏れる
+settings: {
+  secret: [{
+    type: 'text',
+    key: 'signingSecret',
+    label: 'Secret',
+    default: opts?.signingSecret, // ← TS compile error
+  }],
+}
+```
+
+### secret の読み出し: `ctx.secret<T>(key)`
+
+`ctx.secret<T>(key)` は trusted hook handler 内でのみ利用できます (`processor-trusted.ts` が注入)。シグネチャ:
+
+```ts
+ctx.secret<T = string>(key: string): Promise<T | undefined>
+```
+
+- admin が未保存なら `undefined` を返す。
+- `T` は convenience cast (ctx.setting と同じ)。値は常に string として保存される。
+- 結果は per-invocation キャッシュされる。同 batch 内で同キーを 2 回呼んでも DDB 呼び出しは 1 回。
+- cache key は namespace 化される: `${instanceId ?? name}:${fieldKey}`。異なる plugin instance が同名フィールドを持っても混線しない。
+
+### admin UI
+
+`settings.secret` を宣言すると、admin plugin settings ページの public フィールドの下に **Secret settings** セクションが表示されます。各フィールド:
+
+- **未保存**: 通常テキスト入力 + Save ボタン。
+- **保存済み**: マスク表示 `••••••••` + Replace + Clear ボタン。値は絶対に取得・表示されない。
+- **編集中**: Replace クリック後 — 新値入力 + Save + Cancel。
+
+admin は再デプロイなしにいつでも secret をローテーションできます。保存後 ~5〜10 秒以内に次の trusted Lambda 実行から新値が使われます。
+
+---
+
 ## 10. ウォークスルー: GA4 を Phase 1 から Phase 2 に移行する
 
 Phase 1 の GA4 プラグインは measurement ID を constructor 引数で受けていました。Phase 2 では後方互換のためにその引数を残しつつ、値は `ctx.setting()` 経由で読みます。

package/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,193 @@ 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) {
+        // ctx.secret() reads from PluginSecret DDB table.
+        // Returns undefined when no value has been saved by admin yet.
+        const storedSecret = await ctx.secret<string>('signingSecret')
+
+        // Closure-private fallback: use the constructor argument when
+        // the admin has not saved a value yet. This preserves backward
+        // compatibility with sites that pass the secret at install time.
+        const secret = storedSecret ?? constructorSecret
+        if (!secret) return // no secret → skip signing
+
+        // ... 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** and TypeScript will error
+if you try to add one.
+
+This is intentional: `default` values propagate into admin UI form
+props (visible in the browser), static manifests cross-checked by
+the runtime, and JS bundles. For a credential, these are all leak
+paths.
+
+If you have a fallback value (e.g. the constructor argument), keep
+it as a **closure-private variable** inside the plugin factory
+function — never in the manifest:
+
+```ts
+// ✓ correct — closure-private, never in the manifest
+const constructorSecret = opts?.signingSecret
+
+// ✗ wrong — TypeScript error, would also leak to browser
+settings: {
+  secret: [{
+    type: 'text',
+    key: 'signingSecret',
+    label: 'Secret',
+    default: opts?.signingSecret, // ← TS compile error
+  }],
+}
+```
+
+### Reading secrets: `ctx.secret<T>(key)`
+
+`ctx.secret<T>(key)` is only available in trusted hook handlers
+(injected by `processor-trusted.ts`). The signature is:
+
+```ts
+ctx.secret<T = string>(key: string): Promise<T | undefined>
+```
+
+- Returns `undefined` when no value has been saved by admin yet.
+- The generic `T` is a convenience cast (same as `ctx.setting<T>()`).
+  Values are always stored as strings; `T` defaults to `string`.
+- Results are per-invocation cached. Calling `ctx.secret('key')`
+  twice in the same hook batch costs one DDB round-trip.
+- Cache keys are namespaced: `${instanceId ?? name}:${fieldKey}`.
+  Two plugin instances both declaring `'signingSecret'` never get
+  each other's values.
+
+### Admin UI
+
+When `settings.secret` is declared, the admin plugin settings page
+renders a **Secret settings** section below the public fields.
+Each secret field shows:
+
+- **Unset**: a plain text input + Save button.
+- **Stored**: a masked placeholder `••••••••` + Replace + Clear
+  buttons. The actual value is never fetched or displayed.
+- **Editing**: after clicking Replace — new text input + Save + Cancel.
+
+Admins can rotate a secret at any time without redeploying. The
+change takes effect on the next trusted-Lambda invocation (within
+~5–10 seconds of saving).
+
+### Testing hooks that use `ctx.secret`
+
+Mock `ctx.secret` alongside the other context methods:
+
+```ts
+import { describe, it, expect, vi } from 'vitest'
+import webhookPlugin from './index.js'
+import type { TrustedPluginRuntimeContext } from 'ampless'
+
+function makeCtx(secrets: Record<string, string> = {}): TrustedPluginRuntimeContext {
+  return {
+    site: { name: 'Test', url: 'https://example.com' },
+    listPublishedPosts: vi.fn().mockResolvedValue([]),
+    writePublicAsset: vi.fn().mockResolvedValue(''),
+    secret: vi.fn().mockImplementation(async (key: string) => secrets[key]),
+  }
+}
+
+describe('webhookPlugin signing', () => {
+  it('uses admin-stored secret when available', async () => {
+    const plugin = webhookPlugin()
+    const ctx = makeCtx({ signingSecret: 'stored-secret' })
+    await plugin.hooks?.['content.published']?.({ type: 'content.published', payload: {} as never }, ctx)
+    // assert that the request was signed with 'stored-secret'
+  })
+
+  it('falls back to constructor secret when admin has not saved one', async () => {
+    const plugin = webhookPlugin({ signingSecret: 'fallback-secret' })
+    const ctx = makeCtx({}) // no stored secret
+    await plugin.hooks?.['content.published']?.({ type: 'content.published', payload: {} as never }, ctx)
+    // assert that the request was signed with 'fallback-secret'
+  })
+})
+```
+
+---
+
 ## 10. Walk-through: migrating GA4 from Phase 1 to Phase 2
 
 The Phase 1 GA4 plugin took the measurement ID through a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.28",
+  "version": "1.0.0-alpha.29",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",