create-ampless 1.0.0-alpha.108 → 1.0.0-alpha.111

package/dist/templates/_shared/amplify/data/get-published-post.js

@@ -8,6 +8,13 @@ import { util } from '@aws-appsync/utils'
 //
 // Drafts are dropped in the response handler. If draft + published
 // somehow share a slug we prefer the published row.
+//
+// Scheduled-publish: a `published` post is visible only when its
+// publishedAt is absent (= immediate) OR <= now (= already live).
+// When publishedAt is present and in the future the post is treated as
+// "not yet live" and is hidden from the public site. This check is
+// server-authoritative: the AppSync resolver enforces it on every read
+// without relying on any client-side filtering.
 export function request(ctx) {
   const slug = ctx.args.slug
   return {
@@ -25,6 +32,11 @@ export function request(ctx) {
 export function response(ctx) {
   if (ctx.error) util.error(ctx.error.message, ctx.error.type)
   const items = ctx.result.items ?? []
-  const published = items.find((i) => i.status === 'published')
+  const now = util.time.nowISO8601()
+  // Hide a published post only when publishedAt exists AND is in the future
+  // (scheduled). Missing publishedAt = immediate publish.
+  const published = items.find(
+    (i) => i.status === 'published' && (!i.publishedAt || i.publishedAt <= now)
+  )
   return published ?? null
 }

package/dist/templates/_shared/amplify/data/list-posts-by-tag.js

@@ -9,14 +9,26 @@ import { util } from '@aws-appsync/utils'
 // the tag partition condition. Drafts never appear here because the
 // admin client only writes PostTag rows for posts whose status is
 // 'published'.
+//
+// Scheduled-publish: the SK is a composite of `${publishedAt}#${postId}`.
+// ISO 8601 timestamps are fixed-width to millisecond precision, so lexical
+// order == chronological order. We add an upper-bound SK condition
+// `<= now + '#' + '￿'` to exclude PostTag rows whose publishedAt is in
+// the future. U+FFFF sorts above every character that can appear in a real
+// postId, so `now#￿` is strictly greater than `now#<any-postId>`:
+// every postId suffix sharing the current-millisecond ISO prefix is
+// included, while any SK whose timestamp prefix is later is excluded.
+// (Written as an escape so this source file stays ASCII.)
 export function request(ctx) {
   const { tag, limit, nextToken } = ctx.args
+  const now = util.time.nowISO8601()
+  const upper = now + '#￿'
   return {
     operation: 'Query',
     query: {
-      expression: '#tag = :tag',
-      expressionNames: { '#tag': 'tag' },
-      expressionValues: util.dynamodb.toMapValues({ ':tag': tag }),
+      expression: '#tag = :tag AND #pap <= :upper',
+      expressionNames: { '#tag': 'tag', '#pap': 'publishedAtPostId' },
+      expressionValues: util.dynamodb.toMapValues({ ':tag': tag, ':upper': upper }),
     },
     scanIndexForward: false, // newest first (SK descends)
     limit: limit ?? 20,

package/dist/templates/_shared/amplify/data/list-published-posts.js

@@ -1,4 +1,4 @@
-import { util } from '@aws-appsync/utils'
+import { util, runtime } from '@aws-appsync/utils'
 
 // AppSync JS resolver: list published posts, newest first.
 //
@@ -8,29 +8,40 @@ import { util } from '@aws-appsync/utils'
 // so a single Query reads only the `published` partition. Drafts never
 // appear because the PK condition pins status='published'.
 //
+// Scheduled-publish: the upper bound of the SK range is always clamped
+// to `now`. This ensures future-dated published posts (scheduled but not
+// yet live) never appear in public listings. The upper bound is the lesser
+// of `now` and any caller-supplied `to` argument.
+//
+// Reverse-range guard: if `from` is supplied and ends up > upper (e.g.
+// the caller asks for a range entirely in the future), we return an empty
+// result early via `runtime.earlyReturn` instead of issuing an inverted
+// BETWEEN to DynamoDB (which DynamoDB rejects with a ValidationException).
+//
 // Date-range filtering (`from`, `to`) is pushed into the SK condition,
 // so DynamoDB only reads the matching range. `nextToken` paginates
 // without re-issuing a fresh query.
 export function request(ctx) {
   const { from, to, limit, nextToken } = ctx.args
+  const now = util.time.nowISO8601()
+  // Always clamp the upper bound to now so future-dated posts are excluded.
+  const upper = to && to < now ? to : now
+
+  // If `from` is later than `upper` the range is empty — skip the query
+  // rather than letting DynamoDB see an inverted BETWEEN / >= condition.
+  if (from && from > upper) {
+    return runtime.earlyReturn({ items: [], nextToken: null })
+  }
 
   let keyExpression = '#status = :status'
-  const expressionNames = { '#status': 'status' }
-  const expressionValueMap = { ':status': 'published' }
+  const expressionNames = { '#status': 'status', '#publishedAt': 'publishedAt' }
+  const expressionValueMap = { ':status': 'published', ':upper': upper }
 
-  if (from && to) {
-    keyExpression += ' AND #publishedAt BETWEEN :from AND :to'
-    expressionNames['#publishedAt'] = 'publishedAt'
-    expressionValueMap[':from'] = from
-    expressionValueMap[':to'] = to
-  } else if (from) {
-    keyExpression += ' AND #publishedAt >= :from'
-    expressionNames['#publishedAt'] = 'publishedAt'
+  if (from) {
+    keyExpression += ' AND #publishedAt BETWEEN :from AND :upper'
     expressionValueMap[':from'] = from
-  } else if (to) {
-    keyExpression += ' AND #publishedAt <= :to'
-    expressionNames['#publishedAt'] = 'publishedAt'
-    expressionValueMap[':to'] = to
+  } else {
+    keyExpression += ' AND #publishedAt <= :upper'
   }
 
   return {

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

@@ -441,7 +441,7 @@ runtime は `body` を `sanitize-html` の厳格 allowlist で sanitize し（
 - **`attrs` allowlist**: `data-*`、`crossorigin`、`referrerpolicy`、`integrity`、`fetchpriority`、`loading`、`sandbox`、`allow`、`allowfullscreen`。それ以外は dev warn 付きで drop
 - **`inlineScript.id` は必須**。無いとプラグイン同士が似たスニペットを emit したときに dedup できず、dev warning も index 番号を指すだけで原因プラグインを特定できません
 - **id 重複**: 最後の出現が勝ち。dev warning でどの key が重複したか表示されます
-- **CSP nonce**: Phase 1 では伝搬しません。`nonce` attr は型上は宣言してありますが今のところ無視されます
+- **CSP nonce**: `inlineScript.nonce` と `script.nonce` は型として受け入れられます（`'auto'` は将来の runtime スタンプ用 sentinel。文字列リテラルも可）。Phase 1 予約: runtime はフィールドを受け入れますが描画要素には伝搬しません。詳細は下記の [CSP nonce（Phase 1 予約）](#csp-nonce-phase-1-) を参照。
 - **strategy**: `afterInteractive` は外部 script に `async` を付ける。`lazyOnload` は `defer`。明示的な `async` / `defer` が常に勝ち。`beforeInteractive` は非対応
 
 ### runtime が描画する形
@@ -565,9 +565,124 @@ React 19 はさらに、クライアントコンポーネントのレンダー
 
 ---
 
+## 6a. 予約投稿とコンテンツイベント
+
+ampless は**予約投稿**をサポートしています。`status: 'published'` かつ `publishedAt` が未来の投稿は、その時刻まで公開読み出しから隠されます。`publishedAt` を過ぎると、サイトの自然なキャッシュ有効期限（デフォルト ≤ ~5 分）の範囲内で公開されます — 秒単位の正確なトリガーはありません。
+
+### イベントは保存時に発火する（`publishedAt` のタイミングではない）
+
+`content.published`（および `content.updated`）は DynamoDB Streams 経由で**投稿が保存されたとき**に emit されます。`publishedAt` が到来したときではありません。つまり、`content.published` に反応するプラグインは、投稿が未来日時の場合、**その投稿が公開される前**に実行されます。
+
+現在の投稿一覧から公開アセットを再構築する trusted プラグイン（RSS、sitemap、JSON インデックスなど）にとってはこれは問題ありません — `listPublishedPosts()` が未来日時の投稿をすでに除外しているため、再生成されたアセットはその投稿が公開されるまでリストに含まれません。
+
+一方、**外部通知プラグイン**（webhook、プッシュ通知、SNS 投稿など）には影響があります。投稿の URL が 404 を返しているまたはホームページにリダイレクトされている間に通知が配信されてしまいます。
+
+### 推奨パターン: `publishedAt` でゲートする
+
+ディスパッチの前に `event.payload.publishedAt` を確認します。投稿が未来日時の場合はスキップまたは保留します:
+
+```ts
+hooks: {
+  async 'content.published'(event, ctx) {
+    const { publishedAt } = event.payload
+
+    // 予約投稿には通知を送らない。イベントは保存時に発火するが、
+    // 投稿が公開されるのは publishedAt になってから。
+    if (publishedAt && new Date(publishedAt) > new Date()) {
+      return
+    }
+
+    // 投稿は今すぐ公開状態 — 通知しても安全。
+    await sendWebhook(event.payload, ctx)
+  },
+}
+```
+
+イベントペイロード内の `publishedAt` は UTC ISO 8601 文字列（`...Z`）です。`Date.now()` と比較する前に `new Date()` またはお好みの日付ライブラリでパースしてください。
+
+### 今後の対応
+
+`content.published` の発火を保存時ではなく `publishedAt` のタイミングに合わせる機能 — EventBridge Scheduler または DynamoDB TTL トリガー Lambda によるスケジューラーコンポーネントが必要 — は計画中の機能強化です。現リリースのスコープには含まれていません。それまでの間は上記のパターンが通知プラグインにおける推奨ガードです。
+
+オペレーター視点からの `publishedAt` セマンティクスの全体像は [`docs/scheduled-publishing.md`](https://github.com/heavymoons/ampless/blob/main/docs/scheduled-publishing.ja.md) を参照してください。
+
+---
+
+### CSP nonce（Phase 1 予約）
+
+CSP（Content Security Policy）は本番公開サイトのほぼ必須要件です。nonce 伝搬を後から追加した場合に既存プラグインが一斉に動かなくなるのを防ぐため、ampless は今のうちに API サーフェスだけ予約しておきます（Phase 1 は完全 no-op）。
+
+3 層設計:
+
+1. **`ctx.cspNonce?: string`** — `PluginPublicRenderContext` の型に予約済み。今のところ常に `undefined`。runtime はこのフィールドをまだ populate しません。middleware/SSR nonce threading は将来の CSP RFP とともに landing します。
+
+2. **`descriptor.nonce: 'auto' | string`** — `inlineScript` と `script` の両 descriptor variant の型で受け入れられます。`'auto'` は将来の runtime スタンプ用 sentinel。その他の文字列は明示的リテラル。`undefined` は `nonce` 属性を emit しない（デフォルト、非 CSP サイトと後方互換）。Phase 1: runtime は受け入れますが伝搬しません。`nonce: 'auto'` を今日宣言することは前方互換性のヒントであり、描画 HTML を変更しません。
+
+3. **`'cspReady'` capability** — name-only の declarative バッジ。将来の admin UI / サニティチェックの対象になります。Phase 1 では runtime の cross-check や enforcement は一切なし。
+
+**対応方法:**
+
+```ts
+// src/index.ts
+definePlugin({
+  name: 'my-plugin',
+  apiVersion: 1,
+  trust_level: 'untrusted',
+  capabilities: ['publicHead', 'cspReady'],
+  publicHead: () => [{
+    type: 'inlineScript',
+    id: 'my-snippet',
+    body: '...',
+    nonce: 'auto',    // 前方互換性ヒント。Phase 1 では効果なし
+  }],
+})
+```
+
+npm 公開のスタンドアロンプラグインの場合は、`package.json#amplessPlugin.capabilities` も合わせて更新してください — static manifest と factory return value が一致しない場合、runtime cross-check が警告を出します:
+
+```json
+{
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "my-plugin",
+    "trustLevel": "untrusted",
+    "capabilities": ["publicHead", "cspReady"]
+  }
+}
+```
+
+**`'cspReady'` の意味:**
+
+- サイト全体の CSP 適合は middleware / レスポンスヘッダー / runtime が制御しない他の inline コンテンツにも依存します。
+- middleware-driven nonce threading PR が landing した後は、`nonce: 'auto'` を持つ plugin-supplied script が runtime nonce スタンプの候補になります。
+- `'cspReady'` は `create-ampless plugin --capabilities` には表示されません — reserved capability であり、scaffold はアクティブな enforcement を示唆しないよう除外しています。
+
+---
+
 ## 7. 非同期イベントフック
 
-`hooks` は SQS から到着したイベントを trust_level に対応する processor Lambda が受けて実行します。runtime context (`ctx`) の中身:
+`hooks` は SQS から到着したイベントを trust_level に対応する processor Lambda が受けて実行します。
+
+### 戻り値の予約
+
+`PluginEventHandler` の戻り値型は `Promise<void | PluginHookResult>`。
+runtime は現状この戻り値を完全に無視する — 既存 plugin が
+`Promise<void>` を返す形は migration 不要で動き続ける。
+`PluginHookResult` は将来の directive (最初の用例として有力:
+`metrics?: Record<string, number>` による observability emission) のた
+めの予約で、今宣言するのは forward-compatibility のヒントとして
+の扱い。注意: rewrite / cancel 系 directive は本 widening だけで
+は有効化されない — `before:*` event の plugin 配線と payload 拡張
+が別 PR で必要。
+
+`PluginHookResult` には private な `__amplessPluginHookResult`
+marker が付いており、union が `Promise<string>` / `Promise<number>`
+等の無関係な promise を silently 受け入れないようになっている —
+plugin 作者がこの marker を明示的に設定する必要は無い。
+
+### Runtime context
+
+runtime context (`ctx`) の中身:
 
 ```ts
 interface PluginRuntimeContext {
@@ -706,14 +821,146 @@ stored 値 (validated)
 
 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.public` と API が違うのか
+
+`settings.public` の値は公開 runtime に流れる設計です。`public/site-settings.json` にミラーされ、`ctx.setting()` で sync render surface から読めます。analytics の measurementId などには適切ですが、Webhook 署名 secret には絶対に使えません。
+
+`settings.secret` はストレージモデルが構造的に異なります:
+
+- KvStore とは **別テーブル** の `PluginSecret` DynamoDB テーブルに保存。admin/editor Cognito ユーザーは AppSync 経由でこのテーブルに**直接アクセスできない** — すべての書き込みは `setPluginSecret` mutation を通じて `plugin-secret-handler` Lambda 経由で行われる。
+- 値は保存前に **AES-256-GCM 暗号化**される。admin ブラウザが plaintext を Lambda に TLS 経由で送信 → Lambda がバリデーション + `process.env.PLUGIN_SECRET_ENCRYPTION_KEY`（CDK が `amplify/secrets/encryption-key.ts` から注入）から鍵を読み取り + 暗号化 → ciphertext のみを DDB に書き込む。平文は DynamoDB に保存されず、ブラウザにも返らない。
+- **脅威モデル（Phase 6a v2.2）**:
+
+  | 脅威 | 状態 |
+  |---|---|
+  | PluginSecret テーブルを閲覧する AWS Console オペレータ | ✓ 対策済み — ciphertext のみ、DDB に鍵なし |
+  | ソースリポジトリ / デプロイアーティファクトへのアクセス | ⚠ 対策なし — 鍵は `amplify/secrets/encryption-key.ts` に存在。リポジトリを private にし、アーティファクトアクセスを制限すること |
+  | 同一 Lambda 内の悪意ある trusted plugin | ✗ 対策なし — `process.env.PLUGIN_SECRET_ENCRYPTION_KEY` はプラグインコードから読める。真の分離 = per-plugin Lambda（privileged tier, ロードマップ） |
+  | S3 mirror 漏洩 | ✓ 対策済み — PluginSecret テーブルは mirror されない |
+
+- trusted-processor Lambda が `node:crypto` で復号する。`ctx.secret<T>(key)` は平文 string を返す（ciphertext ではない）。
+- S3 mirror 経路に絶対に流れない（mirror は KvStore のみを query する）。
+- 公開 render surface (`publicHead` など) からは読めない。
+- **field manifest 検証の範囲**: admin クライアントは UX フィードバック目的で `pattern` / `maxLength` / `required` を検証するが、Lambda 側は **汎用の 10,000 文字ハードキャップと安全文字サニタイザのみ**を強制する。admin/editor が AppSync mutation を直接呼ぶと field 単位の制約は迂回できる。設計上意図したもので、admin/editor は secret 設定を許可された信頼されたオペレータと位置づけている。manifest チェックは UX ガイダンスであり、セキュリティ境界ではない。
+
+### 要件
+
+`settings.secret` には 3 つの要件があります:
+
+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` の不整合パターンと同じ）。
+3. **鍵の初回セットアップ** — プロジェクトルートで実行:
+   ```sh
+   npx create-ampless setup-encryption-key
+   ```
+   32 バイトのランダムな鍵を生成し、`amplify/secrets/encryption-key.ts` に書き込む。AWS 認証情報不要 — ローカルファイル操作のみ。
+
+   次に `amplify/backend.ts` でその定数を import し、`defineAmplessBackend({ pluginSecretEncryptionKey })` に渡す。その後デプロイ（またはサンドボックス再起動）して Lambda env var に注入する。
+
+   public リポジトリの場合は `--gitignore` を渡してバージョン管理から除外し、鍵を別途配布する。
+
+### Dual-write 整合性
+
+`setPluginSecret` と `clearPluginSecret` は各操作で **2 テーブル**に連続して書き込む: `PluginSecret`（ciphertext）と `PluginSecretIndicator`（存在タイムスタンプ）。2 回目の書き込みが失敗した場合、テーブルは以下の予測可能な状態になる:
+
+| 障害ポイント | `PluginSecret` | `PluginSecretIndicator` | `ctx.secret()` | `hasPluginSecret()` |
+|---|---|---|---|---|
+| **set**: indicator PutItem 失敗 | ciphertext 存在 | 不在 | plaintext を返す ✓ | `false`（UI: 「未保存」） |
+| **clear**: indicator DeleteItem 失敗 | 不在 | stale（古いタイムスタンプ） | `undefined` ✓ | `true`（UI: 「保存済み」） |
+
+clear パスの失敗は「安全側」: secret は発火しなくなるが、UI は一時的に「保存済み」と表示する。set パスの失敗は軽微な UI 不整合: secret は機能するが、存在インジケータはリトライが成功するまで不在となる。
+
+### 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 回ずつ。暗号化キーは Lambda env var から cold-start 時に decode される（DDB への余分な fetch は不要）。
+- キャッシュされる値は **復号済みの平文** — ciphertext ではない。2 回目の呼び出しで再復号は発生しない。
+- cache key は namespace 化される: `${instanceId ?? name}:${fieldKey}`。異なる plugin instance が同名フィールドを持っても混線しない。
+
+### admin UI
+
+`settings.secret` を宣言すると、admin plugin settings ページの public フィールドの下に **Secret settings** セクションが表示されます。各フィールド:
+
+- **未保存**: 通常テキスト入力 + Save ボタン。
+- **保存済み**: マスク表示 `••••••••` + Replace + Clear ボタン。値は絶対に取得・表示されない。
+- **編集中**: Replace クリック後 — 新値入力 + Save + Cancel。
 
-- `settings.secret` は `trust_level: 'trusted'` + `'secretSettings'` capability 必須。鍵の初回セットアップ: `npx create-ampless setup-encryption-key` を実行して `amplify/secrets/encryption-key.ts` を生成し、`defineAmplessBackend({ pluginSecretEncryptionKey })` に渡してデプロイ（AWS 認証情報不要）。
-- フィールド型は `PluginSecretField` = `Omit<PluginTextField, 'default'> | Omit<PluginTextareaField, 'default'>`。`default` は型レベルで禁止。fallback は closure-private 変数で保持。
-- admin ブラウザは AppSync mutation (`setPluginSecret`) 経由で書き込む → `plugin-secret-handler` Lambda が env var から鍵取得・AES-256-GCM 暗号化・DDB PutItem。平文は DDB に保存されずブラウザにも返らない。`ctx.secret<T>(key)` は trusted Lambda が復号した平文を返す（`process.env.PLUGIN_SECRET_ENCRYPTION_KEY` を使用; DDB に鍵は保存しない）。per-invocation でキャッシュ。
-- admin UI が「保存済み」表示 (`••••••••`) + Replace + Clear を提供。値は取得・表示されない。
-- **Dual-write 整合性**: set/clear は 2 テーブルに連続して書く。2 回目失敗時 — set パス部分失敗は「secret 機能する・indicator 不在（UI: 未保存誤表示）」; clear パス部分失敗は「secret 削除済・indicator stale（UI: 保存済み誤表示、secret は発火しない安全側）」。
-- **field manifest 検証の範囲**: admin クライアントは UX フィードバック用に `pattern` / `maxLength` / `required` を検証するが、Lambda は **汎用 10,000 文字キャップと安全文字サニタイザのみ**を強制。admin/editor が AppSync mutation を直接呼ぶと field 単位の制約は迂回可能 — admin/editor は信頼されたオペレータと扱う設計のため、manifest チェックはセキュリティ境界ではなく UX ガイダンス。
+admin は再デプロイなしにいつでも secret をローテーションできます。保存後 ~5〜10 秒以内に次の trusted Lambda 実行から新値が使われます。
 
 ---
 

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

@@ -540,8 +540,12 @@ a console warning** and never rendered.
   index numbers no one can map back to a plugin.
 - **Duplicate `id`**: the last occurrence wins. A dev warning prints
   which key was duplicated.
-- **CSP nonce**: not propagated in Phase 1. The `nonce` attr is
-  declared in the type for forward-compat but discarded today.
+- **CSP nonce**: `inlineScript.nonce` and `script.nonce` are accepted
+  by the type (`'auto'` is the sentinel for future runtime stamping;
+  any string is an explicit literal). Phase 1 reservation: the runtime
+  accepts the field but does not propagate it to the rendered element.
+  See [CSP nonce (Phase 1 reservation)](#csp-nonce-phase-1-reservation)
+  below.
 - **Strategy**: `afterInteractive` adds `async` to external scripts.
   `lazyOnload` adds `defer`. Explicit `async` / `defer` always
   wins. `beforeInteractive` is not supported.
@@ -717,10 +721,167 @@ nothing races against hydration.
 
 ---
 
+## 6a. Scheduled posts and content events
+
+ampless supports **scheduled publishing**: a post with `status:
+'published'` and a future `publishedAt` is hidden from all public
+reads until that time. Once `publishedAt` arrives, the post becomes
+visible within the site's natural cache window (≤ ~5 minutes by
+default) — there is no exact-time trigger.
+
+### Events fire at save time, not at `publishedAt`
+
+`content.published` (and `content.updated`) are emitted via DynamoDB
+Streams **when the post is saved**, not when `publishedAt` arrives.
+This means a plugin that reacts to `content.published` will run
+**before the post is publicly visible** when the post is future-dated.
+
+For trusted plugins that rebuild public assets from the current post
+list (RSS, sitemap, JSON indexes), this is harmless — `listPublishedPosts()`
+already filters out future-dated posts, so the regenerated asset
+simply omits the scheduled post until it goes live.
+
+For **outbound-notification plugins** (webhook, push notification,
+social post) the early fire matters: the notification will be
+delivered to subscribers while the post URL still returns 404 or
+redirects to the home page.
+
+### Recommended pattern: gate on `publishedAt`
+
+Check `event.payload.publishedAt` before dispatching. Skip or defer
+when the post is future-dated:
+
+```ts
+hooks: {
+  async 'content.published'(event, ctx) {
+    const { publishedAt } = event.payload
+
+    // Skip notification for future-scheduled posts. The event fires
+    // at save time, but the post won't be public until publishedAt.
+    if (publishedAt && new Date(publishedAt) > new Date()) {
+      return
+    }
+
+    // Post is live now — safe to notify.
+    await sendWebhook(event.payload, ctx)
+  },
+}
+```
+
+The `publishedAt` value in the event payload is a UTC ISO 8601 string
+(`...Z`). Parse it with `new Date()` or your preferred date library
+before comparing against `Date.now()`.
+
+### Future work
+
+Aligning event emission with the scheduled time — so `content.published`
+fires at `publishedAt` rather than at save time — is a planned
+enhancement. It requires a scheduler component (EventBridge Scheduler
+or a DynamoDB TTL-triggered Lambda) and is not yet in scope for the
+current release. Until then, the pattern above is the recommended
+guard for notification plugins.
+
+For a full description of `publishedAt` semantics from the operator's
+perspective, see [`docs/scheduled-publishing.md`](https://github.com/heavymoons/ampless/blob/main/docs/scheduled-publishing.md).
+
+---
+
+### CSP nonce (Phase 1 reservation)
+
+Content Security Policy (CSP) is a near-mandatory requirement for production
+sites. To avoid breaking every plugin at once when nonce propagation lands,
+ampless reserves the API surface today (Phase 1 no-op) so plugins can opt in
+ahead of time.
+
+The 3-layer design:
+
+1. **`ctx.cspNonce?: string`** on `PluginPublicRenderContext` — type-reserved
+   on the interface; always `undefined` today. The runtime does not populate
+   this field yet; reads resolve to `undefined`. Middleware/SSR nonce threading
+   lands with the future CSP RFP.
+
+2. **`descriptor.nonce: 'auto' | string`** — accepted by the type on both
+   `inlineScript` and `script` descriptor variants. `'auto'` is the sentinel
+   for future runtime stamping; any other string is an explicit literal;
+   `undefined` emits no `nonce` attribute (default, backward-compatible).
+   Phase 1: the runtime accepts but does not propagate it. Declaring
+   `nonce: 'auto'` today is a forward-compatibility hint and does not change
+   the rendered HTML.
+
+3. **`'cspReady'` capability** — a name-only declarative badge. Declaring it
+   signals intent; future admin UI / sanity checks may surface it. No runtime
+   cross-check or enforcement exists in Phase 1.
+
+**How to be ready:**
+
+```ts
+// src/index.ts
+definePlugin({
+  name: 'my-plugin',
+  apiVersion: 1,
+  trust_level: 'untrusted',
+  capabilities: ['publicHead', 'cspReady'],
+  publicHead: () => [{
+    type: 'inlineScript',
+    id: 'my-snippet',
+    body: '...',
+    nonce: 'auto',    // forward-compat hint; no effect in Phase 1
+  }],
+})
+```
+
+For standalone npm-published plugins, also update `package.json#amplessPlugin.capabilities`
+to match — the runtime cross-check warns on disagreement between the static
+manifest and the factory return value:
+
+```json
+{
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "my-plugin",
+    "trustLevel": "untrusted",
+    "capabilities": ["publicHead", "cspReady"]
+  }
+}
+```
+
+**What "cspReady" means:**
+
+- Site-level CSP compliance depends on middleware / response headers / other
+  inline content the runtime does not control.
+- Once the middleware-driven nonce threading PR lands, plugin-supplied scripts
+  that carry `nonce: 'auto'` will become candidates for runtime nonce stamping.
+- `'cspReady'` does **not** appear in `create-ampless plugin --capabilities`
+  output — it is a reserved capability and the scaffold excludes it to avoid
+  implying active enforcement.
+
+---
+
 ## 7. Async event hooks
 
 `hooks` runs inside the trust_level-matched processor Lambda when an
-event arrives via SQS. The runtime context (`ctx`) carries:
+event arrives via SQS.
+
+### Return value reservation
+
+`PluginEventHandler` returns `Promise<void | PluginHookResult>`. The
+runtime currently ignores the return value entirely — existing
+plugins returning `Promise<void>` keep working without migration.
+`PluginHookResult` is reserved for a future directive (likely first:
+`metrics?: Record<string, number>` for observability emission);
+declaring it today is a forward-compatibility hint. Note: rewrite
+or cancel directives are NOT enabled by this widening alone — they
+require additional `before:*` event support and payload extensions
+in separate PRs.
+
+`PluginHookResult` carries a private `__amplessPluginHookResult`
+marker so that the union does not silently accept unrelated promise
+types (`Promise<string>` / `Promise<number>` etc.) — plugin authors
+do not need to set this field.
+
+### Runtime context
+
+The runtime context (`ctx`) carries:
 
 ```ts
 interface PluginRuntimeContext {
@@ -924,14 +1085,15 @@ etc. — but completely wrong for a webhook signing secret.
 
 - Stored in the `PluginSecret` DynamoDB table (separate from KvStore).
   Admin/editor Cognito users have **no direct AppSync access** to this
-  table — all writes go through the `setPluginSecret` mutation backed
-  by the `plugin-secret-handler` Lambda.
+  table — all writes go through the `setPluginSecret` mutation, which
+  is backed by the `plugin-secret-handler` Lambda.
 - Values are **AES-256-GCM encrypted** before reaching DynamoDB.
   The admin browser sends the plaintext to the Lambda via AppSync
-  (TLS); the Lambda validates, reads the 32-byte encryption key from
-  `process.env.PLUGIN_SECRET_ENCRYPTION_KEY` (injected by CDK from
-  `amplify/secrets/encryption-key.ts`), and writes only the ciphertext.
-  The plaintext never rests in DynamoDB and never flows back to the browser.
+  (TLS in transit); the Lambda validates it, reads the 32-byte
+  encryption key from `process.env.PLUGIN_SECRET_ENCRYPTION_KEY`
+  (injected by CDK from `amplify/secrets/encryption-key.ts`), encrypts
+  the value, and writes only the ciphertext to DDB. The plaintext
+  never rests in DynamoDB and never flows back to the browser.
 - **Threat model (Phase 6a v2.2)**:
 
   | Threat | Status |
@@ -942,19 +1104,19 @@ etc. — but completely wrong for a webhook signing secret.
   | S3 mirror leak | ✓ defeated — PluginSecret table never mirrored. |
 
 - The trusted-processor Lambda decrypts with `node:crypto` on read.
-  `ctx.secret<T>(key)` returns the plaintext string, never ciphertext.
+  `ctx.secret<T>(key)` returns the plaintext string, never the
+  ciphertext.
 - 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()`.
 - **Field-manifest validation scope**: the admin client validates
   `pattern` / `maxLength` / `required` for UX feedback, but the
-  Lambda only enforces a generic 10,000-character hard cap +
-  safe-character sanitizer. An admin/editor calling the AppSync
-  mutation directly can bypass field-level constraints — by design,
-  since admin/editor are trusted operators authorised to set
-  secrets. The manifest checks are UX guidance, not a security
-  boundary.
+  Lambda only enforces a generic 10,000-character hard cap + safe-
+  character sanitizer. An admin/editor calling the AppSync mutation
+  directly can bypass field-level constraints — by design, since
+  admin/editor are trusted operators authorised to set secrets.
+  The manifest checks are UX guidance, not a security boundary.
+  (`publicHead`, `publicBodyEnd`, `publicBodyForPost`,
+  `publicHtmlForPost`) — those surfaces only see `ctx.setting()`.
 
 ### Requirements
 
@@ -970,25 +1132,33 @@ etc. — but completely wrong for a webhook signing secret.
    ```sh
    npx create-ampless setup-encryption-key
    ```
-   Generates a cryptographically random 32-byte key and writes it to
-   `amplify/secrets/encryption-key.ts`. No AWS credentials required.
-   Then import it in `amplify/backend.ts` and pass it to
+   This generates a cryptographically random 32-byte key and writes
+   it to `amplify/secrets/encryption-key.ts`. No AWS credentials
+   required — this is a local file operation only.
+
+   Then import the constant in `amplify/backend.ts` and pass it to
    `defineAmplessBackend({ pluginSecretEncryptionKey })`. Redeploy (or
-   restart the sandbox) to inject the key into Lambda env vars.
-   For public repos, add `--gitignore` to exclude from version control.
+   restart the sandbox) to inject the key into the Lambda env vars.
+
+   For public repos, pass `--gitignore` to exclude the key file from
+   version control and distribute the key separately.
 
 ### Dual-write integrity
 
-The `setPluginSecret` and `clearPluginSecret` operations each write to
-**two DynamoDB tables** in sequence. If the second write fails, the
-tables are left in a predictable state:
+The `setPluginSecret` and `clearPluginSecret` operations each write
+to **two DynamoDB tables** in sequence: `PluginSecret` (ciphertext)
+and `PluginSecretIndicator` (existence timestamp). If the second
+write fails, the tables are left in a predictable, documented state:
 
-| Failure | `PluginSecret` | `PluginSecretIndicator` | `ctx.secret()` | `hasPluginSecret()` |
+| Failure point | `PluginSecret` | `PluginSecretIndicator` | `ctx.secret()` | `hasPluginSecret()` |
 |---|---|---|---|---|
 | **set**: indicator PutItem fails | ciphertext present | absent | returns plaintext ✓ | `false` (UI: "not saved") |
-| **clear**: indicator DeleteItem fails | absent | stale | `undefined` ✓ | `true` (UI: "saved") |
+| **clear**: indicator DeleteItem fails | absent | stale (old timestamp) | `undefined` ✓ | `true` (UI: "saved") |
 
-The clear-path failure is the "safe side": the secret stops firing.
+The clear-path failure is the "safe side": the secret stops firing even
+though the UI briefly shows it as saved. The set-path failure is a minor
+UI inaccuracy: the secret is functional but the existence indicator is
+absent until a retry succeeds.
 
 ### Declaring secret fields
 
@@ -1020,9 +1190,16 @@ export default function webhookPlugin(opts?: { signingSecret?: string }) {
     },
     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
+        if (!secret) return // no secret → skip signing
+
         // ... use secret to sign and POST
       },
     },
@@ -1034,25 +1211,104 @@ export default function webhookPlugin(opts?: { signingSecret?: string }) {
 
 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.
+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.
-Returns `undefined` when no value has been saved by admin. Returns
-the **decrypted plaintext** — never the ciphertext blob.
-Results are per-invocation cached (plaintext, not ciphertext).
-The encryption key is decoded from the Lambda env var at cold-start
-(no extra DDB fetch).
-Cache keys are namespaced by `${instanceId ?? name}:${fieldKey}`.
+`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 (and one
+  decrypt). The encryption key is decoded from the Lambda env var
+  at cold-start (no extra DDB fetch).
+- Cache keys are namespaced: `${instanceId ?? name}:${fieldKey}`.
+  Two plugin instances both declaring `'signingSecret'` never get
+  each other's values.
+- The cached value is the **decrypted plaintext** — not the
+  ciphertext. There is no redundant decrypt on repeated calls.
 
 ### 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.
+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'
+  })
+})
+```
 
 ---
 

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.17",
-    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.8",
-    "@ampless/plugin-gtm": "^0.2.0-alpha.16",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.33",
-    "@ampless/plugin-plausible": "^0.2.0-alpha.16",
-    "@ampless/plugin-reading-time": "^0.1.0-alpha.6",
-    "@ampless/plugin-rss": "^0.2.0-alpha.33",
-    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.12",
-    "@ampless/plugin-seo": "^0.2.0-alpha.33",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.34",
-    "@ampless/admin": "^1.0.0-alpha.66",
-    "@ampless/backend": "^1.0.0-alpha.54",
-    "@ampless/runtime": "^1.0.0-alpha.42",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.18",
+    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.9",
+    "@ampless/plugin-gtm": "^0.2.0-alpha.17",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.34",
+    "@ampless/plugin-plausible": "^0.2.0-alpha.17",
+    "@ampless/plugin-reading-time": "^0.1.0-alpha.7",
+    "@ampless/plugin-rss": "^0.2.0-alpha.34",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.13",
+    "@ampless/plugin-seo": "^0.2.0-alpha.34",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.35",
+    "@ampless/admin": "^1.0.0-alpha.67",
+    "@ampless/backend": "^1.0.0-alpha.56",
+    "@ampless/runtime": "^1.0.0-alpha.43",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.33",
+    "ampless": "^1.0.0-alpha.34",
     "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.108",
+  "version": "1.0.0-alpha.111",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",