ampless 1.0.0-alpha.29 → 1.0.0-alpha.30

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

@@ -712,18 +712,48 @@ Secret settings を使うと、trusted プラグインが認証情報 (Webhook
 
 `settings.secret` はストレージモデルが構造的に異なります:
 
-- KvStore とは **別テーブル** の `PluginSecret` DynamoDB model に保存。
-- admin/editor グループは **書き込み・削除のみ可**。AppSync が `getPluginSecret` / `listPluginSecrets` を生成しない（read 権限がない）。
-- trusted-processor Lambda IAM role だけが DDB `GetItem` で読み取れる。
+- 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` には 2 つの要件があります:
+`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 フィールドの宣言
 
@@ -803,7 +833,8 @@ ctx.secret<T = string>(key: string): Promise<T | undefined>
 
 - admin が未保存なら `undefined` を返す。
 - `T` は convenience cast (ctx.setting と同じ)。値は常に string として保存される。
-- 結果は per-invocation キャッシュされる。同 batch 内で同キーを 2 回呼んでも DDB 呼び出しは 1 回。
+- 結果は 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

package/docs/plugin-author-guide.md

@@ -922,14 +922,38 @@ 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.
+- 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, 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 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 |
+  |---|---|
+  | AWS Console operator browsing PluginSecret table | ✓ defeated — ciphertext only, no key in DDB |
+  | Source repo / deploy artifact access | ⚠ NOT defeated — key is in `amplify/secrets/encryption-key.ts`. Private repo + restricted artifact access expected. |
+  | Malicious trusted plugin in same Lambda | ✗ NOT defeated — `process.env.PLUGIN_SECRET_ENCRYPTION_KEY` reachable from plugin code. True isolation = per-plugin Lambda (privileged tier, roadmap). |
+  | 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 the
+  ciphertext.
 - Never queried by the site-settings mirror path.
 - Never passed to any public-render surface
+- **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.
   (`publicHead`, `publicBodyEnd`, `publicBodyForPost`,
   `publicHtmlForPost`) — those surfaces only see `ctx.setting()`.
 
@@ -943,6 +967,37 @@ etc. — but completely wrong for a webhook signing secret.
 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`).
+3. **One-time key setup** — run from your project root:
+   ```sh
+   npx create-ampless setup-encryption-key
+   ```
+   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 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: `PluginSecret` (ciphertext)
+and `PluginSecretIndicator` (existence timestamp). If the second
+write fails, the tables are left in a predictable, documented state:
+
+| 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 (old timestamp) | `undefined` ✓ | `true` (UI: "saved") |
+
+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
 
@@ -1035,10 +1090,14 @@ ctx.secret<T = string>(key: string): Promise<T | undefined>
 - 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.
+  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
 

package/package.json

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