code wiki / (root) / nx_html_escape.nx
`nx_html_escape.nx` source

↩ module page · 287 lines · 9533 B
1// html_escape.nx -- HTML entity encoder + decoder.
2//
3// Escapes the five characters that are NEVER safe in HTML text
4// content or attribute values:
5//   <   &lt;
6//   >   &gt;
7//   &   &amp;
8//   "   &quot;
9//   '   &#39;        (apostrophe -- &apos; is XML only, not HTML4)
10//
11// This is the XSS-prevention primitive.  Any user-supplied text
12// rendered into an HTML template MUST go through this first.
13// Nishi-pages, every sovereign web handler, and any template
14// engine built on top all rely on correct escaping.
15//
16// Decoder handles the five named entities + numeric character
17// references (&#NN; and &#xHH;) bounded to the ASCII range.
18// Full Unicode entity decoding is out of scope (would need the
19// HTML5 named-character-reference table of ~2000 entries);
20// callers with that need should pre-process server-side into
21// one of the five safe forms.
22//
23// Invariants:
24//   HE1  Encoding output is never larger than 6x input (worst
25//        case: every byte is '>' which becomes "&gt;" = 4 bytes).
26//        Caller sizes the output buffer at src_len * 6 + 1.
27//   HE2  Encode is idempotent on already-safe bytes (ASCII alnum,
28//        space, punctuation except the five).
29//   HE3  Decode rejects malformed entities by leaving them
30//        literal (per WHATWG tolerant parsing); unknown named
31//        entities also pass through literal.
32//   HE4  Round trip: decode(encode(x)) == x for any ASCII x.
33
34// nx_safety_envelope:
35//   intended_use:       AUTO_APPLIED -- primitive-specific tuning queued
36//   sil_target:         SIL1
37//   evidence:           [bulk_applied_2026-05-16, see-file-comment-for-detail]
38//   verdict:            NOT_YET_EVALUATED
39
40import "nx_syscalls.nx"
41
42const HE_ERR_SHORT: i64 = -1
43
44// Is this ASCII byte "safe" (doesn't need escaping)?
45func he_is_safe(b: i64) -> i64 {
  if b == 0x3C { return 0 }       // '<'
  if b == 0x3E { return 0 }       // '>'
  if b == 0x26 { return 0 }       // '&'
  if b == 0x22 { return 0 }       // '"'
  if b == 0x27 { return 0 }       // "'"
  return 1
52}
53
54// Write literal bytes src[0..n] into out at offset.  Returns new
55// offset or HE_ERR_SHORT.
56func he_put(out: *u8, cap: i64, off: i64, src: *u8, n: i64) -> i64 {
  if off + n > cap { return HE_ERR_SHORT }
  var i: i64 = 0
  while i < n {
      out[off + i] = src[i]
      i = i + 1
  }
  return off + n
64}
65
66// Encode src[0..n] into out.  Returns bytes written or HE_ERR_SHORT.
67func html_escape(out: *u8, cap: i64, src: *u8, n: i64) -> i64 {
  var off: i64 = 0
  var i: i64 = 0
  while i < n {
      let b: i64 = src[i]
      if he_is_safe(b) == 1 {
          if off >= cap { return HE_ERR_SHORT }
          out[off] = b
          off = off + 1
      }
      if b == 0x3C {
          off = he_put(out, cap, off, "&lt;", 4)
          if off < 0 { return off }
      }
      if b == 0x3E {
          off = he_put(out, cap, off, "&gt;", 4)
          if off < 0 { return off }
      }
      if b == 0x26 {
          off = he_put(out, cap, off, "&amp;", 5)
          if off < 0 { return off }
      }
      if b == 0x22 {
          off = he_put(out, cap, off, "&quot;", 6)
          if off < 0 { return off }
      }
      if b == 0x27 {
          off = he_put(out, cap, off, "&#39;", 5)
          if off < 0 { return off }
      }
      i = i + 1
  }
  return off
100}
101
102// Helper: lowercase a hex digit.
103func he_hex_digit(b: i64) -> i64 {
  if b >= 0x30 {
      if b <= 0x39 { return b - 0x30 }
  }
  if b >= 0x61 {
      if b <= 0x66 { return b - 0x61 + 10 }
  }
  if b >= 0x41 {
      if b <= 0x46 { return b - 0x41 + 10 }
  }
  return -1
114}
115
116// Decode src[0..n] into out.  Returns bytes written.  Malformed
117// or unknown entities pass through literal per WHATWG tolerance.
118func html_unescape(out: *u8, cap: i64, src: *u8, n: i64) -> i64 {
  var off: i64 = 0
  var i: i64 = 0
  while i < n {
      if src[i] == 0x26 {
          // '&' -- possible entity start.
          // Find the terminating ';' within the next 8 bytes (any
          // longer is almost certainly not an entity).
          var end: i64 = -1
          var j: i64 = i + 1
          while j < n {
              if src[j] == 0x3B {
                  end = j
                  break
              }
              if j - i > 8 { break }
              j = j + 1
          }
          if end < 0 {
              // No ';' -- pass literal '&'.
              if off >= cap { return HE_ERR_SHORT }
              out[off] = src[i]
              off = off + 1
              i = i + 1
              continue
          }
144
          let entity_len: i64 = end - (i + 1)
          var decoded: i64 = -1
147
          // Numeric: &#NN; or &#xHH;
          if entity_len >= 2 {
              if src[i + 1] == 0x23 {
                  // '#'
                  var k: i64 = i + 2
                  var val: i64 = 0
                  var ok: i64 = 1
                  if src[k] == 0x78 {
                      // Hex
                      k = k + 1
                      while k < end {
                          let d: i64 = he_hex_digit(src[k])
                          if d < 0 { ok = 0; break }
                          val = val * 16 + d
                          k = k + 1
                      }
                  } else {
                      while k < end {
                          if src[k] < 0x30 { ok = 0; break }
                          if src[k] > 0x39 { ok = 0; break }
                          val = val * 10 + (src[k] - 0x30)
                          k = k + 1
                      }
                  }
                  if ok == 1 {
                      if val >= 0 {
                          if val <= 127 {
                              decoded = val
                          }
                      }
                  }
              }
          }
181
          // Named entities -- just the five we produced.
          if decoded < 0 {
              if entity_len == 2 {
                  if src[i+1] == 0x6C {         // 'l'
                      if src[i+2] == 0x74 {     // 't'
                          decoded = 0x3C
                      }
                  }
                  if src[i+1] == 0x67 {         // 'g'
                      if src[i+2] == 0x74 {     // 't'
                          decoded = 0x3E
                      }
                  }
              }
              if entity_len == 3 {
                  if src[i+1] == 0x61 {         // 'a'
                      if src[i+2] == 0x6D {     // 'm'
                          if src[i+3] == 0x70 { // 'p'
                              decoded = 0x26
                          }
                      }
                  }
              }
              if entity_len == 4 {
                  if src[i+1] == 0x71 {         // 'q'
                      if src[i+2] == 0x75 {     // 'u'
                          if src[i+3] == 0x6F { // 'o'
                              if src[i+4] == 0x74 { // 't'
                                  decoded = 0x22
                              }
                          }
                      }
                  }
                  if src[i+1] == 0x61 {         // 'a'
                      if src[i+2] == 0x70 {     // 'p'
                          if src[i+3] == 0x6F { // 'o'
                              if src[i+4] == 0x73 { // 's'
                                  decoded = 0x27
                              }
                          }
                      }
                  }
              }
          }
226
          if decoded >= 0 {
              if off >= cap { return HE_ERR_SHORT }
              out[off] = decoded
              off = off + 1
              i = end + 1
              continue
          }
          // Unknown entity: pass '&' literal; caller sees the rest
          // on the next loop iterations.
          if off >= cap { return HE_ERR_SHORT }
          out[off] = src[i]
          off = off + 1
          i = i + 1
          continue
      }
      if off >= cap { return HE_ERR_SHORT }
      out[off] = src[i]
      off = off + 1
      i = i + 1
  }
  return off
248}
249
250// Compile-only smoke: encode, decode, round-trip.
251func main() -> i64 {
  let out: *u8 = sys_mmap(128)
  let src: *u8 = "a<b&c>d\"e'f"
  let n: i64 = html_escape(out, 128, src, 11)
  // Expected: "a&lt;b&amp;c&gt;d&quot;e&#39;f"
  //  a + 4 + b + 5 + c + 4 + d + 6 + e + 5 + f = 28
  if n != 28 { return 1 }
  if out[0] != 0x61 { return 2 }       // 'a'
  if out[1] != 0x26 { return 3 }       // '&'
260
  // Round-trip.
  let out2: *u8 = sys_mmap(128)
  let n2: i64 = html_unescape(out2, 128, out, n)
  if n2 != 11 { return 4 }
  // Verify equality.
  var i: i64 = 0
  while i < 11 {
      if out2[i] != src[i] { return 5 }
      i = i + 1
  }
271
  // Numeric entity decode: "&#65;" -> "A".
  let n3: i64 = html_unescape(out2, 128, "&#65;", 5)
  if n3 != 1 { return 6 }
  if out2[0] != 0x41 { return 7 }
276
  // Hex entity: "&#x41;" -> "A".
  let n4: i64 = html_unescape(out2, 128, "&#x41;", 6)
  if n4 != 1 { return 8 }
  if out2[0] != 0x41 { return 9 }
281
  // Unknown entity: "&unknown;" passes literal.
  let n5: i64 = html_unescape(out2, 128, "&unknown;", 9)
  if n5 != 9 { return 10 }
285
  return 0
287}
nx_html_escape.nx source

`nx_html_escape.nx` source
