Prepare gamification-api develop deployment with OIDC v2.0.5

.circleci/config.yml

@@ -1,74 +1,115 @@
 version: 2.1
-defaults: &defaults
-  docker:
-    - image: cimg/python:3.13.2-browsers
-
-install_dependency: &install_dependency
-  name: Installation of build and deployment dependencies.
-  command: |
-      sudo apt update
-      sudo apt install python3-pip
-      sudo pip3 install awscli --upgrade 
-
-install_deploysuite: &install_deploysuite
-  name: Installation of install_deploysuite.
-  command: |
-    git clone --branch v1.4.20 https://github.com/topcoder-platform/tc-deploy-scripts ../buildscript
-    cp ./../buildscript/master_deploy.sh .
-    cp ./../buildscript/buildenv.sh .
-    cp ./../buildscript/awsconfiguration.sh .
-    cp ../buildscript/psvar-processor.sh .
-
-builddeploy_steps: &builddeploy_steps
-      - checkout
-      - setup_remote_docker
-      - run: *install_dependency
-      - run: *install_deploysuite
-      - run: ./build.sh ${APPNAME}
-      - deploy:
-          name: Running MasterScript.
-          command: |
-            ./awsconfiguration.sh $DEPLOY_ENV
-            source awsenvconf
-            ./psvar-processor.sh -t appenv -p /config/${APPNAME}/deployvar
-            source deployvar_env
-            ./master_deploy.sh -d ECS -e $DEPLOY_ENV -t latest -j /config/${APPNAME}/appvar -i ${APPNAME} -p FARGATE
-
+executors:
+  reviewed:
+    docker:
+    - image: cimg/aws@sha256:4cf3768db00ddf9bc439b8c84e8a60c11a14edf81c8baf76f74132144f8340d5
+commands:
+  checkout-source:
+    steps:
+    - run:
+        name: Check out the exact public source commit over HTTPS
+        command: |
+          set -euo pipefail
+          [[ "$CIRCLE_SHA1" =~ ^[0-9a-f]{40}$ ]]
+          export GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null GIT_TERMINAL_PROMPT=0
+          git init --quiet .
+          git remote add origin https://github.com/topcoder-platform/gamification-api.git
+          git -c credential.helper= fetch --quiet --depth 1 origin "$CIRCLE_SHA1"
+          git checkout --quiet --detach FETCH_HEAD
+          test "$(git rev-parse HEAD)" = "$CIRCLE_SHA1"
+  checkout-suite:
+    steps:
+    - run:
+        name: Verify deployment suite v2.0.6
+        command: |
+          set -euo pipefail
+          git init --quiet /tmp/tc-deploy-scripts
+          git -C /tmp/tc-deploy-scripts remote add origin https://github.com/topcoder-platform/tc-deploy-scripts.git
+          git -C /tmp/tc-deploy-scripts fetch --quiet --depth 1 origin refs/tags/v2.0.6
+          git -C /tmp/tc-deploy-scripts checkout --quiet --detach FETCH_HEAD
+          test "$(git -C /tmp/tc-deploy-scripts rev-parse HEAD)" = 26aaf607463d4a271c0099854c1731214215a9c5
 jobs:
-  # Build & Deploy against development backend
-  "build-dev":
-    <<: *defaults
-    environment:
-      DEPLOY_ENV: "DEV"
-      LOGICAL_ENV: "dev"
-      APPNAME: "tc-gamification"
-      BUILDSTAGE: "development"    
-    steps: *builddeploy_steps
-
-  "build-prod":
-    <<: *defaults
+  build:
+    executor: reviewed
+    steps:
+    - checkout-source
+    - setup_remote_docker
+    - checkout-suite
+    - run:
+        name: Build committed source without AWS or broker credentials
+        command: |
+          set -euo pipefail
+          case "$CIRCLE_BRANCH" in
+            develop) target=development-build-stage ;;
+            *) target=production-build-stage ;;
+          esac
+          python3 -I /tmp/tc-deploy-scripts/build_image.py --dockerfile Dockerfile --target "$target" --image gamification-api:candidate
+          mkdir -p /tmp/release
+          docker save --output /tmp/release/image.tar gamification-api:candidate
+        no_output_timeout: 30m
+    - persist_to_workspace:
+        root: /tmp/release
+        paths:
+        - image.tar
+  deploy:
+    executor: reviewed
+    parameters:
+      environment:
+        type: enum
+        enum:
+        - dev
+        - prod
     environment:
