Files

cproudlock f9d6b57f0f Move the documentation to the line that ships, and correct it against the code

The docs lived on one lineage and the fleet code on another. That is why six
pages described a shared fleet key as how an agent authenticates, why
COLLECTOR-AUTH had to warn that the per-PC credential code was not in the
repository it sat in, and why ADR-019 recorded a decision whose implementation
was somewhere else. Documentation that cannot see the code it documents goes
stale by construction, and no amount of editing fixes that.

So the corpus moves here: 84 files, 56 pages, 20 ADRs, the proposals, INDEX.md,
llms.txt and both gates. Filenames are unchanged, because a wiki page name is
derived from the filename and a rename breaks every link anybody saved.

THE POINT OF THE MOVE IS THE CORRECTION IT ENABLES. Every caveat that said "not
in this tree" was false the moment the files landed beside the code, so each was
rewritten from what is actually here:

- COLLECTOR-AUTH gained the real enroll request body, the two bounds on the
  unauthenticated route (per-IP rate limit, pending cap with stale rows dropped
  before a real PC is refused), and the rejected pending reason that binds to
  the endpoint identity rather than the nonce.
- ADR-019 now describes an implementation that is present, including its tests,
  and says plainly that what remains is the FLEET migration, not the code.
- proposals/device-identity claimed phase 1 was unbuilt. plugins/computers
  declares deviceid on the collector schema and prefers it over the older
  fallbacks. Corrected in the page, its summary and the index.

WINDOWS/IIS IS NOW DOCUMENTED AS THE LEGACY PATH, per the product decision, and
carefully: it is what production runs today. Every Windows page opens by saying
it is supported, not for a new site, and where a new site should go instead. No
procedure was cut - an operator on an IIS box at 2am needs these pages to work
exactly as well tomorrow. MIGRATE-TOPOLOGY stops being a footnote and becomes
the off-ramp, which is why it nearly doubled: what was there did not match how
the Docker stack really works here.

The Docker material that already lived on this line was kept and given
ownership rather than buried under the ported Windows-centric prose: DEPLOY now
describes the four services, the migrate service that runs the upgrade chain
before api starts, TLS terminated by nginx, and the plugin count corrected from
thirteen to seventeen - a number both lineages had wrong.

ROADMAP is rewritten from evidence rather than memory: what has shipped, read
out of the changelog, the ADRs and the manifests, and ahead of it exactly two
items - finalize a distributed release and polish the setup wizard.

PROJECT-MAP is generated and was stale; the GENERATOR was what was wrong.
--check passes now.

API-REFERENCE is retired to a pointer. /api/docs serves 573 operations with
derived auth, query parameters and harvested examples, and a hand-written page
competing with that is a liability. The file stays so its wiki page and its
inbound links survive.

