ampless 1.0.0-alpha.27 → 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' | '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.
  *
@@ -449,6 +452,29 @@ type PublicPostBodyDescriptor = Extract<PublicHeadDescriptor, {
      *  whose scriptType is not 'application/ld+json'. */
     scriptType: 'application/ld+json';
 };
+/**
+ * Slot positions for `publicHtmlForPost` descriptors. v1 ships two
+ * fixed slots; additional slots (beforeTitle / sidebar / etc) are
+ * deferred until dogfood reveals the need.
+ */
+type PublicPostHtmlPosition = 'beforeContent' | 'afterContent';
+/**
+ * Per-post visible HTML descriptor returned by `publicHtmlForPost`.
+ * The runtime sanitizes `body` with `sanitize-html` under a strict
+ * allowlist before rendering; see the plugin-author guide for how
+ * trusted plugins compose with the public surface.
+ *
+ * `id` is a plugin-local short identifier (e.g. `'display'`). The
+ * runtime resolves it to `${instanceId ?? name}:${id}` when building
+ * the React wrapper key — plugin authors do not embed their own
+ * namespace in `id`.
+ */
+interface PublicPostHtmlDescriptor {
+    type: 'html';
+    id: string;
+    body: string;
+    position: PublicPostHtmlPosition;
+}
 /**
  * Metadata-like object that maps cleanly onto Next.js `Metadata`. We keep
  * the shape framework-agnostic so the core type doesn't depend on Next.js.
@@ -498,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
@@ -675,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;
@@ -790,6 +873,28 @@ interface AmplessPlugin {
      * Plugins implementing this should declare the `schema` capability.
      */
     publicBodyForPost?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostBodyDescriptor[];
