Skip to content

PLUGIN_ARCHITECTURE_SUMMARY.md

Latest commit

 

History

History
444 lines (353 loc) · 12.9 KB

PLUGIN_ARCHITECTURE_SUMMARY.md

File metadata and controls

444 lines (353 loc) · 12.9 KB

Xbox Plugin Architecture Summary

Generated: 2026-01-09 Plugin: @allow2/allow2automate-xbox Version: 1.0.0 Status: Initial Structure Created

Executive Summary

The Xbox Live Controls plugin has been architecturally designed and scaffolded following the Allow2 Automate plugin patterns (Steam and PlayStation plugins). This document summarizes the complete file structure, configuration, and integration points.

Directory Structure

/mnt/ai/automate/plugins/allow2automate-xbox/
├── package.json                     # Plugin manifest with allow2automate metadata
├── rollup.config.js                 # Rollup bundler configuration
├── .babelrc                         # Babel transpilation config
├── .gitignore                       # Git ignore rules
├── .eslintrc.js                     # ESLint configuration
├── README.md                        # User-facing documentation
├── ARCHITECTURE.md                  # Technical architecture (31KB)
├── PLUGIN_ARCHITECTURE_SUMMARY.md   # This file
├── LICENSE                          # Apache 2.0 license
│
├── src/                             # Source code
│   ├── index.js                     # Main plugin entry (factory function)
│   │
│   ├── services/                    # Business logic layer
│   │   ├── XboxAuthManager.js       # OAuth2 authentication (3-stage)
│   │   ├── XboxMonitorCoordinator.js # Presence polling (15-second)
│   │   ├── ChildLinkManager.js      # Child-to-gamertag mapping
│   │   └── XboxAPI.js               # Xbox Live API wrapper
│   │
│   ├── components/                  # React UI components
│   │   ├── TabContent.jsx           # Main plugin settings tab
│   │   ├── XboxStatus.jsx           # Real-time status display
│   │   ├── ChildLinkingWizard.jsx   # Child account linking wizard
│   │   ├── ActivityLog.jsx          # Gaming activity history
│   │   └── QuotaDisplay.jsx         # Time remaining display
│   │
│   ├── utils/                       # Utility functions
│   │   ├── tokenStorage.js          # Secure token storage (Electron safeStorage)
│   │   ├── privacy.js               # XUID privacy utilities (XR-013 compliance)
│   │   ├── rateLimiter.js           # API rate limiting (10/15s, 30/5min)
│   │   └── cacheManager.js          # NodeCache wrapper for TTL management
│   │
│   └── constants/                   # Constants
│       ├── xboxEndpoints.js         # Xbox Live API URLs
│       └── errorCodes.js            # Xbox error code mappings
│
├── __tests__/                       # Test files
│   ├── unit/                        # Unit tests (80% coverage target)
│   └── integration/                 # Integration tests
│
├── img/                             # Plugin assets
│   ├── icon.png                     # Plugin icon (256x256)
│   └── logo.svg                     # Xbox logo
│
└── dist/                            # Built files (generated by rollup)
    ├── index.js                     # CommonJS bundle
    └── index.es.js                  # ES module bundle

Configuration Files

package.json

Key Metadata:

{
  "name": "@allow2/allow2automate-xbox",
  "shortName": "xbox",
  "version": "1.0.0",
  "description": "Xbox Live parental control integration for Allow2 Automate",
  "main": "dist/index.js",
  "module": "dist/index.es.js",
  "allow2automate": {
    "plugin": true,
    "pluginId": "allow2automate-xbox",
    "displayName": "Xbox Live Controls",
    "category": "Gaming",
    "permissions": ["network", "configuration", "storage"],
    "minAppVersion": "2.0.0"
  }
}

Dependencies:

  • @babel/runtime - Babel runtime helpers
  • node-fetch - HTTP client for Xbox Live APIs
  • node-cache - In-memory caching (TTL support)

Peer Dependencies (provided by main app):

  • @material-ui/core ^4.0.0
  • @material-ui/icons ^4.0.0
  • react ^16.0.0 || ^17.0.0
  • react-dom ^16.0.0 || ^17.0.0

Build Scripts:

  • npm run build - Build production bundle
  • npm start - Watch mode for development
  • npm test - Run Jest tests
  • npm run lint - ESLint code quality

rollup.config.js

Configuration:

  • Input: src/index.js
  • Output: CommonJS (dist/index.js) + ES Modules (dist/index.es.js)
  • Plugins:
    • rollup-plugin-peer-deps-external - Externalize peer deps
    • rollup-plugin-postcss - CSS processing
    • @rollup/plugin-babel - JSX/ES6+ transpilation
    • @rollup/plugin-node-resolve - Node module resolution
    • @rollup/plugin-commonjs - CommonJS compatibility

