@anthusai/papyrus 2.0.0-next.4 → 2.0.0-next.41

package/infra/secure-string-parameter.ts

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

package/infra/site-config.js

@@ -2,12 +2,29 @@ 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 +35,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_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 +60,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 +191,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 +225,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 +236,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 +249,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 +259,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 +269,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 +337,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", "reader", "papyrusVersion", "storagePreviewPrefix", "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 +363,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 +401,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 +430,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 +458,29 @@ export function parseSiteConfig(raw) {
         frontend,
         hostedZoneId,
         stackName,
+        aws,
         cms,
         reader,
         papyrusVersion,
         storagePreviewPrefix,
+        autoDeploy: autoDeploy,
         github,
     };
     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

@@ -32,6 +32,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 +44,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,6 +61,7 @@ export type AmplifyAppShellSiteConfig = {
   frontend: "pretext" | "markus-static";
   hostedZoneId?: string;
   stackName?: string;
+  aws?: SiteAwsConfig;
   cms?: CmsConfig;
   reader?: {
     appName?: string;
@@ -69,20 +78,62 @@ export type AmplifyAppShellSiteConfig = {
   };
   papyrusVersion: string;
   storagePreviewPrefix?: string;
+  /**
+   * 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 +141,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 +152,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_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 +179,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 +311,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 +346,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 +357,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 +370,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 +385,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 +401,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 +470,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", "reader", "papyrusVersion", "storagePreviewPrefix", "autoDeploy", "github"],
     "site",
   );
 
@@ -415,6 +501,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 +539,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 +566,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,10 +593,12 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     frontend,
     hostedZoneId,
     stackName,
+    aws,
     cms,
     reader,
     papyrusVersion,
     storagePreviewPrefix,
+    autoDeploy: autoDeploy as boolean,
     github,
   };
 
@@ -506,3 +606,20 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
 
   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/category-repository.ts

@@ -200,7 +200,6 @@ export type ProcedureRunRecord = {
   newsroomFeedKey?: string | null;
 };
 
-const DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH = path.join(process.cwd(), "corpora", "papyrus-newsroom-sections.yml");
 const NEWSROOM_SECTION_TYPES = new Set<NewsroomSectionType>(["canonical", "floating", "rotating"]);
 type NewsroomSectionSeedRow = Omit<NewsroomSectionRecord, "sortOrder" | "enabled" | "enabledStatus" | "createdAt" | "updatedAt"> & {
   enabled: boolean;
@@ -690,10 +689,10 @@ export type CategorySteeringDashboard = {
   loadError?: string | null;
 };
 
-const DEFAULT_ANALYSIS_PROFILES_PATH = path.join(process.cwd(), "corpora", "papyrus-analysis-profiles.yml");
-const DEFAULT_STEERING_CONFIG_PATH = path.join(process.cwd(), "corpora", "papyrus-steering.yml");
 
-export async function loadAnalysisProfileSummaries(filepath = DEFAULT_ANALYSIS_PROFILES_PATH): Promise<AnalysisProfileSummary[]> {
+/** Analysis profiles the site keeps in a file; a site that configures none (data-driven sites) has none. No default file is looked up. */
+export async function loadAnalysisProfileSummaries(filepath?: string): Promise<AnalysisProfileSummary[]> {
+  if (!filepath) return [];
   try {
     const parsed = YAML.parse(fs.readFileSync(filepath, "utf8")) as {
       schemaVersion?: number;
@@ -722,7 +721,9 @@ export async function loadAnalysisProfileSummaries(filepath = DEFAULT_ANALYSIS_P
   }
 }
 
-export async function loadConfiguredCorpusSummaries(filepath = DEFAULT_STEERING_CONFIG_PATH): Promise<CategorySteeringCorpus[]> {
+/** Corpora a site lists in a steering file; no configured file means none. No default file is looked up. */
+export async function loadConfiguredCorpusSummaries(filepath?: string): Promise<CategorySteeringCorpus[]> {
+  if (!filepath) return [];
   try {
     const parsed = YAML.parse(fs.readFileSync(filepath, "utf8")) as {
       corpora?: Array<Record<string, unknown>>;
@@ -818,7 +819,8 @@ function sortCategorys(categorys: CategorySteeringCategory[]): CategorySteeringC
   });
 }
 
-function defaultNewsroomSections(importedAt: string, sectionsConfigPath = DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH): NewsroomSectionRecord[] {
+function defaultNewsroomSections(importedAt: string, sectionsConfigPath?: string): NewsroomSectionRecord[] {
+  if (!sectionsConfigPath) return [];
   return loadNewsroomSectionSeedRows(sectionsConfigPath).map((row, index) => ({
     ...row,
     enabledStatus: "enabled",
@@ -828,7 +830,7 @@ function defaultNewsroomSections(importedAt: string, sectionsConfigPath = DEFAUL
   }));
 }
 
-function loadNewsroomSectionSeedRows(sectionsConfigPath = DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH) {
+function loadNewsroomSectionSeedRows(sectionsConfigPath: string) {
   const cached = newsroomSectionSeedRowsCache.get(sectionsConfigPath);
   if (cached) return cached;
   const parsed = YAML.parse(fs.readFileSync(sectionsConfigPath, "utf8")) as {
@@ -883,7 +885,7 @@ function normalizeNewsroomSectionSeedRow(
 
 export function createDemoCategorySteeringDashboard(
   brandId: SiteBrandId = resolveSiteBrandId(),
-  newsroomSectionsConfigPath = DEFAULT_NEWSROOM_SECTIONS_CONFIG_PATH,
+  newsroomSectionsConfigPath?: string,
 ): CategorySteeringDashboard {
   const importedAt = "2026-05-16T12:00:00.000Z";
   const profile = getNewsroomDemoProfile(brandId);
@@ -1698,7 +1700,7 @@ export function createDemoCategorySteeringDashboard(
           question: "Should this candidate source become a reference for this publication?",
           reviewControl: "thumbs",
           reviewReason: "program",
-          reviewDetail: "Every decision is reviewed while the cyclotron is onboarding.",
+          reviewDetail: "Every suggestion is reviewed while suggestions are getting started.",
           version: 1,
         }),
       },