Prevent gateway descendant asset data leakage #2427

Activity

1. richturner

   added a parent issue on Jan 19, 2026

   • Gateway tunnel robustness improvements #1807
2. richturner

   added

   BugError or issue in the systemError or issue in the system

   DiscussNeeds discussion within the planning teamNeeds discussion within the planning team

   on Jan 19, 2026
3. richturner

   changed the title [-]Prevent gateway descendat asset data leakage[/-] [+]Prevent gateway descendant asset data leakage[/+] on Jan 19, 2026
4. ebariaux

   removed

   DiscussNeeds discussion within the planning teamNeeds discussion within the planning team

   on Mar 9, 2026
5. ebariaux

   assigned

   richturner

   and unassigned

   richturner

   on Mar 9, 2026
6. ebariaux commented on May 18, 2026

   

   ebariaux

   on May 18, 2026

   Contributor

   More actions

   Take migration into account, don't want to loose history for assets in central manager
7. denniskuijs

   assigned

   richturner

   on Jul 13, 2026
8. wborn

   added the

   Bug

   issue type on Jul 16, 2026
9. richturner

   added

   GatewaysTopic Gateways: all features related to gateway featuresTopic Gateways: all features related to gateway features

   on Sep 9, 2026
10. pierrekil

    assigned

    wborn

    and unassigned

    richturner

    on Nov 2, 2026
