merge main

.editorconfig

@@ -311,7 +311,7 @@ csharp_space_between_empty_square_brackets = false
 csharp_space_between_square_brackets = false
 # Wrap options
 # https://docs.microsoft.com/visualstudio/ide/editorconfig-formatting-conventions#wrap-options
-csharp_preserve_single_line_statements = false
+csharp_preserve_single_line_statements = true
 csharp_preserve_single_line_blocks = false
 
 ##########################################

.env.example

@@ -75,6 +75,50 @@ TELEGRAM_ENABLED=false
 # TELEGRAM_BOT_TOKEN=
 # TELEGRAM_BOT_USERNAME=
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# EXTERNAL SSO / OIDC (optional — delegate login to your own OAuth2/OIDC provider)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Point PoracleWeb at any OAuth2/OIDC provider (Keycloak, Authentik, Auth0, Okta, …) for SSO.
+# The provider's userinfo endpoint must return a claim holding the user's Poracle id
+# (a Discord/Telegram id) — set OIDC_IDENTITY_CLAIM to that claim name.
+# Enabled is auto-inferred when ClientId + the three URLs are all set; set explicitly to override.
+# Replace the example URLs below with your provider's actual endpoints.
+# OIDC_ENABLED=true
+# OIDC_PROVIDER_NAME=My SSO
+# OIDC_AUTHORIZATION_URL=https://sso.example.com/authorize
+# OIDC_TOKEN_URL=https://sso.example.com/oauth/token
+# OIDC_USERINFO_URL=https://sso.example.com/oauth/userinfo
+# OIDC_CLIENT_ID=your_oidc_client_id
+# OIDC_CLIENT_SECRET=your_oidc_client_secret
+# OIDC_SCOPES=openid profile email
+# OIDC_IDENTITY_CLAIM=discord_id
+# OIDC_USERNAME_CLAIM=preferred_username
+# OIDC_AVATAR_CLAIM=picture
+# OIDC_IDENTITY_TYPE=discord:user
+# OIDC_USE_PKCE=true
+#
+# --- Refresh tokens (optional, opt-in) — silent session renewal + revocation propagation ---
+# When OFF (default) the provider's tokens are discarded after login and the internal session
+# JWT lives its full Jwt:ExpirationMinutes (24h); users re-auth at expiry. When ON, PoracleWeb
+# brokers the provider's refresh token SERVER-SIDE (encrypted at rest, never sent to the browser),
+# silently renews the session, and propagates provider-side disable/logout. Requires the provider
+# to actually issue a refresh token. Fully provider-agnostic — see docs/configuration/oidc-refresh-tokens.md.
+# OIDC_USE_REFRESH_TOKENS=true
+# OIDC_ACCESS_TOKEN_MINUTES=30          # internal JWT lifetime for refresh-backed OIDC sessions only
+# OIDC_REFRESH_TOKEN_LIFETIME_DAYS=30   # PoracleWeb-side absolute session cap before a real re-login
+# OIDC_SESSION_REVOKED_RETENTION_DAYS=2 # how long revoked/rotated session rows are kept (replay detection) before cleanup deletes them
+# OIDC_OFFLINE_ACCESS_SCOPE=offline_access  # appended to the authorize scope so the provider issues an RT; empty to disable
+# OIDC_TOKEN_AUTH_METHOD=client_secret_post # client_secret_post (body) | client_secret_basic (HTTP Basic)
+#
+# Per-provider notes (token auth method / offline scope / identity claim):
+#   PogoAlerts : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post  OIDC_IDENTITY_CLAIM=discord_id
+#   Keycloak   : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_basic  OIDC_IDENTITY_CLAIM=sub
+#   Authentik  : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post   OIDC_IDENTITY_CLAIM=sub
+#   Auth0      : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post   OIDC_IDENTITY_CLAIM=sub
+#   Okta       : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_basic  OIDC_IDENTITY_CLAIM=sub
+#   Azure/Entra: OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post   OIDC_IDENTITY_CLAIM=sub
+#   Google     : OIDC_OFFLINE_ACCESS_SCOPE= (empty) and append ?access_type=offline to OIDC_AUTHORIZATION_URL
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # PORACLE API — your running PoracleNG instance
 # ═══════════════════════════════════════════════════════════════════════════════

