@anthusai/papyrus 2.0.0-next.6 → 2.0.0-next.61

package/infra/index.js

@@ -10,6 +10,7 @@ try {
   );
 }
 export const { AmplifyAppShellStack } = await import("./amplify-app-shell.js");
+export const { SecureStringParameter } = await import("./secure-string-parameter.js");
 export const { GithubOidcProviderStack } = await import("./github-oidc-provider.js");
 export { parseSiteConfig } from "./site-config.js";
 export { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec, buildSpecFor } from "./build-specs.js";

package/infra/secure-string-parameter-handler.js

@@ -0,0 +1,41 @@
+/**
+ * Source of the Lambda behind SecureStringParameter, as a string so the staged
+ * package (which ships only .ts under infra/) can inline it and tests can run it
+ * against a fake SSM client. CommonJS, under the 4096-character inline limit.
+ *
+ * It creates the parameter when it is missing and does nothing else: it never
+ * overwrites an existing value, never reads one back, never logs the value, and
+ * returns no data (only the parameter name as the physical id).
+ */
+export const SECURE_STRING_PARAMETER_HANDLER_SOURCE = `
+const { randomInt } = require("node:crypto");
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function generate(length) {
+  let value = "";
+  for (let index = 0; index < length; index += 1) value += ALPHABET[randomInt(ALPHABET.length)];
+  return value;
+}
+exports.createHandler = (ssm, PutParameterCommand) => async (event) => {
+  const name = event.ResourceProperties.ParameterName;
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  try {
+    await ssm.send(new PutParameterCommand({
+      Name: name,
+      Description: event.ResourceProperties.Description,
+      Type: "SecureString",
+      Tier: "Standard",
+      Overwrite: false,
+      Value: generate(Number(event.ResourceProperties.Length)),
+    }));
+  } catch (error) {
+    if (!error || error.name !== "ParameterAlreadyExists") {
+      throw new Error("PutParameter failed for " + name + " (" + (error && error.name ? error.name : "error") + ")");
+    }
+  }
+  return { PhysicalResourceId: name };
+};
+exports.handler = async (event) => {
+  const { SSMClient, PutParameterCommand } = require("@aws-sdk/client-ssm");
+  return exports.createHandler(new SSMClient({}), PutParameterCommand)(event);
+};
+`;

package/infra/secure-string-parameter-handler.ts

@@ -0,0 +1,41 @@
+/**
+ * Source of the Lambda behind SecureStringParameter, as a string so the staged
+ * package (which ships only .ts under infra/) can inline it and tests can run it
+ * against a fake SSM client. CommonJS, under the 4096-character inline limit.
+ *
+ * It creates the parameter when it is missing and does nothing else: it never
+ * overwrites an existing value, never reads one back, never logs the value, and
+ * returns no data (only the parameter name as the physical id).
+ */
+export const SECURE_STRING_PARAMETER_HANDLER_SOURCE = `
+const { randomInt } = require("node:crypto");
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function generate(length) {
+  let value = "";
+  for (let index = 0; index < length; index += 1) value += ALPHABET[randomInt(ALPHABET.length)];
+  return value;
+}
+exports.createHandler = (ssm, PutParameterCommand) => async (event) => {
+  const name = event.ResourceProperties.ParameterName;
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  try {
+    await ssm.send(new PutParameterCommand({
+      Name: name,
+      Description: event.ResourceProperties.Description,
+      Type: "SecureString",
+      Tier: "Standard",
+      Overwrite: false,
+      Value: generate(Number(event.ResourceProperties.Length)),
+    }));
+  } catch (error) {
+    if (!error || error.name !== "ParameterAlreadyExists") {
+      throw new Error("PutParameter failed for " + name + " (" + (error && error.name ? error.name : "error") + ")");
+    }
+  }
+  return { PhysicalResourceId: name };
+};
+exports.handler = async (event) => {
+  const { SSMClient, PutParameterCommand } = require("@aws-sdk/client-ssm");
+  return exports.createHandler(new SSMClient({}), PutParameterCommand)(event);
+};
+`;

package/infra/secure-string-parameter.js

@@ -0,0 +1,79 @@
+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.js";
+/** One Lambda and role per stack, shared by every SecureStringParameter in it. */
+class SecureStringParameterProvider extends Construct {
+    static ID = "SecureStringParameterProvider";
+    role;
+    provider;
+    static of(stack) {
+        return stack.node.tryFindChild(SecureStringParameterProvider.ID)
+            ?? new SecureStringParameterProvider(stack);
+    }
+    constructor(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 {
+    parameterName;
+    parameterArn;
+    constructor(scope, id, props) {
+        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/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", "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 +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,30 @@ export function parseSiteConfig(raw) {
         frontend,
         hostedZoneId,
         stackName,
+        aws,
         cms,
         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 };
+}