Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
20.1 KB
Raw Blame
/**
 * The text an Office package (DOCX, XLSX, PPTX) holds, read from the bytes
 * that are delivered rather than predicted from the arguments that produced
 * them: a generator may write a value in a form its arguments never spelled,
 * as a sheet stores the text "3,141,592,653" as the number 3141592653. Numbers
 * are also read as they are shown: a cell's number format or a chart's label
 * format turns a stored 46024 into "2026-01-02", and 3141592653 into
 * "3,141,592,653" (shownNumbers.ts).
 */
import * as zlib from 'zlib'
import {
  builtinFormatCode,
  isModelledFormatCode,
  isShortDateId,
  renderCount,
  shownForms,
  showsIntegerAsStored,
} from './shownNumbers'

/** Bounds on one inspection; a package past them is reported as unreadable. */
export const OFFICE_PACKAGE_LIMITS = {
  /** Entries in one package; an embedded package counts its own. */
  maxEntries: 4096,
  /** Bytes inflated across the package and every package inside it. */
  maxInflatedBytes: 64 * 1024 * 1024,
  /** Packages inside packages, such as the workbook behind a deck's chart. */
  maxDepth: 2,
  /**
   * Numbers rendered through their format across the package and every
   * package inside it; a larger package is not attached.
   */
  maxShownValues: 250_000,
  /**
   * Renderings those numbers take (shownNumbers.renderCount): a built-in
   * short date is rendered in dozens of patterns. About 0.6 s at this bound.
   */
  maxShownRenders: 500_000,
}

export type OfficePackageLimits = typeof OFFICE_PACKAGE_LIMITS

