@anthusai/papyrus 2.0.0-next.8 → 2.0.0-next.81

package/infra/amplify-app-shell.js

@@ -1,10 +1,12 @@
 import { ArnFormat, CfnOutput, Duration, Fn, Stack } 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.js";
+import { addCloudEmail } from "./cloud-email.js";
+import { parseCloudEmail } from "./cloud-email-config.js";
 import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider.js";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs.js";
-import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveProspectusAccountsEndpoint, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
+import { PROSPECTUS_PAPYRUS_SITE_ROUTES, hasCmsApp, isStagingEnabled, resolveRedirectSubDomainPrefix, resolveCmsHostName, resolveSiteOrigin, githubOidcSubjects, resolveGithubRepository, resolveProspectusAccountsEndpoint, resolveProspectusSessionSealingParameterName, resolveReaderPollSecretParameterName, resolveRevalidateSecretParameterName, resolveStackName, resolveStagingDomainName, resolveStoragePreviewPrefix } from "./site-config.js";
 function environmentVariables(variables) {
     return Object.entries(variables).map(([name, value]) => ({ name, value }));
 }
@@ -68,9 +70,13 @@ export class AmplifyAppShellStack extends Stack {
             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;
         }
         const cmsAppName = config.cms.appName ?? `${config.siteId}-cms`;
+        const emailEnvironment = addCloudEmail(this, parseCloudEmail(config.email, true, config.siteId));
         const stagingEnabled = isStagingEnabled(config);
         const stagingDomainName = resolveStagingDomainName(config);
         const cmsHostName = resolveCmsHostName(config);
@@ -89,33 +95,49 @@ 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 = 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],
             }));
         }
         if (prospectusAccountsApiStageArn) {
@@ -153,9 +175,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
@@ -165,15 +193,18 @@ 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,
+                ...emailEnvironment,
                 PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
                 ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
                 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,
@@ -195,6 +226,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
@@ -247,6 +279,12 @@ 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);
         }
@@ -294,6 +332,46 @@ export class AmplifyAppShellStack extends Stack {
             description: `Role the Papyrus CLI assumes for ${config.siteId} (profile role_arn)`,
         });
     }
