📋

<secure-select>

A security-hardened dropdown that enforces a closed option allowlist, prevents value injection attacks, and provides full audit logging.

The Problem with Native Select

A native <select> has no client-side allowlist enforcement. Any JavaScript running on the page — including browser extensions, injected scripts, or malicious third-party code — can set the value to anything:

Native select — trivially bypassed JavaScript
// A native <select> with options: viewer, editor
const select = document.querySelector('select[name="role"]');

// This succeeds silently — no error, no log
select.value = 'admin';

// The form now submits "admin" even though it was never in the options
console.log(select.value); // "admin"
Why server-side validation isn't enough on its own
Server validation is essential, but client-side injection can bypass access control checks that rely on the submitted value being "one of the expected options." It also produces no visible signal — the tampered submission looks identical to a legitimate one. Defence in depth means catching it client-side too, and logging it.

How Secure Select Fixes It

On mount, <secure-select> reads every <option value> from the server-rendered HTML and locks them into a private allowlist. From that point, only those values can be selected — programmatically or by the user.

🔒
Closed option allowlist
Valid values are snapshotted from the server-rendered <option> elements at initialization. Any attempt to set a value outside this set is rejected and the field is reset to empty.
🛡
XSS sanitization
Option values and display text are sanitized before insertion into the Shadow DOM. Dynamically-added options via addOption() pass through the same sanitization pipeline.
📋
Audit logging
Every selection, focus, blur, and blocked injection attempt is recorded. Blocked entries include the exact value that was attempted.
⚡
Progressive enhancement
Without JavaScript, the component falls back to a native <select>. JS adds the security layer — the form always works.
🚫 Injection attempt — blocked JavaScript
const select = document.querySelector('secure-select[name="role"]');
// Options are: viewer, editor — set server-side

// Injection attempt
select.value = 'admin';

// Rejected: value is reset to '' and logged
console.log(select.value); // ""

// Audit log records the attempt:
// { action: 'invalid_option_detected', attemptedValue: 'admin' }
const log = select.getAuditLog();

Basic Usage

Drop in as a direct replacement for <select>. Options are declared server-side — this is what seeds the allowlist.

HTML HTML
<secure-select
  label="Role"
  name="role"
  security-tier="critical"
  required
>
  <option value="">Select a role</option>
  <option value="viewer">Viewer</option>
  <option value="editor">Editor</option>
  <option value="admin">Administrator</option>
</secure-select>
Live Demo

Security Tiers

The security-tier attribute controls validation strictness, autocomplete behaviour, and rate limiting. Default is critical.

Public
Use for: Preferences, categories, filters
Autocomplete: Allowed
Rate limiting: Off
Sensitive
Use for: Country, address type, payment method
Autocomplete: Disabled
Rate limiting: On
Critical
Use for: Roles, permissions, security questions
Autocomplete: Disabled
Rate limiting: On, full audit logging
Tier examples HTML
<!-- PUBLIC: General preferences, browser autocomplete allowed -->
<secure-select security-tier="public" label="Theme" name="theme">
  <option value="light">Light</option>
  <option value="dark">Dark</option>
  <option value="system">System</option>
</secure-select>

<!-- CRITICAL: Permission level, autocomplete off, full audit log -->
<secure-select security-tier="critical" label="Access Level" name="access_level">
  <option value="viewer">Viewer</option>
  <option value="editor">Editor</option>
  <option value="admin">Administrator</option>
</secure-select>

Dynamic Options

When options must be loaded from an API, use addOption(). Added options are sanitized and registered in the allowlist before the component accepts them as valid selections.

Prefer server-rendered options where possible
Server-rendered <option> elements are the most secure approach — the allowed set is defined at render time and never travels through client-side JS. Use dynamic loading only when the option list cannot be known at render time.
Loading options from an API JavaScript
const select = document.querySelector('secure-select[name="country"]');

const response = await fetch('/api/countries');
const countries = await response.json();

select.clearOptions();
select.addOption('', 'Select a country');

for (const { code, name } of countries) {
  // Values are sanitized inside addOption() before entering the allowlist
  select.addOption(code, name);
}

API Reference

Attributes

AttributeTypeDefaultDescription
security-tierstring"critical"Validation strictness: public, sensitive, critical
namestring-Form field name
labelstring-Visible label text (also sets aria-label when no visible label)
requiredbooleanfalseField is required
disabledbooleanfalseDisable the select
multiplebooleanfalseAllow multiple selections — all selected values are validated against the allowlist
sizenumber-Number of visible options (listbox mode)

Properties

value string Get or set the selected value. Setting to a value not in the allowlist is rejected.
valid boolean Whether the current selection passes all validation rules
selectedOptions string[] Array of selected values for multi-select

Methods

addOption(value: string, text: string, selected?: boolean): void
Add an option. Value and text are sanitized; the value is added to the allowlist.
removeOption(value: string): void
Remove an option by value and remove it from the allowlist
clearOptions(): void
Remove all options and reset the allowlist
getAuditLog(): AuditLogEntry[]
Returns all audit entries including blocked injection attempts
getFieldTelemetry(): FieldTelemetry
Returns behavioral signals for this field
reportError(message: string, variant?: 'error' | 'warning'): void
Display an external validation message on this field. Default variant is 'error'.
clearExternalError(): void
Clear a message previously set by reportError()

Events

EventDetailDescription
secure-select-change{ name, value, tier }Fired on valid selection change. value is a string array for multi-select, a string for single-select. Not fired when an injection attempt is blocked.
secure-audit{ event, tier, timestamp, data? }Fired on every audit entry