shopdb-flask/docs/adr/ADR-016-credential-delivery.md

ADR-016: Credential delivery to the fleet

• Status: ACCEPTED (decided; NOT yet implemented - see Implementation status)
• Date: 2026-08-11
• Deciders: ShopDB maintainers
• Relates to: ADR-006 (collector contract), ADR-012 (GE-Enforce manifest ownership), ADR-015 (site-specific configuration)

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:

1. Each rule carries an integer priority. Higher wins. This is the only thing an operator needs to reason about.
2. Ties break on scope specificity, in the order of the table above (hostname most specific, site default least).
3. 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, 2026-08-14

Nothing in this ADR is built yet. The fetch endpoint and the credentials.* permissions it describes do not exist in the code, and a reader searching for them will not find them.

Recorded here rather than by changing the status, because the decision itself stands: this is how credential delivery WILL work, and a plugin author designing against it is designing correctly. What credentials the fleet uses today, and where they live, is in FLEET-ARCHITECTURE.