@bquery/bquery 1.5.0 → 1.7.0

package/src/security/constants.ts

@@ -1,211 +1,211 @@
-/**
- * Security constants and safe lists.
- *
- * @module bquery/security
- */
-
-/**
- * Trusted Types policy name.
- */
-export const POLICY_NAME = 'bquery-sanitizer';
-
-/**
- * Default allowed HTML tags considered safe.
- */
-export const DEFAULT_ALLOWED_TAGS = new Set([
-  'a',
-  'abbr',
-  'address',
-  'article',
-  'aside',
-  'b',
-  'bdi',
-  'bdo',
-  'blockquote',
-  'br',
-  'button',
-  'caption',
-  'cite',
-  'code',
-  'col',
-  'colgroup',
-  'data',
-  'dd',
-  'del',
-  'details',
-  'dfn',
-  'div',
-  'dl',
-  'dt',
-  'em',
-  'figcaption',
-  'figure',
-  'footer',
-  'form',
-  'h1',
-  'h2',
-  'h3',
-  'h4',
-  'h5',
-  'h6',
-  'header',
-  'hgroup',
-  'hr',
-  'i',
-  'img',
-  'input',
-  'ins',
-  'kbd',
-  'label',
-  'legend',
-  'li',
-  'main',
-  'mark',
-  'nav',
-  'ol',
-  'optgroup',
-  'option',
-  'p',
-  'picture',
-  'pre',
-  'progress',
-  'q',
-  'rp',
-  'rt',
-  'ruby',
-  's',
-  'samp',
-  'section',
-  'select',
-  'small',
-  'source',
-  'span',
-  'strong',
-  'sub',
-  'summary',
-  'sup',
-  'table',
-  'tbody',
-  'td',
-  'textarea',
-  'tfoot',
-  'th',
-  'thead',
-  'time',
-  'tr',
-  'u',
-  'ul',
-  'var',
-  'wbr',
-]);
-
-/**
- * Explicitly dangerous tags that should never be allowed.
- * These are checked even if somehow added to allowTags.
- */
-export const DANGEROUS_TAGS = new Set([
-  'script',
-  'iframe',
-  'frame',
-  'frameset',
-  'object',
-  'embed',
-  'applet',
-  'link',
-  'meta',
-  'style',
-  'base',
-  'template',
-  // 'slot' is intentionally excluded here so component shadow markup can opt in
-  // via sanitizeHtml(..., { allowTags: ['slot'] }). It remains disallowed by default
-  // for general HTML writes, because DEFAULT_ALLOWED_TAGS does not include it.
-  'math',
-  'svg',
-  'foreignobject',
-  'noscript',
-]);
-
-/**
- * Reserved IDs that could cause DOM clobbering attacks.
- * These are prevented to avoid overwriting global browser objects.
- */
-export const RESERVED_IDS = new Set([
-  // Global objects
-  'document',
-  'window',
-  'location',
-  'top',
-  'self',
-  'parent',
-  'frames',
-  'history',
-  'navigator',
-  'screen',
-  // Dangerous functions
-  'alert',
-  'confirm',
-  'prompt',
-  'eval',
-  'function',
-  // Document properties
-  'cookie',
-  'domain',
-  'referrer',
-  'body',
-  'head',
-  'forms',
-  'images',
-  'links',
-  'scripts',
-  // DOM traversal properties
-  'children',
-  'parentnode',
-  'firstchild',
-  'lastchild',
-  // Content manipulation
-  'innerhtml',
-  'outerhtml',
-  'textcontent',
-]);
-
-/**
- * Default allowed attributes considered safe.
- * Note: 'style' is excluded by default because inline CSS can be abused for:
- * - UI redressing attacks
- * - Data exfiltration via url() in CSS
- * - CSS injection vectors
- * If you need to allow inline styles, add 'style' to allowAttributes in your
- * sanitizeHtml options, but ensure you implement proper CSS value validation.
- */
-export const DEFAULT_ALLOWED_ATTRIBUTES = new Set([
-  'alt',
-  'class',
-  'dir',
-  'height',
-  'hidden',
-  'href',
-  'id',
-  'lang',
-  'loading',
-  'name',
-  'rel',
-  'role',
-  'src',
-  'srcset',
-  'tabindex',
-  'target',
-  'title',
-  'type',
-  'width',
-  'aria-*',
-]);
-
-/**
- * Dangerous attribute prefixes to always remove.
- */
-export const DANGEROUS_ATTR_PREFIXES = ['on', 'formaction', 'xlink:', 'xmlns:'];
-
-/**
- * Dangerous URL protocols to block.
- */
-export const DANGEROUS_PROTOCOLS = ['javascript:', 'data:', 'vbscript:', 'file:'];
+/**
+ * Security constants and safe lists.
+ *
+ * @module bquery/security
+ */
+
+/**
+ * Trusted Types policy name.
+ */
+export const POLICY_NAME = 'bquery-sanitizer';
+
+/**
+ * Default allowed HTML tags considered safe.
+ */
+export const DEFAULT_ALLOWED_TAGS = new Set([
+  'a',
+  'abbr',
+  'address',
+  'article',
+  'aside',
+  'b',
+  'bdi',
+  'bdo',
+  'blockquote',
+  'br',
+  'button',
+  'caption',
+  'cite',
+  'code',
+  'col',
+  'colgroup',
+  'data',
+  'dd',
+  'del',
+  'details',
+  'dfn',
+  'div',
+  'dl',
+  'dt',
+  'em',
+  'figcaption',
+  'figure',
+  'footer',
+  'form',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'header',
+  'hgroup',
+  'hr',
+  'i',
+  'img',
+  'input',
+  'ins',
+  'kbd',
+  'label',
+  'legend',
+  'li',
+  'main',
+  'mark',
+  'nav',
+  'ol',
+  'optgroup',
+  'option',
+  'p',
+  'picture',
+  'pre',
+  'progress',
+  'q',
+  'rp',
+  'rt',
+  'ruby',
+  's',
+  'samp',
+  'section',
+  'select',
+  'small',
+  'source',
+  'span',
+  'strong',
+  'sub',
+  'summary',
+  'sup',
+  'table',
+  'tbody',
+  'td',
+  'textarea',
+  'tfoot',
+  'th',
+  'thead',
+  'time',
+  'tr',
+  'u',
+  'ul',
+  'var',
+  'wbr',
+]);
+
+/**
+ * Explicitly dangerous tags that should never be allowed.
+ * These are checked even if somehow added to allowTags.
+ */
+export const DANGEROUS_TAGS = new Set([
+  'script',
+  'iframe',
+  'frame',
+  'frameset',
+  'object',
+  'embed',
+  'applet',
+  'link',
+  'meta',
+  'style',
+  'base',
+  'template',
+  // 'slot' is intentionally excluded here so component shadow markup can opt in
+  // via sanitizeHtml(..., { allowTags: ['slot'] }). It remains disallowed by default
+  // for general HTML writes, because DEFAULT_ALLOWED_TAGS does not include it.
+  'math',
+  'svg',
+  'foreignobject',
+  'noscript',
+]);
+
+/**
+ * Reserved IDs that could cause DOM clobbering attacks.
+ * These are prevented to avoid overwriting global browser objects.
+ */
+export const RESERVED_IDS = new Set([
+  // Global objects
+  'document',
+  'window',
+  'location',
+  'top',
+  'self',
+  'parent',
+  'frames',
+  'history',
+  'navigator',
+  'screen',
+  // Dangerous functions
+  'alert',
+  'confirm',
+  'prompt',
+  'eval',
+  'function',
+  // Document properties
+  'cookie',
+  'domain',
+  'referrer',
+  'body',
+  'head',
+  'forms',
+  'images',
+  'links',
+  'scripts',
+  // DOM traversal properties
+  'children',
+  'parentnode',
+  'firstchild',
+  'lastchild',
+  // Content manipulation
+  'innerhtml',
+  'outerhtml',
+  'textcontent',
+]);
+
+/**
+ * Default allowed attributes considered safe.
+ * Note: 'style' is excluded by default because inline CSS can be abused for:
+ * - UI redressing attacks
+ * - Data exfiltration via url() in CSS
+ * - CSS injection vectors
+ * If you need to allow inline styles, add 'style' to allowAttributes in your
+ * sanitizeHtml options, but ensure you implement proper CSS value validation.
+ */
+export const DEFAULT_ALLOWED_ATTRIBUTES = new Set([
+  'alt',
+  'class',
+  'dir',
+  'height',
+  'hidden',
+  'href',
+  'id',
+  'lang',
+  'loading',
+  'name',
+  'rel',
+  'role',
+  'src',
+  'srcset',
+  'tabindex',
+  'target',
+  'title',
+  'type',
+  'width',
+  'aria-*',
+]);
+
+/**
+ * Dangerous attribute prefixes to always remove.
+ */
+export const DANGEROUS_ATTR_PREFIXES = ['on', 'formaction', 'xlink:', 'xmlns:'];
+
+/**
+ * Dangerous URL protocols to block.
+ */
+export const DANGEROUS_PROTOCOLS = ['javascript:', 'data:', 'vbscript:', 'file:'];

