layerpro 3.4.0 → 4.0.1

package/SECURITY-HARDENING.md

@@ -0,0 +1,265 @@
+# Security Hardening Guide
+
+This document is a security reference for LayerPro maintainers and consumers.
+It documents every threat surface in the library, the defense-in-depth controls
+that mitigate it, and the residual risks that must be managed at the application
+level.
+
+---
+
+## 1. Threat Surface Summary
+
+| Threat | Vector | Mitigation | Residual Risk |
+|--------|--------|------------|---------------|
+| Global override side effects | `import 'layerpro/global'` rewrites `window.alert/confirm/prompt` | Globals are opt-in (not auto-applied) in 4.0; `layerpro.installGlobals()` for programmatic opt-in; native globals untouched by default | Consumers who import `layerpro/global` accept Promise-based globals |
+| XSS via popup body | `body: '<script>...'` or `buttons.confirm.text: '<img onerror=...>'` | `escapeHtml()` on all string bodies, button labels, names, icons | Does **not** protect against stored XSS from same-origin `source` (see §5) |
+| SSRF via `source` prop | `source: 'https://evil.example.com/...'` | Same-origin URL check (`url.origin !== window.location.origin`) + `fetch` mode `same-origin` | Same-origin XSS (server compromise or stored content on own domain) is still possible |
+| CSP bypass via inline `<style>` | CSS injected via `document.head.appendChild(<style>)` | Nonce auto-detection (`window.__layerproNonce`, `<style[nonce]>`, `<script[nonce]>`, `document.body.dataset.nonce`) | If no nonce is detectable, strict CSP will silently drop the stylesheet |
+| React DOM injection | `body: <Component />` executes arbitrary component code | React adapter loaded lazily via dynamic `import('layerpro/react')` - `react-dom` is never in the core bundle | Consumer is fully responsible for the React components they pass |
+| Prototype pollution | `setProps` iterates `Reflect.ownKeys` and reassigns descriptors | `setProps` only operates on the frozen `layerpro` object (non-enumerable, non-configurable, non-writable) | Low - `layerpro` is frozen in `index.ts:21` |
+
+---
+
+## 2. CSP (Content Security Policy) Support
+
+LayerPro supports three strategies for strict CSP environments, in order
+of preference:
+
+### Strategy A - Static stylesheet import (recommended)
+
+```js
+import 'layerpro/style.css'
+```
+
+This serves the CSS as a static file under `style-src 'self'`. No inline
+`<style>` element is created at all, so no nonce or hash is needed.
+
+In `package.json`:
+
+```json
+{
+  "exports": {
+    "./style.css": "./dist/index.css"
+  },
+  "files": ["dist/index.css", "..."]
+}
+```
+
+### Strategy B - Nonce auto-detection
+
+When the CSS-in-JS injection path is used (i.e., `import 'layerpro'` without
+the static stylesheet), the injected `<style>` element reads the nonce from:
+
+1. `window.__layerproNonce` - set explicitly via `layerpro.config({ nonce })`
+2. Any existing `<style>` or `<script>` element with a `nonce` attribute
+3. `document.body.dataset.nonce`
+
+This is implemented in `tsup.plugin.injectCss.ts`:
+
+```js
+const n = window.__layerproNonce
+  || window.layerpro?.nonce
+  || document.querySelector('style[nonce],script[nonce]')?.nonce
+  || document.body?.dataset?.nonce
+if (n) s.setAttribute('nonce', n)
+```
+
+Under a strict `style-src` policy with no detectable nonce, the stylesheet
+is **silently dropped** (the browser rejects it). Popups will render unstyled.
+
+### Strategy C - Explicit nonce configuration
+
+```js
+// Call BEFORE importing LayerPro so the nonce is set at injection time
+window.__layerproNonce = 'your-base64-nonce-here'
+// OR
+import 'layerpro'
+layerpro.config({ nonce: 'your-base64-nonce-here' })
+```
+
+> **Important**: `layerpro.config({ nonce })` must be called **before** the
+> CSS is first injected (i.e., before `import 'layerpro'`). If the module
+> was already imported, the nonce will not be retroactively applied to the
+> already-injected `<style>`.
+
+---
+
+## 3. Global Override Security Model
+
+### Risk (legacy 3.x pattern)
+
+In LayerPro 3.x, `import 'layerpro'` unconditionally replaced
+`window.alert`, `window.confirm`, `window.prompt`, and added `window.message`.
+The overridden versions were **callback-based and asynchronous** - they did not
+return native values:
+
+```js
+import 'layerpro'
+
+confirm('Are you sure?') // returns undefined, NOT a boolean
+if (confirm('Proceed?')) { ... } // ALWAYS falsey - silently breaks!
+```
+
+Any third-party code in your `node_modules` that relied on synchronous return
+values would break **silently** (no error, no warning, just the falsy branch).
+
+### 4.0 Mitigation: opt-in globals
+
+LayerPro 4.0 **removes the auto-override**. The main entry (`import 'layerpro'`)
+no longer touches browser globals at all. To opt in to global overrides, use:
+
+```js
+import 'layerpro/global'   // explicitly overrides window.alert/confirm/prompt/message
+
+const confirmed = await confirm('Are you sure?')  // Promise<boolean>
+```
+
+Or programmatically:
+
+```js
+import 'layerpro'
+layerpro.installGlobals()  // same effect, explicit call
+```
+
+### Recommendation
+
+In 4.0, simply **do not import `layerpro/global`** if you need the native
+synchronous `alert`/`confirm`/`prompt`. Use the Promise-based methods on the
+`layerpro` object directly instead:
+
+```js
+import 'layerpro'
+
+const confirmed = await layerpro.confirm('Are you sure?')
+```
+
+---
+
+## 4. XSS Prevention
+
+All user-provided string content is escaped via `escapeHtml()` (regex-based
+replacement of `& < > " '` → HTML entities) before being inserted into the DOM:
+
+- **Popup body (text/HTML strings)**: `core/genLayer.ts:escapeHtml()`
+- **Button labels**: `core/genLayer.ts:escapeHtml()` (confirm/cancel text)
+- **Popup name/icon**: `core/genLayer.ts:escapeHtml()`
+- **`alert()`/`confirm()`/`prompt()`/`message()` bodies**: `core/message.ts:escapeHtml()`
+
+This is **not** a sanitization library - it does not allow any HTML through.
+Raw HTML rendering is deliberately not supported for string bodies. If you
+need raw HTML, use the React adapter with a component that explicitly
+renders `dangerouslySetInnerHTML`.
+
+---
+
+## 5. `source` Prop (Remote Content Loading)
+
+The `source` prop fetches same-origin HTML and injects it into the popup body.
+
+### Same-origin enforcement
+
+- `core/genLayer.ts:loadSource()` constructs a `URL` and checks
+  `url.origin !== window.location.origin`
+- The `fetch()` call also uses `mode: 'same-origin'` as a second layer
+- The same-origin guard is the **primary defense** against SSRF
+
+### What is rendered
+
+Remote HTML is injected as **raw, unescaped HTML** (as of 3.4.1 - previously
+it was double-escaped, rendering all tags as visible text). This means:
+
+- `<p>Hello</p>` renders as a real paragraph (not visible tags)
+- `<script>` tags in the response are **executed** when the HTML is parsed
+- Event handlers (`onclick="..."`) in the response are **activated**
+
+### Consumer responsibility
+
+The same-origin guard protects against cross-origin SSRF, but **not** against
+same-origin XSS. If an attacker can inject malicious HTML into an endpoint
+on your own domain (stored XSS), the `source` prop will render it.
+
+**Always sanitize server-side content before serving it as a `source` URL.**
+
+### Abort safety
+
+An `AbortController` is associated with each `source` fetch and is aborted
+when the popup closes (`layerpro.popup.abortSource(id)`), preventing
+callbacks from targeting a destroyed layer.
+
+---
+
+## 6. React Adapter Isolation
+
+The React adapter (`layerpro/react`) is loaded via dynamic `import('layerpro/react')`
+only when a React element is passed as the `body` prop:
+
+- `react-dom` is **never** imported in the core bundle (verified by `verify-fixes.mjs`)
+- The adapter is a separate entry point declared in `package.json` `exports`
+- `reattach` is bundled **inside** the adapter, not as a separate dependency
+- The adapter externalizes only `react` and `react-dom` as peer dependencies
+
+This ensures consumers who don't use React bodies never load `react-dom`.
+
+### Risk
+
+The `import('layerpro/react')` bare-specifier requires a bundler that
+understands the `exports` field in `package.json`. In plain `<script type="module">`
+environments or old bundlers, this dynamic import will fail. The failure is
+caught and logged:
+
+```js
+import('layerpro/react').then(adapter => { ... }).catch(error => {
+  console.error('LayerPro Error: React adapter failed to load.')
+  console.debug(error)
+})
+```
+
+No error is surfaced to the user - the popup renders with an empty body.
+
+---
+
+## 7. Accessibility & Security Interaction
+
+LayerPro renders popups with the following ARIA attributes (as of 3.4.1):
+
+- `role="dialog"` on the popup window container
+- `aria-modal="true"` on modal popups
+- `aria-label` (from `props.name`) or `aria-labelledby` if a named title exists
+- `aria-hidden="true"` on all `<body>` children except `#popup` while a modal is open
+- `tabindex="-1"` on the popup window (focusable via script)
+
+### Focus management
+
+- The currently focused element is saved when a popup opens
+- Focus is moved into the popup via `requestAnimationFrame` + `.focus()`
+- A `Tab` key listener traps focus within the popup container (cycles to
+  first/last focusable element)
+- On close, focus is restored to the previously active element and
+  `aria-hidden` is removed from page content
+
+### Limitations
+
+- This is a **lightweight** focus trap (Tab key only). It does not handle
+  screen reader virtual cursor navigation, nested modals, or `inert` polyfill.
+- `aria-hidden` on page content is not equivalent to `inert` - focus can
+  still technically reach page elements via direct `.focus()` calls from
+  application code.
+
+---
+
+## 8. Build-time Security
+
+- `tsup.plugin.injectCss.ts` injects CSS at build time with nonce support
+- `tsup.plugin.copyStatic.ts` rewrites the dist `package.json` exports map
+- `tsup.plugin.types.ts` generates `react.d.ts` and patches `index.d.ts`
+  with a `dphelper` reference (tsc strips `/// <reference>` from `.ts` files)
+- `react.d.ts` is included in the npm `files` array so `import layerpro/react`
+  resolves types under `moduleResolution: bundler`
+
+---
+
+## 9. Reporting
+
+If you have a potential security vulnerability to report, please email
+[@passariello](https://github.com/passariello) or see
+<https://dario.passariello.ca/contact/>.

package/SECURITY.md

@@ -1,3 +1,11 @@
 # Security
 
 Please email [@passariello](https://github.com/passariello) or see <https://dario.passariello.ca/contact/> if you have a potential security vulnerability to report.
+
+## Source feature (same-origin fetch)
+
+The `source` prop fetches HTML from a same-origin URL and renders it as-is.
+The same-origin guard prevents SSRF to other hosts, but the fetched markup is
+NOT sanitized by LayerPro. Any same-origin endpoint used as a `source` must
+sanitize its output server-side. Consumers needing client-side sanitization
+should pass a React element in `body` instead.