Externals: fs, path, os, electron, node-fetch, node-cache

.babelrc

Presets:

  • @babel/preset-env - ES6+ transpilation
  • @babel/preset-react - JSX support

Plugins (40+ Babel plugins for advanced JS features):

  • Class properties
  • Optional chaining
  • Nullish coalescing
  • Decorators (legacy)
  • Pipeline operator
  • And more...

.eslintrc.js

Configuration:

  • Environment: Browser, Node, ES2021, Jest
  • Extends: eslint:recommended, plugin:react/recommended
  • Rules: Console allowed, prop-types warned

Plugin API

Actions (IPC Handlers)

  1. authenticate

    • Description: Connect Microsoft account via OAuth2
    • Handler: xbox:authenticate
    • Returns: Authentication status

  2. linkChild

    • Description: Link Allow2 child to Xbox gamertag
    • Handler: xbox:linkChild
    • Parameters: { childId, gamertag }
    • Returns: { success, xuid, gamertag }

  3. unlinkChild

    • Description: Remove Xbox gamertag link
    • Handler: xbox:unlinkChild
    • Parameters: { childId }

  4. refreshPresence

    • Description: Force refresh Xbox presence data
    • Handler: xbox:refreshPresence

  5. checkQuota

    • Description: Check remaining gaming time quota
    • Handler: xbox:checkQuota
    • Parameters: { childId }

Triggers (Events)

  1. quotaExceeded

    • Fired when: Child exceeds Xbox gaming quota
    • Payload: { childId, timeUsed, quotaLimit }

  2. gameStarted

    • Fired when: Child starts playing a game
    • Payload: { childId, game, timestamp }

  3. gameEnded

    • Fired when: Child stops playing
    • Payload: { childId, game, duration }

  4. sessionViolation

    • Fired when: Gaming detected while blocked
    • Payload: { childId, game, reason }

Integration Points

Main App Integration

Plugin Factory:

// src/index.js
function plugin(context) {
  const xbox = {};

  xbox.onLoad = async function(loadState) {
    // Initialize OAuth, monitoring, IPC handlers
  };

  xbox.newState = function(newState) {
    // Handle configuration updates
  };

  xbox.onSetEnabled = async function(enabled) {
    // Start/stop monitoring
  };

  xbox.onUnload = function(callback) {
    // Cleanup
  };

  return xbox;
}

Context APIs Used:

  • context.ipcMain.handle() - IPC communication
  • context.configurationUpdate() - State persistence
  • context.statusUpdate() - Plugin status
  • context.sendToRenderer() - UI events
  • context.allow2 - Allow2 API integration
  • context.services.agent - Agent communication

Xbox Live API Integration

Authentication Flow:

  1. Microsoft OAuth2 → Access Token
  2. Xbox User Token (XAU) → JWT
  3. XSTS Token → API Authorization

API Endpoints:

  • https://login.live.com/oauth20_* - OAuth
  • https://user.auth.xboxlive.com/user/authenticate - User Token
  • https://xsts.auth.xboxlive.com/xsts/authorize - XSTS Token
  • https://userpresence.xboxlive.com/users/batch - Presence
  • https://profile.xboxlive.com/users/gt(...) - Profile
  • https://titlehub.xboxlive.com/titles/... - Game metadata

Rate Limits:

  • Burst: 10 requests per 15 seconds
  • Sustained: 30 requests per 5 minutes
  • Recommended polling: 15-second intervals

Agent Integration

Hybrid Detection Strategy:

  • Cloud Detection (Primary): Xbox Live Presence API
  • Local Detection (Secondary): Agent process monitoring

Agent Communication:

agentService.createPolicy(agentId, {
  processName: 'XboxApp.exe',
  processAlternatives: ['xboxconsolecompanion.exe', 'gamebarftserver.exe'],
  allowed: false, // Updated based on quota
  checkInterval: 30000,
  actions: {
    onDetected: 'check-quota',
    onViolation: 'kill-process'
  }
});

Privacy & Security

Microsoft XR-013 Compliance

XUID Privacy Safeguards:

  • ✅ XUID stored internally, NEVER exposed in UI
  • ✅ Gamertag displayed to users (public identifier)
  • ✅ Periodic gamertag refresh (handles name changes)
  • ✅ Explicit consent required before linking
  • ✅ Unlink functionality provided

