ampless 1.0.0-alpha.39 → 1.0.0-alpha.41

package/docs/plugin-author-guide.ja.md

@@ -13,6 +13,8 @@
 
 設計の経緯と背景は [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md) に集約。本ページはその実装ハンドブック側です。
 
+> **ポジショニング**: ampless はエンジニア向けのカスタマイズベース CMS です — プラグインは**サイトエンジニアが `cms.config.ts` でインポート + 設定する npm dep** です。エンジニアは他の npm ライブラリと同様にインストール前に各 dep を審査します（Astro integration / Next.js plugin パターン）。このガイドで説明する trust framework（`trust_level`、capabilities、IAM スコープ付き Lambda）は v1 において**ファーストパーティプラグインの code organization**として実装されています — どの trust 階層の Lambda が各イベントフックを実行するか、各階層が保有する IAM 権限、そして狭い範囲のポイントでのみ runtime hard gate を適用する（最も重要: `settings.secret` は `trust_level: 'trusted'` を要求、シークレット読み取りに trusted Lambda の IAM 権限が必要なため）。ほとんどの capability 宣言は runtime の hard gate ではなく soft warning + admin ラベル + 将来の allow-list surface です。任意の未審査サードパーティ untrusted プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox としては**設計されていません**。マーケットプレイス + ランタイムサンドボックスは v2.0+ の探索であり、v1 の保証ではありません。詳細な trust model は [`docs/architecture/08-plugin-architecture.md#trust-model-v1-scope`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) を参照してください。
+
 ---
 
 ## 0. テーマとプラグインの境界線
@@ -287,13 +289,15 @@ runtime がチェックする内容:
 
 ## 4. `trust_level` の選び方
 
