# Session Log — 2026-06-02 — GuruConnect Zero-Touch Enrollment

## User
- **User:** Mike Swanson (mike)
- **Machine:** GURU-5070
- **Role:** admin

## Session Summary

The session began as a request to deploy the GuruConnect (GC) agent onto Howard's RMM test machines "to see how things are working," but investigation showed the managed-agent enrollment path wasn't ready, so the work pivoted into designing and building that path end-to-end. Two live test machines were identified under the `AZ Computer Guru` client (`RMM-TEST-MACHINE` / site `Howard-VM`, and `WIN-TG2STMODJG8` / site `Discovery test site`); a duplicate v0.6.38 `RMM-TEST-MACHINE` ghost was noted. The deploy was deliberately parked once it became clear that (a) the GC relay had moved to per-agent `cak_` keys with only a deprecated shared `AGENT_API_KEY` fallback, and (b) the existing embedded-config download path appends a config blob to the end of the signed `.exe`, which voids Authenticode — colliding with the CI code-signing shipped earlier in the day.

The first concrete deliverable was a **signed beta/test release channel**: a `channel: stable | beta` `workflow_dispatch` input added to GuruConnect's `release.yml`, where `beta` produces a signed, prerelease-tagged build (skipping the semver bump/changelog) through the identical fail-closed Azure Trusted Signing path. This closed the "every binary handed to a tester must be signed" gap. A long interview with Mike then shaped the enrollment architecture, producing **SPEC-016 (zero-touch per-site agent enrollment)**: a per-site rotatable enrollment key (long secret + short hex `vN (XXXX)` fingerprint), self-registration that mints a per-machine `cak_` bound to a hardware-salted `machine_uid`, auto-approve + new-enrollment alert, collision-gated activation, and a sign-once base binary + per-site signed wrapper (resolving SPEC-007's signing question). Three enrollment paths (per-site embedded key / flag overrides / technician-assisted) were defined, with only the per-site path in v1 and the others reserved.

Implementation proceeded in reviewed, CI-gated phases. **SPEC-016 Phase A** (server backend: `POST /api/enroll`, per-site key issue/rotate/verify, `machine_uid` dedup + collision gate, `cak_` minting, rate-limiting, migration `010`) was built, reviewed (one HIGH cross-site-move hijack + one MEDIUM timing oracle fixed), and merged via PR #5. **SPEC-016 Phase B** (agent: hardware-salted `machine_uid`, first-run enroll client, DPAPI+ACL `cak_` store, run-mode wiring) was built, reviewed (six findings incl. a re-image-stability bug and a credential-store self-lockout, all fixed), and landed on `main`. During Phase B, Mike authored **SPEC-017 (end-user/sub-user remote access)** and an auto-sync fast-forwarded the whole Phase B line plus SPEC-017 onto `main` outside the PR gate; the planned PR-split became moot but the commits remained cleanly separated.

The credential-store review exposed that the managed agent runs in the **interactive user context** (`HKCU Run`), not SYSTEM, so the SYSTEM-ACL'd `cak_` store would self-lock the agent on second launch. Mike chose **Option A** (run the managed agent as a SYSTEM service), which is also required for the upcoming session-switching feature. This became **SPEC-018 (managed-agent SYSTEM service host + session broker)** — split into its own spec (per Mike) rather than folded into SPEC-013. **SPEC-018 Phase 1** (LocalSystem service install/lifecycle, SCM dispatch, run-as-SYSTEM, HKCU→service autostart swap; session broker/per-session capture worker deferred to Phase 2) was built, reviewed (APPROVE WITH NITS — connected-stop interruption + FFI panic guard fixed), re-reviewed (confirmed closed), and merged via PR #7.

All code work flowed through the coordinator pattern: Coding Agent (opus) → Code Review Agent (opus) → fix pass → focused re-review → CI-green → merge → submodule pointer bump. Two transient Windows-runner CI failures occurred (jobs that never started); both were diagnosed against local builds and cleared on re-run. The session ended at a clean checkpoint: Phase A + Phase B + SPEC-018 Phase 1 merged, three specs in place, with SPEC-018 Phase 2 (capture worker) as the next critical-path item.

