SPB Git

Repository Public

security.md 22.4 KB

# Security

A word processor opens files written by other people. This document states what ORIX Docs 1.0.0 assumes about those files, what the code does, which tests exercise it, and what remains at risk. The requirements were set before the importers were written (technology-evaluation.md, section 13); this document describes the code as it is.

# Threat model

Assets. The user's documents and other files, the integrity of the document being edited, and the user's privacy (no content leaves the Mac).

Untrusted input. Any file opened or imported: .orixdoc, DOCX (also .docm and .dotx), RTF, Markdown, HTML, plain text, PDF; bibliography files (BibTeX, RIS, CSL-JSON); workflow JSON files; pasted and dropped content; LaTeX strings inside documents.

Adversary. Someone who can get a crafted file opened — by e-mail, download or a shared folder — and wants to crash the application, exhaust memory or CPU, read or write files the user did not choose, make the application contact a server, or run code.

Out of scope. An attacker who already runs code as the user; physical access; malicious fonts installed on the system; flaws in macOS frameworks themselves (they are listed under residual risks because the application depends on them).

# Summary

Threat What the code does Tests
Decompression bombs, oversized archives Limits on entry count, entry size, total size and compression ratio ZipTests.detectsCorruptionAndBombs, decompressionBombIsRefused
Path traversal in archives Unsafe entry names refused; entries are never extracted to disk ZipTests.rejectsTraversalAndGarbage, pathTraversalEntryNamesAreRefused
XML entity attacks (XXE, billion laughs) Any part containing <!DOCTYPE or <!ENTITY is refused; external entities never resolved doctypeAndEntitiesAreRefused
Stack or memory exhaustion by nesting Depth, size and node limits; dedicated large stacks hugeNestingIsRefusedNotOverflowed, tenThousandNestedQuotesAndLists
Macros and active content Never executed, never preserved macrosOleAndActiveXAreDroppedNeverPreserved
Remote resources (tracking, data exfiltration) Nothing is ever fetched; external targets are inert strings externalTargetsAreKeptAsTextNeverFetched, imagesComeOnlyFromDataURIsAndTheLoader
Script in HTML and Markdown Own parsers, no web engine; script content skipped, script schemes removed scriptSchemesNeverReachTheOutput, scriptLinksAreRemoved
Crashing the math typesetter Guard before typesetting; fuzz tests MathRobustnessTests
Corrupted native files SHA-256 manifest, strict reader, bounded recovery NativeContainerTests, malformedContainersNeverTrap
Workflow files that run code or write anywhere Closed step vocabulary; output path confinement unknownStepTypesAreRejected, pathsLeavingTheOutputFolderAreRejected
Malformed input in general Importers throw or warn, never trap truncatedAndCorruptedPackagesNeverCrash, mutatedXmlNeverCrashes, fuzzedMarkupNeverTrapsAndKeepsModelInvariants

The engine test run that contains these tests is recorded as 582 tests, passed, 0 issues, in test-results.json. The report records totals, not individual test outcomes.

# ZIP archives

Code: Packages/ORIXDocsKit/Sources/DocContainer/ZipArchive.swift. Both .orixdoc and DOCX are ZIP files and go through the same reader, written for this project.

ZipLimits.standard:

Limit Value
Entries 20,000
One entry, uncompressed 256 MiB
All entries, uncompressed 1 GiB
Compression ratio Entries larger than 1 MB whose uncompressed/compressed ratio exceeds 1,000 are refused

Checks made while reading the central directory, before any data is decompressed:

  • ZIP64 archives, encrypted entries and compression methods other than stored and deflate are refused (unsupported);
  • the central directory and every entry must lie inside the file (corrupted);
  • duplicate entry names are refused;
  • unsafe entry names are refused: empty, starting with /, containing a backslash, a NUL, a colon, or a .. component.

When an entry is read: the local header must match the directory (signature and name), the data must lie inside the file, a stored entry must have equal sizes, the inflated data must have exactly the declared size, and the CRC-32 must match.