+trust 階層は v1 において**ファーストパーティプラグインの code organization**として実装されています — イベントフックがどの IAM スコープ付き Lambda で実行されるか、その Lambda が保有する権限を決定します。これはエンジニアが審査した npm dep 向けの code organization surface であり、任意のサードパーティ未審査プラグインを自動的に安全に動かすための marketplace-grade automatic sandbox ではありません（上記の[ポジショニング注記](#ampless-プラグインの書き方)と[詳細な trust model](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) を参照）。
+
 3 階層、選択基準は **イベントフック (hooks) が何を必要とするか** で決まります (sync サーフェスは IAM に触れない):
 
 | 階層 | IAM | 今日動くもの | 用途 |
 |---|---|---|---|
 | `untrusted` | なし (SQS consume のみ) | 同期サーフェス + イベントフック | head/body descriptor、webhook 配送、コンテンツ変換 |
 | `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | 同期サーフェス + イベントフック | RSS フィード、sitemap、計算済み JSON インデックス |
-| `privileged` | 予約 | 同期サーフェスのみ — イベントフックはサイレントフィルタ（警告ログあり） | 将来: SES、secret、private S3 |
+| `privileged` | 予約（v2.0+ 探索のみ） | 同期サーフェスのみ — イベントフックはサイレントフィルタ（警告ログあり） | 将来のマーケットプレイス探索: SES、secret、private S3 |
 
 > **`privileged` プラグイン作者へ：** `trust_level: 'privileged'` とイベント
 > `hooks` を宣言した場合、**現時点でフックは実行されません**。両 processor が
@@ -301,8 +305,10 @@ runtime がチェックする内容:
 > `console.warn` を出力するため、サイレントドロップは可視化されます。
 > 同期サーフェス（`publicHead`、`publicBodyEnd`、`metadata`、`publicBodyForPost`、
 > `publicHtmlForPost`）は `trust_level` に関わらず正常に動き、警告も出ません。
-> privileged Lambda が用意された際、`'privileged'` を宣言済みのプラグインは
-> 自動的に新しい tier を使えるようになります — コードの変更は不要です。
+> privileged Lambda プロビジョニングは v2.0+ の探索項目です — ampless が
+> プラグインマーケットプレイスを構築する場合、すでに `'privileged'` を宣言した
+> プラグインは自動的に新しい tier を使えるようになります。
+> v1 ファーストパーティプラグインは trusted Lambda の現行 IAM スコープに収まる用途で `trust_level: 'trusted'` を使ってください。すなわち Post / KvStore / PluginSecret / PostTag の読み取り、`public/plugins/*` への S3 書き込み、外向き HTTP (AWS IAM 認証を必要としないもの) です。このスコープ外の要件 — SES、private S3 プレフィックス、自前の IAM プリンシパルを必要とする AWS API 呼び出し — は v2.0+ privileged Lambda 探索の対象で、v1 `trusted` には収まりません。
 
 決め方の目安:
 
@@ -862,12 +868,18 @@ Secret settings を使うと、trusted プラグインが認証情報 (Webhook
 - 公開 render surface (`publicHead` など) からは読めない。
 - **field manifest 検証の範囲**: admin クライアントは UX フィードバック目的で `pattern` / `maxLength` / `required` を検証するが、Lambda 側は **汎用の 10,000 文字ハードキャップと安全文字サニタイザのみ**を強制する。admin/editor が AppSync mutation を直接呼ぶと field 単位の制約は迂回できる。設計上意図したもので、admin/editor は secret 設定を許可された信頼されたオペレータと位置づけている。manifest チェックは UX ガイダンスであり、セキュリティ境界ではない。
 
-### 要件
+### 要件と `definePlugin()` の挙動
+
+`settings.secret` は `definePlugin()` 時に 4 つの observable な挙動を持ちます（これは v1 のファーストパーティ organization のシークレットアクセス hard gate; [plugin.ts:1004-1019](https://github.com/heavymoons/ampless/blob/main/packages/ampless/src/plugin.ts#L1004-L1019) 参照）:
 
-`settings.secret` には 3 つの要件があります:
+1. **`settings.secret` 非空 + `trust_level !== 'trusted'`** → `definePlugin()` が **throw**。untrusted と privileged Lambda は `PluginSecret` テーブルへの IAM read アクセスを持たない; trusted Lambda の IAM 権限が必要。
+2. **`settings.secret` 非空 + `capabilities` 宣言済み + `capabilities` に `'secretSettings'` が含まれない** → **soft 不一致 warning**。`'schema'` / `'publicHtmlForPost'` の既存 capability-mismatch パターンと同じ。
+3. **`settings.secret` 非空 + `capabilities` 未定義**（`capabilities` 配列を持たない legacy プラグイン）→ **warning なし**。`capabilities` が `undefined` のとき不一致チェックをスキップ、後方互換のため。
+4. **`capabilities: ['secretSettings']` 宣言だけで `settings.secret` フィールドなし** → **no-op**。warning も throw もなし。
 
-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` の不整合パターンと同じ）。
+`settings.secret` を使うには以下も必要です:
+1. `trust_level: 'trusted'`（上記 #1 の要件; それ以外は `definePlugin()` が throw）。
+2. `capabilities` に `'secretSettings'` を含める（`capabilities` が定義されているとき省略すると console.warn）。
 3. **鍵の初回セットアップ** — プロジェクトルートで実行:
    ```sh
    npx create-ampless setup-encryption-key
@@ -1234,7 +1246,7 @@ it('admin が空文字保存した場合は空配列', () => {
 - [`packages/plugin-plausible`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible) — `data-*` attrs 付きの単一 `<script>` descriptor、`required` な URL field（self-hosted Plausible 上書き対応）
 - [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted、非同期 hooks + `writePublicAsset`
 - [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`
-- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook + 外向き HTTP
+- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — trusted hook + 外向き HTTP + `secretSettings` (admin 管理の signing secret、Phase 6a)
 - [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` ルートレンダラ
 - [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability、投稿単位 Article JSON-LD。（Phase 4）
 
@@ -1340,4 +1352,4 @@ export default defineConfig({
 - ファーストパーティプラグインの bug → `heavymoons/ampless` にプラグインの package 名つきで issue
 - プラグインランタイム / admin form の bug → 同じレポ、ラベル `area:plugins`
 
-ampless レポは v1.0 RC まで非公開なので、上記のリンクは現時点では package tarball 内の `node_modules/ampless/docs/` をローカルで見るための参照です。public 化後は実 GitHub URL に解決されます。
+ampless レポは現在 alpha 期間中は非公開です。beta に進む (npm `beta` dist-tag、リポジトリ公開) と上記のリンクが GitHub URL に解決されます。現状でも同じ docs が package tarball 内の `node_modules/ampless/docs/` に同梱されているので、GitHub にアクセスせずローカルで読めます。

package/docs/plugin-author-guide.md

@@ -19,6 +19,8 @@ per-post body injection, the async event hooks, and admin-managed
 The design rationale is in [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md);
 this page is the hands-on companion.
 
+> **Positioning**: ampless is a customization-based CMS for engineers — plugins are **npm dependencies that the site engineer imports + configures in `cms.config.ts`**. The engineer audits each dep before installing, the way they would for any other npm library (Astro integration / Next.js plugin pattern). The trust framework described in this guide (`trust_level`, capabilities, IAM-scoped Lambdas) is implemented in v1 as **first-party plugin organization** — it decides which trust tier's Lambda runs each event hook, which IAM permissions each tier holds, and applies hard runtime gates only at narrowly-scoped points (most notably: `settings.secret` requires `trust_level: 'trusted'` because secret read needs the trusted Lambda's IAM permission). Most capability declarations are soft warnings + admin labels + future allow-list surfaces, not hard runtime gates. It is **not** designed as a marketplace-grade automatic sandbox that safely runs arbitrary untrusted third-party plugins. Marketplace + runtime sandbox is a v2.0+ exploration, not a v1 guarantee. See [`docs/architecture/08-plugin-architecture.md#trust-model-v1-scope`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) for the full trust model.
+
 ---
 
 ## 0. Theme vs Plugin Boundary
@@ -358,6 +360,8 @@ not a runtime block.
 
 ## 4. Picking a `trust_level`
 
+The trust tiers are implemented in v1 as **first-party plugin organization** — they decide which IAM-scoped Lambda runs your event hooks and which permissions that Lambda holds. This is a code organization surface for engineer-audited npm deps, not a marketplace-grade automatic sandbox for arbitrary third-party untrusted plugins (see the [Positioning note](#writing-an-ampless-plugin) above and the [full trust model](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope)).
+
 Three tiers, picked by what the plugin needs to do **inside
 event hooks** (the sync surfaces — metadata, head, body — don't
 touch IAM):
@@ -366,7 +370,7 @@ touch IAM):
 |---|---|---|---|
 | `untrusted` | none (SQS consume only) | sync surfaces + event hooks | head/body descriptors, webhook delivery, content transforms |
 | `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | sync surfaces + event hooks | RSS feed, sitemap, computed JSON indexes |
-| `privileged` | reserved | sync surfaces only — event hooks are silently filtered out (warning logged) | future: SES, secrets, private S3 |
+| `privileged` | reserved (v2.0+ exploration only) | sync surfaces only — event hooks are silently filtered out (warning logged) | future marketplace exploration: SES, secrets, private S3 |
 
 > **Warning for `privileged` plugin authors:** If you declare
 > `trust_level: 'privileged'` with event `hooks` today, **your hooks
@@ -375,9 +379,10 @@ touch IAM):
 > the drop is visible. Sync render surfaces (`publicHead`,
 > `publicBodyEnd`, `metadata`, `publicBodyForPost`, `publicHtmlForPost`)
 > work normally regardless of `trust_level` and emit no warning.
-> When the privileged Lambda provisioning PR lands, plugins that
-> already declared `'privileged'` will automatically pick up the new
-> tier — nothing needs to change in your code.
+> `privileged` Lambda provisioning is a v2.0+ exploration item — if
+> AmpLess later builds a plugin marketplace, that PR will automatically
+> pick up plugins that already declared `'privileged'`.
+> v1 first-party plugins should use `trust_level: 'trusted'` for capabilities that fit within the trusted Lambda's existing IAM scope: Post / KvStore / PluginSecret / PostTag read, `public/plugins/*` S3 write, and outbound HTTP (no AWS-IAM-authenticated calls). Requirements that fall outside that scope — SES, private S3 prefixes, calling AWS APIs that need an IAM principal of their own — are v2.0+ privileged-Lambda exploration material and don't fit into v1 `trusted`.
 
 Rule of thumb:
 
@@ -1150,16 +1155,18 @@ etc. — but completely wrong for a webhook signing secret.
   (`publicHead`, `publicBodyEnd`, `publicBodyForPost`,
   `publicHtmlForPost`) — those surfaces only see `ctx.setting()`.
 
-### Requirements
+### Requirements and `definePlugin()` behaviour
+
+`settings.secret` has four observable behaviours at `definePlugin()` time (this is the v1 first-party organization hard gate for secret access; see [plugin.ts:1004-1019](https://github.com/heavymoons/ampless/blob/main/packages/ampless/src/plugin.ts#L1004-L1019)):
 
-`settings.secret` requires:
+1. **`settings.secret` non-empty + `trust_level !== 'trusted'`** → `definePlugin()` **throws**. Untrusted and privileged Lambdas have no IAM read access to the `PluginSecret` table; the trusted Lambda's IAM permission is required.
+2. **`settings.secret` non-empty + `capabilities` declared + `'secretSettings'` missing from `capabilities`** → **soft mismatch warning**. Matches the existing capability-mismatch pattern for `'schema'` / `'publicHtmlForPost'`.
+3. **`settings.secret` non-empty + `capabilities` undefined** (legacy plugin without a `capabilities` array) → **no warning**. The mismatch check is skipped when `capabilities` is `undefined`, for backward compatibility.
+4. **`capabilities: ['secretSettings']` declared with no `settings.secret` field** → **no-op**. Neither warning nor throw.
 
-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`).
+To use `settings.secret`, you also need:
+1. `trust_level: 'trusted'` (requirement #1 above; `definePlugin()` throws otherwise).
+2. `'secretSettings'` in `capabilities` (omitting it when `capabilities` is defined produces a console warning).
 3. **One-time key setup** — run from your project root:
    ```sh
    npx create-ampless setup-encryption-key
@@ -1676,7 +1683,7 @@ Worked examples to crib from:
 - [`packages/plugin-plausible`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible) — single `<script>` descriptor with `data-*` attrs and a required URL field (self-hosted Plausible override).
 - [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted, async event hooks + `writePublicAsset`.
 - [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`.
-- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook with outbound HTTP.
+- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — trusted hook with outbound HTTP + `secretSettings` (admin-managed signing secret, Phase 6a).
 - [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` route renderer.
 - [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability; per-post Article JSON-LD. (Phase 4)
 
@@ -1826,6 +1833,8 @@ PROTECTED), so the scaffolded code is safe across ampless upgrades.
 - Bugs in the plugin runtime / admin form → same repo, label
   `area:plugins`.
 
-The ampless repo stays private until v1.0 RC. Once it's public, the
-links above resolve to the actual GitHub URLs; today they live in
-the package tarball directly under `node_modules/ampless/docs/`.
+The ampless repo is currently private during the alpha stage; the
+GitHub URLs above start resolving once beta ships (npm `beta`
+dist-tag, repo flips public). Today the same docs also live in the
+package tarball directly under `node_modules/ampless/docs/`, so
+you can read them locally without browsing GitHub.

package/package.json

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