serverless-ircd 0.9.0 → 0.10.0

package/.github/workflows/deploy-aws.yml

@@ -2,30 +2,31 @@ name: deploy-aws
 
 # AWS CDK deploy pipeline.
 #
-# On every push to `main`:
+# This workflow is `workflow_dispatch`-only — there is no automatic
+# push-to-main trigger. A maintainer runs it by hand to ship the single
+# AWS stack target (`apps/aws-stack`):
 #   1. Install deps (frozen lockfile).
 #   2. Build the aws-adapter + irc-core/irc-server so the CDK stack
 #      typechecks against real workspace packages.
 #   3. `cdk deploy --all` the `apps/aws-stack` stack (API Gateway v2
-#      WebSocket API, Lambda, DynamoDB tables) to the staging AWS
-#      account/region.
+#      WebSocket API, Lambda, DynamoDB tables).
 #   4. Replay the smoke e2e (`scripts/smoke.mjs`) against the deployed
 #      WebSocket endpoint — CONNECT/REGISTER/JOIN/PRIVMSG/QUIT. Failure
 #      blocks the merge (the deploy job is required on `main`).
 #
 # Secrets / variables (configure under repo Settings → Secrets and
 # variables → Actions):
-#   AWS_ACCESS_KEY_ID     Static AWS access key with permission to deploy
-#                          the stack (IAM, APIGW, Lambda, DynamoDB).
-#                          Required unless OIDC is used (see below).
-#   AWS_SECRET_ACCESS_KEY Companion secret key. Required unless OIDC.
-#   AWS_DEPLOY_ROLE_ARN   Optional. When set, the job assumes this role
-#                          via OIDC web identity instead of using static
-#                          access keys. Requires `permissions.id-token:
-#                          write` (declared below) and an OIDC trust
-#                          policy on the role granting
-#                          `sts:AssumeRoleWithWebIdentity` to this repo's
-#                          GitHub OIDC provider.
+#   AWS_DEPLOY_ROLE_ARN   REQUIRED. ARN of the IAM role the workflow
+#                          assumes via GitHub OIDC web identity. The
+#                          role's trust policy MUST condition on
+#                          `token.actions.githubusercontent.com:sub`
+#                          = `repo:<owner>/<repo>:ref:refs/heads/main`
+#                          (see docs/AWS-Deployment.md §17 for the
+#                          trust-policy snippet). Long-lived access
+#                          keys (`AWS_ACCESS_KEY_ID` /
+#                          `AWS_SECRET_ACCESS_KEY`) are NOT accepted —
+#                          a single exfil vector against them is full
+#                          AWS account takeover.
 #   AWS_REGION            AWS region to deploy into (e.g. us-east-1).
 #
 # Repo variable (Settings → Secrets and variables → Variables):
@@ -38,22 +39,23 @@ name: deploy-aws
 #                          behaviour).
 
 on:
-  # Automatic push trigger disabled; deploy only runs manually.
   workflow_dispatch:
 
-# OIDC web identity requires id-token write; contents:read for checkout.
+# GitHub OIDC web identity: id-token write so Actions can mint a JWT
+# for `sts:AssumeRoleWithWebIdentity`; contents:read for checkout.
+# Least-privilege — no other GITHUB_TOKEN permissions granted.
 permissions:
   id-token: write
   contents: read
 
 # Prevent two deploys racing the same CloudFormation stack.
 concurrency:
-  group: aws-staging
+  group: aws-deploy
   cancel-in-progress: false
 
 jobs:
-  deploy-staging:
-    name: cdk deploy --all (staging)
+  deploy:
+    name: cdk deploy --all
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -81,20 +83,55 @@ jobs:
       - name: Test
         run: pnpm test
 
-      # When AWS_DEPLOY_ROLE_ARN is set, assume it via OIDC web identity
-      # (ignores the static access keys). Otherwise fall back to the
-      # static access-key pair. Both shapes are handled by the action:
-      # an empty role-to-assume is treated as unset.
+      # Fail fast before any AWS call if the OIDC role ARN is missing.
+      # `AWS_DEPLOY_ROLE_ARN` is the ONLY accepted credential source —
+      # long-lived access keys are intentionally not wired in.
+      - name: Assert OIDC deploy role ARN is set
+        if: env.AWS_DEPLOY_ROLE_ARN == ''
+        env:
+          AWS_DEPLOY_ROLE_ARN: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+        run: |
+          echo "::error::AWS_DEPLOY_ROLE_ARN secret is empty — configure the GitHub OIDC IAM role trust before deploying (see docs/AWS-Deployment.md §17)."
+          exit 1
+
+      # OIDC-only: assume the configured role via web identity. No
+      # static access keys are accepted; if the role ARN is empty the
+      # step above has already failed the job.
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v4
         with:
           aws-region: ${{ secrets.AWS_REGION }}
           role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
