@anthusai/papyrus 1.0.0-next.9 → 1.1.0

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;

package/amplify/site-backend-names.js

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { Token } from "aws-cdk-lib";
+export function sanitizeAwsName(value, maxLength = 50) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, maxLength);
+}
+/**
+ * Account-global names are immutable in AWS, so they must be built from literal
+ * synth-time inputs only. A CDK token (or text that came from one, such as
+ * `token-token-17565`) makes the name change on every synth and fail with
+ * AlreadyExists, so this throws instead.
+ */
+export function assertLiteralResourceName(label, name) {
+    if (Token.isUnresolved(name) || /token|\$\{/i.test(name)) {
+        throw new Error(`${label} "${name}" is derived from an unresolved CDK token. Build account-global names from literal site config values only.`);
+    }
+    return name;
+}
+export function readBooleanEnvFlag(environment, name, defaultValue) {
+    const raw = (environment[name] ?? "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(raw))
+        return true;
+    if (["0", "false", "no", "off"].includes(raw))
+        return false;
+    return defaultValue;
+}
+/**
+ * True only for the Amplify app that owns the original p.apyr.us backend. That
+ * backend keeps its historical account-global names so its live resources are
+ * never replaced. Every other site gets brand-scoped names.
+ */
+export function isLegacyProductionApp(identity) {
+    return identity.productionAppId !== "" && identity.amplifyAppId === identity.productionAppId;
+}
+export function isLegacyProductionPipeline(identity) {
+    return isLegacyProductionApp(identity) && identity.amplifyBranch === "main";
+}
+export function resolveSiteBackendFeatureFlags(features, environment, identity) {
+    const legacyPipeline = isLegacyProductionPipeline(identity);
+    return {
+        consoleResponder: features?.consoleResponder ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_CONSOLE_RESPONDER", true),
+        inboundEmail: features?.inboundEmail ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_INBOUND_EMAIL", legacyPipeline),
+        slack: features?.slack ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_SLACK", false),
+        storageBackups: features?.storageBackups ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_STORAGE_BACKUPS", legacyPipeline),
+    };
+}
+export function deriveKnowledgeVectorIndexName(identity) {
+    const name = isLegacyProductionApp(identity)
+        ? "papyrus-knowledge"
+        : `papyrus-knowledge-${sanitizeAwsName(identity.brandId, 40)}`;
+    return assertLiteralResourceName("Knowledge vector index name", name);
+}
+export function deriveStorageBackupVaultName(identity, explicitName) {
+    const explicit = (explicitName ?? "").trim();
+    if (explicit !== "")
+        return assertLiteralResourceName("Backup vault name", sanitizeAwsName(explicit));
+    if (isLegacyProductionPipeline(identity)) {
+        return assertLiteralResourceName("Backup vault name", sanitizeAwsName(`papyrus-${identity.productionAppId}-main-media-backup-vault`));
+    }
+    const literalSiteKey = [identity.brandId, identity.amplifyAppId, identity.amplifyBranch].join("|");
+    const siteHash = createHash("sha256").update(literalSiteKey).digest("hex").slice(0, 8);
+    return assertLiteralResourceName("Backup vault name", `papyrus-${sanitizeAwsName(identity.brandId, 20)}-${siteHash}-media-vault`);
+}
+/**
+ * The `papyrus-site-inbound-` prefix keeps a brand named `p-apyr-us` from
+ * colliding with the legacy `papyrus-inbound-p-apyr-us` set.
+ * SES allows one ACTIVE receipt rule set per region. A non-legacy site creates
+ * its own brand-named rule set and never activates it from CloudFormation.
+ */
+export function deriveReceiptRuleSetName(identity, inboundEmailDomain) {
+    const name = isLegacyProductionApp(identity)
+        ? `papyrus-inbound-${inboundEmailDomain.replace(/\./g, "-")}`
+        : `papyrus-site-inbound-${sanitizeAwsName(identity.brandId, 40)}`;
+    return assertLiteralResourceName("Receipt rule set name", name);
+}
+/** `undefined` keeps the legacy auto-generated rule name of the live p.apyr.us rule. */
+export function deriveReceiptRuleName(identity) {
+    if (isLegacyProductionApp(identity))
+        return undefined;
+    return assertLiteralResourceName("Receipt rule name", `${sanitizeAwsName(identity.brandId, 40)}-inbound-submissions`);
+}
+export function planInboundEmailSes(identity, inboundEmailEnabled, options) {
+    const legacyPipeline = isLegacyProductionPipeline(identity);
+    const deployedMainBranch = identity.amplifyAppId !== "" && identity.amplifyBranch === "main";
+    const createReceiptRules = inboundEmailEnabled && (legacyPipeline || deployedMainBranch);
+    return {
+        createReceiptRules,
+        activateReceiptRuleSet: createReceiptRules && legacyPipeline,
+        manageDomainIdentity: createReceiptRules && (legacyPipeline || options?.manageDomainIdentity === true),
+    };
+}
+export function deriveSiteGlobalResourceNames(identity, inboundEmailDomain) {
+    return {
+        knowledgeVectorIndexName: deriveKnowledgeVectorIndexName(identity),
+        storageBackupVaultName: deriveStorageBackupVaultName(identity),
+        receiptRuleSetName: deriveReceiptRuleSetName(identity, inboundEmailDomain),
+        receiptRuleName: deriveReceiptRuleName(identity),
+    };
+}

package/amplify/site-backend-names.ts

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { Token } from "aws-cdk-lib";
+
+export type SiteBackendFeatureFlags = {
+  consoleResponder: boolean;
+  inboundEmail: boolean;
+  slack: boolean;
+  storageBackups: boolean;
+};
+
+export type SiteBackendFeatureInput = Partial<SiteBackendFeatureFlags> | undefined;
+
+export function sanitizeAwsName(value: string, maxLength = 50): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, maxLength);
+}
+
+/**
+ * Account-global names are immutable in AWS, so they must be built from literal
+ * synth-time inputs only. A CDK token (or text that came from one, such as
+ * `token-token-17565`) makes the name change on every synth and fail with
+ * AlreadyExists, so this throws instead.
+ */
+export function assertLiteralResourceName(label: string, name: string): string {
+  if (Token.isUnresolved(name) || /token|\$\{/i.test(name)) {
+    throw new Error(
+      `${label} "${name}" is derived from an unresolved CDK token. Build account-global names from literal site config values only.`,
+    );
+  }
+  return name;
+}
+
+export function readBooleanEnvFlag(
+  environment: Record<string, string | undefined>,
+  name: string,
+  defaultValue: boolean,
+): boolean {
+  const raw = (environment[name] ?? "").trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(raw)) return true;
+  if (["0", "false", "no", "off"].includes(raw)) return false;
+  return defaultValue;
+}
+
+export type SiteBackendIdentity = {
+  brandId: string;
+  amplifyAppId: string;
+  amplifyBranch: string;
+  productionAppId: string;
+};
+
+/**
+ * True only for the Amplify app that owns the original p.apyr.us backend. That
+ * backend keeps its historical account-global names so its live resources are
+ * never replaced. Every other site gets brand-scoped names.
+ */
+export function isLegacyProductionApp(identity: SiteBackendIdentity): boolean {
+  return identity.productionAppId !== "" && identity.amplifyAppId === identity.productionAppId;
+}
+
+export function isLegacyProductionPipeline(identity: SiteBackendIdentity): boolean {
+  return isLegacyProductionApp(identity) && identity.amplifyBranch === "main";
+}
+
+export function resolveSiteBackendFeatureFlags(
+  features: SiteBackendFeatureInput,
+  environment: Record<string, string | undefined>,
+  identity: SiteBackendIdentity,
+): SiteBackendFeatureFlags {
+  const legacyPipeline = isLegacyProductionPipeline(identity);
+  return {
+    consoleResponder:
+      features?.consoleResponder ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_CONSOLE_RESPONDER", true),
+    inboundEmail:
+      features?.inboundEmail ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_INBOUND_EMAIL", legacyPipeline),
+    slack: features?.slack ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_SLACK", false),
+    storageBackups:
+      features?.storageBackups ?? readBooleanEnvFlag(environment, "PAPYRUS_ENABLE_STORAGE_BACKUPS", legacyPipeline),
+  };
+}
+
+export function deriveKnowledgeVectorIndexName(identity: SiteBackendIdentity): string {
+  const name = isLegacyProductionApp(identity)
+    ? "papyrus-knowledge"
+    : `papyrus-knowledge-${sanitizeAwsName(identity.brandId, 40)}`;
+  return assertLiteralResourceName("Knowledge vector index name", name);
+}
+
+export function deriveStorageBackupVaultName(identity: SiteBackendIdentity, explicitName?: string): string {
+  const explicit = (explicitName ?? "").trim();
+  if (explicit !== "") return assertLiteralResourceName("Backup vault name", sanitizeAwsName(explicit));
+  if (isLegacyProductionPipeline(identity)) {
+    return assertLiteralResourceName(
+      "Backup vault name",
+      sanitizeAwsName(`papyrus-${identity.productionAppId}-main-media-backup-vault`),
+    );
+  }
+  const literalSiteKey = [identity.brandId, identity.amplifyAppId, identity.amplifyBranch].join("|");
+  const siteHash = createHash("sha256").update(literalSiteKey).digest("hex").slice(0, 8);
+  return assertLiteralResourceName(
+    "Backup vault name",
+    `papyrus-${sanitizeAwsName(identity.brandId, 20)}-${siteHash}-media-vault`,
+  );
+}
+
+/**
+ * The `papyrus-site-inbound-` prefix keeps a brand named `p-apyr-us` from
+ * colliding with the legacy `papyrus-inbound-p-apyr-us` set.
+ * SES allows one ACTIVE receipt rule set per region. A non-legacy site creates
+ * its own brand-named rule set and never activates it from CloudFormation.
+ */
+export function deriveReceiptRuleSetName(identity: SiteBackendIdentity, inboundEmailDomain: string): string {
+  const name = isLegacyProductionApp(identity)
+    ? `papyrus-inbound-${inboundEmailDomain.replace(/\./g, "-")}`
+    : `papyrus-site-inbound-${sanitizeAwsName(identity.brandId, 40)}`;
+  return assertLiteralResourceName("Receipt rule set name", name);
+}
+
+/** `undefined` keeps the legacy auto-generated rule name of the live p.apyr.us rule. */
+export function deriveReceiptRuleName(identity: SiteBackendIdentity): string | undefined {
+  if (isLegacyProductionApp(identity)) return undefined;
+  return assertLiteralResourceName("Receipt rule name", `${sanitizeAwsName(identity.brandId, 40)}-inbound-submissions`);
+}
+
+export type InboundEmailSesPlan = {
+  createReceiptRules: boolean;
+  activateReceiptRuleSet: boolean;
+  manageDomainIdentity: boolean;
+};
+
+export function planInboundEmailSes(
+  identity: SiteBackendIdentity,
+  inboundEmailEnabled: boolean,
+  options: { manageDomainIdentity?: boolean } | undefined,
+): InboundEmailSesPlan {
+  const legacyPipeline = isLegacyProductionPipeline(identity);
+  const deployedMainBranch = identity.amplifyAppId !== "" && identity.amplifyBranch === "main";
+  const createReceiptRules = inboundEmailEnabled && (legacyPipeline || deployedMainBranch);
+  return {
+    createReceiptRules,
+    activateReceiptRuleSet: createReceiptRules && legacyPipeline,
+    manageDomainIdentity: createReceiptRules && (legacyPipeline || options?.manageDomainIdentity === true),
+  };
+}
+
+export type SiteGlobalResourceNames = {
+  knowledgeVectorIndexName: string;
+  storageBackupVaultName: string;
+  receiptRuleSetName: string;
+  receiptRuleName: string | undefined;
+};
+
+export function deriveSiteGlobalResourceNames(
+  identity: SiteBackendIdentity,
+  inboundEmailDomain: string,
+): SiteGlobalResourceNames {
+  return {
+    knowledgeVectorIndexName: deriveKnowledgeVectorIndexName(identity),
+    storageBackupVaultName: deriveStorageBackupVaultName(identity),
+    receiptRuleSetName: deriveReceiptRuleSetName(identity, inboundEmailDomain),
+    receiptRuleName: deriveReceiptRuleName(identity),
+  };
+}