-      DEPLOY_ENV: "PROD"
-      LOGICAL_ENV: "prod"    
-      APPNAME: "tc-gamification" 
-      BUILDSTAGE: "production"  
-    steps: *builddeploy_steps
-
+      DEPLOY_ENV: << parameters.environment >>
+    steps:
+    - checkout-source
+    - setup_remote_docker
+    - checkout-suite
+    - attach_workspace:
+        at: /tmp/release
+    - run:
+        name: Promote a scanned digest with repository-bound OIDC
+        command: |
+          set +x
+          set -euo pipefail
+          test -f "deploy/${DEPLOY_ENV}.json"
+          docker load --input /tmp/release/image.tar
+          python3 -I deploy/release.py "deploy/${DEPLOY_ENV}.json"
+        no_output_timeout: 45m
 workflows:
-  version: 2
-  build:
+  release:
     jobs:
-      # Development builds are executed on "develop" branch only.
-      - "build-dev":
-          context : org-global
-          filters:
-            branches:
-              only: [develop, db_schema]
-
-      # Production builds are exectuted only on tagged commits to the
-      # master branch.
-      - "build-prod":
-          context : org-global
-          filters:
-            branches:
-              only: master
+    - build
+    - deploy:
+        name: deploy-dev
+        environment: dev
+        requires:
+        - build
+        context: gamification-api-dev-deploy
+        serial-group: << pipeline.project.slug >>/deploy-dev
+        filters:
+          branches:
+            only: develop
+          tags:
+            ignore: /.*/
+    - approve-prod:
+        type: approval
+        requires:
+        - build
+        filters:
+          branches:
+            only: master
+          tags:
+            ignore: /.*/
+    - deploy:
+        name: deploy-prod
+        environment: prod
+        requires:
+        - approve-prod
+        context: gamification-api-prod-deploy
+        serial-group: << pipeline.project.slug >>/deploy-prod
+        filters:
+          branches:
+            only: master
+          tags:
+            ignore: /.*/

.gitignore

