@anthusai/papyrus 2.0.0-next.9 → 2.0.0-next.90

package/infra/site-config.js

@@ -1,13 +1,31 @@
+import { parseCloudEmail } from "./cloud-email-config.js";
 export const READER_REDIRECT_STATUSES = ["301", "302", "200", "404", "404-200"];
 export function hasCmsApp(config) {
     return config.cms !== undefined;
 }
+export function resolveGithubRepository(config) {
+    if (config.github)
+        return { owner: config.github.owner, repo: config.github.repo };
+    const [owner, repo] = config.repository.replace("https://github.com/", "").split("/");
+    return { owner, repo };
+}
+/** The OIDC `sub` values a GitHub Actions run on `ref` of the site's repository can present. */
+export function githubOidcSubjects(config, ref) {
+    const { owner, repo } = resolveGithubRepository(config);
+    const subjects = [`repo:${owner}/${repo}:ref:refs/heads/${ref}`];
+    const { ownerId, repoId } = config.github ?? {};
+    if (ownerId !== undefined && repoId !== undefined) {
+        subjects.push(`repo:${owner}@${ownerId}/${repo}@${repoId}:ref:refs/heads/${ref}`);
+    }
+    return subjects;
+}
 export const DEFAULT_CI_BRANCHES = ["main", "staging"];
 const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const SECRETS_MANAGER_SECRET_ARN_PATTERN = /^arn:aws:secretsmanager:[a-z0-9-]+:\d{12}:secret:[A-Za-z0-9/_+=.@-]+$/;
 const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
 const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+const SITE_ORIGIN_PATTERN = /^https:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(:\d{1,5})?$/;
 const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
@@ -18,7 +36,7 @@ const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
 const PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN = /^arn:aws:execute-api:[a-z0-9-]+:\d{12}:[a-z0-9]+\/api$/;
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_ARN", "PAPYRUS_PROSPECTUS_SITE_PRODUCT"];
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_EMAIL_FROM_ADDRESS", "PAPYRUS_EMAIL_IDENTITY_ARN", "PAPYRUS_EMAIL_CONFIGURATION_SET", "PAPYRUS_EMAIL_EVENT_TOPIC_NAME", "PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_SITE_PRODUCT", "PAPYRUS_READER_POLL_SECRET_PARAMETER", "PAPYRUS_SITE_ORIGIN"];
 /** Routes Prospectus admits for a registered Papyrus site (Prospectus accounts/papyrus-sites.ts). */
 export const PROSPECTUS_PAPYRUS_SITE_ROUTES = [
     "GET/v1/identities/me",
@@ -43,6 +61,12 @@ function originOfRedirectUrl(value) {
         return value;
     }
 }
+export function resolveProspectusSessionSealingParameterName(config) {
+    return `/papyrus/${config.siteId}/prospectus-session-sealing`;
+}
+export function resolveReaderPollSecretParameterName(config) {
+    return `/papyrus/${config.siteId}/reader-poll-secret`;
+}
 export function resolveRevalidateSecretParameterName(config) {
     return `/papyrus/${config.siteId}/revalidate-secret`;
 }
@@ -168,6 +192,9 @@ export function resolveCmsHostName(config) {
         return undefined;
     return config.cms.domainPrefix ? `${config.cms.domainPrefix}.${config.cms.domainName}` : config.cms.domainName;
 }
