serverless-ircd 0.9.0 → 0.10.0

package/apps/aws-stack/src/static-site.ts

@@ -0,0 +1,323 @@
+/**
+ * `StaticSite` — the AWS web-client hosting substrate.
+ *
+ * Serves the shared `apps/web/dist` build artifact (the Kiwi IRC SPA +
+ * landing page) exclusively over CloudFront. The S3 origin bucket is
+ * private and grants the distribution via Origin Access Control (OAC),
+ * the modern AWS recommendation that supersedes the legacy Origin
+ * Access Identity (OAI). Direct S3 object access is denied; only the
+ * CloudFront URL serves the SPA.
+ *
+ * The bucket layout mirrors the CF Worker's `[assets]` binding (so the
+ * same `apps/web/dist` artifact ships on both platforms unchanged):
+ *   - `index.html`              → the project landing page (served at `/`)
+ *   - `webclient/index.html`    → the Kiwi SPA shell (served at `/webclient/`)
+ *   - `webclient/static/*`      → hashed JS/CSS bundles
+ *   - `docs/*`                  → rendered documentation pages
+ *
+ * `https://<dist>/` serves `index.html` via the distribution's
+ * `defaultRootObject`. SPA client-side routing under `/webclient/*` is
+ * handled by a CloudFront custom error response that maps S3's 403/404
+ * (the response when an object does not exist) to
+ * `200 /webclient/index.html`, so a deep link like
+ * `/webclient/networks/example` resolves to the SPA shell and Kiwi's
+ * hash/history router takes over.
+ *
+ * This is pure infrastructure — it does NOT build or bake the artifact
+ * (that is the per-env config bake and the deploy pipeline). Custom
+ * domain (ACM cert + CloudFront alias + optional Route53 record) is
+ * exposed via optional construct props and used by prod; the default
+ * uses the `*.cloudfront.net` URL.
+ */
+
+import { CfnOutput, Duration, RemovalPolicy } from 'aws-cdk-lib';
+import { Certificate } from 'aws-cdk-lib/aws-certificatemanager';
+import {
+  Function as CloudFrontFunction,
+  Distribution,
+  FunctionCode,
+  FunctionEventType,
+  ViewerProtocolPolicy,
+} from 'aws-cdk-lib/aws-cloudfront';
+import { S3BucketOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';
+import { ARecord, HostedZone, RecordTarget } from 'aws-cdk-lib/aws-route53';
+import { CloudFrontTarget } from 'aws-cdk-lib/aws-route53-targets';
+import { BlockPublicAccess, Bucket } from 'aws-cdk-lib/aws-s3';
+import { Construct } from 'constructs';
+
+/**
+ * Path of the landing page inside the origin bucket. Served by the
+ * distribution's `defaultRootObject` for requests to `/` (the project
+ * front door — links to the SPA, the rendered docs, and the source
+ * repo). Mirrors `dist/index.html` from `apps/web/scripts/build.mjs`
+ * step 5.
+ */
+const LANDING_INDEX_PATH = 'index.html';
+
+/**
+ * Path to the SPA shell inside the origin bucket. CloudFront serves this
+ * for any unmatched `/webclient/*` route (via the 403/404 → 200 custom
+ * error response), so client-side routing resolves to the SPA. Mirrors
+ * `dist/webclient/index.html` from `apps/web/scripts/build.mjs` step 3
+ * — the same path the CF Worker's `[assets]` binding serves the SPA at.
+ */
+const SPA_INDEX_PATH = '/webclient/index.html';
+
+/**
+ * CloudFront viewer-request function that resolves directory indexes for
+ * the S3 REST origin. S3 REST (used with Origin Access Control) does NOT
+ * serve index documents: a request for `/docs/` or `/docs` looks up an
+ * object literally named `docs/` (or `docs`) and 404s, which then falls
+ * through to the SPA error response and serves the Kiwi shell instead of
+ * the rendered docs index (reproduced live on `irc.aws.fowl.cloud`).
+ *
+ * The function makes directory-style URIs resolve to their `index.html`,
+ * matching the Cloudflare Worker `[assets]` binding (which resolves
+ * directory indexes automatically). Two cases:
+ *
+ *   - trailing slash (`/docs/`, `/`, `/webclient/`) → internal rewrite
+ *     appending `index.html` (browser URL unchanged; relative links in
+ *     the page already resolve against the directory);
+ *   - no trailing slash AND the last path segment has no file extension
+ *     (`/docs`, `/webclient`) → **301 redirect** to the trailing-slash
+ *     form. A redirect is used (rather than a silent rewrite to
+ *     `<path>/index.html`) so the BROWSER URL becomes `<path>/` and the
+ *     page's relative asset links (`<link href="docs.css">`) resolve
+ *     against the directory (`/docs/docs.css`) instead of the parent
+ *     (`/docs.css`). This mirrors Apache/nginx `DirectorySlash`.
+ *
+ * URIs whose last segment contains a `.` (every real static asset:
+ * `.html`, `.css`, `.js`, `.png`, `.json`, `.woff2`, `.ico`) are served
+ * unchanged. The redirect is safe: S3 REST currently resolves no
+ * no-extension path to a real object, so redirecting only ever helps
+ * (the trailing-slash form then resolves via the internal rewrite) or
+ * stays equivalent (SPA deep links like `/webclient/<route>` redirect
+ * to `<route>/`, then 404 → the SPA error response still serves
+ * `/webclient/index.html`, and Kiwi's router resolves from the URL).
+ * AWS publishes this pattern for S3-backed CloudFront distributions.
+ *
+ * Implemented with `var` + `indexOf`/`lastIndexOf`/`slice`/`endsWith`
+ * only — the CloudFront Functions runtime supports these (ES5.1 + the
+ * documented `String.prototype.endsWith`).
+ */
+const INDEX_DOCUMENT_FN_CODE = [
+  'function handler(event) {',
+  '    var request = event.request;',
+  '    var uri = request.uri;',
+  '    // Trailing slash: resolve to the directory index.html (internal rewrite).',
+  '    if (uri.endsWith("/")) {',
+  '        request.uri = uri + "index.html";',
+  '        return request;',
+  '    }',
+  '    // File (last path segment has an extension): serve unchanged.',
+  '    var lastSegment = uri.slice(uri.lastIndexOf("/") + 1);',
+  '    if (lastSegment.indexOf(".") !== -1) {',
+  '        return request;',
+  '    }',
+  '    // Directory path without a trailing slash: 301-redirect to the',
+  '    // trailing-slash form so the browser resolves relative asset URLs',
+  '    // against the directory (href="docs.css" -> /docs/docs.css, not',
+  '    // /docs.css). Rebuild the query string from the CloudFront Functions',
+  '    // object form ({ key: { value: "..." } }); request.querystring is',
+  '    // ALWAYS an object ({} when empty), never a raw string, so a truthy',
+  '    // check alone would append "?[object Object]".',
+  '    var qsRoot = request.querystring;',
+  '    var qsKeys = qsRoot ? Object.keys(qsRoot) : [];',
+  '    var qs = "";',
+  '    for (var qi = 0; qi < qsKeys.length; qi++) {',
+  '        var qk = qsKeys[qi];',
+  '        qs += (qs.length === 0 ? "?" : "&") + encodeURIComponent(qk) + "=" + encodeURIComponent(request.querystring[qk].value);',
+  '    }',
+  '    return {',
+  '        statusCode: 301,',
+  '        statusDescription: "Moved Permanently",',
+  '        headers: { location: { value: uri + "/" + qs } }',
+  '    };',
+  '}',
+].join('\n');
+
+/**
+ * Construct props for {@link StaticSite}.
+ *
+ * Custom domain is opt-in: when `customDomain` is omitted the
+ * distribution is reachable only via its default `*.cloudfront.net`
+ * domain (suitable for staging). Prod passes all three fields to wire a
+ * CloudFront alias + Route53 `ARecord`.
+ */
+export interface StaticSiteProps {
+  /**
+   * Custom domain name for the CloudFront distribution (e.g.
+   * `app.example.com`). When provided together with {@link certificateArn}
+   * the distribution is configured with this alias.
+   *
+   * @default - the distribution uses its default `*.cloudfront.net` domain.
+   */
+  readonly customDomain?: string;
+
+  /**
+   * ARN of an ACM certificate covering {@link customDomain}. The
+   * certificate MUST be in `us-east-1` (a CloudFront requirement). Only
+   * consulted when {@link customDomain} is set.
+   */
+  readonly certificateArn?: string;
+
+  /**
+   * Name of the Route53 hosted zone to add the alias record into (e.g.
+   * `example.com.`). When provided together with {@link customDomain} and
+   * {@link hostedZoneId} an `ARecord` aliasing the distribution is created.
+   * Only consulted when {@link customDomain} is set.
+   */
+  readonly hostedZoneName?: string;
+
+  /**
+   * Public Route53 hosted zone ID for {@link hostedZoneName}. Required to
+   * materialise the alias record (CDK's `fromHostedZoneAttributes` needs
+   * both the name and the ID; `fromLookup` is avoided so `cdk synth` does
+   * not require AWS credentials). Discoverable via
+   * `aws route53 list-hosted-zones-by-name --dns-name <hostedZoneName>`.
+   * Only consulted when {@link customDomain} is set.
+   */
+  readonly hostedZoneId?: string;
+}
+
+/**
+ * Serves the web client over CloudFront backed by a private S3 bucket
+ * with Origin Access Control.
+ *
+ * The bucket is never public-read; CloudFront reads it via an OAC and a
+ * bucket policy scoped to this distribution (`AWS:SourceArn`). The
+ * landing page at `/` is served via the distribution's
+ * `defaultRootObject` (`index.html`); a custom error response maps
+ * 403/404 → `200 /webclient/index.html` so SPA routes under
+ * `/webclient/*` resolve. The bucket layout mirrors the CF Worker's
+ * `[assets]` binding so the same `apps/web/dist` artifact ships on
+ * both platforms unchanged.
+ */
+export class StaticSite extends Construct {
+  /** The private S3 origin bucket holding the web client artifact. */
+  readonly bucket: Bucket;
+
+  /** The CloudFront distribution serving the SPA. */
+  readonly distribution: Distribution;
+
+  constructor(scope: Construct, id: string, props: StaticSiteProps = {}) {
+    super(scope, id);
+
+    // Private origin bucket. Block ALL public access and attach no public
+    // read ACL — the bucket is reachable only through CloudFront via the
+    // OAC-granted bucket policy. AutoDeleteObjects + DESTROY keeps the
+    // dev/test stack clean on `cdk destroy` (the deploy pipeline owns
+    // the object lifecycle in real envs via s3 sync).
+    this.bucket = new Bucket(this, 'Bucket', {
+      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
+      removalPolicy: RemovalPolicy.DESTROY,
+      autoDeleteObjects: true,
+    });
+
+    // CloudFront distribution. The default behavior routes to the S3
+    // origin via OAC (`S3BucketOrigin.withOriginAccessControl` auto-creates
+    // the `S3OriginAccessControl` and the `cloudfront.amazonaws.com`
+    // service-principal bucket policy scoped by `AWS:SourceArn`).
+    // HTTPS is enforced by redirecting HTTP viewers.
+    //
+    // The `as never` cast on the bucket bypasses an `exactOptionalPropertyTypes`
+    // friction between the concrete `Bucket` and the `IBucket` interface
+    // (optional vs required properties in the CDK jsii layer); the same
+    // pattern is used elsewhere in this stack for the NLB `Vpc`.
+    const origin = S3BucketOrigin.withOriginAccessControl(this.bucket as never);
+
+    // Directory-index resolver. S3 REST (OAC) does not serve index
+    // documents, so `/docs/` and `/docs` would 404 and fall through to the
+    // SPA error response below. This viewer-request function appends
+    // `index.html` to directory-style URIs first, mirroring the CF Worker
+    // `[assets]` binding (see {@link INDEX_DOCUMENT_FN_CODE} for the full
+    // rationale + the SPA-deep-link interaction).
+    const indexFunction = new CloudFrontFunction(this, 'IndexDocumentFunction', {
+      code: FunctionCode.fromInline(INDEX_DOCUMENT_FN_CODE),
+    });
+
+    // SPA fallback: S3 returns 403/404 for any `/webclient/*` path that is
+    // not a real object (i.e. a client-side route). Map both to a `200`
+    // response serving the SPA shell so Kiwi's router can resolve the
+    // deep link. The landing page at `/` is unaffected (served via
+    // `defaultRootObject` below, not via the error response).
+    const errorResponses = [
+      {
+        httpStatus: 403,
+        responseHttpStatus: 200,
+        responsePagePath: SPA_INDEX_PATH,
+        ttl: Duration.seconds(0),
+      },
+      {
+        httpStatus: 404,
+        responseHttpStatus: 200,
+        responsePagePath: SPA_INDEX_PATH,
+        ttl: Duration.seconds(0),
+      },
+    ];
+
+    // Optional custom domain. Only wired when `customDomain` is provided;
+    // otherwise the distribution uses its default `*.cloudfront.net`
+    // domain (staging). The certificate MUST be in us-east-1 (a CloudFront
+    // requirement) — validated at deploy time.
+    const domainNames = props.customDomain !== undefined ? [props.customDomain] : undefined;
+    const certificate =
+      props.customDomain !== undefined && props.certificateArn !== undefined
+        ? Certificate.fromCertificateArn(this, 'Certificate', props.certificateArn)
+        : undefined;
+
+    this.distribution = new Distribution(this, 'Distribution', {
+      // The landing page (`dist/index.html`, the project front door with
+      // links to the SPA + docs + source repo) is served at `/`. The SPA
+      // shell lives at `/webclient/index.html` and is reached either
+      // directly or via the 403/404 error-response fallback for deep
+      // links. CloudFront's `DefaultRootObject` does NOT take a leading
+      // slash (unlike `responsePagePath`).
+      defaultRootObject: LANDING_INDEX_PATH,
+      defaultBehavior: {
+        origin,
+        viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+        functionAssociations: [
+          { eventType: FunctionEventType.VIEWER_REQUEST, function: indexFunction },
+        ],
+      },
+      errorResponses,
+      ...(domainNames !== undefined ? { domainNames } : {}),
+      ...(certificate !== undefined ? { certificate } : {}),
+    });
+
+    // Route53 alias record for the custom domain. Only created when the
+    // custom domain AND its hosted zone (name + id) are supplied; the
+    // certificate is optional only in the sense that CloudFront requires
+    // it for an alias, so a missing cert surfaces as a deploy-time CFN
+    // error rather than a synth-time crash. The zone is imported via
+    // `fromHostedZoneAttributes` (explicit name + id) rather than
+    // `fromLookup` so `cdk synth` does not require AWS credentials.
+    if (
+      props.customDomain !== undefined &&
+      props.hostedZoneName !== undefined &&
+      props.hostedZoneId !== undefined
+    ) {
+      const zone = HostedZone.fromHostedZoneAttributes(this, 'HostedZone', {
+        zoneName: props.hostedZoneName,
+        hostedZoneId: props.hostedZoneId,
+      });
+      new ARecord(this, 'AliasRecord', {
+        zone,
+        recordName: props.customDomain,
+        target: RecordTarget.fromAlias(new CloudFrontTarget(this.distribution)),
+      });
+    }
+
+    // Pin the logical id to the stable key `WebsiteURL` so the deployed
+    // stack exposes `Stack.WebsiteURL` rather than the CDK-hashed default
+    // (`StaticSiteWebsiteURL<8-hex>`). Matches the convention used by the
+    // parent-stack outputs (`WebsiteBucketName`, `WebsiteDistributionId`)
+    // and keeps `describe-stacks --query` lookups predictable.
+    const urlOutput = new CfnOutput(this, 'WebsiteURL', {
+      description: 'CloudFront distribution domain serving the web client (HTTPS).',
+      value: this.distribution.domainName,
+    });
+    urlOutput.overrideLogicalId('WebsiteURL');
+  }
+}

package/apps/aws-stack/tests/smoke-helpers.test.ts

@@ -61,7 +61,7 @@ describe('parseArgs', () => {
   });
 
   it('tolerates a leading -- options terminator (pnpm script passthrough)', () => {
-    // `pnpm smoke:aws:staging -- --url wss://x` forwards `['--', '--url', 'wss://x']`.
+    // `pnpm smoke:aws -- --url wss://x` forwards `['--', '--url', 'wss://x']`.
     expect(parseArgs(['--', '--url', 'wss://irc.example.com/prod'])).toStrictEqual<ParseResult>({
       url: 'wss://irc.example.com/prod',
       help: false,