ampless 1.0.0-alpha.31 → 1.0.0-alpha.32

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;
 } | {

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,6 +563,56 @@ 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. 非同期イベントフック

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,6 +719,76 @@ 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

package/package.json

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