@deployfoundation/foundation-deploy 0.2.14 → 0.2.16

package/src/stacks/pages-stack.ts

@@ -0,0 +1,504 @@
+import * as cdk from "aws-cdk-lib";
+import * as acm from "aws-cdk-lib/aws-certificatemanager";
+import * as cloudfront from "aws-cdk-lib/aws-cloudfront";
+import * as origins from "aws-cdk-lib/aws-cloudfront-origins";
+import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+import * as iam from "aws-cdk-lib/aws-iam";
+import type * as kms from "aws-cdk-lib/aws-kms";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as route53 from "aws-cdk-lib/aws-route53";
+import * as route53Targets from "aws-cdk-lib/aws-route53-targets";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import * as secretsmanager from "aws-cdk-lib/aws-secretsmanager";
+import type { Construct } from "constructs";
+import { lambdaCode } from "../artifacts.ts";
+import { type Instance, namesFor } from "../names.ts";
+import { pagesViewerRequestCode } from "./pages-edge-function.ts";
+
+export interface FoundationPagesProps extends cdk.StackProps {
+  instance: Instance;
+  /** Encrypts the pages table, like every other Foundation table. */
+  dataKey: kms.IKey;
+  secrets: {
+    /** Verifies the actor capability every Pages API call carries. */
+    signing: secretsmanager.ISecret;
+    /** Bot token (membership check) plus the app's OIDC `client_id`/`client_secret`. */
+    slackApp: secretsmanager.ISecret;
+  };
+  /**
+   * The deploy tool has seen the Foundation-made zone's NS delegation resolve
+   * (`-c pagesDomainDelegated=true`), so the certificate can be issued and the
+   * domain attached without the deploy hanging on validation. Irrelevant with
+   * no `pages.domain`, and implied by `pages.hostedZoneId`.
+   */
+  domainDelegated?: boolean;
+}
+
+/** How the stack serves pages for this instance and deploy. */
+export interface PagesDomainPlan {
+  /** The custom domain, attached to the distribution in this deploy. */
+  attached?: string;
+  /** `pages.domain` is set but waits for its NS delegation. */
+  pending?: string;
+  /** Foundation creates the zone (no `pages.hostedZoneId`). */
+  ownZone: boolean;
+}
+
+export function pagesDomainPlan(instance: Instance, delegated: boolean): PagesDomainPlan {
+  const { domain, hostedZoneId } = instance.pages;
+  if (domain === undefined) return { ownZone: false };
+  const ownZone = hostedZoneId === undefined;
+  return ownZone && !delegated ? { pending: domain, ownZone } : { attached: domain, ownZone };
+}
+
+/**
+ * Content-Security-Policy for every hosted page and sign-in response.
+ *
+ * Pages are static, self-contained bundles: scripts, styles, fonts and data
+ * come from the page itself (or inline, or `data:`/`blob:`). `connect-src
+ * 'self'` means a page makes no external data calls; Google Fonts is the one
+ * outside origin, because decks and brand kits use it for type. Framing is
+ * limited to the pages origin so a page cannot be embedded elsewhere.
+ */
+export const PAGES_CONTENT_SECURITY_POLICY = [
+  "default-src 'self'",
+  "script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:",
+  "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+  "font-src 'self' data: https://fonts.gstatic.com",
+  "img-src 'self' data: blob:",
+  "media-src 'self' data: blob:",
+  "connect-src 'self' data: blob:",
+  "worker-src 'self' blob:",
+  "frame-src 'self'",
+  "object-src 'none'",
+  "base-uri 'self'",
+  "form-action 'self'",
+  "frame-ancestors 'self'",
+].join("; ");
+
+/**
+ * FoundationPages — hosted, private, versioned pages (`docs/pages.md`).
+ *
+ *   S3 (private, versioned) ← OAC ← CloudFront ← viewer function (cookie check)
+ *                                        └─ /_auth/* → sign-in Lambda (Function URL, OAC)
+ *   Pages API Lambda (actor-capability authorized) → S3 + DynamoDB
+ *
+ * The agent's only grant is to invoke the Pages API (FoundationAgent adds it
+ * by function name). Nothing here reads the agent, and the agent is explicitly
+ * denied the bucket, the table, the cookie key and the edge key store.
+ *
+ * SSE-S3 rather than the instance data key on the bucket: CloudFront reads it
+ * through origin access control, and SSE-KMS would need the data key's policy
+ * (owned by FoundationData) to trust this stack's distribution, a cross-stack
+ * key-policy edit for no gain in who can read the objects. The table, which
+ * only Foundation's own Lambdas read, uses the data key as the others do.
+ */
+export class FoundationPages extends cdk.Stack {
+  public readonly bucket: s3.Bucket;
+  public readonly table: dynamodb.Table;
+  public readonly apiFunction: lambda.Function;
+  public readonly distribution: cloudfront.Distribution;
+
+  constructor(scope: Construct, id: string, props: FoundationPagesProps) {
+    super(scope, id, props);
+    const { instance } = props;
+    if (!instance.integrations.pages)
+      throw new Error(`${id}: FoundationPages needs integrations.pages: true`);
+    const names = namesFor(instance);
+    const display = instance.displayName;
+    const plan = pagesDomainPlan(instance, props.domainDelegated === true);
+    const domain = plan.attached;
+
+    this.bucket = new s3.Bucket(this, "PagesBucket", {
+      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+      encryption: s3.BucketEncryption.S3_MANAGED,
+      enforceSSL: true,
+      versioned: true,
+      objectOwnership: s3.ObjectOwnership.BUCKET_OWNER_ENFORCED,
+      // Published pages are company content: they outlive the stack, like the CRM table.
+      removalPolicy: cdk.RemovalPolicy.RETAIN,
+      lifecycleRules: [
+        // Staged chunks of an upload that never committed (the upload row lives an hour).
+        { id: "StagedUploads", prefix: "uploads/", expiration: cdk.Duration.days(1) },
+        // Versions are immutable by key; S3 versioning only guards against an operator mistake.
+        { id: "NoncurrentObjects", noncurrentVersionExpiration: cdk.Duration.days(30) },
+        { id: "IncompleteMultipart", abortIncompleteMultipartUploadAfter: cdk.Duration.days(1) },
+      ],
+    });
+
+    this.table = new dynamodb.Table(this, "PagesTable", {
+      partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
+      sortKey: { name: "sk", type: dynamodb.AttributeType.STRING },
+      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+      encryption: dynamodb.TableEncryption.CUSTOMER_MANAGED,
+      encryptionKey: props.dataKey,
+      pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: true },
+      timeToLiveAttribute: "ttl",
+      removalPolicy: cdk.RemovalPolicy.RETAIN,
+    });
+    // A conversation's pages, newest first (a later `page_list`, the phase-2 comment digest).
+    this.table.addGlobalSecondaryIndex({
+      indexName: "ChannelIndex",
+      partitionKey: { name: "gsi1pk", type: dynamodb.AttributeType.STRING },
+      sortKey: { name: "gsi1sk", type: dynamodb.AttributeType.STRING },
+      projectionType: dynamodb.ProjectionType.ALL,
+    });
+
+    // The cookie HMAC key. Generated by Secrets Manager at deploy time, so it
+    // is in no template; destroyed with the stack like other opt-in secrets
+    // (a new key only means everyone signs in again).
+    const cookieKey = new secretsmanager.Secret(this, "CookieKey", {
+      secretName: names.secretPagesCookieKey,
+      description: `${display} hosted-pages cookie signing key ({ key }); read by the sign-in Lambda and copied to the edge key store`,
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+      generateSecretString: {
+        secretStringTemplate: "{}",
+        generateStringKey: "key",
+        passwordLength: 64,
+        excludePunctuation: true,
+      },
+    });
+
+    const edgeKeys = new cloudfront.KeyValueStore(this, "EdgeKeys", {
+      comment: `${display} pages cookie key for the viewer function`,
+    });
+
+    // --- sign-in Lambda --------------------------------------------------
+    const authRole = new iam.Role(this, "PagesAuthRole", {
+      assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+      description: `${display} pages sign-in Lambda (Slack OIDC + membership check)`,
+      managedPolicies: [
+        iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+      ],
+    });
+    authRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PagesAuthSecrets",
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [secretArnPattern(props.secrets.slackApp), cookieKey.secretArn],
+      }),
+    );
+    authRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PagesAuthPageLookup",
+        actions: ["dynamodb:GetItem"],
+        resources: [this.table.tableArn],
+      }),
+    );
+    authRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PagesTableKey",
+        actions: ["kms:Decrypt", "kms:DescribeKey"],
+        resources: [props.dataKey.keyArn],
+      }),
+    );
+    const authFunction = new lambda.Function(this, "PagesAuthFunction", {
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambdaCode(this, "pages-auth"),
+      role: authRole,
+      timeout: cdk.Duration.seconds(15),
+      memorySize: 256,
+      environment: {
+        FOUNDATION_SLACK_APP_SECRET_ID: props.secrets.slackApp.secretName,
+        FOUNDATION_PAGES_COOKIE_SECRET_ID: cookieKey.secretName,
+        FOUNDATION_SLACK_TEAM_ID: instance.slack.teamId,
+        FOUNDATION_PAGES_TABLE_NAME: this.table.tableName,
+        FOUNDATION_DISPLAY_NAME: display,
+        ...(domain === undefined ? {} : { FOUNDATION_PAGES_DOMAIN: domain }),
+      },
+    });
+    // IAM auth: only CloudFront, signing through origin access control, can call it.
+    const authUrl = authFunction.addFunctionUrl({ authType: lambda.FunctionUrlAuthType.AWS_IAM });
+
+    // --- edge key seeding ------------------------------------------------
+    const seedRole = new iam.Role(this, "EdgeKeySeedRole", {
+      assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+      description: `${display} copies the pages cookie key into the edge key store`,
+      managedPolicies: [
+        iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+      ],
+    });
+    seedRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "ReadCookieKey",
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [cookieKey.secretArn],
+      }),
+    );
+    seedRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "WriteEdgeKey",
+        actions: [
+          "cloudfront-keyvaluestore:DescribeKeyValueStore",
+          "cloudfront-keyvaluestore:PutKey",
+        ],
+        resources: [edgeKeys.keyValueStoreArn],
+      }),
+    );
+    const seedFunction = new lambda.Function(this, "EdgeKeySeedFunction", {
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.edgeKeyHandler",
+      code: lambdaCode(this, "pages-auth"),
+      role: seedRole,
+      timeout: cdk.Duration.seconds(60),
+      memorySize: 256,
+    });
+    new cdk.CustomResource(this, "EdgeKeySeed", {
+      serviceToken: seedFunction.functionArn,
+      resourceType: "Custom::FoundationPagesEdgeKey",
+      properties: {
+        SecretId: cookieKey.secretArn,
+        KeyValueStoreArn: edgeKeys.keyValueStoreArn,
+        // Bump to copy the key again after rotating the secret.
+        Generation: "1",
+      },
+    });
+
+    // --- CloudFront ------------------------------------------------------
+    const viewerRequest = new cloudfront.Function(this, "ViewerRequest", {
+      runtime: cloudfront.FunctionRuntime.JS_2_0,
+      keyValueStore: edgeKeys,
+      comment: `${display} pages: cookie check and path mapping`,
+      code: cloudfront.FunctionCode.fromInline(pagesViewerRequestCode(edgeKeys.keyValueStoreId)),
+    });
+    const headers = new cloudfront.ResponseHeadersPolicy(this, "PagesHeaders", {
+      comment: `${display} pages security headers`,
+      securityHeadersBehavior: {
+        contentSecurityPolicy: {
+          contentSecurityPolicy: PAGES_CONTENT_SECURITY_POLICY,
+          override: true,
+        },
+        strictTransportSecurity: {
+          accessControlMaxAge: cdk.Duration.days(365),
+          includeSubdomains: false,
+          override: true,
+        },
+        contentTypeOptions: { override: true },
+        frameOptions: { frameOption: cloudfront.HeadersFrameOption.SAMEORIGIN, override: true },
+        referrerPolicy: {
+          referrerPolicy: cloudfront.HeadersReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN,
+          override: true,
+        },
+      },
+      customHeadersBehavior: {
+        customHeaders: [{ header: "X-Robots-Tag", value: "noindex, nofollow", override: true }],
+      },
+    });
+    // --- custom domain ---------------------------------------------------
+    // Foundation makes a public zone for exactly the pages subdomain, so the
+    // company delegates one name (NS records at its DNS provider) and never
+    // hands over its main zone. With `pages.hostedZoneId` the parent zone is
+    // already in this account and records go straight into it.
+    const zoneDomain = instance.pages.domain;
+    const zone: route53.IHostedZone | undefined =
+      zoneDomain === undefined
+        ? undefined
+        : instance.pages.hostedZoneId !== undefined
+          ? route53.HostedZone.fromHostedZoneId(
+              this,
+              "PagesParentZone",
+              instance.pages.hostedZoneId,
+            )
+          : new route53.PublicHostedZone(this, "PagesZone", {
+              zoneName: zoneDomain,
+              comment: `${display} hosted pages (delegated from the company's DNS)`,
+            });
+    let certificate: acm.ICertificate | undefined;
+    if (domain !== undefined && zone !== undefined) {
+      const certificateRole = new iam.Role(this, "PagesCertificateRole", {
+        assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+        description: `${display} issues the pages domain certificate in us-east-1`,
+        managedPolicies: [
+          iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+        ],
+      });
+      certificateRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "RequestCertificate",
+          // RequestCertificate has no resource-level scoping.
+          actions: ["acm:RequestCertificate"],
+          resources: ["*"],
+        }),
+      );
+      certificateRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "ManageCertificate",
+          actions: ["acm:DescribeCertificate", "acm:DeleteCertificate"],
+          resources: [`arn:${this.partition}:acm:us-east-1:${this.account}:certificate/*`],
+        }),
+      );
+      certificateRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "ValidationRecord",
+          actions: ["route53:ChangeResourceRecordSets"],
+          resources: [`arn:${this.partition}:route53:::hostedzone/${zone.hostedZoneId}`],
+        }),
+      );
+      const certificateFunction = new lambda.Function(this, "PagesCertificateFunction", {
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: "index.certificateHandler",
+        code: lambdaCode(this, "pages-auth"),
+        role: certificateRole,
+        // Bounded wait for ACM; the resource fails rather than hangs.
+        timeout: cdk.Duration.minutes(15),
+        memorySize: 256,
+      });
+      const issued = new cdk.CustomResource(this, "PagesCertificate", {
+        serviceToken: certificateFunction.functionArn,
+        resourceType: "Custom::FoundationPagesCertificate",
+        properties: { DomainName: domain, HostedZoneId: zone.hostedZoneId },
+      });
+      certificate = acm.Certificate.fromCertificateArn(
+        this,
+        "PagesCertificateArn",
+        issued.getAttString("CertificateArn"),
+      );
+    }
+
+    const functionAssociations = [
+      { function: viewerRequest, eventType: cloudfront.FunctionEventType.VIEWER_REQUEST },
+    ];
+    this.distribution = new cloudfront.Distribution(this, "Distribution", {
+      comment: `${display} pages`,
+      ...(domain === undefined || certificate === undefined
+        ? {}
+        : { domainNames: [domain], certificate }),
+      // Never a bucket listing at `/`, even if the viewer function were detached.
+      defaultRootObject: "index.html",
+      minimumProtocolVersion: cloudfront.SecurityPolicyProtocol.TLS_V1_2_2021,
+      httpVersion: cloudfront.HttpVersion.HTTP2_AND_3,
+      priceClass: cloudfront.PriceClass.PRICE_CLASS_100,
+      defaultBehavior: {
+        // LIST lets S3 answer a missing key with 404 rather than 403. The
+        // function only ever forwards mapped object keys, never a listing.
+        origin: origins.S3BucketOrigin.withOriginAccessControl(this.bucket, {
+          originAccessLevels: [cloudfront.AccessLevel.READ, cloudfront.AccessLevel.LIST],
+        }),
+        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+        allowedMethods: cloudfront.AllowedMethods.ALLOW_GET_HEAD,
+        // Access is decided by the viewer function before the cache, so the
+        // cache key needs no cookie: one cached copy serves every member.
+        cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
+        responseHeadersPolicy: headers,
+        functionAssociations,
+      },
+      additionalBehaviors: {
+        "/_auth/*": {
+          origin: origins.FunctionUrlOrigin.withOriginAccessControl(authUrl),
+          viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+          allowedMethods: cloudfront.AllowedMethods.ALLOW_GET_HEAD,
+          cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
+          originRequestPolicy: cloudfront.OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
+          responseHeadersPolicy: headers,
+          functionAssociations,
+        },
+      },
+    });
+    cdk.Annotations.of(this.distribution).acknowledgeWarning(
+      "@aws-cdk/aws-cloudfront-origins:listBucketSecurityRisk",
+      "The viewer function forwards only mapped object keys and 404s `/`; defaultRootObject is set too. LIST only turns a missing key into 404 instead of 403.",
+    );
+    if (domain !== undefined && zone !== undefined) {
+      const target = route53.RecordTarget.fromAlias(
+        new route53Targets.CloudFrontTarget(this.distribution),
+      );
+      // Fully qualified, so the parent-zone case needs no zone name.
+      new route53.ARecord(this, "PagesAliasA", { zone, recordName: `${domain}.`, target });
+      new route53.AaaaRecord(this, "PagesAliasAaaa", { zone, recordName: `${domain}.`, target });
+    }
+    const defaultUrl = `https://${this.distribution.distributionDomainName}`;
+    const baseUrl = domain === undefined ? defaultUrl : `https://${domain}`;
+
+    // --- Pages API proxy -------------------------------------------------
+    const apiRole = new iam.Role(this, "PagesApiRole", {
+      assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+      description: `${display} Pages API proxy (the only writer of the pages bucket and table)`,
+      managedPolicies: [
+        iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+      ],
+    });
+    apiRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PagesApiSigningSecret",
+        actions: ["secretsmanager:GetSecretValue"],
+        resources: [secretArnPattern(props.secrets.signing)],
+      }),
+    );
+    apiRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PagesTableData",
+        actions: [
+          "dynamodb:GetItem",
+          "dynamodb:PutItem",
+          "dynamodb:UpdateItem",
+          "dynamodb:Query",
+          "dynamodb:TransactWriteItems",
+          "dynamodb:ConditionCheckItem",
+        ],
+        resources: [this.table.tableArn],
+      }),
+    );
+    apiRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PagesTableKey",
+        actions: ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey", "kms:DescribeKey"],
+        resources: [props.dataKey.keyArn],
+      }),
+    );
+    apiRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "PagesObjects",
+        actions: ["s3:GetObject", "s3:PutObject"],
+        resources: [this.bucket.arnForObjects("pages/*"), this.bucket.arnForObjects("uploads/*")],
+      }),
+    );
+    this.apiFunction = new lambda.Function(this, "PagesApiFunction", {
+      functionName: names.pagesApiFunctionName,
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambdaCode(this, "pages-api"),
+      role: apiRole,
+      // A commit reassembles and verifies up to 100 MiB of staged chunks.
+      timeout: cdk.Duration.seconds(300),
+      memorySize: 1024,
+      environment: {
+        FOUNDATION_PAGES_TABLE_NAME: this.table.tableName,
+        FOUNDATION_PAGES_BUCKET_NAME: this.bucket.bucketName,
+        FOUNDATION_PAGES_BASE_URL: baseUrl,
+        FOUNDATION_SLACK_TEAM_ID: instance.slack.teamId,
+        FOUNDATION_SLACK_SIGNING_SECRET_ID: props.secrets.signing.secretName,
+      },
+    });
+
+    new cdk.CfnOutput(this, "PagesApiFunctionArn", { value: this.apiFunction.functionArn });
+    new cdk.CfnOutput(this, "PagesBaseUrl", { value: baseUrl });
+    new cdk.CfnOutput(this, "PagesDistributionDomainName", {
+      value: this.distribution.distributionDomainName,
+    });
+    new cdk.CfnOutput(this, "PagesAuthRedirectUrl", {
+      description: "Slack OAuth redirect URL for Sign in with Slack on the pages domain",
+      value: `${baseUrl}/_auth/callback`,
+    });
+    // Registered as well, so links from before a custom domain attached keep signing in.
+    new cdk.CfnOutput(this, "PagesDefaultAuthRedirectUrl", {
+      value: `${defaultUrl}/_auth/callback`,
+    });
+    new cdk.CfnOutput(this, "PagesCustomDomainAttached", {
+      value: domain === undefined ? "false" : "true",
+    });
+    if (domain !== undefined) new cdk.CfnOutput(this, "PagesCustomDomain", { value: domain });
+    if (zone instanceof route53.PublicHostedZone) {
+      new cdk.CfnOutput(this, "PagesHostedZoneId", { value: zone.hostedZoneId });
+      new cdk.CfnOutput(this, "PagesNameServers", {
+        description: `NS records to add for ${zoneDomain} at the company's DNS provider`,
+        value: cdk.Fn.join(",", zone.hostedZoneNameServers ?? []),
+      });
+    }
+  }
+}
+
+/** Imported secrets carry a partial ARN; match the 6-character suffix IAM needs. */
+function secretArnPattern(secret: secretsmanager.ISecret): string {
+  return secret.secretFullArn ?? `${secret.secretArn}-??????`;
+}