Skip to main content

​
🟠 Release v2.475.27

⭐⭐⭐ Complex Integrity & Security • 16 commits • 92 files
This release prioritizes platform security and integrity with critical permission guard fixes, admin route access control hardening, and a significant security fix preventing unauthorized token escalation. Additional improvements include refined theme contrast for accessibility and UI polish.

​
What’s New

  • Permission Guard Restoration: Fixed 17 dead permission checks across admin analytics endpoints (user, achievement, challenge, reward, organization stats) that prevented unauthorized data access
  • Admin Proxy Security Hardening: Blocked direct admin route access through the user app proxy and prevented unauthorized token lending to member sessions
  • Challenge Stats Route Access Control: Added comprehensive authentication and authorization enforcement for challenge statistics endpoints with tenant-scoped action lookups
  • Theme Contrast Improvements: Enhanced challenge option visibility by ensuring primary colors have sufficient contrast against backgrounds, with automatic accent color substitution when needed
  • Game Tutorial Theme Alignment: Tutorial screens now respect the community’s game appearance colors and gracefully skip unresolvable icons
  • UI Polish: Hidden disabled state separators in info modals for cleaner appearance

​
Apps Updated

User App

✓ Updated - Theme contrast, proxy security, tutorial styling

API

✓ Updated - Permission guard restoration, analytics RBAC

Admin

✓ Updated - Challenge stats route access control, UI polish

MCP Server

— No changes

Website

— No changes

Games

✓ Updated - Tutorial appearance theming

​
Detailed Changes

  • Theme Contrast System — Added ensurePrimaryContrastInVars() function that automatically substitutes primary color with accent when contrast against background is insufficient (< 15 lightness difference)
  • Color Control Variables — Generate control-scoped theme variables (--control-surface, --control-foreground, --control-border, etc.) ensuring form controls adapt to community colors
  • Ring Color Resolution — Auto-generate --ring color from primary when not explicitly set, using both primary and accent for better visual feedback
  • Foreground & Popover Fallbacks — Ensure primary/secondary foreground colors and popover surfaces have sensible defaults when not explicitly themed
  • Proxy Security Hardening — Removed automatic forwarding of user access tokens to the API; upload routes now exclusively use org-level API tokens
  • Admin Route Blocking — Blocked all direct admin API routes through the user app proxy, returning HTTP 404 to prevent unauthorized access
  • Community Banner UI — Hidden separator divider when info modal is disabled for cleaner visual hierarchy
  • Tutorial Appearance Binding — Tutorial layout now reads and applies game appearance colors (background, primary, secondary) from the community theme
  • Icon Fallback Handling — Skip unresolvable icon references in tutorial screens instead of breaking the layout
  • Comprehensive Test Coverage — Added 600+ lines of test coverage for theme utilities, color contrast validation, and control variable generation
  • Permission Guard Restoration — Restored 17 dead !ctx.can.read() permission checks across admin analytics endpoints
  • User Analytics Access Control — Added org-level and community-scoped RBAC checks to user analytics endpoints (get-user-activity-timeseries)
  • Organization Analytics Access Control — Added permission validation to org-level stats endpoints (get-org-communities, get-org-stats-overview)
  • Challenge Analytics Access Control — Enforced Challenge read permission on get-challenge-stats-overview
  • Achievement Analytics Access Control — Added permission checks to achievement completion batch and participant list endpoints
  • Community Analytics Access Control — Enforced Community read permission on community stats endpoints
  • Reward Analytics Access Control — Added permission validation to reward allocation and timeline endpoints
  • Community-Scoped User Access — Added community-level RBAC validation to prevent users from reading data across unauthorized communities
  • User Create/Get/Sync Authorization — Implemented community-scoped permission checks on user admin endpoints with detailed error logging
  • Comprehensive Auth Tests — Added 300+ lines of test coverage for permission scenarios and org/community-scoped access validation
  • Challenge Stats Route Access Control — Created require-challenge-route-access.ts helper providing centralized auth and authorization for challenge statistics routes
  • Session Authentication — Required valid admin session for all challenge stats endpoints with detailed 401/403 error responses
  • Organization ID Validation — Enforced organisation ID parameter presence and ObjectId format validation
  • Challenge ID Validation — Added challenge ID presence and format validation with detailed error messages
  • RBAC Permission Enforcement — Super-admin bypass plus role-based Challenge and Action read permission checks
  • Tenant-Scoped Challenge Lookup — Retrieve challenge’s organization location and verify tenant membership to prevent cross-org data access
  • Community-Scoped Action Lookups — Validate action belongs to challenge’s community before exposing allocation data
  • Comprehensive Audit Logging — Detailed log.warn() calls for every auth failure with userId, org, reason, and error context
  • Refactored Stats Routes — Simplified multiple-choice-stats, results, receipt-detections, and image-uploads routes using centralized access helper
  • Consistent Error Handling — Standardized 401/403/404 responses across all challenge stats endpoints
  • Tutorial Theme Integration — Tutorial layout reads and applies community game appearance colors to the interface
  • Color Application — Primary, secondary, and background colors from community theme now style the tutorial container
  • Icon Resolution — Skip unresolvable icon references gracefully instead of failing the entire tutorial
  • Appearance Utility — Created tutorial-appearance.ts helper to extract and normalize game appearance colors from theme
  • Test Coverage — Added 300+ lines of test coverage for tutorial layout color application and icon handling

