Xbox Live Controls Plugin for Allow2 Automate

Xbox Live parental control integration for Allow2 Automate. Monitor gaming activity across Xbox consoles, PCs, and cloud gaming platforms.

Features

• OAuth2 Authentication: Secure 3-stage Xbox Live authentication flow
• Presence Detection: 15-second polling accuracy for real-time game activity monitoring
• Child Linking: Map Allow2 children to Xbox gamertags with privacy compliance
• Quota Enforcement: Automatic time tracking and quota management
• Hybrid Detection: Cloud + local agent detection for PC gaming
• Microsoft XR-013 Compliant: XUID privacy safeguards implemented

Installation

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

Configuration

Azure AD Application Setup

1. Register app at https://portal.azure.com
2. Configure redirect URI: http://localhost:8080/oauth/callback
3. Note Client ID and generate Client Secret
4. Add required scopes: Xboxlive.signin, Xboxlive.offline_access

Environment Variables

Create .env in the main Allow2 Automate directory:

MICROSOFT_CLIENT_ID=your_azure_client_id
MICROSOFT_CLIENT_SECRET=your_azure_client_secret
XBOX_OAUTH_REDIRECT_URI=http://localhost:8080/oauth/callback

Usage

1. Navigate to Plugins → Xbox Live Controls
2. Click "Connect Xbox Account" to authenticate
3. Link children to their Xbox gamertags
4. Plugin will automatically monitor gaming activity

Development

# Install dependencies
npm install

# Build plugin
npm run build

# Watch mode for development
npm start

# Run tests
npm test

# Run tests with coverage
npm test:coverage

# Lint code
npm run lint

Architecture

Main Process Execution

This plugin requires main process execution for OAuth authentication and IPC handlers. The plugin declares this requirement via:

module.exports = {
    plugin,
    TabContent,
    XboxStatus,
    requiresMainProcess: true  // OAuth and IPC handlers need main process
};

When loaded in the main process, the plugin:

1. Registers IPC handlers for authentication flow
2. Manages OAuth2 token lifecycle and secure storage
3. Coordinates presence polling and quota enforcement
4. Communicates with renderer via IPC for UI updates

Plugin Context API

The main process receives:

function plugin(context) {
    context.isMain              // true in main process
    context.ipcMain             // Electron ipcMain for registering handlers
    context.configurationUpdate(state)  // Persist encrypted tokens and config
    context.statusUpdate(status)        // Update authentication status
    context.allow2              // Allow2 integration for quota management
    context.logActivity(data)   // Log gaming activity
}

IPC Communication Pattern

Renderer → Main Process:

// components/TabContent.jsx
const handleAuth = async () => {
    const result = await ipcRenderer.invoke('xbox:authenticate');
    if (result.success) {
        // Update UI
    }
};

Main Process → Renderer:

// src/index.js (main process)
context.sendToRenderer('xbox:presenceUpdate', {
    gamertag: 'Player123',
    playing: true,
    game: 'Halo Infinite'
});

IMPORTANT: All window.require('electron') calls must be inside component functions, not at module level, to prevent main process loading errors.

For detailed main process documentation, see:

• Main Process Plugin Guide
• Template Documentation

Directory Structure

/mnt/ai/automate/plugins/allow2automate-xbox/
├── package.json              # Plugin manifest
├── rollup.config.js         # Build configuration
├── .babelrc                 # Babel configuration
├── src/
│   ├── index.js            # Main plugin entry
│   ├── services/           # Business logic
│   │   ├── XboxAuthManager.js
│   │   ├── XboxMonitorCoordinator.js
│   │   ├── ChildLinkManager.js
│   │   └── XboxAPI.js
│   ├── components/         # React UI components
│   │   ├── TabContent.jsx
│   │   ├── XboxStatus.jsx
│   │   ├── ChildLinkingWizard.jsx
│   │   ├── ActivityLog.jsx
│   │   └── QuotaDisplay.jsx
│   ├── utils/              # Utility functions
│   │   ├── tokenStorage.js
│   │   ├── privacy.js
│   │   ├── rateLimiter.js
│   │   └── cacheManager.js
│   └── constants/          # Constants
│       ├── xboxEndpoints.js
│       └── errorCodes.js
└── __tests__/              # Test files
    ├── unit/
    └── integration/

Key Components

• XboxAuthManager: Handles OAuth2 flow and token management
• XboxMonitorCoordinator: 15-second presence polling
• ChildLinkManager: Child-to-gamertag mapping
• XboxAPI: Xbox Live API wrapper with rate limiting

API

Actions

• authenticate - Connect Microsoft account via OAuth2
• checkQuota - Check remaining gaming time quota
• refreshPresence - Force refresh Xbox presence data
• linkChild - Link Allow2 child to Xbox gamertag
• unlinkChild - Remove Xbox gamertag link

Triggers

• quotaExceeded - Gaming quota exceeded
• gameStarted - Child started playing
• gameEnded - Child stopped playing
• sessionViolation - Gaming detected while blocked

Privacy & Security

• XUID Privacy: Xbox User IDs never displayed in UI (Microsoft XR-013 compliance)
• Token Security: Encrypted storage using Electron safeStorage
• Rate Limiting: Automatic rate limit handling (10 req/15s, 30 req/5min)
• OAuth Security: State parameter validation, HTTPS-only redirects

Testing

# Run all tests
npm test

# Run specific test file
npm test -- XboxAuthManager.test.js

# Watch mode
npm test:watch

# Coverage report
npm test:coverage

Target coverage: 80%+ for all metrics

License

Apache-2.0 License - see LICENSE file for details

Support

• Documentation: https://github.com/Allow2/allow2automate-xbox
• Issues: https://github.com/Allow2/allow2automate-xbox/issues
• Allow2 Support: https://allow2.com/support