shopdb-flask/docs/GE-ENFORCE-CLIENT.md

GE-Enforce client integration (shopdb manifest source + reporting)

This is the client-side contract for the GE-Enforce manifest-store plugin: how a PC sources its install manifest from shopdb instead of a share file, and how it reports its enforcement result back. It pairs with the plugin proposal in docs/proposals/ge-enforce-plugin.md.

The reference kit lives in plugins/geenforce/client/:

• ShopdbEnforceClient.psm1 - fetch (with ETag + last-known-good cache), shadow compare, and report helpers.
• Invoke-ShopdbEnforce.ps1 - a reference orchestrator that fetches a manifest, runs the UNCHANGED engine against it, and reports the result.

These are site-neutral references, not the live dispatcher. A site adapts them into its GE-Enforce.ps1 flow. The engine (Install-FromManifest.ps1), detection, self-heal, and SMB payload resolution are untouched - only the source of the manifest JSON moves, plus a result report.

What does NOT change

• The engine and its four filters, all detection methods, self-heal, marker files, and SMB payload staging.
• Payload transport for smb rows: the client still mounts the share and resolves apps/... paths exactly as today. Only the manifest JSON source moves.
• The fail-safe posture: any error exits 0. A PC is never blocked or broken because shopdb is unreachable.

Configuration

Registry (provisioned by Azure DSC, same channel as the SFLD credentials):

HKLM:\SOFTWARE\GE\ShopDB
  BaseUrl   https://shopdb.<site>.geaerospace.net
  ApiToken  <a geenforce.fetch (+ geenforce.report) managed service token>

Mint the token in shopdb: Settings > API Tokens, scopes geenforce.fetch and geenforce.report. It is a service token (owner must hold those permissions).

Fetch contract

GET /api/geenforce/manifest?pctype=<scope>[&phase=runtime]
    X-API-Key: <token>
    If-None-Match: <cached ETag>     (optional)

• 200 - body is the full published manifest JSON for the scope (fat client: the engine filters locally, exactly as today). Response headers carry ETag and X-Manifest-Version. Cache the body + ETag + version.
• 304 - your cached copy is current; use it.
• 404 - no such scope, or the scope has no published version yet.
• Network failure - enforce from the last-known-good cached manifest (the kit does this automatically) and log a warning.

The served manifest is always the current PUBLISHED snapshot, never a live draft being edited in shopdb, so a half-finished edit can never reach a PC.

Report contract

Each enforcement cycle, POST the result (best-effort; a failed report never fails the cycle):

appliedversion is the published version the client actually ran, not the latest one available.

POST /api/geenforce/report
    X-API-Key: <token>
    Content-Type: application/json
{
  "hostname": "CMMPC01",
  "scopename": "gea-shopfloor-cmm",
  "appliedversion": 3,
  "enforcerversion": "2.6",
  "counts":  { "installed": 1, "skipped": 3, "failed": 0, "filtered": 2 },
  "results": [
    { "name": "PC-DMIS 2019 R2", "action": "installed", "selfhealed": true },
    { "name": "Protect Viewer",  "action": "skipped" },
    { "name": "eDNC",            "action": "failed", "exitcode": 1603,
      "message": "MSI 1603" }
  ]
}

• appliedversion lets shopdb show which PCs received the latest manifest (receivedlatest in the fleet view).
• action per entry: installed (fired - a self-heal when it should already be present), skipped (detected present), failed, filtered. selfhealed marks a drift correction.
• shopdb keeps the latest report per (hostname, scope, phase) plus history, and surfaces it under GE-Enforce > Enforcement Reports.

The engine already computes these counts (installed/skipped/failed/pcFiltered at the end of its main loop) and knows each entry's action; shape them into the results list at the call site (New-ShopdbReport in the kit takes a summary with Installed/Skipped/Failed/Filtered + a Results list).

The engine emits per-entry outcomes in PascalCase (Name/Action/SelfHealed/ ExitCode/Message); New-ShopdbReport maps every per-entry key down to the lowercase names above (name/action/selfhealed/exitcode/message) before POST, so the entire wire contract shopdb reads is lowercase. ConvertTo-ShopdbSummary first normalizes whatever the engine returns (a well-formed summary, a bare return code, $null, or several emitted objects) into the count/results shape New-ShopdbReport expects, so a not-yet-compliant engine still produces a valid report.

Common-scope inheritance (opt-in, OFF by default)

By default a PC enforces its -Scope ALONE. Pass -IncludeCommon to also fetch the fleet-wide common scope and merge it on top, mirroring the real GE-Enforce.ps1 (which applies common\manifest.json first, then the pctype's). When enabled, Invoke-ShopdbEnforce.ps1 fetches common in addition to -Scope and merges it via Merge-ShopdbManifests:

• entries are keyed by Name (case-insensitive);
• common's unique entries come first, then all pctype entries (common enforces ahead of the pctype, as on the share);
• on a Name conflict the pctype entry wins (its override replaces common's).

Common is fetched over the same fail-safe path (ETag + last-known-good cache). -CommonScope <name> inherits a different fleet scope; a run whose -Scope already is the common scope does not merge itself.

Displays do NOT use this: the gea-shopfloor-display scope is self-sufficient, so the display scheduled task omits -IncludeCommon. Common-merge exists for a future share-less non-display PC that genuinely needs the fleet-wide entries (which would first require repackaging common's SMB payloads as http/inline). The three display subtypes (Dashboard, Lobby, 3D Print Room), selected by C:\Enrollment\display-type.txt, carry their shared policy inside the display scope itself, not via common.

Fail-safe is observable, not silent

Any error still exits 0 - a bad web app never blocks or breaks a PC. But a fresh display with an EMPTY cache (first boot, shopdb unreachable or the token rejected with 401 / a TLS-trust failure) would otherwise enforce nothing silently. When no manifest and no cache are available, the kit:

• writes a Windows Application event-log entry (source ShopdbEnforce, event id 1001, type Error) naming the scope and the reason (HTTP status or transport error), and
• fires a best-effort report ping (counts failed: 1, a single (manifest-fetch) result carrying the reason) so the miss surfaces under GE-Enforce > Enforcement Reports.

The cycle still exits 0; the signal just makes the no-enforcement state visible.

Cutover (safe, staged)

1. Configure the registry values on a canary PC; mint the token.
2. Shadow mode: run Invoke-ShopdbEnforce.ps1 -ShadowMode -ShareManifestPath <current share manifest>. It installs from the SHARE (no behavior change), fetches the shopdb manifest, logs any diff, and reports. Watch for zero diffs across one PC of every pctype for ~20 cycles.
3. Read cutover: drop -ShadowMode. The engine now runs against the shopdb-sourced manifest; payloads still come from the share. Rollback is a one-line revert to the share-sourced call. Keep exporting manifests from shopdb to the share (GE-Enforce > Manifests > Export to Share) so the share stays a break-glass copy.
4. Payload migration (optional, later): move small scripts/configs to http/inline payloads, verified by payloadsha256. Big MSIs stay on SMB.

Do not cut a fleet over before the shadow diffs are clean. Preinstall (phase=preinstall) stays share-sourced until its own cutover is planned - it runs before enrollment provisions a token.

Security notes

• The client runs as SYSTEM, so shopdb's TLS certificate must be in the machine trust store (air-gapped/self-signed sites provision the CA via the same DSC step as the token).
• http/inline payloads are verified against payloadsha256 before running, independent of how the entry detects install state. This is the real integrity guarantee and holds even over plain HTTP inside a trusted segment.
• The token is a scoped service token: it can fetch manifests and report, and nothing else.