-          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
 
-      - name: Deploy to staging
-        run: pnpm deploy:aws:staging -- -c environmentName=staging
+      # Defence-in-depth: confirm sts:AssumeRoleWithWebIdentity actually
+      # minted the configured role and the job is NOT running on
+      # ambient static credentials. Aborts before any `cdk deploy`.
+      - name: Assert assumed role matches AWS_DEPLOY_ROLE_ARN
+        env:
+          AWS_DEPLOY_ROLE_ARN: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+        run: |
+          set -euo pipefail
+          CALLER_ARN=$(aws sts get-caller-identity --query 'Arn' --output text)
+          ASSUMED_ROLE_ARN="${AWS_DEPLOY_ROLE_ARN}"
+          # The caller ARN for an OIDC-assumed role looks like
+          #   arn:aws:sts::<account>:assumed-role/<role-name>/GitHubActions
+          # while AWS_DEPLOY_ROLE_ARN is the role ARN
+          #   arn:aws:iam::<account>:role/<role-name>
+          # Compare by role-name + account-id so the two shapes match.
+          CALLER_ROLE=$(echo "$CALLER_ARN" | sed -n 's#.*assumed-role/\([^/]*\).*#\1#p')
+          CALLER_ACCT=$(echo "$CALLER_ARN" | sed -n 's#arn:aws:sts::\([0-9]*\).*#\1#p')
+          CONFIG_ROLE=$(echo "$ASSUMED_ROLE_ARN" | sed -n 's#.*/role/\([^/]*\)#\1#p')
+          CONFIG_ACCT=$(echo "$ASSUMED_ROLE_ARN" | sed -n 's#arn:aws:iam::\([0-9]*\).*#\1#p')
+          if [ -z "$CALLER_ROLE" ] || [ -z "$CONFIG_ROLE" ] \
+             || [ "$CALLER_ROLE" != "$CONFIG_ROLE" ] \
+             || [ "$CALLER_ACCT" != "$CONFIG_ACCT" ]; then
+            echo "::error::STS caller-identity does not match AWS_DEPLOY_ROLE_ARN (got '$CALLER_ARN', expected role '$CONFIG_ROLE' in account '$CONFIG_ACCT'). OIDC did not mint the configured role — aborting before cdk deploy."
+            exit 1
+          fi
+          echo "OIDC role assertion passed: $CALLER_ROLE in account $CALLER_ACCT"
+
+      - name: Deploy stack
+        run: pnpm deploy:aws
 
       - name: Resolve smoke URL
         id: smoke-url
@@ -105,16 +142,15 @@ jobs:
             echo "url=$AWS_SMOKE_URL" >> "$GITHUB_OUTPUT"
           else
             # Fall back to the stack's ConnectUrl CloudFormation output.
-            # Stack name is `IrcAwsStack-<environmentName>`; staging →
-            # `IrcAwsStack-staging`.
+            # Stack name is `IrcAwsStack` (single target, no env suffix).
             URL=$(aws cloudformation describe-stacks \
-              --stack-name IrcAwsStack-staging \
+              --stack-name IrcAwsStack \
               --query 'Stacks[0].Outputs[?OutputKey==`ConnectUrl`].OutputValue' \
               --output text 2>/dev/null || true)
             if [ -n "$URL" ]; then
               echo "url=$URL" >> "$GITHUB_OUTPUT"
             else
-              echo "::warning::Unable to resolve the staging WebSocket URL (set the AWS_SMOKE_URL repo variable or check the stack ConnectUrl output); smoke step will be skipped."
+              echo "::warning::Unable to resolve the WebSocket URL (set the AWS_SMOKE_URL repo variable or check the stack ConnectUrl output); smoke step will be skipped."
               echo "url=" >> "$GITHUB_OUTPUT"
             fi
           fi
@@ -123,4 +159,92 @@ jobs:
         if: steps.smoke-url.outputs.url != ''
         env:
           SMOKE_URL: ${{ steps.smoke-url.outputs.url }}
