Import the wilm agent store, WINC adoption work and batches CLI, with four fixes

plugins/endpoints/api/__init__.py

@@ -5,6 +5,8 @@ from .routes import endpoints_bp
 from . import adoption  # noqa: F401
 # Attaches the site agent generator packaging routes to endpoints_bp.
 from . import siteagent  # noqa: F401
+# Attaches the agent binary upload/retention routes to endpoints_bp.
+from . import agentupload  # noqa: F401
 # Attaches the monitor catalog CRUD and resolve routes to endpoints_bp.
 from . import monitors  # noqa: F401
 

plugins/endpoints/api/agentstore.py

@@ -0,0 +1,472 @@
+"""Versioned staging and retention for the endpoint agent binaries.
+
+The site-agent packager ships a prebuilt shopdbagent.exe and an optional
+shopdb-endpoint-tray.exe. Originally each was a single staged file under
+instance/siteagent/; this module adds per-version staging so an operator can
+drop in a new build, keep the last few, and roll a push out from a known
+version.
+
+Layout (all under the Flask instance directory):
+
+    siteagent/
+      shopdbagent.exe              legacy flat path (pre-versioning)
+      shopdb-endpoint-tray.exe     legacy flat path (pre-versioning)
+      agent/
+        manifest.json              {current, versions:[{version,uploadedat,size}]}
+        1.6.3/shopdbagent.exe
+        1.6.2/shopdbagent.exe
+      tray/
+        manifest.json
+        1.0.0/shopdb-endpoint-tray.exe
+
+Retention: the RETAIN most recently uploaded versions per binary are kept; the
+current version is never pruned even if it falls outside that window. The legacy
+flat file is treated as an unmanaged fallback: the packager still ships it when
+no versioned build exists, so an install that predates versioning keeps working.
+
+This module holds NO routes and NO permission checks - it is pure staging logic
+so it can be unit-tested without a request context and reused by both the upload
+routes and the packager. Callers own authorization.
+"""
+
+import hashlib
+import io
+import json
+import os
+import re
+import struct
+from datetime import datetime
+
+from flask import current_app
+
+# How many versions to retain per binary. The current version is exempt from
+# pruning, so the effective floor is max(RETAIN, 1-including-current).
+RETAIN = 3
+
+# Per-binary staging spec. 'exe' is the canonical filename shipped in the ZIP and
+# stored inside each version directory; 'legacy' is the flat pre-versioning path
+# under siteagent/ kept as a fallback source.
+BINARY_SPECS = {
+    'agent': {'exe': 'shopdbagent.exe', 'legacy': 'shopdbagent.exe'},
+    'tray': {'exe': 'shopdb-endpoint-tray.exe', 'legacy': 'shopdb-endpoint-tray.exe'},
+}
+
+# A dotted numeric version, 1 to 4 parts (matches .NET assembly versions like
+# 1.6.3 or 1.6.3.0). Deliberately strict so a typo or an arbitrary label cannot
+# become a directory name.
+_VERSION_RE = re.compile(r'^\d+(\.\d+){0,3}$')
+
+# Windows PE magic. Uploaded agent binaries must be real PE executables; a quick
+# header check rejects an operator who uploads the wrong file (a ZIP, a script)
+# before it is ever staged or pushed.
+_PE_MAGIC = b'MZ'
+
+
+def is_valid_binary_key(binkey):
+    """Whether binkey names a managed binary (agent or tray)."""
+    return binkey in BINARY_SPECS
+
+
+def is_valid_version(version):
+    """Whether version is a strict dotted-numeric string safe to use as a dir."""
+    return bool(version) and bool(_VERSION_RE.match(version))
+
+
+def looks_like_pe(data):
+    """Whether data begins with the Windows PE 'MZ' magic."""
+    return len(data) >= 2 and data[:2] == _PE_MAGIC
+
+
+# RT_VERSION resource type id (the version resource Windows shows in file
+# properties). We must read the version from THIS resource on the outer
+# executable - not the first VS_FIXEDFILEINFO signature we can find in the bytes.
+# A self-contained single-file .NET exe bundles dozens of framework assemblies,
+# each carrying its own version block, so a naive byte scan returns a framework
+# version (for example the .NET runtime's) instead of the app's. The only
+# reliable value is the RT_VERSION resource reached by walking the PE resource
+# directory, which belongs to the outer image alone.
+_RT_VERSION = 16
+
+# 0xFEEF04BD little-endian: the dwSignature that opens VS_FIXEDFILEINFO inside
+# the RT_VERSION resource data.
+_VS_FIXEDFILEINFO_SIGNATURE = b'\xbd\x04\xef\xfe'
+
+
+def _rva_to_offset(data, rva, sections):
+    """Map a resource RVA to a file offset using the section table, or None."""
+    for virtual_address, virtual_size, raw_offset, raw_size in sections:
+        if virtual_address <= rva < virtual_address + max(virtual_size, raw_size):
+            delta = rva - virtual_address
+            if delta < raw_size:
+                return raw_offset + delta
+    return None
+
+
+def _first_resource_entry_offset(data, table_offset, resource_base, sections,
+                                  want_id):
+    """Walk one IMAGE_RESOURCE_DIRECTORY level and return a child offset.
+
+    When want_id is not None, follow the entry whose id matches (used to select
+    RT_VERSION at the type level); otherwise follow the first entry (used to
+    descend name/language levels). Returns the absolute file offset of the child
+    directory or data entry, with the high bit stripped, or None.
+    """
+    # IMAGE_RESOURCE_DIRECTORY: 12 fixed bytes, then NumberOfNamedEntries (2)
+    # and NumberOfIdEntries (2), then the entries.
+    named = struct.unpack_from('<H', data, table_offset + 12)[0]
+    id_count = struct.unpack_from('<H', data, table_offset + 14)[0]
+    entries_offset = table_offset + 16
+    for index in range(named + id_count):
+        entry_offset = entries_offset + index * 8
+        name_or_id, offset_to_data = struct.unpack_from('<II', data, entry_offset)
+        # Named entries carry the high bit in name_or_id; we only match numeric
+        # ids, so skip named entries when selecting by id.
+        is_named = bool(name_or_id & 0x80000000)
+        if want_id is not None:
+            if is_named or name_or_id != want_id:
+                continue
+        # Directory children have the high bit set on offset_to_data.
+        child = (offset_to_data & 0x7FFFFFFF) + resource_base
+        return child
+    return None
+
+
+def read_pe_file_version(data):
+    """Dotted four-part file version from the PE's RT_VERSION resource, or None.
+
+    Walks the PE resource directory to the RT_VERSION resource of the outer
+    executable and decodes its VS_FIXEDFILEINFO file version. Returns None when
+    the file has no version resource or the structures are malformed. Never
+    raises - callers treat None as "unknown, ask the operator".
+    """
+    try:
+        if len(data) < 0x40 or data[:2] != _PE_MAGIC:
+            return None
+        pe_offset = struct.unpack_from('<I', data, 0x3C)[0]
+        if data[pe_offset:pe_offset + 4] != b'PE\x00\x00':
+            return None
+
+        coff = pe_offset + 4
+        number_of_sections = struct.unpack_from('<H', data, coff + 2)[0]
+        size_of_optional = struct.unpack_from('<H', data, coff + 16)[0]
+        optional = coff + 20
+        # Magic distinguishes PE32 (0x10b) from PE32+ (0x20b); the data-directory
+        # array sits at a different offset in each.
+        magic = struct.unpack_from('<H', data, optional)[0]
+        if magic == 0x20B:
+            data_dir = optional + 112
+        else:
+            data_dir = optional + 96
+        # Resource table is data directory index 2: its RVA then size.
+        resource_rva = struct.unpack_from('<I', data, data_dir + 2 * 8)[0]
+        if not resource_rva:
+            return None
+
+        section_table = optional + size_of_optional
+        sections = []
+        for index in range(number_of_sections):
+            base = section_table + index * 40
+            virtual_size = struct.unpack_from('<I', data, base + 8)[0]
+            virtual_address = struct.unpack_from('<I', data, base + 12)[0]
+            raw_size = struct.unpack_from('<I', data, base + 16)[0]
+            raw_offset = struct.unpack_from('<I', data, base + 20)[0]
+            sections.append((virtual_address, virtual_size, raw_offset, raw_size))
+
+        resource_base = _rva_to_offset(data, resource_rva, sections)
+        if resource_base is None:
+            return None
+
+        # Level 1: type -> pick RT_VERSION. Level 2: name/id -> first.
+        # Level 3: language -> first. Then a data entry pointing at the resource.
+        type_dir = _first_resource_entry_offset(
+            data, resource_base, resource_base, sections, _RT_VERSION)
+        if type_dir is None:
+            return None
+        name_dir = _first_resource_entry_offset(
+            data, type_dir, resource_base, sections, None)
+        if name_dir is None:
+            return None
+        lang_entry = _first_resource_entry_offset(
+            data, name_dir, resource_base, sections, None)
+        if lang_entry is None:
+            return None
+
+        # lang_entry is an IMAGE_RESOURCE_DATA_ENTRY: RVA (4), size (4), ...
+        version_rva = struct.unpack_from('<I', data, lang_entry)[0]
+        version_offset = _rva_to_offset(data, version_rva, sections)
+        if version_offset is None:
+            return None
+
+        # Within the version resource, find VS_FIXEDFILEINFO by its signature.
+        signature = data.find(_VS_FIXEDFILEINFO_SIGNATURE, version_offset,
+                              version_offset + 512)
+        if signature == -1:
+            return None
+        base = signature + 4 + 4  # skip signature and dwStrucVersion
+        version_ms, version_ls = struct.unpack_from('<II', data, base)
+        parts = (
+            (version_ms >> 16) & 0xFFFF,
+            version_ms & 0xFFFF,
+            (version_ls >> 16) & 0xFFFF,
+            version_ls & 0xFFFF,
+        )
+        if not any(parts):
+            return None
+        return '.'.join(str(part) for part in parts)
+    except (struct.error, TypeError, IndexError):
+        return None
+
+
+def read_pe_file_version_from_path(path):
+    """Read a PE file's version from disk, or None on any failure."""
+    try:
+        with open(path, 'rb') as handle:
+            return read_pe_file_version(handle.read())
+    except OSError:
+        return None
+
+
+def _siteagent_dir():
+    return os.path.join(current_app.instance_path, 'siteagent')
+
+
+def _binary_dir(binkey):
+    return os.path.join(_siteagent_dir(), binkey)
+
+
+def _manifest_path(binkey):
+    return os.path.join(_binary_dir(binkey), 'manifest.json')
+
+
+def _legacy_path(binkey):
+    return os.path.join(_siteagent_dir(), BINARY_SPECS[binkey]['legacy'])
+
+
+def _version_exe_path(binkey, version):
+    return os.path.join(_binary_dir(binkey), version, BINARY_SPECS[binkey]['exe'])
+
+
+def _read_manifest(binkey):
+    """Return the manifest dict, or an empty skeleton when none is written yet."""
+    path = _manifest_path(binkey)
+    try:
+        with open(path, 'r', encoding='utf-8') as handle:
+            data = json.load(handle)
+    except (OSError, ValueError):
+        return {'current': None, 'versions': []}
+    if not isinstance(data, dict):
+        return {'current': None, 'versions': []}
+    data.setdefault('current', None)
+    data.setdefault('versions', [])
+    return data
+
+
+def _write_manifest(binkey, manifest):
+    os.makedirs(_binary_dir(binkey), exist_ok=True)
+    with open(_manifest_path(binkey), 'w', encoding='utf-8') as handle:
+        json.dump(manifest, handle, indent=2)
+        handle.write('\n')
+
+
+def _version_sort_key(version):
+    """Parse a dotted-numeric version into a tuple of ints for ordering.
+
+    Pads to four parts so 1.6 and 1.6.0.0 compare equal-ish and shorter
+    versions do not sort above longer ones with the same prefix. A part that
+    is not numeric (should not happen after validation) sorts as 0.
+    """
+    parts = []
+    for chunk in str(version).split('.'):
+        try:
+            parts.append(int(chunk))
+        except ValueError:
+            parts.append(0)
+    while len(parts) < 4:
+        parts.append(0)
+    return tuple(parts[:4])
+
+
+def list_versions(binkey):
+    """Staged versions for a binary, highest version number first.
+
+    Each item is {version, uploadedat, size, iscurrent}. Reads the manifest as
+    the source of truth for currency; a version whose exe is missing on disk is
+    dropped so the caller never offers a broken push. Ordered by version number
+    (descending) so a rollback dropdown reads newest-build-first regardless of
+    the order versions were uploaded.
+    """
+    manifest = _read_manifest(binkey)
+    current = manifest.get('current')
+    out = []
+    for entry in manifest.get('versions', []):
+        version = entry.get('version')
+        if not version or not os.path.isfile(_version_exe_path(binkey, version)):
+            continue
+        out.append({
+            'version': version,
+            'uploadedat': entry.get('uploadedat'),
+            'size': entry.get('size'),
+            'iscurrent': version == current,
+        })
+    out.sort(key=lambda item: _version_sort_key(item['version']), reverse=True)
+    return out
+
+
+def current_version(binkey):
+    """The current version string, or None when only a legacy flat file exists."""
+    manifest = _read_manifest(binkey)
+    current = manifest.get('current')
+    if current and os.path.isfile(_version_exe_path(binkey, current)):
+        return current
+    return None
+
+
+def current_path(binkey):
+    """Absolute path to the exe the packager should ship, or None.
+
+    Prefers the current managed version; falls back to the legacy flat file so a
+    site that staged a binary before versioning still packages it.
+    """
+    version = current_version(binkey)
+    if version:
+        return _version_exe_path(binkey, version)
+    legacy = _legacy_path(binkey)
+    if os.path.isfile(legacy):
+        return legacy
+    return None
+
+
+def legacy_status(binkey):
+    """Describe an unmanaged legacy flat file, or None when there is none.
+
+    Returned only when a flat file exists and no managed version is current, so
+    the UI can show its detected version and offer one-click adoption without
+    the operator re-uploading. {version} is the PE file version if readable,
+    else None.
+    """
+    if current_version(binkey):
+        return None
+    legacy = _legacy_path(binkey)
+    if not os.path.isfile(legacy):
+        return None
+    try:
+        size = os.path.getsize(legacy)
+    except OSError:
+        size = None
+    return {
+        'version': read_pe_file_version_from_path(legacy),
+        'size': size,
+    }
+
+
+def adopt_legacy(binkey, version):
+    """Copy the legacy flat file into the version store as a staged version.
+
+    Reads the flat file, validates it as a PE, and stores it under the given
+    version (making it current). Returns the fresh manifest view, or None when
+    there is no legacy file or it is not a PE. Caller supplies the version -
+    typically the detected PE version, or an operator override when the binary
+    carries no version resource.
+    """
+    legacy = _legacy_path(binkey)
+    if not os.path.isfile(legacy):
+        return None
+    try:
+        with open(legacy, 'rb') as handle:
+            data = handle.read()
+    except OSError:
+        return None
+    if not looks_like_pe(data):
+        return None
+    return store_version(binkey, version, data)
+
+
+def _prune(binkey, manifest):
+    """Drop versions past the retention window, never removing the current one."""
+    current = manifest.get('current')
+    versions = manifest.get('versions', [])
+    keep = []
+    removed = 0
+    for index, entry in enumerate(versions):
+        version = entry.get('version')
+        # Keep the RETAIN newest (list is newest-first) plus the current always.
+        if index < RETAIN or version == current:
+            keep.append(entry)
+            continue
+        # Beyond the window and not current: remove its directory.
+        _remove_version_dir(binkey, version)
+        removed += 1
+    manifest['versions'] = keep
+    return removed
+
+
+def _remove_version_dir(binkey, version):
+    directory = os.path.join(_binary_dir(binkey), version)
+    try:
+        exe = _version_exe_path(binkey, version)
+        if os.path.isfile(exe):
+            os.remove(exe)
+        if os.path.isdir(directory) and not os.listdir(directory):
+            os.rmdir(directory)
+    except OSError:
+        # Best effort: a locked or already-gone file must not fail the upload
+        # that triggered pruning. The manifest no longer references it either way.
+        pass
+
+
+def store_version(binkey, version, data, make_current=True):
+    """Stage an uploaded binary as a new version.
+
+    Writes data to siteagent/<binkey>/<version>/<exe>, records it newest-first in
+    the manifest (de-duping a re-upload of the same version in place), and prunes
+    older versions past RETAIN. When make_current is True the new version also
+    becomes the current staged build; pass False to stage a rollback/legacy build
+    that should appear in the version list without displacing the active current.
+    Returns the fresh manifest view {current, versions:[...]}. Caller must have
+    validated binkey, version, and that data is a PE binary.
+    """
+    os.makedirs(os.path.join(_binary_dir(binkey), version), exist_ok=True)
+    with open(_version_exe_path(binkey, version), 'wb') as handle:
+        handle.write(data)
+
+    manifest = _read_manifest(binkey)
+    versions = [entry for entry in manifest.get('versions', [])
+                if entry.get('version') != version]
+    versions.insert(0, {
+        'version': version,
+        'uploadedat': datetime.utcnow().isoformat() + 'Z',
+        'size': len(data),
+        # The identity of the BYTES, not of the label. A version string is
+        # chosen by whoever uploads, and re-uploading the same string replaces
+        # the file in place - without this, a swap under a trusted label leaves
+        # no trace. It is also what an operator compares against the build they
+        # meant to ship, and what package time can check before handing an exe
+        # to the fleet.
+        'sha256': hashlib.sha256(data).hexdigest(),
+    })
+    manifest['versions'] = versions
+    if make_current or not manifest.get('current'):
+        manifest['current'] = version
+    _prune(binkey, manifest)
+    _write_manifest(binkey, manifest)
+    return {
+        'current': manifest['current'],
+        'versions': list_versions(binkey),
+    }
+
+
+def set_current(binkey, version):
+    """Point 'current' at an already-staged version. Returns True on success.
+
+    Used to roll back to a retained version. Refuses a version that is not
+    staged on disk so current never dangles.
+    """
+    if not os.path.isfile(_version_exe_path(binkey, version)):
+        return False
+    manifest = _read_manifest(binkey)
+    if not any(entry.get('version') == version
+               for entry in manifest.get('versions', [])):
+        return False
+    manifest['current'] = version
+    _write_manifest(binkey, manifest)
+    return True

