@anthusai/papyrus 1.0.0-next.8 → 1.0.0

package/amplify/publication/s3-projection.ts

@@ -0,0 +1,201 @@
+import { Duration, RemovalPolicy, Stack } from "aws-cdk-lib";
+import * as acm from "aws-cdk-lib/aws-certificatemanager";
+import * as cloudfront from "aws-cdk-lib/aws-cloudfront";
+import type { Code } from "aws-cdk-lib/aws-lambda";
+import * as origins from "aws-cdk-lib/aws-cloudfront-origins";
+import { Effect, Policy, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import type { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
+import { SqsDestination } from "aws-cdk-lib/aws-lambda-destinations";
+import * as route53 from "aws-cdk-lib/aws-route53";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import * as sqs from "aws-cdk-lib/aws-sqs";
+import type { Construct } from "constructs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertValidPublicationConfig, type PapyrusPublicationConfig } from "../site-backend-config";
+import { addRenditionsFunction, type RenditionsFunction } from "./renditions-function";
+import { RENDITIONS_FUNCTION_NAME_ENV, type RenditionsPlan } from "./renditions-settings";
+import { addInvalidationPathAlarm } from "./invalidation-alarm";
+import { distributionIdFromArn, s3ProjectionEnvironment, s3ProjectionPolicyStatements } from "./s3-projection-settings";
+
+const redirectFunctionSourcePath = resolve(dirname(fileURLToPath(import.meta.url)), "redirect-and-index.js");
+
+export type S3ProjectionPublicationProps = Omit<PapyrusPublicationConfig, "kind"> & { kind?: "s3-projection" };
+
+export type S3ProjectionMedia = {
+  mediaBucket: s3.IBucket;
+  renditions: RenditionsPlan;
+  renditionsCode?: Code;
+};
+
+export type S3ProjectionPublication = {
+  bucket: s3.Bucket;
+  keyValueStore: cloudfront.KeyValueStore;
+  redirectFunction: cloudfront.Function;
+  deadLetterQueue: sqs.Queue;
+  distribution?: cloudfront.Distribution;
+  distributionId?: string;
+  renditions?: RenditionsFunction;
+  environment: Record<string, string>;
+  policyStatements: PolicyStatement[];
+};
+
+function createSiteBucket(scope: Construct, retainBucketOnDelete: boolean): s3.Bucket {
+  return new s3.Bucket(scope, "SiteBucket", {
+    versioned: true,
+    blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+    enforceSSL: true,
+    encryption: s3.BucketEncryption.S3_MANAGED,
+    lifecycleRules: [{ noncurrentVersionExpiration: Duration.days(90) }],
+    removalPolicy: retainBucketOnDelete ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
+    autoDeleteObjects: !retainBucketOnDelete,
+  });
+}
+
+function createDnsValidatedCertificate(
+  scope: Construct,
+  aliases: string[],
+  hostedZone: { hostedZoneId: string; hostedZoneName: string },
+): acm.ICertificate {
+  const zone = route53.HostedZone.fromHostedZoneAttributes(scope, "SiteHostedZone", {
+    hostedZoneId: hostedZone.hostedZoneId,
+    zoneName: hostedZone.hostedZoneName,
+  });
+  return new acm.DnsValidatedCertificate(scope, "SiteCertificate", {
+    domainName: aliases[0],
+    subjectAlternativeNames: aliases.slice(1),
+    hostedZone: zone,
+    region: "us-east-1",
+  });
+}
+
+function createDistribution(
+  scope: Construct,
+  props: S3ProjectionPublicationProps,
+  bucket: s3.Bucket,
+  redirectFunction: cloudfront.Function,
+): cloudfront.Distribution {
+  const aliases = props.distribution?.aliases ?? [];
+  let certificate: acm.ICertificate | undefined;
+  if (aliases.length > 0) {
+    certificate = props.distribution?.acm !== undefined
+      ? createDnsValidatedCertificate(scope, aliases, props.distribution.acm)
+      : acm.Certificate.fromCertificateArn(scope, "SiteCertificate", props.distribution?.certificateArn ?? "");
+  }
+  return new cloudfront.Distribution(scope, "SiteDistribution", {
+    defaultRootObject: "index.html",
+    httpVersion: cloudfront.HttpVersion.HTTP2_AND_3,
+    enableLogging: false,
+    domainNames: aliases.length > 0 ? aliases : undefined,
+    certificate,
+    defaultBehavior: {
+      origin: origins.S3BucketOrigin.withOriginAccessControl(bucket),
+      viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+      compress: true,
+      functionAssociations: [{ function: redirectFunction, eventType: cloudfront.FunctionEventType.VIEWER_REQUEST }],
+    },
+    errorResponses: [
+      { httpStatus: 404, responseHttpStatus: 404, responsePagePath: "/404.html" },
+      { httpStatus: 403, responseHttpStatus: 404, responsePagePath: "/404.html" },
+    ],
+  });
+}
+
+export function addS3ProjectionPublication(
+  scope: Construct,
+  props: S3ProjectionPublicationProps,
+  media?: S3ProjectionMedia,
+): S3ProjectionPublication {
+  assertValidPublicationConfig({ kind: "s3-projection", ...props });
+  const bucket = createSiteBucket(scope, props.retainBucketOnDelete !== false);
+
+  const keyValueStore = new cloudfront.KeyValueStore(scope, "RedirectsKeyValueStore");
+  const redirectFunction = new cloudfront.Function(scope, "RedirectAndIndexFunction", {
+    runtime: cloudfront.FunctionRuntime.JS_2_0,
+    code: cloudfront.FunctionCode.fromFile({ filePath: redirectFunctionSourcePath }),
+    keyValueStore,
+  });
+  const deadLetterQueue = new sqs.Queue(scope, "ProjectionDeadLetterQueue", {
+    encryption: sqs.QueueEncryption.SQS_MANAGED,
+    retentionPeriod: Duration.days(14),
+    enforceSSL: true,
+  });
+
+  const createsDistribution = props.distribution?.create === true;
+  const distribution = createsDistribution ? createDistribution(scope, props, bucket, redirectFunction) : undefined;
+
+  let distributionArn: string | undefined;
+  if (distribution !== undefined) {
+    distributionArn = distribution.distributionArn;
+  } else if (props.edgeDistributionArn !== undefined) {
+    distributionArn = props.edgeDistributionArn;
+    bucket.addToResourcePolicy(
+      new PolicyStatement({
+        effect: Effect.ALLOW,
+        principals: [new ServicePrincipal("cloudfront.amazonaws.com")],
+        actions: ["s3:GetObject"],
+        resources: [bucket.arnForObjects("*")],
+        conditions: { StringEquals: { "aws:SourceArn": props.edgeDistributionArn } },
+      }),
+    );
+  }
+
+  const renditions = media?.renditions.enabled === true
+    ? addRenditionsFunction(scope, { siteBucket: bucket, mediaBucket: media.mediaBucket, siteFiles: media.renditions.siteFiles, code: media.renditionsCode })
+    : undefined;
+
+  const settingsInput = {
+    bucketName: bucket.bucketName,
+    bucketArn: bucket.bucketArn,
+    keyValueStoreArn: keyValueStore.keyValueStoreArn,
+    deadLetterQueueUrl: deadLetterQueue.queueUrl,
+    deadLetterQueueArn: deadLetterQueue.queueArn,
+    distributionArn,
+    distributionId: distribution?.distributionId,
+    publicHostName: distribution !== undefined
+      ? (props.distribution?.aliases?.[0] ?? distribution.distributionDomainName)
+      : undefined,
+    cache: props.cache,
+    projector: props.projector,
+    staticDir: props.staticDir,
+  };
+  const invalidatedDistributionId = distribution?.distributionId
+    ?? (props.edgeDistributionArn !== undefined ? distributionIdFromArn(props.edgeDistributionArn) : undefined);
+  if (invalidatedDistributionId !== undefined && props.cache?.invalidation !== "off") {
+    addInvalidationPathAlarm(scope, "EdgeInvalidationPaths", invalidatedDistributionId);
+  }
+  return {
+    bucket,
+    keyValueStore,
+    redirectFunction,
+    deadLetterQueue,
+    distribution,
+    distributionId: distribution?.distributionId,
+    renditions,
+    environment: {
+      ...s3ProjectionEnvironment(settingsInput),
+      ...(renditions !== undefined ? { [RENDITIONS_FUNCTION_NAME_ENV]: renditions.function.functionName } : {}),
+    },
+    policyStatements: s3ProjectionPolicyStatements(settingsInput).map(
+      (statement) => new PolicyStatement({ effect: Effect.ALLOW, actions: statement.actions, resources: statement.resources }),
+    ),
+  };
+}
+
+/**
+ * The content-actions function runs a failed or follow-up projection again as an asynchronous
+ * invocation of itself: one retry, and an on-failure destination (the dead letter queue) for
+ * what still fails. The self-invoke permission is a separate policy on the role so that the
+ * function does not depend on a policy that refers to the function.
+ */
+export function addProjectionRetries(lambda: LambdaFunction, deadLetterQueue: sqs.IQueue): void {
+  lambda.configureAsyncInvoke({
+    retryAttempts: 1,
+    maxEventAge: Duration.hours(1),
+    onFailure: new SqsDestination(deadLetterQueue),
+  });
+  new Policy(Stack.of(lambda), "ContentActionsProjectionSelfInvoke", {
+    statements: [new PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [lambda.functionArn] })],
+    roles: [lambda.role!],
+  });
+}

