create-ampless 1.0.0-alpha.96 → 1.0.0-alpha.98

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { spinner as spinner2, outro as outro4, log as log6 } from "@clack/prompts";
-import { existsSync as existsSync8 } from "fs";
+import { spinner as spinner2, outro as outro5, log as log7 } from "@clack/prompts";
+import { existsSync as existsSync9 } from "fs";
 import { basename as basename4, resolve as resolve5 } from "path";
 
 // src/prompts.ts
@@ -315,7 +315,9 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "-h",
   // Phase 5 `plugin <name>` mode flags
   "--local",
-  "--standalone"
+  "--standalone",
+  // setup-encryption-key flags
+  "--gitignore"
 ]);
 function parseDeployArgs(argv) {
   const out = {
@@ -324,6 +326,8 @@ function parseDeployArgs(argv) {
     upgrade: false,
     copyTheme: false,
     createPlugin: false,
+    setupEncryptionKey: false,
+    gitignore: false,
     dryRun: false,
     noInstall: false,
     githubPrivate: false,
@@ -383,6 +387,9 @@ function parseDeployArgs(argv) {
           }
           out.pluginMode = "standalone";
           break;
+        case "--gitignore":
+          out.gitignore = true;
+          break;
       }
       continue;
     }
@@ -474,6 +481,10 @@ function parseDeployArgs(argv) {
       out.upgrade = true;
       continue;
     }
+    if (raw === "setup-encryption-key" && out.projectName === void 0 && !out.setupEncryptionKey && !out.upgrade && !out.copyTheme && !out.createPlugin) {
+      out.setupEncryptionKey = true;
+      continue;
+    }
     if (raw === "copy-theme" && out.projectName === void 0 && !out.copyTheme) {
       out.copyTheme = true;
       continue;
@@ -510,6 +521,7 @@ Usage:
   npx create-ampless@latest upgrade [options]               # in an existing project dir
   npx create-ampless@latest copy-theme <src> <dst>          # in an existing project dir
   npx create-ampless@latest plugin <name> [options]         # scaffold a plugin (Phase 5)
+  npx create-ampless@latest setup-encryption-key [--gitignore]  # generate encryption key file
 
 Options:
   --site-name <name>          Site display name (default: "My Blog")
@@ -586,6 +598,34 @@ plugin <name>
          Examples:
            npx create-ampless@latest plugin site-verification
            npx create-ampless@latest plugin @ishinao/ampless-plugin-foo --standalone
+
+setup-encryption-key
+         Generate the AES-256-GCM encryption key for plugin secret storage
+         and write it to amplify/secrets/encryption-key.ts (adjacent to
+         amplify/backend.ts). No AWS credentials required \u2014 this is a
+         local file operation only.
+
+         After generating, import the constant in amplify/backend.ts and
+         pass it to defineAmplessBackend({ pluginSecretEncryptionKey: ... }).
+         Then redeploy (or restart the sandbox) to inject the key into the
+         Lambda env vars.
+
+  --gitignore                 Add amplify/secrets/encryption-key.ts to
+                              .gitignore. Default: file is committed
+                              (safe for private repos). Use this flag only
+                              for public repos; distribute the key separately.
+
+         Threat model:
+           \u2713 DDB Console operator sees ciphertext only
+           \u26A0 Source repo / deploy artifact access defeats encryption
+           \u2717 Malicious trusted plugin in the same Lambda can also read
+             the key (per-plugin Lambda isolation = roadmap)
+
+         Rotation: re-run with confirm overwrite. Existing ciphertext
+         becomes unreadable; re-save each secret via /admin/plugins.
+
+         Example: npx create-ampless@latest setup-encryption-key
+         Example: npx create-ampless@latest setup-encryption-key --gitignore
 `;
 
 // src/deploy-prompts.ts
@@ -1909,7 +1949,7 @@ var PROTECTED_PATTERNS = [
   // plugin" doc lives in `packages/ampless/docs/plugin-author-guide.md`.
   /^plugins(\/|$)/
 ];
-var SEED_IF_MISSING_PATTERN = /\.custom\.ts$|^plugins\/README(\.ja)?\.md$/;
+var SEED_IF_MISSING_PATTERN = /\.custom\.ts$|^plugins\/README(\.ja)?\.md$|^amplify\/secrets\/encryption-key\.ts$/;
 var TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([
   ".json",
   ".md",
@@ -2620,8 +2660,126 @@ async function runCreatePlugin(args) {
   }
 }
 
-// src/index.ts
+// src/setup-encryption-key.ts
+import { writeFile as writeFile6, mkdir as mkdir4, readFile as readFile6 } from "fs/promises";
+import { existsSync as existsSync8 } from "fs";
+import { join as join6 } from "path";
+import { randomBytes } from "crypto";
+import { log as log6, confirm as confirm3, outro as outro4, cancel as cancel4 } from "@clack/prompts";
 import pc6 from "picocolors";
+var SECRETS_DIR = "amplify/secrets";
+var KEY_FILE = "encryption-key.ts";
+var KEY_FILE_PATH = `${SECRETS_DIR}/${KEY_FILE}`;
+function buildFileContent(keyB64) {
+  return `// Generated by \`npx create-ampless setup-encryption-key\`.
+// AES-256-GCM key (32 bytes, base64) for plugin secret storage.
+// Rotate via the same CLI command. Existing ciphertext becomes unreadable on rotation.
+
+export const PLUGIN_SECRET_ENCRYPTION_KEY = '${keyB64}'
+`;
+}
+function extractKeyValue(source) {
+  const match = source.match(
+    /\bPLUGIN_SECRET_ENCRYPTION_KEY\b\s*(?::\s*[^=]+)?=\s*(['"])(.*?)\1/
+  );
+  return match?.[2] ?? null;
+}
+function isEmptyPlaceholder(source) {
+  return extractKeyValue(source) === "";
+}
+async function appendGitignoreEntry(cwd, entry) {
+  const gitignorePath = join6(cwd, ".gitignore");
+  if (existsSync8(gitignorePath)) {
+    const content = await readFile6(gitignorePath, "utf-8");
+    if (content.includes(entry)) return;
+    await writeFile6(gitignorePath, content + (content.endsWith("\n") ? "" : "\n") + entry + "\n");
+  } else {
+    await writeFile6(gitignorePath, entry + "\n");
+  }
+}
+async function runSetupEncryptionKey(args) {
+  const cwd = process.cwd();
+  if (!existsSync8(join6(cwd, "amplify"))) {
+    log6.error(
+      `No \`amplify/\` directory found in ${cwd}.
+Run this command from the root of an ampless project (where amplify/backend.ts lives).`
+    );
+    process.exit(1);
+  }
+  const keyFilePath = join6(cwd, KEY_FILE_PATH);
+  if (existsSync8(keyFilePath)) {
+    const existingContent = await readFile6(keyFilePath, "utf-8");
+    if (!isEmptyPlaceholder(existingContent)) {
+      log6.warn(
+        pc6.yellow(
+          `${KEY_FILE_PATH} already exists.
+Overwriting it will make all existing plugin secrets unreadable
+until each secret is re-saved through the admin UI.`
+        )
+      );
+      const confirmed = await confirm3({
+        message: "Overwrite the existing encryption key?",
+        initialValue: false
+      });
+      if (confirmed === false || confirmed === void 0) {
+        cancel4("Cancelled \u2014 existing key preserved.");
+        return;
+      }
+    }
+  }
+  const keyBytes = randomBytes(32);
+  const keyB64 = keyBytes.toString("base64");
+  const secretsDir = join6(cwd, SECRETS_DIR);
+  if (!existsSync8(secretsDir)) {
+    await mkdir4(secretsDir, { recursive: true });
+  }
+  try {
+    await writeFile6(keyFilePath, buildFileContent(keyB64), "utf-8");
+  } catch (err) {
+    log6.error(
+      `Failed to write ${KEY_FILE_PATH}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+  if (args.gitignore) {
+    try {
+      await appendGitignoreEntry(cwd, KEY_FILE_PATH);
+      log6.info(`Added ${KEY_FILE_PATH} to .gitignore`);
+    } catch (err) {
+      log6.warn(
+        `Could not update .gitignore: ${err instanceof Error ? err.message : String(err)}
+Add \`${KEY_FILE_PATH}\` to your .gitignore manually.`
+      );
+    }
+  }
+  outro4(
+    `${pc6.green("\u2714")} Generated ${pc6.cyan(KEY_FILE_PATH)}
+
+  ${pc6.bold("Next steps:")}
+    1. In \`amplify/backend.ts\`, add:
+       import { PLUGIN_SECRET_ENCRYPTION_KEY } from './secrets/encryption-key.js'
+       defineAmplessBackend({ ..., pluginSecretEncryptionKey: PLUGIN_SECRET_ENCRYPTION_KEY })
+    2. Redeploy (or restart the sandbox) to inject the key into Lambda env vars.
+    3. Save plugin secrets via the admin UI \u2014 they are now encrypted at rest.
+
+  ${pc6.bold("Threat model summary:")}
+    ${pc6.green("\u2713")} AWS Console operator browsing DDB sees ciphertext only
+    ${pc6.yellow("\u26A0")} Anyone with source repo / deploy artifact access can decrypt
+    ${pc6.red("\u2717")} Malicious trusted plugin in the same Lambda can also decrypt
+       (per-plugin Lambda isolation = roadmap)
+
+` + (args.gitignore ? `  ${pc6.dim(`${KEY_FILE_PATH} added to .gitignore.`)}
+
+` : `  ${pc6.yellow("Tip:")} If committing to a PUBLIC repo, run with --gitignore instead
+  and distribute the key separately.
+
+`) + `  ${pc6.yellow("Rotation:")} Re-run this command and confirm overwrite.
+  Existing ciphertext will be unreadable; re-save via /admin/plugins.`
+  );
+}
+
+// src/index.ts
+import pc7 from "picocolors";
 var DEFAULT_THEMES = VALID_THEMES;
 function buildNonInteractiveOpts(args) {
   const projectName = args.projectName ?? (() => {
@@ -2646,7 +2804,7 @@ function warnIgnoredScaffoldFlags(args) {
   if (args.plugins) ignored.push("--plugins");
   if (args.projectName) ignored.push("<project-name> positional");
   if (ignored.length > 0) {
-    log6.warn(`--mount mode ignores: ${ignored.join(", ")}`);
+    log7.warn(`--mount mode ignores: ${ignored.join(", ")}`);
   }
 }
 async function runMount(args) {
@@ -2655,8 +2813,8 @@ async function runMount(args) {
   warnIgnoredScaffoldFlags(args);
   const problem = validateMountableProject(destDir);
   if (problem) {
-    log6.error(problem);
-    log6.info(
+    log7.error(problem);
+    log7.info(
       "Run `npx create-ampless@latest <name>` first to scaffold, or `cd` into a scaffolded project before passing --mount."
     );
     process.exit(1);
@@ -2670,23 +2828,23 @@ async function runMount(args) {
     if (err instanceof PreflightError) {
       process.exit(1);
     }
-    log6.error(err instanceof Error ? err.message : String(err));
+    log7.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
 }
 function printDeployResult(result) {
   const lines = [
-    `${pc6.green("\u2714")} Project deployed`,
+    `${pc7.green("\u2714")} Project deployed`,
     ``,
-    `  GitHub:        ${pc6.cyan(result.githubRepoUrl)}`,
-    `  Amplify app:   ${pc6.cyan(result.amplifyAppId)}`,
-    `  Amplify URL:   ${pc6.cyan(result.amplifyAppUrl)}`
+    `  GitHub:        ${pc7.cyan(result.githubRepoUrl)}`,
+    `  Amplify app:   ${pc7.cyan(result.amplifyAppId)}`,
+    `  Amplify URL:   ${pc7.cyan(result.amplifyAppUrl)}`
   ];
   if (result.domainUrl) {
-    lines.push(`  Custom domain: ${pc6.cyan(result.domainUrl)}`);
+    lines.push(`  Custom domain: ${pc7.cyan(result.domainUrl)}`);
   }
   if (result.domainVerification && result.domainVerification.length > 0) {
-    lines.push("", `  ${pc6.bold("Add these DNS records to verify the domain:")}`);
+    lines.push("", `  ${pc7.bold("Add these DNS records to verify the domain:")}`);
     for (const v of result.domainVerification) {
       lines.push(`    ${v.cname}  CNAME  ${v.target}`);
     }
@@ -2694,9 +2852,9 @@ function printDeployResult(result) {
   lines.push(
     "",
     `  First build is now running in Amplify Hosting.`,
-    `  Watch it at ${pc6.cyan(`https://console.aws.amazon.com/amplify/home#/${result.amplifyAppId}`)}`
+    `  Watch it at ${pc7.cyan(`https://console.aws.amazon.com/amplify/home#/${result.amplifyAppId}`)}`
   );
-  outro4(lines.join("\n"));
+  outro5(lines.join("\n"));
 }
 async function main() {
   const args = parseDeployArgs(process.argv.slice(2));
@@ -2705,7 +2863,7 @@ async function main() {
     return;
   }
   for (const flag of args.unknown) {
-    log6.warn(`Unknown argument ignored: ${flag}`);
+    log7.warn(`Unknown argument ignored: ${flag}`);
   }
   if (args.upgrade) {
     await runUpgrade(args);
@@ -2719,6 +2877,10 @@ async function main() {
     await runCreatePlugin(args);
     return;
   }
+  if (args.setupEncryptionKey) {
+    await runSetupEncryptionKey(args);
+    return;
+  }
   if (args.mount) {
     await runMount(args);
     return;
@@ -2731,8 +2893,8 @@ async function main() {
   }
   if (!opts) return;
   const destDir = resolve5(process.cwd(), opts.projectName);
-  if (existsSync8(destDir)) {
-    log6.error(`Directory already exists: ${destDir}`);
+  if (existsSync9(destDir)) {
+    log7.error(`Directory already exists: ${destDir}`);
     process.exit(1);
   }
   const sharedDir = sharedTemplateDir();
@@ -2743,7 +2905,7 @@ async function main() {
     s.stop("Done!");
   } catch (err) {
     s.stop("Failed.");
-    log6.error(String(err));
+    log7.error(String(err));
     process.exit(1);
   }
   if (args.deploy) {
@@ -2756,18 +2918,18 @@ async function main() {
       if (err instanceof PreflightError) {
         process.exit(1);
       }
-      log6.error(err instanceof Error ? err.message : String(err));
+      log7.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
     return;
   }
-  outro4(
-    `${pc6.green("\u2714")} Project created at ${pc6.bold(opts.projectName)}
+  outro5(
+    `${pc7.green("\u2714")} Project created at ${pc7.bold(opts.projectName)}
 
   Next steps:
-    ${pc6.cyan("cd")} ${opts.projectName}
-    ${pc6.cyan("npm install")}
-    ${pc6.cyan("npm run sandbox")}   ${pc6.dim("# deploy sandbox + start Next.js")}`
+    ${pc7.cyan("cd")} ${opts.projectName}
+    ${pc7.cyan("npm install")}
+    ${pc7.cyan("npm run sandbox")}   ${pc7.dim("# deploy sandbox + start Next.js")}`
   );
 }
 main().catch((err) => {

package/dist/templates/_shared/amplify/backend.ts

@@ -10,7 +10,13 @@ import { processorUntrusted } from './events/processor-untrusted/resource.js'
 import { apiKeyRenewer } from './functions/api-key-renewer/resource.js'
 import { mcpHandler } from './functions/mcp-handler/resource.js'
 import { userAdmin } from './functions/user-admin/resource.js'
+import { pluginSecretHandler } from './functions/plugin-secret-handler/resource.js'
 import { customizeBackend } from './backend.custom.js'
+// Plugin secret encryption key (Phase 6a v2.2).
+// Generate with: npx create-ampless setup-encryption-key
+// The key lives in amplify/secrets/encryption-key.ts (gitignore it for
+// public repos; safe to commit for private repos).
+import { PLUGIN_SECRET_ENCRYPTION_KEY } from './secrets/encryption-key.js'
 
 // `defineAmplessBackend` provisions auth, data, storage, the event
 // system (DynamoDB Streams → SQS-trusted / SQS-untrusted → trust_level
@@ -30,6 +36,8 @@ const backend = defineAmplessBackend({
   apiKeyRenewer,
   mcpHandler,
   userAdmin,
+  pluginSecretHandler,
+  pluginSecretEncryptionKey: PLUGIN_SECRET_ENCRYPTION_KEY,
 })
 
 // Run user-defined customizations after baseline wiring. `backend.custom.ts`

package/dist/templates/_shared/amplify/data/resource.ts

@@ -8,6 +8,7 @@ import {
 } from '@ampless/backend'
 import { userAdmin } from '../functions/user-admin/resource.js'
 import { mcpHandler } from '../functions/mcp-handler/resource.js'
+import { pluginSecretHandler } from '../functions/plugin-secret-handler/resource.js'
 import { customSchemaModels } from './resource.custom.js'
 
 // AppSync's `a.handler.custom({ entry })` paths are resolved by CDK
@@ -38,6 +39,7 @@ const schema = a
     ...amplessSchemaModels(a, {
       resolverPaths,
       userAdminFunction: userAdmin,
+      pluginSecretHandlerFunction: pluginSecretHandler,
     }),
     ...customSchemaModels(a),
   })

package/dist/templates/_shared/amplify/functions/plugin-secret-handler/handler.ts

@@ -0,0 +1,11 @@
+// Re-exported from @ampless/backend so the package can ship Lambda
+// handler updates via `npm update`. Amplify's esbuild follows this
+// import and bundles the real handler into the Lambda artifact.
+//
+// The handler validates Cognito group membership (admin/editor),
+// enforces a hard 10,000-char server cap on the value (field-level
+// `pattern` / `maxLength` come from the admin client and are NOT
+// re-enforced here), encrypts with the AES-256-GCM key from
+// `process.env.PLUGIN_SECRET_ENCRYPTION_KEY`, and dual-writes to
+// PluginSecret + PluginSecretIndicator.
+export { handler } from '@ampless/backend/functions/plugin-secret-handler'

package/dist/templates/_shared/amplify/functions/plugin-secret-handler/resource.ts

@@ -0,0 +1,12 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+// `resourceGroupName: 'data'` co-locates this Lambda with the AppSync
+// stack. Required because `setPluginSecret` / `clearPluginSecret` are
+// wired as custom GraphQL resolvers (data → function), matching the
+// same circular-dependency avoidance used for user-admin.
+export const pluginSecretHandler = defineFunction({
+  name: 'plugin-secret-handler',
+  entry: './handler.ts',
+  runtime: 22,
+  resourceGroupName: 'data',
+})

package/dist/templates/_shared/amplify/secrets/encryption-key.ts

@@ -0,0 +1,9 @@
+// Generated by `npx create-ampless setup-encryption-key`.
+// AES-256-GCM key (32 bytes, base64) for plugin secret storage.
+// Rotate via the same CLI command. Existing ciphertext becomes unreadable on rotation.
+//
+// IMPORTANT: This is a placeholder. Replace the value below with a real key
+// by running: npx create-ampless setup-encryption-key
+// (from your project root, after scaffolding).
+
+export const PLUGIN_SECRET_ENCRYPTION_KEY = ''

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

@@ -708,10 +708,12 @@ Secret settings を使うと、trusted プラグインが認証情報 (Webhook
 
 詳しいリファレンスは [`packages/ampless/docs/plugin-author-guide.md`](../../packages/ampless/docs/plugin-author-guide.md) §9a を参照してください。概要:
 
-- `settings.secret` は `trust_level: 'trusted'` + `'secretSettings'` capability 必須。
+- `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 変数で保持。
-- hook 内で `await ctx.secret<string>('signingSecret')` で読む。per-invocation キャッシュ済み。
+- 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 ガイダンス。
 
 ---
 

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

@@ -922,16 +922,39 @@ 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 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.
+- **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 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.
 
 ### Requirements
 
@@ -943,6 +966,29 @@ 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
+   ```
+   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
+   `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.
+
+### 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:
+
+| Failure | `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") |
+
+The clear-path failure is the "safe side": the secret stops firing.
 
 ### Declaring secret fields
 
@@ -994,9 +1040,12 @@ fallback variable instead; never put credentials in the manifest.
 ### 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. Results
-are per-invocation cached; cache keys are namespaced by
-`${instanceId ?? name}:${fieldKey}`.
+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}`.
 
 ### Admin UI
 

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.13",
-    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.4",
-    "@ampless/plugin-gtm": "^0.2.0-alpha.12",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.29",
-    "@ampless/plugin-plausible": "^0.2.0-alpha.12",
-    "@ampless/plugin-reading-time": "^0.1.0-alpha.2",
-    "@ampless/plugin-rss": "^0.2.0-alpha.29",
-    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.8",
-    "@ampless/plugin-seo": "^0.2.0-alpha.29",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.30",
-    "@ampless/admin": "^1.0.0-alpha.58",
-    "@ampless/backend": "^1.0.0-alpha.46",
-    "@ampless/runtime": "^1.0.0-alpha.37",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.14",
+    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.5",
+    "@ampless/plugin-gtm": "^0.2.0-alpha.13",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.30",
+    "@ampless/plugin-plausible": "^0.2.0-alpha.13",
+    "@ampless/plugin-reading-time": "^0.1.0-alpha.3",
+    "@ampless/plugin-rss": "^0.2.0-alpha.30",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.9",
+    "@ampless/plugin-seo": "^0.2.0-alpha.30",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.31",
+    "@ampless/admin": "^1.0.0-alpha.59",
+    "@ampless/backend": "^1.0.0-alpha.47",
+    "@ampless/runtime": "^1.0.0-alpha.38",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.29",
+    "ampless": "^1.0.0-alpha.30",
     "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.96",
+  "version": "1.0.0-alpha.98",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",