​
Technical Details

​
Permission Guard Restoration

The API shipped 17 permission checks across admin analytics endpoints that were never executed due to unreachable code paths. This release restores all of them:
  • Scope: get-achievement-completion-batch, get-achievement-participants-list, get-challenge-completion-batch, get-challenge-stats-overview, get-community-stats-overview, get-dashboard-callouts, get-new-members-timeseries, get-wau-timeseries, get-org-communities, get-org-stats-overview, get-allocations-overview, get-reward-recipients, get-reward-timeline, get-user-activity-timeseries, plus user admin endpoints (create-user, get-user-by-id, sync-user-to-external-account)
  • Impact: Prevents unauthorized users from accessing organization and community analytics, user directory, and reward distribution data
  • Enforcement: All checks are RBAC-aware and include community-scoped access validation for endpoints serving multiple-community data

​
Proxy Security Model

The user app proxy (/api/proxy/[...path]) previously allowed:
  1. Direct forwarding of admin routes to the API (security boundary violation)
  2. Automatic token escalation — member sessions would send their access tokens to any proxied route
This release:
  1. Blocks all /api/v2/admin routes — returns HTTP 404 to prevent accidental exposure
  2. Removes automatic token forwarding — only upload routes use the org-level API token; integration routes must supply their own credentials
  3. Maintains backward compatibility — upload functionality unchanged, integration routes unchanged

​
Theme Contrast Algorithm

The new contrast system measures HSL lightness difference between primary and background colors:
  • Formula: |primary_lightness - background_lightness|
  • Threshold: 15% difference minimum
  • Fallback: When contrast is insufficient, the system automatically substitutes primary with accent color
  • Atomic: Both --primary and --primary-foreground swap simultaneously to maintain the theme relationship
  • Safe Mode: Falls back to default accent if the incoming theme lacks either color

​
Challenge Stats Route Access

The new centralized require-challenge-route-access() helper:
  1. Validates session — requires authenticated admin user
  2. Validates parameters — organisation ID and challenge ID must be present and valid ObjectIds
  3. Enforces RBAC — checks Challenge and Action read permissions, allows SuperAdmin bypass
  4. Scopes to tenant — retrieves challenge’s organisation location and prevents cross-org leakage
  5. Scopes to community — validates action allocations belong to the challenge’s community
  6. Logs all failures — detailed audit trail for security investigation

​
Contributors

erek_d@erek_d7 commits • +27,825/-0 lines
dch@dch4 commits • +833/-729 lines
jamescockayne@jamescockayne2 commits • +738/-182 lines
zuhayrk00@zuhayrk001 commit • +835/-1,006 lines
solicshop@solicshop1 commit • +384/-16 lines

​
Release Stats

v2.475.27 deployed on August 12, 2026