> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Release v2.475.27

> Released August 12, 2026

## 🟠 Release v2.475.27

⭐⭐⭐ Complex Integrity & Security • 16 commits • 92 files

<Note>
  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.
</Note>

## 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

<CardGroup cols={3}>
  <Card title="User App" icon="mobile">
    ✓ Updated - Theme contrast, proxy security, tutorial styling
  </Card>

  <Card title="API" icon="server">
    ✓ Updated - Permission guard restoration, analytics RBAC
  </Card>

  <Card title="Admin" icon="gear">
    ✓ Updated - Challenge stats route access control, UI polish
  </Card>

  <Card title="MCP Server" icon="robot">
    — No changes
  </Card>

  <Card title="Website" icon="globe">
    — No changes
  </Card>

  <Card title="Games" icon="gamepad">
    ✓ Updated - Tutorial appearance theming
  </Card>
</CardGroup>

## Detailed Changes

<AccordionGroup>
  <Accordion title="User App" icon="mobile">
    * **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
  </Accordion>

  <Accordion title="API" icon="server">
    * **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
  </Accordion>

  <Accordion title="Admin" icon="gear">
    * **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
  </Accordion>

  <Accordion title="Games" icon="gamepad">
    * **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
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={4}>
  <Card>
    <img src="https://github.com/erek_d@me.com.png" alt="erek_d" style={{borderRadius: '50%', width: 48}} />

    **@erek\_d**

    7 commits • +27,825/-0 lines
  </Card>

  <Card>
    <img src="https://github.com/dch@wenudj.com.png" alt="dch" style={{borderRadius: '50%', width: 48}} />

    **@dch**

    4 commits • +833/-729 lines
  </Card>

  <Card>
    <img src="https://github.com/jamescockayne.png" alt="jamescockayne" style={{borderRadius: '50%', width: 48}} />

    **@jamescockayne**

    2 commits • +738/-182 lines
  </Card>

  <Card>
    <img src="https://github.com/zuhayrk00@gmail.com.png" alt="zuhayrk00" style={{borderRadius: '50%', width: 48}} />

    **@zuhayrk00**

    1 commit • +835/-1,006 lines
  </Card>

  <Card>
    <img src="https://github.com/solicshop@gmail.com.png" alt="solicshop" style={{borderRadius: '50%', width: 48}} />

    **@solicshop**

    1 commit • +384/-16 lines
  </Card>
</CardGroup>

## Release Stats

| Metric        | Value   |
| ------------- | ------- |
| Total Commits | 16      |
| Lines Added   | +30,731 |
| Lines Removed | -1,934  |
| Files Changed | 92      |
| Size          | Large   |
| Complexity    | ⭐⭐⭐     |

***

*v2.475.27 deployed on August 12, 2026*