@ampless/backend 1.0.0-alpha.46 → 1.0.0-alpha.48

package/dist/events/processor-trusted.d.ts

@@ -21,6 +21,12 @@ interface CreateProcessorTrustedHandlerOpts {
      */
     site: Config['site'];
 }
+/**
+ * Decrypt one AES-256-GCM ciphertext blob.
+ * @param rawKey   32-byte Buffer
+ * @param b64      base64( IV[12] || ciphertext || authTag[16] )
+ */
+declare function decryptSecret(rawKey: Buffer, b64: string): string;
 /**
  * SQS-driven trusted plugin executor. Trusted plugins get a runtime
  * context with `listPublishedPosts` (one Query against the byStatus
@@ -37,4 +43,4 @@ interface CreateProcessorTrustedHandlerOpts {
  */
 declare function createProcessorTrustedHandler(opts: CreateProcessorTrustedHandlerOpts): SQSHandler;
 
-export { type CreateProcessorTrustedHandlerOpts, createProcessorTrustedHandler };
+export { type CreateProcessorTrustedHandlerOpts, createProcessorTrustedHandler, decryptSecret };

package/dist/events/processor-trusted.js

@@ -1,4 +1,5 @@
 // src/events/processor-trusted.ts
+import { createDecipheriv } from "crypto";
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 import { DynamoDBClient, GetItemCommand } from "@aws-sdk/client-dynamodb";
 import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
@@ -48,6 +49,21 @@ function requireEnv(name) {
   return v;
 }
 var POST_BY_STATUS_INDEX = "byStatus";
