altifyhwid 1.1.0__py3-none-any.whl

altifyhwid-1.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: altifyhwid
+Version: 1.1.0
+Summary: Windows hardware identity matching across three or more hardware categories
+Author: Altify
+Keywords: hardware,hwid,windows,device,identity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Altify HWID
+
+Recognize a Windows device using three or more matching hardware categories.
+Python 3.10 or newer. No third-party runtime dependencies.
+
+## Install
+
+After the maintainer publishes this project to PyPI:
+
+```shell
+python -m pip install altifyhwid
+```
+
+The PyPI distribution name is `altifyhwid`; the Python import is `altifyhwid`.
+
+## Use
+
+```python
+import altifyhwid as hwid
+
+device_id = hwid.get_id()
+print(device_id)
+
+result = hwid.identify()
+print(result.to_dict())
+```
+
+Hardware collection is cached for 60 seconds per process. Database matching
+still runs on each call. When both the ID and details are needed, call
+`identify()` once and read `result.device_id`. Use `get_id(cache_ttl=0)` for a
+fresh scan or `clear_cache()` to discard cached snapshots.
+
+```python
+from altifyhwid import hwid
+
+print(hwid())
+```
+
+Default database on Windows:
+`%LOCALAPPDATA%\Altify\HWID\devices.sqlite3`.
+Preserve this database to preserve device IDs. Override it with `db_path` or
+the `ALTIFY_HWID_DB` environment variable. Explicit `db_path` takes priority.
+
+```python
+import altifyhwid
+
+# Reuse the registry created by the earlier standalone script:
+device_id = altifyhwid.get_id(
+    db_path=r"C:\MyApp\settings\AltifyHWID\devices.sqlite3"
+)
+
+# Match only, never write (no enrollment, no refresh, no last_seen update):
+device_id = altifyhwid.get_id(read_only=True, create=False)
+```
+
+`identify()` accepts `create=False` (match only), `refresh=False` (do not
+store newly seen hardware on a match), and `read_only=True` (open the
+database read-only; implies both). `IdentityResult.stored_kinds` lists the
+identifier kinds written to the registry by that call.
+
+## Command line
+
+```shell
+python -m altifyhwid --json
+python -m altifyhwid scan
+python -m altifyhwid scan --raw
+python -m altifyhwid --no-tpm --no-monitors
+python -m altifyhwid list
+python -m altifyhwid merge KEEP_ID ABSORB_ID
+python -m altifyhwid delete DEVICE_ID
+python -m altifyhwid -v
+altifyhwid --json
+```
+
+`scan` reports categories, counts, and collection warnings without saving an
+identity. `--raw` also prints hardware identifiers and diagnostic context.
+Programmatic diagnostic context is available with
+`collect(include_diagnostics=True)`. TPM is queried by default, but a missing
+or inaccessible endorsement public key contributes no match evidence.
+`--no-refresh`, `--no-create`, and `--read-only` mirror the API flags.
+`-v` logs collector timings, PowerShell exit codes with a stderr tail, and
+registry activity to stderr. Exit code 0 is success, 2 is a reported error
+(JSON on stderr), 1 is an unexpected error. Console entry point
+`altifyhwid` requires the Scripts directory of the environment on PATH; the
+`python -m altifyhwid` form works without that extra PATH requirement.
+
+## Matching
+
+The categories are firmware, storage, RAM, network, display, TPM public key,
+and CPU serial where available. Related SMBIOS fields together count as one
+firmware vote. Multiple disks or RAM modules do not multiply category votes.
+CPU/GPU models and ordinary CPU ProcessorId values do not count as unique IDs.
+
+A new enrollment gets a random UUID. Later scans reuse it when at least three
+categories match that enrollment. Use `min_matches=4` or higher to require
+more evidence.
+
+On a match the registry also stores identifiers it has not seen before for
+that device (a replaced disk, new RAM, a new network adapter), so gradual
+hardware changes keep the same ID as long as each scan still matches three
+categories. Old identifiers are kept, so a reverted swap still matches. Each
+device keeps at most 128 identifiers per kind; beyond that the oldest ones not
+present in the current scan are dropped. Pass `refresh=False` to disable this.
+
+Insufficient usable categories raise `InsufficientHardwareError`. `create=False`
+requires an existing match and otherwise raises `NoMatchError`.
+
+Multiple qualifying records raise `AmbiguousMatchError`; `.candidates` lists
+the two strongest, best first, each with `match_count`. Resolve it once with
+the registry tools below (usually `merge` the weaker into the stronger).
+
+## Registry maintenance
+
+```python
+from altifyhwid import Registry
+
+registry = Registry()                     # same defaults as identify()
+registry.list_devices()                   # dicts with device_id, created_at,
+                                          # last_seen, token_count, groups, kinds
+registry.list_devices(all_namespaces=True)
+registry.merge("ALTIFY-KEEP...", "ALTIFY-DUPLICATE...")
+registry.delete("ALTIFY-OLD...")
+registry.backup(r"D:\backups\devices.sqlite3")
+```
+
+`merge` moves the identifiers of the absorbed enrollments onto the kept one and
+removes the absorbed records. Both must be in the namespace of the registry.
+`delete` and `merge` refuse a `read_only=True` registry.
+
+## Integrity, backups, and schema
+
+Each registry path is checked with `PRAGMA quick_check` once per process. A
+corrupt or non-SQLite file raises `RegistryError` naming the newest backup.
+
+After any change to enrollments (a new device, stored identifiers, merge,
+delete) the registry writes `devices.sqlite3.bak1` next to the database, at
+most once per `backup_interval` seconds (default one day), and rotates older
+copies to `.bak2` and so on up to `backup_copies` (default 2; 0 disables).
+Backup failures are logged and never fail the identity call. To restore, stop
+the application and copy `.bak1` over `devices.sqlite3`.
+
+The database schema is version 2. A schema 1 registry (created by 1.0.x) is
+migrated automatically on the first writable open; a `read_only=True` open
+refuses it until then. A registry written by a newer module version is refused
+rather than modified.
+
+Only HMAC tokens are persisted, but the key is in the same database: this is
+pseudonymization, not encryption. No data is uploaded by this module. Collection
+uses read-only Windows queries, bounded worker threads, and timeouts. TPM and
+some provider queries can be unavailable under ordinary user permissions.
+
+## Logging
+
+The module logs to `logging.getLogger("altifyhwid")` and stays silent unless
+the application configures logging. `WARNING` covers failed collector batches
+(exit code, duration, last 2 KiB of PowerShell stderr), ambiguous matches,
+rollback problems, and failed automatic backups. `INFO` covers enrollments,
+migrations, backups, and scan summaries. `DEBUG` covers per-batch timings and
+match details. Hardware identifiers are never logged.
+
+## Scope
+
+Hardware collection requires Windows. Registry matching can run elsewhere with
+an explicitly supplied `HardwareSnapshot`. Separate registry databases produce
+separate IDs; installing this package does not create a shared identity service.
+For multiple clients, use a trusted central registry through your own
+authenticated transport. Client-supplied hardware values are not attestation.
+
+This is heuristic recognition, not a guarantee of uniqueness or resistance to
+spoofing. Shared components, OEM duplicates, cloned VMs, and extensive hardware
+changes can produce incorrect matches or new IDs. Storing newly seen hardware
+on a match also means a wrong match teaches the wrong record; raise
+`min_matches` or set `refresh=False` where that matters. Proprietary kernel
+anti-cheat internals are not implemented.
+
+## Resource limits
+
+Collection uses at most four concurrent workers and an overall deadline. One
+scan runs at a time per process; a caller waits up to `timeout` seconds for an
+active scan, then gets the cached result when the same options were scanned,
+or runs its own scan with a fresh deadline. Cache reads and `clear_cache()`
+never wait behind a scan. The scan cache holds at most eight immutable
+snapshots. No workers run between calls. Provider results are limited to 128
+rows and Python reads at most 2 MiB of output per collector batch. SQLite
+connections and temporary output files close when each operation completes.
+
+The registry uses SQLite WAL mode, so readers never block the single writer.
+Opening an existing registry takes no write lock; only enrollment, refresh,
+merge, delete, and migration do. Backup has a deadline and removes incomplete
+output on failure. Matching uses an index and retrieves at most two qualifying
+records to detect ambiguity.
+
+## Tests
+
+```shell
+py -m unittest discover -s tests -v
+```
+
+The suite covers normalization, snapshot building from recorded provider
+output, enrollment and matching, refresh and its cap, ambiguity and merge,
+read-only mode, schema migration, integrity failures, backups and rotation,
+collector caching and locking, PowerShell failure handling, and the command
+line. It runs without hardware access. `ALTIFY_LIVE=1` adds one live
+collection on the current Windows PC.