+    /**
+     * 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.
+     */
+    addGithubDeployRole(config, targets) {
+        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}`,
+        });
+    }
     addGithubCiRole(config, github, cmsAppId, amplifyAppIds) {
         const provider = iam.OpenIdConnectProvider.fromOpenIdConnectProviderArn(this, "GithubOidcProvider", this.formatArn({
             service: "iam",
@@ -309,7 +387,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)),
                 },
             }),
         });
@@ -361,7 +439,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/amplify-app-shell.ts

@@ -2,10 +2,12 @@ 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 { addCloudEmail } from "./cloud-email";
+import { parseCloudEmail } from "./cloud-email-config";
 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,10 +74,14 @@ 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;
     }
 
     const cmsAppName = config.cms.appName ?? `${config.siteId}-cms`;
+    const emailEnvironment = addCloudEmail(this, parseCloudEmail(config.email, true, config.siteId)!);
     const stagingEnabled = isStagingEnabled(config);
     const stagingDomainName = resolveStagingDomainName(config);
     const cmsHostName = resolveCmsHostName(config);
@@ -97,37 +103,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 +196,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,15 +215,18 @@ 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,
+        ...emailEnvironment,
         PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
         ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
         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 +249,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 +308,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 +367,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 +441,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 +508,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/cloud-email-config.js

@@ -0,0 +1,32 @@
+export function parseCloudEmail(raw, cloud, siteId) {
+    if (!cloud) {
+        if (raw !== undefined)
+            throw new Error("site.json: email requires a cloud cms; static-only sites do not need email resources");
+        return undefined;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("site.json: email is required for cloud sites; configure mode managed or existing and an explicit sendingDomain (see docs/email-reference-intake.md)");
+    }
+    const value = raw;
+    for (const key of Object.keys(value)) {
+        if (!["mode", "sendingDomain", "senderLocalPart", "configurationSet", "eventTopicName"].includes(key)) {
+            throw new Error(`site.json: email.${key} is not a known field`);
+        }
+    }
+    if (value.mode !== "managed" && value.mode !== "existing")
+        throw new Error("site.json: email.mode must be managed or existing");
+    const string = (key, pattern, fallback) => {
+        const result = value[key] ?? fallback;
+        if (typeof result !== "string" || !pattern.test(result))
+            throw new Error(`site.json: email.${key} is required and must be valid`);
+        return result;
+    };
+    return {
+        mode: value.mode,
+        sendingDomain: string("sendingDomain", /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/),
+        senderLocalPart: string("senderLocalPart", /^[a-z0-9][a-z0-9._+-]{0,63}$/, "notifications"),
+        configurationSet: string("configurationSet", /^[A-Za-z0-9_-]{1,64}$/, value.mode === "managed" ? `papyrus-${siteId}` : undefined),
+        // Preserve the newsletter consumer's historical default; the topic now also serves notifications.
+        eventTopicName: string("eventTopicName", /^[A-Za-z0-9_-]{1,256}$/, value.mode === "managed" ? `papyrus-newsletter-events-${siteId}` : undefined),
+    };
+}

package/infra/cloud-email-config.ts

@@ -0,0 +1,39 @@
+/** Email belongs to a cloud site, independently of any newsletter plugin. */
+export type CloudEmailConfig = {
+  mode: "managed" | "existing";
+  sendingDomain: string;
+  senderLocalPart: string;
+  configurationSet: string;
+  eventTopicName: string;
+};
+
+export function parseCloudEmail(raw: unknown, cloud: boolean, siteId: string): CloudEmailConfig | undefined {
+  if (!cloud) {
+    if (raw !== undefined) throw new Error("site.json: email requires a cloud cms; static-only sites do not need email resources");
+    return undefined;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("site.json: email is required for cloud sites; configure mode managed or existing and an explicit sendingDomain (see docs/email-reference-intake.md)");
+  }
+  const value = raw as Record<string, unknown>;
+  for (const key of Object.keys(value)) {
+    if (!["mode", "sendingDomain", "senderLocalPart", "configurationSet", "eventTopicName"].includes(key)) {
+      throw new Error(`site.json: email.${key} is not a known field`);
+    }
+  }
+  if (value.mode !== "managed" && value.mode !== "existing") throw new Error("site.json: email.mode must be managed or existing");
+  const string = (key: string, pattern: RegExp, fallback?: string) => {
+    const result = value[key] ?? fallback;
+    if (typeof result !== "string" || !pattern.test(result)) throw new Error(`site.json: email.${key} is required and must be valid`);
+    return result;
+  };
+  return {
+    mode: value.mode,
+    sendingDomain: string("sendingDomain", /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/),
+    senderLocalPart: string("senderLocalPart", /^[a-z0-9][a-z0-9._+-]{0,63}$/, "notifications"),
+    configurationSet: string("configurationSet", /^[A-Za-z0-9_-]{1,64}$/, value.mode === "managed" ? `papyrus-${siteId}` : undefined),
+    // Preserve the newsletter consumer's historical default; the topic now also serves notifications.
+    eventTopicName: string("eventTopicName", /^[A-Za-z0-9_-]{1,256}$/, value.mode === "managed" ? `papyrus-newsletter-events-${siteId}` : undefined),
+  };
+}
+

package/infra/cloud-email.js

@@ -0,0 +1,57 @@
+import { ArnFormat, CfnOutput, RemovalPolicy } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as ses from "aws-cdk-lib/aws-ses";
+import * as sns from "aws-cdk-lib/aws-sns";
+/** No DNS mutation, sending grant or receipt activation. Existing identities remain with their owner. */
+export function addCloudEmail(stack, config) {
+    if (config.mode === "managed") {
+        const configurationSet = new ses.CfnConfigurationSet(stack, "CloudEmailConfigurationSet", {
+            name: config.configurationSet,
+            reputationOptions: { reputationMetricsEnabled: true },
+            suppressionOptions: { suppressedReasons: ["BOUNCE", "COMPLAINT"] },
+            sendingOptions: { sendingEnabled: true },
+        });
+        configurationSet.applyRemovalPolicy(RemovalPolicy.RETAIN);
+        const identity = new ses.CfnEmailIdentity(stack, "CloudEmailIdentity", {
+            emailIdentity: config.sendingDomain,
+            dkimSigningAttributes: { nextSigningKeyLength: "RSA_2048_BIT" },
+            configurationSetAttributes: { configurationSetName: configurationSet.ref },
+        });
+        identity.applyRemovalPolicy(RemovalPolicy.RETAIN);
+        const topic = new sns.Topic(stack, "CloudEmailEvents", { topicName: config.eventTopicName });
+        topic.applyRemovalPolicy(RemovalPolicy.RETAIN);
+        topic.addToResourcePolicy(new iam.PolicyStatement({
+            principals: [new iam.ServicePrincipal("ses.amazonaws.com")], actions: ["sns:Publish"],
+            resources: [topic.topicArn], conditions: { StringEquals: { "aws:SourceAccount": stack.account } },
+        }));
+        const events = new ses.CfnConfigurationSetEventDestination(stack, "CloudEmailEventDestination", {
+            configurationSetName: configurationSet.ref,
+            eventDestination: { name: "delivery-events", enabled: true,
+                matchingEventTypes: ["SEND", "DELIVERY", "BOUNCE", "COMPLAINT", "REJECT", "RENDERING_FAILURE", "DELIVERY_DELAY"],
+                snsDestination: { topicArn: topic.topicArn } },
+        });
+        events.node.addDependency(topic);
+        // These dimensions also feed the newsletter consumer's existing bounce/complaint alarms.
+        new ses.CfnConfigurationSetEventDestination(stack, "CloudEmailMetrics", {
+            configurationSetName: configurationSet.ref,
+            eventDestination: { name: "cloudwatch-metrics", enabled: true,
+                matchingEventTypes: ["SEND", "BOUNCE", "COMPLAINT"],
+                cloudWatchDestination: { dimensionConfigurations: [{ dimensionName: "ses:configuration-set",
+                            dimensionValueSource: "MESSAGE_TAG", defaultDimensionValue: config.configurationSet }] } },
+        });
+        const records = [[identity.attrDkimDnsTokenName1, identity.attrDkimDnsTokenValue1],
+            [identity.attrDkimDnsTokenName2, identity.attrDkimDnsTokenValue2],
+            [identity.attrDkimDnsTokenName3, identity.attrDkimDnsTokenValue3]];
+        records.forEach(([name, value], index) => {
+            new CfnOutput(stack, `EmailDkimRecord${index + 1}Name`, { value: name, description: "CNAME name; DNS change requires separate approval" });
+            new CfnOutput(stack, `EmailDkimRecord${index + 1}Value`, { value });
+        });
+    }
+    const identityArn = stack.formatArn({ service: "ses", resource: "identity", resourceName: config.sendingDomain, arnFormat: ArnFormat.SLASH_RESOURCE_NAME });
+    new CfnOutput(stack, "EmailIdentityArn", { value: identityArn });
+    new CfnOutput(stack, "EmailConfigurationSetName", { value: config.configurationSet });
+    new CfnOutput(stack, "EmailEventTopicName", { value: config.eventTopicName });
+    return { PAPYRUS_EMAIL_FROM_ADDRESS: `${config.senderLocalPart}@${config.sendingDomain}`,
+        PAPYRUS_EMAIL_IDENTITY_ARN: identityArn, PAPYRUS_EMAIL_CONFIGURATION_SET: config.configurationSet,
+        PAPYRUS_EMAIL_EVENT_TOPIC_NAME: config.eventTopicName };
+}

package/infra/cloud-email.test.js

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { App } from "aws-cdk-lib";
+import { Template } from "aws-cdk-lib/assertions";
+import { AmplifyAppShellStack } from "./amplify-app-shell.js";
+import { parseSiteConfig } from "./site-config.js";
+const base = () => ({
+    siteId: "example", repository: "https://github.com/example/publication", brand: "example",
+    frontend: "markus-static", papyrusVersion: "5.32.0", autoDeploy: false,
+    cms: { cognitoDomainPrefix: "example-cms", staging: false,
+        environment: { PAPYRUS_OAUTH_REDIRECT_URLS: "http://localhost:3001/" } },
+});
+function synth(raw) {
+    const app = new App();
+    return Template.fromStack(new AmplifyAppShellStack(app, "EmailTest", parseSiteConfig(raw), {
+        env: { account: "123456789012", region: "us-east-1" },
+    }));
+}
+const checks = {
+    managed() {
+        const template = synth({ ...base(), email: { mode: "managed", sendingDomain: "news.example.test" } });
+        template.resourceCountIs("AWS::SES::EmailIdentity", 1);
+        template.resourceCountIs("AWS::SES::ConfigurationSet", 1);
+        template.resourceCountIs("AWS::Route53::RecordSet", 0);
+        template.resourceCountIs("AWS::SES::ReceiptRuleSet", 0);
+        template.hasResourceProperties("AWS::SES::EmailIdentity", { EmailIdentity: "news.example.test" });
+        template.hasResourceProperties("AWS::SNS::Topic", { TopicName: "papyrus-newsletter-events-example" });
+        template.hasResourceProperties("AWS::SES::ConfigurationSetEventDestination", {
+            EventDestination: { Name: "cloudwatch-metrics", MatchingEventTypes: ["SEND", "BOUNCE", "COMPLAINT"],
+                CloudWatchDestination: { DimensionConfigurations: [{ DimensionName: "ses:configuration-set",
+                            DimensionValueSource: "MESSAGE_TAG", DefaultDimensionValue: "papyrus-example" }] } },
+        });
+        const text = JSON.stringify(template.toJSON());
+        assert.ok(text.includes("PAPYRUS_EMAIL_FROM_ADDRESS"));
+        assert.ok(text.includes("notifications@news.example.test"));
+        assert.ok(text.includes("EmailDkimRecord1Name"));
+        assert.ok(!text.includes("ses:SendEmail"), "identity setup does not grant unsolicited sending authority");
+    },
+    existing() {
+        const template = synth({ ...base(), email: { mode: "existing", sendingDomain: "news.example.test",
+                configurationSet: "already-owned", eventTopicName: "already-owned-events" } });
+        template.resourceCountIs("AWS::SES::EmailIdentity", 0);
+        template.resourceCountIs("AWS::SES::ConfigurationSet", 0);
+        template.resourceCountIs("AWS::SNS::Topic", 0);
+        assert.ok(JSON.stringify(template.toJSON()).includes("already-owned"));
+    },
+    static() {
+        const raw = { ...base(), reader: { buildCommand: "make site", baseDirectory: "dist" } };
+        delete raw.cms;
+        const template = synth(raw);
+        template.resourceCountIs("AWS::SES::EmailIdentity", 0);
+        template.resourceCountIs("AWS::SES::ConfigurationSet", 0);
+        template.resourceCountIs("AWS::SES::ReceiptRule", 0);
+    },
+    missing() {
+        assert.throws(() => parseSiteConfig(base()), /email.*required.*cloud/i);
+        assert.throws(() => parseSiteConfig({ ...base(), email: { mode: "existing", sendingDomain: "news.example.test" } }), /email.configurationSet/);
+    },
+};
+export function runCloudEmailTests(selected) {
+    if (selected) {
+        assert.ok(checks[selected], selected);
+        checks[selected]();
+    }
+    else
+        for (const check of Object.values(checks))
+            check();
+    console.log("cloud email infrastructure: ok");
+}
+runCloudEmailTests(process.argv[2]);