feat: modernize private read-only global region API

.dockerignore

@@ -0,0 +1,27 @@
+.git
+.github
+.yarn/*
+!.yarn/releases/
+!.yarn/releases/yarn-4.18.0.cjs
+!.yarn/patches/
+!.yarn/patches/*.patch
+.pnp.*
+node_modules
+dist
+coverage
+reports
+documentation
+.stryker-tmp
+test
+**/._*
+
+.env
+.env.*
+.secrets
+*.pem
+*.key
+*.crt
+
+*.log
+*.tsbuildinfo
+.DS_Store

.env.example

@@ -0,0 +1,9 @@
+NODE_ENV=local
+SERVICE_NAME=api-region
+PORT=3903
+MONGODB_URI=mongodb://localhost:27017
+MONGODB_DATABASE=foundation_central
+JWT_PUBLIC_KEY_PATH=/run/secrets/jwt-public-key.pem
+METRICS_BEARER_TOKEN=replace-with-a-local-only-value
+# Optional loopback listener for a co-located Prometheus collector.
+METRICS_SIDECAR_PORT=9464

.github/workflows/deploy-cloud-run.yml

@@ -0,0 +1,25 @@
+name: Deploy api-region to Cloud Run
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+  packages: read
+
+jobs:
+  deploy:
+    name: Production delivery
+    uses: ioterax/hub-platform/.github/workflows/reusable-microservice-cloud-run-deploy.yml@c6148575457cb8130ea64765c41f432e3bb69ddf # sidecar-safe release workflow
+    with:
+      gcp_project_id: ioterax-prd
+      gcp_region: europe-west1
+      artifact_registry_repository: ioterax-images
+      image_name: api-region
+      cloud_run_service: api-region
+      expected_ingress: internal
+    secrets:
+      GH_NPM_TOKEN: ${{ secrets.GH_NPM_TOKEN }}
+      GCP_WORKLOAD_IDENTITY_PROVIDER: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+      GCP_DEPLOYER_SERVICE_ACCOUNT: ${{ secrets.GCP_DEPLOYER_SERVICE_ACCOUNT }}

.github/workflows/production.yml

@@ -1,31 +1,155 @@
-name: Node.js CIon
+name: Required microservice CI
 
-on: 
+on:
   push:
-    branches: [ master ]
+    branches:
+      - develop
+      - master
   pull_request:
-    branches: [ master ]
+    branches:
+      - develop
+      - master
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
 
 jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18.x]
+  application-quality:
+    name: Build, quality, coverage, and E2E
+    runs-on: ubuntu-24.04
+    timeout-minutes: 35
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 26.6.0
+
+      - name: Restore shared Yarn cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .yarn/cache
+          key: ${{ runner.os }}-node-26.6.0-yarn-4.18.0-api-region-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-node-26.6.0-yarn-4.18.0-api-region-
+            ${{ runner.os }}-node-26.6.0-yarn-4.18.0-
+
+      - name: Resolve environment channel and install PnP dependencies
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GH_NPM_TOKEN || github.token }}
+        shell: bash
+        run: |
+          corepack enable
+          test "$(node --version)" = 'v26.6.0'
+          test "$(yarn --version)" = '4.18.0'
+          if [[ "$GITHUB_REF" == 'refs/heads/master' ]]; then
+            yarn install --immutable --mode=skip-build
+          else
+            IOTERAX_DEPENDENCY_CHANNEL=dev node scripts/docker/prepare-dependency-channel.cjs
+            yarn up -R '@ioterax/*' --mode=update-lockfile
+            yarn install --no-immutable --mode=skip-build
+          fi
+          test -f .pnp.cjs
+          test ! -d node_modules
+
+      - name: Run complete application gate
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GH_NPM_TOKEN || github.token }}
+        run: |
+          yarn quality
+          yarn security:audit
+          yarn test:e2e
 
-    name: 'build app'
+  container-image:
+    name: PnP runtime image and vulnerability scan
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: read
     steps:
-      - name: Checkout project sources
-        uses: actions/checkout@v3
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Build environment-specific image with shared BuildKit cache
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: Dockerfile
+          load: true
+          push: false
+          tags: ioterax/api-region:${{ github.ref == 'refs/heads/master' && 'latest' || 'dev' }}
+          build-args: |
+            IOTERAX_DEPENDENCY_CHANNEL=${{ github.ref == 'refs/heads/master' && 'stable' || 'dev' }}
+          cache-from: type=gha,scope=api-region-production
+          cache-to: type=gha,mode=max,scope=api-region-production
+          secrets: |
+            ioterax_npm_token=${{ secrets.GH_NPM_TOKEN || github.token }}
+
+      - name: Verify exact non-root PnP runtime
+        run: >-
+          docker run --rm --entrypoint=/usr/local/bin/node
+          ioterax/api-region:${{ github.ref == 'refs/heads/master' && 'latest' || 'dev' }}
+          -e "const fs=require('node:fs');
+          const entries=fs.readdirSync('/app',{recursive:true,withFileTypes:true});
+          const invalid=process.version!=='v26.6.0'||process.getuid()!==65532||
+          entries.some(entry=>entry.isDirectory()&&entry.name==='node_modules')||
+          fs.existsSync('/app/.yarn/unplugged');
+          if(invalid)process.exit(1)"
 
-      # See supported Node.js release schedule at https://nodejs.org/en/about/releases/  
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+      - name: Report all image vulnerabilities
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
         with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm i
-      - run: npm run build --if-present
-      - run: npm run lint
-      - run: npm run test:cov
-      - run: npm run test:e2e
+          version: v0.74.0
+          image-ref: ioterax/api-region:${{ github.ref == 'refs/heads/master' && 'latest' || 'dev' }}
+          format: table
+          vuln-type: os,library
+          severity: UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL
+          ignore-unfixed: false
+          exit-code: '0'
+
+      - name: Reject high and critical image vulnerabilities
+        run: >-
+          trivy image --exit-code 1 --ignore-unfixed=false
+          --ignorefile .trivyignore.yaml --show-suppressed
+          --pkg-types os,library --severity CRITICAL,HIGH
+          ioterax/api-region:${{ github.ref == 'refs/heads/master' && 'latest' || 'dev' }}
+
+      - name: Reject fixable medium image vulnerabilities
+        run: >-
+          trivy image --exit-code 1 --ignore-unfixed=true
+          --ignorefile .trivyignore.yaml --show-suppressed
+          --pkg-types os,library --severity MEDIUM
+          ioterax/api-region:${{ github.ref == 'refs/heads/master' && 'latest' || 'dev' }}
+
+  required-gate:
+    name: Required delivery gate
+    if: ${{ always() }}
+    needs:
+      - application-quality
+      - container-image
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions: {}
+    steps:
+      - name: Require every parallel gate to pass
+        env:
+          APPLICATION_RESULT: ${{ needs.application-quality.result }}
+          CONTAINER_RESULT: ${{ needs.container-image.result }}
+        run: |
+          test "$APPLICATION_RESULT" = success
+          test "$CONTAINER_RESULT" = success