@anthusai/papyrus 2.0.0-next.5 → 2.0.0-next.50

package/infra/amplify-app-shell.ts

@@ -2,10 +2,10 @@ import { Construct } from "constructs";
 import { ArnFormat, CfnOutput, Duration, Fn, Stack, StackProps } from "aws-cdk-lib";
 import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
-import * as secretsmanager from "aws-cdk-lib/aws-secretsmanager";
+import { SecureStringParameter } from "./secure-string-parameter";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs";
-import { AmplifyAppShellSiteConfig, PROSPECTUS_PAPYRUS_SITE_ROUTES, ReaderCustomHeaderRule, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveProspectusAccountsEndpoint, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config";
+import { AmplifyAppShellSiteConfig, PROSPECTUS_PAPYRUS_SITE_ROUTES, ReaderCustomHeaderRule, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveReaderPollSecretParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config";
 
 function environmentVariables(variables: Record<string, string>): amplify.CfnBranch.EnvironmentVariableProperty[] {
   return Object.entries(variables).map(([name, value]) => ({ name, value }));
@@ -72,6 +72,9 @@ export class AmplifyAppShellStack extends Stack {
     if (!hasCmsApp(config)) {
       if (!config.reader) throw new Error(`site ${config.siteId} has neither a cms section nor a reader`);
       this.readerAppId = this.addReaderApp(config, config.reader);
+      if (config.autoDeploy) {
+        this.addGithubDeployRole(config, [{ appId: this.readerAppId, branch: config.reader.branchName ?? "main" }]);
+      }
       return;
     }
 
@@ -97,37 +100,55 @@ export class AmplifyAppShellStack extends Stack {
 
     const revalidateSecretParameterName = config.frontend === "pretext" ? resolveRevalidateSecretParameterName(config) : undefined;
     if (revalidateSecretParameterName) {
+      const revalidateSecret = new SecureStringParameter(this, "RevalidateSecretParameter", {
+        parameterName: revalidateSecretParameterName,
+        description: `Shared secret that authorizes publishes to call the /api/revalidate route of ${cmsAppName}`,
+      });
       computeRole.addToPolicy(
         new iam.PolicyStatement({
           sid: "ReadRevalidateSecret",
           actions: ["ssm:GetParameter"],
-          resources: [
-            this.formatArn({ service: "ssm", resource: "parameter", resourceName: revalidateSecretParameterName.slice(1), arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
-          ],
+          resources: [revalidateSecret.parameterArn],
         }),
       );
     }
 
     const prospectusAccountsApiStageArn = config.cms.prospectusAccountsApiStageArn;
-    const prospectusSessionSealingSecret = prospectusAccountsApiStageArn
-      ? new secretsmanager.Secret(this, "ProspectusSessionSealingSecret", {
+    const prospectusSessionSealing = prospectusAccountsApiStageArn
+      ? new SecureStringParameter(this, "ProspectusSessionSealingParameter", {
+        parameterName: resolveProspectusSessionSealingParameterName(config),
         description: `Seals the Prospectus sign-in cookies of ${cmsAppName}; replacing it signs everyone out`,
-        generateSecretString: { passwordLength: 64, excludePunctuation: true },
       })
       : undefined;
-    const prospectusEnvironment = prospectusAccountsApiStageArn && prospectusSessionSealingSecret
+    const prospectusEnvironment: Record<string, string> = prospectusAccountsApiStageArn && prospectusSessionSealing
       ? {
         PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT: resolveProspectusAccountsEndpoint(prospectusAccountsApiStageArn),
-        PAPYRUS_PROSPECTUS_SESSION_SECRET_ARN: prospectusSessionSealingSecret.secretArn,
+        PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER: prospectusSessionSealing.parameterName,
         PAPYRUS_PROSPECTUS_SITE_PRODUCT: `papyrus-${config.siteId}`,
       }
       : {};
-    if (prospectusSessionSealingSecret) {
+    if (prospectusSessionSealing) {
       computeRole.addToPolicy(
         new iam.PolicyStatement({
           sid: "ReadProspectusSessionSealingSecret",
-          actions: ["secretsmanager:GetSecretValue"],
-          resources: [prospectusSessionSealingSecret.secretArn],
+          actions: ["ssm:GetParameter"],
+          resources: [prospectusSessionSealing.parameterArn],
+        }),
+      );
+    }
+    if (prospectusAccountsApiStageArn && config.cms.readerRetirementPoll) {
+      // Prospectus admits one caller per site, this compute role, so the scheduled snapshot run reaches the retired-subject
+      // route through the CMS route /api/reader/retired, which it authenticates with this secret.
+      const readerPollSecret = new SecureStringParameter(this, "ReaderPollSecretParameter", {
+        parameterName: resolveReaderPollSecretParameterName(config),
+        description: `Authorizes the scheduled reader snapshot run to call the retired-subject route of ${cmsAppName}`,
+      });
+      prospectusEnvironment.PAPYRUS_READER_POLL_SECRET_PARAMETER = readerPollSecret.parameterName;
+      computeRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "ReadReaderPollSecret",
+          actions: ["ssm:GetParameter"],
+          resources: [readerPollSecret.parameterArn],
         }),
       );
     }
@@ -172,9 +193,15 @@ export class AmplifyAppShellStack extends Stack {
     const stagingOrigin = stagingDomainName
       ? `https://${stagingDomainName}/`
       : Fn.join("", ["https://staging.", cmsApp.attrDefaultDomain, "/"]);
+    // The compute adapter's request URL is https://localhost:3000, so the site names its own public origin.
+    // A site served by its own edge (cms.siteOrigin) has no Amplify domain, so the edge host is its origin.
+    const siteOrigin = resolveSiteOrigin(config);
+    const productionSiteOrigin = cmsHostName ? `https://${cmsHostName}` : siteOrigin ?? Fn.join("", ["https://main.", cmsApp.attrDefaultDomain]);
+    const stagingSiteOrigin = stagingDomainName ? `https://${stagingDomainName}` : Fn.join("", ["https://staging.", cmsApp.attrDefaultDomain]);
     const sharedRootDomain = config.cms.domainPrefix !== undefined;
     const defaultOriginsToAllow = [
       ...(config.cms.domainName ? [] : [productionOrigin]),
+      ...(siteOrigin ? [`${siteOrigin}/`] : []),
       ...(stagingEnabled && !stagingDomainName ? [stagingOrigin] : []),
     ];
     const oauthRedirectUrls = defaultOriginsToAllow.length === 0
@@ -185,7 +212,8 @@ export class AmplifyAppShellStack extends Stack {
       appId: cmsApp.attrAppId,
       branchName: "main",
       stage: "PRODUCTION",
-      enableAutoBuild: true,
+      // Auto-build off when GitHub Actions starts the job on merge (autoDeploy): nothing may double-build.
+      enableAutoBuild: !config.autoDeploy,
       enablePerformanceMode: false,
       environmentVariables: environmentVariables({
         ...config.cms.environment,
@@ -194,6 +222,7 @@ export class AmplifyAppShellStack extends Stack {
         PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,
         PAPYRUS_SITE_BRAND: config.brand,
         SITE_ENV: "production",
+        PAPYRUS_SITE_ORIGIN: productionSiteOrigin,
         PAPYRUS_CONTENT_SOURCE: "published",
         ...(revalidateSecretParameterName ? { PAPYRUS_REVALIDATE_SECRET_PARAMETER: revalidateSecretParameterName } : {}),
         ...prospectusEnvironment,
@@ -216,6 +245,7 @@ export class AmplifyAppShellStack extends Stack {
           PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,
           PAPYRUS_SITE_BRAND: config.brand,
           SITE_ENV: "staging",
+          PAPYRUS_SITE_ORIGIN: stagingSiteOrigin,
           ...stagingMode,
           ...prospectusEnvironment,
           NEXT_PUBLIC_PAPYRUS_STAGING_URL: stagingDomainName
@@ -274,6 +304,13 @@ export class AmplifyAppShellStack extends Stack {
     const amplifyAppIds = [cmsApp.attrAppId, ...(this.readerAppId ? [this.readerAppId] : [])];
     this.addAuthoringRole(config, cmsApp.attrAppId, amplifyAppIds);
 
+    if (config.autoDeploy) {
+      this.addGithubDeployRole(config, [
+        { appId: cmsApp.attrAppId, branch: "main" },
+        ...(this.readerAppId && config.reader ? [{ appId: this.readerAppId, branch: config.reader.branchName ?? "main" }] : []),
+      ]);
+    }
+
     if (config.github) {
       this.addGithubCiRole(config, config.github, cmsApp.attrAppId, amplifyAppIds);
     }
@@ -326,6 +363,55 @@ export class AmplifyAppShellStack extends Stack {
     });
   }
 
+  /**
+   * The merge-to-main deploy role: assumable only by a GitHub Actions run on `main` of the site's own
+   * repository (OIDC, no keys), and able to do exactly one thing: start and read Amplify jobs on the
+   * production branch of the site's apps.
+   */
+  private addGithubDeployRole(config: AmplifyAppShellSiteConfig, targets: { appId: string; branch: string }[]): void {
+    const { owner, repo } = resolveGithubRepository(config);
+    const provider = iam.OpenIdConnectProvider.fromOpenIdConnectProviderArn(
+      this,
+      "GithubDeployOidcProvider",
+      this.formatArn({
+        service: "iam",
+        region: "",
+        resource: "oidc-provider",
+        resourceName: GITHUB_OIDC_PROVIDER_HOST,
+        arnFormat: ArnFormat.SLASH_RESOURCE_NAME,
+      }),
+    );
+    const deployRole = new iam.Role(this, "GithubDeployRole", {
+      roleName: `${config.siteId}-github-deploy`,
+      description: `Merge-to-main deploy for ${owner}/${repo}: GitHub OIDC on refs/heads/main only; amplify:StartJob and GetJob on the production branch of the site's apps only`,
+      maxSessionDuration: Duration.hours(1),
+      assumedBy: new iam.OpenIdConnectPrincipal(provider, {
+        StringEquals: {
+          [`${GITHUB_OIDC_PROVIDER_HOST}:aud`]: "sts.amazonaws.com",
+          [`${GITHUB_OIDC_PROVIDER_HOST}:sub`]: githubOidcSubjects(config, "main"),
+        },
+      }),
+    });
+    deployRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "StartAndReadProductionJobs",
+        actions: ["amplify:StartJob", "amplify:GetJob"],
+        resources: targets.map((target) =>
+          this.formatArn({
+            service: "amplify",
+            resource: "apps",
+            resourceName: `${target.appId}/branches/${target.branch}/jobs/*`,
+            arnFormat: ArnFormat.SLASH_RESOURCE_NAME,
+          }),
+        ),
+      }),
+    );
+    new CfnOutput(this, "GithubDeployRoleArn", {
+      value: deployRole.roleArn,
+      description: `Role for the merge-to-main deploy workflow in ${owner}/${repo}`,
+    });
+  }
+
   private addGithubCiRole(
     config: AmplifyAppShellSiteConfig,
     github: NonNullable<AmplifyAppShellSiteConfig["github"]>,
@@ -351,9 +437,7 @@ export class AmplifyAppShellStack extends Stack {
       assumedBy: new iam.OpenIdConnectPrincipal(provider, {
         StringEquals: { [`${GITHUB_OIDC_PROVIDER_HOST}:aud`]: "sts.amazonaws.com" },
         StringLike: {
-          [`${GITHUB_OIDC_PROVIDER_HOST}:sub`]: github.branches.map(
-            (branch) => `repo:${github.owner}/${github.repo}:ref:refs/heads/${branch}`,
-          ),
+          [`${GITHUB_OIDC_PROVIDER_HOST}:sub`]: github.branches.flatMap((branch) => githubOidcSubjects(config, branch)),
         },
       }),
     });
@@ -420,7 +504,7 @@ export class AmplifyAppShellStack extends Stack {
       appId: readerApp.attrAppId,
       branchName: readerBranchName,
       stage: "PRODUCTION",
-      enableAutoBuild: true,
+      enableAutoBuild: !config.autoDeploy,
       environmentVariables: environmentVariables({
         ...(reader.environment ?? {}),
         PAPYRUS_SITE_BRAND: config.brand,

package/infra/index.js

@@ -10,6 +10,7 @@ try {
   );
 }
 export const { AmplifyAppShellStack } = await import("./amplify-app-shell.js");
+export const { SecureStringParameter } = await import("./secure-string-parameter.js");
 export const { GithubOidcProviderStack } = await import("./github-oidc-provider.js");
 export { parseSiteConfig } from "./site-config.js";
 export { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec, buildSpecFor } from "./build-specs.js";

package/infra/secure-string-parameter-handler.js

@@ -0,0 +1,41 @@
+/**
+ * Source of the Lambda behind SecureStringParameter, as a string so the staged
+ * package (which ships only .ts under infra/) can inline it and tests can run it
+ * against a fake SSM client. CommonJS, under the 4096-character inline limit.
+ *
+ * It creates the parameter when it is missing and does nothing else: it never
+ * overwrites an existing value, never reads one back, never logs the value, and
+ * returns no data (only the parameter name as the physical id).
+ */
+export const SECURE_STRING_PARAMETER_HANDLER_SOURCE = `
+const { randomInt } = require("node:crypto");
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function generate(length) {
+  let value = "";
+  for (let index = 0; index < length; index += 1) value += ALPHABET[randomInt(ALPHABET.length)];
+  return value;
+}
+exports.createHandler = (ssm, PutParameterCommand) => async (event) => {
+  const name = event.ResourceProperties.ParameterName;
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  try {
+    await ssm.send(new PutParameterCommand({
+      Name: name,
+      Description: event.ResourceProperties.Description,
+      Type: "SecureString",
+      Tier: "Standard",
+      Overwrite: false,
+      Value: generate(Number(event.ResourceProperties.Length)),
+    }));
+  } catch (error) {
+    if (!error || error.name !== "ParameterAlreadyExists") {
+      throw new Error("PutParameter failed for " + name + " (" + (error && error.name ? error.name : "error") + ")");
+    }
+  }
+  return { PhysicalResourceId: name };
+};
+exports.handler = async (event) => {
+  const { SSMClient, PutParameterCommand } = require("@aws-sdk/client-ssm");
+  return exports.createHandler(new SSMClient({}), PutParameterCommand)(event);
+};
+`;

package/infra/secure-string-parameter-handler.ts

@@ -0,0 +1,41 @@
+/**
+ * Source of the Lambda behind SecureStringParameter, as a string so the staged
+ * package (which ships only .ts under infra/) can inline it and tests can run it
+ * against a fake SSM client. CommonJS, under the 4096-character inline limit.
+ *
+ * It creates the parameter when it is missing and does nothing else: it never
+ * overwrites an existing value, never reads one back, never logs the value, and
+ * returns no data (only the parameter name as the physical id).
+ */
+export const SECURE_STRING_PARAMETER_HANDLER_SOURCE = `
+const { randomInt } = require("node:crypto");
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function generate(length) {
+  let value = "";
+  for (let index = 0; index < length; index += 1) value += ALPHABET[randomInt(ALPHABET.length)];
+  return value;
+}
+exports.createHandler = (ssm, PutParameterCommand) => async (event) => {
+  const name = event.ResourceProperties.ParameterName;
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  try {
+    await ssm.send(new PutParameterCommand({
+      Name: name,
+      Description: event.ResourceProperties.Description,
+      Type: "SecureString",
+      Tier: "Standard",
+      Overwrite: false,
+      Value: generate(Number(event.ResourceProperties.Length)),
+    }));
+  } catch (error) {
+    if (!error || error.name !== "ParameterAlreadyExists") {
+      throw new Error("PutParameter failed for " + name + " (" + (error && error.name ? error.name : "error") + ")");
+    }
+  }
+  return { PhysicalResourceId: name };
+};
+exports.handler = async (event) => {
+  const { SSMClient, PutParameterCommand } = require("@aws-sdk/client-ssm");
+  return exports.createHandler(new SSMClient({}), PutParameterCommand)(event);
+};
+`;

package/infra/secure-string-parameter.js

@@ -0,0 +1,79 @@
+import { Construct } from "constructs";
+import { ArnFormat, CustomResource, Duration, RemovalPolicy, Stack } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as customResources from "aws-cdk-lib/custom-resources";
+import { SECURE_STRING_PARAMETER_HANDLER_SOURCE } from "./secure-string-parameter-handler.js";
+/** One Lambda and role per stack, shared by every SecureStringParameter in it. */
+class SecureStringParameterProvider extends Construct {
+    static ID = "SecureStringParameterProvider";
+    role;
+    provider;
+    static of(stack) {
+        return stack.node.tryFindChild(SecureStringParameterProvider.ID)
+            ?? new SecureStringParameterProvider(stack);
+    }
+    constructor(stack) {
+        super(stack, SecureStringParameterProvider.ID);
+        this.role = new iam.Role(this, "Role", {
+            assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+            description: "Creates generated SecureString parameters: PutParameter per named parameter, never overwriting",
+            managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole")],
+        });
+        const onEvent = new lambda.Function(this, "OnEvent", {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            handler: "index.handler",
+            code: lambda.Code.fromInline(SECURE_STRING_PARAMETER_HANDLER_SOURCE),
+            role: this.role,
+            timeout: Duration.seconds(30),
+            description: "Creates a generated SecureString parameter once; never returns or logs the value",
+        });
+        this.provider = new customResources.Provider(this, "Provider", { onEventHandler: onEvent });
+    }
+}
+/**
+ * A generated secret in SSM Parameter Store as a standard SecureString (free,
+ * AWS-managed `aws/ssm` key), instead of a Secrets Manager secret ($0.40/month).
+ *
+ * CloudFormation cannot create a SecureString, so a custom resource Lambda puts
+ * it. The Lambda generates a random value at create time and never returns or
+ * logs it, so the value is in no template, output or stack event. It is
+ * create-only: an update never regenerates it and never overwrites a parameter
+ * that already exists (a hand-made one is adopted as it is), and delete retains
+ * it, so a stack teardown cannot sign anyone out. Rotate it with
+ * `aws ssm put-parameter --overwrite`. Readers get `ssm:GetParameter` on
+ * `parameterArn` only; decrypting with the AWS-managed key needs no KMS grant.
+ */
+export class SecureStringParameter extends Construct {
+    parameterName;
+    parameterArn;
+    constructor(scope, id, props) {
+        super(scope, id);
+        if (!props.parameterName.startsWith("/"))
+            throw new Error(`SSM parameter name must be absolute: ${props.parameterName}`);
+        const length = props.length ?? 64;
+        if (!Number.isInteger(length) || length < 32)
+            throw new Error("A generated secret must be at least 32 characters.");
+        const stack = Stack.of(this);
+        this.parameterName = props.parameterName;
+        this.parameterArn = stack.formatArn({
+            service: "ssm",
+            resource: "parameter",
+            resourceName: props.parameterName.slice(1),
+            arnFormat: ArnFormat.SLASH_RESOURCE_NAME,
+        });
+        const shared = SecureStringParameterProvider.of(stack);
+        shared.role.addToPolicy(new iam.PolicyStatement({
+            sid: `Put${id.replace(/[^A-Za-z0-9]/g, "")}`,
+            actions: ["ssm:PutParameter"],
+            resources: [this.parameterArn],
+        }));
+        const resource = new CustomResource(this, "Resource", {
+            serviceToken: shared.provider.serviceToken,
+            resourceType: "Custom::SecureStringParameter",
+            properties: { ParameterName: props.parameterName, Description: props.description, Length: String(length) },
+            removalPolicy: RemovalPolicy.RETAIN,
+        });
+        resource.node.addDependency(shared.role);
+    }
+}

package/infra/secure-string-parameter.ts

@@ -0,0 +1,91 @@
+import { Construct } from "constructs";
+import { ArnFormat, CustomResource, Duration, RemovalPolicy, Stack } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as customResources from "aws-cdk-lib/custom-resources";
+import { SECURE_STRING_PARAMETER_HANDLER_SOURCE } from "./secure-string-parameter-handler";
+
+export interface SecureStringParameterProps {
+  /** Absolute parameter name, e.g. `/papyrus/<siteId>/prospectus-session-sealing`. */
+  parameterName: string;
+  description: string;
+  /** Length of the generated value. Default 64. */
+  length?: number;
+}
+
+/** One Lambda and role per stack, shared by every SecureStringParameter in it. */
+class SecureStringParameterProvider extends Construct {
+  static readonly ID = "SecureStringParameterProvider";
+  public readonly role: iam.Role;
+  public readonly provider: customResources.Provider;
+
+  static of(stack: Stack): SecureStringParameterProvider {
+    return (stack.node.tryFindChild(SecureStringParameterProvider.ID) as SecureStringParameterProvider | undefined)
+      ?? new SecureStringParameterProvider(stack);
+  }
+
+  private constructor(stack: Stack) {
+    super(stack, SecureStringParameterProvider.ID);
+    this.role = new iam.Role(this, "Role", {
+      assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+      description: "Creates generated SecureString parameters: PutParameter per named parameter, never overwriting",
+      managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole")],
+    });
+    const onEvent = new lambda.Function(this, "OnEvent", {
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambda.Code.fromInline(SECURE_STRING_PARAMETER_HANDLER_SOURCE),
+      role: this.role,
+      timeout: Duration.seconds(30),
+      description: "Creates a generated SecureString parameter once; never returns or logs the value",
+    });
+    this.provider = new customResources.Provider(this, "Provider", { onEventHandler: onEvent });
+  }
+}
+
+/**
+ * A generated secret in SSM Parameter Store as a standard SecureString (free,
+ * AWS-managed `aws/ssm` key), instead of a Secrets Manager secret ($0.40/month).
+ *
+ * CloudFormation cannot create a SecureString, so a custom resource Lambda puts
+ * it. The Lambda generates a random value at create time and never returns or
+ * logs it, so the value is in no template, output or stack event. It is
+ * create-only: an update never regenerates it and never overwrites a parameter
+ * that already exists (a hand-made one is adopted as it is), and delete retains
+ * it, so a stack teardown cannot sign anyone out. Rotate it with
+ * `aws ssm put-parameter --overwrite`. Readers get `ssm:GetParameter` on
+ * `parameterArn` only; decrypting with the AWS-managed key needs no KMS grant.
+ */
+export class SecureStringParameter extends Construct {
+  public readonly parameterName: string;
+  public readonly parameterArn: string;
+
+  constructor(scope: Construct, id: string, props: SecureStringParameterProps) {
+    super(scope, id);
+    if (!props.parameterName.startsWith("/")) throw new Error(`SSM parameter name must be absolute: ${props.parameterName}`);
+    const length = props.length ?? 64;
+    if (!Number.isInteger(length) || length < 32) throw new Error("A generated secret must be at least 32 characters.");
+    const stack = Stack.of(this);
+    this.parameterName = props.parameterName;
+    this.parameterArn = stack.formatArn({
+      service: "ssm",
+      resource: "parameter",
+      resourceName: props.parameterName.slice(1),
+      arnFormat: ArnFormat.SLASH_RESOURCE_NAME,
+    });
+
+    const shared = SecureStringParameterProvider.of(stack);
+    shared.role.addToPolicy(new iam.PolicyStatement({
+      sid: `Put${id.replace(/[^A-Za-z0-9]/g, "")}`,
+      actions: ["ssm:PutParameter"],
+      resources: [this.parameterArn],
+    }));
+    const resource = new CustomResource(this, "Resource", {
+      serviceToken: shared.provider.serviceToken,
+      resourceType: "Custom::SecureStringParameter",
+      properties: { ParameterName: props.parameterName, Description: props.description, Length: String(length) },
+      removalPolicy: RemovalPolicy.RETAIN,
+    });
+    resource.node.addDependency(shared.role);
+  }
+}