merge main

.claude/commands/regression-lens.md

@@ -0,0 +1,80 @@
+---
+description: Audit recent merges for defects the fixes themselves introduced
+argument-hint: "[commit-ish or PR range, e.g. 4bf0230 or 'last 20 hours']"
+---
+
+Run a **regression lens** over this repository.
+
+This is not a bug hunt. It audits **the fixes themselves**, asking only what they broke and which
+siblings they missed. It exists because roughly one in five defects found in this codebase's audit
+sweeps was caused by an earlier fix in the same campaign, and nothing else looks for those.
+
+## Scope
+
+Audit: **$ARGUMENTS**
+
+If that is empty, audit everything merged to `develop` in the last 24 hours (`git log --oneline
+--since="24 hours ago"`). Read each diff in full with `git show <sha>`, then read the **current** state
+of every file touched — a later commit may already have changed it.
+
+Keep the scope tight. One pass over one batch of fixes finds more than one pass over everything.
+
+## The only two questions
+
+1. **What did this fix break?** Did it tighten or loosen a rule — validation, guard, allowlist, filter,
+   cache, default, lifetime, error path, order of operations — without accounting for a legitimate case
+   that depended on the previous behaviour?
+2. **Which siblings did it miss?** This codebase has sets of ten (alarm types, list components, edit
+   dialogs, services, `*Create`/`*Update` DTO pairs) and eleven (locale files). A fix applied to one
+   member is suspect until the others are checked.
+
+## Calibration — the shapes this keeps finding
+
+Give the auditor these, so it knows what it is looking for:
+
+- **A constraint added, the bad case verified refused, the legitimate cases never enumerated.** A live
+  resolution locked out users configured elsewhere (#601 → #626). Save-time validation broke seeding,
+  because two presets carry empty filters on purpose (#604 → #637). An allowlist would have refused
+  `blanche` and `npc 0`, both live in production.
+- **A claim wider than its evidence.** `isAdmin` made live without distinguishing "not an admin" from
+  "could not ask", so an outage de-admined live sessions (#624 → #656). A comment asserting one key was
+  the only type-agnostic one, when the repo's own whitelist listed four (#671 → #674).
+- **Validation in the wrong place.** Checks added *after* the thing they guard is created, so a refusal
+  answers 400 and leaves an orphan behind (#647 → #665).
+- **One member of a set of ten.** `bulkDelete` hardened, `bulkUpdateDistance` left (#603 → #641). Create
+  DTO bounded, Update DTO not (#612 → #660).
+
+## Ground rules for the auditor
+
+- Verify against the code. `git show` the diff, then read the current file. Never reason from a commit
+  message.
+- Check any PoracleNG claim against `E:/PGAN/pogogit/PoracleNG`, pinned to the commit production runs —
+  see the "Keep the PoracleNG Checkout Pinned To What Prod Runs" section of `CLAUDE.md`.
+- Read "Fixing Defects Without Causing Them" in `CLAUDE.md` first.
+- Before claiming a value should be refused, query production for what currently satisfies the loose
+  rule. Connection details are in `.env`.
+- Do **not** report defects in code the audited commits did not touch. That is a different lens's job.
+- Do **not** re-report findings from earlier passes.
+- **A clean result is the expected and desired outcome.** Say so plainly and stop. Manufacturing a
+  marginal finding to appear thorough costs real work, because every finding gets acted on.
+
+Report each finding with the commit that introduced it, the legitimate case now broken (or the sibling
+now missed), a demonstrable failure case, and what should happen instead. Then list what was checked
+and cleared.
+
+## Run it until it comes back empty
+
+One pass is not enough — its own fixes can introduce the next round. Re-run, scoping each pass to the
+previous pass's fixes, until a pass reports nothing.
+
+Observed convergence when this was first run: **8 → 5 → 2 → 1 → 0**. Pass one held a severe defect (an
+outage de-admining a live session); pass two another (an orphan profile left behind a 400); by pass four
+the only finding was an overclaiming comment. Expect roughly that shape. Stopping at pass one would have
+left five defects live.
+
+## Fixing what it finds
+
+Follow `CLAUDE.md`. In particular: give every guard a **legitimate-case-still-passes** test beside the
+refusal test, and **revert the fix and confirm the new test goes red** before trusting it. A test written
+alongside a fix encodes that fix's own assumptions and passes either way — one spec in this repo was
+asserting a broken request shape, so the suite was defending the bug.

.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

@@ -68,13 +68,62 @@ DISCORD_BOT_TOKEN=your_discord_bot_token
 # Forum channel for geofence submission threads (optional)
 # DISCORD_GEOFENCE_FORUM_CHANNEL_ID=
 
+# Public URL where users reach this site, no trailing slash (optional).
+# Used to link geofence review threads straight to the admin review page.
+# The link is omitted when this is unset.
+# PUBLIC_URL=https://alerts.example.com
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # TELEGRAM (optional)
 # ═══════════════════════════════════════════════════════════════════════════════
 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
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -101,6 +150,37 @@ KOJI_PROJECT_NAME=YourProjectName
 # Set to the URL you access PoracleWeb.NET from. Not required in development mode.
 # CORS_ORIGIN=http://192.168.1.50:8082
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# PUBLIC URL — the address users reach this instance on
+# ═══════════════════════════════════════════════════════════════════════════════
+# Sets the OAuth callback URLs (Discord and OIDC) outright instead of guessing them
+# from each incoming request. Set this if sign-in fails with an invalid redirect_uri,
+# or just set it anyway — it is the one value your identity provider must also have
+# registered, so stating it here keeps the two in step.
+#
+# Origin only: no trailing path, no query. A bad value stops the app at startup.
+# Leave it blank to keep the old behaviour of following the incoming request, which
+# is correct for a direct-exposed instance or one whose proxy is declared below.
+# PUBLIC_URL=https://poracle.example.com
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# REVERSE PROXY — required if anything sits in front of PoracleWeb.NET
+# ═══════════════════════════════════════════════════════════════════════════════
+# Nginx, Caddy, Traefik, Cloudflare Tunnel and friends terminate TLS themselves and
+# announce the original request with X-Forwarded-For and X-Forwarded-Proto. Those
+# headers are only believed from addresses named here — a forgeable header would let
+# any caller hand itself a fresh rate-limit allowance on the sign-in endpoints.
+#
+# Leave both blank only if the app is exposed directly. Behind an undeclared proxy the
+# app sees every request as plain HTTP from the proxy's address, which means all users
+# share one rate-limit bucket AND OAuth callback URLs are built as http:// — Discord
+# and OIDC providers then reject the sign-in with "Invalid redirect_uri". (PUBLIC_URL
+# above fixes the sign-in on its own; only these settings fix the rate-limit bucket.)
+#
+# Comma-separated. Use the address the proxy connects FROM, as the container sees it.
+# PROXY_KNOWN_PROXIES=10.0.3.20
+# PROXY_KNOWN_NETWORKS=172.18.0.0/16,10.0.0.0/8
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # PORACLE CONFIG (optional — for DTS template previews)
 # ═══════════════════════════════════════════════════════════════════════════════

.github/dependabot.yml

@@ -3,6 +3,9 @@ updates:
   # .NET (backend)
   - package-ecosystem: nuget
     directory: /
+    # main only moves when a release is merged (see CLAUDE.md), so bumps land on
+    # develop first and reach released code with the release that carries them.
+    target-branch: develop
     schedule:
       interval: weekly
       day: monday
@@ -13,19 +16,46 @@ updates:
       - dependencies
     commit-message:
       prefix: deps
+    ignore:
+      # Microsoft.OpenApi 3.x cannot be used while Microsoft.AspNetCore.OpenApi targets the 2.x
+      # object model. Its source generator assigns IOpenApiMediaType.Example, which became
+      # read-only in 3.0, so the build fails in generated code no edit here can reach:
+      #   OpenApiXmlCommentSupport.generated.cs: error CS0200: Property or indexer
+      #   IOpenApiMediaType.Example cannot be assigned to -- it is read only
+      #
+      # The direct reference exists only to clear GHSA-v5pm-xwqc-g5wc, which
+      # Microsoft.AspNetCore.OpenApi 10.0.10 reintroduces by pinning 2.0.0 transitively (see the
+      # comment in Pgan.PoracleWebNet.Api.csproj). Minor and patch updates inside 2.x still come
+      # through, so a later advisory is not masked.
+      #
+      # Drop this once Microsoft.AspNetCore.OpenApi ships a release built against 3.x -- at which
+      # point the direct reference should go too. See #702.
+      - dependency-name: Microsoft.OpenApi
+        update-types:
+          - version-update:semver-major
     groups:
-      microsoft:
+      # One group for the whole .NET platform. These packages ship as a single versioned set:
+      # Microsoft.EntityFrameworkCore 10.0.x transitively requires Microsoft.Extensions.* at
+      # >= the same 10.0.x, so any grouping that splits them produces a PR that cannot restore.
+      #
+      # The previous `microsoft` / `aspnetcore` / `ef-core` split did exactly that, and the
+      # patterns overlapped besides -- `Microsoft.*` is a superset of both `Microsoft.AspNetCore.*`
+      # and `Microsoft.EntityFrameworkCore*`. It yielded three PRs carving up one package set,
+      # of which only the widest could build. See #366: EF Core went to 10.0.10 while
+      # Microsoft.Extensions.* stayed at 10.0.8, giving `NU1605: Detected package downgrade`
+      # (a hard error under the .NET 10 SDK, not a warning).
+      #
+      # MySql.EntityFrameworkCore belongs here too: it version-locks to
+      # Microsoft.EntityFrameworkCore.Relational and drags the same Extensions floor with it.
+      dotnet:
         patterns:
           - 'Microsoft.*'
           - 'System.*'
-      aspnetcore:
-        patterns:
-          - 'Microsoft.AspNetCore.*'
-          - 'Microsoft.Extensions.*'
-      ef-core:
-        patterns:
-          - 'Microsoft.EntityFrameworkCore*'
           - 'MySql.EntityFrameworkCore'
+        exclude-patterns:
+          # Test-only and versioned independently of the platform (18.x, not 10.0.x).
+          # Kept in the `test` group so a runtime bump and a test-tooling bump stay separable.
+          - 'Microsoft.NET.Test.Sdk'
       test:
         patterns:
           - 'xunit*'
@@ -36,6 +66,9 @@ updates:
   # Angular frontend
   - package-ecosystem: npm
     directory: /Applications/Pgan.PoracleWebNet.App/ClientApp
+    # main only moves when a release is merged (see CLAUDE.md), so bumps land on
+    # develop first and reach released code with the release that carries them.
+    target-branch: develop
     schedule:
       interval: weekly
       day: monday
@@ -91,6 +124,9 @@ updates:
   # GitHub Actions
   - package-ecosystem: github-actions
     directory: /
+    # main only moves when a release is merged (see CLAUDE.md), so bumps land on
+    # develop first and reach released code with the release that carries them.
+    target-branch: develop
     schedule:
       interval: weekly
       day: monday
@@ -106,6 +142,9 @@ updates:
   # Dockerfile base images
   - package-ecosystem: docker
     directory: /
+    # main only moves when a release is merged (see CLAUDE.md), so bumps land on
+    # develop first and reach released code with the release that carries them.
+    target-branch: develop
     schedule:
       interval: weekly
       day: monday