package/src/security/index.ts

@@ -1,10 +1,12 @@
-/**
- * Security module providing sanitization, CSP compatibility, and Trusted Types.
- *
- * @module bquery/security
- */
-
-export { generateNonce, hasCSPDirective } from './csp';
-export { escapeHtml, sanitizeHtml as sanitize, sanitizeHtml, stripTags } from './sanitize';
-export { createTrustedHtml, getTrustedTypesPolicy, isTrustedTypesSupported } from './trusted-types';
-export type { SanitizeOptions } from './types';
+/**
+ * Security module providing sanitization, CSP compatibility, and Trusted Types.
+ *
+ * @module bquery/security
+ */
+
+export { generateNonce, hasCSPDirective } from './csp';
+export { escapeHtml, sanitizeHtml as sanitize, sanitizeHtml, stripTags } from './sanitize';
+export { trusted } from './trusted-html';
+export { createTrustedHtml, getTrustedTypesPolicy, isTrustedTypesSupported } from './trusted-types';
+export type { SanitizedHtml, TrustedHtml } from './trusted-html';
+export type { SanitizeOptions } from './types';

package/src/security/sanitize.ts

@@ -6,9 +6,13 @@
  */
 
 import { sanitizeHtmlCore } from './sanitize-core';
+import { toSanitizedHtml } from './trusted-html';
+import type { SanitizedHtml } from './trusted-html';
 import type { SanitizeOptions } from './types';
 export { generateNonce } from './csp';
 export { isTrustedTypesSupported } from './trusted-types';