+export function resolveSiteOrigin(config) {
+    return config.cms.siteOrigin;
+}
 export function resolveStagingDomainName(config) {
     if (!isStagingEnabled(config))
         return undefined;
@@ -199,7 +226,7 @@ function parseStagingPreview(value) {
 }
 function parseCms(value) {
     const cmsRecord = requireObject(value, "cms");
-    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "deployStackInBuild"], "cms");
+    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "siteOrigin", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "readerRetirementPoll", "deployStackInBuild"], "cms");
     const buildComputeType = cmsRecord.buildComputeType;
     if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
         fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -210,6 +237,12 @@ function parseCms(value) {
     if (cmsRecord.applyCognitoDomainPrefix !== undefined && typeof cmsRecord.applyCognitoDomainPrefix !== "boolean") {
         fail("cms.applyCognitoDomainPrefix", `must be a boolean, got ${JSON.stringify(cmsRecord.applyCognitoDomainPrefix)}`);
     }
+    if (cmsRecord.readerRetirementPoll !== undefined && typeof cmsRecord.readerRetirementPoll !== "boolean") {
+        fail("cms.readerRetirementPoll", `must be a boolean, got ${JSON.stringify(cmsRecord.readerRetirementPoll)}`);
+    }
+    if (cmsRecord.readerRetirementPoll === true && cmsRecord.prospectusAccountsApiStageArn === undefined) {
+        fail("cms.readerRetirementPoll", "requires cms.prospectusAccountsApiStageArn: the poll calls Prospectus as the site");
+    }
     if (cmsRecord.deployStackInBuild !== undefined && typeof cmsRecord.deployStackInBuild !== "boolean") {
         fail("cms.deployStackInBuild", `must be a boolean, got ${JSON.stringify(cmsRecord.deployStackInBuild)}`);
     }
@@ -217,6 +250,7 @@ function parseCms(value) {
         appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
         domainName: optionalString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
         domainPrefix: optionalString(cmsRecord.domainPrefix, "cms.domainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
+        siteOrigin: optionalString(cmsRecord.siteOrigin, "cms.siteOrigin", SITE_ORIGIN_PATTERN, "https origin with no path, query or trailing slash, such as https://shipped.anth.us"),
         staging: cmsRecord.staging,
         cognitoDomainPrefix: requireString(cmsRecord.cognitoDomainPrefix, "cms.cognitoDomainPrefix", COGNITO_DOMAIN_PREFIX_PATTERN, "lowercase letters, digits and hyphens; globally unique per region"),
         applyCognitoDomainPrefix: cmsRecord.applyCognitoDomainPrefix,
@@ -226,6 +260,7 @@ function parseCms(value) {
         stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
         redirects: parseRedirects(cmsRecord.redirects),
         deployStackInBuild: cmsRecord.deployStackInBuild,
+        readerRetirementPoll: cmsRecord.readerRetirementPoll,
         stagingPreview: parseStagingPreview(cmsRecord.stagingPreview),
         prospectusAccountsApiStageArn: optionalString(cmsRecord.prospectusAccountsApiStageArn, "cms.prospectusAccountsApiStageArn", PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN, "arn:aws:execute-api:<region>:<account>:<api id>/api"),
     };
@@ -235,9 +270,12 @@ function parseCms(value) {
     }
     for (const key of TEMPLATE_MANAGED_ENVIRONMENT_KEYS) {
         if (key in cms.environment) {
-            fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn");
+            fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn and the public site origin comes from the site host");
         }
     }
+    if (cms.siteOrigin && cms.domainName) {
+        fail("cms.siteOrigin", "is for sites whose host is served by their own edge; remove it when cms.domainName is set");
+    }
     if (cms.staging === false && cms.stagingDomainName) {
         fail("cms.stagingDomainName", "must not be set when cms.staging is false");
     }
@@ -300,9 +338,20 @@ function validateOauthRedirectUrls(config) {
         }
     }
 }
+function parseAws(value) {
+    if (value === undefined)
+        return undefined;
+    const record = requireObject(value, "aws");
+    rejectUnknownKeys(record, ["profile", "accountId", "region"], "aws");
+    return {
+        profile: optionalString(record.profile, "aws.profile", /^[A-Za-z0-9_.-]+$/, "AWS CLI profile name"),
+        accountId: optionalString(record.accountId, "aws.accountId", /^\d{12}$/, "12-digit account id"),
+        region: optionalString(record.region, "aws.region", /^[a-z]{2}(-[a-z]+)+-\d$/, "AWS region such as us-east-1"),
+    };
+}
 export function parseSiteConfig(raw) {
     const record = requireObject(raw, "site");
-    rejectUnknownKeys(record, ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "cms", "reader", "papyrusVersion", "storagePreviewPrefix", "github"], "site");
+    rejectUnknownKeys(record, ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "knowledgeRun", "autoDeploy", "github"], "site");
     const siteId = requireString(record.siteId, "siteId", SITE_ID_PATTERN, "kebab-case");
     const repository = requireString(record.repository, "repository", REPOSITORY_PATTERN, "https://github.com/<org>/<repo>");
     const repositoryAccessTokenSecretArn = record.repositoryAccessTokenSecretArn === undefined
