Configuration Guide

Enveil uses a hierarchical configuration system with support for both traditional Site Configurations and Cloud Environments. This guide covers both configuration types in detail.

Configuration Structure

Dual-Tab Interface

The Options page is organized into two main tabs:

  1. Site Configurations: Traditional URL-based environment identification
  2. Cloud Environments: Cloud provider account and role highlighting

Cloud Portal Configuration interface with Site and Cloud Environment tabs

Site Configuration

Configuration Groups

Each group contains:

Site Portal Group Site configuration groups with multiple environment rules

Site Rules

Each site rule defines:

Field Description Type Example
Enable Toggle this specific rule on/off Boolean ✓
Match Pattern How to match the current page Enum domain
Match Value The string/regex to match against String localhost
Environment Name Text to display in banner String DEV
Color Background color of indicator Hex/RGB #4a9eff
Position Banner corner placement Enum rightTop
Banner Enable Show corner ribbon/banner Boolean ✓
Background Enable Show full-page overlay Boolean ✗

Match Patterns

Enveil supports five sophisticated matching strategies:

1. Everything (Auto-Match) - everything

Intelligent pattern detection with multiple fallback strategies

The system automatically detects the best matching approach:

Examples:

*                           → Matches everything
localhost                   → Matches localhost and *.localhost
https://api.example.com     → Matches URL prefix
/^https?:\/\/.*\.dev$/      → Regex for .dev domains

2. Domain - domain

Hostname-based matching with subdomain support

Examples:

example.com     → Matches example.com, app.example.com, api.example.com
localhost       → Matches localhost only
staging.app.io  → Matches staging.app.io only

3. URL Prefix - urlPrefix

Path-based matching for specific sections

Examples:

https://github.com/enveil          → Matches repository and sub-paths
http://localhost:3000/admin        → Matches admin section
https://api.example.com/v1         → Matches API v1 endpoints

4. Exact URL - url

Precise URL matching

Examples:

http://localhost:8080/admin        → Only admin page
https://app.example.com/dashboard  → Only dashboard page

5. Regex - regex

Advanced pattern matching with JavaScript RegExp

Examples:

^https?:\/\/.*\.test\.com          → All test.com subdomains
localhost:\d+                      → Localhost with any port
\/admin|\/dashboard                → Admin or dashboard paths

Visual Indicators

Corner Banners

Rotated ribbons in page corners

Positions:

Styling:

Background Overlays

Full-page color tinting

When Background Enable is checked:

Cloud Environment Configuration

Overview

Cloud Environment configuration allows you to visually distinguish between different cloud provider accounts and roles. Currently supported providers:

Cloud Environment Configuration Cloud environment configuration with provider selection

Cloud Environment Structure

Cloud Environment
├── Provider: AWS China / AWS Global / Custom
├── Name: "Production AWS"
├── Enable/Disable: Toggle
└── Accounts: List of cloud accounts
    ├── Account 1: "prod-main"
    │   ├── Background Color: #f44336 (Red)
    │   ├── Account Patterns: URL matching patterns
    │   └── Roles: Keyword highlighting rules
    └── Account 2: "dev-sandbox"
        ├── Background Color: #4a9eff (Blue)
        ├── Account Patterns: URL matching patterns
        └── Roles: Keyword highlighting rules

Cloud Account Configuration

Each cloud account defines:

Field Description Example
Name Account identifier prod-main
Enable Toggle account highlighting ✓
Background Enable Show background overlay ✓
Background Color Account highlight color #f44336
Account Patterns URL patterns to match account domain: 123456789012
Roles Role keyword highlighting rules Admin, ReadOnly

Account Patterns

Account patterns use the same matching strategies as site configurations:

AWS Account Pattern Examples:

# Match by account ID (12 digits)
Pattern: domain
Value: 123456789012

# Match by account name in URL
Pattern: urlPrefix
Value: https://123456789012.signin.aws.amazon.com

# Match multiple accounts with regex
Pattern: regex
Value: (123456789012|987654321098)

Role Highlighting

Roles define keywords to highlight within cloud pages:

Field Description Example
Enable Toggle role highlighting ✓
Match Pattern Matching strategy contains or regex
Match Value Keyword to highlight Administrator