+export { trusted } from './trusted-html';
+export type { SanitizedHtml, TrustedHtml } from './trusted-html';
 
 /**
  * Sanitize HTML string, removing dangerous elements and attributes.
@@ -24,8 +28,8 @@ export { isTrustedTypesSupported } from './trusted-types';
  * // Returns: '<div>Hello</div>'
  * ```
  */
-export const sanitizeHtml = (html: string, options: SanitizeOptions = {}): string => {
-  return sanitizeHtmlCore(html, options);
+export const sanitizeHtml = (html: string, options: SanitizeOptions = {}): SanitizedHtml => {
+  return toSanitizedHtml(sanitizeHtmlCore(html, options));
 };
 
 /**

package/src/security/trusted-html.ts

@@ -0,0 +1,71 @@
+declare const sanitizedHtmlBrand: unique symbol;
+const trustedHtmlBrand: unique symbol = Symbol('bquery.trusted-html.brand');
+const TRUSTED_HTML_VALUE = Symbol('bquery.trusted-html');
+
+/**
+ * Branded HTML string produced by bQuery's sanitization or escaping template helpers.
+ *
+ * Values returned from {@link sanitizeHtml} carry sanitized markup. Values returned from
+ * {@link safeHtml} preserve the template's static markup while escaping normal interpolations
+ * and splicing {@link trusted} fragments verbatim. This brand is not intended for arbitrary
+ * strings or manual concatenation outside those helpers.
+ */
+export type SanitizedHtml = string & { readonly [sanitizedHtmlBrand]: true };
+
+/**
+ * Marker object that safeHtml can splice into templates without escaping again.
+ */
+export type TrustedHtml = { readonly [trustedHtmlBrand]: true; toString(): string };
+
+type TrustedHtmlValue = TrustedHtml & { readonly [TRUSTED_HTML_VALUE]: string };
+
+/**
+ * Apply the internal {@link SanitizedHtml} brand to helper output.
+ *
+ * @internal
+ */
+export const toSanitizedHtml = (html: string): SanitizedHtml => html as SanitizedHtml;
+
+/**
+ * Mark a sanitized HTML string for verbatim splicing into safeHtml templates.
+ *
+ * @param html - HTML previously produced by sanitizeHtml, safeHtml, or another trusted bQuery helper
+ * @returns Trusted HTML marker object for safeHtml interpolations
+ *
+ * @example
+ * ```ts
+ * const badge = trusted(sanitizeHtml('<strong onclick="alert(1)">New</strong>'));
+ * const markup = safeHtml`<span>${badge}</span>`;
+ * ```
+ */
+export const trusted = (html: SanitizedHtml): TrustedHtml => {
+  const value = String(html);
+  return Object.freeze({
+    [trustedHtmlBrand]: true as const,
+    [TRUSTED_HTML_VALUE]: value,
+    toString: () => value,
+  });
+};
+
+/**
+ * Check whether a value is a trusted HTML marker created by trusted().
+ *
+ * @internal
+ */
+export const isTrustedHtml = (value: unknown): value is TrustedHtml => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    trustedHtmlBrand in value &&
+    TRUSTED_HTML_VALUE in value
+  );
+};
+
+/**
+ * Unwrap the raw HTML string stored inside a trusted HTML marker.
+ *
+ * @internal
+ */
+export const unwrapTrustedHtml = (value: TrustedHtml): string => {
+  return (value as TrustedHtmlValue)[TRUSTED_HTML_VALUE];
+};