-        run: pnpm smoke:aws:staging -- --url "$SMOKE_URL"
+        run: pnpm smoke:aws -- --url "$SMOKE_URL"
+
+  # ---------------------------------------------------------------------------
+  # deploy-web — AWS web client two-phase deploy (s3 sync + CloudFront
+  # invalidation, stack-output-driven).
+  #
+  # The SPA lives in S3 behind CloudFront (provisioned by the StaticSite
+  # construct in apps/aws-stack). It ships SEPARATELY from the runtime
+  # stack because the deploy pipeline needs the stack's CloudFormation
+  # outputs (the API Gateway WebSocket URL, the S3 bucket name, the
+  # CloudFront distribution ID) to exist BEFORE it can bake the SPA —
+  # `cdk deploy` therefore runs first (the `deploy` job above), then this
+  # job reads the outputs and:
+  #   1. `aws cloudformation describe-stacks --stack-name IrcAwsStack`
+  #      reads `ConnectUrl`, `WebsiteBucketName`, `WebsiteDistributionId`.
+  #   2. `pnpm --filter @serverless-ircd/web run build:prod-aws -- --api-url <url>`
+  #      bakes the SPA with the real wss URL (no hardcoded URLs in the repo).
+  #   3. `aws s3 sync apps/web/dist s3://<bucket> --delete` uploads the
+  #      build (the CLI skips unchanged objects via etag comparison).
+  #   4. `aws cloudfront create-invalidation --distribution-id <id> --paths /*`
+  #      busts the edge cache.
+  #
+  # Why a script instead of CDK `BucketDeployment`: the script reads
+  # post-deploy outputs that do not exist at synth time, avoids
+  # re-synth-on-every-deploy, and is faster. See
+  # `scripts/deploy-web-aws.mjs` and `docs/AWS-Deployment.md`.
+  #
+  # Staleness note: T170 collapsed the staging/prod split — there is no
+  # `staging` branch and this job is `workflow_dispatch`-only on the
+  # current branch, mirroring the parent pipeline. A maintainer runs the
+  # workflow by hand to ship the AWS web client.
+  # ---------------------------------------------------------------------------
+  deploy-web:
+    name: web deploy (s3 sync + CloudFront invalidation)
+    needs: deploy
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # The web client build requires the Kiwi IRC upstream submodule
+          # and the docs/ submodule (rendered into dist/docs/ by build.mjs).
+          submodules: recursive
+
+      - name: Checkout submodules (worktree-safe fallback)
+        run: |
+          # `submodules: recursive` covers the normal case; this fallback
+          # ensures the Kiwi + docs submodules are present even when the
+          # checkout action's recursive flag was a no-op (older runners /
+          # path-filter configurations).
+          git submodule update --init --recursive
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Fail fast before any AWS call if the OIDC role ARN is missing.
+      # Mirrors the guard in the `deploy` job — the `deploy-web` job
+      # also assumes the role via OIDC and accepts no static keys.
+      - name: Assert OIDC deploy role ARN is set
+        if: env.AWS_DEPLOY_ROLE_ARN == ''
+        env:
+          AWS_DEPLOY_ROLE_ARN: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+        run: |
+          echo "::error::AWS_DEPLOY_ROLE_ARN secret is empty — configure the GitHub OIDC IAM role trust before deploying (see docs/AWS-Deployment.md §17)."
+          exit 1
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ secrets.AWS_REGION }}
+          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+
+      # Two-phase deploy: describe-stacks → bake (--api-url) → s3 sync →
+      # create-invalidation. Implemented in scripts/deploy-web-aws.mjs;
+      # exits non-zero with a clear message if any required stack output
+      # is missing (i.e. the parent `deploy` job did not run first or the
+      # stack's `webSite` prop is not configured).
+      - name: Deploy web client (bake + s3 sync + CloudFront invalidation)
+        run: node scripts/deploy-web-aws.mjs

package/.github/workflows/deploy-cf-tcp.yml

@@ -6,8 +6,11 @@ name: deploy-cf-tcp
 # Containers and applies the Spectrum TLS config (terraform). Spectrum
 # terminates TLS on :6697 and forwards plaintext TCP to the container.
 #
-# This pipeline runs alongside deploy-cf.yml (the WebSocket path). The two
-# are independent: a deployment can enable either or both transports.
+# This pipeline is `workflow_dispatch`-only — there is no automatic
+# push-to-main trigger. A maintainer runs it by hand to ship the single
+# TCP container target. It runs alongside deploy-cf.yml (the WebSocket
+# path); the two are independent, so a deployment can enable either or
+# both transports.
 #
 # Secrets (configure under repo Settings → Secrets and variables → Actions):
 #   CLOUDFLARE_API_TOKEN    Spectrum/Containers API token.