@@ -128,3 +128,7 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+# Infrastructure definitions and detailed AWS inventories are maintained privately.
+/deploy/iam/
+/deploy/*-baseline.json

Dockerfile

@@ -6,9 +6,9 @@ FROM ${NODE_IMAGE} AS build-stage
 
 WORKDIR /app
 
-COPY package.json package-lock.json .npmrc ./
+COPY package.json package-lock.json ./
 COPY tools ./tools
-RUN npm ci
+RUN npm ci --install-links=true
 
 COPY . .
 RUN npm run build
@@ -26,9 +26,9 @@ FROM ${NODE_IMAGE} AS production-dependencies-stage
 
 WORKDIR /app
 
-COPY package.json package-lock.json .npmrc ./
+COPY package.json package-lock.json ./
 COPY tools ./tools
-RUN npm ci --omit=dev --ignore-scripts \
+RUN npm ci --install-links=true --omit=dev --ignore-scripts \
     && npm cache clean --force
 
 FROM ${NODE_IMAGE} AS runtime-stage

README.md

@@ -17,7 +17,7 @@ export POSTGRE_SQL_DATABASE=<HOST&DB_NAME>
 
 3. `npm run init-db`
 4. `npm run seed-db` - optional step, assuming you want mock data for development.
-5. Set the local environment file - we keep a sample file with all vars one needs to have set to be able to run the API locally. Check the `.env.development.local.sample`, fill it with proper values, and finally rename it to `.env.development.local`. Done, vars will be picked-up on server start.
+5. Set the local environment file - we keep a sample file with all vars one needs to have set to be able to run the API locally. Check the `.env.sample`, fill it with proper values, and finally rename it to `.env.development.local`. Done, vars will be picked-up on server start.
 6. `npm run dev`
 
 ## Docker support
@@ -68,9 +68,9 @@ We follow strict naming convention: `org_id/badge_image_id.file_ext`. This will
 This is public access bucket, which provides access to the digital assets used by the gamification project. All files are served with proper HTTP headers. We set `CacheControl: 'max-age=31536000'` (365 days)  header to all badge images which ensures speed loading and reduces traffic.
 ### Dependency security checks
 
-Use the Node 24 version in `.nvmrc` and `npm ci` for a reproducible install.
-The committed `.npmrc` packages local compatibility dependencies with
-`install-links=true`; it is also copied into both Docker dependency stages.
+Use the Node 24 version in `.nvmrc` and `npm ci --install-links=true` for a reproducible install.
+The explicit install option packages local compatibility dependencies with
+`install-links=true`; both Docker dependency stages pass the same option.
 The minimatch adapter preserves older tooling APIs while delegating matching
 to the maintained engine.
 

deploy/MIGRATION.md

@@ -0,0 +1,39 @@
+# OIDC deployment migration
+
+This change replaces the Auth0 credential broker and SSM-to-shell deployment path with [tc-deploy-scripts v2.0.6](https://github.com/topcoder-platform/tc-deploy-scripts/releases/tag/v2.0.6), fetched by tag and verified against commit `26aaf607463d4a271c0099854c1731214215a9c5`. Build and deployment run in separate jobs. The deployer cannot read Parameter Store, Secrets Manager or decrypt KMS data, including through another assumed role. ECS continues resolving the existing runtime secret references using the execution role.
+
+## Production target
+
+The read-only inventory on 2026-11-03 verified account `409275337247`, cluster `tc-gamification-serverless`, service `tc-gamification`, family `tc-gamification`, and container `tc-gamification`. `prod.json` preserves the observed task/execution roles and names the proposed service-specific deployment role. [prod-baseline.json](https://github.com/topcoder-platform/v6-services-iac/blob/main/services/gamification-api/deploy/prod-baseline.json) records references only; it contains no parameter values. Do not recreate the service or replace its complete task definition from this baseline.
+
+## Installed infrastructure and production cutover
+
+The dev deployment role/boundary, restricted empty CircleCI context, and immutable ECR tags are installed. Existing enhanced scanning is preserved. The production OIDC provider, deployment role/boundary and restricted context are also installed; production runtime and ECR changes remain gated on dev validation. Installation evidence and remaining service-specific steps are private in [PROVISIONING.txt](https://github.com/topcoder-platform/v6-services-iac/blob/main/services/gamification-api/deploy/PROVISIONING.txt). Deploy roles have explicit secret-store and KMS-decryption denies. Runtime values are retrieved only by ECS using the execution role.
+
+At production cutover, stop legacy publishers, enable unconditional tag immutability, adopt missing task health checks with the reviewed image, and use the approval-gated `master` workflow. Preserve capacity, roles, secret references and rollback. Do not run production before dev validation.
+
+## Development acceptance
+
+This PR targets `develop`. Administrator-installed dev prerequisites are recorded in the private IaC repository. The reviewed task health check was submitted only after confirming the existing image serves the identical healthy load-balancer endpoint.
+
+- Dev infrastructure prerequisites are installed; merge to run the application deployment, then validate functionality.
+
+Run the shared offline suite, validate the CircleCI config and IAM policies, and test a dev release plus an unhealthy-image rollback. Verify CloudTrail contains no SSM/Secrets Manager calls from the deployment principal. Remove its old broker grants only after migration. Check the runtime secret references and roles stayed unchanged. Production requires the manual approval job and a passing digest/scan/health verification.
+
+The pinned executor is `cimg/aws@sha256:4cf3768db00ddf9bc439b8c84e8a60c11a14edf81c8baf76f74132144f8340d5`. Python/AWS CLI/Buildx/Git compatibility was tested with the shared offline suite. No package installation or service build runs in the deployment job. The Dockerfile retains the existing in-image quality gates. This PR does not deploy, change IAM, rotate credentials, or claim a successful live rollout.
+
+## Infrastructure source
+
+IAM templates and detailed AWS baselines are maintained in the private [v6-services-iac service directory](https://github.com/topcoder-platform/v6-services-iac/tree/main/services/gamification-api). Provision infrastructure separately with an administrator identity; application CI does not fetch that repository or install IAM. Required application manifests and health-check proposals remain here.
+
+## Dev branch refresh
+
+This PR targets `develop` and preserves its current application/dependency fixes. The shared suite is v2.0.6 (92 offline tests); service-specific adapters and their tests remain part of review. Use the current readiness record above for the remaining merge/deployment gates. Updating these files does not provision AWS or CircleCI resources.
+
+Source checkout uses the public HTTPS repository and verifies the exact CircleCI commit, avoiding dependency on failing SSH checkout keys. No GitHub token is added to build or deployment contexts.
+
+The credential-free builder rejects committed `.npmrc` files. Preserve the existing local compatibility dependencies with explicit `--install-links=true` npm options instead; do not reintroduce credential-capable npm configuration files.
+
+## Reviewed health-check bootstrap
+
+The release wrapper passes the environment-specific health-check JSON to v2.0.6. A missing check is added with the new scanned image; the old image is not restarted with a new probe. An identical existing check is preserved, and a different existing check stops the release. Role, runtime-secret reference, scan, concurrency and healthy-digest checks remain enforced.

deploy/dev-healthcheck.json

@@ -0,0 +1,14 @@
+{
+  "tc-gamification": {
+    "command": [
+      "CMD",
+      "node",
+      "-e",
+      "const r=require('node:http').get(\"http://127.0.0.1:3000/v5/gamification/\",r=>{r.resume();process.exit(r.statusCode>=200&&r.statusCode<300?0:1)});r.setTimeout(4000,()=>{r.destroy();process.exit(1)});r.on('error',()=>process.exit(1))"
+    ],
+    "interval": 30,
+    "timeout": 5,
+    "retries": 3,
+    "startPeriod": 120
+  }
+}

deploy/dev.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 2,
+  "environment": "dev",
+  "accountId": "811668436784",
+  "region": "us-east-1",
+  "deployRoleArn": "arn:aws:iam::811668436784:role/gamification-api-dev-deploy",
+  "taskRoleArn": "arn:aws:iam::811668436784:role/tc-gamification-container-role",
+  "executionRoleArn": "arn:aws:iam::811668436784:role/ecsTaskExecutionRole",
+  "cluster": "tc-gamification-serverless",
+  "service": "tc-gamification",
+  "taskFamily": "tc-gamification",
+  "circleciOrgId": "947bef5e-1669-415d-b83c-4fc85155b7df",
+  "circleciProjectId": "9ddd1952-70f8-49fa-b485-e0a500795ff2",
+  "repository": "github.com/topcoder-platform/gamification-api",
+  "branch": "develop",
+  "images": {
+    "tc-gamification": "tc-gamification"
+  }
+}

deploy/prod-healthcheck.json

@@ -0,0 +1,14 @@
+{
+  "tc-gamification": {
+    "command": [
+      "CMD",
+      "node",
+      "-e",
+      "const r=require('node:http').get('http://127.0.0.1:3000/v5/gamification/',r=>{r.resume();process.exit(r.statusCode>=200&&r.statusCode<300?0:1)});r.setTimeout(4000,()=>{r.destroy();process.exit(1)});r.on('error',()=>process.exit(1))"
+    ],
+    "interval": 30,
+    "timeout": 5,
+    "retries": 3,
+    "startPeriod": 120
+  }
+}

deploy/prod.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 2,
+  "environment": "prod",
+  "accountId": "409275337247",
+  "region": "us-east-1",
+  "deployRoleArn": "arn:aws:iam::409275337247:role/gamification-api-prod-deploy",
+  "taskRoleArn": "arn:aws:iam::409275337247:role/tc-gamification-container-role",
+  "executionRoleArn": "arn:aws:iam::409275337247:role/ecsTaskExecutionRole",
+  "cluster": "tc-gamification-serverless",
+  "service": "tc-gamification",
+  "taskFamily": "tc-gamification",
+  "circleciOrgId": "947bef5e-1669-415d-b83c-4fc85155b7df",
+  "circleciProjectId": "9ddd1952-70f8-49fa-b485-e0a500795ff2",
+  "repository": "github.com/topcoder-platform/gamification-api",
+  "branch": "master",
+  "images": {
+    "tc-gamification": "tc-gamification"
+  }
+}

deploy/release.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+"""Pass the reviewed manifest and this job's prebuilt images to the pinned suite."""
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+manifest = Path(sys.argv[1])
+data = json.loads(manifest.read_text())
+command = [sys.executable, '-I', '/tmp/tc-deploy-scripts/tcdeploy.py', 'deploy', '--manifest', str(manifest),
+           '--bootstrap-health-checks', str(manifest.with_name(data['environment'] + '-healthcheck.json'))]
+for container in data['images']:
+    command.extend(['--image', container + '=gamification-api:candidate'])
+subprocess.run(command, check=True)