package/src/ssr/hydrate.ts

@@ -0,0 +1,82 @@
+/**
+ * Hydration support for server-rendered DOM.
+ *
+ * Enables the client-side view system to reuse existing server-rendered DOM
+ * elements instead of re-rendering them, by attaching reactive bindings
+ * to the pre-existing DOM structure.
+ *
+ * @module bquery/ssr
+ */
+
+import type { BindingContext, MountOptions, View } from '../view/types';
+import { mount } from '../view/mount';
+
+/**
+ * Extended mount options that include hydration mode.
+ */
+export type HydrateMountOptions = MountOptions & {
+  /**
+   * When present, must be `true` so the mount operation reuses existing DOM elements
+   * instead of re-rendering them. Reactive bindings (effects) are
+   * still attached so the DOM updates reactively from that point on.
+   *
+   * @default true
+   */
+  hydrate?: true;
+};
+
+/**
+ * Mounts a reactive view with optional hydration support.
+ *
+ * When `hydrate: true` is set, the existing server-rendered DOM is preserved
+ * and reactive bindings are attached on top. The DOM is NOT re-rendered;
+ * instead, effects begin tracking signals so future changes update the DOM.
+ *
+ * This is the client-side counterpart to `renderToString()`. The typical flow:
+ * 1. Server: `renderToString(template, data)` → send HTML to client
+ * 2. Client: `hydrateMount('#app', reactiveContext, { hydrate: true })`
+ *
+ * Under the hood, `hydrateMount` simply delegates to the standard `mount()`
+ * function. The `mount()` function already processes existing DOM elements
+ * and attaches reactive effects to them — it does not clear/replace content.
+ * The `hydrate` flag is a semantic marker indicating developer intent and
+ * ensures the existing DOM structure is preserved.
+ *
+ * @param selector - CSS selector or Element to hydrate
+ * @param context - Binding context with signals, computed values, and functions
+ * @param options - Mount options with `hydrate: true`
+ * @returns The mounted View instance
+ *
+ * @example
+ * ```ts
+ * import { hydrateMount } from '@bquery/bquery/ssr';
+ * import { signal, computed } from '@bquery/bquery/reactive';
+ *
+ * // Server rendered:
+ * // <div id="app"><h1>Welcome</h1><p>Hello, World!</p></div>
+ *
+ * // Client hydration — attaches reactivity to existing DOM:
+ * const name = signal('World');
+ * const greeting = computed(() => `Hello, ${name.value}!`);
+ *
+ * const view = hydrateMount('#app', { name, greeting }, { hydrate: true });
+ *
+ * // Now updating `name.value` will reactively update the DOM
+ * name.value = 'Alice'; // <p> updates to "Hello, Alice!"
+ * ```
+ */
+export const hydrateMount = (
+  selector: string | Element,
+  context: BindingContext,
+  options: HydrateMountOptions = {}
+): View => {
+  const { hydrate = true, ...mountOptions } = options;
+
+  if (!hydrate) {
+    throw new Error('bQuery ssr: hydrateMount() requires { hydrate: true } when options are provided.');
+  }
+
+  // Hydration uses the standard mount which processes existing DOM
+  // and attaches reactive effects without clearing content.
+  return mount(selector, context, mountOptions);
+};