@ksl101/vulnreaper 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -1,199 +1,221 @@
-# VulnReaper — Plateforme d'analyse statique pour la sécurité Android
-
-**VulnReaper** est une plateforme d'analyse statique **offline-first** destinée au
-bug-bounty et à la recherche sécurité sur les **jeux Android** (APK natifs,
-Unity et IL2CPP). Elle tourne en **pur Python** (bibliothèque standard
-uniquement), sans dépendance runtime, et est **conçue pour Windows en priorité**,
-tout en restant compatible POSIX.
-
-Elle transforme un APK en un rapport exploitable : surface d'attaque
-(manifest), chaînes et secrets, endpoints/hosts, bibliothèques natives et
-métadonnées IL2CPP — le tout corrélé par un moteur de règles JSON.
-
----
-
-## Points clés
-
-- **Aucune dépendance runtime** : uniquement la bibliothèque standard.
-- **Jamais de résultats fabriqués** : un outil externe absent est marqué
-  `missing` et l'étape correspondante est `skipped`, jamais simulée.
-- **Windows-first** : encodage UTF-8, couleurs ANSI (VT), gestion des chemins et
-  des sous-processus adaptée à Windows.
-- **Analyses natives sans décompilateur** : parseurs intégrés DEX, AXML
-  (manifest compilé), ELF et `global-metadata.dat` (IL2CPP v24–v31).
-- **Rapports** JSON, Markdown et HTML prêts à joindre à un rapport de bug bounty.
-
----
-
-## Installation
-
-### Bêta publique (npm)
-
-```sh
-npm install -g @ksl101/vulnreaper@beta
-vr version
-```
-
-Prérequis : Node.js ≥ 18 et Python ≥ 3.10 (le paquet embarque le cœur Python
-complet, exécuté par le lanceur `vr` / `vulnreaper`).
-
-VulnReaper est sous licence nominative : activez votre clé avec
-`vr login --key VR-...`, puis consultez `vr whoami`. Les commandes `scan` et
-`report` exigent une permission (`scan.run`, `report.export`) ; les permissions
-`recon.run` et `audit.run` sont réservées aux futures commandes `recon`/`audit`.
-Voir **[docs/BETA_TESTERS.md](docs/BETA_TESTERS.md)** pour le guide complet des
-testeurs.
-
-### Depuis les sources
-
-Aucune installation n'est requise pour utiliser VulnReaper depuis les sources.
-
-```bat
-:: Windows (invité de commandes)
-vulnreaper.bat doctor
-vulnreaper.bat scan C:\path\to\game.apk --profile apk-static
-```
-
-```sh
-# Git Bash / Linux / macOS
-./vulnreaper.sh doctor
-./vulnreaper.sh scan /path/to/game.apk --profile apk-static
-```
-
-Ou directement via Python (à la racine du dépôt) :
-
-```bat
-python -m vulnreaper doctor
-python -m vulnreaper scan C:\path\to\game.apk
-```
-
-Installation optionnelle comme commande globale :
-
-```sh
-pip install -e .
-vulnreaper --version
-```
-
----
-
-## Commandes
-
-| Commande | Description |
-| --- | --- |
-| `vulnreaper doctor` | Diagnostic de l'environnement et des outils externes |
-| `vulnreaper version` | Affiche la version |
-| `vulnreaper profiles` | Liste les profils de scan |
-| `vulnreaper rules [--json]` | Liste les règles chargées |
-| `vulnreaper tools [--missing\|--available] [--json]` | Inspecte les outils externes |
-| `vulnreaper project create\|list\|show\|delete <nom>` | Gère les projets/workspaces |
-| `vulnreaper scan <apk> [--profile P] [--project N] [--json]` | Lance un scan |
-| `vulnreaper runs [--project N]` | Liste les runs |
-| `vulnreaper findings [--run ID] [--severity S]` | Affiche les findings |
-| `vulnreaper report --run ID` | Chemin des rapports générés |
-| `vulnreaper config show\|init` | Affiche / initialise la configuration |
-| `vulnreaper login --key <VR-…> [--base-url URL]` | Active une licence et ouvre une session |
-| `vulnreaper logout` | Ferme la session locale |
-| `vulnreaper whoami [--json]` | Affiche licence, rôle, statut, permissions |
-| `vulnreaper admin license\|device\|audit …` | Administration des licences/appareils (rôle `admin`) |
-| `vulnreaper ui` | Menu interactif |
-
-Sans commande, `vulnreaper` ouvre le menu interactif (`ui`).
-
----
-
-## Profils de scan
-
-| Profil | Usage |
-| --- | --- |
-| `apk-static` *(défaut)* | Analyse statique complète : import, extraction, manifest, dex, natif, Unity, IL2CPP, assets, endpoints, scanners, rapport |
-| `quick` | Version rapide sans extraction ni décompilation |
-| `android-full` | Ajoute apktool, Il2CppDumper et jadx quand ils sont présents |
-| `il2cpp` | Orienté Unity/IL2CPP |
-| `recon` | Reconnaissance endpoints/hosts uniquement |
-| `device` | Énumération des appareils adb |
-| `report-only` | Régénère un rapport à partir de données existantes |
-
-Lister les profils : `vulnreaper profiles`.
-
----
-
-## Outils externes (optionnels)
-
-VulnReaper fonctionne sans eux ; s'ils sont présents, il en tire parti :
-
-| Outil | Rôle |
-| --- | --- |
-| `adb` | Énumération d'appareils / interaction device |
-| `apktool` | Décodage des ressources |
-| `jadx` | Décompilation Java |
-| `apksigner` | Vérification de signature |
-| `aapt` | Inspection d'APK |
-| `frida` | Instrumentation dynamique |
-| `il2cppdumper` | Dump IL2CPP (`.cs` reconstruits) |
-| `cpp2il` | Reconstruction IL2CPP alternative |
-| `ghidra` | Analyse native avancée |
-
-Statut : `vulnreaper tools`. Chemins explicites et répertoires de recherche se
-définissent dans la configuration (`vulnreaper config show`).
-
----
-
-## Structure du dépôt
-
-```
-vulnreaper/                 paquet principal
-  cli/                  point d'entrée, menu interactif, tableaux/dashboard
-  formats/              parseurs strings, AXML, DEX, ELF, métadonnées IL2CPP
-  android/              import APK, modèle manifest, analyse dex/natif, adb
-  unity/ il2cpp/        détection moteur + adaptateurs de dump
-  web/                  découverte et classification d'endpoints
-  scanners/             moteur de règles + scanners (secrets, crypto, réseau, natif)
-  findings/             modèle Finding + rapports JSON/MD/HTML
-  rules/                packs de règles JSON
-  config.py workspace.py database.py project.py pipeline.py engine.py tools.py
-tests/                  suite pytest + fixtures synthétiques + smoke end-to-end
-docs/                   architecture, règles, utilisation
-```
-
----
-
-## Tests
-
-```bat
-python -m pytest tests/ -q      :: cœur Python (122 tests)
-python tests/smoke.py           :: scan end-to-end d'un APK synthétique
-cd server && npm test           :: API de licence (11 tests, store mémoire)
-cd server && VULNREAPER_E2E=1 npm test   :: + E2E CLI ↔ API
-```
-
-Le smoke construit un APK structurellement valide (manifest AXML compilé, DEX,
-`.so` natif, `global-metadata.dat`) dans un dossier temporaire, exécute le profil
-`quick` et vérifie que le run se termine, écrit les 3 formats de rapport et
-produit findings et endpoints.
-
-Le test E2E inter-stack pilote réellement la CLI contre l'API de licence
-(activation, `whoami`, gating, révocation). Détail de la couverture et
-prérequis : **[docs/TESTING.md](docs/TESTING.md)**.
-
----
-
-## Documentation
-
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — conception et flux de données
-- [`docs/USAGE.md`](docs/USAGE.md) — prise en main et workflow bug-bounty
-- [`docs/RULES.md`](docs/RULES.md) — packs de règles et écriture de règles
-- [`docs/BETA_TESTERS.md`](docs/BETA_TESTERS.md) — guide des testeurs bêta (npm, licence, gating)
-- [`docs/TESTING.md`](docs/TESTING.md) — stratégie et couverture des tests
-
----
-
-## Licence et usage
-
-> Distribution sous licence nominative propriétaire. L'utilisation du logiciel
-> vaut acceptation du [contrat de licence utilisateur final (EULA)](LICENSE).
-> Le guide d'activation et le détail des permissions se trouvent dans
-> [docs/BETA_TESTERS.md](docs/BETA_TESTERS.md).
-
-Outil destiné aux professionnels autorisés. Ne scannez que des applications que
-vous êtes autorisé à tester (vos propres cibles, programmes de bug bounty, ou
-cibles explicitement autorisées).
+# VulnReaper — Security platform for research and bug-bounty
+
+**VulnReaper** is an **offline-first** security-analysis platform for bug-bounty
+and security research. It is built around a **target-agnostic core** (projects,
+runs, findings, rule engine, JSON/Markdown/HTML reports, licence/account) and
+around **per-target modules**:
+the **Android** module (APK/APKS/XAPK, Unity and IL2CPP) is available today,
+while web, Windows and game-engine project targets are already detected and
+routed, with their engines still to be integrated.
+
+It runs on **pure Python** (standard library only), with no runtime dependency,
+and is **Windows-first**, while remaining POSIX-compatible.
+
+On an Android target, it turns an APK into an actionable report: attack surface
+(manifest), strings and secrets, endpoints/hosts, native libraries and IL2CPP
+metadata — all correlated by a JSON rule engine.
+
+---
+
+## Highlights
+
+- **No runtime dependency**: standard library only.
+- **Never fabricate results**: a missing external tool is marked `missing` and
+  its step is `skipped`, never simulated.
+- **Windows-first**: UTF-8 encoding, ANSI (VT) colours, Windows-aware path and
+  subprocess handling.
+- **Native analysis without a decompiler**: built-in DEX, AXML (compiled
+  manifest), ELF and `global-metadata.dat` (IL2CPP v24–v31) parsers.
+- **Reports** in JSON, Markdown and HTML, ready to attach to a bug-bounty report.
+
+---
+
+## Core and per-target modules
+
+| Element | Scope |
+| --- | --- |
+| **Core** (target-agnostic) | Workspaces/projects, runs, findings, JSON rule engine, JSON/Markdown/HTML reports, licence/account management — **always available**. |
+| **Android module** | APK/APKS/XAPK: manifest, DEX, native, Unity/IL2CPP, assets, endpoints — **available**. |
+| **Web module** | http(s) URL: detected and routed; engine coming. |
+| **Windows module** | EXE/DLL/SYS/MSI: detected and routed; engine coming. |
+| **Unity / Unreal module** | Project folders: detected and routed; engines coming. |
+
+A target whose module is not yet integrated is **honestly refused**
+("not supported yet" message): VulnReaper never simulates a scan.
+
+---
+
+## Installation
+
+### Public beta (npm)
+
+```sh
+npm install -g @ksl101/vulnreaper@beta
+vr version
+```
+
+Requirements: Node.js ≥ 18 and Python ≥ 3.10 (the package embeds the complete
+Python core, executed by the `vr` / `vulnreaper` launcher).
+
+VulnReaper is nominative-licence software: activate your key with
+`vr login --key VR-...`, then check `vr whoami`. The `scan` and
+`report` commands require a permission (`scan.run`, `report.export`); the
+`recon.run` and `audit.run` permissions are reserved for the future `recon`/`audit`
+commands.
+See **[docs/BETA_TESTERS.md](docs/BETA_TESTERS.md)** for the full tester guide.
+
+### From source
+
+No installation is required to use VulnReaper from source.
+
+```bat
+:: Windows (command prompt)
+vulnreaper.bat doctor
+vulnreaper.bat scan C:\path\to\game.apk --profile apk-static
+```
+
+```sh
+# Git Bash / Linux / macOS
+./vulnreaper.sh doctor
+./vulnreaper.sh scan /path/to/game.apk --profile apk-static
+```
+
+Or directly through Python (at the repository root):
+
+```bat
+python -m vulnreaper doctor
+python -m vulnreaper scan C:\path\to\game.apk
+```
+
+Optional installation as a global command:
+
+```sh
+pip install -e .
+vulnreaper --version
+```
+
+---
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `vulnreaper doctor` | Diagnose the environment and external tools |
+| `vulnreaper version` | Print the version |
+| `vulnreaper profiles` | List scan profiles |
+| `vulnreaper rules [--json]` | List loaded rules |
+| `vulnreaper tools [--missing\|--available] [--json]` | Inspect external tools |
+| `vulnreaper project create\|list\|show\|delete <name>` | Manage projects/workspaces |
+| `vulnreaper scan <target> [--profile P] [--project N] [--json]` | Analyze a security target (APK, URL, EXE, project) |
+| `vulnreaper runs [--project N]` | List runs |
+| `vulnreaper findings [--run ID] [--severity S]` | Show findings |
+| `vulnreaper report --run ID` | Path of the generated reports |
+| `vulnreaper config show\|init` | Show / initialise the configuration |
+| `vulnreaper login --key <VR-…> [--base-url URL]` | Activate a licence and open a session |
+| `vulnreaper logout` | Close the local session |
+| `vulnreaper whoami [--json]` | Show licence, role, status, permissions |
+| `vulnreaper admin license\|device\|audit …` | Licence/device administration (`admin` role) |
+| `vulnreaper self-update [--check] [--yes] [--force] [--json]` | Update VulnReaper itself (npm `@beta`) |
+| `vulnreaper ui` | Interactive shell (conversational REPL) |
+
+With no command, `vulnreaper` opens the interactive shell (`ui`).
+
+---
+
+## Scan profiles
+
+| Profile | Usage |
+| --- | --- |
+| `apk-static` *(default)* | Full static analysis: import, extraction, manifest, dex, native, Unity, IL2CPP, assets, endpoints, scanners, report |
+| `quick` | Fast version without extraction or decompilation |
+| `android-full` | Adds apktool, Il2CppDumper and jadx when present |
+| `il2cpp` | Unity/IL2CPP-oriented |
+| `recon` | Endpoint/host reconnaissance only |
+| `device` | Enumerate adb devices |
+| `report-only` | Regenerate a report from existing data |
+
+List profiles: `vulnreaper profiles`.
+
+---
+
+## External tools (optional)
+
+VulnReaper works without them; when present, it takes advantage of them:
+
+| Tool | Role |
+| --- | --- |
+| `adb` | Device enumeration / device interaction |
+| `apktool` | Resource decoding |
+| `jadx` | Java decompilation |
+| `apksigner` | Signature verification |
+| `aapt` | APK inspection |
+| `frida` | Dynamic instrumentation |
+| `il2cppdumper` | IL2CPP dump (reconstructed `.cs`) |
+| `cpp2il` | Alternative IL2CPP reconstruction |
+| `ghidra` | Advanced native analysis |
+
+Status: `vulnreaper tools`. Explicit paths and search directories are
+defined in the configuration (`vulnreaper config show`).
+
+---
+
+## Repository layout
+
+```
+vulnreaper/                 main package
+  cli/                  entry point, interactive shell (REPL), theme + components
+  formats/              strings, AXML, DEX, ELF, IL2CPP metadata parsers
+  android/              APK import, manifest model, dex/native analysis, adb
+  unity/ il2cpp/        engine detection + dump adapters
+  web/                  endpoint discovery and classification
+  scanners/             rule engine + scanners (secrets, crypto, network, native)
+  findings/             Finding model + JSON/MD/HTML reports
+  rules/                JSON rule packs
+  config.py workspace.py database.py project.py pipeline.py engine.py tools.py
+tests/                  pytest suite + synthetic fixtures + end-to-end smoke
+docs/                   architecture, rules, usage
+```
+
+---
+
+## Tests
+
+```bat
+python -m pytest tests/ -q      :: Python core + UI
+python tests/smoke.py           :: end-to-end scan of a synthetic APK
+cd server && npm test           :: licence API (in-memory store)
+cd server && VULNREAPER_E2E=1 npm test   :: + CLI ↔ API E2E
+```
+
+The smoke builds a structurally valid APK (compiled AXML manifest, DEX,
+native `.so`, `global-metadata.dat`) in a temporary folder, runs the `quick`
+profile and checks that the run completes, writes the 3 report formats and
+produces findings and endpoints.
+
+The cross-stack E2E test actually drives the CLI against the licence API
+(activation, `whoami`, gating, revocation). Coverage details and
+prerequisites: **[docs/TESTING.md](docs/TESTING.md)**.
+
+---
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — design and data flow
+- [`docs/USAGE.md`](docs/USAGE.md) — getting started and bug-bounty workflow
+- [`docs/UI.md`](docs/UI.md) — CLI/REPL interface (theme, components, shortcuts)
+- [`docs/RULES.md`](docs/RULES.md) — rule packs and writing rules
+- [`docs/BETA_TESTERS.md`](docs/BETA_TESTERS.md) — beta tester guide (npm, licence, gating)
+- [`docs/TESTING.md`](docs/TESTING.md) — test strategy and coverage
+
+---
+
+## Licence and usage
+
+> Distributed under a proprietary nominative licence. Using the software
+> constitutes acceptance of the [end-user licence agreement (EULA)](LICENSE).
+> The activation guide and the details of the permissions are in
+> [docs/BETA_TESTERS.md](docs/BETA_TESTERS.md).
+
+Tool intended for authorised professionals. Only scan applications you are
+authorised to test (your own targets, bug-bounty programs, or explicitly
+authorised targets).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ksl101/vulnreaper",
-  "version": "0.1.0-beta.0",
-  "description": "VulnReaper - authorised security auditing & bug-bounty CLI for Android/Unity/IL2CPP game packages",
+  "version": "0.1.0-beta.2",
+  "description": "VulnReaper - authorised security-auditing & bug-bounty CLI with a target-agnostic core and per-target modules (Android today; web, Windows and game-engine projects detected next)",
   "keywords": [
     "security",
     "bug-bounty",

package/vendor/vulnreaper/__init__.py

@@ -1,23 +1,23 @@
-"""VulnReaper — Android game security research & bug-bounty automation platform.
-
-A modular, offline-first toolkit for analysing Android/Unity/IL2CPP game
-packages: APK/DEX/native/IL2CPP parsing, secret and misconfiguration scanning,
-endpoint discovery, and JSON/Markdown/HTML reporting.
-
-Design invariants
------------------
-* Standard library only (no third-party runtime dependencies).
-* Never fabricate results: a missing external tool is reported as ``missing``
-  and its pipeline stage is ``skipped`` — never simulated.
-* Windows-first, POSIX-compatible.
-"""
-from __future__ import annotations
-
-__all__ = ["__version__", "PRODUCT"]
-
-__version__ = "0.1.0-beta.0"
-PRODUCT = "VulnReaper"
-
-
-def version_string() -> str:
-    return f"{PRODUCT} {__version__} — Security Research Platform"
+"""VulnReaper — Android game security research & bug-bounty automation platform.
+
+A modular, offline-first toolkit for analysing Android/Unity/IL2CPP game
+packages: APK/DEX/native/IL2CPP parsing, secret and misconfiguration scanning,
+endpoint discovery, and JSON/Markdown/HTML reporting.
+
+Design invariants
+-----------------
+* Standard library only (no third-party runtime dependencies).
+* Never fabricate results: a missing external tool is reported as ``missing``
+  and its pipeline stage is ``skipped`` — never simulated.
+* Windows-first, POSIX-compatible.
+"""
+from __future__ import annotations
+
+__all__ = ["__version__", "PRODUCT"]
+
+__version__ = "0.1.0-beta.2"
+PRODUCT = "VulnReaper"
+
+
+def version_string() -> str:
+    return f"{PRODUCT} {__version__} — Security Research Platform"

package/vendor/vulnreaper/cli/__init__.py

@@ -1,4 +1,4 @@
 """Command-line interface."""
 from __future__ import annotations
 
-__all__ = ["app", "menu"]
+__all__ = ["app"]

package/vendor/vulnreaper/cli/account.py

@@ -0,0 +1,140 @@
+"""Account helpers shared by the CLI entrypoint and the REPL.
+
+A VulnReaper *account* is the username + subscription tag + free-form profile
+blob carried on the license view returned by the licensing API.  These helpers
+keep the interpretation of that view in one place and tolerate both the
+snake_case the API emits and the camelCase the Node store uses internally.
+
+The username is deliberately **not** a credential: authentication stays with
+the license key / server session.  The username only identifies the tester,
+personalises the interface and enables administration/search.
+
+Human-facing expiry wording is produced through the i18n catalog so it follows
+the active interface language; the underlying arithmetic (seconds until
+``expiresAt``) is language-independent.
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+
+from ..i18n import t
+
+# Must stay in sync with ``USERNAME_RE`` in the licensing server.
+USERNAME_RE = re.compile(r"^[A-Za-z0-9_-]{3,32}$")
+# Static English fallback (kept for callers importing the constant).  Prefer
+# :func:`username_rule` so the hint tracks the active language.
+USERNAME_RULE = "3-32 characters (letters, digits, underscore or hyphen)"
+
+
+def username_rule() -> str:
+    """The username policy hint, localised."""
+    return t("account.username_rule", default=USERNAME_RULE)
+
+
+def username(lic: dict | None) -> str:
+    """The account username, or '' when it has not been chosen yet."""
+    return str((lic or {}).get("username") or "").strip()
+
+
+def tag(lic: dict | None) -> str:
+    """The subscription tag, upper-cased, defaulting to BETA."""
+    raw = (lic or {}).get("subscriptionTag") or (lic or {}).get("subscription_tag") or "BETA"
+    return str(raw).upper()
+
+
+def expires_at(lic: dict | None):
+    return (lic or {}).get("expiresAt") or (lic or {}).get("expires_at")
+
+
+def _expiry_datetime(lic: dict | None) -> datetime | None:
+    """Parse ``expiresAt`` into an aware UTC datetime, or None when absent."""
+    value = expires_at(lic)
+    if not value:
+        return None
+    try:
+        when = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return when
+
+
+def _seconds_left(lic: dict | None, now: datetime | None = None) -> float | None:
+    when = _expiry_datetime(lic)
+    if when is None:
+        return None
+    now = now or datetime.now(timezone.utc)
+    return (when - now).total_seconds()
+
+
+def days_left(lic: dict | None) -> int | None:
+    """Whole days until expiry, or None when the license never expires."""
+    seconds = _seconds_left(lic)
+    if seconds is None:
+        return None
+    return max(0, int(seconds // 86400))
+
+
+def expiry_phrase(lic: dict | None, now: datetime | None = None) -> str:
+    """The value form for tables/cards, without the verb.
+
+    Examples: ``never``, ``expired``, ``in 42 minutes``, ``in 18 hours``,
+    ``in 27 days``.  Everything is derived from ``expiresAt`` — nothing
+    time-relative is ever persisted.
+    """
+    seconds = _seconds_left(lic, now)
+    if seconds is None:
+        return t("expiry.never")
+    if seconds <= 0:
+        return t("expiry.expired")
+    if seconds < 60:
+        return t("expiry.less_than_minute")
+    if seconds < 3600:
+        return t("expiry.minutes", count=int(seconds // 60))
+    if seconds < 86400:
+        return t("expiry.hours", count=int(seconds // 3600))
+    return t("expiry.days", count=int(seconds // 86400))
+
+
+def expiry_text(lic: dict | None, now: datetime | None = None) -> str:
+    """A full, human sentence describing the remaining lifetime.
+
+    Examples: ``never expires``, ``expired``, ``expires in 42 minutes``,
+    ``expires in 18 hours``, ``expires in 27 days``.
+    """
+    seconds = _seconds_left(lic, now)
+    if seconds is None:
+        return t("expiry.text_never")
+    if seconds <= 0:
+        return t("expiry.text_expired")
+    return t("expiry.text", phrase=expiry_phrase(lic, now))
+
+
+def expiry_short(lic: dict | None, now: datetime | None = None) -> str:
+    """A compact expiry label for tables: ``27d`` / ``18h`` / ``42m`` /
+    ``never`` / ``expired``."""
+    seconds = _seconds_left(lic, now)
+    if seconds is None:
+        return t("expiry.short_never")
+    if seconds <= 0:
+        return t("expiry.short_expired")
+    if seconds < 3600:
+        return t("expiry.short_minutes", count=int(seconds // 60))
+    if seconds < 86400:
+        return t("expiry.short_hours", count=int(seconds // 3600))
+    return t("expiry.short_days", count=int(seconds // 86400))
+
+
+def devices_label(lic: dict | None, used: int | None = None) -> str:
+    """``used/max`` device usage, tolerating snake_case and camelCase."""
+    max_devices = (lic or {}).get("maxDevices")
+    if max_devices is None:
+        max_devices = (lic or {}).get("max_devices")
+    max_devices = max_devices if max_devices is not None else "?"
+    return f"{used if used is not None else '?'}/{max_devices}"
+
+
+def valid_username(name: str) -> bool:
+    return bool(USERNAME_RE.match((name or "").strip()))