AeThex-OS/docs/MODE_SYSTEM_COMPLETE.md

Production-Safe Mode System - Implementation Complete

✅ What Was Built

1. Realm vs Mode Separation

• Realm = Authority + Policy Boundary (enforced server-side)
• Mode = Presentation + App Surface (user preference)

2. Single Source of Truth: App Registry

File: shared/app-registry.ts

• Canonical app dictionary (appsById) - no duplication
• Mode manifests - select app subsets per mode
• Capability system - 9 capabilities (credential_verification, commerce, social, etc.)
• Policy metadata per app:
  • requiresRealm: "foundation" | "corporation" | "either"
  • requiresCapabilities: array of required capabilities
  • navVisibleIn: which modes show this app
  • routes: all routes for route guarding

3. Database Schema

New tables in migrations/0003_mode_system.sql:

aethex_user_mode_preference
  - user_id (unique)
  - mode ("foundation" | "corporation")
  - created_at, updated_at

aethex_workspace_policy
  - workspace_id (unique)
  - enforced_realm (if set, users cannot switch)
  - allowed_modes (json array)
  - commerce_enabled, social_enabled, messaging_enabled
  - created_at, updated_at

4. Client-Side Protection

Route Guard (client/src/hooks/use-route-guard.ts)

• Monitors location changes
• Checks canAccessRoute(path, realm, mode)
• Redirects with toast notification if access denied
• Prevents manual URL navigation to restricted apps

Mode Hook (client/src/hooks/use-mode.ts)

• Fetches user mode preference from API
• Fetches workspace policy
• Respects enforced_realm (disables mode switching)
• Updates mode preference via API

5. Server-Side Protection

Capability Guard Middleware (server/capability-guard.ts)

• Maps endpoints to required capabilities
• Checks x-user-realm header
• Enforces realm requirements
• Enforces capability requirements
• Returns 403 with detailed error if access denied

Protected Endpoints:

/api/hub/messaging        → corporation, ["social", "messaging"]
/api/hub/marketplace      → corporation, ["commerce", "marketplace"]
/api/hub/projects         → corporation, ["social"]
/api/hub/analytics        → corporation, ["analytics"]
/api/hub/file-manager     → corporation, ["file_storage"]
/api/os/entitlements/*    → ["credential_verification"]
/api/os/link/*            → ["identity_linking"]

Mode API Endpoints (server/routes.ts)

GET  /api/user/mode-preference  → Get user mode
PUT  /api/user/mode-preference  → Update user mode
GET  /api/workspace/policy      → Get workspace policy

6. App Distribution

Foundation Mode (7 apps)

• Achievements (credential verification)
• Passport (identity profile)
• Curriculum (learning paths)
• Events (programs and cohorts)
• Lab (development environment)
• Network (directory of verified builders)
• OS Link (identity linking)

Corporation Mode (15 apps)

• All Foundation apps +
• Messaging (direct messaging)
• Marketplace (access to courses, tools, services)
• Projects (portfolio showcase)
• Code Gallery (code sharing)
• Notifications (activity feed)
• Analytics (engagement metrics)
• File Manager (cloud storage)
• Settings (preferences)

7. Key Design Decisions

✅ Network App Clarified

• Foundation: Directory of issuers/program cohorts + verified builders
• No DMs, no public feeds, no monetization hooks
• Remains in Foundation mode as a directory-only feature

✅ Marketplace Reworded

• Changed from "Buy and sell credentials" (dangerous)
• To "Access courses, tools, and services" (safe)
• Credentials are earned/issued, not purchased
• What's sold: course seats, audits, software licenses, service engagements

✅ OS Kernel Clearly Separated

• Scope badge: "Kernel"
• Accessible from both modes
• Visually distinct (cyan accent)
• Infrastructure layer, not a third mode

---

🔒 Security Model

Multi-Layer Defense

1. Client Route Guard → Prevents UI navigation
2. App Visibility Filter → Hides unavailable apps
3. Server Capability Guard → Blocks API calls
4. Workspace Policy → Organizational enforcement

Enforcement Chain

User → Client checks mode → Server checks realm → Database checks capability → Action allowed/denied

---

📊 Mode Comparison

Feature	Foundation	Corporation
Apps	7 core + OS	7 core + 8 Hub + OS
Focus	Credentials	Community + Commerce
Messaging	❌	✅
Marketplace	❌	✅
Projects	❌	✅
File Storage	❌	✅
Analytics	❌	✅
Color	Cyan/Blue	Purple/Pink
Label	"AeThex Foundation"	"AeThex Hub"

---

🚀 What's Enforced

✅ Route Access - Manual URL navigation blocked
✅ API Access - Hub endpoints check realm + capabilities
✅ App Visibility - Only allowed apps shown in UI
✅ Workspace Policy - Organizations can lock users into Foundation
✅ Capability Mapping - Every Hub feature requires explicit capabilities

---

🔄 Migration Status

✅ 0001_new_apps_expansion.sql  (10 Hub tables)
✅ 0002_os_kernel.sql            (7 OS kernel tables)
✅ 0003_mode_system.sql          (2 mode governance tables)

Total: 19 tables deployed

---

🧪 Testing

Start dev server:

npm run dev

Visit http://localhost:5000 and:

1. Toggle between Foundation/Corporation modes
2. Try accessing Hub apps in Foundation mode (should be blocked)
3. Check browser console for access denied messages
4. Try direct URL navigation to /hub/messaging in Foundation mode

---

📝 Result

Mode is now enforceable governance, not cosmetic theming.

Foundation becomes a credentialing/education console that feels institutional. Corporation becomes a full platform with commerce + community. OS Kernel remains shared infrastructure accessible to both.

The distinction is now enforceable at every layer: UI visibility, client routing, server API access, and workspace policy.