+    /**
+     * Per-post visible HTML descriptors (Phase 6d). Themes render the
+     * result by calling `ampless.publicHtmlForPost(post)` in their post
+     * template; descriptors emit inside `<body>` at the `beforeContent`
+     * or `afterContent` slot relative to the post prose. Primary use
+     * cases: reading-time badge, breadcrumb, share links, micro-format
+     * annotations.
+     *
+     * Each descriptor's `body` is sanitized by the runtime under a
+     * strict `sanitize-html` allowlist before rendering — plugin authors
+     * may NOT call `dangerouslySetInnerHTML` themselves. The runtime
+     * wraps each surviving entry in a keyed `<div>` with the sanitized
+     * HTML.
+     *
+     * Plugin-local `id` (e.g. `'display'`) is namespace-resolved to
+     * `${instanceId ?? name}:${id}` by the runtime. Plugin authors do
+     * not embed their own namespace in `id`.
+     *
+     * Plugins implementing this should declare the `'publicHtmlForPost'`
+     * capability.
+     */
+    publicHtmlForPost?(post: Post, ctx: PluginPublicRenderContext): readonly PublicPostHtmlDescriptor[];
     /**
      * Dynamic OG image renderer. The dispatcher route (e.g.
      * `app/og/[slug]/route.ts`) reads this and feeds the element into
@@ -1337,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 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

@@ -28,6 +28,7 @@ ampless はテーマとプラグインの両方を提供します。用途に合
 | 信頼できる副作用（S3 書き込み・外部 API 送信） | | ✓ (`writePublicAsset` + `trusted`) |
 | テーマに依存しない `<head>` / `<body>` 注入（アナリティクス・同意バナー） | | ✓ (`publicHead` / `publicBodyEnd`) |
 | 投稿単位の機械可読メタデータ（JSON-LD 等） | | ✓ (`schema` via `publicBodyForPost`) |
+| 投稿本文の周囲の可視 HTML（reading-time、breadcrumb、share など） | | ✓ (`publicHtmlForPost`) |
 | 複数の ampless サイトで共有したいコード | | ✓ (npm パッケージとして公開) |
 
 判断の目安:
@@ -67,6 +68,7 @@ ampless プラグインは `AmplessPlugin` オブジェクトを返す TypeScrip
 | `publicHead(ctx)` | root layout の `<head>` | 同期 (async layout から呼ばれる) | 1 |
 | `publicBodyEnd(ctx)` | root layout の `<body>` 末尾 | 同期 | 1 |
 | `publicBodyForPost(post, ctx)` | テーマの post ページテンプレート（投稿単位） | 同期 | 4 |
+| `publicHtmlForPost(post, ctx)` | テーマの post ページテンプレート（投稿単位、可視 HTML） | 同期 | 6d |
 | `ogImage` | `/og/[slug]` ルート | リクエスト時、公開 Lambda 内 | 既存 |
 | `hooks` | trust_level に応じた processor Lambda | 非同期、SQS イベントで起動 | 既存 |
 | `settings.public` | `/admin/plugins` フォーム | 宣言的なマニフェスト | 2 |
@@ -86,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 を置かないこと
 
 ---
@@ -181,6 +183,7 @@ interface AmplessPlugin {
   publicHead?(ctx): readonly PublicHeadDescriptor[]
   publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
   publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
+  publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[]
   ogImage?: OgImageConfig
   settings?: { public?: readonly PluginSettingField[] }
 }
@@ -309,6 +312,7 @@ SSR がデッドラインなしでブロックします。ネットワーク呼
 | `publicHead(ctx)` | `PublicHeadDescriptor[]` | 解析ローダー、フォント、jsonld、hreflang |
 | `publicBodyEnd(ctx)` | `PublicBodyDescriptor[]` | GTM no-script フレーム、チャットウィジェット、末尾スニペット |
 | `publicBodyForPost(post, ctx)` | `PublicPostBodyDescriptor[]` | 投稿単位の body 注入 — JSON-LD 構造化データ。テーマの post ページテンプレートが render する |
+| `publicHtmlForPost(post, ctx)` | `PublicPostHtmlDescriptor[]` | 投稿単位の可視 HTML を `beforeContent` / `afterContent` に注入 — reading-time バッジ、breadcrumb、share リンク等。body は runtime が `sanitize-html` の厳格 allowlist で sanitize |
 
 `ctx` オブジェクトの中身:
 
@@ -402,6 +406,21 @@ TypeScript としてサイトと同一の Node プロセスで動きます。des
 
 `meta` / `link` を除いている理由：投稿単位のメタデータは Next.js `generateMetadata()` 経由の `metadata()` サーフェスが担い、フレームワークの deduplication・streaming と統合されている。`publicBodyForPost` は `generateMetadata` が生成できない構造化データ（`<script type="application/ld+json">`）のためだけに存在する。
 
+### `PublicPostHtmlDescriptor`（Phase 6d）
+
+`publicHtmlForPost` は `PublicPostHtmlDescriptor[]` を返します:
+
+```ts
+{
+  type: 'html',
+  id: 'display',                  // plugin-local 短識別子（≤ 64 文字、制御文字不可）
+  position: 'beforeContent' | 'afterContent',
+  body: '<p class="reading-time">約 3 分で読めます</p>',
+}
+```
+
+runtime は `body` を `sanitize-html` の厳格 allowlist で sanitize し（詳しい allowlist と drop 対象は上の `publicHtmlForPost` 例を参照）、結果を `<div data-ampless-plugin="${namespace}" data-ampless-position="${position}">` で wrap します。テーマは `pages/post.tsx` で `{html.beforeContent}` / `{html.afterContent}` を embed するだけで、plugin の出力に対して `dangerouslySetInnerHTML` を書きません。
+
 ### JSON-LD 自動 escape
 
 `scriptType === 'application/ld+json'` のとき、runtime は描画前に **`body` 文字列を自動 escape** する — `<` → `<`、`>` → `>`、`&` → `&`、U+2028 → ` `、U+2029 → ` `。この処理は `inlineScript` を受け付ける 3 つのサーフェス（`publicHead` / `publicBodyEnd` / `publicBodyForPost`）すべてで行われる。プラグイン作者は生の JSON 文字列を返せばよく、自前で escape しなくてよい。
@@ -470,6 +489,60 @@ export default function schemaJsonldPlugin() {
 
 テーマの `pages/post.tsx` が `ampless.publicBodyForPost(post)` を呼び、返された descriptor を描画します。runtime は自動 escape した body を持つ `<script type="application/ld+json">` 要素をページに挿入します。
 
+### `publicHtmlForPost` 例（Phase 6d）
+
+**可視 HTML** を post の周囲に出したいとき（reading-time バッジ、breadcrumb、share リンク、micro-format 注釈など）は `publicHtmlForPost` を使います。runtime が body を sanitize したうえで `beforeContent` / `afterContent` スロットに embed するので、テーマ側で `dangerouslySetInnerHTML` を書く必要はありません。
+
+```typescript
+import { definePlugin } from 'ampless'
+
+export default function readingTimePlugin() {
+  return definePlugin({
+    name: 'reading-time',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHtmlForPost'],
+    publicHtmlForPost(post, _ctx) {
+      const words = countWords(post)
+      const minutes = Math.max(1, Math.round(words / 200))
+      return [{
+        type: 'html',
+        id: 'display',
+        position: 'beforeContent',
+        body: `<p class="reading-time" data-words="${words}" data-minutes="${minutes}">約 ${minutes} 分で読めます</p>`,
+      }]
+    },
+  })
+}
+```
+
+テーマの `pages/post.tsx` は `const html = await ampless.publicHtmlForPost(post)` を 1 回呼び、スロットを embed します:
+
+```tsx
+{postBody}            {/* publicBodyForPost — JSON-LD */}
+{html.beforeContent}  {/* publicHtmlForPost — beforeContent スロット */}
+<div className="prose" dangerouslySetInnerHTML={{ __html: renderBody(post) }} />
+{html.afterContent}   {/* publicHtmlForPost — afterContent スロット */}
+```
+
+**スロット位置**（v1）: `'beforeContent'` / `'afterContent'` の 2 つ。
+
+**Sanitizer（厳格、trust level に関わらず同一）:**
+
+- 許可タグ: `p` · `span` · `strong` · `em` · `a` · `code` · `br` · `ul` · `ol` · `li`
+- 許可グローバル属性: `class` · `data-words` · `data-minutes` · `data-ampless-*`
+- 許可 `<a>` 属性: `href` · `rel` · `target`。`target="_blank"` のとき sanitizer が `rel="noopener noreferrer"` を自動付与
+- `href` で許可するスキーム: `http` / `https`。相対 URL (`./path` / `../path` / `/path` / `#anchor`) は素通り。`javascript:` / `data:` / `mailto:` / `tel:` / `vbscript:` は drop
+- drop されるタグ・属性: `<img>` · `<iframe>` · `<video>` · `<audio>` · `<object>` · `<embed>` · `<form>` · `<style>` · インライン `style` · 全 event handler (`on*`)
+
+allowlist 外のタグが必要になった場合は issue を立ててください。allowlist は設計上拡張するものであって、escape hatch ではありません。
+
+**`id` は plugin-local。** 短い識別子（例: `'display'`）を使います。runtime が React `key` および wrapper `<div>` の `data-ampless-plugin` / `data-ampless-position` 属性を組むときに `${instanceId ?? name}:${id}` で resolve するので、plugin 作者が自前で namespace を埋め込む必要はありません。validator は `id` が空、制御文字を含む、64 文字超のいずれかなら descriptor を drop します。
+
+**dedupe は position ごと。** 1 つの plugin instance が `beforeContent` と `afterContent` の両方に同じ `id` を返すのは OK（dedupe スコープが独立）。同じ position に同じ `id` を 2 回返すと最初の 1 件を残して 2 件目を warn 付きで drop します。
+
+**複数 instance。** distinct な `instanceId` を持つ 2 つの `reading-time` instance（例: `reading-time-en` / `reading-time-jp`）は、同じ position に `id: 'display'` を返しても両方残ります（namespace が違うため）。
+
 ### クライアントサイドの DOM 操作はしない
 
 `publicHead` または `publicBodyEnd` から返したインラインスクリプトは、React がページを hydrate する前、HTML のパース中に実行されます。**React が管理するサブツリー内の見える DOM を操作してはいけません** — hydration が走ると React は仮想 DOM と合わないツリーを検出し、`Hydration failed because the server rendered HTML didn't match the client` エラーを投げてサブツリーをゼロから再生成します。挿入したノードは消えてしまいます。