package/amplify/resolver-waves.js

@@ -0,0 +1,26 @@
+import { NestedStack } from "aws-cdk-lib";
+export const DEFAULT_RESOLVER_WAVE_SIZE = 12;
+export function planResolverWaves(items, waveSize) {
+    if (!Number.isInteger(waveSize) || waveSize < 1) {
+        return [];
+    }
+    const waves = [];
+    for (let start = 0; start < items.length; start += waveSize) {
+        waves.push(items.slice(start, start + waveSize));
+    }
+    return waves;
+}
+export function orderModelStacksInWaves(graphqlApi, modelNames, waveSize) {
+    const modelStacks = modelNames
+        .map((modelName) => graphqlApi.node.tryFindChild(modelName))
+        .filter((child) => child instanceof NestedStack);
+    const waves = planResolverWaves(modelStacks, waveSize);
+    for (let waveIndex = 1; waveIndex < waves.length; waveIndex += 1) {
+        for (const stack of waves[waveIndex]) {
+            for (const previousStack of waves[waveIndex - 1]) {
+                stack.addDependency(previousStack);
+            }
+        }
+    }
+    return waves.length;
+}

package/amplify/resolver-waves.ts

@@ -0,0 +1,34 @@
+import { NestedStack } from "aws-cdk-lib";
+import type { IConstruct } from "constructs";
+
+export const DEFAULT_RESOLVER_WAVE_SIZE = 12;
+
+export function planResolverWaves<T>(items: T[], waveSize: number): T[][] {
+  if (!Number.isInteger(waveSize) || waveSize < 1) {
+    return [];
+  }
+  const waves: T[][] = [];
+  for (let start = 0; start < items.length; start += waveSize) {
+    waves.push(items.slice(start, start + waveSize));
+  }
+  return waves;
+}
+
+export function orderModelStacksInWaves(
+  graphqlApi: IConstruct,
+  modelNames: string[],
+  waveSize: number,
+): number {
+  const modelStacks = modelNames
+    .map((modelName) => graphqlApi.node.tryFindChild(modelName))
+    .filter((child): child is NestedStack => child instanceof NestedStack);
+  const waves = planResolverWaves(modelStacks, waveSize);
+  for (let waveIndex = 1; waveIndex < waves.length; waveIndex += 1) {
+    for (const stack of waves[waveIndex]) {
+      for (const previousStack of waves[waveIndex - 1]) {
+        stack.addDependency(previousStack);
+      }
+    }
+  }
+  return waves.length;
+}

