Home > Documentation > Security

Security Guide

Security best practices for cross-window communication with ParleyJS.

Overview

Cross-window communication has inherent security risks. This section covers ParleyJS security features, best practices, and common security pitfalls.

ParleyJS implements security-first design with origin validation, payload sanitization, and DoS prevention built-in.

Contents

Security Topics

• Origin Validation - Validating message sources

  • Why origin validation matters
  • Configuring allowed origins
  • Common mistakes
  • Testing origin validation

• Message Validation - Validating message content

  • Schema validation
  • Input sanitization
  • XSS prevention
  • Data type checking

Complete Security Guide

• SECURITY.md - Comprehensive security documentation
  • Threat model
  • Attack prevention
  • Security testing
  • Reporting security issues

Critical Security Rules

Always:

1. Validate origins explicitly (never use *)
2. Validate message content before processing
3. Use HTTPS in production
4. Sanitize data before displaying
5. Never send sensitive data through postMessage

Never:

1. Use wildcard origins in production
2. Trust message content without validation
3. Send passwords or tokens
4. Execute code from messages
5. Disable origin checking

Quick Security Checklist

Before deploying:

• [ ] Origins are explicitly configured (not *)
• [ ] HTTPS is used in production
• [ ] Message content is validated
• [ ] Error messages don't leak sensitive data
• [ ] Security tests pass
• [ ] Code reviewed for security issues

Common Security Mistakes

Mistake 1: Wildcard origins

// DANGEROUS
allowedOrigins: ['*'];

// CORRECT
allowedOrigins: ['https://trusted-domain.com'];

Mistake 2: Not validating content

// DANGEROUS
parley.on('update', (data) => {
    element.innerHTML = data.html; // XSS risk!
});

// CORRECT
parley.on('update', (data) => {
    element.textContent = data.text; // Safe
});

Mistake 3: Sending sensitive data

// DANGEROUS
await parley.send('login', { password: 'secret123' });

// CORRECT
await parley.send('login', { sessionToken: token });

Security Features

ParleyJS provides:

• Automatic origin validation - Messages from unauthorized origins are rejected
• Payload sanitization - Dangerous content is removed automatically
• DoS prevention - Size limits and rate limiting
• Protocol validation - Message structure is verified
• Error safety - No sensitive data in error messages

For details, see SECURITY.md.

Testing Security

Security must be tested:

// Test origin validation
it('should reject messages from wrong origin', async () => {
    const handler = vi.fn();
    parley.on('message', handler);

    await simulateMessageFrom('https://evil.com');

    expect(handler).not.toHaveBeenCalled();
});

For more testing patterns, see Testing Patterns.

Related Sections

• Origin Validation - Origin security details
• Message Validation - Content validation
• SECURITY.md - Complete security guide
• Error Handling - Secure error handling
• Testing Patterns - Security testing

Reporting Security Issues

Found a security issue? See Reporting Security Issues.

Do not open public issues for security vulnerabilities.

---

Navigation

Security Topics:

• Origin Validation
• Message Validation

Related:

• Complete Security Guide
• Testing Security

Back to: Documentation Home | Project Home