## Key Decisions

- **Beta builds get signed via a `channel` input on `release.yml`, not by signing every CI build.** Keeps signing secrets out of PR-triggered runs; `beta` rides the existing fail-closed sign path, skips bump/changelog, publishes a prerelease tag.
- **Two-tier credential model:** a low-sensitivity, rotatable, long per-site enrollment key (embedded, never typed) gates registration; a high-sensitivity per-machine `cak_` is self-provisioned on first run. Rotating a site key blocks new enrollments from old installers but leaves enrolled agents (holding `cak_`) untouched.
- **Enrollment key fingerprint = monotonic version + short HEX** (`v3 (7F2A)`), deliberately NOT the RMM word-code style (`GREEN-FALCON`), so GuruConnect and GuruRMM artifacts are never visually conflated.
- **`machine_uid` salted from stable HARDWARE signals** (SMBIOS UUID primary; motherboard + disk serial fallback), NOT a per-install random salt — so it survives an OS re-image on the same hardware (re-image dedup) while separating distinct boxes. Uniqueness scoped per-tenant `(tenant_id, machine_uid)`.
- **Collision-gated activation:** a detected `machine_uid` collision (e.g. template-cloned VMs sharing a hardware UUID) drops the endpoint to `pending` + alert, requiring dashboard confirmation — the one deliberate exception to auto-approve.
- **Sign once + per-site signed wrapper, both `.exe` and MSI** (ScreenConnect offers both). The signed agent stays byte-identical; per-site config is delivered around the signed bytes (wrapper/MSI/CLI), never appended into the PE.
- **Cross-site enroll is default-refused (`409 ENROLL_SITE_CONFLICT`)** in Phase A — the deliberate-move (`--reassign`) path is deferred — closing a within-tenant machine-hijack vector.
- **Managed agent → SYSTEM service (Option A)**, chosen over patching the store ACL for user-context, because true unattended access and the upcoming session-switching feature both require SYSTEM. Spec'd as its own SPEC-018, separate from SPEC-013.
- **Accepted the auto-sync fast-forward of `main`** rather than rewriting published history against a live auto-sync; SPEC-018 landed as its own commits, and the "separate specs" intent held via clean commit separation.

## Problems Encountered

- **"Entire fleet offline" in RMM** — a rendering artifact: the API returns `is_connected: null`, which the display treated as offline. Real liveness is `last_seen`; both target machines had checked in seconds earlier.
- **Append-config voids Authenticode** — the existing `download_agent` path appends `[MAGIC][len][json]` after the signed PE, invalidating the signature. Resolved architecturally in SPEC-016: sign-once base + per-site wrapper, retire the managed append path. (The attended support-code path is filename-based and already signing-safe — left unchanged.)
- **Phase A HIGH — cross-site machine-move hijack:** a valid site-B key + a guessed `machine_uid` could silently repoint a site-A machine and mint a `cak_`. Fixed: default-refuse different-site enroll (409) before any repoint/mint.
- **Phase A MEDIUM — timing/enumeration oracle:** unknown `site_code` returned fast (no Argon2) vs. wrong key (Argon2), distinguishing valid sites. Fixed: dummy Argon2id verify on all reject paths.
- **Phase B HIGH — `machine_uid` not re-image-stable:** `MachineGuid` (regenerated per OS install) was mixed into the salted digest. Fixed: derive from hardware salt only; `MachineGuid` is last-resort fallback.
- **Phase B CRITICAL — credential-store self-lockout:** the SYSTEM+Admins ACL'd `cak_` store is unreadable by the user-context agent → bricks on 2nd launch. Root cause: managed agent runs via `HKCU Run`, not SYSTEM. Resolved by deciding Option A (SYSTEM service = SPEC-018) and keeping a fail-fast guard in the interim.
- **SPEC-017 number collision:** Mike authored SPEC-017 (end-user access) mid-flight; the planned service-host spec became SPEC-018, and the dangling `SPEC-017` references in the Phase B fail-fast guard were corrected to `SPEC-018`.
- **Auto-sync bypassed the PR/CI gate** — `main` was fast-forwarded up the Phase B + SPEC-017 line outside the PR merge flow. No harm (code was reviewed + green), but flagged: enable branch protection on `main`.
- **Two transient Windows-runner CI failures** (jobs reported `failure` with empty "job not started" logs). Diagnosed as runner infra (identical code green on prior run + local build clean); cleared on re-run. Gitea's combined commit-status also lingers stale failed jobs in its aggregation.
- **SPEC-018 Phase 1 HIGH — non-cancellable connected session:** the SCM stop flag wasn't checked inside the inner session loop, so a connected service couldn't stop gracefully. Fixed with an optional shutdown param threaded into `run_with_tray` (None for non-service callers = unchanged) + a clean WS-close sentinel path. MEDIUM: agent-runtime panic unwound across the `extern "system"` service entry → wrapped in `catch_unwind` → `ServiceSpecific(1)`.