package/amplify/revalidate-invalidation-settings.js

@@ -0,0 +1,30 @@
+/**
+ * Environment and IAM for purging our CloudFront copies of the paths a Pretext reader revalidated.
+ * Pure (no CDK imports) so it can be tested without synthesizing.
+ */
+export const REVALIDATE_DISTRIBUTION_IDS_ENV = "PAPYRUS_REVALIDATE_DISTRIBUTION_IDS";
+const CLOUDFRONT_DISTRIBUTION_ID = /^E[A-Z0-9]{8,}$/;
+export function validateRevalidateDistributionIds(ids, revalidateBaseUrl) {
+    if (ids === undefined)
+        return [];
+    if (!Array.isArray(ids) || ids.length === 0)
+        return ["revalidateDistributionIds must be a non-empty array of CloudFront distribution ids"];
+    const problems = [];
+    for (const id of ids) {
+        if (typeof id !== "string" || !CLOUDFRONT_DISTRIBUTION_ID.test(id)) {
+            problems.push(`revalidateDistributionIds entry ${JSON.stringify(id)} is not a CloudFront distribution id`);
+        }
+    }
+    if ((revalidateBaseUrl ?? "").trim() === "")
+        problems.push("revalidateDistributionIds requires revalidateBaseUrl");
+    return problems;
+}
+export function revalidateDistributionEnvironment(ids) {
+    return { [REVALIDATE_DISTRIBUTION_IDS_ENV]: ids.join(",") };
+}
+export function revalidateInvalidationStatement(input) {
+    return {
+        actions: ["cloudfront:CreateInvalidation"],
+        resources: input.distributionIds.map((id) => `arn:${input.partition}:cloudfront::${input.account}:distribution/${id}`),
+    };
+}

