tile-identity-resolver 0.1.0__py3-none-any.whl

tile_identity_resolver/__init__.py

@@ -0,0 +1,6 @@
+"""Resolve configured Tiles from raw FEED service-data bytes."""
+
+from .models import Tile, TileInfo
+from .resolver import TileResolver
+
+__all__ = ["Tile", "TileInfo", "TileResolver"]

tile_identity_resolver/models.py

@@ -0,0 +1,50 @@
+"""Tile credentials and metadata decoded from a matching payload."""
+
+import base64
+from dataclasses import dataclass, field
+
+
+def _to_bytes(value: str | bytes) -> bytes:
+    """Accept raw bytes or decode hexadecimal or padded Base64 text."""
+    if isinstance(value, bytes):
+        return value
+    if not isinstance(value, str):
+        raise ValueError("Expected raw bytes, hexadecimal, or Base64 text")
+    value = value.strip()
+    if value.endswith("="):
+        return base64.b64decode(value, validate=True)
+    return bytes.fromhex(value)
+
+
+@dataclass(frozen=True, slots=True)
+class Tile:
+    """Immutable Tile credentials stored as text.
+
+    The ID is lowercase hex; the key is hex or padded Base64.
+    """
+
+    tile_id: str
+    auth_key: str = field(repr=False)
+
+    def __post_init__(self) -> None:
+        tile_id = _to_bytes(self.tile_id)
+        if len(tile_id) != 8 or tile_id.hex() != self.tile_id:
+            raise ValueError("Tile ID must be 16 lowercase hexadecimal digits")
+        if (
+            not isinstance(self.auth_key, str)
+            or len(_to_bytes(self.auth_key)) != 16
+        ):
+            raise ValueError("Auth key must decode to sixteen bytes")
+
+@dataclass(frozen=True, slots=True)
+class TileInfo:
+    """A registered Tile and metadata from one matching FEED payload.
+
+    A match does not establish freshness, proximity, or availability.
+    Flags are exposed verbatim; their meaning is not interpreted here.
+    """
+
+    tile: Tile
+    counter: int
+    version: int
+    flags: int

tile_identity_resolver/resolver.py

@@ -0,0 +1,110 @@
+"""Register Tile identities and resolve version-2 FEED payloads."""
+
+import hashlib
+import hmac
+from collections.abc import Iterable
+
+from .models import Tile, TileInfo, _to_bytes
+
+
+def _generate_private_ids(tile: Tile) -> dict[bytes, int]:
+    tile_id = bytes.fromhex(tile.tile_id)
+    auth_key = _to_bytes(tile.auth_key)
+    identity_message = tile_id + b"identity" + bytes(16)
+    identity_key = hmac.digest(auth_key, identity_message, hashlib.sha256)[:16]
+
+    private_ids = {}
+    for counter in range(8640):
+        counter_message = counter.to_bytes(4, "little") + bytes(28)
+        private_id = hmac.digest(
+            identity_key, counter_message, hashlib.sha256
+        )[:8]
+        private_ids[private_id] = counter
+    return private_ids
+
+
+class TileResolver:
+    """Resolve payloads against any number of registered Tiles.
+
+    Each resolver prepares and owns candidates for its registered Tiles.
+    Calls are synchronous; callers must serialize concurrent mutations.
+    """
+
+    def __init__(self, tiles: Iterable[Tile] = ()) -> None:
+        self._tiles: dict[str, Tile] = {}
+        self._private_ids: dict[str, list[bytes]] = {}
+        self._index: dict[
+            bytes, tuple[Tile, int] | dict[str, tuple[Tile, int]]
+        ] = {}
+        for tile in tiles:
+            self.add(tile)
+
+    @property
+    def tiles(self) -> tuple[Tile, ...]:
+        """Return a snapshot of Tiles in registration order."""
+        return tuple(self._tiles.values())
+
+    def add(self, tile: Tile) -> None:
+        """Register a Tile and prepare its candidate IDs.
+
+        Duplicate stable IDs raise ValueError. To change a key, remove
+        the existing Tile and add its replacement.
+        """
+        if not isinstance(tile, Tile):
+            raise TypeError("Expected a Tile")
+        if tile.tile_id in self._tiles:
+            raise ValueError("Tile ID is already registered")
+        private_ids = _generate_private_ids(tile)
+        self._tiles[tile.tile_id] = tile
+        self._private_ids[tile.tile_id] = list(private_ids)
+        for private_id, counter in private_ids.items():
+            match = (tile, counter)
+            owners = self._index.get(private_id)
+            if owners is None:
+                self._index[private_id] = match
+            elif isinstance(owners, tuple):
+                # Allocate an owners dictionary only for collisions.
+                self._index[private_id] = {
+                    owners[0].tile_id: owners,
+                    tile.tile_id: match,
+                }
+            else:
+                owners[tile.tile_id] = match
+
+    def remove(self, tile_id: str) -> None:
+        """Remove a Tile by hex ID; raise KeyError if it is unknown."""
+        del self._tiles[tile_id]
+        private_ids = self._private_ids.pop(tile_id)
+        for private_id in private_ids:
+            owners = self._index[private_id]
+            if isinstance(owners, tuple):
+                del self._index[private_id]
+            else:
+                del owners[tile_id]
+                if len(owners) == 1:
+                    self._index[private_id] = next(iter(owners.values()))
+
+    def resolve(
+        self, payload: bytes | bytearray | memoryview
+    ) -> TileInfo | None:
+        """Resolve FEED data without UUID or advertising headers.
+
+        Return None for short, unsupported, unknown, or ambiguous data.
+        Allow trailing bytes. Other input types raise TypeError.
+        No state is updated by resolving a payload.
+        """
+        if not isinstance(payload, (bytes, bytearray, memoryview)):
+            raise TypeError("Payload must be bytes, bytearray, or memoryview")
+        payload = bytes(payload)
+        if len(payload) < 10 or payload[0] != 2:
+            return None
+        match = self._index.get(payload[2:10])
+        if not isinstance(match, tuple):
+            return None
+        tile, counter = match
+        return TileInfo(
+            tile=tile,
+            counter=counter,
+            version=payload[0],
+            flags=payload[1],
+        )

