ampless 1.0.0-alpha.31 → 1.0.0-alpha.33

package/dist/index.d.ts

@@ -302,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' | 'secretSettings' | 'contentFields' | 'adminPage' | 'serverRoute' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
+type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'writePublicAsset' | 'schema' | 'publicHtmlForPost' | 'secretSettings' | 'contentFields' | 'adminPage' | 'serverRoute' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem' | 'cspReady';
 /**
  * Loading strategy for `script` / `inlineScript` descriptors.
  *
@@ -344,6 +344,16 @@ interface PluginPublicRenderContext {
      * field's declared shape, so the cast is safe in practice.
      */
     setting<T = unknown>(key: string): T | undefined;
+    /**
+     * Request-scoped CSP nonce reservation. Always `undefined` in Phase 1
+     * — the runtime does not populate this field yet. Middleware/SSR
+     * threading lands with the future CSP RFP. Plugin authors who want to
+     * be ready for the future stamping can declare
+     * `inlineScript.nonce: 'auto'` today; once the middleware-driven
+     * threading PR lands, those descriptors will become candidates for
+     * runtime nonce stamping.
+     */
+    cspNonce?: string;
 }
 /**
  * Descriptor returned by `publicHead()`. The runtime validates each
@@ -364,6 +374,15 @@ type PublicHeadDescriptor = {
     defer?: boolean;
     /** Allow-listed attributes only (data-*, crossorigin, referrerpolicy, ...). */
     attrs?: Record<string, string | boolean>;
+    /**
+     * Optional CSP nonce. Same semantics as inlineScript.nonce
+     * (`'auto'` is the sentinel for future runtime stamping; any
+     * other string is an explicit literal; undefined emits no
+     * `nonce` attribute). Phase 1 reservation: runtime accepts
+     * but does not propagate. See `inlineScript.nonce` JSDoc for
+     * the full description.
+     */
+    nonce?: 'auto' | string;
 } | {
     type: 'inlineScript';
     /** Required for duplicate detection and dev warnings. */
@@ -391,9 +410,25 @@ type PublicHeadDescriptor = {
      */
     scriptType?: 'application/ld+json';
     /**
-     * Type-only reservation. CSP nonce resolution (including the
-     * planned `'auto'` mode) is deferred to a future RFP; Phase 1
-     * does not propagate this field to the rendered element.
+     * Optional CSP nonce.
+     *
+     *   - `'auto'`: sentinel reserved for future runtime stamping.
+     *     When the middleware/SSR CSP nonce threading PR lands, the
+     *     runtime will read `ctx.cspNonce` from the request scope
+     *     and stamp the rendered `<script>` tag automatically.
+     *   - any other `string`: explicit nonce literal (advanced;
+     *     rarely needed).
+     *   - `undefined`: no `nonce` attribute emitted (default,
+     *     backward-compatible with non-CSP sites).
+     *
+     * Phase 1 reservation: the runtime accepts the field but does
+     * not propagate it to the rendered element. Declaring
+     * `nonce: 'auto'` today is a forward-compatibility hint and
+     * does not change the rendered HTML.
+     *
+     * Note: TypeScript does not type-widen here — `string` already
+     * accepts `'auto'` as a literal. The semantic reservation is
+     * documented above.
      */
     nonce?: string;
 } | {
@@ -540,7 +575,48 @@ interface PluginMetadata {
         types?: Record<string, string>;
     };
 }
-type PluginEventHandler<T extends EventType = EventType> = (event: AmplessEvent<T>, ctx: PluginRuntimeContext) => Promise<void>;
+/**
+ * Hook return value reservation (Phase 1: type only, runtime no-op).
+ *
+ * Today's runtime (after-event SQS Lambdas) ignores the return value
+ * entirely. The type is widened so a future PR can land additive
+ * directives without breaking plugin authors who publish in the
+ * meantime. Likely first use case:
+ *
+ *   - `metrics?: Record<string, number>` — emit observability data
+ *     without touching CloudWatch SDK directly from the plugin.
+ *
+ * `cancel` / `post` rewrite-style directives are NOT enabled by this
+ * type alone — they would also require `before:*` events to be wired
+ * to plugins (currently reserved, see events.ts) and payload shapes
+ * to expose mutable bodies. This PR widens the return surface only;
+ * richer semantics need follow-on PRs.
+ *
+ * The `readonly __amplessPluginHookResult?: never` marker is a
+ * type-level nominal tag: it prevents `Promise<void | PluginHookResult>`
+ * from silently accepting unrelated promise types like
+ * `Promise<string>` or `Promise<number>`. Plugin authors do not need
+ * to set this field — it is optional and exists only to constrain
+ * what the union accepts.
+ */
+interface PluginHookResult {
+    readonly __amplessPluginHookResult?: never;
+}
+/**
+ * Async event hook handler.
+ *
+ * The return value is reserved (see `PluginHookResult`). Today's
+ * runtime ignores it — returning `undefined` (`Promise<void>`) is
+ * the canonical "no-op" and matches existing plugin code without
+ * migration. Plugins that explicitly return a `PluginHookResult`
+ * object type-check today but do not change runtime behaviour
+ * until the matching capability PR lands.
+ *
+ * Non-PluginHookResult promise types (`Promise<string>`,
+ * `Promise<number>`, etc.) are rejected at compile time by the
+ * `__amplessPluginHookResult` private marker on `PluginHookResult`.
+ */
+type PluginEventHandler<T extends EventType = EventType> = (event: AmplessEvent<T>, ctx: PluginRuntimeContext) => Promise<void | PluginHookResult>;
 /**
  * Runtime services injected into hook handlers by the Lambda processor.
  * Decoupling plugins from concrete AWS clients lets us swap implementations
@@ -1475,4 +1551,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 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 };
+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 PluginHookResult, 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/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 が描画する形
@@ -563,11 +563,82 @@ React 19 はさらに、クライアントコンポーネントのレンダー
 
 投稿単位の見える出力には `publicHtmlForPost` を使ってください（Phase 6d — 上の例と §6 の `PublicPostHtmlDescriptor` 参照）。runtime が post 本文の周囲の固定スロットにサーバーサイド HTML を出すので、hydration と競合しません。
 
+
+### 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 {

package/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.
@@ -715,12 +719,103 @@ 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.
 
+
+### 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 {

package/package.json

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