The archive is held in memory and entries are decompressed on demand. Nothing is ever extracted to the file system, so a path in an archive cannot become a path on disk; the name checks are defence in depth.

Tests: Tests/DocContainerTests/ZipTests.swift (rejectsTraversalAndGarbage, detectsCorruptionAndBombs, plus interoperability with the system zip and unzip); Tests/DocDOCXTests/SecurityTests.swift (notAnArchive, decompressionBombIsRefused, pathTraversalEntryNamesAreRefused). DocContainer line coverage is 100.0 % (coverage.json).

# XML in DOCX

Code: Packages/ORIXDocsKit/Sources/DocDOCX/XML.swift (XMLTree.parse), on Foundation's XMLParser.

  • No DTD at all. A part whose bytes contain <!DOCTYPE or <!ENTITY is refused before parsing. UTF-16 parts are transcoded first so that the scan sees them. OOXML never needs a DTD, so nothing legitimate is lost; entity expansion and external entities are therefore impossible.
  • shouldResolveExternalEntities is set to false explicitly.
  • XMLLimits.standard: 96 MiB per part, depth 256, 4,000,000 elements. Custom XML and the ORIX extras payload are size-capped before parsing (32 MiB for the extras payload).
  • Import and export run on a thread with a 32 MB stack (DocxStack), so nesting up to the depth limit cannot overflow a small concurrency-thread stack.
  • Numbers read from XML are range-checked before conversion.

Tests: doctypeAndEntitiesAreRefused, hugeNestingIsRefusedNotOverflowed, absurdValuesDoNotCrash, mutatedXmlNeverCrashes (200 structurally mutated documents), truncatedAndCorruptedPackagesNeverCrash (198 corrupted archives) — counts as stated in compatibility/docx.md.

# Macros, OLE and other active content

  • A .docm is imported for its text; VBA projects, OLE embeddings, ActiveX controls and custom UI parts are never interpreted, never executed and never kept. The user gets a warning that names what was dropped.
  • Uninterpreted parts of a DOCX (theme, font table, custom XML…) are preserved through an allow-list of part names; each must be well-formed XML and its relationships must stay inside the preserved set.
  • The exporter validates preserved parts again, because a model can also come from an untrusted .orixdoc that claims to carry preserved parts.
  • The model's field type is a closed set (page number, page count, date, title, sequence, heading text…); there is no field that reads files, the environment or the network. Unknown DOCX fields keep their displayed text and raise a warning.
  • ORIX Docs never writes a macro-enabled file.

Tests: macrosOleAndActiveXAreDroppedNeverPreserved, preservedPartsFromAnUntrustedModelAreRevalidatedOnExport.

  • OPC.resolve maps a relationship target to a part inside the archive or to nothing. A target that is absolute, has a scheme, or climbs above the package root is ignored with a warning.
  • External targets (linked pictures, remote templates, INCLUDEPICTURE) are kept as strings or dropped with a warning. Nothing is read from the file system or fetched from the network.
  • Hyperlinks are inert data. In the editor a link is followed only on an explicit ⌘-click, and only http, https and mailto URLs are handed to the system; #name jumps inside the document (text-engine.md).

Tests: relationshipTargetsCannotLeaveThePackage, externalTargetsAreKeptAsTextNeverFetched.

# HTML and Markdown

Code: Packages/ORIXDocsKit/Sources/DocFormats/HTMLTokenizer.swift, HTMLImporter.swift, MarkdownImporter.swift, MarkdownInline.swift.

  • No web engine. HTML is read by a tolerant tokeniser and tree builder written for this project; WebKit and NSAttributedString(html:) are not used. There is nothing that could execute a script.
  • The content of <script> and <style> is skipped as raw text; scripts, frames and event handlers are reported as dropped.
  • Links whose scheme can carry script (javascript:, vbscript:, data:, livescript:) are removed and their text kept, in HTML and in Markdown.
  • Images come only from data URIs or from the resource loader supplied by the caller. The loader built in DocAutomation/DocumentConverter.swift refuses any path that contains ://, resolves the path against the folder of the source file, requires the result to stay under that folder, and refuses files of 64 MiB or more. Remote images are never fetched.
  • Limits: 64 MiB of source, 256 open HTML elements, 32 nested Markdown containers, 9 list levels, 256 columns and 1,000,000 cells per table; the recursive Markdown parser runs on its own 16 MiB stack (formats.md).