tile_identity_resolver-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: tile-identity-resolver
+Version: 0.1.0
+Summary: Resolve Tile identities from FEED service data without Bluetooth dependencies
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kbck/tile-identity-resolver
+Project-URL: Repository, https://github.com/kbck/tile-identity-resolver
+Project-URL: Issues, https://github.com/kbck/tile-identity-resolver/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.11; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: mypy<3,>=1.15; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Requires-Dist: check-wheel-contents<1,>=0.6; extra == "dev"
+Dynamic: license-file
+
+# Tile Identity Resolver
+
+A dependency-free Python library for identifying registered Tile trackers from
+version-2 FEED service data. Requires Python 3.10 or newer.
+
+## Install
+
+```sh
+python -m pip install tile-identity-resolver
+```
+
+## Usage
+
+```python
+from tile_identity_resolver import Tile, TileResolver
+
+# Replace these example credentials with your Tile's ID and auth key.
+tile = Tile(
+    tile_id="0011223344556677",
+    auth_key="AAECAwQFBgcICQoLDA0ODw==",
+)
+resolver = TileResolver([tile])
+
+# Pass the raw service-data value for UUID 0000feed-0000-1000-8000-00805f9b34fb.
+def handle_feed_payload(payload: bytes) -> None:
+    info = resolver.resolve(payload)
+    if info is not None:
+        print(info.tile.tile_id, info.counter, info.version, info.flags)
+```
+
+Tile IDs are eight-byte lowercase hex strings. Auth keys are sixteen-byte hex
+or padded Base64 strings. Invalid credentials raise `ValueError`.
+
+## API
+
+| API | Behavior |
+| --- | --- |
+| `TileResolver(tiles=())` | Register one or more Tiles |
+| `resolver.add(tile)` | Register a Tile; duplicate IDs raise `ValueError` |
+| `resolver.remove(tile_id)` | Remove a Tile; missing IDs raise `KeyError` |
+| `resolver.tiles` | Immutable snapshot of registered Tiles |
+| `resolver.resolve(payload)` | Return `TileInfo` for an unambiguous match, otherwise `None` |
+
+`TileInfo` contains the registered `tile`, `counter`, `version`, and `flags`.
+Remove and re-add a Tile to replace its key.
+
+Registration precomputes private IDs and uses memory per Tile. In async apps,
+prepare the resolver in a worker thread and serialize access during mutations.
+The library resolves identities only; it does not track Bluetooth addresses or
+presence, and a match does not prove freshness or proximity.
+
+## Development
+
+```sh
+python -m pip install -e '.[dev]'
+python tools/check_package.py
+```
+
+Runs tests, code checks, and package validation.
+
+## Acknowledgements
+
+Based on [Security and Privacy Analysis of Tile's Location Tracking Protocol](https://www.usenix.org/conference/usenixsecurity26/presentation/kumar-akshaya)
+by Akshaya Kumar, Anna Raymaker, and Michael A. Specter (USENIX Security 2026).
+
+Unofficial; not affiliated with Tile or Life360.
+Licensed under the [MIT License](LICENSE).

tile_identity_resolver-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tile_identity_resolver/__init__.py,sha256=WCc0o5rQyWu746HhfnHk9w5-1fLC5ol-9TnDi8OiUGk,184
+tile_identity_resolver/models.py,sha256=ivtGhI_iwTDDBYGdNzqBdOYbhvMS91LwnoAtbv1sAyI,1528
+tile_identity_resolver/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tile_identity_resolver/resolver.py,sha256=wX7FHIILKL1H7ONhttxH0De4OCR-DmPsGlkRlEvEebs,4042
+tile_identity_resolver-0.1.0.dist-info/licenses/LICENSE,sha256=eFEuVhg0HsgE6Oyp3GhhpjOmPbqOm0h0MGqjKyQvXLM,1061
+tile_identity_resolver-0.1.0.dist-info/METADATA,sha256=Puee845Ff_-gsP0ZlQoOjzrTC1JCI_aGgIU_cBzLOpc,3288
+tile_identity_resolver-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+tile_identity_resolver-0.1.0.dist-info/top_level.txt,sha256=ajc8dYW6gQXUkNeAyXz5mPv6Syk9hZOy0FdA7jAAXP0,23
+tile_identity_resolver-0.1.0.dist-info/RECORD,,

tile_identity_resolver-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tile_identity_resolver-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kbck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tile_identity_resolver-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tile_identity_resolver