.github/workflows/auto-merge-deps.yml

@@ -1,29 +1,33 @@
 name: Dependabot auto-merge
 
+# Only triggers on pull_request_target. Listing `push:` here previously caused
+# the workflow to fire on push events instead of pull_request_target ones,
+# so Dependabot PRs never got auto-approved and every push recorded a failure
+# run. pr-labeler.yml uses pull_request_target alone and triggers correctly,
+# which was the side-by-side that confirmed the issue.
 on:
   pull_request_target:
     types: [opened, synchronize, reopened, ready_for_review]
-  # Claim push events so GitHub doesn't create phantom 0-job failed runs.
-  # The job early-exits for non-pull_request_target events.
-  push:
 
 permissions:
   contents: write
   pull-requests: write
 
 jobs:
   auto-merge:
-    # Skip the job entirely on push events so GitHub records the run as "skipped"
-    # (neutral, green in status UI) instead of "failure" with 0 jobs. The prior
-    # approach of claiming push with in-step gates still produced failed runs
-    # because the job itself never spawned for non-dependabot pushes.
-    if: github.event_name == 'pull_request_target' && github.actor == 'dependabot[bot]'
     runs-on: ubuntu-latest
     steps:
+      # Sentinel step so the run records as "success" for non-Dependabot PRs.
+      # Without it, every step below is gated by `github.actor == 'dependabot[bot]'`
+      # and a non-Dependabot PR would produce a job with zero successful steps,
+      # which GitHub records as failure.
+      - name: Workflow ran
+        run: echo "Auto-merge workflow evaluated for actor=${{ github.actor }}"
+
       - name: Fetch Dependabot metadata
         id: meta
         if: github.actor == 'dependabot[bot]'
-        uses: dependabot/fetch-metadata@v2
+        uses: dependabot/fetch-metadata@v3
 
       - name: Enable auto-merge for low-risk bumps
         # Auto-merge criteria:
@@ -49,7 +53,7 @@ jobs:
             steps.meta.outputs.update-type == 'version-update:semver-patch' ||
             steps.meta.outputs.dependency-group != ''
           )
-        run: gh pr review --approve "$PR_URL" --body "Auto-approved: low-risk bump, gated on CI."
+        run: gh pr review --approve "$PR_URL" --body 'Auto-approved low-risk bump, gated on CI.'
         env:
           PR_URL: ${{ github.event.pull_request.html_url }}
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/changelog.yml

@@ -1,150 +1,72 @@
-name: Update Changelog
+name: Changelog Check
+
+# Verify-only: confirms a PR adds an entry under "## [Unreleased]" in CHANGELOG.md.
+# It never writes to the repo, so it cannot trip branch protection on `main`.
+# Replaces the old post-merge auto-writer, which always failed pushing to protected main
+# and risked duplicate entries. Release cuts are still handled by release-changelog.yml.
 
 on:
   pull_request:
-    types: [closed]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
-  update-changelog:
-    if: github.event.pull_request.merged == true
+  changelog:
+    name: Changelog entry present
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
     steps:
       - name: Checkout
         uses: actions/checkout@v6
         with:
-          ref: main
           fetch-depth: 0
 
-      - name: Categorize PR
-        id: categorize
+      - name: Require a CHANGELOG entry under [Unreleased]
+        env:
+          # Passed via env (not inlined) to avoid shell injection from PR titles/labels.
+          TITLE: ${{ github.event.pull_request.title }}
+          LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
         run: |
-          TITLE="${{ github.event.pull_request.title }}"
-          PR_NUM="${{ github.event.pull_request.number }}"
-          PR_URL="${{ github.event.pull_request.html_url }}"
+          set -euo pipefail
 
