Hypergrid summary

← Back to docs · Architecture · Decisions · Previous: Social Modules · Next: WebRTC Voice

Status: accepted (20 of 20 tasks, 10 sections, 265 tests). Security review verdict: CONDITIONAL PASS (CRITICAL RISK). Change: openspec/changes/hypergrid/.

What was built

The Hypergrid (HG) system from OpenSimulator 0.9.3.0: ~11,171 lines of C# across ~23 files in two layers (Robust services and region modules). Ported as ~9,144 lines of Rust with 265 tests (215 unit + 50 integration).

HG enables cross-grid teleportation, inventory transfer, friend lists, IM, and map linking between independent OpenSimulator grids.

SectionAreaTasks
1Gatekeeper service: foreign visitor entry, access control1.1-1.2
2UserAgent service: outbound HG teleport, session verification2.1-2.2
3HG inventory: proxied access, suitcase folder restriction3.1-3.2
4HG assets and friends: access-controlled transfer, cross-grid friends4.1-4.2
5HG messaging: cross-grid IM routing5.1-5.2
6Hyperlink management: grid linking, HELO probe6.1-6.2
7Service connectors: HTTP clients for Gatekeeper, UserAgent, HGFriends7.1-7.2
8HG region modules: entity transfer, inventory, friends, lure, map, users8.1-8.3
9HypergridServiceInConnectorModule: expose HG endpoints in simulator9.1
10Integration tests and CRITICAL RISK security review10.1-10.2

Architecture

Foreign Grid                          Home Grid
┌─────────────┐   HTTP/XMLRPC   ┌─────────────────┐
│ UserAgent    │ ←──────────────→│ Gatekeeper       │
│ Service      │                 │ Service          │
└─────────────┘                  └────────┬────────┘
                                          │
                                 ┌────────▼────────┐
                                 │ Region Simulator │
                                 │ HGEntityTransfer │
                                 │ HGInventoryAccess│
                                 │ HGFriends        │
                                 │ HGAssetMapper    │
                                 └─────────────────┘

Two sides: the Gatekeeper (entry point for foreign visitors) and the UserAgent service (manages outbound travel from the home grid). HG region modules extend their base counterparts via trait composition.

Module breakdown

ModuleLinesTestsResponsibility
gatekeeper.rs75210Foreign visitor entry, hyperlink creation, access control
user_agent.rs84417Outbound HG teleport, session verification, UUI
hg_inventory.rs61812Proxied inventory, suitcase folder restriction
hg_assets.rs2859Access-controlled asset transfer, export filtering
hg_friends.rs5876Cross-grid friendship, secret verification
hg/messaging.rs64111Cross-grid IM routing, HGMessageTransferModule
hg_linker.rs3116Grid-to-grid region linking, console commands
connectors/81110HTTP clients for Gatekeeper, UserAgent, HGFriends, HELO
hg/entity_transfer.rs5789Cross-grid teleport, appearance restriction
hg/inventory_access.rs5488Route inventory to local/remote, suitcase enforcement
hg/ (lure, map, users)-28Lures, map blocks, UUID-to-name for foreign users
hg/connector_in.rs3265Expose HG endpoints in simulator
Integration tests-50HG teleport round-trip, suitcase, IM, hyperlinks, friends

Key decisions

  • H1: HG modules extend base modules via trait composition, not separate implementations. HGEntityTransferModule wraps EntityTransferModule.
  • H2: UUI format (uuid;griduri;name) stored alongside local UUIDs. HGUserManagementModule resolves first.last@griduri to local cache.
  • H3: Suitcase inventory uses path validation with a root-anchored check to prevent directory traversal to the full inventory tree.
  • H4: Traveling agent sessions use cryptographically random tokens, not predictable values. Tokens are single-use and expire on logout.
  • H5: HELO probe (HeloServicesConnector) discovers HG capability before attempting cross-grid operations, with timeout and retry.

Tests

265 tests total (215 unit + 50 integration). Integration tests cover HG teleport round-trip (outbound + inbound), suitcase inventory access, cross-grid IM delivery, hyperlink creation/removal, and friend request across grids.

Full suite after this phase: 1,679 tests passing.

Security review

[!CAUTION] CRITICAL RISK: CONDITIONAL PASS: 3 critical, 3 high, 3 medium, 2 low findings. All CRITICAL and HIGH findings must be fixed before any public-facing deployment. See security review for details.

Full report: security-review-hypergrid.md.

Critical findings

IDSeverityFinding
F-01CRITICALSuitcase folder escape via get_item: no suitcase-tree check
F-02CRITICALVerifyAgent callback not implemented in gatekeeper
F-03CRITICALUUID impersonation check not implemented

High findings

IDSeverityFinding
F-04HIGHSession token comparison is not constant-time
F-05HIGHNo session token expiration or TTL
F-06HIGHNo rate limiting on any Hypergrid endpoint

Medium and low

IDSeverityFinding
F-07MEDIUMassets_exist leaks asset existence info
F-08MEDIUMFriendship secret has only 32 bits of entropy
F-09MEDIUMFriendship deletion uses weak pattern matching
F-10LOWMAC/ID0 deny lists use substring matching (ported C# bug)
F-11LOWNo per-asset transfer-permission check (matches C# design)

All 6 CRITICAL + HIGH findings require remediation before deployment. F-01 through F-03 must be fixed before any multi-user grid.

Commits

HashDescription
7892e6cSections 1-9: services, connectors, and region modules (27 files, 9,144 lines, 215 tests)
8e02eaeSection 10: integration tests + CRITICAL security review