@@ -488,7 +561,7 @@ React 19 はさらに、クライアントコンポーネントのレンダー
 - テーマが描画した要素のクラス / 属性 / テキストコンテンツの変更
 - クライアントサイドで `#post-body` のような要素を読み取って投稿単位の HTML を挿入する — 現在 `publicHead`-for-post に相当するサーフェスはなく、サーバーレンダリング済みのサブツリーをクライアントサイドで書き換えると hydration と競合します
 
-投稿単位の見える出力には、`publicBodyForPost` 経由で JSON-LD を返す（§6 の `PublicPostBodyDescriptor` 参照）か、テーマ自身のテンプレートを使ってください。サーバーサイドでの投稿単位 HTML 注入はロードマップに載っています。
+投稿単位の見える出力には `publicHtmlForPost` を使ってください（Phase 6d — 上の例と §6 の `PublicPostHtmlDescriptor` 参照）。runtime が post 本文の周囲の固定スロットにサーバーサイド HTML を出すので、hydration と競合しません。
 
 ---
 
@@ -629,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

@@ -35,6 +35,7 @@ your code where future-you (and other site authors) will look for it.
 | Trusted side effects (S3 writes, external API push) | | ✓ (`writePublicAsset` + `trusted`) |
 | Theme-independent `<head>` / `<body>` injection (analytics, consent) | | ✓ (`publicHead` / `publicBodyEnd`) |
 | Per-post machine-readable metadata (JSON-LD, etc.) | | ✓ (`schema` via `publicBodyForPost`) |