11. wborn commented on Nov 3, 2026

    

    wborn

    on Nov 3, 2026

    Member

    More actions

    Before implementing this issue, I'd like agreement on whether V2 should apply only to new gateway registrations, also to newly synchronized assets on existing gateways, or to existing assets through an explicit migration.

    The two gateway IDs in this report both start with 4H, so every shared edge asset ID maps to the same central ID under V1.

    For V2, I suggest position-by-position addition of the Base62 alphabet indices of the corresponding gateway ID and edge asset ID characters, modulo 62, with subtraction providing the inverse. The alphabet order could remain abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.

    This preserves the 22-character ID format and guarantees distinct results for identical edge asset IDs on different V2 gateways. Ownership validation would remain necessary because different gateway/edge-ID combinations can still collide.

    1. Common requirements

    Whichever approach we choose, gateway operations should validate persisted ownership when the central manager applies the change.

    This should cover initial synchronization, live asset updates, attribute writes, and deletions. Existing targets must belong to the authenticated gateway, and destination parents must remain within its permitted subtree.

    Ownership checks should run inside the existing asset locks and transactions. Failed or incomplete synchronization must stop before obsolete-asset cleanup. Outbound routing and cleanup must use the same mapping rules as incoming operations.

    Mapping information must also be managed centrally and preserved across ordinary updates, reconnects, and restarts.

    For already-affected installations, the current parent may reflect an earlier incorrect reassignment. Contested ownership and historical data would need investigation before either gateway resumes synchronization.

    2. Overview of the options

    All three approaches would use V2 for new gateway registrations.

    Approach	Existing central assets	New assets on existing gateways	Initial impact
    Option 1 — Version per gateway	Retain V1 IDs	Continue using V1	Smallest mapping change
    Option 2 — Preserve existing bindings, use V2 for new assets	Retain V1 IDs	Use V2	Mixed mapping versions within a gateway
    Option 3 — Full migration to V2	Rekey to V2-derived IDs	Use V2	Rewrite affected data and references

    3. Option 1 — Keep existing gateways on V1 and use V2 for new gateways

    Store an immutable mapping version on each locally registered gateway. Existing registrations without a version continue using V1. Normal provisioning of a new registration assigns and persists V2 before synchronization.

    Logical imports and recreation would need explicit handling so an old registration is restored with the version its existing IDs depend on.

    Advantages

    • Preserves existing central IDs, history, rules, dashboards, and external references.
    • Keeps mapping deterministic and reversible using the gateway's version.
    • Avoids mixed mapping versions within a gateway.
    • Should fit the existing attribute storage without requiring a schema migration or edge protocol change.

    Disadvantages

    • Existing gateways continue using V1 for newly synchronized assets.
    • Existing conflicting gateways still need intervention before both can synchronize their cloned assets.
    • V1 remains supported for as long as any gateway depends on it.

    Later migration

    An existing gateway could later be migrated explicitly to V2 using the procedure described below. That operation would retain the gateway registration and edge IDs while rekeying its central descendants and updating their history and references.

    Migrating individual descendants would require introducing support for mixed mappings, as described in option 2. A gateway with no central data or references worth preserving could instead be replaced with a fresh V2 registration.

    4. Option 2 — Preserve existing V1 assets and use V2 for newly synchronized assets

    Keep established central IDs and use V2 whenever an asset is first accepted centrally after the cutover.

    Here, “new” means newly represented in the central manager. An asset created earlier on an offline gateway could still receive V2 when it is first synchronized.

    This requires durable information identifying which mapping applies to each asset. Possible representations include:

    • A server-managed mapping-version marker on each central asset.
    • A frozen set of legacy V1 IDs associated with each gateway.
    • Explicit bindings between gateway ID, edge asset ID, and central asset ID.

    A timestamp could identify the cutover, but imports, recreation, and ordinary synchronization would still need to preserve the established mapping choice.

    Advantages

    • Existing assets keep their IDs, history, and references.
    • Existing gateways benefit from V2 for future assets.
    • Introduces V2 gradually without requiring an immediate historical-data rewrite.
    • Allows later migration to be performed per asset, subtree, or gateway.

    Disadvantages

    • A single gateway can contain a V1 parent and V2 children. Every asset and parent reference needs independent resolution.
    • Incoming updates, outbound writes, deletes, and cleanup all need the same resolver.
    • Server-managed mapping information must survive full asset synchronization and restoration.
    • Deletion and recreation need an explicit policy for retaining or releasing old bindings.
    • Cross-version collisions remain possible, including within the same gateway.

    That last point requires more than checking gateway ownership. It is possible for V1(edgeA) and V2(edgeB) to produce the same central ID. The resolver must verify the exact association and prevent a new V2 allocation from taking an ID already bound or reserved for another asset.

    This approach could also help an affected gateway whose cloned asset has no verified central representation of its own. It could receive a V2 representation while the verified existing owner keeps the V1 ID. Already mixed history would still require separate investigation.

    Later migration

    Selected V1 assets could be explicitly migrated to V2-derived IDs. That would still require updating their history and references, but the scope could be limited to one asset or subtree.

    Migrating a V1 parent would also require updating the parent references and paths of children that retain their own V1 IDs. References from assets outside the selected subtree must be considered too.

    The stored version or binding would change only after the rewrite had been validated. Once all retained V1 bindings for a gateway had been migrated, that gateway could operate entirely with V2.

    5. Option 3 — Fully migrate existing gateways and assets to V2

    Recalculate the central IDs of existing gateway descendants using V2 and update the associated database records and known references.

    For a verified V1 asset, the manager can reverse V1 to recover its edge ID, then apply V2 using the same gateway ID.

    Advantages

    • Existing and new gateways use the same mapping after migration.
    • Removes continued reliance on V1 for the migrated assets.
    • Reduces the need for permanent mixed-version resolution.
    • Can bring existing gateways onto V2 while retaining attributable history, provided the necessary references are migrated.

    Disadvantages

    • Requires changing persistent identities throughout the installation.
    • Can affect parent relationships, ltree paths, permissions, asset rulesets, alarm associations, historical and predicted datapoints, attributes, and dashboards.
    • Requires coordination with rules and external integrations that store central IDs.
    • Introduces migration, interruption, and recovery risks during an upgrade.
    • Cannot automatically separate history that was already mixed under one ID.

    Groovy rules are a concrete compatibility concern. OpenRemote's own ChildAssetControl.groovy contains a hardcoded asset ID used in an AssetQuery. Scripts may also construct IDs dynamically, so a generic migration cannot reliably discover and rewrite every reference. External clients may retain IDs outside the database. Example Groovy rule

    TimescaleDB adds a potential operational cost. Historical datapoints use entity_id as a columnstore segmentation key. Updates to compressed data are supported, but rekeying extensive history could involve substantial rewriting and database load. This needs benchmarking against representative compressed datasets before deciding whether full migration is suitable for an upgrade.

    6. Requirements whenever existing IDs are migrated

    Options 1 and 2 can defer rekeying existing assets. Whenever that migration is performed, the same underlying requirements apply.

    I would make it an explicit administrative operation with the following stages.

    1. Prepare a dry run. Verify ownership, calculate the complete old-to-new ID mapping, identify affected history and references, and detect target conflicts. Account for targets occupied by other assets included in the migration.
    2. Quiesce affected operations. Pause gateway traffic, handle queued events, resolve pending deletions, and establish a consistent recovery point.
    3. Persist migration state. Keep synchronization and cleanup blocked across restarts until migration or recovery finishes.
    4. Rewrite the affected data. Update IDs, relationships, history, and supported references. Produce the ID translation and report references requiring manual changes.
    5. Validate and complete the cutover. Check the migrated data, update mapping versions or bindings, rebuild caches, and resume synchronization.
    6. Recover safely if interrupted. Support a defined resume or restore procedure.

    Merely changing a version attribute would cause the manager to interpret existing IDs differently and could lead cleanup to classify valid descendants as obsolete.

    For option 2, the operation could cover a selected asset or subtree. For option 1, it would normally cover the entire gateway. Option 3 makes this operation part of the initial rollout for existing installations.

    7. Decisions to agree on

    The main questions seem to be:

    1. Should V2 apply only to new gateway registrations, or also to new assets synchronized through existing gateways?
    2. Can rekeying existing assets remain an explicit follow-up operation, or must both reported gateways be brought back into service with preserved attributable history as part of this issue?
    3. If we choose mixed mappings, would we prefer per-asset version metadata, a frozen legacy ID set, or explicit bindings?
    4. What history and central references does each affected gateway currently have, and could either start with a fresh V2 registration?
