hyper-html-api 0.8.1 → 0.9.0

package/src/engine/write-policy.js

@@ -0,0 +1,136 @@
+import { POLICY_TOKENS } from '../lib/region-capabilities.js'
+import { WriteRefused } from './errors.js'
+
+export const WRITE_POLICY = Object.freeze({
+  refusedRuleForms: ['innerHTML', 'outerHTML'],
+  refusedTargets: ['script', 'style', 'template', 'noscript', 'iframe', 'object', 'embed', 'xmp', 'plaintext', 'noembed', 'noframes', 'meta', 'link', 'base', 'animate', 'set', 'animatemotion', 'animatetransform'],
+  refusedAttributes: [
+    'style', 'srcdoc', 'is', 'http-equiv', 'sandbox', 'allow', 'nonce', 'integrity', 'charset',
+    'htmlclaytoken', 'htmlclayid', 'data-rules-name', 'data-rules-version', 'clay', 'contenteditable',
+    ...POLICY_TOKENS,
+  ],
+  refusedAttributePrefixes: ['on'],
+  urlAttributes: ['href', 'src', 'srcset', 'action', 'formaction', 'poster', 'cite', 'data', 'ping', 'background', 'longdesc', 'usemap', 'xlink:href', 'manifest', 'codebase', 'icon'],
+  refusedSchemes: ['javascript', 'vbscript', 'data'],
+})
+
+const TEXT_PROPS = new Set(['textContent', 'innerText'])
+
+export function urlScheme(value) {
+  const cleaned = String(value).replace(/^[\u0000- ]+|[\u0000- ]+$/g, '').replace(/[\t\n\r]/g, '')
+  const m = cleaned.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/)
+  return m ? m[1].toLowerCase() : null
+}
+
+const VALID_ATTR_NAME = /^[^\t\n\f\r "'>/=\u0000-\u001f\u007f]+$/
+
+export function checkAttribute(name, value, policy = WRITE_POLICY) {
+  if (!VALID_ATTR_NAME.test(String(name))) return `attribute name ${JSON.stringify(String(name))} is not valid`
+  const lower = String(name).toLowerCase()
+  if (policy.refusedAttributePrefixes.some((p) => lower.startsWith(p))) return `attribute "${lower}" can run script`
+  if (policy.refusedAttributes.includes(lower)) return `attribute "${lower}" is not content`
+  if (policy.urlAttributes.includes(lower) && value != null) {
+    const urls = lower === 'srcset'
+      ? String(value).split(',').map((c) => c.trim().split(/\s+/)[0]).filter(Boolean)
+      : [String(value)]
+    for (const url of urls) {
+      const scheme = urlScheme(url)
+      if (scheme && policy.refusedSchemes.includes(scheme)) return `"${scheme}:" URLs are not allowed in "${lower}"`
+    }
+  }
+  return null
+}
+
+function tagOf(adapter, node) {
+  const t = adapter.prop(node, 'tagName')
+  return t ? String(t).toLowerCase() : ''
+}
+
+function describe(adapter, node) {
+  const tag = tagOf(adapter, node) || 'node'
+  const id = adapter.attr(node, 'id')
+  return id ? `<${tag}#${id}>` : `<${tag}>`
+}
+
+function refusedAncestor(adapter, node, policy) {
+  let cur = node
+  while (cur) {
+    const tag = tagOf(adapter, cur)
+    if (tag && policy.refusedTargets.includes(tag)) return tag
+    cur = adapter.parent(cur)
+  }
+  return null
+}
+
+function holdsRulesTag(adapter, node) {
+  return adapter.find(node, 'script[data-rules-name]', { includeRulesTag: true, templateAttr: null }).length > 0
+}
+
+function isOrHoldsRulesTag(adapter, node) {
+  if (tagOf(adapter, node) === 'script' && adapter.attr(node, 'data-rules-name') != null) return true
+  return holdsRulesTag(adapter, node)
+}
+
+// Wraps an adapter so every write is checked against the policy first. A write
+// that breaks it is skipped and recorded; call assertClean() after apply() to
+// throw one WriteRefused listing every violation.
+export function guardAdapter(adapter, policy = WRITE_POLICY) {
+  const refusals = []
+  const refuse = (node, reason) => {
+    refusals.push({ target: describe(adapter, node), reason })
+    return false
+  }
+  const allowTarget = (node) => {
+    const bad = refusedAncestor(adapter, node, policy)
+    return bad ? refuse(node, `inside <${bad}>, which is not content`) : true
+  }
+  const allowText = (node) => {
+    if (!allowTarget(node)) return false
+    if (holdsRulesTag(adapter, node)) return refuse(node, 'a text write here would delete the data rules tag')
+    return true
+  }
+  const allowAttr = (node, name, value) => {
+    if (!allowTarget(node)) return false
+    const reason = checkAttribute(name, value, policy)
+    return reason ? refuse(node, reason) : true
+  }
+
+  const guarded = {
+    ...adapter,
+    text(node, value) {
+      if (value === undefined) return adapter.text(node)
+      if (allowText(node)) adapter.text(node, value)
+    },
+    attr(node, name, value) {
+      if (value === undefined) return adapter.attr(node, name)
+      if (allowAttr(node, name, value)) adapter.attr(node, name, value)
+    },
+    prop(node, name, value) {
+      if (value === undefined) return adapter.prop(node, name)
+      if (policy.refusedRuleForms.includes(name)) return refuse(node, `"@${name}" writes HTML, only text is allowed`)
+      if (TEXT_PROPS.has(name)) {
+        if (allowText(node)) adapter.prop(node, name, value)
+        return
+      }
+      const attrName = name === 'className' ? 'class' : name
+      if (allowAttr(node, attrName, value)) adapter.prop(node, name, value)
+    },
+    remove(node) {
+      if (isOrHoldsRulesTag(adapter, node)) {
+        refuse(node, 'removing this would delete the data rules tag')
+        return
+      }
+      adapter.remove(node)
+    },
+    replaceWith(node, html) {
+      if (html === adapter.prop(node, 'outerHTML')) return node
+      refuse(node, '"@outerHTML" writes HTML, only text is allowed')
+      return node
+    },
+    refusals,
+    assertClean() {
+      if (refusals.length) throw new WriteRefused(refusals.slice())
+    },
+  }
+  return guarded
+}

package/src/write.js

@@ -0,0 +1,29 @@
+import cheerioAdapter from './adapters/cheerio.js'
+import { apply } from './engine/apply.js'
+import { findRulesIn } from './engine/rules-tag.js'
+import { guardAdapter } from './engine/write-policy.js'
+import { planWrite } from './engine/write-plan.js'
+import { trackAdapter, spliceDocument } from './engine/splice.js'
+import { NoRulesTag, WriteRejected } from './engine/errors.js'
+
+// Applies a JSON body to a document's source through the document's own rules
+// tag, under the content-only policy. `load` is cheerio.load, passed in so this
+// package keeps cheerio out of its browser bundles. Returns the new source and
+// whether anything changed. Throws NoRulesTag, WriteRejected, WriteRefused,
+// ShapeMismatch or EmptyListInsert, always before producing any output.
+export function writeDocument(load, src, data, { token = 'api' } = {}) {
+  const $ = load(src, { sourceCodeLocationInfo: true })
+  const root = $.root()
+  const found = findRulesIn(cheerioAdapter, root, token)
+  if (!found) throw new NoRulesTag(token)
+  const { rules } = found
+  const plan = planWrite(cheerioAdapter, root, rules, data)
+  if (plan.unknownKeys.length || plan.unmatched.length) throw new WriteRejected(plan.unknownKeys, plan.unmatched)
+  const tracker = trackAdapter(cheerioAdapter)
+  const guarded = guardAdapter(tracker)
+  apply(guarded, root, rules, data, { templateAttr: 'cms-template' })
+  guarded.assertClean()
+  if (tracker.dirty.size === 0) return { html: src, changed: false, spliced: true }
+  const { html, spliced } = spliceDocument(load, src, $, tracker)
+  return { html, changed: html !== src, spliced }
+}

package/conformance/cases/props-type-is-node-type.expected.json

@@ -1,5 +0,0 @@
-{
-  "input": "tag",
-  "script": "script",
-  "style": "style"
-}

package/conformance/cases/props-type-is-node-type.meta

@@ -1,11 +0,0 @@
-tier: 3
-face: query
-expect: ok
-skip: htmlclay=ships @type fixed; fixed behavior asserted in htmlclay dataapi/props_test.go
-note: @type is NOT the type attribute. `type` is on the DOM property whitelist, and domhandler
-note: nodes already carry a `type` field naming the node kind, so cheerio's prop() returns that
-note: instead: "tag" for a normal element, "script" for a script, "style" for a style. Three
-note: values, none of them the author's type="text".
-note: DIVERGENCE, direction JS-only. This case pins the WART so an upstream fix gets noticed.
-note: htmlclay deliberately does not reproduce it and returns the type attribute, because that API
-note: has no existing htmlclay users and preserving the bug would buy nothing.