const END_OF_CENTRAL_DIRECTORY = 0x06054b50
const CENTRAL_DIRECTORY_ENTRY = 0x02014b50
const LOCAL_FILE_HEADER = 0x04034b50
const TEXT_PART = /\.(?:xml|rels|vml)$/i
const EMBEDDED_PACKAGE = /\.(?:docx|docm|xlsx|xlsm|pptx|pptm)$/i
const CHARACTER_REFERENCE = /&(?:#(\d{1,7})|#[xX]([0-9a-fA-F]{1,6})|(lt|gt|amp|quot|apos));/g
const NAMED_REFERENCES: Record<string, string> = {
  lt: '<',
  gt: '>',
  amp: '&',
  quot: '"',
  apos: "'",
}

interface ZipEntry {
  name: string
  flags: number
  method: number
  compressedSize: number
  localHeaderOffset: number
}

/**
 * Whether any text in the package satisfies `matches`: per XML part, its text
 * nodes run together, so a value split across runs or cells reads whole, and
 * each attribute value on its own, with character references decoded; then
 * each number a sheet cell or a chart holds, in every form it may be shown,
 * passed to `matchesShown` as shown (match numbers with shownNumbers.showsNumber);
 * null skips them.
 * Embedded packages are read too. Null when the bytes are not a package this
 * reader can read within `limits`, or show a number in a way it does not model
 * (a formula, a system date format, the 1904 date system); the caller then
 * treats the file as unsafe.
 */
export function officePackageHasText(
  buffer: Buffer,
  matches: (text: string) => boolean,
  limits: OfficePackageLimits = OFFICE_PACKAGE_LIMITS,
  matchesShown: ((shown: string) => boolean) | null = matches
): boolean | null {
  return searchPackage(
    buffer,
    matches,
    limits,
    { inflated: 0, shownValues: 0, shownRenders: 0 },
    0,
    matchesShown ?? undefined
  )
}

/**
 * Every text the scan above reads in the package, numbers as stored: per XML
 * part, its text nodes run together, and each attribute value. Null when the
 * package cannot be read within the limits.
 */
export function officePackageTexts(
  buffer: Buffer,
  limits: OfficePackageLimits = OFFICE_PACKAGE_LIMITS
): string[] | null {
  const texts: string[] = []
  const read = searchPackage(
    buffer,
    text => {
      texts.push(text)
      return false
    },
    { ...limits, maxShownValues: 0 },
    { inflated: 0, shownValues: 0, shownRenders: 0 },
    0,
    undefined
  )
  return read === null ? null : texts
}

interface ScanBudget {
  inflated: number
  shownValues: number
  shownRenders: number
}

function searchPackage(
  buffer: Buffer,
  matches: (text: string) => boolean,
  limits: OfficePackageLimits,
  budget: ScanBudget,
  depth: number,
  matchesShown: ((shown: string) => boolean) | undefined
): boolean | null {
  const entries = centralDirectory(buffer, limits.maxEntries)
  if (!entries) return null
  const parts = new Map<string, string>()
  for (const entry of entries) {
    const embedded = EMBEDDED_PACKAGE.test(entry.name)
    if (!embedded && !TEXT_PART.test(entry.name)) continue
    if (embedded && depth >= limits.maxDepth) return null
    const data = entryData(buffer, entry, limits.maxInflatedBytes - budget.inflated)
    if (!data) return null
    budget.inflated += data.length
    let found: boolean | null
    if (embedded) {
      found = searchPackage(data, matches, limits, budget, depth + 1, matchesShown)
    } else {
      const xml = data.toString('utf8')
      parts.set(entry.name, xml)
      found = xmlHasText(xml, matches)
    }
    if (found !== false) return found
  }
  return matchesShown ? numbersShow(parts, matchesShown, limits, budget) : false
}

/** Sections whose content is read as it stands, up to their end mark. */
const RAW_SECTIONS: ReadonlyArray<readonly [start: string, end: string]> = [
  ['<![CDATA[', ']]>'],
  ['<!--', '-->'],
]

/**
 * Whether one XML part's text satisfies `matches`, read in a single pass: its
 * text nodes, character data and comments run together, and each quoted
 * attribute value on its own, so a '>' a value holds does not end its tag. A
 * value or section left open runs to the end of the part, which is read too.
 */
function xmlHasText(xml: string, matches: (text: string) => boolean): boolean {
  const text: string[] = []
  let at = 0
  while (at < xml.length) {
    const open = xml.indexOf('<', at)
    if (open < 0) {
      text.push(xml.slice(at))
      break
    }
    text.push(xml.slice(at, open))
    const raw = RAW_SECTIONS.find(([start]) => xml.startsWith(start, open))
    if (raw) {
      const close = xml.indexOf(raw[1], open + raw[0].length)
      const end = close < 0 ? xml.length : close
      text.push(xml.slice(open + raw[0].length, end))
      at = end + raw[1].length
      continue
    }
    let i = open + 1
    while (i < xml.length && xml[i] !== '>') {
      const quote = xml[i]
      if (quote !== '"' && quote !== "'") {
        i++
        continue
      }
      const close = xml.indexOf(quote, i + 1)
      const end = close < 0 ? xml.length : close
      if (matches(decodeReferences(xml.slice(i + 1, end)))) return true
      i = end + 1
    }
    at = i + 1
  }
  return matches(decodeReferences(text.join('')))
}

function decodeReferences(text: string): string {
  return text.replace(CHARACTER_REFERENCE, (reference, decimal, hex, name) => {
    if (name) return NAMED_REFERENCES[name]
    const codePoint = decimal ? Number(decimal) : parseInt(hex, 16)
    return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : reference
  })
}

/** The entries the central directory lists; null for anything but a plain zip. */
function centralDirectory(buffer: Buffer, maxEntries: number): ZipEntry[] | null {
  // The end record is the last 22 bytes, followed by a comment of at most 65535.
  let end = -1
  const earliest = Math.max(0, buffer.length - 22 - 0xffff)
  for (let at = buffer.length - 22; at >= earliest; at--) {
    if (buffer.readUInt32LE(at) === END_OF_CENTRAL_DIRECTORY) {
      end = at
      break
    }
  }
  if (end < 0) return null
  const count = buffer.readUInt16LE(end + 10)
  const size = buffer.readUInt32LE(end + 12)
  let at = buffer.readUInt32LE(end + 16)
  // ZIP64 markers: the generators never write one, so it is not read here.
  if (count === 0xffff || size === 0xffffffff || at === 0xffffffff) return null
  if (count > maxEntries || at + size > end) return null
  const entries: ZipEntry[] = []
  for (let n = 0; n < count; n++) {
    if (at + 46 > end || buffer.readUInt32LE(at) !== CENTRAL_DIRECTORY_ENTRY) return null
    const nameLength = buffer.readUInt16LE(at + 28)
    const next = at + 46 + nameLength + buffer.readUInt16LE(at + 30) + buffer.readUInt16LE(at + 32)
    if (next > end) return null
    entries.push({
      name: buffer.toString('utf8', at + 46, at + 46 + nameLength),
      flags: buffer.readUInt16LE(at + 8),
      method: buffer.readUInt16LE(at + 10),
      // From the central directory: writers that stream (ExcelJS) leave the
      // local header sizes zero.
      compressedSize: buffer.readUInt32LE(at + 20),
      localHeaderOffset: buffer.readUInt32LE(at + 42),
    })
    at = next
  }
  return entries
}

/** The entry's bytes, inflated within `remaining`; null when they cannot be read. */
function entryData(buffer: Buffer, entry: ZipEntry, remaining: number): Buffer | null {
  // Bit 0 marks an encrypted entry.
  if (entry.flags & 1 || remaining <= 0) return null
  const local = entry.localHeaderOffset
  if (local + 30 > buffer.length || buffer.readUInt32LE(local) !== LOCAL_FILE_HEADER) return null
  const start = local + 30 + buffer.readUInt16LE(local + 26) + buffer.readUInt16LE(local + 28)
  const stop = start + entry.compressedSize
  if (stop > buffer.length) return null
  const data = buffer.subarray(start, stop)
  if (entry.method === 0) return data.length <= remaining ? data : null
  if (entry.method !== 8) return null
  try {
    return zlib.inflateRawSync(data, { maxOutputLength: remaining })
  } catch {
    return null
  }
}

// ─── Numbers as they are shown ───────────────────────────────────────

const SHEET_PART = /^xl\/worksheets\/[^/]+\.xml$/
const CHART_PART = /(?:^|\/)charts\/chart[^/]*\.xml$/

/**
 * Whether a number a sheet or a chart of this package shows satisfies
 * `matches`. Null for a way of showing a number this reader does not model, or
 * when the package holds more numbers than the limits allow.
 */
function numbersShow(
  parts: Map<string, string>,
  matches: (text: string) => boolean,
  limits: OfficePackageLimits,
  budget: ScanBudget
): boolean | null {
  const render = (value: number, code: string, shortDate: boolean): boolean | null => {
    if (!shortDate && showsIntegerAsStored(code, value)) return false
    if (++budget.shownValues > limits.maxShownValues) return null
    budget.shownRenders += renderCount(code, shortDate)
    if (budget.shownRenders > limits.maxShownRenders) return null
    return shownForms(value, code, shortDate).some(matches)
  }
  const sheets = [...parts.keys()].filter(name => SHEET_PART.test(name))
  if (sheets.length > 0) {
    // A workbook in the 1904 date system shows every serial four years later.
    if (/\bdate1904\s*=\s*["'](?:1|true)["']/.test(parts.get('xl/workbook.xml') ?? '')) return null
    const styles = readStyles(parts.get('xl/styles.xml'))
    if (!styles) return null
    for (const name of sheets) {
      const found = sheetShows(parts.get(name)!, styles, render)
      if (found !== false) return found
    }
  }
  for (const name of [...parts.keys()].filter(part => CHART_PART.test(part))) {
    const found = chartShows(parts.get(name)!, render)
    if (found !== false) return found
  }
  return false
}

interface CellFormat {
  code: string
  /** A built-in short date, shown in the viewer's own date pattern. */
  shortDate: boolean
}

interface StyleFormats {
  /** The format of cell style `index`; null when it is not modelled. */
  format(index: number): CellFormat | null
}

/** The number format of each cell style; null when a conditional format sets one. */
function readStyles(xml: string | undefined): StyleFormats | null {
  const custom = new Map<number, string>()
  const xfFormats: number[] = []
  let inCellXfs = false
  let inDxf = false
  let dxfFormat = false
  if (xml) {
    walkXml(xml, {
      start(name, attrs, selfClosing) {
        const local = localName(name)
        if (local === 'cellXfs') inCellXfs = !selfClosing
        else if (local === 'dxf') inDxf = !selfClosing
        else if (local === 'numFmt') {
          if (inDxf) dxfFormat = true
          else if (attrs.numFmtId !== undefined && attrs.formatCode !== undefined) {
            custom.set(Number(attrs.numFmtId), attrs.formatCode)
          }
        } else if (local === 'xf' && inCellXfs) {
          xfFormats.push(Number(attrs.numFmtId ?? 0))
        }
      },
      end(name) {
        const local = localName(name)
        if (local === 'cellXfs') inCellXfs = false
        else if (local === 'dxf') inDxf = false
      },
    })
  }
  if (dxfFormat) return null
  const known = new Map<number, CellFormat | null>()
  return {
    format(index) {
      const cached = known.get(index)
      if (cached !== undefined) return cached
      const id = xfFormats[index] ?? (index === 0 ? 0 : undefined)
      const code = id === undefined ? undefined : (custom.get(id) ?? builtinFormatCode(id))
      const format =
        id !== undefined && code !== undefined && isModelledFormatCode(code)
          ? { code, shortDate: !custom.has(id) && isShortDateId(id) }
          : null
      known.set(index, format)
      return format
    },
  }
}

type Render = (value: number, code: string, shortDate: boolean) => boolean | null

/** Whether a number cell of the sheet shows text `render` matches; null for a formula. */
function sheetShows(xml: string, styles: StyleFormats, render: Render): boolean | null {
  let cell: { style: number; type?: string; value: string; inValue: boolean } | undefined
  let result: boolean | null = false
  walkXml(xml, {
    start(name, attrs, selfClosing) {
      const local = localName(name)
      if (local === 'c') {
        cell = selfClosing
          ? undefined
          : { style: Number(attrs.s ?? 0), type: attrs.t, value: '', inValue: false }
      } else if (cell && local === 'v') {
        cell.inValue = !selfClosing
      } else if (cell && local === 'f') {
        // A formula shows a result the package does not hold.
        result = null
        return true
      }
      return false
    },
    text(text) {
      if (cell?.inValue) cell.value += text
      return false
    },
    end(name) {
      const local = localName(name)
      if (local === 'v' && cell) cell.inValue = false
      else if (local === 'c' && cell) {
        const shown = cellShows(cell, styles, render)
        cell = undefined
        if (shown !== false) {
          result = shown
          return true
        }
      }
      return false
    },
  })
  return result
}

function cellShows(
  cell: { style: number; type?: string; value: string },
  styles: StyleFormats,
  render: Render
): boolean | null {
  // An ISO date cell is shown through a format this reader does not apply.
  if (cell.type === 'd') return null
  // Text, booleans and errors are read as text.
  if (cell.type !== undefined && cell.type !== 'n') return false
  const stored = cell.value.trim()
  const value = Number(stored)
  if (!stored || !Number.isFinite(value)) return false
  const format = styles.format(cell.style)
  if (!format) return null
  return render(value, format.code, format.shortDate)
}

/**
 * Whether a number a chart caches shows text `render` matches. Each value is
 * rendered with every format code of the chart part (series caches, data and
 * axis labels), so the check covers what a label may show.
 */
function chartShows(xml: string, render: Render): boolean | null {
  const codes = new Set<string>(['General'])
  const values: number[] = []
  let cacheDepth = 0
  let value: string | undefined
  let formatCode: string | undefined
  walkXml(xml, {
    start(name, attrs, selfClosing) {
      const local = localName(name)
      if (local === 'numCache' || local === 'numLit') {
        if (!selfClosing) cacheDepth++
      } else if ((local === 'numFmt' || local === 'pt') && attrs.formatCode !== undefined) {
        codes.add(attrs.formatCode)
      } else if (local === 'formatCode' && !selfClosing) {
        formatCode = ''
      } else if (local === 'v' && cacheDepth > 0 && !selfClosing) {
        value = ''
      }
      return false
    },
    text(text) {
      if (value !== undefined) value += text
      if (formatCode !== undefined) formatCode += text
      return false
    },
    end(name) {
      const local = localName(name)
      if (local === 'numCache' || local === 'numLit') cacheDepth = Math.max(0, cacheDepth - 1)
      else if (local === 'formatCode' && formatCode !== undefined) {
        codes.add(formatCode)
        formatCode = undefined
      } else if (local === 'v' && value !== undefined) {
        const number = Number(value.trim())
        if (value.trim() && Number.isFinite(number)) values.push(number)
        value = undefined
      }
      return false
    },
  })
  for (const code of codes) if (!isModelledFormatCode(code)) return null
  for (const number of values) {
    for (const code of codes) {
      const found = render(number, code, false)
      if (found !== false) return found
    }
  }
  return false
}

function localName(name: string): string {
  const colon = name.indexOf(':')
  return colon < 0 ? name : name.slice(colon + 1)
}

interface XmlVisitor {
  /** Each returns true to stop the walk. */
  start?(name: string, attrs: Record<string, string>, selfClosing: boolean): boolean | void
  end?(name: string): boolean | void
  text?(text: string): boolean | void
}

/** Space, tab, newline and carriage return, the whitespace XML allows between attributes. */
function isSpace(code: number): boolean {
  return code === 32 || code === 9 || code === 10 || code === 13
}

/** Text with its character references decoded; most text has none. */
function decodedText(text: string): string {
  return text.includes('&') ? decodeReferences(text) : text
}

/**
 * Walks the elements of one XML part in a single pass, tolerating malformed
 * input: text and character data go to `text` with references decoded,
 * comments, declarations and processing instructions are skipped, and each
 * quoted attribute value is read whole, so a '>' it holds does not end its tag.
 */
function walkXml(xml: string, visit: XmlVisitor): void {
  const LT = 60 // <
  const GT = 62 // >
  const SLASH = 47 // /
  const EQ = 61 // =
  let at = 0
  while (at < xml.length) {
    const open = xml.indexOf('<', at)
    if (open < 0) {
      visit.text?.(decodedText(xml.slice(at)))
      return
    }
    if (open > at && visit.text?.(decodedText(xml.slice(at, open)))) return
    if (xml.startsWith('<![CDATA[', open)) {
      const close = xml.indexOf(']]>', open + 9)
      const end = close < 0 ? xml.length : close
      if (visit.text?.(xml.slice(open + 9, end))) return
      at = end + 3
      continue
    }
    if (xml.startsWith('<!--', open)) {
      const close = xml.indexOf('-->', open + 4)
      at = close < 0 ? xml.length : close + 3
      continue
    }
    const second = xml.charCodeAt(open + 1)
    if (second === 63 || second === 33) {
      // <? ... ?> and <! ... >
      const close = xml.indexOf('>', open)
      at = close < 0 ? xml.length : close + 1
      continue
    }
    const closing = second === SLASH
    let i = open + (closing ? 2 : 1)
    const nameStart = i
    for (let c = xml.charCodeAt(i); i < xml.length; c = xml.charCodeAt(++i)) {
      if (isSpace(c) || c === SLASH || c === GT || c === LT) break
    }
    const name = xml.slice(nameStart, i)
    // No prototype: an attribute named "__proto__" stays a plain key.
    const attrs: Record<string, string> = Object.create(null)
    let selfClosing = false
    while (i < xml.length) {
      const c = xml.charCodeAt(i)
      if (c === GT) break
      if (c === SLASH) {
        selfClosing = true
        i++
        continue
      }
      if (isSpace(c)) {
        i++
        continue
      }
      const attrStart = i
      for (let d = xml.charCodeAt(i); i < xml.length; d = xml.charCodeAt(++i)) {
        if (isSpace(d) || d === EQ || d === SLASH || d === GT) break
      }
      const attrName = xml.slice(attrStart, i)
      while (i < xml.length && isSpace(xml.charCodeAt(i))) i++
      if (xml.charCodeAt(i) !== EQ) continue
      i++
      while (i < xml.length && isSpace(xml.charCodeAt(i))) i++
      const quote = xml[i]
      if (quote !== '"' && quote !== "'") continue
      const close = xml.indexOf(quote, i + 1)
      const end = close < 0 ? xml.length : close
      attrs[attrName] = decodedText(xml.slice(i + 1, end))
      selfClosing = false
      i = end + 1
    }
    at = i + 1
    if (closing) {
      if (visit.end?.(name)) return
    } else {
      if (visit.start?.(name, attrs, selfClosing)) return
      if (selfClosing && visit.end?.(name)) return
    }
  }
}