12. wborn

    assigned

    richturner

    on Nov 3, 2026
13. richturner commented on Nov 3, 2026

    

    richturner

    on Nov 3, 2026

    MemberAuthor

    More actions

    I think Option 1 and V2 should only ever apply to newly created gateways, I suggest looking at the creation time of the gateway asset to decide whether to use V1 or V2.
14. wborn commented on Nov 5, 2026

    

    wborn

    on Nov 5, 2026

    Member

    More actions

    I looked into this a bit further. OpenRemote tracks database migrations through Flyway and exposes the current application version, but doesn't seem to persist when a particular application version was first deployed. We'd therefore need some additional persistent state to establish a reliable installation-specific cutoff timestamp.

    Since we only want V2 for newly created gateways, could we instead assign a mapping version when a gateway asset is first persisted? Existing gateways without a mapping version would default to V1, while newly created gateways would receive V2. This should work without a Flyway migration or any timestamp comparison, provided we preserve the mapping version across updates and imports.
15. richturner commented on Nov 5, 2026

    

    richturner

    on Nov 5, 2026

    MemberAuthor

    More actions

    The only issue I see with a mapping version attribute is it could be modified which it shouldn't.

    Persisting the timestamp when an instance is migrated to specific versions could solve this, maybe we introduce a new table to track version history?
16. wborn

    added 2 commits that reference this issue on Nov 5, 2026

    Prevent cross-gateway asset data leakage

    ...

    This issue will close once commit 1325e32 is merged into the 'main' branch.

    1325e32

    Prevent cross-gateway asset data leakage

    ...

    This issue will close once commit 418dd84 is merged into the 'main' branch.

    418dd84
17. wborn commented on Nov 5, 2026

    

    wborn

    on Nov 5, 2026

    Last edited by wborn

    Member

    More actions

    Persisting the timestamp when an instance is migrated to specific versions could solve this, maybe we introduce a new table to track version history?

    I gave this approach a try in #3547.