Tests: Tests/DocFormatsTests/HTMLTests.swift (scriptSchemesNeverReachTheOutput), MarkdownTests.swift (scriptLinksAreRemoved, imagesComeOnlyFromDataURIsAndTheLoader), FacadeAndRobustnessTests.swift (HostileInputTests: tenThousandNestedQuotesAndLists, pathologicalInlineInputIsLinearEnough, hugeTables, brokenMarkdownTables, malformedContainersNeverTrap, fuzzedMarkupNeverTrapsAndKeepsModelInvariants; UnicodeTortureTests).

The loader (DocumentConverter.confinedResource) resolves symbolic links and compares whole path components, so neither a sibling folder with a similar name nor a link pointing outside is read; Tests/DocAutomationTests/ResourceConfinementTests.swift checks both.

# RTF, plain text and PDF import

  • RTF goes through AppKit's NSAttributedString RTF codec, which is local (no network, no WebKit). Pictures are lifted out of the bytes and handled by this project's code; WMF, EMF and PICT pictures are dropped with a warning. RTFD is refused. Limit: 128 MiB.
  • Plain text: encoding detection with repair, control characters removed. Limit: 64 MiB.
  • PDF: text extraction through PDFKit only. Password-protected PDFs and PDFs whose owner forbids extraction are refused. Limits: 512 MiB, 20,000 pages.

Details and what was verified: formats.md.

# Mathematics

Equations are LaTeX strings that arrive from untrusted documents and are given to a third-party typesetter, SwiftMath, which recurses on nesting and can trap on some malformed input.

MathGuard (Packages/ORIXDocsKit/Sources/DocMath/MathRenderer.swift) refuses an expression before it reaches the library when it:

  • is longer than 4,000 UTF-16 units (maxLength);
  • contains control characters or the object-replacement character;
  • has an unmatched closing brace, an unclosed group, or ends with an incomplete command;
  • has two script operators in a row (^^, __);
  • nests deeper than 24 levels (maxDepth), counting braces, \left and \begin;
  • contains more than 60 fraction, root or binomial commands;
  • has more than 400 cells (maxCells), counting & and \\.

A refused or unparsable expression is shown as its source in red monospaced text with an error message; it never disappears and never stops the layout. Drawing is serialised by a lock.

Tests: Tests/DocLayoutTests/MathRobustnessTests.swift — hostileLatexNeverCrashes (a list of about a hundred malformed and extreme expressions, each typeset inline and in display style, then drawn), randomTokenSoupNeverCrashes (3,000 pseudo-random token sequences from a fixed seed), validEquationsTypesetWithoutError.

# The native container

Code: Packages/ORIXDocsKit/Sources/DocFormats/NativeContainer.swift; description in persistence.md.

  • A hostile .orixdoc is as untrusted as a hostile DOCX: it goes through the same ZIP reader and limits, plus a 1 GiB file limit.
  • The manifest lists every entry with its size and SHA-256; the strict reader verifies them before decoding document.json. A container or schema version newer than the build is refused.
  • Recovery of a damaged file keeps only entries whose data is complete, reports everything it skipped, and refuses to open a file whose document.json cannot be recovered.

What the checksum is for. It detects corruption — a bad disk, a truncated download, a careless tool. It does not detect tampering: whoever can rewrite the file can rewrite the manifest. The format has no digital signature and no encryption.

Tests: Tests/DocFormatsTests/NativeContainerTests.swift (byte flips in each kind of entry, tampered asset, truncation, wrong or misplaced mimetype, missing manifest, future versions, recovery).

# Workflows

