safevalues

safevalues is a security library designed to prevent Cross-Site Scripting (XSS) vulnerabilities in TypeScript and JavaScript. It works by providing safe-by-construction values through escaping or sanitization, making security decisions so developers don't have to.

Key capabilities include:

• Trusted Types Integration: It defines policies to produce Trusted Types when the browser API is available, providing runtime protection.
• Extended Sink Protection: It provides types and builders for DOM APIs that are not covered by the standard Trusted Types specification.
• DOM Sink Wrappers: It offers wrappers for dangerous DOM APIs (e.g., setLocationHref from safevalues/dom) that sanitize arguments before assignment.
• Transparent Polyfilling: If Trusted Types is not supported by the browser, safevalues transparently uses its own internal types so the application continues to function.

If safety-web flags an assignment (e.g., myImg.src = value) because it cannot determine the element type, use setElementAttribute from safevalues/dom. This function performs a runtime check on the element and attribute name to ensure the assignment is safe.

Important: You must still use the correct safe type for the specific attribute. For example, a <script> element's src attribute requires a TrustedResourceUrl, not a SafeScript or a plain string.

import {setElementAttribute} from 'safevalues/dom';
import {trustedResourceUrl} from 'safevalues';

// Use when element type is unknown to avoid safety-web warnings
declare const myImg: unknown;
setElementAttribute(myImg, 'src', value);

// Correct usage for a script element
const myScript = document.createElement('script');
setElementAttribute(myScript, 'src', trustedResourceUrl`https://myapp.com/script.js`);

When standard library builders do not meet your application's specific needs, but the use case is narrow and safe, you can use safevalues/restricted/reviewed.

If you use tsec, you can use reviewed conversion functions which create a polyfilled value. These functions require a justification object to document why the operation is safe, helping to enforce human review and prevent misuse.

If you are in a browser with native Trusted Types support, you should instead create a new policy, add it to your headers, and include an extensive comment explaining the safety rationale.

import {setScriptSrc} from 'safevalues/dom';
import {scriptSafeByReview} from 'safevalues/restricted/reviewed';

if (document.domain === '') {
    const scriptText = scriptSafeByReview(
        userInput,
        {
            justification: `Even though the input is user controller, the wrapping if statement
         ensures that this code is only ever run in a sandboxed origin`
        }
    );
    setScriptSrc(scriptEl, scriptText);
}

Direct use of Element#setAttribute is discouraged as it can bypass security checks. Use these alternatives:

1. Specific Setters: Use dedicated functions like setAnchorHref for known attributes.
2. Prefixed Attributes: If attribute names are dynamic but follow a known pattern (e.g., aria-*), use setElementPrefixedAttribute with safeAttrPrefix to restrict the allowed prefixes.
3. Dataset API: For data-* attributes, use the standard Element.dataset API.

import {setAnchorHref, setElementPrefixedAttribute} from 'safevalues/dom';
import {safeAttrPrefix} from 'safevalues';

// 1. Use specific setters
setAnchorHref(anchor, safeUrl`https://example.com`);

// 2. Use prefixed attributes for dynamic names (e.g., aria-* or role*)
setElementPrefixedAttribute(
    [safeAttrPrefix`aria-`, safeAttrPrefix`role`], 
    elem, 
    attr, 
    value
);

// 3. Use dataset for data-* attributes
elem.dataset['safe'] = true;

To minimize the production bundle size, safevalues strips out error messages and development-time checks using the process.env.NODE_ENV !== 'production' compile-time constant from the environment.ts module.

To ensure the compiler successfully removes this code, you must follow two rules:

1. Use dedicated if statements: Always use the constant in a standalone if statement without combining it with other conditions (e.g., do not use if (otherVar && process.env.NODE_ENV !== 'production')).
2. Proximity to API: Place these if statements as close to the public API surface as possible to maximize code stripping.

Error Messages

Only include verbose error messages inside a development-mode check so they are removed in production.

Development-time Checks

Security or development checks that use compile-time assertions or have no downstream effects should be wrapped in a development-mode check.

// Example: Stripping an error message
import {process.env.NODE_ENV !== 'production'} from './environment';

let message = '';
if (process.env.NODE_ENV !== 'production') {
  message = 'Verbose error message';
}
throw new Error(message);

// Example: Stripping a development-time check
import {process.env.NODE_ENV !== 'production'} from './environment';

if (process.env.NODE_ENV !== 'production') {
  assertIsTemplateObject(input);
}

To prevent XSS when rendering HTML, avoid direct assignments to risky DOM properties like .innerHTML, .outerHTML, or .srcdoc. Instead, use safevalues/dom setter functions that require a SafeHtml instance. If the content is plain text and does not require HTML parsing, use .textContent or .insertAdjacentText instead.

import {setElementInnerHtml, setElementOuterHtml, setIframeSrcdoc, elementInsertAdjacentHTML, documentWrite, domParserParseFromString, rangeCreateContextualFragment} from 'safevalues/dom';

// Safe alternatives for common sinks:
setElementInnerHtml(element, safeHtmlValue);
setElementOuterHtml(element, safeHtmlValue);
setIframeSrcdoc(iframe, safeHtmlValue);
elementInsertAdjacentHTML(element, 'beforeend', safeHtmlValue);
documentWrite(document, safeHtmlValue);
domParserParseFromString(parser, safeHtmlValue, mimeType);
rangeCreateContextualFragment(range, safeHtmlValue);

The safevalues/restricted/legacy module provides unsafe conversions from string to Trusted Types. These are intended as temporary bridge solutions during migration from raw strings to Trusted Types.

Workflow:

1. Use a legacy conversion function (e.g., legacyUnsafeResourceUrl) at the sink (where the value is used, like innerHTML or setScriptSrc) to make the code compatible with Trusted Types.
2. Gradually "move up" the conversion point closer to where the value is originally created.
3. Once the conversion point is in a context where the value can be constructed safely, replace the legacy conversion with a proper safe builder and remove the legacy dependency.

import {legacyUnsafeResourceUrl} from 'safevalues/restricted/legacy';
import {setScriptSrc} from 'safevalues/dom';

// Temporary bridge: converting a string to a Trusted Type at the sink
setScriptSrc(script, legacyUnsafeResourceUrl(url));