+| Per-post visible HTML around the body (reading-time, breadcrumb, share) | | ✓ (`publicHtmlForPost`) |
 | Code you want to share across multiple ampless sites | | ✓ (publish as npm package) |
 
 Rule of thumb:
@@ -88,9 +89,11 @@ surfaces:
 | `publicHead(ctx)` | root layout `<head>` | sync (called from async layout) | 1 |
 | `publicBodyEnd(ctx)` | root layout end of `<body>` | sync | 1 |
 | `publicBodyForPost(post, ctx)` | theme post page template (per-post) | sync | 4 |
+| `publicHtmlForPost(post, ctx)` | theme post page template (per-post, visible HTML) | sync | 6d |
 | `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:
@@ -109,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.
 
 ---
 
@@ -210,6 +211,7 @@ interface AmplessPlugin {
   publicHead?(ctx): readonly PublicHeadDescriptor[]
   publicBodyEnd?(ctx): readonly PublicBodyDescriptor[]
   publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
+  publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[]
   ogImage?: OgImageConfig
   settings?: { public?: readonly PluginSettingField[] }
 }
@@ -380,6 +382,7 @@ elevated AWS access.
 | `publicHead(ctx)` | `PublicHeadDescriptor[]` | Analytics loader, fonts, jsonld, hreflang |
 | `publicBodyEnd(ctx)` | `PublicBodyDescriptor[]` | GTM no-script frame, chat widgets, tail snippets |
 | `publicBodyForPost(post, ctx)` | `PublicPostBodyDescriptor[]` | Per-post body injection — JSON-LD structured data; rendered by the theme's post page template |
+| `publicHtmlForPost(post, ctx)` | `PublicPostHtmlDescriptor[]` | Per-post visible HTML at `beforeContent` / `afterContent` — reading-time badge, breadcrumb, share links. Bodies are sanitized by the runtime under a strict `sanitize-html` allowlist |
 
 The `ctx` object carries:
 
@@ -483,6 +486,27 @@ behaviour. `publicBodyForPost` exists solely for the structured data
 use-case (`<script type="application/ld+json">`) that `generateMetadata`
 cannot produce.
 
+### `PublicPostHtmlDescriptor` (Phase 6d)
+
+`publicHtmlForPost` returns `PublicPostHtmlDescriptor[]`:
+
+```ts
+{
+  type: 'html',
+  id: 'display',                  // plugin-local short identifier (≤ 64 chars, no control chars)
+  position: 'beforeContent' | 'afterContent',
+  body: '<p class="reading-time">~3 min read</p>',
+}
+```
+
+The runtime sanitizes `body` with `sanitize-html` under a strict
+allowlist (see the `publicHtmlForPost` example above for the full
+allowlist + dropped-tag list) and wraps the result in
+`<div data-ampless-plugin="${namespace}" data-ampless-position="${position}">`.
+Themes embed `{html.beforeContent}` / `{html.afterContent}` in
+`pages/post.tsx`; they never call `dangerouslySetInnerHTML` on plugin
+output themselves.
+
 ### JSON-LD auto-escape
 
 When `scriptType === 'application/ld+json'`, the runtime **automatically
@@ -574,6 +598,80 @@ and renders the returned descriptors. The runtime inserts a
 `<script type="application/ld+json">` element with the auto-escaped
 body into the page.
 
+### `publicHtmlForPost` example (Phase 6d)
+
+Use `publicHtmlForPost` when you need to render **visible HTML**
+around a post — reading-time badge, breadcrumb, share links,
+micro-format annotations, etc. The runtime sanitizes the body before
+rendering and embeds the result at the `beforeContent` or
+`afterContent` slot, so themes never call `dangerouslySetInnerHTML`
+on plugin output.
+
+```typescript
+import { definePlugin } from 'ampless'
+
+export default function readingTimePlugin() {
+  return definePlugin({
+    name: 'reading-time',
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    capabilities: ['publicHtmlForPost'],
+    publicHtmlForPost(post, _ctx) {
+      const words = countWords(post)
+      const minutes = Math.max(1, Math.round(words / 200))
+      return [{
+        type: 'html',
+        id: 'display',
+        position: 'beforeContent',
+        body: `<p class="reading-time" data-words="${words}" data-minutes="${minutes}">~${minutes} min read</p>`,
+      }]
+    },
+  })
+}
+```
+
+The theme's `pages/post.tsx` calls
+`const html = await ampless.publicHtmlForPost(post)` once and embeds
+the slots:
+
+```tsx
+{postBody}            {/* publicBodyForPost — JSON-LD */}
+{html.beforeContent}  {/* publicHtmlForPost — beforeContent slot */}
+<div className="prose" dangerouslySetInnerHTML={{ __html: renderBody(post) }} />
+{html.afterContent}   {/* publicHtmlForPost — afterContent slot */}
+```
+
+**Slot positions** (v1): `'beforeContent'` and `'afterContent'`.
+
+**Sanitizer (strict, identical across trust levels):**
+
+- Allowed tags: `p` · `span` · `strong` · `em` · `a` · `code` · `br` · `ul` · `ol` · `li`
+- Allowed global attributes: `class` · `data-words` · `data-minutes` · `data-ampless-*`
+- Allowed `<a>` attributes: `href` · `rel` · `target`. `target="_blank"` triggers auto-injection of `rel="noopener noreferrer"`.
+- Allowed URL schemes on `href`: `http` / `https`. Relative URLs (`./path`, `../path`, `/path`, `#anchor`) pass through. `javascript:` / `data:` / `mailto:` / `tel:` / `vbscript:` are dropped.
+- Dropped tags / attributes: `<img>` · `<iframe>` · `<video>` · `<audio>` · `<object>` · `<embed>` · `<form>` · `<style>` · inline `style` · all event handlers (`on*`).
+
+If you need a tag outside this list, open an issue — the allowlist
+expands by design, not by escape hatch.
+
+**`id` is plugin-local.** Use a short identifier (e.g. `'display'`).
+The runtime resolves it to `${instanceId ?? name}:${id}` when building
+the React `key` and the wrapper `<div>`'s `data-ampless-plugin` /
+`data-ampless-position` attributes. Do not embed your own namespace
+in `id`. The validator drops descriptors whose `id` is empty,
+contains control characters, or exceeds 64 characters.
+
+**Dedupe is per-position.** Returning the same `id` to both
+`beforeContent` and `afterContent` from a single plugin instance is
+fine — they live in independent dedupe scopes. Returning the same
+`id` twice to the same position keeps only the first occurrence and
+warns.
+
+**Multiple instances.** Two `reading-time` plugin instances with
+distinct `instanceId` (e.g. `reading-time-en` / `reading-time-jp`)
+can both emit `id: 'display'` to the same position; the runtime
+keeps both because the namespaces differ.
+
 ### Client-side DOM mutation: don't
 
 Inline scripts you return from `publicHead` or `publicBodyEnd` execute
@@ -612,10 +710,10 @@ something like `document.body.append(myNewElement)` may not even fire.
   any client-side rewrite of a server-rendered subtree races against
   hydration
 
-For visible per-post output, return JSON-LD via `publicBodyForPost`
-(see §6's `PublicPostBodyDescriptor`) or stick with the theme's own
-templates. A future ampless capability for server-side per-post HTML
-injection is on the roadmap.
+For visible per-post output, use `publicHtmlForPost` (Phase 6d — see
+the example above and §6's `PublicPostHtmlDescriptor`). The runtime
+emits server-side HTML at fixed slots around the post body, so
+nothing races against hydration.
 
 ---
 
@@ -807,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.27",
+  "version": "1.0.0-alpha.29",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",