Token Security:

  • Electron safeStorage encryption
    • Windows: DPAPI
    • macOS: Keychain
    • Linux: Secret Service API
  • Automatic token refresh 5 minutes before expiry
  • Secure credential storage in Redux state

Development Workflow

Initial Setup

cd /mnt/ai/automate/plugins/allow2automate-xbox
npm install

Build Commands

# Development watch mode
npm start

# Production build
npm run build

# Run tests
npm test

# Test coverage
npm run test:coverage

# Lint code
npm run lint

Testing Strategy

Unit Tests (Jest):

  • Target: 80%+ coverage
  • Test files: __tests__/unit/*.test.js
  • Focus: Services (Auth, Monitor, API)

Integration Tests:

  • Test files: __tests__/integration/*.test.js
  • Focus: End-to-end flows

Coverage Thresholds:

{
  "branches": 80,
  "functions": 80,
  "lines": 80,
  "statements": 80
}

Installation

In Main App

cd /mnt/ai/automate/automate/dev-data/plugins
npm install @allow2/allow2automate-xbox

Auto-discovery: Plugin discovered via node_modules scan

Environment Variables

# .env in main app root
MICROSOFT_CLIENT_ID=your_azure_client_id
MICROSOFT_CLIENT_SECRET=your_azure_client_secret
XBOX_OAUTH_REDIRECT_URI=http://localhost:8080/oauth/callback

Implementation Roadmap

Phase 1: Core Authentication (Week 1)

  • OAuth2 flow implementation
  • Token chain (OAuth → User Token → XSTS)
  • Secure token storage
  • Automatic token refresh

Phase 2: Child Linking UI (Week 2)

  • Child linking wizard
  • Gamertag validation
  • State management
  • Link/unlink operations

Phase 3: Presence Detection (Week 3)

  • Presence API polling (15s)
  • Batch presence queries
  • Game activity detection
  • Title metadata caching

Phase 4: Allow2 Integration (Week 4)

  • Activity logging to Allow2 API
  • Quota enforcement
  • Violation notifications
  • Dashboard widgets

Phase 5: Agent Integration (Week 5)

  • Agent-side process monitoring
  • Policy creation for Xbox games
  • Hybrid detection (cloud + local)
  • Policy synchronization

Phase 6: Polish & Testing (Week 6)

  • Comprehensive testing
  • Error handling improvements
  • Documentation
  • Privacy compliance audit

Key Technical Decisions

ADR-001: Use 3-Stage OAuth Token Chain

Decision: Implement full Microsoft OAuth → Xbox User Token → XSTS Token chain Rationale: Required by Xbox Live API for parental account access Alternatives: Direct OAuth (rejected - insufficient permissions)

ADR-002: 15-Second Presence Polling

Decision: Poll Xbox Live Presence API every 15 seconds Rationale: Balance between accuracy and rate limits (30 req/5min) Alternatives: 5s (too aggressive), 30s (too slow)

ADR-003: XUID Privacy Compliance

Decision: Never expose XUID in UI, display Gamertag only Rationale: Microsoft XR-013 policy compliance Alternatives: Display XUID (rejected - privacy violation)

ADR-004: Hybrid Cloud + Local Detection

Decision: Combine cloud Presence API with local agent monitoring Rationale: Maximize accuracy, faster PC gaming detection Alternatives: Cloud-only (rejected - slower), Local-only (rejected - console blind)

ADR-005: NodeCache for Metadata

Decision: Use node-cache for in-memory title metadata caching Rationale: Simple TTL management, no external dependencies Alternatives: Redis (overkill), No cache (inefficient)

Next Steps

  1. ✅ Plugin structure created
  2. ✅ Configuration files complete
  3. ✅ Architecture documented
  4. ⏳ Phase 1: Implement XboxAuthManager.js
  5. ⏳ Phase 2: Implement ChildLinkManager.js
  6. ⏳ Phase 3: Implement XboxMonitorCoordinator.js
  7. ⏳ Phase 4: Implement UI components
  8. ⏳ Phase 5: Agent integration
  9. ⏳ Phase 6: Testing and polish

References

  • Implementation Plan: /mnt/ai/automate/automate/docs/plugins/xbox-implementation-plan.md
  • Architecture Design: ./ARCHITECTURE.md
  • Steam Plugin Pattern: /mnt/ai/automate/plugins/allow2automate-steam/
  • PlayStation Plugin Pattern: /mnt/ai/automate/plugins/allow2automate-playstation/

Status: ✅ READY FOR IMPLEMENTATION

All configuration files, build setup, and directory structure are in place. Development can begin with Phase 1 (Core Authentication).