vole_document/limits.rs
1//! Centralized resource bounds.
2//!
3//! Every decode and encode path takes a [`Limits`]. Untrusted descriptors must
4//! be rejected *before* catastrophic work is performed, so all arithmetic on
5//! declared lengths and offsets is checked against these bounds and uses
6//! checked integer operations.
7
8/// Hard upper bounds applied while parsing and materializing a descriptor.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub struct Limits {
11 /// Maximum accepted source/descriptor input size.
12 pub max_input_bytes: u64,
13 /// Maximum reconstructed output size for a single materialization.
14 pub max_output_bytes: u64,
15 /// Admission cap on the output of a single `DEFLATE_REPLAY`.
16 ///
17 /// This is a **VOLE replay-profile policy limit**, not an RFC 1951 maximum.
18 /// RFC 1951 permits arbitrarily many empty non-final stored blocks, so it
19 /// gives no finite `f(decompressed_size)` bound on `compressed_size`; a
20 /// bitstream that inflates to zero bytes may be arbitrarily large. VOLE
21 /// therefore declines to replay a descriptor whose declared output exceeds
22 /// this policy cap (see ADR-0016).
23 pub max_replay_bytes: u64,
24 /// Maximum length of a single record payload.
25 pub max_record_len: u32,
26 /// Maximum number of records in a container.
27 pub max_record_count: u32,
28 /// Maximum number of distinct byte objects (`OBJECT` records).
29 pub max_object_count: u32,
30 /// Maximum number of DRA instructions in a reconstruction graph.
31 pub max_graph_ops: u32,
32 /// Maximum repeat count for a single `REPEAT_LAST` instruction.
33 pub max_repeat_count: u64,
34 /// Maximum number of symbols in a single entropy channel.
35 pub max_channel_symbols: u64,
36 /// Maximum number of distinct entropy models (`MODEL` records).
37 pub max_model_count: u32,
38 /// Maximum number of entropy channels (`ENTROPY_CHANNEL` records).
39 pub max_channel_count: u32,
40 /// Maximum encoded size of a single entropy model payload.
41 pub max_entropy_model_bytes: u32,
42 /// Maximum number of lexical spans produced for a PDF input.
43 pub max_pdf_spans: u32,
44 /// Maximum number of selectors in a single `OBSERVATION_INDEX` record.
45 ///
46 /// Bounds the admissions of the optional partial-decode index (Phase 7.3)
47 /// before allocation: an index whose selector table would exceed this is
48 /// rejected at parse and declined by the index builder. It mirrors the
49 /// object/graph scale so the table cannot dwarf the document it describes.
50 pub max_index_selectors: u32,
51 /// Maximum accepted size of an optional `DIRECTORY` record payload.
52 ///
53 /// Bounds the seek directory (Phase 8) before allocation: a directory larger
54 /// than this is declined at decode rather than trusted. A directory is roughly
55 /// `13 * record_count` bytes, so this also caps the record count a directory
56 /// can describe.
57 pub max_directory_bytes: u32,
58 // The ZIP caps below mirror the threat model and DEFAULT/STRICT values frozen
59 // in `research/subagents/phase-12/I-security.md` §6 (threat ids Z1–Z15), as
60 // required by plan §DEC-3/§DEC-9.
61 /// Maximum number of ZIP members accepted in one archive (Phase 12, Z2).
62 pub max_zip_members: u32,
63 /// Maximum declared compressed size of a single ZIP member (Phase 12, Z1).
64 pub max_zip_member_compressed: u64,
65 /// Maximum declared uncompressed size of a single ZIP member (Phase 12, Z1).
66 pub max_zip_member_uncompressed: u64,
67 /// Maximum sum of declared uncompressed sizes across all members (Z2).
68 pub max_zip_aggregate_uncompressed: u64,
69 /// Maximum declared uncompressed/compressed ratio for one member (Z1).
70 pub max_zip_compression_ratio: u32,
71 /// Maximum raw name byte length of one member (Phase 12, Z13/Z14).
72 pub max_zip_name_bytes: u32,
73 /// Maximum raw extra-field byte length of one member (Z7/Z14).
74 pub max_zip_extra_bytes: u32,
75 /// Maximum per-entry comment byte length (Z14).
76 pub max_zip_entry_comment_bytes: u32,
77 /// Maximum archive comment byte length (Z14/Z15).
78 pub max_zip_archive_comment_bytes: u32,
79 /// Maximum central-directory byte length (Z14).
80 pub max_zip_central_dir_bytes: u64,
81 /// Maximum leading bytes before the first local header (Z14).
82 pub max_zip_prefix_bytes: u64,
83 /// Maximum trailing bytes after the EOCD record (Z14).
84 pub max_zip_trailing_bytes: u64,
85 // The XML/OPC caps below mirror the threat model and DEFAULT/STRICT values
86 // frozen in `research/subagents/phase-12/I-security.md` §6 (§2 XML, §3 OPC),
87 // as required by plan §DEC-4/§DEC-9. XML is derived (`Q_gen`) state only.
88 /// Maximum XML element nesting depth before a typed decline (Phase 12, §2).
89 pub max_xml_depth: u32,
90 /// Maximum decoded byte length of a single XML part (Phase 12, §2).
91 pub max_xml_part_bytes: u64,
92 /// Maximum number of XML pull events in a single part (Phase 12, §2).
93 pub max_xml_events: u64,
94 /// Maximum number of XML element nodes in a single part (Phase 12, §2).
95 pub max_xml_nodes: u64,
96 /// Maximum number of attributes on a single XML element (Phase 12, §2).
97 pub max_xml_attrs_per_element: u32,
98 /// Maximum total text bytes accepted across a single XML part (Phase 12, §2).
99 pub max_xml_text_bytes: u64,
100 /// Maximum number of `<!DOCTYPE` declarations accepted (Phase 12: always 0).
101 pub max_xml_doctype: u32,
102 /// Maximum relationships across all `.rels` parts (Phase 12, §3).
103 pub max_opc_rels: u32,
104 /// Maximum internal relationship traversal depth (Phase 12 cycles, §3).
105 pub max_opc_rel_depth: u32,
106 /// Maximum `Default`+`Override` entries in `[Content_Types].xml` (Phase 12, §3).
107 pub max_opc_content_types_overrides: u32,
108 /// Maximum byte length of an OPC part name (Phase 12, §3).
109 pub max_opc_part_name_bytes: u32,
110 // The EPUB/OCF caps below mirror the threat model and DEFAULT/STRICT values
111 // frozen in `research/subagents/phase-12/I-security.md` §6 (§4 EPUB), as
112 // required by plan §DEC-5/§DEC-9. EPUB semantics are derived (`Q_gen`) only.
113 /// Maximum `rootfile` entries accepted in `META-INF/container.xml` (Phase 12, §4).
114 pub max_epub_rootfiles: u32,
115 /// Maximum Package Document manifest items accepted (Phase 12, §4).
116 pub max_epub_manifest_items: u32,
117 /// Maximum Package Document spine `itemref`s accepted (Phase 12, §4).
118 pub max_epub_spine_items: u32,
119 /// Maximum navigation-document nesting depth accepted (Phase 12, §4).
120 pub max_epub_nav_depth: u32,
121 /// Maximum manifest `fallback` chain length followed (Phase 12, §4).
122 pub max_epub_fallback_chain: u32,
123 /// Maximum XHTML element nodes accepted in one content/nav document (Phase 12, §4).
124 pub max_xhtml_nodes: u32,
125}
126
127impl Limits {
128 /// The default archival limits: generous, but always finite.
129 pub const DEFAULT: Limits = Limits {
130 max_input_bytes: 1 << 40, // 1 TiB
131 max_output_bytes: 1 << 40, // 1 TiB
132 max_replay_bytes: 1 << 34, // 16 GiB
133 max_record_len: 1 << 31, // 2 GiB
134 max_record_count: 1 << 20, // ~1M records
135 max_object_count: 1 << 20,
136 max_graph_ops: 1 << 20,
137 max_repeat_count: 1 << 32,
138 max_channel_symbols: 1 << 40,
139 max_model_count: 1 << 16,
140 max_channel_count: 1 << 16,
141 max_entropy_model_bytes: 4096,
142 max_pdf_spans: 1 << 26,
143 max_index_selectors: 1 << 20,
144 max_directory_bytes: 1 << 20,
145 max_zip_members: 1 << 20,
146 max_zip_member_compressed: 1 << 34,
147 max_zip_member_uncompressed: 1 << 34,
148 max_zip_aggregate_uncompressed: 1 << 36,
149 max_zip_compression_ratio: 1024,
150 max_zip_name_bytes: 1 << 16,
151 max_zip_extra_bytes: 1 << 16,
152 max_zip_entry_comment_bytes: 1 << 16,
153 max_zip_archive_comment_bytes: 1 << 16,
154 max_zip_central_dir_bytes: 1 << 28,
155 max_zip_prefix_bytes: 1 << 20,
156 max_zip_trailing_bytes: 1 << 20,
157 max_xml_depth: 256,
158 max_xml_part_bytes: 1 << 28,
159 max_xml_events: 1 << 24,
160 max_xml_nodes: 1 << 24,
161 max_xml_attrs_per_element: 4096,
162 max_xml_text_bytes: 1 << 28,
163 max_xml_doctype: 0,
164 max_opc_rels: 1 << 20,
165 max_opc_rel_depth: 64,
166 max_opc_content_types_overrides: 1 << 20,
167 max_opc_part_name_bytes: 1 << 16,
168 max_epub_rootfiles: 16,
169 max_epub_manifest_items: 1 << 20,
170 max_epub_spine_items: 1 << 20,
171 max_epub_nav_depth: 64,
172 max_epub_fallback_chain: 32,
173 max_xhtml_nodes: 1 << 24,
174 };
175
176 /// Tight limits for hostile-input testing and fuzzing.
177 pub const STRICT: Limits = Limits {
178 max_input_bytes: 1 << 26, // 64 MiB
179 max_output_bytes: 1 << 26, // 64 MiB
180 max_replay_bytes: 1 << 26, // 64 MiB
181 max_record_len: 1 << 24, // 16 MiB
182 max_record_count: 1 << 16, // 65536
183 max_object_count: 1 << 16,
184 max_graph_ops: 1 << 16,
185 max_repeat_count: 1 << 24,
186 max_channel_symbols: 1 << 26,
187 max_model_count: 1 << 12,
188 max_channel_count: 1 << 12,
189 max_entropy_model_bytes: 4096,
190 max_pdf_spans: 1 << 16,
191 max_index_selectors: 1 << 16,
192 max_directory_bytes: 1 << 18,
193 max_zip_members: 1 << 16,
194 max_zip_member_compressed: 1 << 26,
195 max_zip_member_uncompressed: 1 << 26,
196 max_zip_aggregate_uncompressed: 1 << 27,
197 max_zip_compression_ratio: 256,
198 max_zip_name_bytes: 4096,
199 max_zip_extra_bytes: 4096,
200 max_zip_entry_comment_bytes: 4096,
201 max_zip_archive_comment_bytes: 4096,
202 max_zip_central_dir_bytes: 1 << 20,
203 max_zip_prefix_bytes: 1 << 16,
204 max_zip_trailing_bytes: 1 << 16,
205 max_xml_depth: 64,
206 max_xml_part_bytes: 1 << 20,
207 max_xml_events: 1 << 16,
208 max_xml_nodes: 1 << 16,
209 max_xml_attrs_per_element: 256,
210 max_xml_text_bytes: 1 << 20,
211 max_xml_doctype: 0,
212 max_opc_rels: 1 << 14,
213 max_opc_rel_depth: 16,
214 max_opc_content_types_overrides: 1 << 12,
215 max_opc_part_name_bytes: 4096,
216 max_epub_rootfiles: 4,
217 max_epub_manifest_items: 1 << 14,
218 max_epub_spine_items: 1 << 14,
219 max_epub_nav_depth: 16,
220 max_epub_fallback_chain: 8,
221 max_xhtml_nodes: 1 << 16,
222 };
223}
224
225impl Default for Limits {
226 fn default() -> Self {
227 Limits::DEFAULT
228 }
229}