Code: Packages/ORIXDocsKit/Sources/DocAutomation/Workflow.swift, WorkflowRunner.swift; description in automation.md. A workflow is a JSON file, possibly received from someone else.

  • Closed vocabulary. The step types are a fixed list of document operations. Any other type is rejected when the file is loaded, before any input is read. There is no step that runs a script, starts a process or opens a connection.
  • Values are validated before anything runs: theme, template, paper, citation style, audit profile, export format, margins and levels. The file must be smaller than 1 MB.
  • Path confinement. An output name that is absolute, starts with ~, or contains .., . or empty components is rejected at load time. At run time the destination is resolved again with symbolic links followed and refused if it lands outside the output folder; the {name} placeholder is sanitised.
  • Existing files are not overwritten unless asked, and a workflow can never replace its own input.

Tests: Tests/DocAutomationTests/WorkflowRunnerTests.swift — unknownStepTypesAreRejected (runScript, shell, exec, appleScript, download), pathsLeavingTheOutputFolderAreRejected, invalidValuesAreRejectedBeforeAnythingRuns.

# No network code

The application, the engines and the command-line tool contain no networking calls.

  • Tests. OnDeviceOnlyTests.noNetworkCodeInAutomationOrIntelligence (Tests/DocAutomationTests/IntelligenceTests.swift) reads every Swift file under DocAutomation, orixdocs, App/Sources/Intelligence, App/Sources/Automation and App/Sources/Inspector and fails if one contains URLSession, URLRequest, NWConnection, import Network, CFNetwork, NSURLConnection, Process(), NSTask, NSAppleScript or /bin/sh. OnDeviceOnlyTests.noServerBackedModelTypeInTheSources reads every Swift file of the application and of the package and fails if one names the server-backed language-model type.
  • By inspection. The first test covers five folders, not the whole code base. A search of all of App/Sources and Packages/ORIXDocsKit/Sources for the same networking APIs and for WebKit, made on 2026-11-21, found none. This is an observation, not a standing test.
  • What does leave the process, on the user's action only: a ⌘-clicked http, https or mailto URL, handed to the system; and revealing an output folder in the Finder after a workflow.
  • macOS services the application calls (spelling, NaturalLanguage, the on-device model) are system components; the system may download assets for them on its own account (technology-evaluation.md, section 9).

# The process

  • Hardened runtime, no entitlements. The Release build is signed with the hardened runtime and an empty entitlements file: no JIT, no unsigned executable memory, no DYLD environment variables, no disabled library validation, no debugger attachment, no get-task-allow (signing.md). The release script fails if get-task-allow is present.
  • Notarized by Apple and stapled (notarization.md).
  • Not sandboxed. This is the weak point of the design. The application runs with the user's full file permissions (subject to the system's privacy prompts for folders such as Documents and Desktop) and, like any unsandboxed process, could open network connections if code to do so were injected. If a parser flaw allowed code execution, nothing in the process would confine the damage. The technology evaluation recommended the sandbox for the GUI application (section 12); it is not adopted in 1.0.0, which is why the parser rules above carry the weight.
  • Foreign files are never written back. A DOCX, RTF, Markdown, HTML, text or PDF file opens as an untitled copy (persistence.md).
  • No updater. There is no code that downloads and installs anything. The other side of that coin is under residual risks.

# Third-party code