+function decryptSecret(rawKey, b64) {
+  const combined = Buffer.from(b64, "base64");
+  if (combined.byteLength < 12 + 16) {
+    throw new Error(
+      `[trusted-processor] decryptSecret: ciphertext blob too short (${combined.byteLength} bytes)`
+    );
+  }
+  const iv = combined.subarray(0, 12);
+  const authTag = combined.subarray(combined.byteLength - 16);
+  const ciphertext = combined.subarray(12, combined.byteLength - 16);
+  const decipher = createDecipheriv("aes-256-gcm", rawKey, iv);
+  decipher.setAuthTag(authTag);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return plaintext.toString("utf8");
+}
 function safeParse(s) {
   try {
     return JSON.parse(s);
@@ -89,6 +105,21 @@ function createProcessorTrustedHandler(opts) {
   const PLUGIN_SECRET_TABLE = requireEnv("AMPLESS_PLUGIN_SECRET_TABLE");
   const REGION = requireEnv("AWS_REGION");
   const rawDdb = new DynamoDBClient({});
+  const _encKeyB64 = process.env.PLUGIN_SECRET_ENCRYPTION_KEY;
+  const ENCRYPTION_KEY = (() => {
+    if (!_encKeyB64) return null;
+    const buf = Buffer.from(_encKeyB64, "base64");
+    if (buf.byteLength !== 32) {
+      console.error(
+        `[trusted-processor] PLUGIN_SECRET_ENCRYPTION_KEY must encode 32 bytes (got ${buf.byteLength}); secrets will not be decryptable.`
+      );
+      return null;
+    }
+    return buf;
+  })();
+  function getEncryptionKey() {
+    return ENCRYPTION_KEY;
+  }
   async function listPublished() {
     const items = [];
     let exclusiveStartKey;
@@ -164,9 +195,37 @@ function createProcessorTrustedHandler(opts) {
               Key: marshall({ siteId: "default", sk })
             })
           );
-          const value = result.Item ? unmarshall(result.Item).value : void 0;
-          secretCache.set(cacheKey, value);
-          return value;
+          if (!result.Item) {
+            secretCache.set(cacheKey, void 0);
+            return void 0;
+          }
+          const storedValue = unmarshall(result.Item).value;
+          if (!storedValue) {
+            secretCache.set(cacheKey, void 0);
+            return void 0;
+          }
+          const encryptionKey = getEncryptionKey();
+          let plaintext;
+          if (encryptionKey) {
+            try {
+              plaintext = decryptSecret(encryptionKey, storedValue);
+            } catch (decErr) {
+              console.error(
+                `[trusted-processor] ${label}: ctx.secret("${key}") decryption failed`,
+                decErr
+              );
+              secretCache.set(cacheKey, void 0);
+              return void 0;
+            }
+          } else {
+            console.warn(
+              `[trusted-processor] ${label}: ctx.secret("${key}") \u2014 no encryption key found; returning undefined. Run \`npx create-ampless setup-encryption-key\` and rotate secrets.`
+            );
+            secretCache.set(cacheKey, void 0);
+            return void 0;
+          }
+          secretCache.set(cacheKey, plaintext);
+          return plaintext;
         } catch (err) {
           console.error(
             `[trusted-processor] ${label}: ctx.secret("${key}") DDB read failed`,
@@ -278,5 +337,6 @@ function createProcessorTrustedHandler(opts) {
   };
 }
 export {
-  createProcessorTrustedHandler
+  createProcessorTrustedHandler,
+  decryptSecret
 };

package/dist/functions/plugin-secret-handler.d.ts

@@ -0,0 +1,32 @@
+import { Handler } from 'aws-lambda';
+
+/**
+ * Encrypt `plaintext` with AES-256-GCM.
+ * Returns base64( IV[12] || ciphertext || authTag[16] ).
+ * Node.js `createCipheriv` produces ciphertext and authTag separately;
+ * we concatenate them after the IV.
+ */
+declare function encryptSecret(rawKey: Buffer, plaintext: string): string;
+interface SetArgs {
+    fieldKey: string;
+    instanceId: string;
+    value: string;
+}
+interface ClearArgs {
+    fieldKey: string;
+    instanceId: string;
+}
+interface PluginSecretHandlerEvent {
+    typeName: string;
+    fieldName: string;
+    arguments: Partial<SetArgs & ClearArgs>;
+    identity?: {
+        sub?: string;
+        username?: string;
+        groups?: string[];
+        [k: string]: unknown;
+    };
+}
+declare const handler: Handler<PluginSecretHandlerEvent, string | null>;
+
+export { encryptSecret, handler };

package/dist/functions/plugin-secret-handler.js

@@ -0,0 +1,147 @@
+// src/functions/plugin-secret-handler.ts
+import { createCipheriv, randomBytes } from "crypto";
+import { DynamoDBClient, PutItemCommand, DeleteItemCommand } from "@aws-sdk/client-dynamodb";
+import { marshall } from "@aws-sdk/util-dynamodb";
+import { isValidPluginKey, validatePluginSettingValue } from "ampless";
+var ddb = new DynamoDBClient({});
+var ADMIN_GROUP = "ampless-admin";
+var EDITOR_GROUP = "ampless-editor";
+function requireEnv(name) {
+  const v = process.env[name];
+  if (!v) throw new Error(`plugin-secret-handler: missing required env var ${name}`);
+  return v;
+}
+var _encKeyB64 = process.env.PLUGIN_SECRET_ENCRYPTION_KEY;
+if (!_encKeyB64) {
+  throw new Error(
+    "[plugin-secret-handler] PLUGIN_SECRET_ENCRYPTION_KEY env var is not set. Run `npx create-ampless setup-encryption-key` and configure pluginSecretEncryptionKey in defineAmplessBackend()."
+  );
+}
+var _encKeyBuf = Buffer.from(_encKeyB64, "base64");
+if (_encKeyBuf.byteLength !== 32) {
+  throw new Error(
+    `[plugin-secret-handler] PLUGIN_SECRET_ENCRYPTION_KEY must encode 32 bytes (got ${_encKeyBuf.byteLength}). Re-run \`npx create-ampless setup-encryption-key\`.`
+  );
+}
+var ENCRYPTION_KEY = _encKeyBuf;
+function getEncryptionKey() {
+  return ENCRYPTION_KEY;
+}
+function encryptSecret(rawKey, plaintext) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", rawKey, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  const combined = Buffer.concat([iv, encrypted, authTag]);
+  return combined.toString("base64");
+}
+function pluginSecretSk(instanceId, fieldKey) {
+  return `plugins.${instanceId}.${fieldKey}`;
+}
+function isAllowedGroup(identity) {
+  const groups = identity?.groups ?? [];
+  return groups.includes(ADMIN_GROUP) || groups.includes(EDITOR_GROUP);
+}
+async function handleSet(args) {
+  const { fieldKey, instanceId, value } = args;
+  if (!isValidPluginKey(instanceId)) {
+    throw new Error(`[plugin-secret-handler] Invalid instanceId: "${instanceId}"`);
+  }
+  if (!isValidPluginKey(fieldKey)) {
+    throw new Error(`[plugin-secret-handler] Invalid fieldKey: "${fieldKey}"`);
+  }
+  if (typeof value !== "string") {
+    throw new Error("[plugin-secret-handler] value must be a string");
+  }
+  const validated = validatePluginSettingValue(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    { type: "text", key: fieldKey, label: fieldKey, maxLength: 1e4 },
+    value,
+    "strict"
+  );
+  if (validated === null) {
+    throw new Error(
+      `[plugin-secret-handler] Value for field "${fieldKey}" failed validation (too long or contains invalid characters).`
+    );
+  }
+  const sanitizedValue = validated;
+  const encKey = getEncryptionKey();
+  const ciphertext = encryptSecret(encKey, sanitizedValue);
+  const sk = pluginSecretSk(instanceId, fieldKey);
+  const secretTable = requireEnv("AMPLESS_PLUGIN_SECRET_TABLE");
+  const indicatorTable = requireEnv("AMPLESS_PLUGIN_SECRET_INDICATOR_TABLE");
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await ddb.send(
+    new PutItemCommand({
+      TableName: secretTable,
+      Item: marshall({ siteId: "default", sk, value: ciphertext })
+    })
+  );
+  await ddb.send(
+    new PutItemCommand({
+      TableName: indicatorTable,
+      Item: marshall({ siteId: "default", sk, lastSetAt: now })
+    })
+  );
+  return "ok";
+}
+async function handleClear(args) {
+  const { fieldKey, instanceId } = args;
+  if (!isValidPluginKey(instanceId)) {
+    throw new Error(`[plugin-secret-handler] Invalid instanceId: "${instanceId}"`);
+  }
+  if (!isValidPluginKey(fieldKey)) {
+    throw new Error(`[plugin-secret-handler] Invalid fieldKey: "${fieldKey}"`);
+  }
+  const sk = pluginSecretSk(instanceId, fieldKey);
+  const secretTable = requireEnv("AMPLESS_PLUGIN_SECRET_TABLE");
+  const indicatorTable = requireEnv("AMPLESS_PLUGIN_SECRET_INDICATOR_TABLE");
+  await ddb.send(
+    new DeleteItemCommand({
+      TableName: secretTable,
+      Key: marshall({ siteId: "default", sk })
+    })
+  );
+  await ddb.send(
+    new DeleteItemCommand({
+      TableName: indicatorTable,
+      Key: marshall({ siteId: "default", sk })
+    })
+  );
+  return "ok";
+}
+var handler = async (event) => {
+  const field = event.fieldName;
+  if (!isAllowedGroup(event.identity)) {
+    console.error(
+      `[plugin-secret-handler] ${field}: caller is not in admin or editor group`,
+      { identity: event.identity }
+    );
+    throw new Error("Unauthorized: caller must be in ampless-admin or ampless-editor group");
+  }
+  try {
+    if (field === "setPluginSecret") {
+      const { fieldKey, instanceId, value } = event.arguments;
+      if (!fieldKey || !instanceId || value === void 0) {
+        throw new Error("[plugin-secret-handler] setPluginSecret: missing required arguments");
+      }
+      return await handleSet({ fieldKey, instanceId, value });
+    }
+    if (field === "clearPluginSecret") {
+      const { fieldKey, instanceId } = event.arguments;
+      if (!fieldKey || !instanceId) {
+        throw new Error("[plugin-secret-handler] clearPluginSecret: missing required arguments");
+      }
+      return await handleClear({ fieldKey, instanceId });
+    }
+    console.error(`[plugin-secret-handler] unsupported fieldName: ${field}`);
+    throw new Error(`Unsupported fieldName: ${field}`);
+  } catch (err) {
+    console.error(`[plugin-secret-handler] ${field} failed:`, err);
+    throw err;
+  }
+};
+export {
+  encryptSecret,
+  handler
+};

package/dist/index.d.ts

@@ -15,6 +15,44 @@ interface DefineAmplessBackendOpts {
     apiKeyRenewer: FunctionResource;
     userAdmin: FunctionResource;
     mcpHandler: FunctionResource;
+    /**
+     * The plugin-secret-handler Lambda resource.
+     *
+     * Backs the `setPluginSecret` and `clearPluginSecret` AppSync mutations.
+     * Receives plaintext from admin browser, validates, encrypts with the
+     * AES-256-GCM key (injected as `PLUGIN_SECRET_ENCRYPTION_KEY` env var),
+     * and writes only ciphertext to DDB. The admin browser never touches
+     * PluginSecret directly.
+     *
+     * Generate and commit the key with `npx create-ampless setup-encryption-key`,
+     * then pass it via `pluginSecretEncryptionKey` below. No AWS credentials
+     * required for key provisioning.
+     *
+     * Optional so that existing stacks that haven't added the function yet
+     * don't break at TypeScript level. The function must be wired in for
+     * the mutations to be reachable.
+     */
+    pluginSecretHandler?: FunctionResource;
+    /**
+     * AES-256-GCM encryption key for plugin secret storage (v2.2).
+     *
+     * A base64-encoded 32-byte key generated by
+     * `npx create-ampless setup-encryption-key` and stored in
+     * `amplify/secrets/encryption-key.ts` (adjacent to `amplify/backend.ts`).
+     *
+     * Example wiring in `amplify/backend.ts`:
+     * ```ts
+     * import { PLUGIN_SECRET_ENCRYPTION_KEY } from './secrets/encryption-key.js'
+     * defineAmplessBackend({ ..., pluginSecretEncryptionKey: PLUGIN_SECRET_ENCRYPTION_KEY })
+     * ```
+     *
+     * When provided, the value is injected as the `PLUGIN_SECRET_ENCRYPTION_KEY`
+     * env var into both the `processorTrusted` Lambda (for decryption via
+     * `ctx.secret()`) and the `pluginSecretHandler` Lambda (for encryption on
+     * set).  If omitted, the env var is not set and both Lambdas will log a
+     * warning and return `undefined` from `ctx.secret()`.
+     */
+    pluginSecretEncryptionKey?: string;
 }
 type AmplessBackend = any;
 /**
@@ -148,6 +186,19 @@ interface AmplessSchemaModelsOpts {
      * pattern as `AmplessAuthConfigOpts.postConfirmation`.
      */
     userAdminFunction?: unknown;
+    /**
+     * Optional Amplify `defineFunction` ref backing the plugin-secret
+     * mutation ops (`setPluginSecret`, `clearPluginSecret`).
+     *
+     * When supplied, the mutations are added to the schema and routed to
+     * this Lambda. The Lambda receives the plaintext from admin browser,
+     * encrypts with the env-var key, and writes ciphertext to the
+     * PluginSecret table. Admin/editor Cognito users never touch
+     * PluginSecret directly — only the Lambda (via IAM) does.
+     *
+     * Typed as `unknown` for the same reason as `userAdminFunction`.
+     */
+    pluginSecretHandlerFunction?: unknown;
 }
 /**
  * The Ampless model + custom query definitions, returned as a plain
@@ -168,6 +219,8 @@ declare function amplessSchemaModels(a: any, opts?: AmplessSchemaModelsOpts): {
     AdminUser?: any;
     listAdminUsers?: any;
     setAdminUserRole?: any;
+    setPluginSecret?: any;
+    clearPluginSecret?: any;
     Post: any;
     Page: any;
     Media: any;
@@ -176,6 +229,7 @@ declare function amplessSchemaModels(a: any, opts?: AmplessSchemaModelsOpts): {
     KvStore: any;
     McpToken: any;
     PluginSecret: any;
+    PluginSecretIndicator: any;
     PublicPost: any;
     PublicPostConnection: any;
     PublicMedia: any;

package/dist/index.js

@@ -18,7 +18,8 @@ function defineAmplessBackend(opts) {
     processorUntrusted: opts.processorUntrusted,
     apiKeyRenewer: opts.apiKeyRenewer,
     userAdmin: opts.userAdmin,
-    mcpHandler: opts.mcpHandler
+    mcpHandler: opts.mcpHandler,
+    ...opts.pluginSecretHandler ? { pluginSecretHandler: opts.pluginSecretHandler } : {}
   });
   const cfnBucket = backend.storage.resources.cfnResources.cfnBucket;
   cfnBucket.publicAccessBlockConfiguration = {
@@ -79,6 +80,7 @@ function defineAmplessBackend(opts) {
     "AMPLESS_USER_POOL_ID",
     backend.auth.resources.userPool.userPoolId
   );
+  const graphqlApi = backend.data.resources.cfnResources.cfnGraphqlApi;
   const postTable = backend.data.resources.tables["Post"];
   const cfnPostTable = backend.data.resources.cfnResources.amplifyDynamoDbTables["Post"];
   cfnPostTable.streamSpecification = { streamViewType: "NEW_AND_OLD_IMAGES" };
@@ -150,13 +152,32 @@ function defineAmplessBackend(opts) {
       ]
     })
   );
+  const pluginSecretTable = backend.data.resources.tables["PluginSecret"];
+  pluginSecretTable.grantReadData(trustedFn);
+  const pluginSecretIndicatorTable = backend.data.resources.tables["PluginSecretIndicator"];
   trustedFn.addEnvironment("AMPLESS_BUCKET_NAME", backend.storage.resources.bucket.bucketName);
   trustedFn.addEnvironment("AMPLESS_POST_TABLE", postTable.tableName);
   trustedFn.addEnvironment("AMPLESS_KV_TABLE", kvTable.tableName);
   trustedFn.addEnvironment("AMPLESS_POSTTAG_TABLE", postTagTable.tableName);
+  trustedFn.addEnvironment("AMPLESS_PLUGIN_SECRET_TABLE", pluginSecretTable.tableName);
+  if (opts.pluginSecretEncryptionKey) {
+    trustedFn.addEnvironment("PLUGIN_SECRET_ENCRYPTION_KEY", opts.pluginSecretEncryptionKey);
+  }
+  if (opts.pluginSecretHandler) {
+    const secretHandlerFn = backend.pluginSecretHandler.resources.lambda;
+    pluginSecretTable.grantReadWriteData(secretHandlerFn);
+    pluginSecretIndicatorTable.grantReadWriteData(secretHandlerFn);
+    secretHandlerFn.addEnvironment("AMPLESS_PLUGIN_SECRET_TABLE", pluginSecretTable.tableName);
+    secretHandlerFn.addEnvironment(
+      "AMPLESS_PLUGIN_SECRET_INDICATOR_TABLE",
+      pluginSecretIndicatorTable.tableName
+    );
+    if (opts.pluginSecretEncryptionKey) {
+      secretHandlerFn.addEnvironment("PLUGIN_SECRET_ENCRYPTION_KEY", opts.pluginSecretEncryptionKey);
+    }
+  }
   const untrustedFn = backend.processorUntrusted.resources.lambda;
   untrustedFn.addEventSource(new SqsEventSource(untrustedQueue, { batchSize: 5 }));
-  const graphqlApi = backend.data.resources.cfnResources.cfnGraphqlApi;
   const apiKeyRenewerFn = backend.apiKeyRenewer.resources.lambda;
   apiKeyRenewerFn.addEnvironment("APPSYNC_API_ID", graphqlApi.attrApiId);
   apiKeyRenewerFn.addToRolePolicy(
@@ -183,7 +204,7 @@ function defineAmplessBackend(opts) {
   mcpHandlerFn.addEnvironment("AMPLESS_MCP_TOKEN_TABLE", mcpTokenTable.tableName);
   mcpHandlerFn.addEnvironment(
     "AMPLESS_APPSYNC_URL",
-    backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl
+    graphqlApi.attrGraphQlUrl
   );
   mcpHandlerFn.addToRolePolicy(
     new PolicyStatement({
@@ -401,16 +422,32 @@ function amplessSchemaModels(a, opts = {}) {
     // This is a COMPLETELY SEPARATE model from KvStore. KvStore grants
     // admin/editor full read access through AppSync, which means any
     // value stored there can be read by anyone with admin/editor
-    // credentials. PluginSecret has NO read authorization for any
-    // Cognito group — read is exclusively granted to IAM-authenticated
-    // principals (i.e. the trusted-processor Lambda role).
+    // credentials. PluginSecret is intentionally inaccessible to
+    // admin/editor Cognito users via AppSync — the only way to write
+    // a secret is through the `setPluginSecret` / `clearPluginSecret`
+    // AppSync mutations which are backed by the plugin-secret-handler
+    // Lambda. The Lambda receives the plaintext, reads the encryption
+    // key from `process.env.PLUGIN_SECRET_ENCRYPTION_KEY` (injected by
+    // CDK at deploy time from `amplify/secrets/encryption-key.ts` — see
+    // Phase 6a v2.2 in docs/architecture/08-plugin-architecture.md),
+    // and performs the DDB PutItem using its own IAM role. Ciphertext
+    // never flows back to the browser.
     //
     // Authorization design:
-    //   - admin / editor: CREATE, UPDATE, DELETE only. The AppSync
-    //     schema will not generate getPluginSecret / listPluginSecrets
-    //     queries for these groups because 'read' is absent.
-    //   - IAM (Lambda): read only. The trusted-processor Lambda uses
-    //     DDB SDK GetItem directly (not AppSync) to read secrets.
+    //   - admin / editor: NO direct AppSync access. All writes go
+    //     through the plugin-secret-handler Lambda mutation.
+    //   - `allow.resource(pluginSecretHandlerFunction)`: grants the
+    //     plugin-secret-handler Lambda AppSync access to this model
+    //     (used internally by the mutation's resolver path).
+    //   - trusted-processor Lambda reads directly via DDB SDK with the
+    //     `grantReadData` IAM grant in `backend.ts`, bypassing AppSync
+    //     entirely — no `@auth` rule needed for that path.
+    //   - Fallback (when `pluginSecretHandlerFunction` is not provided
+    //     by the caller): admin-only Cognito group. Encryption renders
+    //     ciphertext meaningless without the env-var key, but the
+    //     feature won't actually work without the handler — this
+    //     fallback only exists to keep CDK synth from failing in a
+    //     partially-wired deployment.
     //
     // Storage key convention:
     //   siteId = 'default'   (single-site architecture)
@@ -425,18 +462,68 @@ function amplessSchemaModels(a, opts = {}) {
       siteId: a.string().required(),
       // Composite sort key: `plugins.<instanceId>.<fieldKey>`
       sk: a.string().required(),
-      // The secret value (plaintext string). DynamoDB's server-side
-      // encryption (SSE) with AWS-owned KMS protects the value at
-      // rest. IAM controls Lambda read; AppSync controls admin write.
+      // The secret value stored as AES-256-GCM ciphertext (base64).
+      // Format: base64( IV[12] || ciphertext || authTag[16] ).
+      // Encrypted by the plugin-secret-handler Lambda using the key
+      // in `process.env.PLUGIN_SECRET_ENCRYPTION_KEY` (set by CDK at
+      // deploy time from the `amplify/secrets/encryption-key.ts`
+      // constant). Even if an AWS account operator reads this column
+      // via the DDB Console they only see ciphertext — the key lives
+      // outside DynamoDB. The honest threat model is documented in
+      // docs/architecture/08-plugin-architecture.md: defeated for
+      // DDB-only browsing, NOT defeated for anyone with source repo
+      // / deploy artifact access, NOT defeated for a malicious
+      // trusted plugin co-located in the same Lambda.
       value: a.string().required()
-    }).identifier(["siteId", "sk"]).authorization((allow) => [
-      // admin/editor can create/update/delete but NOT read.
-      // 'read' is intentionally omitted so AppSync does not generate
-      // getPluginSecret / listPluginSecrets queries for these groups.
-      allow.groups(["ampless-admin", "ampless-editor"]).to(["create", "update", "delete"]),
-      // Trusted Lambda reads via IAM-signed requests (SigV4).
-      allow.authenticated("iam").to(["read"])
-    ]),
+    }).identifier(["siteId", "sk"]).authorization((allow) => {
+      const rules = [];
+      if (opts.pluginSecretHandlerFunction) {
+        rules.push(
+          allow.resource(opts.pluginSecretHandlerFunction).to(["read", "create", "update", "delete"])
+        );
+      } else {
+        rules.push(allow.groups(["ampless-admin"]));
+      }
+      return rules;
+    }),
+    // Existence-only indicator for PluginSecret rows.
+    //
+    // Admin/editor Cognito users cannot read from PluginSecret at all
+    // (IAM-only authorization above). But the admin UI needs to know
+    // whether a secret has been saved so it can show the "stored"
+    // indicator (••••••••) vs an empty input. PluginSecretIndicator
+    // solves this without ever exposing ciphertext or plaintext to the
+    // browser — it stores only the timestamp of the last write.
+    //
+    // The plugin-secret-handler Lambda writes to both tables atomically
+    // (in practice: two sequential DDB puts; true DDB transactions would
+    // require TransactWriteItems which adds latency; an extra indicator
+    // row is at most stale-indicator-but-no-secret, which degrades
+    // gracefully as a false "stored" indicator in the UI).
+    PluginSecretIndicator: a.model({
+      siteId: a.string().required(),
+      // Same sort-key format as PluginSecret:
+      //   `plugins.${instanceId ?? name}.${fieldKey}`
+      sk: a.string().required(),
+      // ISO 8601 datetime string — set by plugin-secret-handler on
+      // every write. Admin UI may show this as "last updated" hint.
+      lastSetAt: a.datetime().required()
+    }).identifier(["siteId", "sk"]).authorization((allow) => {
+      const rules = [
+        // Admin/editor have AppSync read for `hasPluginSecret` and
+        // direct write+delete as a fallback path (the Lambda is the
+        // normal write path, but allowing admin write here keeps the
+        // indicator and ciphertext aligned if a clear operation is
+        // retried after a partial failure).
+        allow.groups(["ampless-admin", "ampless-editor"])
+      ];
+      if (opts.pluginSecretHandlerFunction) {
+        rules.push(
+          allow.resource(opts.pluginSecretHandlerFunction).to(["read", "create", "update", "delete"])
+        );
+      }
+      return rules;
+    }),
     // Custom return type for public post reads. Decoupling from `Post` lets
     // AppSync skip the model-level (admin-only) auth check on fields.
     //
@@ -548,6 +635,33 @@ function amplessSchemaModels(a, opts = {}) {
       allow.publicApiKey(),
       allow.groups(["ampless-admin", "ampless-editor"])
     ]),
+    // Plugin secret mutation ops, only wired when the caller supplies a
+    // Lambda function ref. Conditionally spread because
+    // `a.handler.function(undefined)` is not a valid call.
+    //
+    // setPluginSecret:   admin browser sends plaintext → Lambda encrypts
+    //                    (AES-256-GCM, env-var key) → DDB PutItem on
+    //                    PluginSecret + PutItem on PluginSecretIndicator.
+    // clearPluginSecret: Lambda deletes from both tables.
+    //
+    // Both ops require Cognito group admin-or-editor — the Lambda still
+    // re-checks via the Cognito token in the AppSync event context so
+    // a raw IAM call bypassing AppSync cannot skip the group gate.
+    ...opts.pluginSecretHandlerFunction ? {
+      setPluginSecret: a.mutation().arguments({
+        fieldKey: a.string().required(),
+        instanceId: a.string().required(),
+        value: a.string().required()
+      }).returns(a.string()).handler(a.handler.function(opts.pluginSecretHandlerFunction)).authorization((allow) => [
+        allow.groups(["ampless-admin", "ampless-editor"])
+      ]),
+      clearPluginSecret: a.mutation().arguments({
+        fieldKey: a.string().required(),
+        instanceId: a.string().required()
+      }).returns(a.string()).handler(a.handler.function(opts.pluginSecretHandlerFunction)).authorization((allow) => [
+        allow.groups(["ampless-admin", "ampless-editor"])
+      ])
+    } : {},
     // User management ops, only wired when the caller supplies a
     // Lambda function ref. Conditionally spread because
     // `a.handler.function(undefined)` is not a valid call — projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/backend",
-  "version": "1.0.0-alpha.46",
+  "version": "1.0.0-alpha.48",
   "description": "Amplify Gen 2 backend factories for ampless: auth, data, storage, event processors, API key renewer",
   "license": "MIT",
   "type": "module",
@@ -36,6 +36,10 @@
     "./functions/mcp-handler": {
       "import": "./dist/functions/mcp-handler.js",
       "types": "./dist/functions/mcp-handler.d.ts"
+    },
+    "./functions/plugin-secret-handler": {
+      "import": "./dist/functions/plugin-secret-handler.js",
+      "types": "./dist/functions/plugin-secret-handler.d.ts"
     }
   },
   "files": [
@@ -65,8 +69,8 @@
     "@smithy/protocol-http": "^5.4.4",
     "@smithy/signature-v4": "^5.4.4",
     "fflate": "^0.8.3",
-    "ampless": "1.0.0-alpha.29",
-    "@ampless/mcp-server": "1.0.0-alpha.35"
+    "@ampless/mcp-server": "1.0.0-alpha.36",
+    "ampless": "1.0.0-alpha.30"
   },
   "peerDependencies": {
     "@aws-amplify/backend": "^1",