## Configuration Changes

GuruConnect repo (`azcomputerguru/guru-connect`, submodule `projects/msp-tools/guru-connect`):
- **Created:** `docs/specs/SPEC-016-zero-touch-enrollment.md`, `docs/specs/SPEC-018-managed-agent-service-host.md` (SPEC-017 created by Mike). `server/migrations/010_spec016_enrollment.sql`. `server/src/auth/enrollment_keys.rs`, `server/src/api/enroll.rs`, `server/src/api/sites.rs`, `server/src/db/sites.rs`, `server/src/db/enrollment_keys.rs`. `agent/src/enroll.rs`, `agent/src/credential_store.rs`, `agent/src/service/mod.rs`.
- **Modified:** `.gitea/workflows/release.yml` (beta channel). `docs/FEATURE_ROADMAP.md` (signing shipped, beta channel, SPEC-016/018 entries, SPEC-007 signing-question resolved). `server/src/{main.rs, auth/mod.rs, db/mod.rs, db/machines.rs, db/events.rs, middleware/rate_limit.rs, api/mod.rs}`. `agent/src/{main.rs, config.rs, install.rs, identity.rs, session/mod.rs}`. `agent/Cargo.toml` (Win32_Security_Cryptography feature; `windows-service` already present).
- ClaudeTools parent: submodule pointer bumped repeatedly to track `guru-connect` main.

## Credentials & Secrets

No new credentials created. Existing vaulted credentials used (cite paths, not values):
- Gitea API token: `services/gitea.sops.yaml` → `credentials.api.api-token` (used for PR create/merge/close + CI status polling against internal Gitea).
- GuruRMM admin API: `infrastructure/gururmm-server.sops.yaml` → `credentials.gururmm-api.admin-email` / `admin-password`.
- GC agent enrollment secrets (`cak_`, per-site `cek_` keys) are minted/stored by the new code — stored hashed (Argon2id) server-side; `cak_` stored DPAPI-machine-encrypted in a SYSTEM-ACL'd `%ProgramData%\GuruConnect\credentials\agent.cak` on the endpoint. None exist yet (no live enrollment performed).

## Infrastructure & Servers

- **GuruConnect server:** `connect.azcomputerguru.com` (NPM → port 3002 on 172.16.3.30). Relay agent plane `wss://connect.azcomputerguru.com/ws/agent`; new enrollment endpoint `https://connect.azcomputerguru.com/api/enroll` (public). PostgreSQL backend (runtime `sqlx`, no offline cache).
- **GuruRMM API:** `http://172.16.3.30:3001` (JWT auth).
- **Coordination API:** `http://172.16.3.30:8001/api/coord`.
- **Gitea (internal):** `http://172.16.3.20:3000` (preferred on-network); public `git.azcomputerguru.com`.
- **CI:** Gitea Actions `build-and-test.yml` (fmt + clippy -D warnings + Linux build + Postgres-gated tests + Windows agent build + cargo-audit). Windows agent built natively on the Pluto `windows-msvc` runner.
- **GC test machines (GuruRMM):** `RMM-TEST-MACHINE` id `99d6d692-99e0-4359-9f9c-f43be89f49e5` (site Howard-VM, v0.6.52, live); `WIN-TG2STMODJG8` id `eee9f26d-0dbc-4b8e-8e42-3a901b4ff73a` (site Discovery test site, v0.6.52, live); stale `RMM-TEST-MACHINE` id `7d3456f5-...` (v0.6.38, ghost).