@@ -16,16 +19,15 @@ name: deploy-cf-tcp
 #   CF_TCP_ORIGIN_ADDRESS   Hostname/IP of the container origin.
 
 on:
-  # Automatic push trigger disabled; deploy only runs manually.
   workflow_dispatch:
 
 concurrency:
-  group: cf-tcp-staging
+  group: cf-tcp-deploy
   cancel-in-progress: false
 
 jobs:
-  deploy-staging:
-    name: deploy cf-tcp staging
+  deploy:
+    name: deploy cf-tcp
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
@@ -53,19 +55,19 @@ jobs:
       - name: Test
         run: pnpm --filter '@serverless-ircd/cf-tcp-container' test
 
-      - name: Deploy container to staging
+      - name: Deploy container
         working-directory: apps/cf-tcp-container
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-        run: wrangler deploy --env staging
+        run: wrangler deploy
 
       - name: Apply Spectrum TLS config
         working-directory: apps/cf-tcp-container/terraform
         env:
           TF_VAR_zone_id: ${{ secrets.CF_ZONE_ID }}
           TF_VAR_origin_address: ${{ secrets.CF_TCP_ORIGIN_ADDRESS }}
-          TF_VAR_hostname: irc-staging.example.com
+          TF_VAR_hostname: irc.example.com
         run: |
           terraform init
           terraform apply -auto-approve

package/.github/workflows/deploy-cf.yml

@@ -2,12 +2,13 @@ name: deploy-cf
 
 # Cloudflare Workers deploy pipeline.
 #
-# On every push to `main`:
+# This workflow is `workflow_dispatch`-only — there is no automatic
+# push-to-main trigger. A maintainer runs it by hand to ship the single
+# Cloudflare Worker target (`apps/cf-worker`):
 #   1. Install deps (frozen lockfile).
 #   2. Build the cf-adapter + irc-core/irc-server so the Worker entry
 #      typechecks against real workspace packages.
-#   3. `wrangler deploy --env staging` the `apps/cf-worker` worker to the
-#      `serverless-ircd-staging` Worker + DO namespace.
+#   3. `wrangler deploy` the `apps/cf-worker` worker.
 #   4. Replay the smoke e2e (`scripts/smoke.mjs`) against the deployed
 #      URL — CONNECT/REGISTER/JOIN/PRIVMSG/QUIT. Failure blocks the
 #      merge (the deploy job is required on `main`).
@@ -19,23 +20,22 @@ name: deploy-cf
 #   CLOUDFLARE_ACCOUNT_ID  Optional; required if the token's account
 #                          context is ambiguous.
 #
-# The smoke URL is derived from the staging Worker name
-# (`serverless-ircd-staging`) plus the deployer's account subdomain.
-# Override by setting `CF_SMOKE_URL` in the repo Variables store when
-# custom routes are wired.
+# The smoke URL is derived from the Worker name (`serverless-ircd`)
+# plus the deployer's account subdomain. Override by setting
+# `CF_SMOKE_URL` in the repo Variables store when custom routes are
+# wired.
 
 on:
-  # Automatic push trigger disabled; deploy only runs manually.
   workflow_dispatch:
 
 # Prevent two deploys racing the same DO namespace.
 concurrency:
-  group: cf-staging
+  group: cf-deploy
   cancel-in-progress: false
 
 jobs:
-  deploy-staging:
-    name: wrangler deploy --env staging
+  deploy:
+    name: wrangler deploy
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -63,12 +63,12 @@ jobs:
       - name: Test
         run: pnpm test
 
-      - name: Deploy to staging
+      - name: Deploy Worker
         working-directory: apps/cf-worker
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-        run: pnpm deploy:staging
+        run: pnpm run deploy
 
       - name: Resolve smoke URL
         id: smoke-url
@@ -82,7 +82,7 @@ jobs:
             # The subdomain is per-account; if CF_SMOKE_URL isn't set we
             # fall back to a workers.dev route that the deployer must
             # configure once via the Cloudflare dashboard.
-            echo "::warning::CF_SMOKE_URL repo variable is not set; smoke step will be skipped. Set it to the staging Worker's wss:// URL."
+            echo "::warning::CF_SMOKE_URL repo variable is not set; smoke step will be skipped. Set it to the Worker's wss:// URL."
             echo "url=" >> "$GITHUB_OUTPUT"
           fi