One dependency: SwiftMath (https://github.com/mgriebling/SwiftMath, MIT), pinned in Packages/ORIXDocsKit/Package.swift by revision, 0b0222e102ba415b352cd29f334075622bd4e6aa, and recorded in Package.resolved.

  • Why a revision and not a version. In the checkout this revision is described by git as 1.7.3-111-g0b0222e: 111 commits after the last tagged release, 1.7.3, dated 2026-10-28. The technology evaluation found that release 1.7.3 contained input-triggered traps whose fixes existed only on the upstream main branch, together with commonly used commands, and listed "pin a specific main revision after review" as an option (section 6). Package.swift itself carries no comment giving the reason; this is the reason the evaluation supports.
  • Why pinned at all. A revision pin means a build cannot silently pick up different upstream code: the same sources are fetched every time, and moving the pin is a deliberate, reviewable change.
  • Cost. An unreleased revision has no upstream release notes and no version to compare against advisories. Updating it is manual, and must be followed by the math robustness tests.
  • The library is treated as untrusted with respect to input: MathGuard and the fuzz tests above exist because of it.

Everything else — ZIP, DOCX, Markdown, HTML, citations, layout — is written in this repository and has no other dependency than Apple's frameworks.

# Hostile-input tests

File Suite or tests
Tests/DocContainerTests/ZipTests.swift rejectsTraversalAndGarbage, detectsCorruptionAndBombs
Tests/DocDOCXTests/SecurityTests.swift Suite "DOCX import — hostile input": notAnArchive, archiveWithoutDocument, decompressionBombIsRefused, pathTraversalEntryNamesAreRefused, relationshipTargetsCannotLeaveThePackage, doctypeAndEntitiesAreRefused, hugeNestingIsRefusedNotOverflowed, macrosOleAndActiveXAreDroppedNeverPreserved, preservedPartsFromAnUntrustedModelAreRevalidatedOnExport, externalTargetsAreKeptAsTextNeverFetched, absurdValuesDoNotCrash, truncatedAndCorruptedPackagesNeverCrash, mutatedXmlNeverCrashes
Tests/DocFormatsTests/FacadeAndRobustnessTests.swift HostileInputTests, UnicodeTortureTests
Tests/DocFormatsTests/HTMLTests.swift, MarkdownTests.swift scriptSchemesNeverReachTheOutput, scriptLinksAreRemoved, imagesComeOnlyFromDataURIsAndTheLoader
Tests/DocFormatsTests/NativeContainerTests.swift Corruption, tampering, truncation, versions, recovery
Tests/DocLayoutTests/MathRobustnessTests.swift hostileLatexNeverCrashes, randomTokenSoupNeverCrashes
Tests/DocAutomationTests/WorkflowRunnerTests.swift unknownStepTypesAreRejected, pathsLeavingTheOutputFolderAreRejected, invalidValuesAreRejectedBeforeAnythingRuns
Tests/DocAutomationTests/IntelligenceTests.swift OnDeviceOnlyTests

# Residual risks

Stated plainly.

  1. No sandbox. A memory-safety or logic flaw that led to code execution would act with the user's permissions. Swift's memory safety makes this unlikely in this project's own code; it does not cover the system frameworks listed next.
  2. System parsers run in-process on untrusted bytes: ImageIO (every embedded image), PDFKit (PDF import, PDF assets), AppKit's RTF codec, Foundation's XMLParser and JSONDecoder, Core Text. Their flaws are outside this project's control, and no size limit removes that exposure.
  3. SwiftMath can still trap on an input that MathGuard does not anticipate. The fuzz tests cover a fixed list and a fixed random seed; they are evidence, not proof. A trap would terminate the application; autosave limits the loss to the autosave delay for a saved document.
  4. Fuzzing is modest: hundreds to thousands of generated cases per importer, run as unit tests. There is no coverage-guided fuzzing and no continuous fuzzing.
  5. Denial of service within the limits. A file inside every limit can still be slow or memory-hungry to open (up to 1 GiB of uncompressed entries is accepted). Layout runs on the main thread, so a pathological document can make the window unresponsive.
  6. Image loading from the document's folder. Markdown and HTML may reference local images; they are read only from inside the source file's own folder (symbolic links resolved, whole path components compared, 64 MB cap — DocumentConverter.confinedResource, tested in ResourceConfinementTests). A hostile document can still make the app read any image-like file placed in that same folder; nothing is sent anywhere.
  7. Integrity is not authenticity. The native container's checksums do not protect against deliberate modification; documents are neither signed nor encrypted.
  8. No automatic updates. A parser fix reaches users only when they install a new version by hand. The technology evaluation called this out as the main argument for an in-app updater; 1.0.0 has none.
  9. Links. A ⌘-click opens http, https and mailto targets in other applications; the destination's safety is not the application's to judge.
  10. Verification gaps. No independent security review was made. The Intel build was never run. The no-network property is test-enforced for five source folders and observed, not enforced, for the rest.

Security reports: contact@spboucher.ai.

Files main
Menu

Theme