AND THE MOVE TURNED ON A SCRUB THAT HAD NEVER RUN HERE. test_docs_publishable
keys on docs/*.md, which this line did not have, so it skipped - its own comment
predicted what would surface. Porting the corpus activated it and it found 48
lines that must not reach a published wiki: branch names abbreviating the site,
assistant-tooling paths, the site name in two deployment pages, and an employee
ID in a Windows path that the scrub does not even look for.

2026-09-19 09:10:15 -04:00

9.0 KiB

Raw Blame History

ADR-016: Credential delivery to the fleet

Status: SUPERSEDED by ADR-019
Date: 2026-08-11
Deciders: ShopDB maintainers
Relates to: ADR-006 (collector contract), ADR-012 (GE-Enforce manifest ownership), ADR-015 (site-specific configuration)

Do not build against this. Nothing in it was built. The model below has a PC ask ShopDB for credentials chosen by server-side targeting rules. The GET /api/collector/credentials endpoint, the credentials.fetch and credentials.manage permissions and the rule store do not exist in the code, and a reader searching for them will not find them.

What shipped instead is the opposite shape: the endpoint holds ONE secret of its own, obtained by enrolling, and there are no targeting rules to resolve. ADR-019 records that decision.

The PROBLEM stated below is still the real problem, and ADR-019 cites it. Kept as the record of a design that was decided and then not taken.

Context

Shopfloor bays need credentials they cannot prompt for. A collections bay loses the Windows Credential Manager entry for its controller subnet periodically - suspected Defender or Intune scrub - and without it, controller-side connections need an interactive prompt, so an unattended bay simply stops working. A machine whose NTLARS config points at a program share needs a credential to reach that share for the same reason.

Today this is solved by Set-ControllerCredential.ps1 on the SFLD share:

$Target   = '192.168.1.1'
$Username = 'CHANGEME'
$Password = 'CHANGEME'

A person edits the values into the file, GE-Enforce runs it every cycle, and cmdkey /add re-applies it. It works, and it has three problems.

The password is cleartext in a file on a share, readable by anything that can read the share - a wider exposure than the machine-local secret it becomes. Rotating it means editing that file and hoping: there is no way to ask which bays have picked up the new value. And it is one value for everything, while the requirement is per-bay variation: sites will have machines needing different credentials from their neighbours.

Per-bay variation is what rules out the obvious alternative. GE-Enforce scopes are per PC TYPE, so expressing per-machine credentials as manifest scopes means a scope per bay, which is not a model. The manifest can deliver a value (Registry entries with inline payloads already do this for the display scope), but it cannot decide WHICH value a given PC should get.

Decision

ShopDB owns credential definitions and their targeting. A PC asks for its own credentials and receives a decided answer; it never receives rules to evaluate.

Targeting

A credential rule carries a targeting expression using the SAME axes GE-Enforce already filters on, plus those the asset model knows:

Axis	Source	Notes
hostname	reported	exact or `-like` glob (`WJRP*`)
machine	PC -> machine link	the machine the PC drives
model	asset model	e.g. every Okuma of one model
controller OS	asset / reported	version-valued, like the existing CmmVersion gate
PC type	ComputerType	with GE-Enforce ALIAS EXPANSION
GE-Enforce profile	manifest scope	the imaging profile
DNC/NTLARS setting	stored backup projection	e.g. any machine whose `DataHost` is a given UNC
site default	setting	the fallback

The DNC axis is not a special case bolted on: the NTLARS projection ShopDB already stores contains DataHost, DataPath and MarkMasterPath, so "every machine that talks to \ntshare" is a selector over data already held. It is also the axis that answers "which machines even need a credential", which nothing answers today.

Precedence

Overlapping matches are guaranteed, not exceptional - a hostname glob and a per-model rule will both hit the same bay. Precedence is therefore EXPLICIT, never emergent:

Each rule carries an integer priority. Higher wins. This is the only thing an operator needs to reason about.
Ties break on scope specificity, in the order of the table above (hostname most specific, site default least).
Remaining ties break on the lowest rule id, so the result is stable rather than dependent on row order.

A resolve endpoint must be able to EXPLAIN itself - "this PC got rule 12, matched on model, beating rule 4 on priority" - or nobody will trust it. The GE-Enforce simulator (applicable_entry_names) already set this precedent.

Reuse the existing matcher

plugins/geenforce/filters.py already mirrors the engine's targeting: alias groups, hostname globs, the rule that a machine-number filter with no machine number EXCLUDES rather than defaults. The resolver reuses it. It must not become a third implementation of the same matching logic - there are already two (the PowerShell engine and its Python mirror), kept honest by a parity harness, and a third would drift silently.

Alias expansion in particular is not optional: if a rule says PCTypes: Standard, it must mean what it means in GE-Enforce, or the two systems will disagree about who a rule covers.

Targeting is not detection

Who gets a credential and whether it is already applied are separate questions, exactly as PCTypes and DetectionMethod are separate in the manifest. The client decides the second locally - is this cmdkey entry already present and correct - and rewrites only on drift. Conflating them rewrites the credential every cycle instead of healing it, and turns the audit trail into noise.

Storage

Encrypted at rest with Fernet. cryptography is already a dependency.
The key lives OUTSIDE the database - instance file or environment, like SECRET_KEY. A key in the database it protects is not encryption.
Write-only through the API. Masked on read, as smtp_password already is. A fleet PC receives a value; a human never reads one back.
A dedicated credentials.manage permission for authoring.

Delivery

GET /api/collector/credentials     X-API-Key: <credentials.fetch token>

A DEDICATED credentials.fetch scope, not collector.ingest. A leaked collector key must not yield controller passwords.
The caller is resolved by hostname; it receives only what it is entitled to, and never the rule set.
Every fetch is audited: which PC, which credential, when. The audit log exists; this belongs in it.
The client half is a shared helper alongside ShopdbBackupClient.psm1: fetch, compare, cmdkey /add on drift, log once per state.

Consequences

Positive:

The cleartext credential leaves the share.
Rotation becomes a settings change plus a report of who has picked it up, instead of a file edit and a hope.
Per-bay, per-model and per-share credentials become expressible, which is the actual requirement.
"Which machines need a credential" becomes answerable from the DNC data already stored.

Negative, and these are real:

ShopDB becomes a credential store. That is a different security posture from an asset database, and it earns the obligations above rather than choosing them.
The key is a new single point of loss. Restore the database without it and every stored credential is unrecoverable. docs/BACKUP-RESTORE.md must say so IN THE SAME CHANGE, not later.
A PC that cannot reach ShopDB gets no credential. The client must keep the last known good value rather than clearing a working entry on a failed fetch.
Targeting complexity is real complexity. Eight axes with priorities will produce a rule set someone has to debug, which is why the explain endpoint is a requirement and not a nicety.

Alternatives rejected

Keep editing the script on the share. Cannot express per-bay values, keeps the cleartext, no rotation story.

A manifest scope per bay. Per-machine credentials as GE-Enforce scopes is a spreadsheet, not a model, and the manifest cannot resolve WHICH value applies.

Encrypted payload in the manifest. DPAPI is per-machine, and one manifest serves many machines, so the payload cannot be encrypted to its readers.

Registry-only provisioning (no ShopDB). A worthwhile FIRST STEP - it moves the secret off the share immediately and needs no new endpoint - but it leaves provisioning per-bay by hand and offers no rotation. Recommended as tier one regardless, since the client helper is the same either way.

Implementation status

Never implemented, and now superseded. The fetch endpoint and the credentials.* permissions described above do not exist in the code.

The note that stood here until 2026-09-18 said the decision still stood and a plugin author designing against it was designing correctly. That is no longer true: design against ADR-019. What credentials the fleet uses today, and where they live, is in FLEET-ARCHITECTURE.

9.0 KiB Raw Blame History