plugins/endpoints/api/agentupload.py

@@ -0,0 +1,231 @@
+"""Agent binary upload and retention routes.
+
+Lets an operator drop in a new shopdbagent.exe or shopdb-endpoint-tray.exe from
+the Endpoints page, keep the last few versions, and roll the current pointer
+back to a retained build. The actual staging/retention logic lives in
+agentstore.py; this module is only the HTTP surface and authorization.
+
+Authorization boundary (deliberate):
+  - Uploading, listing, and selecting the current staged version is
+    endpoints.agentpackage - the same grant that already lets someone build and
+    download the site-agent ZIP. Staging a binary only changes what a FUTURE
+    download contains; it does not touch any running endpoint.
+  - Pushing that binary to live endpoints (agent replacement) is a separate,
+    heavier grant, endpoints.agentupdate, and is NOT wired here. It is a distinct
+    command family from application deploys (endpoints.deploy) so app-push rights
+    never imply SYSTEM-level agent replacement. That push pipe is a later slice.
+
+Uploads are capped and PE-checked so a wrong or hostile file cannot be staged.
+"""
+
+from flask import request
+
+from shopdb.api import (success_response, error_response, ErrorCodes, AuditLog, db,
+                        require_permission)
+
+from .routes import endpoints_bp
+from . import agentstore
+
+# Hard cap on an uploaded agent binary. The real agent is a few MB; this is a
+# generous ceiling that still refuses an operator who points at a giant wrong
+# file before it is buffered fully into memory-staged storage.
+_MAX_UPLOAD_BYTES = 64 * 1024 * 1024
+
+
+@endpoints_bp.route('/siteagent/binaries/<binkey>', methods=['GET'])
+@require_permission('endpoints.agentpackage')
+def list_agent_binaries(binkey):
+    """List staged versions for a binary (agent or tray), newest first."""
+    if not agentstore.is_valid_binary_key(binkey):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'binkey must be one of: agent, tray',
+            http_code=400)
+    return success_response({
+        'binary': binkey,
+        'current': agentstore.current_version(binkey),
+        'versions': agentstore.list_versions(binkey),
+    })
+
+
+@endpoints_bp.route('/siteagent/binaries/<binkey>', methods=['POST'])
+@require_permission('endpoints.agentpackage')
+def upload_agent_binary(binkey):
+    """Stage an uploaded binary as a new version.
+
+    Expects multipart/form-data with a 'file' upload and a 'version' field. The
+    version must be a strict dotted-numeric string (for example 1.6.3) so it is
+    safe as a directory name and orderable. The upload must be a Windows PE
+    executable. Older versions past the retention window are pruned, but never
+    the current one. By default the upload becomes the current staged build; send
+    makecurrent=false to stage a rollback/legacy build that joins the version
+    list without displacing the active current.
+    """
+    version = (request.form.get('version') or '').strip()
+    makecurrent = (request.form.get('makecurrent') or 'true').strip().lower()
+    makecurrent = makecurrent not in ('false', '0', 'no')
+    if not agentstore.is_valid_binary_key(binkey):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'binkey must be one of: agent, tray',
+            http_code=400)
+    if not agentstore.is_valid_version(version):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'version must be a dotted-numeric string such as 1.6.3',
+            http_code=400)
+
+    upload = request.files.get('file')
+    if upload is None or not upload.filename:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'a file upload is required',
+            http_code=400)
+
+    data = upload.read(_MAX_UPLOAD_BYTES + 1)
+    if len(data) > _MAX_UPLOAD_BYTES:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'uploaded binary exceeds the size limit',
+            http_code=400)
+    if not agentstore.looks_like_pe(data):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'uploaded file is not a Windows executable',
+            http_code=400)
+
+    result = agentstore.store_version(binkey, version, data,
+                                      make_current=makecurrent)
+
+    # This is the binary every future package installs and runs as SYSTEM on
+    # the fleet. Without a record, an incident has no answer to "who staged
+    # this, and when" - the manifest holds the file, not the person. The digest
+    # identifies the BYTES, because a version string is chosen by whoever
+    # uploads and re-uploading one replaces the file in place.
+    entry = next((v for v in result['versions']
+                  if v.get('version') == version), {})
+    AuditLog.log(
+        'uploaded', 'AgentBinary', entityname='%s %s' % (binkey, version),
+        changes={'sha256': entry.get('sha256'), 'size': entry.get('size'),
+                 'madecurrent': makecurrent})
+    db.session.commit()
+
+    return success_response({
+        'binary': binkey,
+        'current': result['current'],
+        'versions': result['versions'],
+    })
+
+
+@endpoints_bp.route('/siteagent/binaries/<binkey>/detect', methods=['POST'])
+@require_permission('endpoints.agentpackage')
+def detect_agent_binary_version(binkey):
+    """Read the PE file version of an uploaded EXE without staging it.
+
+    The Build Site Agent page calls this on file-select so the version field is
+    prefilled from the binary's own version resource - the operator does not
+    have to read the EXE properties by hand for a current-release upload.
+    Returns {version} which is null when the file carries no readable version.
+    """
+    if not agentstore.is_valid_binary_key(binkey):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'binkey must be one of: agent, tray',
+            http_code=400)
+
+    upload = request.files.get('file')
+    if upload is None or not upload.filename:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'a file upload is required',
+            http_code=400)
+
+    data = upload.read(_MAX_UPLOAD_BYTES + 1)
+    if len(data) > _MAX_UPLOAD_BYTES:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'uploaded binary exceeds the size limit',
+            http_code=400)
+    if not agentstore.looks_like_pe(data):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'uploaded file is not a Windows executable',
+            http_code=400)
+
+    return success_response({
+        'binary': binkey,
+        'version': agentstore.read_pe_file_version(data),
+    })
+
+
+@endpoints_bp.route('/siteagent/binaries/<binkey>/adopt', methods=['POST'])
+@require_permission('endpoints.agentpackage')
+def adopt_legacy_agent_binary(binkey):
+    """Adopt the unmanaged legacy flat file into the version store.
+
+    The pre-versioning install dropped a single shopdbagent.exe (or tray exe)
+    straight under siteagent/. This copies that file in as a real staged version
+    so it shows a version and joins retention, without the operator having to
+    re-upload it. The version comes from the request when the binary carries no
+    readable PE version resource; otherwise the detected version is used.
+    """
+    if not agentstore.is_valid_binary_key(binkey):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'binkey must be one of: agent, tray',
+            http_code=400)
+
+    status = agentstore.legacy_status(binkey)
+    if status is None:
+        return error_response(
+            ErrorCodes.NOT_FOUND,
+            'there is no unmanaged legacy binary to adopt',
+            http_code=404)
+
+    source = request.get_json(silent=True) or {}
+    version = (source.get('version') or status.get('version') or '').strip()
+    if not agentstore.is_valid_version(version):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'version must be a dotted-numeric string such as 1.6.3',
+            http_code=400)
+
+    result = agentstore.adopt_legacy(binkey, version)
+    if result is None:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'the legacy binary could not be adopted',
+            http_code=400)
+    return success_response({
+        'binary': binkey,
+        'current': result['current'],
+        'versions': result['versions'],
+    })
+
+
+@endpoints_bp.route('/siteagent/binaries/<binkey>/current', methods=['PUT'])
+@require_permission('endpoints.agentpackage')
+def set_current_agent_binary(binkey):
+    """Point 'current' at an already-staged version (roll back or forward)."""
+    if not agentstore.is_valid_binary_key(binkey):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'binkey must be one of: agent, tray',
+            http_code=400)
+    source = request.get_json(silent=True) or {}
+    version = (source.get('version') or '').strip()
+    if not agentstore.is_valid_version(version):
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'version must be a dotted-numeric string such as 1.6.3',
+            http_code=400)
+    if not agentstore.set_current(binkey, version):
+        return error_response(
+            ErrorCodes.NOT_FOUND,
+            'that version is not staged',
+            http_code=404)
+    return success_response({
+        'binary': binkey,
+        'current': agentstore.current_version(binkey),
+        'versions': agentstore.list_versions(binkey),
+    })