package/amplify/revalidate-invalidation-settings.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment and IAM for purging our CloudFront copies of the paths a Pretext reader revalidated.
+ * Pure (no CDK imports) so it can be tested without synthesizing.
+ */
+export const REVALIDATE_DISTRIBUTION_IDS_ENV = "PAPYRUS_REVALIDATE_DISTRIBUTION_IDS";
+
+const CLOUDFRONT_DISTRIBUTION_ID = /^E[A-Z0-9]{8,}$/;
+
+export function validateRevalidateDistributionIds(ids: unknown, revalidateBaseUrl: string | undefined): string[] {
+  if (ids === undefined) return [];
+  if (!Array.isArray(ids) || ids.length === 0) return ["revalidateDistributionIds must be a non-empty array of CloudFront distribution ids"];
+  const problems: string[] = [];
+  for (const id of ids) {
+    if (typeof id !== "string" || !CLOUDFRONT_DISTRIBUTION_ID.test(id)) {
+      problems.push(`revalidateDistributionIds entry ${JSON.stringify(id)} is not a CloudFront distribution id`);
+    }
+  }
+  if ((revalidateBaseUrl ?? "").trim() === "") problems.push("revalidateDistributionIds requires revalidateBaseUrl");
+  return problems;
+}
+
+export function revalidateDistributionEnvironment(ids: string[]): Record<string, string> {
+  return { [REVALIDATE_DISTRIBUTION_IDS_ENV]: ids.join(",") };
+}
+
+export function revalidateInvalidationStatement(input: {
+  partition: string;
+  account: string;
+  distributionIds: string[];
+}): { actions: string[]; resources: string[] } {
+  return {
+    actions: ["cloudfront:CreateInvalidation"],
+    resources: input.distributionIds.map((id) => `arn:${input.partition}:cloudfront::${input.account}:distribution/${id}`),
+  };
+}