@@ -315,6 +364,7 @@ export function parseSiteConfig(raw) {
     }
     const hostedZoneId = optionalString(record.hostedZoneId, "hostedZoneId", HOSTED_ZONE_ID_PATTERN, "Route 53 zone id");
     const stackName = optionalString(record.stackName, "stackName", STACK_NAME_PATTERN, "CloudFormation stack name");
+    const aws = parseAws(record.aws);
     const papyrusVersion = requireString(record.papyrusVersion, "papyrusVersion", PAPYRUS_VERSION_PATTERN, "exact version such as 1.0.0 or 1.0.0-next.1");
     const storagePreviewPrefix = optionalString(record.storagePreviewPrefix, "storagePreviewPrefix", /^[A-Za-z0-9._-]+\/$/, "must end with /");
     const cms = record.cms === undefined && frontend === "markus-static" ? undefined : parseCms(record.cms);
@@ -352,12 +402,15 @@ export function parseSiteConfig(raw) {
     if (cms?.stagingPreview !== undefined && cms.staging === false) {
         fail("cms.stagingPreview", "must not be set when cms.staging is false");
     }
+    const autoDeploy = record.autoDeploy ?? true;
+    if (typeof autoDeploy !== "boolean")
+        fail("autoDeploy", "must be a boolean");
     let github;
     if (record.github !== undefined) {
         if (cms === undefined)
             fail("github", "requires cms (the CI role is scoped to the CMS app)");
         const githubRecord = requireObject(record.github, "github");
-        rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra"], "github");
+        rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra", "ownerId", "repoId"], "github");
         const owner = requireString(githubRecord.owner, "github.owner", GITHUB_OWNER_PATTERN, "plain GitHub login");
         const repo = requireString(githubRecord.repo, "github.repo", GITHUB_REPO_PATTERN);
         if (repository !== `https://github.com/${owner}/${repo}`) {
@@ -378,7 +431,18 @@ export function parseSiteConfig(raw) {
         const ciCanDeployInfra = githubRecord.ciCanDeployInfra ?? false;
         if (typeof ciCanDeployInfra !== "boolean")
             fail("github.ciCanDeployInfra", "must be a boolean");
-        github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra };
+        const optionalId = (value, name) => {
+            if (value === undefined)
+                return undefined;
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+                fail(name, "must be a positive integer (GitHub numeric id)");
+            return value;
+        };
+        const ownerId = optionalId(githubRecord.ownerId, "github.ownerId");
+        const repoId = optionalId(githubRecord.repoId, "github.repoId");
+        if ((ownerId === undefined) !== (repoId === undefined))
+            fail("github", "ownerId and repoId must be set together");
+        github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra, ...(ownerId !== undefined ? { ownerId, repoId } : {}) };
     }
     const hasDomain = cms?.domainName !== undefined || reader?.domainName !== undefined;
     if (hasDomain && hostedZoneId === undefined) {
@@ -395,13 +459,31 @@ export function parseSiteConfig(raw) {
         frontend,
         hostedZoneId,
         stackName,
+        aws,
         cms,
+        email: parseCloudEmail(record.email, cms !== undefined, siteId),
         reader,
         papyrusVersion,
         storagePreviewPrefix,
+        autoDeploy: autoDeploy,
         github,
+        ...(record.knowledgeRun !== undefined ? { knowledgeRun: record.knowledgeRun } : {}),
     };
     if (hasCmsApp(config))
         validateOauthRedirectUrls(config);
     return config;
 }
+/**
+ * The CDK environment for a site's app-shell stack, taken only from the site's own `aws` block. There is
+ * deliberately no default account: a deploy that guesses an account can land in, or fail against, the wrong
+ * one.
+ */
+export function resolveDeployEnvironment(config) {
+    const account = config.aws?.accountId;
+    const region = config.aws?.region;
+    const missing = [account ? "" : "aws.accountId", region ? "" : "aws.region"].filter(Boolean);
+    if (!account || !region) {
+        throw new Error(`site "${config.siteId}" does not say where it deploys: add ${missing.join(" and ")} to its site.json, e.g. "aws": { "accountId": "<12-digit account>", "region": "us-east-1" }. No account is assumed.`);
+    }
+    return { account, region };
+}

package/infra/site-config.ts

@@ -1,3 +1,5 @@
+import { parseCloudEmail, type CloudEmailConfig } from "./cloud-email-config";
+
 export type CmsRedirect = {
   source: string;
   status: 301 | 302;
@@ -32,6 +34,8 @@ export type CmsConfig = {
   appName?: string;
   domainName?: string;
   domainPrefix?: string;
+  /** Public https origin of a site whose host is served by its own edge (no Amplify domain association). */
+  siteOrigin?: string;
   staging?: boolean;
   stagingPreview?: StagingPreviewConfig;
   cognitoDomainPrefix: string;
@@ -42,6 +46,12 @@ export type CmsConfig = {
   stagingDomainPrefix?: string;
   redirects?: CmsRedirect[];
   prospectusAccountsApiStageArn?: string;
+  /**
+   * The site is a public-reader site that polls Prospectus for retired reader subjects. The template then generates a
+   * shared secret that the scheduled snapshot run presents to the CMS route `/api/reader/retired` (requires
+   * `prospectusAccountsApiStageArn`; docs/reader-steering.md).
+   */
+  readerRetirementPoll?: boolean;
   deployStackInBuild?: boolean;
 };
 
@@ -53,7 +63,10 @@ export type AmplifyAppShellSiteConfig = {
   frontend: "pretext" | "markus-static";
   hostedZoneId?: string;
   stackName?: string;
+  aws?: SiteAwsConfig;
   cms?: CmsConfig;
+  /** Required for cloud CMS sites; independent of newsletter feature enablement. */
+  email?: CloudEmailConfig;
   reader?: {
     appName?: string;
     domainName?: string;
@@ -69,20 +82,67 @@ export type AmplifyAppShellSiteConfig = {
   };
   papyrusVersion: string;
   storagePreviewPrefix?: string;
+  /**
+   * The scheduled cloud knowledge run for this publication. The app-shell stack ignores it; it is validated by
+   * infra/scheduled-jobs/lib/knowledge-run-config.ts, which owns the schema.
+   */
+  knowledgeRun?: unknown;
+  /**
+   * Merge-to-main deploy from GitHub Actions through OIDC. When true (the default) the stack creates the
+   * `<siteId>-github-deploy` role and turns off Amplify's own auto-build on the production branches, so the
+   * public repository's workflow is the only trigger. Set false for a site whose repository is private:
+   * private repositories get no Actions minutes, so Amplify's own repository-connected auto-build stays on.
+   */
+  autoDeploy: boolean;
   github?: {
     owner: string;
     repo: string;
     branches: string[];
     ciCanDeployInfra: boolean;
+    /**
+     * GitHub's numeric ids of the owner and the repository. Repositories with the immutable OIDC subject
+     * (`repo:<owner>@<ownerId>/<repo>@<repoId>:ref:...`, see `gh api repos/<owner>/<repo>/actions/oidc/customization/sub`)
+     * present that form instead of `repo:<owner>/<repo>:ref:...`; with both ids set, roles trust both forms.
+     */
+    ownerId?: number;
+    repoId?: number;
   };
 };
 
+/**
+ * Where the site's AWS resources live. `bin/app-shell.ts` deploys the stack into exactly this account and
+ * region (see `resolveDeployEnvironment`), and `papyrus site google-secrets` asserts `accountId` with STS
+ * before it writes anything.
+ */
+export type SiteAwsConfig = {
+  profile?: string;
+  accountId?: string;
+  region?: string;
+};
+
 export type CmsSiteConfig = AmplifyAppShellSiteConfig & { cms: CmsConfig };
 
 export function hasCmsApp(config: AmplifyAppShellSiteConfig): config is CmsSiteConfig {
   return config.cms !== undefined;
 }
 
+export function resolveGithubRepository(config: Pick<AmplifyAppShellSiteConfig, "repository" | "github">): { owner: string; repo: string } {
+  if (config.github) return { owner: config.github.owner, repo: config.github.repo };
+  const [owner, repo] = config.repository.replace("https://github.com/", "").split("/");
+  return { owner, repo };
+}
+
+/** The OIDC `sub` values a GitHub Actions run on `ref` of the site's repository can present. */
+export function githubOidcSubjects(config: Pick<AmplifyAppShellSiteConfig, "repository" | "github">, ref: string): string[] {
+  const { owner, repo } = resolveGithubRepository(config);
+  const subjects = [`repo:${owner}/${repo}:ref:refs/heads/${ref}`];
+  const { ownerId, repoId } = config.github ?? {};
+  if (ownerId !== undefined && repoId !== undefined) {
+    subjects.push(`repo:${owner}@${ownerId}/${repo}@${repoId}:ref:refs/heads/${ref}`);
+  }
+  return subjects;
+}
+
 export const DEFAULT_CI_BRANCHES = ["main", "staging"];
 
 const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -90,6 +150,7 @@ const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_
 const SECRETS_MANAGER_SECRET_ARN_PATTERN = /^arn:aws:secretsmanager:[a-z0-9-]+:\d{12}:secret:[A-Za-z0-9/_+=.@-]+$/;
 const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
 const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+const SITE_ORIGIN_PATTERN = /^https:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(:\d{1,5})?$/;
 const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
@@ -100,7 +161,7 @@ const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
 const PROSPECTUS_ACCOUNTS_API_STAGE_ARN_PATTERN = /^arn:aws:execute-api:[a-z0-9-]+:\d{12}:[a-z0-9]+\/api$/;
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_ARN", "PAPYRUS_PROSPECTUS_SITE_PRODUCT"];
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_EMAIL_FROM_ADDRESS", "PAPYRUS_EMAIL_IDENTITY_ARN", "PAPYRUS_EMAIL_CONFIGURATION_SET", "PAPYRUS_EMAIL_EVENT_TOPIC_NAME", "PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH", "PAPYRUS_REVALIDATE_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_ACCOUNTS_ENDPOINT", "PAPYRUS_PROSPECTUS_SESSION_SECRET_PARAMETER", "PAPYRUS_PROSPECTUS_SITE_PRODUCT", "PAPYRUS_READER_POLL_SECRET_PARAMETER", "PAPYRUS_SITE_ORIGIN"];
 
 /** Routes Prospectus admits for a registered Papyrus site (Prospectus accounts/papyrus-sites.ts). */
 export const PROSPECTUS_PAPYRUS_SITE_ROUTES = [
@@ -127,6 +188,14 @@ function originOfRedirectUrl(value: string): string {
   }
 }
 
+export function resolveProspectusSessionSealingParameterName(config: Pick<AmplifyAppShellSiteConfig, "siteId">): string {
+  return `/papyrus/${config.siteId}/prospectus-session-sealing`;
+}
+
+export function resolveReaderPollSecretParameterName(config: Pick<AmplifyAppShellSiteConfig, "siteId">): string {
+  return `/papyrus/${config.siteId}/reader-poll-secret`;
+}
+
 export function resolveRevalidateSecretParameterName(config: Pick<AmplifyAppShellSiteConfig, "siteId">): string {
   return `/papyrus/${config.siteId}/revalidate-secret`;
 }
@@ -251,6 +320,10 @@ export function resolveCmsHostName(config: Pick<CmsSiteConfig, "cms">): string |
   return config.cms.domainPrefix ? `${config.cms.domainPrefix}.${config.cms.domainName}` : config.cms.domainName;
 }
 
+export function resolveSiteOrigin(config: Pick<CmsSiteConfig, "cms">): string | undefined {
+  return config.cms.siteOrigin;
+}
+
 export function resolveStagingDomainName(config: Pick<CmsSiteConfig, "cms">): string | undefined {
   if (!isStagingEnabled(config)) return undefined;
   if (config.cms.domainPrefix) {
@@ -282,7 +355,7 @@ function parseStagingPreview(value: unknown): StagingPreviewConfig | undefined {
 
 function parseCms(value: unknown): CmsConfig {
   const cmsRecord = requireObject(value, "cms");
-  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "deployStackInBuild"], "cms");
+  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "siteOrigin", "stagingDomainPrefix", "redirects", "stagingPreview", "prospectusAccountsApiStageArn", "readerRetirementPoll", "deployStackInBuild"], "cms");
   const buildComputeType = cmsRecord.buildComputeType;
   if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
     fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -293,6 +366,12 @@ function parseCms(value: unknown): CmsConfig {
   if (cmsRecord.applyCognitoDomainPrefix !== undefined && typeof cmsRecord.applyCognitoDomainPrefix !== "boolean") {
     fail("cms.applyCognitoDomainPrefix", `must be a boolean, got ${JSON.stringify(cmsRecord.applyCognitoDomainPrefix)}`);
   }
+  if (cmsRecord.readerRetirementPoll !== undefined && typeof cmsRecord.readerRetirementPoll !== "boolean") {
+    fail("cms.readerRetirementPoll", `must be a boolean, got ${JSON.stringify(cmsRecord.readerRetirementPoll)}`);
+  }
+  if (cmsRecord.readerRetirementPoll === true && cmsRecord.prospectusAccountsApiStageArn === undefined) {
+    fail("cms.readerRetirementPoll", "requires cms.prospectusAccountsApiStageArn: the poll calls Prospectus as the site");
+  }
   if (cmsRecord.deployStackInBuild !== undefined && typeof cmsRecord.deployStackInBuild !== "boolean") {
     fail("cms.deployStackInBuild", `must be a boolean, got ${JSON.stringify(cmsRecord.deployStackInBuild)}`);
   }
@@ -300,6 +379,7 @@ function parseCms(value: unknown): CmsConfig {
     appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
     domainName: optionalString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
     domainPrefix: optionalString(cmsRecord.domainPrefix, "cms.domainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
+    siteOrigin: optionalString(cmsRecord.siteOrigin, "cms.siteOrigin", SITE_ORIGIN_PATTERN, "https origin with no path, query or trailing slash, such as https://shipped.anth.us"),
     staging: cmsRecord.staging as boolean | undefined,
     cognitoDomainPrefix: requireString(
       cmsRecord.cognitoDomainPrefix,
@@ -314,6 +394,7 @@ function parseCms(value: unknown): CmsConfig {
     stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
     redirects: parseRedirects(cmsRecord.redirects),
     deployStackInBuild: cmsRecord.deployStackInBuild as boolean | undefined,
+    readerRetirementPoll: cmsRecord.readerRetirementPoll as boolean | undefined,
     stagingPreview: parseStagingPreview(cmsRecord.stagingPreview),
     prospectusAccountsApiStageArn: optionalString(
       cmsRecord.prospectusAccountsApiStageArn,
@@ -329,10 +410,13 @@ function parseCms(value: unknown): CmsConfig {
   }
   for (const key of TEMPLATE_MANAGED_ENVIRONMENT_KEYS) {
     if (key in cms.environment) {
-      fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn");
+      fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn and the public site origin comes from the site host");
     }
   }
 
+  if (cms.siteOrigin && cms.domainName) {
+    fail("cms.siteOrigin", "is for sites whose host is served by their own edge; remove it when cms.domainName is set");
+  }
   if (cms.staging === false && cms.stagingDomainName) {
     fail("cms.stagingDomainName", "must not be set when cms.staging is false");
   }
@@ -395,11 +479,22 @@ function validateOauthRedirectUrls(config: CmsSiteConfig): void {
   }
 }
 
+function parseAws(value: unknown): SiteAwsConfig | undefined {
+  if (value === undefined) return undefined;
+  const record = requireObject(value, "aws");
+  rejectUnknownKeys(record, ["profile", "accountId", "region"], "aws");
+  return {
+    profile: optionalString(record.profile, "aws.profile", /^[A-Za-z0-9_.-]+$/, "AWS CLI profile name"),
+    accountId: optionalString(record.accountId, "aws.accountId", /^\d{12}$/, "12-digit account id"),
+    region: optionalString(record.region, "aws.region", /^[a-z]{2}(-[a-z]+)+-\d$/, "AWS region such as us-east-1"),
+  };
+}
+
 export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   const record = requireObject(raw, "site");
   rejectUnknownKeys(
     record,
-    ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "cms", "reader", "papyrusVersion", "storagePreviewPrefix", "github"],
+    ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "knowledgeRun", "autoDeploy", "github"],
     "site",
   );
 
@@ -415,6 +510,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   }
   const hostedZoneId = optionalString(record.hostedZoneId, "hostedZoneId", HOSTED_ZONE_ID_PATTERN, "Route 53 zone id");
   const stackName = optionalString(record.stackName, "stackName", STACK_NAME_PATTERN, "CloudFormation stack name");
+  const aws = parseAws(record.aws);
   const papyrusVersion = requireString(record.papyrusVersion, "papyrusVersion", PAPYRUS_VERSION_PATTERN, "exact version such as 1.0.0 or 1.0.0-next.1");
   const storagePreviewPrefix = optionalString(record.storagePreviewPrefix, "storagePreviewPrefix", /^[A-Za-z0-9._-]+\/$/, "must end with /");
 
@@ -452,11 +548,14 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     fail("cms.stagingPreview", "must not be set when cms.staging is false");
   }
 
+  const autoDeploy = record.autoDeploy ?? true;
+  if (typeof autoDeploy !== "boolean") fail("autoDeploy", "must be a boolean");
+
   let github: AmplifyAppShellSiteConfig["github"];
   if (record.github !== undefined) {
     if (cms === undefined) fail("github", "requires cms (the CI role is scoped to the CMS app)");
     const githubRecord = requireObject(record.github, "github");
-    rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra"], "github");
+    rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra", "ownerId", "repoId"], "github");
     const owner = requireString(githubRecord.owner, "github.owner", GITHUB_OWNER_PATTERN, "plain GitHub login");
     const repo = requireString(githubRecord.repo, "github.repo", GITHUB_REPO_PATTERN);
     if (repository !== `https://github.com/${owner}/${repo}`) {
@@ -476,7 +575,15 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     }
     const ciCanDeployInfra = githubRecord.ciCanDeployInfra ?? false;
     if (typeof ciCanDeployInfra !== "boolean") fail("github.ciCanDeployInfra", "must be a boolean");
-    github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra as boolean };
+    const optionalId = (value: unknown, name: string): number | undefined => {
+      if (value === undefined) return undefined;
+      if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) fail(name, "must be a positive integer (GitHub numeric id)");
+      return value as number;
+    };
+    const ownerId = optionalId(githubRecord.ownerId, "github.ownerId");
+    const repoId = optionalId(githubRecord.repoId, "github.repoId");
+    if ((ownerId === undefined) !== (repoId === undefined)) fail("github", "ownerId and repoId must be set together");
+    github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra as boolean, ...(ownerId !== undefined ? { ownerId, repoId } : {}) };
   }
 
   const hasDomain = cms?.domainName !== undefined || reader?.domainName !== undefined;
@@ -495,14 +602,35 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     frontend,
     hostedZoneId,
     stackName,
+    aws,
     cms,
+    email: parseCloudEmail(record.email, cms !== undefined, siteId),
     reader,
     papyrusVersion,
     storagePreviewPrefix,
+    autoDeploy: autoDeploy as boolean,
     github,
+    ...(record.knowledgeRun !== undefined ? { knowledgeRun: record.knowledgeRun } : {}),
   };
 
   if (hasCmsApp(config)) validateOauthRedirectUrls(config);
 
   return config;
 }