plugins/endpoints/api/routes.py

@@ -444,6 +444,7 @@ def panel_status(asset_id: int):
         field('CPU %', state.cpupercent),
         field('Memory %', state.memorypercent),
         field('Agent', state.agentversion, mono=True),
+        field('Tray', state.trayversion, mono=True),
         field('Last reported',
               state.lastreportedat.isoformat() + 'Z' if state.lastreportedat else None),
     ]

plugins/endpoints/api/siteagent.py

@@ -35,6 +35,7 @@ from shopdb.api import (success_response, error_response, ErrorCodes,
                         require_permission)
 
 from .routes import endpoints_bp
+from . import agentstore
 
 # Prebuilt, staged agent binaries. Built out of band and dropped under
 # instance/siteagent/ (mirrors the adoption tool's STAGED_EXE_RELPATH model).
@@ -446,13 +447,23 @@ else {{
 
 
 def _siteagent_status_payload():
-    """Whether a prebuilt agent binary is staged for packaging."""
-    agent_staged = os.path.isfile(_staged_path(STAGED_AGENT_RELPATH))
-    tray_staged = os.path.isfile(_staged_path(STAGED_TRAY_RELPATH))
+    """Whether a prebuilt agent binary is staged for packaging.
+
+    Reports both the legacy flat-file staging and the versioned store so the UI
+    can show current versions and an expandable retained-version history.
+    """
+    agent_staged = agentstore.current_path('agent') is not None
+    tray_staged = agentstore.current_path('tray') is not None
     return {
         'agentstaged': agent_staged,
         'traystaged': tray_staged,
         'certavailable': _server_cert_path() is not None,
+        'agentcurrent': agentstore.current_version('agent'),
+        'traycurrent': agentstore.current_version('tray'),
+        'agentversions': agentstore.list_versions('agent'),
+        'trayversions': agentstore.list_versions('tray'),
+        'agentlegacy': agentstore.legacy_status('agent'),
+        'traylegacy': agentstore.legacy_status('tray'),
     }
 
 
@@ -545,11 +556,11 @@ def package_siteagent():
         if os.path.isfile(UNINSTALLER_PATH):
             archive.write(UNINSTALLER_PATH, 'uninstall-shopdbagent.ps1')
 
-        agent = _staged_path(STAGED_AGENT_RELPATH)
-        if os.path.isfile(agent):
+        agent = agentstore.current_path('agent')
+        if agent and os.path.isfile(agent):
             archive.write(agent, 'shopdbagent.exe')
-        tray = _staged_path(STAGED_TRAY_RELPATH)
-        if os.path.isfile(tray):
+        tray = agentstore.current_path('tray')
+        if tray and os.path.isfile(tray):
             archive.write(tray, 'shopdb-endpoint-tray.exe')
         if cert_pem:
             archive.writestr('server.crt', cert_pem)
@@ -557,8 +568,16 @@ def package_siteagent():
             archive.write(certpath, 'server.crt')
 
     buffer.seek(0)
+    # Stamp the staged agent version into the download filename so a DT operator
+    # can see which agent build a package carries at a glance. This is cosmetic:
+    # install.ps1 finds the exe by its fixed name inside the ZIP, so the download
+    # name never affects the install. Falls back to the unversioned name when no
+    # managed version is current (only a legacy flat file is staged).
+    agentversion = agentstore.current_version('agent')
+    download_name = ('shopdb-endpoint-agent-{0}.zip'.format(agentversion)
+                     if agentversion else 'shopdb-endpoint-agent.zip')
     return send_file(
         buffer,
         mimetype='application/zip',
         as_attachment=True,
-        download_name='shopdb-endpoint-agent.zip')
+        download_name=download_name)