package/amplify/revalidate-secret-policy.js

@@ -0,0 +1,13 @@
+/**
+ * IAM statement for the content-actions Lambda's read of the revalidate secret.
+ * Pure (no CDK imports) so the policy can be tested without synthesizing.
+ * The Lambda reads the parameter through boto3 get_parameters (plural), so the
+ * plural action must be granted alongside the singular one.
+ */
+export const REVALIDATE_SECRET_READ_ACTIONS = ["ssm:GetParameter", "ssm:GetParameters"];
+export function revalidateSecretReadStatement(input) {
+    return {
+        actions: REVALIDATE_SECRET_READ_ACTIONS,
+        resources: [`arn:${input.partition}:ssm:${input.region}:${input.account}:parameter${input.parameterName}`],
+    };
+}

package/amplify/revalidate-secret-policy.ts

@@ -0,0 +1,19 @@
+/**
+ * IAM statement for the content-actions Lambda's read of the revalidate secret.
+ * Pure (no CDK imports) so the policy can be tested without synthesizing.
+ * The Lambda reads the parameter through boto3 get_parameters (plural), so the
+ * plural action must be granted alongside the singular one.
+ */
+export const REVALIDATE_SECRET_READ_ACTIONS = ["ssm:GetParameter", "ssm:GetParameters"];
+
+export function revalidateSecretReadStatement(input: {
+  partition: string;
+  region: string;
+  account: string;
+  parameterName: string;
+}): { actions: string[]; resources: string[] } {
+  return {
+    actions: REVALIDATE_SECRET_READ_ACTIONS,
+    resources: [`arn:${input.partition}:ssm:${input.region}:${input.account}:parameter${input.parameterName}`],
+  };
+}

package/amplify/site-backend-config.js

