Archives summary

← Back to docs · Architecture · Decisions · Previous: Region modules · Next: Social modules

Status: accepted (18 of 18 tasks, 8 sections, 205 tests). Security review verdict: CONDITIONAL PASS. Change: openspec/changes/archives/.

What was built

The OAR (OpenSim Archive) and IAR (Inventory Archive) systems from OpenSim/Region/CoreModules/World/Archiver/ (15 files, ~4,800 lines) and OpenSim/Region/CoreModules/Avatar/Inventory/Archiver/ (8 files, ~3,400 lines), in one crate: welkin-archive (9,555 lines, 205 tests).

SectionAreaTasks
1Foundation: constants, 21 asset-type mappings, path prefixes1.1-1.2
2Land and settings serialization, archive control file2.1-2.2
3OAR write: single/multi-region, async asset gathering3.1-3.3
4OAR read: merge, displace, rotate, bbox, permissions4.1-4.3
5IAR write and read5.1-5.2
6Cross-grid portability: OspResolver, ExternalRepresentationUtils6.1-6.2
7Integration: ArchiverModule, InventoryArchiverModule, console commands7.1-7.2
8Ported tests and security review8.1-8.2

Architecture

Both OAR and IAR are gzip-compressed tar files. The C# custom TarArchiveWriter/TarArchiveReader (455 lines) is replaced by the tar and flate2 crates.

ModuleResponsibility
constants.rs21 asset-type-to-extension mappings, path prefixes, filename helpers
region_settings.rsRegionSettingsSerializer: XML read/write matching C# format
land_data.rsLandDataSerializer: XML read/write for parcel data
control_file.rsarchive.xml parsing: version, timestamps, region dimensions, multi-region
oar_write.rsSingle and multi-region OAR save with progress callbacks
oar_read.rsFull dearchive with merge, displacement, rotation, bbox, permission filter
assets_request.rsAsync asset gathering with tokio::time::timeout, deduplication
iar_write.rsInventory tree walk, permission filter, UserInventoryItemSerializer
iar_read.rsFolder creation, item insertion, creator UUID resolution
osp_resolver.rsfirst.last name-to-UUID mapping for portable archives
external_representation.rsCreator/owner/lastOwner UUID rewriting for cross-grid compatibility
archiver_module.rsRegion module: save oar, load oar console commands
inventory_archiver_module.rsRegion module: save iar, load iar console commands

Key decisions

  • A1: Use tar + flate2 instead of porting the 455-line custom tar code.
  • A2: Async asset gathering with tokio::time::timeout replaces C# ManualResetEvent + timer.
  • A3: OAR load options are a flags struct, not positional arguments.
  • A4: OspResolver writes first.last profiles on save, resolves on load, falls back to UserManagement service.
  • A5: Path traversal protection: all tar paths validated against expected prefix before processing.

Tests

174 unit tests and 31 integration tests (205 total). Integration tests round-trip OAR and IAR save/load, testing merge, displacement, permission filter, and multi-region support. Ported from ArchiverTests.cs and InventoryArchive*Tests.cs (~900 lines C#).

Security review

[!WARNING] CONDITIONAL PASS: 0 critical, 0 high, 5 medium tracked for remediation. See security review for details.

Full report: security-review-archives.md.

IDSeverityFinding
M-1MEDIUMDecompression bomb: no limit on total decompressed size
M-2MEDIUMVec::with_capacity trusts tar header size (up to 50 GiB)
M-3MEDIUMfrom_utf8_lossy on tar paths can silently alter path validation
M-4MEDIUMvalidate_path does not check for null bytes (OAR reader)
M-5MEDIUMvalidate_path does not check for Windows drive-letter paths

All 5 are defense-in-depth gaps tracked for remediation before production.

Commits

HashDescription
5207afcSections 1-2: constants, serializers, control file (22 tests)
4853ed9Sections 3-4: OAR write/read, async assets, multi-region (35 tests)
21945b2Sections 5-6: IAR, OspResolver, ExternalRepresentationUtils (58 tests)
62994ddSections 7-8.1: integration modules, ported tests (90 tests)
0e1b978Section 8.2: security review, CONDITIONAL PASS, accepted