Files

cproudlock 534f179ee6 Make main the lean product a site receives

main was 16 days and 259 commits behind the line the product is actually built
on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It
was neither current nor curated - just stale. This brings it forward and, at the
same time, makes it mean something: main is what a receiving site installs, and
nothing else.

WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides,
knowledgebase, machines, network, notifications, printers, slides, tools,
warranty - plus applications, which is manifest-less core and always ships. The
only manifest dependency inside that set is endpoints on computers, and both are
in it, so the closure is self-contained.

WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb
stay on the site line. So do the Windows installer tree, the VM rehearsal
helpers, the agent tooling config, one site's data loader, the internal audit
and findings records, and the planner spreadsheet. 1,135 tracked files against
1,438.

A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped:

deploy/site-profile-universal.json still named all seventeen plugins. It is the
file docs/DEPLOY.md tells a site to provision from, so a fresh install would
have failed at `flask plugin apply-profile` with PluginError - the first thing a
receiving site does, broken by the branch meant to serve them. It now names the
twelve that exist, and its comment says the two must agree.

agent/ was never refreshed. Whoever populated this branch copied shopdb/,
plugins/, frontend/ and tests/ from the site line and left the agent tree at its
September state: 22 C# and PowerShell sources missing, including AgentCredentials,
EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the
site line had deleted still present. The old tree is internally consistent, so it
compiles, and nothing in CI builds it - every gate was green over a server that
speaks enrollment and per-PC credentials to a bundled agent source that cannot.
Resynced whole.

DECISIONS THIS ENCODES, rather than defers:

- The plugin-authoring lab builds printedparts, whose manifest depends on
  employees, so it could not stay. The lab remains on the site line and main
  ships no build-along tutorial. That is a real loss for an adopting developer
  and is recorded here rather than discovered later.
- Recognition, Training and Recertification notifications are no longer seeded.
  Each splits one notification into a card per employee and renders a photo,
  which needs a plugin this branch does not bundle. Seeding them would offer an
  author a type that cannot resolve anybody. A site that installs employees gets
  them from that plugin's own seed.
- Windows/IIS is documented as the legacy path throughout, and the README leads
  with Docker, because that is what a receiving site gets.

The API description is regenerated for THIS branch - 347 paths and 483
operations, down from 415 and 573 - so the published contract describes what is
here rather than what the site line serves. docs/CONFIG.md lost the two
measuring-tool label keys the code no longer declares, which two lanes had
decided opposite ways.

Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run
rather than skip, and every index line count is derived from the file it names.

2026-09-19 11:24:40 -04:00

5.0 KiB

Raw Blame History

API reference

The reference is generated and served by the app. This page is a pointer to it, plus the two things a specification cannot tell you.

There used to be a hand-written endpoint list here. It competed with the generated spec, lost, and went stale in between - so it was cut rather than maintained. Everything it listed is in the spec, derived from the code: every operation with its auth, its query parameters, its response shape and harvested examples. Counts are in PROJECT-MAP, which is generated; nothing of that kind belongs on this page.

Where the generated reference is

Reach it at	What it is
`GET /api/docs`	The reference, rendered with Redoc. The bundle is vendored in the image, so it renders with no network - which is the only reason it is usable on an air-gapped site.
`GET /api/docs/openapi.json`	The raw OpenAPI 3.1 spec. Also tracked as `docs/openapi.json`, so it can be read from a checkout without running anything; regenerate with `scripts/gen_openapi.py` after any API change.
`GET /api/docs/llms.txt`	The short version, for a machine caller. Also llms.txt in this corpus.
`GET /api/docs/try`	Swagger UI over the same spec, where Execute sends a real request as whoever is signed in on that browser. Off by default (`API_DOCS_TRYIT_ENABLED`) and not something a production site turns on without deciding to.

llms.txt is not a second spec. It is the orientation a caller needs before the spec is useful: the response envelope, how authentication is obtained and sent, the pagination and filtering conventions, and the handful of recipes people get wrong. Read it first, then look operations up in the spec.

Which surface owns what

The spec lists every operation; it does not say which contract governs one. There are three surfaces, and the third is everything else.

Surface	Who calls it	Where its semantics live
Fleet and client contracts	Shop-floor PCs, the endpoint agent, kiosks, displays and printer installers - machines, not browsers	COLLECTOR-INTEGRATION, COLLECTOR-PAYLOADS, COLLECTOR-AUTH, PRINTER-INSTALLER, EVENTSAVER
Bulk import	A script loading a site's data. There is no separate import surface: it drives the same endpoints the UI does, with a header that preserves the source rows' timestamps	IMPORT-API
Core UI API	The Vue frontend, and anything else holding a token	CONTRACT-STABILITY for what is safe to depend on

How auth works at a glance

Four credentials, and which one an operation takes follows from its surface. The spec states it per operation; this is the shape behind it.

JWT - a login token or a Personal Access Token. The core UI API.
Scoped service token - X-API-Key or Authorization: Bearer, minted and revoked per purpose (collector.ingest, collector.ingest.endpoints). A token can be bound to specific resources and is refused anything outside them. This is what the fleet uses.
A per-PC credential - an enrolled endpoint holds its own secret, and revoking one endpoint costs nothing to the rest. See COLLECTOR-AUTH and ADR-019.
A kiosk device token, or an address inside the kiosk's allowlist - a credential for a screen, not authorization for a person. It says which cabinet is asking; the badge on the request says who is standing at it. Both kiosks are off by default and answer 404, not 403, when they are off.

Two rules cover almost everything else:

Every read is behind a permission. Reading is not free, and a site decides what a signed-out visitor may see by granting the seeded guest role the read permissions it chooses - in the same role grid it uses for staff.
Every mutation needs a JWT and a permission or role. None are public.

What is reachable with no credential

This is the inventory a firewall or a deployment reviewer asks for, and it is the one question the spec answers badly - it is a question about the whole surface, not about any one operation.

Do not read it off a page somebody maintains. It is enumerated, with a reason per entry, in tests/test_core/test_public_read_surface.py, which fails the build when a new public read appears without being added to the list. That file is the answer, and it is the answer because it cannot go stale without turning CI red.

5.0 KiB Raw Blame History