+
+/**
+ * The CDK environment for a site's app-shell stack, taken only from the site's own `aws` block. There is
+ * deliberately no default account: a deploy that guesses an account can land in, or fail against, the wrong
+ * one.
+ */
+export function resolveDeployEnvironment(config: Pick<AmplifyAppShellSiteConfig, "siteId" | "aws">): { account: string; region: string } {
+  const account = config.aws?.accountId;
+  const region = config.aws?.region;
+  const missing = [account ? "" : "aws.accountId", region ? "" : "aws.region"].filter(Boolean);
+  if (!account || !region) {
+    throw new Error(
+      `site "${config.siteId}" does not say where it deploys: add ${missing.join(" and ")} to its site.json, e.g. "aws": { "accountId": "<12-digit account>", "region": "us-east-1" }. No account is assumed.`,
+    );
+  }
+  return { account, region };
+}

package/lib/automation-client.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import type { AutomationResult, RunNowResult } from "./automation-overview";
+
+type GraphQLResult = { data?: { automationOverview?: unknown }; errors?: { message?: string; errorType?: string }[] };
+
+/**
+ * Reads the automations through the site's own authenticated API (user pool, editor or admin).
+ * The browser holds no table name, key or secret: the function behind the query does the reads.
+ */
+export async function loadAutomationOverview(): Promise<AutomationResult> {
+  const client = generateClient({ authMode: "userPool" });
+  let result: GraphQLResult;
+  try {
+    result = (await client.graphql({
+      query: `query AutomationOverview($automationId: String) { automationOverview(automationId: $automationId) }`,
+      variables: {},
+    })) as GraphQLResult;
+  } catch (error) {
+    // Amplify throws the response when AppSync returns errors.
+    result = (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
+  }
+  const refused = result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`));
+  if (refused) return { error: "forbidden" };
+  if (result.errors?.length || result.data?.automationOverview === undefined || result.data.automationOverview === null) return { state: "unavailable" };
+  const raw = result.data.automationOverview;
+  return (typeof raw === "string" ? JSON.parse(raw) : raw) as AutomationResult;
+}
+
+type RunGraphQLResult = { data?: { runAutomation?: unknown }; errors?: { message?: string; errorType?: string }[] };
+
+/**
+ * Starts a run of the automation's procedure now, as the signed-in editor or admin. The function behind the
+ * mutation checks the groups again, refuses a disabled automation or one at its limit, and writes the row that
+ * links the run to the automation's history. `input` is sent as JSON text; null uses the record's own input.
+ */
+export async function runAutomationNow(automationId: string, input: Record<string, unknown> | null): Promise<RunNowResult> {
+  const client = generateClient({ authMode: "userPool" });
+  let result: RunGraphQLResult;
+  try {
+    result = (await client.graphql({
+      query: `mutation RunAutomation($automationId: String!, $input: AWSJSON) { runAutomation(automationId: $automationId, input: $input) }`,
+      variables: { automationId, input: input === null ? null : JSON.stringify(input) },
+    })) as RunGraphQLResult;
+  } catch (error) {
+    result = (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as RunGraphQLResult;
+  }
+  const refused = result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`));
+  if (refused) return { error: "forbidden" };
+  if (result.errors?.length || result.data?.runAutomation === undefined || result.data.runAutomation === null) return { state: "unavailable" };
+  const raw = result.data.runAutomation;
+  return (typeof raw === "string" ? JSON.parse(raw) : raw) as RunNowResult;
+}