altifyhwid-1.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+altifyhwid.py,sha256=qIae8omdkuD84AjPqoimexltL7Ot26Ud60d609tWqrs,44952
+altifyhwid-1.1.0.dist-info/METADATA,sha256=zGcW_dzj-2ApAl-uwB6LpktVXyjmcIRSpgNGpO15fjQ,9408
+altifyhwid-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+altifyhwid-1.1.0.dist-info/entry_points.txt,sha256=sPSjY8P4GoX_fmbcavqxLS_SiR-OEP4F7w5ScVCGTPk,48
+altifyhwid-1.1.0.dist-info/top_level.txt,sha256=oWe5IZM2QrUrqlmQIMoxigdpC4RjzZneaWWP8x24bDs,11
+altifyhwid-1.1.0.dist-info/RECORD,,

altifyhwid-1.1.0.dist-info/WHEEL

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

altifyhwid-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+altifyhwid = altifyhwid:_main

altifyhwid-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+altifyhwid

altifyhwid.py

@@ -0,0 +1,714 @@
+from __future__ import annotations
+import argparse
+import base64
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from collections import OrderedDict
+from contextlib import closing, contextmanager
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import hmac
+import json
+import logging
+import math
+import os
+from pathlib import Path
+import re
+import secrets
+import sqlite3
+import subprocess
+import sys
+import tempfile
+from threading import Lock
+from time import monotonic, time
+from types import MappingProxyType
+from typing import Any, Mapping
+import unicodedata
+import uuid
+__version__ = '1.1.0'
+__all__ = ['get_id', 'hwid', 'identify', 'collect', 'clear_cache', 'Registry', 'HardwareSnapshot', 'IdentityResult', 'AltifyError', 'CollectionError', 'RegistryError', 'InsufficientHardwareError', 'AmbiguousMatchError', 'NoMatchError']
+_LOG = logging.getLogger('altifyhwid')
+_LOG.addHandler(logging.NullHandler())
+_KINDS = {'system_uuid': 'firmware', 'system_serial': 'firmware', 'baseboard_serial': 'firmware', 'bios_serial': 'firmware', 'chassis_serial': 'firmware', 'disk_serial': 'storage', 'disk_unique_id': 'storage', 'ram_serial': 'memory', 'nic_permanent_mac': 'network', 'nic_mac': 'network', 'tpm_ek_sha256': 'tpm', 'monitor_serial': 'display', 'cpu_serial': 'cpu'}
+_PLACEHOLDERS = {'UNKNOWN', 'NONE', 'NULL', 'NA', 'NOTAPPLICABLE', 'NOTAVAILABLE', 'NOTSPECIFIED', 'UNSPECIFIED', 'INVALID', 'DEFAULT', 'DEFAULTSTRING', 'SYSTEMSERIALNUMBER', 'SERIALNUMBER', 'CHASSISSERIALNUMBER', 'BASEBOARDSERIALNUMBER', 'OEM', '0123456789', '123456789', '1234567890', '0123456789ABCDEF', '12345678', 'SYSTEMUUID', 'NOASSETTAG'}
+_SCHEMA = 2
+_MAX_OUTPUT = 2 * 1024 * 1024
+_STDERR_TAIL = 2048
+_TOKEN_CAP = 128
+_CACHE = OrderedDict()
+_CACHE_LOCK = Lock()
+_SCAN_LOCK = Lock()
+_CHECKED = OrderedDict()
+_CHECKED_LOCK = Lock()
+_GROUP_SQL = 'CASE t.kind ' + ' '.join((f"WHEN '{kind}' THEN '{group}'" for kind, group in _KINDS.items())) + ' END'
+_MATCH_SQL = 'SELECT t.device_id,GROUP_CONCAT(DISTINCT t.kind),COUNT(DISTINCT ' + _GROUP_SQL + ') AS n FROM incoming i CROSS JOIN tokens t INDEXED BY tokens_lookup JOIN devices d ON d.device_id=t.device_id WHERE t.kind=i.kind AND t.digest=i.digest AND d.namespace=? GROUP BY t.device_id HAVING n>=? ORDER BY n DESC,t.device_id LIMIT 2'
+_LIST_SQL = 'SELECT d.device_id,d.namespace,d.created_at,d.last_seen,COUNT(t.digest),GROUP_CONCAT(DISTINCT t.kind) FROM devices d LEFT JOIN tokens t ON t.device_id=d.device_id {where} GROUP BY d.device_id ORDER BY d.created_at,d.rowid'
+class AltifyError(RuntimeError):
+    pass
+class CollectionError(AltifyError):
+    pass
+class RegistryError(AltifyError):
+    pass
+class NoMatchError(AltifyError):
+    pass
+class InsufficientHardwareError(AltifyError):
+    def __init__(self, groups: tuple[str, ...], minimum: int, warnings=()):
+        self.groups, self.minimum, self.warnings = (groups, minimum, tuple(warnings))
+        super().__init__(f"Need {minimum} hardware groups; found {len(groups)} ({', '.join(groups) or 'none'}). Run: py -m altifyhwid scan")
+class AmbiguousMatchError(AltifyError):
+    def __init__(self, candidates: tuple[dict[str, Any], ...]):
+        self.candidates = candidates
+        super().__init__('Multiple records meet the threshold. No record selected; .candidates lists the two strongest. Run: py -m altifyhwid list, then merge or delete the duplicates')
+def _default_registry_path() -> Path:
+    override = os.environ.get('ALTIFY_HWID_DB')
+    if override:
+        return Path(override).expanduser()
+    if sys.platform == 'win32':
+        base = Path(os.environ.get('LOCALAPPDATA') or Path.home() / 'AppData' / 'Local')
+    elif sys.platform == 'darwin':
+        base = Path.home() / 'Library' / 'Application Support'
+    else:
+        base = Path(os.environ.get('XDG_DATA_HOME') or Path.home() / '.local' / 'share')
+    return base / 'Altify' / 'HWID' / 'devices.sqlite3'
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec='seconds')
+def _normalize(kind: str, value: Any) -> str | None:
+    if not isinstance(value, str) or len(value) > 1024:
+        return None
+    value = re.sub('\\s+', '', unicodedata.normalize('NFKC', value).upper().strip('\x00 '))
+    compact = re.sub('[^A-Z0-9]', '', value)
+    if len(compact) < 4 or compact in _PLACEHOLDERS or len(set(compact)) == 1 or any((s in compact for s in ('TOBEFILLEDBY', 'NOTSPECIFIED', 'DEFAULTSTRING'))):
+        return None
+    if kind == 'system_uuid':
+        try:
+            parsed = uuid.UUID(value)
+        except ValueError:
+            return None
+        if parsed.int in (0, (1 << 128) - 1):
+            return None
+        return str(parsed).upper()
+    if kind in ('nic_mac', 'nic_permanent_mac'):
+        mac = re.sub('[:-]', '', value)
+        if not re.fullmatch('[0-9A-F]{12}', mac) or int(mac[:2], 16) & 3:
+            return None
+        return mac
+    if kind == 'tpm_ek_sha256':
+        value = re.sub('[:-]', '', value)
+        if not re.fullmatch('[0-9A-F]{64}', value):
+            return None
+    return value
+def _freeze(value):
+    if isinstance(value, Mapping):
+        return MappingProxyType({k: _freeze(v) for k, v in value.items()})
+    if isinstance(value, (list, tuple)):
+        return tuple(map(_freeze, value))
+    return value
+def _plain(value):
+    if isinstance(value, Mapping):
+        return {k: _plain(v) for k, v in value.items()}
+    if isinstance(value, tuple):
+        return list(map(_plain, value))
+    return value
+@dataclass(frozen=True, slots=True)
+class HardwareSnapshot:
+    signals: Mapping[str, tuple[str, ...]]
+    diagnostics: Mapping[str, Any] = field(default_factory=dict)
+    warnings: tuple[str, ...] = ()
+    collected_at: str = field(default_factory=_now)
+    _groups: tuple[str, ...] = field(init=False, repr=False)
+    def __post_init__(self):
+        if not isinstance(self.signals, Mapping) or set(self.signals) - _KINDS.keys():
+            raise ValueError('signals must contain supported identifier kinds')
+        cleaned, total = ({}, 0)
+        for kind, values in self.signals.items():
+            if isinstance(values, str):
+                values = (values,)
+            if not isinstance(values, (tuple, list, set)) or len(values) > 128:
+                raise ValueError(f'{kind}: supply at most 128 strings')
+            total += len(values)
+            if total > 512 or any((not isinstance(v, str) for v in values)):
+                raise ValueError('Snapshot permits at most 512 string identifiers')
+            values = tuple(sorted({v for raw in values if (v := _normalize(kind, raw))}))
+            if values:
+                cleaned[kind] = values
+        object.__setattr__(self, 'signals', MappingProxyType(cleaned))
+        object.__setattr__(self, 'diagnostics', _freeze(self.diagnostics))
+        object.__setattr__(self, 'warnings', tuple(self.warnings))
+        object.__setattr__(self, '_groups', tuple(sorted({_KINDS[k] for k in cleaned})))
+    @classmethod
+    def from_signals(cls, signals: Mapping[str, Any], **kwargs) -> HardwareSnapshot:
+        return cls(signals, **kwargs)
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> HardwareSnapshot:
+        if not isinstance(payload, Mapping) or payload.get('format') != 'altify-hwid-v1':
+            raise ValueError('Expected altify-hwid-v1 snapshot')
+        if payload.get('redacted') is not False or 'signals' not in payload:
+            raise ValueError('Snapshot is redacted; export with to_dict(raw=True)')
+        return cls(payload['signals'])
+    @property
+    def groups(self) -> tuple[str, ...]:
+        return self._groups
+    def to_dict(self, *, raw: bool=False) -> dict[str, Any]:
+        result = {'format': 'altify-hwid-v1', 'redacted': not raw, 'collected_at': self.collected_at, 'groups': list(self.groups), 'counts': {k: len(v) for k, v in self.signals.items()}, 'warnings': list(self.warnings)}
+        if raw:
+            result['signals'] = {k: list(v) for k, v in self.signals.items()}
+            result['diagnostics'] = _plain(self.diagnostics)
+        return result
+@dataclass(frozen=True, slots=True)
+class IdentityResult:
+    device_id: str
+    created: bool
+    matched_groups: tuple[str, ...]
+    matched_kinds: tuple[str, ...]
+    available_groups: tuple[str, ...]
+    warnings: tuple[str, ...]
+    stored_kinds: tuple[str, ...] = ()
+    @property
+    def match_count(self) -> int:
+        return len(self.matched_groups)
+    def to_dict(self) -> dict[str, Any]:
+        return {'device_id': self.device_id, 'created': self.created, 'match_count': self.match_count, 'matched_groups': list(self.matched_groups), 'matched_kinds': list(self.matched_kinds), 'available_groups': list(self.available_groups), 'stored_kinds': list(self.stored_kinds), 'warnings': list(self.warnings)}
+_PS_HEADER = '\n$ErrorActionPreference = \'Stop\'\n$ProgressPreference = \'SilentlyContinue\'\n$WarningPreference = \'SilentlyContinue\'\n[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)\n$OutputEncoding = [Console]::OutputEncoding\n$out = [ordered]@{data=@{}; errors=@()}\nfunction Read-Cim($key, $class, $properties, $namespace=\'root/cimv2\') {\n    try {\n        $rows = @(Get-CimInstance -ClassName $class -Namespace $namespace `\n            -Property $properties -OperationTimeoutSec 5 -ErrorAction Stop |\n            Select-Object -First 129 -Property $properties)\n        if ($rows.Count -gt 128) { throw \'Provider row limit exceeded\' }\n        $out.data[$key] = $rows\n    } catch {\n        $rows = @()\n        $out.errors += "$key unavailable ($($_.Exception.GetType().Name))"\n    }\n}\n'
+_BATCHES = {'firmware': "\nRead-Cim 'system' 'Win32_ComputerSystemProduct' @('UUID','IdentifyingNumber','Vendor','Name')\nRead-Cim 'board' 'Win32_BaseBoard' @('SerialNumber','Manufacturer','Product')\nRead-Cim 'bios' 'Win32_BIOS' @('SerialNumber','Manufacturer','SMBIOSBIOSVersion')\nRead-Cim 'chassis' 'Win32_SystemEnclosure' @('SerialNumber')\nRead-Cim 'cpu' 'Win32_Processor' @('SerialNumber','ProcessorId','Name','Manufacturer')\n", 'storage': "\nRead-Cim 'physical_disks' 'MSFT_PhysicalDisk' @('SerialNumber','UniqueId','UniqueIdFormat','BusType','FriendlyName') 'root/Microsoft/Windows/Storage'\nRead-Cim 'disks' 'Win32_DiskDrive' @('SerialNumber','InterfaceType','Model','PNPDeviceID')\n", 'memory_network': "\nRead-Cim 'memory' 'Win32_PhysicalMemory' @('SerialNumber','Manufacturer','PartNumber','Capacity')\nRead-Cim 'adapters' 'MSFT_NetAdapter' @('PermanentAddress','HardwareInterface','Virtual','InterfaceDescription','PNPDeviceID') 'root/StandardCimv2'\nRead-Cim 'legacy_adapters' 'Win32_NetworkAdapter' @('MACAddress','PhysicalAdapter','Name','PNPDeviceID')\n", 'context': "\nRead-Cim 'gpu' 'Win32_VideoController' @('Name','PNPDeviceID','DriverVersion')\ntry {\n    $out.data['windows'] = @{MachineGuid=(Get-ItemProperty -LiteralPath 'HKLM:\\SOFTWARE\\Microsoft\\Cryptography' -Name MachineGuid -ErrorAction Stop).MachineGuid}\n} catch { $out.errors += 'Windows installation context unavailable' }\n", 'monitors': "\nRead-Cim 'monitors' 'WmiMonitorID' @('ManufacturerName','ProductCodeID','SerialNumberID','Active') 'root/wmi'\n", 'tpm': '\ntry {\n    $ek = Get-TpmEndorsementKeyInfo -HashAlgorithm Sha256 -ErrorAction Stop\n    if ($ek.IsPresent -and $ek.PublicKeyHash) {\n        $out.data[\'tpm\'] = @{PublicKeyHash=[string]$ek.PublicKeyHash}\n    } else { $out.errors += \'TPM endorsement public key unavailable\' }\n} catch { $out.errors += "TPM public key unavailable ($($_.Exception.GetType().Name)); try an elevated host if needed" }\n'}
+def _powershell_exe() -> str:
+    root = Path(os.environ.get('SystemRoot', 'C:\\Windows'))
+    for system in ('Sysnative', 'System32'):
+        exe = root / system / 'WindowsPowerShell' / 'v1.0' / 'powershell.exe'
+        if exe.is_file():
+            return str(exe)
+    raise CollectionError('Windows PowerShell was not found in the Windows directory')
+def _tail(handle) -> str:
+    handle.seek(0, os.SEEK_END)
+    handle.seek(max(0, handle.tell() - _STDERR_TAIL))
+    return handle.read().decode('utf-8', 'replace').strip()
+def _run_batch(exe: str, name: str, timeout: float) -> dict[str, Any]:
+    if timeout <= 0:
+        _LOG.warning('%s: collection deadline reached before the batch started', name)
+        return {'errors': [f'{name}: collection deadline reached']}
+    script = _PS_HEADER + _BATCHES[name] + '\n$out | ConvertTo-Json -Depth 8 -Compress\n'
+    encoded = base64.b64encode(script.encode('utf-16-le')).decode('ascii')
+    started = monotonic()
+    try:
+        with tempfile.TemporaryFile() as output, tempfile.TemporaryFile() as errors:
+            proc = subprocess.run([exe, '-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', encoded], stdin=subprocess.DEVNULL, stdout=output, stderr=errors, timeout=timeout, check=False, creationflags=getattr(subprocess, 'CREATE_NO_WINDOW', 0))
+            elapsed = monotonic() - started
+            if proc.returncode:
+                _LOG.warning('%s: PowerShell exited with code %d after %.1fs: %s', name, proc.returncode, elapsed, _tail(errors) or 'no stderr')
+                return {'errors': [f'{name}: PowerShell exited with code {proc.returncode}']}
+            output.seek(0, os.SEEK_END)
+            if output.tell() > _MAX_OUTPUT:
+                raise ValueError('Collector output limit exceeded')
+            output.seek(0)
+            raw = output.read(_MAX_OUTPUT + 1)
+        if len(raw) > _MAX_OUTPUT:
+            raise ValueError('Collector output limit exceeded')
+        result = json.loads(raw.decode('utf-8-sig'))
+        if not isinstance(result, dict) or not isinstance(result.get('data'), dict):
+            raise ValueError('Invalid collector response')
+        _LOG.debug('%s: collected %d bytes in %.1fs with %d provider errors', name, len(raw), elapsed, len(result.get('errors') or []))
+        return result
+    except subprocess.TimeoutExpired:
+        _LOG.warning('%s: collection timed out after %.1fs', name, timeout)
+        return {'errors': [f'{name}: collection timed out']}
+    except (OSError, UnicodeError, ValueError) as exc:
+        _LOG.warning('%s: collection failed after %.1fs (%s: %s)', name, monotonic() - started, type(exc).__name__, exc)
+        return {'errors': [f'{name}: collection failed ({type(exc).__name__})']}
+def _rows(data: Mapping[str, Any], key: str) -> list[dict[str, Any]]:
+    value = data.get(key, [])
+    return [value] if isinstance(value, dict) else [r for r in value or [] if isinstance(r, dict)]
+def _edid_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value.strip('\x00 ')
+    if not isinstance(value, list):
+        return ''
+    return ''.join((chr(n) for n in value if isinstance(n, int) and 32 <= n < 127)).strip()
+def _looks_virtual(value: Any) -> bool:
+    text = str(value or '').upper()
+    return any((word in text for word in ('VIRTUAL', 'VMWARE', 'VBOX', 'VIRTIO', 'QEMU', 'XEN ', 'HYPER-V', 'TAP-WINDOWS', 'TUNNEL')))
+def _snapshot_from_data(data: Mapping[str, Any], warnings=(), include_diagnostics=False) -> HardwareSnapshot:
+    signals: dict[str, list[str]] = {}
+    def add(kind, value):
+        normalized = _normalize(kind, value)
+        if normalized:
+            signals.setdefault(kind, []).append(normalized)
+    for section, prop, kind in (('system', 'UUID', 'system_uuid'), ('system', 'IdentifyingNumber', 'system_serial'), ('board', 'SerialNumber', 'baseboard_serial'), ('bios', 'SerialNumber', 'bios_serial'), ('chassis', 'SerialNumber', 'chassis_serial'), ('cpu', 'SerialNumber', 'cpu_serial'), ('memory', 'SerialNumber', 'ram_serial'), ('tpm', 'PublicKeyHash', 'tpm_ek_sha256')):
+        for row in _rows(data, section):
+            add(kind, row.get(prop))
+    for row in _rows(data, 'physical_disks'):
+        if row.get('BusType') not in (1, 2, 3, 4, 6, 8, 10, 11, 17, 18):
+            continue
+        if _looks_virtual(row.get('FriendlyName')):
+            continue
+        add('disk_serial', row.get('SerialNumber'))
+        if row.get('UniqueIdFormat') in (2, 3, 8):
+            add('disk_unique_id', row.get('UniqueId'))
+    for row in _rows(data, 'disks'):
+        pnp = str(row.get('PNPDeviceID') or '').upper()
+        if str(row.get('InterfaceType') or '').upper() == 'USB' or pnp.startswith('USB'):
+            continue
+        if not _looks_virtual(row.get('Model')):
+            add('disk_serial', row.get('SerialNumber'))
+    permanent_pnp = set()
+    for row in _rows(data, 'adapters'):
+        if row.get('HardwareInterface') is not True or row.get('Virtual') is True:
+            continue
+        if _looks_virtual(row.get('InterfaceDescription')):
+            continue
+        value = _normalize('nic_permanent_mac', row.get('PermanentAddress'))
+        if value:
+            add('nic_permanent_mac', value)
+            permanent_pnp.add(str(row.get('PNPDeviceID') or '').upper())
+    for row in _rows(data, 'legacy_adapters'):
+        pnp = str(row.get('PNPDeviceID') or '').upper()
+        if row.get('PhysicalAdapter') is not True or _looks_virtual(row.get('Name')) or (not pnp.startswith(('PCI\\', 'USB\\'))):
+            continue
+        if pnp not in permanent_pnp:
+            add('nic_permanent_mac', row.get('MACAddress'))
+    for row in _rows(data, 'monitors'):
+        if row.get('Active') is not True:
+            continue
+        serial = _edid_text(row.get('SerialNumberID'))
+        maker = _edid_text(row.get('ManufacturerName'))
+        model = _edid_text(row.get('ProductCodeID'))
+        if _normalize('monitor_serial', serial) and maker and model:
+            add('monitor_serial', f'{maker}|{model}|{serial}')
+    return HardwareSnapshot.from_signals(signals, diagnostics=data if include_diagnostics else {}, warnings=tuple(warnings))
+def clear_cache() -> None:
+    with _CACHE_LOCK:
+        _CACHE.clear()
+def _cache_get(key, cache_ttl: float) -> HardwareSnapshot | None:
+    with _CACHE_LOCK:
+        cached = _CACHE.get(key)
+        if cached and cache_ttl and monotonic() - cached[0] < cache_ttl:
+            _CACHE.move_to_end(key)
+            return cached[1]
+        _CACHE.pop(key, None)
+    return None
+def collect(*, include_tpm: bool=True, include_monitors: bool=True, include_diagnostics: bool=False, timeout: float=35.0, cache_ttl: float=60.0) -> HardwareSnapshot:
+    if sys.platform != 'win32':
+        raise CollectionError('Live hardware collection requires Windows 10/11. Registry works cross-platform.')
+    if type(timeout) not in (float, int) or not math.isfinite(timeout) or (not 1 <= timeout <= 300):
+        raise ValueError('timeout must be between 1 and 300 seconds')
+    if type(cache_ttl) not in (float, int) or not math.isfinite(cache_ttl) or (not 0 <= cache_ttl <= 3600):
+        raise ValueError('cache_ttl must be between 0 and 3600 seconds')
+    key = (bool(include_tpm), bool(include_monitors), bool(include_diagnostics))
+    cached = _cache_get(key, cache_ttl)
+    if cached is not None:
+        return cached
+    if not _SCAN_LOCK.acquire(timeout=timeout):
+        raise CollectionError('Timed out waiting for an active hardware scan')
+    try:
+        cached = _cache_get(key, cache_ttl)
+        if cached is not None:
+            return cached
+        exe = _powershell_exe()
+        names = ['firmware', 'storage', 'memory_network']
+        if include_diagnostics:
+            names.append('context')
+        if include_monitors:
+            names.append('monitors')
+        if include_tpm:
+            names.append('tpm')
+        deadline = monotonic() + timeout
+        _LOG.debug('Scanning batches %s with a %.0fs deadline', ','.join(names), timeout)
+        data, warnings = ({}, [])
+        def run(name):
+            return _run_batch(exe, name, deadline - monotonic())
+        with ThreadPoolExecutor(max_workers=4, thread_name_prefix='AltifyHWID') as pool:
+            jobs = {pool.submit(run, name) for name in names}
+            for job in as_completed(jobs):
+                jobs.remove(job)
+                result = job.result()
+                data.update(result.get('data', {}))
+                warnings.extend(result.get('errors', []))
+        snapshot = _snapshot_from_data(data, warnings, include_diagnostics)
+        _LOG.info('Collected %d hardware groups (%s) with %d warnings in %.1fs', len(snapshot.groups), ','.join(snapshot.groups) or 'none', len(warnings), timeout - (deadline - monotonic()))
+        if len(snapshot.groups) >= 3:
+            with _CACHE_LOCK:
+                _CACHE[key] = (monotonic(), snapshot)
+                while len(_CACHE) > 8:
+                    _CACHE.popitem(last=False)
+        return snapshot
+    finally:
+        _SCAN_LOCK.release()
+def _migrate_1(con: sqlite3.Connection) -> None:
+    con.execute("ALTER TABLE tokens ADD COLUMN added_at TEXT NOT NULL DEFAULT ''")
+    con.execute("UPDATE tokens SET added_at=(SELECT created_at FROM devices WHERE devices.device_id=tokens.device_id) WHERE added_at=''")
+_MIGRATIONS = {1: _migrate_1}
+def _rollback(con: sqlite3.Connection | None) -> None:
+    if con is not None and con.in_transaction:
+        try:
+            con.rollback()
+        except sqlite3.Error as exc:
+            _LOG.warning('Rollback failed: %s', exc)
+class Registry:
+    __slots__ = ('namespace', 'min_matches', 'path', 'read_only', 'backup_copies', 'backup_interval', '_key')
+    def __init__(self, db_path: str | os.PathLike | None=None, *, namespace: str='default', min_matches: int=3, read_only: bool=False, backup_copies: int=2, backup_interval: float=86400.0):
+        if type(min_matches) is not int or not 3 <= min_matches <= len(set(_KINDS.values())):
+            raise ValueError('min_matches must be an integer between 3 and 7')
+        if not isinstance(namespace, str) or not namespace.strip() or len(namespace) > 128:
+            raise ValueError('namespace must contain 1 to 128 characters')
+        if type(backup_copies) is not int or not 0 <= backup_copies <= 16:
+            raise ValueError('backup_copies must be an integer between 0 and 16')
+        if type(backup_interval) not in (float, int) or not math.isfinite(backup_interval) or backup_interval < 0:
+            raise ValueError('backup_interval must be zero or more seconds')
+        self.namespace, self.min_matches, self.read_only = (namespace, min_matches, bool(read_only))
+        self.backup_copies, self.backup_interval = (backup_copies, backup_interval)
+        self.path = (Path(db_path).expanduser() if db_path is not None else _default_registry_path()).resolve()
+        self._key = None
+        try:
+            if self.read_only:
+                if not self.path.is_file():
+                    raise RegistryError(f'Registry {self.path} does not exist; a read-only registry cannot be created')
+            else:
+                self.path.parent.mkdir(parents=True, exist_ok=True)
+            self._check_integrity()
+            with self._transaction(write=False) as con:
+                key = self._load(con)
+            if key is None:
+                if self.read_only:
+                    raise RegistryError(f'Registry {self.path} needs initialization or a schema migration; open it without read_only first')
+                with self._transaction() as con:
+                    key = self._load(con) or self._setup(con)
+            self._key = key
+        except OSError as exc:
+            raise RegistryError(f'Cannot access registry {self.path}: {exc}') from exc
+    def _connect(self) -> sqlite3.Connection:
+        if self.read_only:
+            con = sqlite3.connect(self.path.as_uri() + '?mode=ro', uri=True, timeout=30, isolation_level=None)
+        else:
+            con = sqlite3.connect(str(self.path), timeout=30, isolation_level=None)
+        try:
+            if not self.read_only:
+                try:
+                    mode = con.execute('PRAGMA journal_mode=WAL').fetchone()[0]
+                    if str(mode).lower() != 'wal':
+                        _LOG.debug('Registry %s stays in journal mode %s', self.path, mode)
+                except sqlite3.OperationalError as exc:
+                    _LOG.debug('Could not enable WAL on %s: %s', self.path, exc)
+            con.execute('PRAGMA foreign_keys=ON')
+            con.execute('PRAGMA synchronous=FULL')
+        except BaseException:
+            con.close()
+            raise
+        return con
+    @contextmanager
+    def _transaction(self, write: bool=True):
+        con = None
+        try:
+            con = self._connect()
+            con.execute('BEGIN IMMEDIATE' if write and not self.read_only else 'BEGIN')
+            yield con
+            con.execute('COMMIT')
+        except sqlite3.Error as exc:
+            _rollback(con)
+            raise RegistryError(f'Registry database error: {exc}') from exc
+        except BaseException:
+            _rollback(con)
+            raise
+        finally:
+            if con is not None:
+                con.close()
+    def _check_integrity(self) -> None:
+        with _CHECKED_LOCK:
+            if self.path in _CHECKED:
+                _CHECKED.move_to_end(self.path)
+                return
+        if not self.path.is_file() or self.path.stat().st_size == 0:
+            return
+        try:
+            with closing(self._connect()) as con:
+                row = con.execute('PRAGMA quick_check(1)').fetchone()
+        except sqlite3.Error as exc:
+            raise RegistryError(f'Registry {self.path} is unreadable ({exc}); restore it from {self._backup_path(1)}') from exc
+        if not row or row[0] != 'ok':
+            raise RegistryError(f"Registry {self.path} failed its integrity check ({row[0] if row else 'no result'}); restore it from {self._backup_path(1)}")
+        with _CHECKED_LOCK:
+            _CHECKED[self.path] = True
+            while len(_CHECKED) > 64:
+                _CHECKED.popitem(last=False)
+    @staticmethod
+    def _tables(con: sqlite3.Connection) -> set[str]:
+        return {r[0] for r in con.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+    @staticmethod
+    def _version(text: Any) -> int:
+        if not isinstance(text, str) or not text.isdigit():
+            raise RegistryError('Unsupported registry schema; preserve the database and use its original API version')
+        version = int(text)
+        if version > _SCHEMA:
+            raise RegistryError(f'Registry schema {version} is newer than this module supports ({_SCHEMA}); upgrade altifyhwid')
+        return version
+    @staticmethod
+    def _read_key(con: sqlite3.Connection) -> bytes:
+        key = con.execute("SELECT value FROM meta WHERE key='hmac_key'").fetchone()
+        if not key or not isinstance(key[0], str) or not re.fullmatch('[0-9a-f]{64}', key[0]):
+            raise RegistryError('Registry HMAC key is missing/corrupt; restore a complete backup')
+        return bytes.fromhex(key[0])
+    def _load(self, con: sqlite3.Connection) -> bytes | None:
+        tables = self._tables(con)
+        if 'meta' not in tables:
+            return None
+        row = con.execute("SELECT value FROM meta WHERE key='schema'").fetchone()
+        if not row or self._version(row[0]) < _SCHEMA:
+            return None
+        if not {'devices', 'tokens'} <= tables:
+            raise RegistryError('Registry tables are missing; restore a complete backup')
+        return self._read_key(con)
+    def _setup(self, con: sqlite3.Connection) -> bytes:
+        tables = self._tables(con)
+        row = con.execute("SELECT value FROM meta WHERE key='schema'").fetchone() if 'meta' in tables else None
+        if row is None:
+            if tables - {'meta'} or ('meta' in tables and con.execute('SELECT COUNT(*) FROM meta').fetchone()[0]):
+                raise RegistryError('Database is not a new or recognized Altify registry')
+            con.execute('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)')
+            con.executemany('INSERT INTO meta VALUES (?,?)', [('schema', str(_SCHEMA)), ('hmac_key', secrets.token_hex(32))])
+            con.execute('CREATE TABLE devices (device_id TEXT PRIMARY KEY, namespace TEXT NOT NULL, created_at TEXT NOT NULL, last_seen TEXT NOT NULL)')
+            con.execute("CREATE TABLE tokens (device_id TEXT NOT NULL REFERENCES devices(device_id) ON DELETE CASCADE, kind TEXT NOT NULL, digest TEXT NOT NULL, added_at TEXT NOT NULL DEFAULT '', PRIMARY KEY(device_id, kind, digest))")
+            con.execute('CREATE INDEX tokens_lookup ON tokens(kind,digest)')
+            _LOG.info('Created registry %s (schema %d)', self.path, _SCHEMA)
+        else:
+            version = self._version(row[0])
+            if not {'devices', 'tokens'} <= tables:
+                raise RegistryError('Registry tables are missing; restore a complete backup')
+            while version < _SCHEMA:
+                _MIGRATIONS[version](con)
+                version += 1
+                con.execute("UPDATE meta SET value=? WHERE key='schema'", (str(version),))
+                _LOG.info('Migrated registry %s to schema %d', self.path, version)
+        return self._read_key(con)
+    def _digest(self, kind: str, value: str) -> str:
+        payload = json.dumps(['altify-hwid-v1', self.namespace, kind, value], ensure_ascii=True, separators=(',', ':')).encode('ascii')
+        return hmac.digest(self._key, payload, 'sha256').hex()
+    def _check_key(self, con: sqlite3.Connection) -> None:
+        current_key = con.execute("SELECT value FROM meta WHERE key='hmac_key'").fetchone()
+        if not current_key or current_key[0] != self._key.hex():
+            raise RegistryError('Registry key changed while this instance was open; reopen the registry')
+    def _require_writable(self) -> None:
+        if self.read_only:
+            raise RegistryError('Registry was opened with read_only=True')
+    def _owned(self, con: sqlite3.Connection, device_id: Any) -> None:
+        if not isinstance(device_id, str) or not device_id:
+            raise ValueError('device_id must be a non-empty string')
+        if not con.execute('SELECT 1 FROM devices WHERE device_id=? AND namespace=?', (device_id, self.namespace)).fetchone():
+            raise NoMatchError(f'{device_id} is not enrolled in namespace {self.namespace!r}')
+    def _refresh(self, con: sqlite3.Connection, device_id: str, digests: dict[str, list[str]], stamp: str) -> tuple[str, ...]:
+        stored = []
+        for kind, values in digests.items():
+            cursor = con.executemany('INSERT OR IGNORE INTO tokens(device_id,kind,digest,added_at) VALUES (?,?,?,?)', [(device_id, kind, digest, stamp) for digest in values])
+            if cursor.rowcount <= 0:
+                continue
+            stored.append(kind)
+            excess = con.execute('SELECT COUNT(*) FROM tokens WHERE device_id=? AND kind=?', (device_id, kind)).fetchone()[0] - _TOKEN_CAP
+            if excess > 0:
+                con.execute('DELETE FROM tokens WHERE rowid IN (SELECT t.rowid FROM tokens t WHERE t.device_id=? AND t.kind=? AND NOT EXISTS (SELECT 1 FROM incoming i WHERE i.kind=t.kind AND i.digest=t.digest) ORDER BY t.added_at,t.rowid LIMIT ?)', (device_id, kind, excess))
+                _LOG.debug('Pruned %d stale %s tokens from %s', excess, kind, device_id)
+        return tuple(stored)
+    def resolve(self, snapshot: HardwareSnapshot, *, create: bool=True, refresh: bool=True) -> IdentityResult:
+        if not isinstance(snapshot, HardwareSnapshot):
+            raise TypeError('snapshot must be HardwareSnapshot')
+        if len(snapshot.groups) < self.min_matches:
+            raise InsufficientHardwareError(snapshot.groups, self.min_matches, snapshot.warnings)
+        write = not self.read_only
+        create, refresh = (bool(create) and write, bool(refresh) and write)
+        digests = {kind: [self._digest(kind, value) for value in values] for kind, values in snapshot.signals.items()}
+        tokens = [(kind, digest) for kind, values in digests.items() for digest in values]
+        changed = False
+        with self._transaction(write=write) as con:
+            self._check_key(con)
+            con.execute('CREATE TEMP TABLE incoming (kind TEXT, digest TEXT, PRIMARY KEY(kind,digest))')
+            con.executemany('INSERT INTO incoming VALUES (?,?)', tokens)
+            candidates = []
+            for device_id, kinds, count in con.execute(_MATCH_SQL, (self.namespace, self.min_matches)):
+                kinds = tuple(sorted(kinds.split(',')))
+                groups = tuple(sorted({_KINDS[k] for k in kinds}))
+                candidates.append({'device_id': device_id, 'match_count': count, 'matched_groups': groups, 'matched_kinds': kinds})
+            if len(candidates) > 1:
+                _LOG.warning('Ambiguous match in namespace %r: %s', self.namespace, ', '.join((f"{c['device_id']} ({c['match_count']} groups)" for c in candidates)))
+                raise AmbiguousMatchError(tuple(candidates))
+            stamp = _now()
+            if candidates:
+                candidate = candidates[0]
+                device_id = candidate['device_id']
+                stored = ()
+                if write:
+                    con.execute('UPDATE devices SET last_seen=? WHERE device_id=? AND last_seen<>?', (stamp, device_id, stamp))
+                if refresh:
+                    stored = self._refresh(con, device_id, digests, stamp)
+                    changed = bool(stored)
+                _LOG.debug('Matched %s on %d groups (%s); stored new tokens for %s', device_id, candidate['match_count'], ','.join(candidate['matched_groups']), ','.join(stored) or 'nothing')
+                result = IdentityResult(device_id, False, candidate['matched_groups'], candidate['matched_kinds'], snapshot.groups, snapshot.warnings, stored)
+            else:
+                if not create:
+                    raise NoMatchError(f'No enrollment matches at least {self.min_matches} hardware groups')
+                device_id = 'ALTIFY-' + str(uuid.uuid4()).upper()
+                con.execute('INSERT INTO devices VALUES (?,?,?,?)', (device_id, self.namespace, stamp, stamp))
+                con.executemany('INSERT INTO tokens(device_id,kind,digest,added_at) VALUES (?,?,?,?)', [(device_id, k, v, stamp) for k, v in tokens])
+                changed = True
+                _LOG.info('Enrolled %s with %d groups (%s)', device_id, len(snapshot.groups), ','.join(snapshot.groups))
+                result = IdentityResult(device_id, True, (), (), snapshot.groups, snapshot.warnings, tuple(sorted(digests)))
+        if changed:
+            self._auto_backup()
+        return result
+    def list_devices(self, *, all_namespaces: bool=False) -> list[dict[str, Any]]:
+        sql = _LIST_SQL.format(where='' if all_namespaces else 'WHERE d.namespace=?')
+        with self._transaction(write=False) as con:
+            rows = con.execute(sql, () if all_namespaces else (self.namespace,)).fetchall()
+        devices = []
+        for device_id, namespace, created_at, last_seen, count, kinds in rows:
+            kinds = tuple(sorted(kinds.split(','))) if kinds else ()
+            devices.append({'device_id': device_id, 'namespace': namespace, 'created_at': created_at, 'last_seen': last_seen, 'token_count': count, 'groups': sorted({_KINDS[k] for k in kinds if k in _KINDS}), 'kinds': list(kinds)})
+        return devices
+    def delete(self, *device_ids: str) -> int:
+        self._require_writable()
+        if not device_ids:
+            raise ValueError('Supply at least one device_id')
+        with self._transaction() as con:
+            self._check_key(con)
+            for device_id in device_ids:
+                self._owned(con, device_id)
+            deleted = sum((con.execute('DELETE FROM devices WHERE device_id=? AND namespace=?', (device_id, self.namespace)).rowcount for device_id in set(device_ids)))
+        _LOG.info('Deleted %d enrollment(s) from namespace %r', deleted, self.namespace)
+        self._auto_backup()
+        return deleted
+    def merge(self, keep_id: str, *absorb_ids: str) -> dict[str, Any]:
+        self._require_writable()
+        if not absorb_ids:
+            raise ValueError('Supply the device_id to keep followed by at least one device_id to absorb')
+        if keep_id in absorb_ids or len(set(absorb_ids)) != len(absorb_ids):
+            raise ValueError('device_ids must be distinct and must not include the kept device_id')
+        stamp = _now()
+        with self._transaction() as con:
+            self._check_key(con)
+            for device_id in (keep_id, *absorb_ids):
+                self._owned(con, device_id)
+            for device_id in absorb_ids:
+                con.execute('INSERT OR IGNORE INTO tokens(device_id,kind,digest,added_at) SELECT ?,kind,digest,added_at FROM tokens WHERE device_id=?', (keep_id, device_id))
+                con.execute('DELETE FROM devices WHERE device_id=?', (device_id,))
+            con.execute('UPDATE devices SET last_seen=? WHERE device_id=?', (stamp, keep_id))
+            count = con.execute('SELECT COUNT(*) FROM tokens WHERE device_id=?', (keep_id,)).fetchone()[0]
+        _LOG.info('Merged %s into %s (%d tokens)', ','.join(absorb_ids), keep_id, count)
+        self._auto_backup()
+        return {'device_id': keep_id, 'merged': list(absorb_ids), 'token_count': count}
+    def _backup_path(self, index: int) -> Path:
+        return self.path.with_name(f'{self.path.name}.bak{index}')
+    def _auto_backup(self) -> None:
+        if self.read_only or not self.backup_copies:
+            return
+        newest = self._backup_path(1)
+        staging = self.path.with_name(f'{self.path.name}.bak-{secrets.token_hex(4)}.tmp')
+        try:
+            if newest.is_file() and time() - newest.stat().st_mtime < self.backup_interval:
+                return
+            self.backup(staging)
+            for index in range(self.backup_copies, 1, -1):
+                older = self._backup_path(index - 1)
+                if older.is_file():
+                    os.replace(older, self._backup_path(index))
+            os.replace(staging, newest)
+            _LOG.info('Backed up registry to %s', newest)
+        except Exception as exc:
+            staging.unlink(missing_ok=True)
+            _LOG.warning('Automatic registry backup failed: %s', exc)
+    def backup(self, destination: str | os.PathLike, *, timeout: float=30.0) -> Path:
+        if type(timeout) not in (float, int) or not math.isfinite(timeout) or (not 0 < timeout <= 300):
+            raise ValueError('backup timeout must be between 0 and 300 seconds')
+        target = Path(destination).expanduser().resolve()
+        if target == self.path:
+            raise ValueError('Backup destination must differ from the live database')
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open('xb'):
+            pass
+        deadline = monotonic() + timeout
+        def progress(status, remaining, total):
+            if monotonic() >= deadline:
+                raise RegistryError('Backup timed out')
+        try:
+            with closing(sqlite3.connect(self.path.as_uri() + '?mode=ro', uri=True, timeout=timeout)) as source:
+                with closing(sqlite3.connect(str(target), timeout=timeout)) as dest:
+                    source.backup(dest, pages=256, progress=progress, sleep=0.05)
+        except sqlite3.Error as exc:
+            target.unlink(missing_ok=True)
+            raise RegistryError(f'Backup failed: {exc}') from exc
+        except BaseException:
+            target.unlink(missing_ok=True)
+            raise
+        return target
+def identify(db_path: str | os.PathLike | None=None, *, namespace: str='default', min_matches: int=3, create: bool=True, refresh: bool=True, read_only: bool=False, include_tpm: bool=True, include_monitors: bool=True, timeout: float=35.0, cache_ttl: float=60.0, snapshot: HardwareSnapshot | None=None) -> IdentityResult:
+    if type(min_matches) is not int or not 3 <= min_matches <= 7:
+        raise ValueError('min_matches must be an integer between 3 and 7')
+    if not isinstance(namespace, str) or not namespace.strip() or len(namespace) > 128:
+        raise ValueError('namespace must contain 1 to 128 characters')
+    if snapshot is None:
+        snapshot = collect(include_tpm=include_tpm, include_monitors=include_monitors, timeout=timeout, cache_ttl=cache_ttl)
+    if not isinstance(snapshot, HardwareSnapshot):
+        raise TypeError('snapshot must be HardwareSnapshot')
+    if len(snapshot.groups) < min_matches:
+        raise InsufficientHardwareError(snapshot.groups, min_matches, snapshot.warnings)
+    return Registry(db_path, namespace=namespace, min_matches=min_matches, read_only=read_only).resolve(snapshot, create=create, refresh=refresh)
+def get_id(*args, **kwargs) -> str:
+    return identify(*args, **kwargs).device_id
+hwid = get_id
+def _main() -> int:
+    parser = argparse.ArgumentParser(description='Altify: persistent identity from 3+ hardware groups')
+    parser.add_argument('action', nargs='?', choices=('identify', 'scan', 'list', 'merge', 'delete'), default='identify')
+    parser.add_argument('ids', nargs='*', metavar='DEVICE_ID', help='merge: KEEP_ID ABSORB_ID...; delete: DEVICE_ID...')
+    parser.add_argument('--db', help='Registry path (default: per-user Altify/HWID data folder)')
+    parser.add_argument('--namespace', default='default')
+    parser.add_argument('--all-namespaces', action='store_true', help='list: include every namespace')
+    parser.add_argument('--min-matches', type=int, default=3, choices=range(3, 8))
+    parser.add_argument('--no-create', action='store_true', help='Only match an existing enrollment')
+    parser.add_argument('--no-refresh', action='store_true', help='Do not store newly seen hardware on a match')
+    parser.add_argument('--read-only', action='store_true', help='Never write to the registry')
+    parser.add_argument('--no-tpm', action='store_true')
+    parser.add_argument('--no-monitors', action='store_true')
+    parser.add_argument('--timeout', type=float, default=35, help='Overall collection deadline in seconds')
+    parser.add_argument('--json', action='store_true', help='Print detailed identity result as JSON')
+    parser.add_argument('--raw', action='store_true', help='Include RAW identifiers in scan output')
+    parser.add_argument('-v', '--verbose', action='store_true', help='Log collector and registry activity to stderr')
+    args = parser.parse_args()
+    if args.raw and args.action != 'scan':
+        parser.error('--raw requires the scan action')
+    if args.all_namespaces and args.action != 'list':
+        parser.error('--all-namespaces requires the list action')
+    if args.ids and args.action not in ('merge', 'delete'):
+        parser.error('device ids are only accepted by merge and delete')
+    if args.action == 'merge' and len(args.ids) < 2:
+        parser.error('merge needs KEEP_ID and at least one ABSORB_ID')
+    if args.action == 'delete' and not args.ids:
+        parser.error('delete needs at least one DEVICE_ID')
+    if args.verbose:
+        logging.basicConfig(level=logging.DEBUG, stream=sys.stderr, format='%(levelname)s %(name)s: %(message)s')
+    try:
+        if args.action in ('list', 'merge', 'delete'):
+            registry = Registry(args.db, namespace=args.namespace, min_matches=args.min_matches, read_only=args.read_only)
+            if args.action == 'list':
+                output = registry.list_devices(all_namespaces=args.all_namespaces)
+            elif args.action == 'merge':
+                output = registry.merge(args.ids[0], *args.ids[1:])
+            else:
+                output = {'deleted': registry.delete(*args.ids)}
+            print(json.dumps(output, indent=2))
+            return 0
+        snapshot = collect(include_tpm=not args.no_tpm, include_monitors=not args.no_monitors, include_diagnostics=args.raw, timeout=args.timeout, cache_ttl=0)
+        if args.action == 'scan':
+            print(json.dumps(snapshot.to_dict(raw=args.raw), indent=2, ensure_ascii=True))
+            return 0
+        result = identify(args.db, namespace=args.namespace, min_matches=args.min_matches, create=not args.no_create, refresh=not args.no_refresh, read_only=args.read_only, snapshot=snapshot)
+        print(json.dumps(result.to_dict(), indent=2) if args.json else result.device_id)
+        if not args.json:
+            for warning in result.warnings:
+                print('Warning: ' + warning, file=sys.stderr)
+        return 0
+    except (AltifyError, ValueError, OSError) as exc:
+        error = {'error': type(exc).__name__, 'message': str(exc)}
+        if isinstance(exc, AmbiguousMatchError):
+            error['candidates'] = exc.candidates
+        if isinstance(exc, InsufficientHardwareError):
+            error['warnings'] = exc.warnings
+        print(json.dumps(error, indent=2), file=sys.stderr)
+        return 2
+    except Exception as exc:
+        _LOG.exception('Unexpected error')
+        print(json.dumps({'error': type(exc).__name__, 'message': f'Unexpected error: {exc}'}, indent=2), file=sys.stderr)
+        return 1
+if __name__ == '__main__':
+    raise SystemExit(_main())