# Adoption tool spike

Status: spike. Built on the `origin/main` baseline so it can be cherry-picked as
a single unit once endpoint agent development is complete.

## What it is

A one-shot, agentless enrollment tool. An admin generates a small download from
the Endpoints key settings page; running the tool once on a PC creates a ShopDB
PC (Computer) and Endpoint entry using only the endpoints collector key. It is
NOT the endpoint agent: it installs nothing, runs no service, and sends no
ongoing telemetry. It targets sites that want an inventory entry without running
the full agent.

## How it works

1. Admin generates or reuses an endpoint agent key (existing `/agentkey` flow).
2. Admin opens the "Adoption tool" section, confirms the base URL (prefilled
   from the browser origin) and pastes the collector key (prefilled when a key
   was just generated, since the secret is only shown once).
3. `POST /api/endpoints/adoptiontool/package` (admin-gated) returns a ZIP with
   `adopt.config.json`, `README.txt`, and `shopdb-adopt.exe` when a prebuilt
   binary is staged on the server.
4. On the target PC, `shopdb-adopt.exe` reads the config beside it (or CLI args),
   then POSTs to `/api/collector/endpoints` with `X-API-Key` and `adopt=true`.
   The existing `_adopt_computer` path creates the Computer + EndpointState.

## Collection

The tool gathers the same identity, hardware, and SBOM subset the endpoint
agent collects, using identical WMI queries and wire keys so the server stores
it without translation:

- Identity: `hostname`, `loggedinuser`, `ipaddress`.
- Hardware: `serialnumber` (Win32_BIOS), `vendorname` / `pctype` / `modelnumber`
  (Win32_ComputerSystem), `osname` and `lastboottime` (Win32_OperatingSystem).
- SBOM: `applications` = both Uninstall registry hives (64-bit + WOW6432Node),
  de-duped `{displayname, displayversion, publisher}`. The server logs this as
  an unpersisted key today (same as the agent) until the SBOM store lands.

The tool requires administrator rights (enforced by its app manifest
`requireAdministrator`, with a runtime elevation guard) because the machine
Uninstall hives and full WMI need elevation, or collection would be silently
partial.

## Cherry-pick boundary

The spike is deliberately isolated. Cherry-pick exactly:

- `agent/ShopDbAdoptionTool/` (new standalone tool project, incl. `app.manifest`)
- `agent/ShopDbEndpointAgent.slnx` (one line adding the project)
- `plugins/endpoints/api/adoption.py` (new module; attaches to `endpoints_bp`)
- `plugins/endpoints/api/__init__.py` (one-line import to register the route)
- `plugins/endpoints/frontend/views/AgentKeySettings.vue` (new UI section only)
- `plugins/endpoints/ADOPTION-TOOL-SPIKE.md` (this file)

`plugins/endpoints/api/routes.py` is intentionally untouched so the delivery
spike changes there do not tangle with this feature.

## Prebuilt exe distribution

The api container has no .NET SDK, so the package embeds the exe only when a
prebuilt copy is staged at `instance/adoptiontool/shopdb-adopt.exe`. Otherwise
the ZIP ships the config plus README (build the exe out of band, same model as
the endpoint agent installer bundle). Follow-up: a CI job that publishes
`shopdb-adopt.exe` and stages it into the image or instance path.

## Known follow-ups

- Agentless health signal: an adopted PC never reports again, so
  `EndpointState.lastreportedat` reflects only the adoption moment. The fleet
  health/dashboard logic should distinguish "agentless, adopted" from
  "agent expected but silent" so these PCs do not read as permanently failed.
  Left out of this spike to keep the server create-path unchanged for a clean
  cherry-pick; the tool does not send an `agentless` marker yet because the
  server does not persist one (`KNOWN_PAYLOAD_KEYS`).
- CI packaging of the prebuilt exe (see above).