@@ -1 +1,65 @@
-export {};
+export const MAXIMUM_HTML_S_MAXAGE_SECONDS = 86400;
+const CLOUDFRONT_DISTRIBUTION_ARN = /^arn:aws[a-z-]*:cloudfront::\d{12}:distribution\/[A-Z0-9]+$/;
+function isRelativePathWithoutParentSegments(value) {
+    if (value === "" || value.startsWith("/") || value.includes("\\"))
+        return false;
+    return !value.split("/").includes("..");
+}
+export function validatePublicationConfig(publication) {
+    const problems = [];
+    if (typeof publication !== "object" || publication === null) {
+        return ["publication must be an object"];
+    }
+    const config = publication;
+    if (config.kind !== "s3-projection") {
+        problems.push(`publication.kind must be "s3-projection" (got ${JSON.stringify(config.kind)})`);
+    }
+    if (config.projector !== undefined) {
+        if (typeof config.projector !== "string" || !isRelativePathWithoutParentSegments(config.projector) || !config.projector.endsWith(".py")) {
+            problems.push("publication.projector must be a relative .py path without '..'");
+        }
+    }
+    if (config.staticDir !== undefined) {
+        if (typeof config.staticDir !== "string" || !isRelativePathWithoutParentSegments(config.staticDir)) {
+            problems.push("publication.staticDir must be a relative path without '..'");
+        }
+    }
+    if (config.edgeDistributionArn !== undefined && !CLOUDFRONT_DISTRIBUTION_ARN.test(config.edgeDistributionArn)) {
+        problems.push("publication.edgeDistributionArn must be a CloudFront distribution ARN (arn:aws:cloudfront::<account>:distribution/<id>)");
+    }
+    if (config.reprojectOnDeploy !== undefined && typeof config.reprojectOnDeploy !== "boolean") {
+        problems.push("publication.reprojectOnDeploy must be a boolean");
+    }
+    const cache = config.cache;
+    if (cache !== undefined) {
+        const lifetime = cache.htmlSMaxAgeSeconds;
+        if (lifetime !== undefined && (!Number.isInteger(lifetime) || lifetime < 0 || lifetime > MAXIMUM_HTML_S_MAXAGE_SECONDS)) {
+            problems.push(`publication.cache.htmlSMaxAgeSeconds must be an integer from 0 to ${MAXIMUM_HTML_S_MAXAGE_SECONDS}`);
+        }
+        if (cache.invalidation !== undefined && cache.invalidation !== "targeted" && cache.invalidation !== "off") {
+            problems.push('publication.cache.invalidation must be "targeted" or "off"');
+        }
+    }
+    const distribution = config.distribution;
+    if (distribution !== undefined) {
+        if (config.edgeDistributionArn !== undefined && distribution.create === true) {
+            problems.push("publication.edgeDistributionArn and publication.distribution.create are mutually exclusive");
+        }
+        const aliases = distribution.aliases ?? [];
+        if (aliases.length > 0 && distribution.create !== true) {
+            problems.push("publication.distribution.aliases require distribution.create to be true");
+        }
+        if (aliases.length > 0 && !distribution.certificateArn && !distribution.acm) {
+            problems.push("publication.distribution.aliases require certificateArn or acm");
+        }
+        if (distribution.acm !== undefined && (!distribution.acm.hostedZoneId || !distribution.acm.hostedZoneName)) {
+            problems.push("publication.distribution.acm requires hostedZoneId and hostedZoneName");
+        }
+    }
+    return problems;
+}
+export function assertValidPublicationConfig(publication) {
+    const problems = validatePublicationConfig(publication);
+    if (problems.length > 0)
+        throw new Error(`Invalid backend.publication: ${problems.join("; ")}`);
+}

package/amplify/site-backend-config.ts

@@ -1,3 +1,5 @@
+import type { PluginRequest } from "./plugins/types";
+
 /**
  * Per-site backend configuration: the argument of `defineSiteBackend(site)`.
  * Config is passed in; the environment is only a fallback so Papyrus's own
@@ -7,10 +9,125 @@ export type PapyrusAuthConfig = {
   /** OAuth callback/logout URLs for Google sign-in (ignored when Google is disabled). */
   redirectUrls?: string[];
   disableGoogleOAuth?: boolean;
-  /** Stable Cognito hosted-UI domain prefix. */
+  /**
+   * Public newsroom path prefix for sign-in return URLs. Default `/newsroom`;
+   * `""` on a CMS-only host where the newsroom is the root. Filled from the
+   * active brand's `newsroomBasePath` by `defineSiteBackend` when unset.
+   */
+  newsroomBasePath?: string;
+  /** Desired Cognito hosted-UI domain prefix. Only applied when `applyCognitoDomainPrefix` is true. */
   cognitoDomainPrefix?: string;
+  /**
+   * Opt in to the prefix. Off by default because changing a live pool's
+   * domain replaces it and changes the Google redirect URI.
+   */
+  applyCognitoDomainPrefix?: boolean;
+};
+
+export type S3ProjectionDistributionConfig = {
+  create: boolean;
+  aliases?: string[];
+  certificateArn?: string;
+  acm?: { hostedZoneId: string; hostedZoneName: string };
 };
 