## Commands & Outputs

- Workflow re-trigger (Gitea has no REST rerun; rerun endpoints return 404): `POST /api/v1/repos/azcomputerguru/guru-connect/actions/workflows/build-and-test.yml/dispatches -d '{"ref":"main"}'` → HTTP 204.
- CI status: `GET /api/v1/repos/.../commits/<sha>/status` (combined; per-job `.state` is null — use `/actions/tasks` `.workflow_runs[]` filtered by `head_branch`).
- PR merge: `POST /api/v1/repos/.../pulls/<n>/merge -d '{"Do":"merge","delete_branch_after_merge":true}'`.
- Local agent build (definitive transient-vs-real check): `cargo check -p guruconnect` (windows-msvc) — clean in 2-7s, confirming CI Windows failures were runner infra.

## Pending / Incomplete Tasks

- **SPEC-018 Phase 2 (critical path):** session broker + per-session capture worker (`CreateProcessAsUserW` into the active desktop), service↔worker IPC (ACL'd named pipe), `SERVICE_CONTROL_SESSIONCHANGE` handling. Required for actual desktop capture when running as SYSTEM. X-Large; needs a Windows VM to integration-test.
- **VM integration tests (deferred, not runnable on dev host):** service install/auto-start/stop/uninstall as LocalSystem; `cak_`-as-SYSTEM enroll→store→connect round-trip (the SPEC-016 Phase B end-to-end the guard currently blocks); HKCU→service swap with no autostart gap.
- **Parked:** GC agent deploy on Howard's test machines (`RMM-TEST-MACHINE`, `WIN-TG2STMODJG8`) — waits on SPEC-018 Phase 2 for full function.
- **Enable branch protection on `guru-connect` `main`** so merges go through the CI gate (auto-sync bypassed it once).
- **Memory dedup** (coord todo): retire the 49 orphaned original memory files superseded by the morning consolidation; reconcile MEMORY.md. Flagged by both Howard (ACG-TECH03L) and GURU-KALI self-check.
- **Self-check baseline manifest:** `/autotask` is a per-operator/local command, not a per-machine requirement — move it out of the required baseline (GURU-KALI false-positive).
- **Stale lock to review:** `gururmm / agent/embedded.rs+server/install.rs (per-site EXE re-sign)` held by `GURU-5070/claude-main`, TTL to 23:27 — appears to be a prior-session lock on the GuruRMM equivalent of the same signing problem; verify and release if orphaned.

## Reference Information

- **GuruConnect main HEAD:** `11af9dff8e5ad1f8a121278be581455cc7a6bedd`. **ClaudeTools parent HEAD:** `bf7079383f5e358cbb5fa5c8bd6fc4553b29a72c`.
- **PRs:** #5 SPEC-016 Phase A (merged, `89c3718`); #6 SPEC-016 Phase B (closed already-merged via auto-sync; head `4c49b73`); #7 SPEC-018 Phase 1 (merged, `11af9df`).
- **Key commits (guru-connect):** beta channel `87f2295`; SPEC-016 spec `18429f6`, decisions `c286a29`; Phase B `d0b8db0`/`6a000d0`/`87c6e17`/`52477e4`/`367906b`; SPEC-017 (Mike) `4c49b73`; SPEC-018 spec `94c07c2`; ref fix `55b9c97`; SPEC-018 Phase 1 `7602b43`/`a0e0d5f`.
- **Specs:** `docs/specs/SPEC-016-zero-touch-enrollment.md`, `SPEC-017-end-user-remote-access.md` (Mike), `SPEC-018-managed-agent-service-host.md`. Roadmap: `docs/FEATURE_ROADMAP.md`.
- **Coord:** enrollment-spec todo `dbfe6a56` (done); memory-dedup todo (pending); component `guruconnect/server` = built (Phase A), `guruconnect/agent` = built (Phase B + SPEC-018 P1, end-to-end blocked on Phase 2).
- **Service:** Windows service internal name `GuruConnectAgent`, launch arg `service-run`, LocalSystem auto-start, `sc failure` recovery restart/5000.