-          # Extract category from conventional commit prefix
-          if echo "$TITLE" | grep -qiE '^feat(\(.*\))?[!]?:'; then
-            CATEGORY="Added"
-          elif echo "$TITLE" | grep -qiE '^fix(\(.*\))?[!]?:'; then
-            CATEGORY="Fixed"
-          elif echo "$TITLE" | grep -qiE '^refactor(\(.*\))?[!]?:'; then
-            CATEGORY="Changed"
-          elif echo "$TITLE" | grep -qiE '^perf(\(.*\))?[!]?:'; then
-            CATEGORY="Changed"
-          elif echo "$TITLE" | grep -qiE '^breaking(\(.*\))?[!]?:'; then
-            CATEGORY="Changed"
-          elif echo "$TITLE" | grep -qiE '^deprecate(\(.*\))?[!]?:'; then
-            CATEGORY="Deprecated"
-          elif echo "$TITLE" | grep -qiE '^remove(\(.*\))?[!]?:'; then
-            CATEGORY="Removed"
-          elif echo "$TITLE" | grep -qiE '^security(\(.*\))?[!]?:'; then
-            CATEGORY="Security"
-          elif echo "$TITLE" | grep -qiE '^docs(\(.*\))?[!]?:'; then
-            echo "skip=true" >> "$GITHUB_OUTPUT"
+          # 1) Exempt non-user-facing PR types (mirrors the previous skip set).
+          if printf '%s' "$TITLE" | grep -qiE '^(docs|style|chore|ci|test|build)(\(.*\))?[!]?:'; then
+            echo "Exempt PR type — skipping changelog check."
+            echo "  title: $TITLE"
             exit 0
-          elif echo "$TITLE" | grep -qiE '^(style|chore|ci|test)(\(.*\))?[!]?:'; then
-            echo "skip=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          else
-            CATEGORY="Changed"
           fi
 
-          # Strip prefix from title for the entry text
-          ENTRY=$(echo "$TITLE" | sed -E 's/^[a-zA-Z]+(\(.*\))?[!]?:\s*//')
-
-          echo "category=$CATEGORY" >> "$GITHUB_OUTPUT"
-          echo "entry=$ENTRY" >> "$GITHUB_OUTPUT"
-          echo "pr_num=$PR_NUM" >> "$GITHUB_OUTPUT"
-          echo "pr_url=$PR_URL" >> "$GITHUB_OUTPUT"
-          echo "skip=false" >> "$GITHUB_OUTPUT"
-
-      - name: Update CHANGELOG.md
-        if: steps.categorize.outputs.skip != 'true'
-        run: |
-          CATEGORY="${{ steps.categorize.outputs.category }}"
-          ENTRY="${{ steps.categorize.outputs.entry }}"
-          PR_NUM="${{ steps.categorize.outputs.pr_num }}"
-          PR_URL="${{ steps.categorize.outputs.pr_url }}"
-
-          # Skip if this PR is already referenced in the [Unreleased] section
-          # (e.g., changelog was updated manually in the PR branch)
-          UNRELEASED_BLOCK=$(awk '/^## \[Unreleased\]/,/^## \[[0-9]/' CHANGELOG.md 2>/dev/null)
-          if echo "$UNRELEASED_BLOCK" | grep -qF "#$PR_NUM"; then
-            echo "PR #$PR_NUM already referenced in [Unreleased] — skipping auto-insert"
+          # 2) Manual escape hatch for legitimate exceptions.
+          if printf ',%s,' "$LABELS" | grep -q ',skip-changelog,'; then
+            echo "skip-changelog label present — skipping changelog check."
             exit 0
           fi
 
-          # Check if CHANGELOG.md exists
-          if [ ! -f CHANGELOG.md ]; then
-            cat > CHANGELOG.md << 'INIT'
-          # Changelog
-
-          All notable changes to this project are documented in this file.
-
-          The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+          # 3) Extract the [Unreleased] block from both sides of the PR.
+          unreleased() {
+            git show "$1:CHANGELOG.md" 2>/dev/null \
+              | awk '/^## \[Unreleased\]/{f=1; next} f && /^## \[/{f=0} f'
+          }
+          base_block="$(unreleased "$BASE_SHA" || true)"
+          head_block="$(unreleased "$HEAD_SHA" || true)"
 
-          ## [Unreleased]
-          INIT
-          fi
+          # 4) Top-level entries this PR newly adds under [Unreleased].
+          new_entries="$(comm -13 \
+            <(printf '%s\n' "$base_block" | grep -E '^- ' | sort -u) \
+            <(printf '%s\n' "$head_block" | grep -E '^- ' | sort -u) || true)"
 