+export type PapyrusPublicationCacheConfig = {
+  /** Shared-cache lifetime (seconds) of projected HTML. Default 300 with targeted invalidation, 60 with `invalidation: "off"`. */
+  htmlSMaxAgeSeconds?: number;
+  /** `targeted` (default): purge exactly the written paths after each projection. `off`: rely on the short lifetime alone. */
+  invalidation?: "targeted" | "off";
+};
+
+export const MAXIMUM_HTML_S_MAXAGE_SECONDS = 86400;
+
+export type PapyrusPublicationConfig = {
+  kind: "s3-projection";
+  /** Site repo path (relative, `.py`) of the SiteProjector bundled into content-actions as `site_projector`. */
+  projector?: string;
+  /** Site repo directory (relative) bundled into content-actions as `site_static/`. */
+  staticDir?: string;
+  /** Existing CloudFront distribution that reads the site bucket through OAC. */
+  edgeDistributionArn?: string;
+  /** Edge cache lifetime of projected HTML and whether each projection purges the edge. */
+  cache?: PapyrusPublicationCacheConfig;
+  /** Create the distribution (and optionally its certificate) in the site backend. Default: not created. */
+  distribution?: S3ProjectionDistributionConfig;
+  /** Default true: the site bucket is retained when the stack is deleted. `false` destroys it and its objects. */
+  retainBucketOnDelete?: boolean;
+  /**
+   * Re-project every published page after each backend deploy, so a theme or code change reaches the
+   * site without a manual `papyrus ops content project --all`. Default: true for the publication a
+   * Markus site gets when it sets none, false when `publication` is written out in the site config.
+   */
+  reprojectOnDeploy?: boolean;
+};
+
+const CLOUDFRONT_DISTRIBUTION_ARN = /^arn:aws[a-z-]*:cloudfront::\d{12}:distribution\/[A-Z0-9]+$/;
+
+function isRelativePathWithoutParentSegments(value: string): boolean {
+  if (value === "" || value.startsWith("/") || value.includes("\\")) return false;
+  return !value.split("/").includes("..");
+}
+
+export function validatePublicationConfig(publication: unknown): string[] {
+  const problems: string[] = [];
+  if (typeof publication !== "object" || publication === null) {
+    return ["publication must be an object"];
+  }
+  const config = publication as Partial<PapyrusPublicationConfig> & { kind?: unknown };
+  if (config.kind !== "s3-projection") {
+    problems.push(`publication.kind must be "s3-projection" (got ${JSON.stringify(config.kind)})`);
+  }
+  if (config.projector !== undefined) {
+    if (typeof config.projector !== "string" || !isRelativePathWithoutParentSegments(config.projector) || !config.projector.endsWith(".py")) {
+      problems.push("publication.projector must be a relative .py path without '..'");
+    }
+  }
+  if (config.staticDir !== undefined) {
+    if (typeof config.staticDir !== "string" || !isRelativePathWithoutParentSegments(config.staticDir)) {
+      problems.push("publication.staticDir must be a relative path without '..'");
+    }
+  }
+  if (config.edgeDistributionArn !== undefined && !CLOUDFRONT_DISTRIBUTION_ARN.test(config.edgeDistributionArn)) {
+    problems.push("publication.edgeDistributionArn must be a CloudFront distribution ARN (arn:aws:cloudfront::<account>:distribution/<id>)");
+  }
+  if (config.reprojectOnDeploy !== undefined && typeof config.reprojectOnDeploy !== "boolean") {
+    problems.push("publication.reprojectOnDeploy must be a boolean");
+  }
+  const cache = config.cache;
+  if (cache !== undefined) {
+    const lifetime = cache.htmlSMaxAgeSeconds;
+    if (lifetime !== undefined && (!Number.isInteger(lifetime) || lifetime < 0 || lifetime > MAXIMUM_HTML_S_MAXAGE_SECONDS)) {
+      problems.push(`publication.cache.htmlSMaxAgeSeconds must be an integer from 0 to ${MAXIMUM_HTML_S_MAXAGE_SECONDS}`);
+    }
+    if (cache.invalidation !== undefined && cache.invalidation !== "targeted" && cache.invalidation !== "off") {
+      problems.push('publication.cache.invalidation must be "targeted" or "off"');
+    }
+  }
+  const distribution = config.distribution;
+  if (distribution !== undefined) {
+    if (config.edgeDistributionArn !== undefined && distribution.create === true) {
+      problems.push("publication.edgeDistributionArn and publication.distribution.create are mutually exclusive");
+    }
+    const aliases = distribution.aliases ?? [];
+    if (aliases.length > 0 && distribution.create !== true) {
+      problems.push("publication.distribution.aliases require distribution.create to be true");
+    }
+    if (aliases.length > 0 && !distribution.certificateArn && !distribution.acm) {
+      problems.push("publication.distribution.aliases require certificateArn or acm");
+    }
+    if (distribution.acm !== undefined && (!distribution.acm.hostedZoneId || !distribution.acm.hostedZoneName)) {
+      problems.push("publication.distribution.acm requires hostedZoneId and hostedZoneName");
+    }
+  }
+  return problems;
+}
+
+export function assertValidPublicationConfig(publication: unknown): void {
+  const problems = validatePublicationConfig(publication);
+  if (problems.length > 0) throw new Error(`Invalid backend.publication: ${problems.join("; ")}`);
+}
+
 export type PapyrusSiteBackendConfig = {
   /** Brand id; namespaces account-global resources (S3 Vectors index name). */
   brandId?: string;
@@ -21,12 +138,46 @@ export type PapyrusSiteBackendConfig = {
    */
   productionAppId?: string;
   auth?: PapyrusAuthConfig;
+  /**
+   * Maximum number of data model nested stacks CloudFormation creates at once.
+   * Stacks are chained in waves of this size so a new AWS account is not hit
+   * with every AppSync CreateResolver call in parallel (429). Only adds
+   * DependsOn ordering; no resource changes. Default 12; 0 turns it off.
+   */
+  resolverWaveSize?: number;
   /** Static reader app (Markus-static sites) that a publish rebuilds through IAM `amplify:StartJob`. */
   reader?: { amplifyAppId: string; branchName?: string };
   /** Lets the newsroom start the `staging` branch build of this CMS app. */
   stagingBuild?: { enabled: boolean };
-  /** Base URL of a Pretext reader whose `/api/revalidate` a publish calls (secret `PAPYRUS_REVALIDATE_SECRET`). */
+  /** Base URL of a Pretext reader whose `/api/revalidate` a publish calls (authenticated by the SSM secret named in branch variable `PAPYRUS_REVALIDATE_SECRET_PARAMETER`). */
   revalidateBaseUrl?: string;
+  /**
+   * CloudFront distribution ids (same account) in front of that reader. After a publish refreshes the reader's
+   * cache, content-actions invalidates the revalidated paths on each of them. Needs `revalidateBaseUrl`.
+   */
+  revalidateDistributionIds?: string[];
+  /**
+   * SES receipt options for a site that is not the legacy p.apyr.us backend.
+   * By default the site gets its own brand-named rule set that is never
+   * activated by CloudFormation (SES allows one active rule set per region).
+   */
+  inboundEmailSes?: {
+    /** Add this site's rule to a rule set another stack owns instead of creating one. */
+    existingReceiptRuleSetName?: string;
+    /** Let this stack verify the SES domain identity and write its TXT record. Default false: verify once by hand. */
+    manageDomainIdentity?: boolean;
+  };
+  /**
+   * Static projection of published pages into an S3 site bucket. Unset: a Markus site without a
+   * `reader` gets `{ kind: "s3-projection" }`; any other site gets nothing. `false` opts a Markus
+   * site out. See `resolveSitePublication`.
+   */
+  publication?: PapyrusPublicationConfig | false;
+  /**
+   * Deploy-time plugins (docs/plugins.md): `["signup"]`, or `[{ name: "signup", forms: ["news"] }]`.
+   * Unset: no plugin, and the synthesized backend is exactly what it was before plugins existed.
+   */
+  plugins?: PluginRequest[];
   features?: {
     consoleResponder?: boolean;
     inboundEmail?: boolean;