Role Configuration Examples:

# Highlight Administrator roles
Match Pattern: contains
Match Value: Administrator

# Highlight multiple role patterns
Match Pattern: regex
Match Value: (Admin|PowerUser|FullAccess)

# Highlight specific role names
Match Pattern: contains
Match Value: ReadOnlyAccess

Visual Effects

Account Background Highlighting

Role Text Highlighting

AWS Account Selection Page AWS account selection page with account container highlighting and role keyword emphasis

AWS Console Highlighting AWS Console navigation bar with account information and role highlighting

Cloud Provider Templates

AWS China Template

{
  provider: 'aws-cn',
  accountSelectionUrl: 'https://signin.amazonaws.cn/saml',
  consoleDomainPattern: '*://*.amazonaws.cn/*',
  selectors: {
    accountSelection: {
      accountContainers: ['fieldset > div.saml-account:has(> .expandable-container .saml-account-name)'],
      roleElements: ['.saml-role-name', '.saml-role-description', 'label.saml-role']
    },
    console: {
      accountContainers: [
        '[data-testid="nav-username-menu"]',
        '[data-testid="awsc-nav-unified-account-menu-trigger"]',
        '#nav-usernameMenu',
        '.awsc-nav-account-info'
      ],
      roleElements: [
        '[data-testid="nav-username-menu"]',
        '#nav-usernameMenu button'
      ]
    }
  }
}

AWS Global Template

{
  provider: 'aws-global',
  accountSelectionUrl: 'https://signin.aws.amazon.com/saml',
  consoleDomainPattern: '*://*.aws.amazon.com/*',
  // Same selectors as AWS China
}

Console Page Highlighting

The console highlighting works on the AWS Console navigation bar:

Configuration Groups

Group Management

Group Defaults

Each group can define defaults for new sites:

{
  envName: "PROD",           // Default environment name
  backgroundEnable: true,    // Enable background overlay
  flagEnable: true,          // Enable corner banner
  color: "#f44336"          // Default red for production
}

Color System

Default Color Palette

Enveil includes 10 predefined colors:

Custom Colors

Import/Export System

Export Options

Full Configuration Export

Individual Group Export

Cloud Environment Export

Import Options

Full Configuration Import

Group Import

Cloud Import

Configuration Validation

The system validates:

Browser Synchronization

Sync Features

Conflict Resolution

When conflicts occur:

  1. Version Check: Compare configuration versions
  2. Timestamp Comparison: Use modification times
  3. User Choice: Present options for resolution:
    • Keep Local
    • Use Remote
    • Merge (where possible)

Sync Data Structure

interface CloudSyncData {
  configs: Setting[];              // Configuration groups
  cloudEnvironments: CloudEnvironment[];  // Cloud environments
  defaultColors: string[];         // Color palette
  lastModified: number;            // Timestamp
  version: string;                 // Schema version
}

Advanced Configuration

URL Parameters

The Options page supports URL parameters for quick actions:

chrome-extension://[id]/options.html?action=addSite&domain=example.com&pattern=domain

Configuration Migration

Performance Optimization

Best Practices

Rule Organization

  1. Group by Purpose: Separate work, personal, and testing environments
  2. Specific to General: Order rules from most specific to most general
  3. Color Coding: Use consistent colors for similar environments
  4. Descriptive Names: Use clear environment names (DEV, STAGING, PROD)

Cloud Configuration

  1. Use Templates: Start with built-in templates for quick setup
  2. Account Patterns: Use account IDs for precise matching
  3. Role Keywords: Use specific keywords (e.g., “Administrator” not “Admin”)
  4. Color Safety: Use red/orange for production accounts as warning
  5. Test First: Verify highlighting on account selection pages

Pattern Selection

  1. Domain: Best for entire sites and subdomains
  2. URL Prefix: Ideal for specific sections or API endpoints
  3. Exact URL: Use for single-page applications
  4. Regex: Reserve for complex scenarios
  5. Everything: Good for catch-all rules with intelligent detection

Performance Tips

  1. Disable Unused: Turn off rules and groups you don’t need
  2. Order Matters: Put frequently matched rules first
  3. Avoid Complex Regex: Use simpler patterns when possible
  4. Group Efficiently: Organize related rules together