Security Architecture & Considerations

This document outlines the security architecture, design decisions, and compensating controls implemented in Teams for Linux, particularly around the DOM access requirements and security trade-offs.

Security Context

The DOM Access Requirement

Teams for Linux requires DOM access to Microsoft Teams' React components to provide core functionality:

User Status Tracking: Monitor and sync user presence state
Custom Background Integration: Inject custom background options into Teams interface
System Idle Management: Sync system idle state with Teams presence
Authentication Flow Enhancement: Improve login experience and reduce re-authentication

Security vs. Functionality Trade-off

The application faces a fundamental security vs. functionality trade-off:

Option A: Maximum Security

Enable Electron contextIsolation and sandbox
❌ Breaks all DOM access functionality
❌ Eliminates core application features

Option B: Balanced Security (Current Approach)

Disable contextIsolation and sandbox for main window
✅ Restore all DOM access functionality
✅ Implement comprehensive compensating controls
✅ Recommend system-level sandboxing

Current Security Implementation

Electron Security Configuration

// app/mainAppWindow/browserWindowManager.js
webPreferences: {
  contextIsolation: false,  // Required for ReactHandler DOM access
  nodeIntegration: false,   // Secure: preload scripts don't need this
  sandbox: false,           // Required for system API access
}

Key Security Decision: nodeIntegration remains false to prevent Node.js access in renderer processes, maintaining a critical security boundary.

Compensating Security Controls

1. Content Security Policy (CSP) Headers

Implementation: app/mainAppWindow/browserWindowManager.js:59-102

const responseHeaders = {
  'Content-Security-Policy': [
    "default-src 'self' https://teams.cloud.microsoft https://teams.microsoft.com https://teams.live.com ...",
    "script-src 'self' https://teams.cloud.microsoft https://teams.microsoft.com ...",
    "object-src 'none';",
    "base-uri 'self';",
    "frame-ancestors 'none';"
  ]
};

Protection: Prevents malicious script injection and restricts resource loading to trusted domains.

2. IPC Channel Validation

Implementation: app/security/ipcValidator.js

Features:

Channel Allowlisting: Only legitimate IPC channels are permitted
Recursive Payload Sanitization: Removes dangerous properties (__proto__, constructor, prototype) from payloads at all nesting depths
Prototype Pollution Protection: Guards against object prototype manipulation with depth-limited recursion (max 10 levels)
Request Validation: Validates all IPC requests before processing
Sender Pinning: Channels only the screen-share picker uses (desktop-capturer-get-sources, get-screen-sharing-displays, selected-source, close-view, and the legacy picker's source-selected) are answered only when the sending frame shows a file inside the app directory (isSenderAllowed), so page script cannot capture the screen or pick a source on its own
No Raw ipcRenderer in the Page: With contextIsolation: false, anything electronAPI returns is usable by page script, so its listener helpers return nothing and strip Electron's IPC event (whose sender is the raw ipcRenderer) before calling back

function validateIpcChannel(channel, payload = null) {
  if (!allowedChannels.has(channel)) {
    console.warn(`[IPC Security] Blocked unauthorized channel: ${channel}`);
    return false;
  }
  sanitizePayload(payload); // Recursive sanitization
  return true;
}

3. Domain Validation

Implementation: app/browser/tools/reactHandler.js:142-157

_isAllowedTeamsDomain(hostname) {
  const allowedDomains = [
    'teams.cloud.microsoft',
    'teams.microsoft.com',
    'teams.live.com'
  ];
  
  // Prevents subdomain hijacking attacks
  for (const domain of allowedDomains) {
    if (hostname === domain) return true;
    if (hostname.endsWith('.' + domain)) return true;
  }
  return false;
}

Protection: Restricts DOM access to legitimate Teams domains only, preventing access from malicious sites.

Security Model: Screen sharing windows maintain full security isolation:

contextIsolation: true
sandbox: true
No DOM access requirements
Separate security context

5. Process Error Handlers

Implementation: app/index.js (top-level)

Features:

uncaughtException handler: Logs error details and exits with code 1 (process state unknown after uncaught exception)
unhandledRejection handler: Logs rejection details; network errors are ignored, anything else exits with code 1, so every promise-returning Electron call (for example shell.openExternal) must be caught
Startup try/catch: handleAppReady() wrapped with error logging and graceful app.quit() on failure

Protection: Prevents silent process termination and provides diagnostic output for crash reports.

6. Input Sanitization for External Commands

Implementation: app/mainAppWindow/browserWindowManager.js

Features:

sanitizeCommandArg(): Validates string type, limits length to 500 characters, strips control characters
Applied to all incoming call notification arguments (caller, text, image) before passing to spawn()

Protection: Defense-in-depth against edge cases in user-configured notification commands receiving untrusted data from Teams messages.

7. Webview Attach Blocked

Implementation: app/security/webviewGuard.js, webviewTag: false in app/mainAppWindow/browserWindowManager.js and profileViewManager.js

Features:

webviewTag: false: Nothing in the app or in Teams web uses <webview>, so the tag is off in the root window and every profile view
App-wide will-attach-webview refusal: Covers any webContents created later, including popups, since a guest can request its own preload with sandbox=no and that preload would run with full Node.js
Sticker import signature check: customStickers URL import saves a file only when it starts with the declared image type's signature, rather than trusting the server's content-type header alone (a format sanity check; the webview block is the actual protection)

Protection: Keeps page script from turning a file on disk into code running with Node.js, which preserves the nodeIntegration: false boundary above.

Recommended User-Level Security

System-Level Sandboxing

Instead of relying solely on Electron security features, users should adopt system-level sandboxing:

Available Options

Flatpak

Built-in application isolation
Available via Flathub
Automatic permission management
Filesystem access restrictions

Snap Packages

Application confinement system
Auto-updates with security patches
Interface-based permission system

AppArmor/SELinux

Available by default on most Linux distributions
Kernel-level security enforcement
Fine-grained access control policies

Manual Sandboxing Tools

firejail: User-space sandboxing
bubblewrap: Container-based isolation
Custom chroot environments

Why System-Level > Application-Level

Preserves Functionality: DOM access remains intact
Better Security: OS-level controls more robust than Electron sandbox
User Choice: Flexible security levels based on individual needs
Future-Proof: Works regardless of Teams/React changes
Defense in Depth: Additional security layer independent of application

Security Monitoring & Maintenance

React Version Monitoring

Implementation: Automatic React version detection in app/browser/tools/reactHandler.js

_detectAndLogReactVersion() {
  const { version, method } = this._detectReactVersion();
  console.debug(`ReactHandler: React version detected: ${version} (via ${method})`);
}

Purpose: Monitor Teams React version updates that could break DOM access functionality.

Future Security Enhancements

Token Storage Security (Implemented v2.5.9)

Token Cache Secure Storage Implementation:

OS-Level Encryption: Authentication tokens encrypted using Electron safeStorage API
Platform-Native Security: Leverages Keychain (macOS), DPAPI (Windows), kwallet/gnome (Linux)
Graceful Fallback: Automatic fallback to localStorage if secure storage unavailable
Migration Safety: One-time migration from localStorage to secure storage with no data loss
PII Protection: All logging sanitizes personally identifiable information

Security Benefits:

Risk Mitigation:

✅ Tokens encrypted at rest using OS cryptographic APIs
✅ Application-specific access control
✅ No plain text token storage (when secure storage available)
✅ Automatic migration preserves existing authentication
⚠️ Variable security on Linux (depends on desktop environment)
⚠️ Fallback to localStorage when secure storage unavailable

Phase 2: API Integration Security

Future Planned Security Improvements:

OAuth 2.0 Integration: Secure Microsoft Graph authentication
Permission Scoping: Minimal required API permissions
Rate Limiting: API abuse prevention

Timeline: Future consideration based on user needs

Long-term Security Goals

Progressive Hardening: Gradual restoration of Electron security features as API migration completes
Zero-Trust Architecture: Assume all external inputs are malicious
Automated Security Testing: Integration of security tests in CI/CD
Security Documentation: Comprehensive security guide for developers

Risk Assessment

Current Risk Level: LOW

Real-World Security Assessment:

Effective Security Controls:

✅ System-Level Sandboxing: Modern OS distributions enforce application sandboxing by default (Flatpak, Snap, AppArmor, SELinux)
✅ Microsoft's Infrastructure Security: Teams web app runs on Microsoft's secured infrastructure with their security controls
✅ Domain Restrictions: Application limited to Teams domains only, not arbitrary web content
✅ Node.js Access Prevented: nodeIntegration: false maintains critical security boundary
✅ Comprehensive IPC Validation: Channel allowlisting and payload sanitization
✅ Token Encryption: Authentication tokens encrypted at rest using OS-level security

Technical Trade-offs (Mitigated by Above):

⚠️ Electron context isolation disabled for DOM access functionality
⚠️ Electron sandbox disabled for system integration features

Assessment: The combination of modern OS-level sandboxing, Microsoft's web app security controls, comprehensive compensating measures, and proven operational history results in a low-risk security posture. The disabled Electron features are effectively compensated by system-level protections that are now standard across all major platforms.

Continued Security Best Practices

For Users:

Use official package repositories (Flatpak, Snap, distribution packages) when available
Keep the application updated through your package manager
Follow your distribution's security recommendations

For Developers:

Continue monitoring Teams web app changes that could affect security
Maintain IPC channel validation and domain restrictions
Keep dependencies updated and monitor security advisories

Security Architecture Benefits

Why This Approach Works:

Layered Security: System-level sandboxing + application controls + Microsoft's security
Transparent Trade-offs: Clear documentation of technical decisions and mitigations
Future-Compatible: Architecture supports progressive enhancement as APIs become available

The current security posture represents an acceptable risk because:

Compensating Controls: Multiple security layers implemented
User Choice: System-level sandboxing available
Community Benefit: Preserves functionality for thousands of users
Open Source: Transparent implementation for security review

Security Contact & Reporting

Security Issues: Report via GitHub Security Advisories
Security Questions: GitHub Discussions security category
Emergency Contact: Project maintainer via GitHub

Security Context​

The DOM Access Requirement​

Security vs. Functionality Trade-off​

Current Security Implementation​

Electron Security Configuration​

Compensating Security Controls​

1. Content Security Policy (CSP) Headers​

2. IPC Channel Validation​

3. Domain Validation​

4. Screen Sharing Isolation​

5. Process Error Handlers​

6. Input Sanitization for External Commands​

7. Webview Attach Blocked​

Recommended User-Level Security​

System-Level Sandboxing​

Available Options​

Why System-Level > Application-Level​

Security Monitoring & Maintenance​

React Version Monitoring​

Future Security Enhancements​

Token Storage Security (Implemented v2.5.9)​

Phase 2: API Integration Security​

Long-term Security Goals​

Risk Assessment​

Current Risk Level: LOW​

Continued Security Best Practices​

Security Architecture Benefits​

Security Contact & Reporting​

Security Context

The DOM Access Requirement

Security vs. Functionality Trade-off

Current Security Implementation

Electron Security Configuration

Compensating Security Controls

1. Content Security Policy (CSP) Headers

2. IPC Channel Validation

3. Domain Validation

4. Screen Sharing Isolation

5. Process Error Handlers

6. Input Sanitization for External Commands

7. Webview Attach Blocked

Recommended User-Level Security

System-Level Sandboxing

Available Options

Why System-Level > Application-Level

Security Monitoring & Maintenance

React Version Monitoring

Future Security Enhancements

Token Storage Security (Implemented v2.5.9)

Phase 2: API Integration Security

Long-term Security Goals

Risk Assessment

Current Risk Level: LOW

Continued Security Best Practices

Security Architecture Benefits

Security Contact & Reporting