-          # Use awk to insert entry under [Unreleased] only (not older release sections)
-          # Pass values via environment to avoid awk -v escaping issues with special characters
-          export AWK_CATEGORY="### $CATEGORY"
-          export AWK_ENTRY="- $ENTRY ([PR #$PR_NUM]($PR_URL))"
-          awk '
-          BEGIN { category=ENVIRON["AWK_CATEGORY"]; entry=ENVIRON["AWK_ENTRY"]; found_unreleased=0; inserted=0 }
-          /^## \[Unreleased\]/ { found_unreleased=1; print; next }
-          # If we hit the next version section, unreleased block is over
-          found_unreleased && /^## \[/ {
-            if (!inserted) {
-              print ""
-              print category
-              print entry
-              inserted=1
-            }
-            found_unreleased=0
-            print; next
-          }
-          # Found existing category header under [Unreleased]
-          found_unreleased && !inserted && $0 == category {
-            print
-            print entry
-            inserted=1
-            next
-          }
-          # Hit a different category or blank line before any matching category — insert new section before it
-          found_unreleased && !inserted && /^### / {
-            print category
-            print entry
-            print ""
-            inserted=1
-            print; next
-          }
-          { print }
-          END {
-            if (!inserted) {
-              print ""
-              print category
-              print entry
-            }
-          }
-          ' CHANGELOG.md > CHANGELOG.tmp
-          if [ -s CHANGELOG.tmp ]; then
-            mv CHANGELOG.tmp CHANGELOG.md
-          else
-            echo "::error::awk produced empty output — CHANGELOG.md not modified"
-            rm -f CHANGELOG.tmp
-            exit 1
+          if [ -n "$new_entries" ]; then
+            echo "Found new [Unreleased] entry/entries:"
+            printf '%s\n' "$new_entries"
+            exit 0
           fi
 
-      - name: Commit and push
-        if: steps.categorize.outputs.skip != 'true'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add CHANGELOG.md
-          git diff --cached --quiet || (git commit -m "docs: update changelog for PR #${{ github.event.pull_request.number }}" && git push)
+          echo "::error::This PR has no new entry under '## [Unreleased]' in CHANGELOG.md."
+          echo "Add a Keep a Changelog entry (e.g. under '### Fixed'), or:"
+          echo "  - use a 'docs|style|chore|ci|test|build:' PR title for non-user-facing changes, or"
+          echo "  - apply the 'skip-changelog' label for a legitimate exception."
+          exit 1

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
           dotnet-version: '10.0.x'
 
       - name: Cache NuGet packages
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.nuget/packages
           key: nuget-${{ runner.os }}-${{ hashFiles('**/*.csproj', '**/*.slnx') }}
@@ -39,7 +39,7 @@ jobs:
 
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: backend-test-results
           path: '**/TestResults/*.trx'
@@ -57,12 +57,19 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Setup Node.js 22
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: '22'
           cache: 'npm'
           cache-dependency-path: Applications/Pgan.PoracleWebNet.App/ClientApp/package-lock.json
 
+      # Node 22 ships npm 10.9.7, whose `npm ci` rejects lockfiles that omit nested
+      # optional-peer entries (chokidar@4 / readdirp@4 under @angular-devkit/*) that
+      # newer npm versions prune. Pinning npm 11 here matches what Dependabot uses
+      # to regenerate lockfiles, so `npm ci` stays in sync with that resolution.
+      - name: Pin npm 11
+        run: npm install -g npm@11
+
       - name: Install dependencies
         run: npm ci
 

.github/workflows/docker-preview.yml

@@ -46,7 +46,7 @@ jobs:
 
       - name: Build and push
         id: build
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
         with:
           context: .
           push: true
@@ -56,7 +56,7 @@ jobs:
           cache-to: type=gha,mode=max
 
       - name: Comment preview instructions on PR
-        uses: marocchino/sticky-pull-request-comment@v2
+        uses: marocchino/sticky-pull-request-comment@v3
         with:
           header: preview-image
           message: |

.github/workflows/docker-prune.yml

@@ -18,7 +18,7 @@ jobs:
       pull-requests: read
     steps:
       - name: Delete pr-* tags for closed PRs
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         env:
           ORG: ${{ env.ORG }}
           PACKAGE: ${{ env.PACKAGE }}

.github/workflows/docker-publish.yml

@@ -46,7 +46,7 @@ jobs:
             type=sha,prefix=,enable=${{ github.event_name == 'release' }}
 
       - name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
         with:
           context: .
           push: true