ExecuteR MVP: agent, control plane, WebUI, grouping, deployment #1

Merged
gsadmin merged 31 commits from dev into main 2026-08-07 02:53:25 +00:00
Owner

Brings the complete ExecuteR MVP from the design specification into main: a Windows management agent that enrolls over ordinary HTTPS, establishes scoped NATS messaging over WebSocket through one reverse-proxy edge, publishes live state, accepts durable work, runs PowerShell in-process, and provides a secured interactive terminal — with a browser that updates in real time over NATS, no SignalR/SSE/polling.

31 commits, 245 files.

Verification

  • Release build: 0 warnings, 0 errors
  • 131 unit tests pass (73 shared, 39 agent, 19 backend)
  • Integration test passes against a real nats-server 2.14 with JetStream: durable command dispatch to in-process PowerShell execution to live output, and a duplicate delivery runs exactly once
  • WebUI: svelte-check clean, production build clean
  • Screenshots were captured against the running application, so the rule builder image below doubles as an end-to-end check of the grouping engine

What is included

Agent (single self-contained Windows x64 exe / service, .NET 10)

  • Foreground, install, start, stop, initialize, remove, status, version — service control through the Windows APIs, never sc.exe
  • Registry and Group Policy configuration with deterministic precedence (GPO to registry to compiled default), each value carrying its provenance
  • Deterministic hardware client id from CIM with placeholder rejection; DPAPI-protected credential store where the NKey private seed never leaves the endpoint
  • CIM inventory, 30s presence, durable JetStream command consumer with ack-after-durable-record idempotency
  • In-process PowerShell through System.Management.Automation with all seven streams normalized and streamed live
  • ConPTY remote shell

Backend (ASP.NET Core, EF Core)

  • Enrollment with hashed one-time bootstrap tokens; scoped NATS user JWT issuance; nats-auth CLI that generates real Ed25519 operator/account keys
  • Local auth (PasswordHasher, no compiled default password) plus generic OIDC, role policies, HTTP-only cookies with double-submit CSRF, rate limiting
  • Messaging workers for presence/inventory ingest, live job relay and durable job state
  • Trusted-proxy forwarded headers, health and readiness

WebUI (SvelteKit)

  • Live dashboard, device list and detail, Monaco PowerShell editor, live job output and progress, xterm.js shell — all over browser NATS with session-scoped credentials

Beyond the original MVP

  • Typed script parameters (string/number/bool/array/hashtable, with per-key and per-value primitive types) and reusable function modules prepended as a runspace prelude
  • Device grouping: static and rule-based dynamic groups with 15 operators, AND/OR at group and top level, recursive nesting, independent NOT, and live preview; script triggers on registration and on agent-ready
  • S3 file delivery via presigned URLs, with downloads skipped on hash match or ETag 304
  • Device orphaning toggle (30 day default) with re-enrollment recovery
  • Multi-provider database: SQLite default, Postgres and SQL Server, each with its own migration set
  • Centralized Serilog logging with per-role rotation (agent 5 MB/3 files, server 10 MB/7 files)
  • ADMX/ADML templates, MSI with remember-properties, URL install one-liner
  • Compose stack to the house conventions, self-contained nginx sample, URL-bootstrappable deploy.sh, Gitea CI publishing to the built-in container registry

Reviewer notes

  • main is currently the initial commit, so this is effectively the whole codebase; reviewing by commit is likely easier than by diff
  • Secrets are generated, never committed. .gitignore covers .env, secrets/*, *.seed, *.creds
  • Repository Actions secrets and variables are already seeded on this repo; CI uses Gitea's built-in container registry with the token Actions injects per run, so no registry credentials are stored
  • Two Gitea API quirks are documented in the README: the secrets endpoint takes data (variables take value), and secret names may not start with GITEA_/GITHUB_
  • Merging to main triggers the release workflow: agent zip, MSI and checksums attached to a Gitea release, and images tagged <version> plus latest
Brings the complete ExecuteR MVP from the design specification into `main`: a Windows management agent that enrolls over ordinary HTTPS, establishes scoped NATS messaging over WebSocket through one reverse-proxy edge, publishes live state, accepts durable work, runs PowerShell in-process, and provides a secured interactive terminal — with a browser that updates in real time over NATS, no SignalR/SSE/polling. 31 commits, 245 files. ## Verification - Release build: **0 warnings, 0 errors** - **131 unit tests pass** (73 shared, 39 agent, 19 backend) - **Integration test passes against a real nats-server 2.14 with JetStream**: durable command dispatch to in-process PowerShell execution to live output, and a duplicate delivery runs exactly once - WebUI: `svelte-check` clean, production build clean - Screenshots were captured against the running application, so the rule builder image below doubles as an end-to-end check of the grouping engine ## What is included **Agent** (single self-contained Windows x64 exe / service, .NET 10) - Foreground, install, start, stop, initialize, remove, status, version — service control through the Windows APIs, never `sc.exe` - Registry and Group Policy configuration with deterministic precedence (GPO to registry to compiled default), each value carrying its provenance - Deterministic hardware client id from CIM with placeholder rejection; DPAPI-protected credential store where the NKey private seed never leaves the endpoint - CIM inventory, 30s presence, durable JetStream command consumer with ack-after-durable-record idempotency - In-process PowerShell through System.Management.Automation with all seven streams normalized and streamed live - ConPTY remote shell **Backend** (ASP.NET Core, EF Core) - Enrollment with hashed one-time bootstrap tokens; scoped NATS user JWT issuance; `nats-auth` CLI that generates real Ed25519 operator/account keys - Local auth (PasswordHasher, no compiled default password) plus generic OIDC, role policies, HTTP-only cookies with double-submit CSRF, rate limiting - Messaging workers for presence/inventory ingest, live job relay and durable job state - Trusted-proxy forwarded headers, health and readiness **WebUI** (SvelteKit) - Live dashboard, device list and detail, Monaco PowerShell editor, live job output and progress, xterm.js shell — all over browser NATS with session-scoped credentials **Beyond the original MVP** - Typed script parameters (string/number/bool/array/hashtable, with per-key **and** per-value primitive types) and reusable function modules prepended as a runspace prelude - Device grouping: static and rule-based dynamic groups with 15 operators, AND/OR at group and top level, recursive nesting, independent NOT, and live preview; script triggers on registration and on agent-ready - S3 file delivery via presigned URLs, with downloads skipped on hash match or ETag 304 - Device orphaning toggle (30 day default) with re-enrollment recovery - Multi-provider database: SQLite default, Postgres and SQL Server, each with its own migration set - Centralized Serilog logging with per-role rotation (agent 5 MB/3 files, server 10 MB/7 files) - ADMX/ADML templates, MSI with remember-properties, URL install one-liner - Compose stack to the house conventions, self-contained nginx sample, URL-bootstrappable `deploy.sh`, Gitea CI publishing to the built-in container registry ## Reviewer notes - `main` is currently the initial commit, so this is effectively the whole codebase; reviewing by commit is likely easier than by diff - Secrets are generated, never committed. `.gitignore` covers `.env`, `secrets/*`, `*.seed`, `*.creds` - Repository Actions secrets and variables are already seeded on this repo; CI uses Gitea's built-in container registry with the token Actions injects per run, so no registry credentials are stored - Two Gitea API quirks are documented in the README: the secrets endpoint takes `data` (variables take `value`), and secret names may not start with `GITEA_`/`GITHUB_` - Merging to `main` triggers the release workflow: agent zip, MSI and checksums attached to a Gitea release, and images tagged `<version>` plus `latest`
gsadmin added 31 commits 2026-08-07 02:51:56 +00:00
- Central package management pinned for .NET 10; unified yyyy.MM.dd.HHmm versioning
- Shared.Contracts: ApiRoutes, message envelope, payload/DTO records, JSON defaults
- Shared.Infrastructure: branding constants, protocol defaults, NATS subject map
  with central identifier validation, JetStream definitions, ServerURL normalization,
  token hashing, MSI version transform
- Backend: health/ready endpoints, trusted-proxy forwarded headers plumbing
- Agent: CLI dispatcher, Generic Host worker, Windows service lifecycle via
  advapi32/ServiceController (no sc.exe)
- Shared.Tests: 42 tests covering routes, subjects, ServerURL, envelope, versioning

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- nats.conf: JetStream + WebSocket listener behind reverse proxy, file resolver
- docker-compose(.dev).yml: nats/backend/webui with health checks and volumes
- Multi-stage backend/webui Dockerfiles (non-root, unified version labels)
- Scripts: unified version, build, test, icon generation (ImageMagick via
  winget when missing), agent packaging with checksums, local secrets and
  repo initialization
- SvelteKit WebUI scaffold (Svelte 5, adapter-node, TS) with NATS core,
  nkeys, Monaco and xterm dependencies
- Placeholder icon source + assets/secrets documentation

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- IRegistryStore seam + HKLM implementation; AgentConfigurationLoader with
  deterministic precedence (GPO > registry > dev-only env > defaults) and
  per-value provenance for future ADMX
- RuntimeStateStore for Runtime registry values, bootstrap token clearing,
  credential purge (used by MSI full uninstall via hidden CLI command)
- WiX v5 MSI: public properties with remember-pattern (blank never overwrites,
  upgrades preserve config), LocalSystem service install with failure actions,
  delayed auto-start applied via the agent's own install command, credential
  purge only on real uninstall (never upgrades)
- 10 agent configuration/state tests

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent:
- CIM hardware identity (System.Management) with placeholder rejection and
  labeled canonical string; SHA-256 lowercase-hex client id; strong-identifier
  requirement
- DPAPI(LocalMachine) credential store with SYSTEM/Administrators-only ACLs;
  versioned encrypted JSON blob; private NKey seed never leaves the endpoint
- Enrollment client: local user NKey generation, HTTPS bootstrap, credential
  persistence, bootstrap token erased from registry after success
- NATS options factory: WSS endpoint from ServerURL, JWT+seed auth from
  protected memory, unlimited reconnect with backoff+jitter; worker now
  orchestrates enroll -> connect -> session with reload of registry config

Backend:
- NatsCredentialIssuer: account-signing-key user JWTs (agent scoped to own
  client id, browser scoped to session subjects, backend full access)
- nats-auth init CLI: real Ed25519 operator/APP/SYS keys + resolver.conf via
  NATS.Jwt/NATS.NKeys (no fake seeds)
- EF Core SQLite schema + InitialCreate migration (Users, Devices,
  DeviceInventory, Scripts, Jobs, JobOutput, BootstrapTokens, AuditEvents,
  ShellSessions, OidcProviders); migrate on startup
- Bootstrap endpoint: hashed one-time tokens, idempotent enrollment, NKey
  binding, rate limiting, auditing; credential refresh via Ed25519 proof of
  possession
- Readiness now verifies database, NATS connection and signing key

Tests: 27 agent (identity, config), 9 backend (bootstrap/refresh via
WebApplicationFactory with real JWT verification)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent:
- CIM inventory collector (identity/OS/CPU/memory/disks/volumes/network)
- Presence heartbeat (30s) and inventory publisher (start + interval + command)
- Durable JetStream command consumer: explicit ack, ack-after-durable-record,
  duplicate deliveries acknowledged without re-execution (SQLite job history,
  last 1000 retained)
- In-process PowerShell execution via System.Management.Automation: runspace +
  AddScript/AddParameter, async invoke, all seven streams normalized and
  published near-live with per-job monotonic sequence; progress records mapped
  to normalized progress payloads; cancellation + timeout -> Cancelled/TimedOut

Backend:
- JetStream provisioning (COMMANDS, JOB_EVENTS) and per-agent durable
  consumers created at enrollment
- Messaging workers: presence/inventory ingest with device upsert and status
  transitions, near-live job output relay + async persistence with ownership
  checks, durable job state consumption with terminal-state protection
- Browser session registry + per-session event broadcaster (no raw agent
  subjects ever reach browsers)
- REST: devices (list/detail/inventory refresh), scripts CRUD, jobs
  (create -> JetStream dispatch, list, detail, stored output), admin
  bootstrap tokens, browser messaging credentials (session-scoped, 5 min)
- Development seed: MVP progress demo script

Agent JWTs now include narrowly scoped JS API permissions for their own
durable consumer only.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Design tokens with System/Light/Dark theming (persisted, pre-paint boot)
- App shell: navigation rail, top bar with live connection indicator, theme
  switcher, session display
- Browser NATS service: in-memory NKey generation, short-lived session-scoped
  credentials with automatic refresh, subject dispatch to activity/job/shell
  handlers; no polling anywhere
- Dashboard: device/job stat tiles, live activity stream, latest enrollments
- Devices: searchable/sortable table with live status badges; device detail
  with Overview/Hardware/Network/Jobs/Actions tabs and full inventory
- Scripts: list + Monaco PowerShell editor with target device selector, live
  progress bar and structured live output; stored-output recovery after
  reconnect
- Jobs: list with live state transitions and per-job output viewer
- Settings: theme + bootstrap token administration (one-time reveal)
- Login page (wired to backend auth in the next milestone)
- Vite dev proxy for /api and /messaging; adapter-node

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent:
- ConPTY interop (CreatePseudoConsole + CreateProcess with pseudoconsole
  attribute); no WinPTY fallback
- ConPtySession: pipes, output pump, process watch, resize, clean disposal
- ShellManager: single active session per device, base64 output over Core NATS
  with monotonic sequence, idle (15m) and absolute (60m) timeouts, prefers
  pwsh 7 then Windows PowerShell
- ShellCommandListener: Core NATS subscription gated by AllowRemoteShell policy

Backend:
- ShellBridge: browser publishes only to browser.<sid>.shell.<shellId>.input;
  backend validates ownership and republishes to privileged agent command
  subjects; agent output/state relayed to the owning session only
- POST /api/devices/{clientId}/shell: authorize, bind to live browser session,
  persist metadata only (no transcript), publish open command

WebUI:
- xterm.js terminal page with fit/resize forwarding, live status, explicit
  Disconnect, session-scoped input publishing

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Local auth: ASP.NET Core PasswordHasher (no compiled default password),
  first-boot admin from INITIAL_ADMIN_* env, transparent rehash on login
- HTTP-only cookie session (SameSite=Lax for OIDC), APIs return 401/403 rather
  than redirecting; login rate limited
- Double-submit-cookie CSRF protection for cookie-authenticated state-changing
  calls; enrollment/login exempt; WebUI attaches X-CSRF-Token from cookie
- Generic OIDC (any compliant provider): PKCE code flow, claim-driven role
  mapping (admin role claim -> Admin else Operator), user upsert on token
  validated
- Role policies (Viewer/Operator/Admin) applied across devices, scripts, jobs,
  shell, messaging credential and admin token endpoints
- WebUI: session store, login page wired, 401 -> /login bounce
- SQLite DateTimeOffset stored as UTC ticks (fixes ORDER BY); migration
  regenerated
- 6 auth/RBAC/CSRF tests (84 unit tests total green)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- STACK_NAME/STACKNAME identity; EXTERNAL + INTERNAL bridge networks
- Container naming EXECUTER-{NATS,API,WEB}-00001; service-name networking
- Uncommon host-published ports (webui 13080, backend 19080, nats-ws 19222);
  internal NATS TCP stays off the host (loopback only in the dev override)
- NATS image pinned to the linux multi-arch index digest (2.12-alpine)
- Bind-mount data under ${STACK_BINDMOUNTROOT}/${STACK_NAME}/{Tier}/Data;
  timezone/localtime mounts; local logging; stop grace; watchtower labels;
  healthchecks with start_period
- .env.example rewritten to spec (header, identity, pinned images, ports,
  trust, admin, OIDC, NATS seeds, S3 block, watchtower); vite dev proxy
  defaults updated to new ports

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- SatelliteResourceLanguages=en drops PowerShell localization satellites
- Pre-bundle target removes interactive/gallery modules (PSReadLine,
  PackageManagement, PowerShellGet) and non-Windows native runtimes
  (unix/linux/osx/browser/alpine) from the self-contained publish
- Core automation modules (Management, Utility, Security, Host, Diagnostics,
  CimCmdlets, Archive) are retained so admin scripts keep their normal cmdlet
  surface; modules ship inside Agent.exe (no loose Modules folder)
- Remaining ~53 MB is the self-contained .NET + PowerShell engine, which is
  not IL-trim-safe (reflection-heavy)
- Added headless PowerShell execution tests: output/error/warning/verbose
  streams, progress normalization, cancellation, and typed hashtable parameter
  binding (34 agent tests)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Typed parameters (C):
- ScriptParameter model: string/number/boolean/array/hashtable; array element
  type and hashtable KEY + VALUE primitive types (typed hashtable keys)
- Scripts persist a parameter schema; job creation accepts typed argument
  values; agent ScriptArgumentBinder coerces JSON to CLR (int/long/double/bool/
  object[]/Hashtable with typed keys) and binds via AddParameter
- WebUI: ParameterSchemaEditor (define) and ParameterInputs (type-driven run
  inputs; editor changes per type, add/remove array items and hashtable rows)

Reusable functions (D):
- FunctionModule entity + CRUD endpoints + Functions admin page
- Scripts attach function modules; backend composes them as a prelude run
  first in the same runspace so the main script keeps its param() block first
- PowerShellExecutionService gained prelude support (AddScript + AddStatement)

- New migration (FunctionModules table, Scripts parameter/module columns)
- Tests: typed hashtable parameter binding verified headless (49 backend+agent)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Backend S3PresignService (AWSSDK.S3; AWS S3 / MinIO / path-style) issues
  short-lived presigned GET URLs; S3 credentials never leave the backend
- POST /api/devices/{clientId}/files (Operator): presign object key, record a
  job, dispatch a durable file-download command; progress/result flow through
  the normal live job pipeline
- Durable command subject agent.*.command.file added to the COMMANDS stream
- Agent FileDownloadHandler: streams the presigned URL to the destination path
  (atomic temp+move), emits byte progress, optional SHA-256 verification,
  publishes Running/Succeeded/Failed; idempotent by job id
- WebUI: device Actions "Send file (S3)" form -> jumps to the live job
- S3 config surfaced in .env.example / compose (already added)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- ExecuteR.admx + en-US/ExecuteR.adml under Grace Solution > ExecuteR Agent
- Policies map to HKLM\SOFTWARE\Policies\GraceSolution\ExecuteR (the agent'"'"'s
  highest-precedence config source): ServerURL, LogLevel (enum), inventory
  interval and reconnect min/max delays (REG_SZ seconds), AllowRemoteShell and
  AllowScriptExecution (REG_DWORD toggles)
- Bootstrap token intentionally excluded (secret, not a policy)
- Deployment README (per-machine + domain central store)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- GET /api/enrollment/install?token=… returns a PowerShell one-liner script
  (msi default, ?type=zip alternative) that downloads the agent from this
  origin and installs it with SERVERURL + BOOTSTRAPTOKEN; base URL is
  PUBLIC_SERVER_URL or derived from proxy-forwarded request headers
- GET /api/enrollment/agent-package streams Agent.msi/Agent.zip from
  AGENT_PACKAGE_PATH (default /data/agent); clear 404 when absent
- Both anonymous + rate-limited (token knowledge is the enrollment gate)
- Settings UI shows the copyable install command after token creation
- Compose/.env: AGENT_PACKAGE_PATH
- 4 install-endpoint tests (19 backend tests)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- DevSeeder (DEV_SEED=1, Development only) creates sample devices, inventory
  and jobs so the UI renders populated without a live agent
- docs/screenshots: dashboard (dark+light), devices, device detail + hardware,
  scripts list, Monaco script editor, jobs, functions, settings, login
  (captured with Playwright/Chromium at 2x against the running app)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Comprehensive README covering all 20 required sections: architecture,
  component flow, agent-to-component flow, prerequisites, local dev, secrets,
  Compose, reverse proxy routes, agent lifecycle, MSI properties, registry/GPO
  precedence, bootstrap + URL install, local login + OIDC, typed parameters +
  function modules, S3 delivery, CI/CD + GITEA_* vars, versioning, demo
  sequence, troubleshooting; embeds screenshots
- docs/sequences.md: script execution, enrollment, remote shell
- Mermaid labels are quoted throughout (GitHub/Gitea parser-safe; no raw HTML)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- .gitea/workflows/ci.yml: PR->main builds + unit/integration tests + svelte
  check; push to dev/main also builds (and pushes) backend/webui images with
  dev / <version>-dev or <version> / latest tags
- .gitea/workflows/release.yml + scripts/Publish-Release.ps1: on main, generate
  icon, package agent (exe zip + MSI + checksums) and create a Gitea release
  with assets via the REST API (no-ops without GITEA_TOKEN; never prints it)
- Integration test: real NATS+JetStream durable dispatch -> in-process
  PowerShell execution -> live output/progress/state, and duplicate delivery
  runs exactly once. Verified passing against nats-server 2.14 (JetStream);
  skips cleanly when NATS_URL is unreachable
- Icon generation wired into the agent build (ApplicationIcon)

Full suite: 95 unit tests + 1 integration test green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Logging:
- Shared.Infrastructure/Logging: one Serilog pipeline for every service —
  console (text or compact JSON) plus daily rolling file with size cap
  (LOG_MAX_BYTES) and retention (LOG_RETAIN_DAYS); framework noise pinned to
  Warning; machine/application enrichment; a bad log path degrades to console
  instead of failing startup
- Backend uses UseSerilogRequestLogging with effective client IP + user, and
  health/ready probes demoted to Verbose so they do not flood the log
- Agent log level comes from its own precedence chain (GPO > registry >
  default), writing to %ProgramData%\ExecuteR\logs
- LOG_* surfaced in compose and .env.example

Compose:
- Container and network names are now static (EXECUTER-API-00001,
  EXECUTER-EXTERNAL, ...) instead of interpolating STACKNAME

Registry:
- Dropped the company segment: HKLM\SOFTWARE\ExecuteR,
  HKLM\SOFTWARE\ExecuteR\Runtime, HKLM\SOFTWARE\Policies\ExecuteR
  (updated agent constants, MSI, ADMX, URL install script and docs);
  agent data directory is now %ProgramData%\ExecuteR

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- DATABASE_PROVIDER (sqlite|postgres|sqlserver) + DATABASE_CONNECTION_STRING;
  SQLite keeps using DATABASE_PATH and stays the default
- Thin per-provider DbContexts give each provider its own migration history
  inside one assembly, with design-time factories so `dotnet ef` can scaffold
  without a live database; application code still injects AppDbContext, which
  is aliased to whichever provider context was selected
- Timestamp storage is now provider-correct: SQLite keeps the UTC-ticks
  conversion (no native DateTimeOffset ordering), Postgres and SQL Server use
  native timestamp columns
- InitialCreate migrations generated for all three providers
- Startup logs the active provider

Note: Drizzle ORM is TypeScript-only and cannot back an ASP.NET Core backend,
so the multi-database capability is implemented with EF Core providers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Rule engine (Shared.Infrastructure/Grouping):
- Operators: equals, notEquals, contains, notContains, startsWith, endsWith,
  regex, in, notIn, greaterThan/OrEqual, lessThan/OrEqual, exists, notExists —
  each with an independent Negate flag
- One or more condition groups, each AND/OR internally, combined AND/OR at the
  top level, with optional recursive nesting and per-group negation
- Multi-valued fields (tags, IPs, MACs, DNS) match when ANY value satisfies a
  positive operator, and require ALL values for the negative ones; a missing
  field satisfies only negative operators
- Numeric comparisons fall back to ordinal text so version-ish values still order
- Invalid or runaway regex never matches and never throws (250ms timeout)
- Field catalogue drawn from inventory, tags, hostname, status and agent data,
  exposed via /api/groups/fields so the UI stays in sync

Backend:
- DeviceGroup (static membership table or dynamic rules) + device tags
- CRUD, member management, and a preview endpoint that evaluates candidate
  rules against live devices without saving
- Device detail now reports the groups a device belongs to
- ScriptTrigger: run a script on OnRegistration or OnAgentReady, targeted at a
  group (or all devices), with once-per-device semantics recorded durably;
  triggered runs reuse the normal job pipeline (prelude + typed parameters)
- Agents publish a "ready" lifecycle event once their durable command consumer
  is bound, which is what OnAgentReady keys off — connected AND consuming
- Migrations added for all three providers

31 new rule-engine tests (73 shared tests total).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- RuleBuilder component: condition groups with AND/OR at both the group and
  top level, per-condition and per-group NOT, field picker grouped by category
  (fed by /api/groups/fields so it tracks the server catalogue), and
  operator-aware value inputs (list hints, regex hints, numeric)
- Groups page: create/edit static or dynamic groups, preview which devices
  match candidate rules before saving, tick-list membership for static groups
- Script trigger management: bind a script to on-registration or
  on-agent-ready for a group (or all devices), with once-per-device
- Device detail gained a Tags and groups panel: add/remove tags (usable in
  rules) and see computed group membership
- Groups added to the navigation rail

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
nginx (src/Infra/nginx):
- nginx-ui style site: one file plus shared proxy-headers and websocket
  snippets; generic hostname/IPs, no real domains
- Routes / to WebUI, /api/ to backend, and both /messaging paths to the NATS
  WebSocket listener; 1h WebSocket timeouts with buffering off so agent and
  browser sessions are not cut every 60s
- Edge rate limiting for enrollment and sign-in, security headers, ACME
  passthrough, HTTP to HTTPS redirect
- Commented allow/deny IP blocks at three levels (site, agent messaging,
  enrollment); README calls out the two common footguns (trusted proxies and
  duplicate http-level map/limit_req_zone directives)

Diagrams:
- The architecture diagram previously drew agent and browser arrows straight to
  NATS, which read as a direct connection bypassing the proxy. Split into a
  physical topology diagram (everything crosses the edge on 443, NATS sits
  inside the private stack) and a separate message-flow diagram that is
  explicitly logical traffic over those proxied WSS sessions

README: new sections for device groups and script triggers, database providers
and logging; nginx reference from the reverse-proxy section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Dev seeder now creates tags plus a dynamic group (Dell or Lenovo AND
  16 GB+ AND workstation-tagged) and a static lab group, so the grouping UI
  renders real data
- Captured 18 screenshots against the running app: dashboard (dark and light),
  devices, device overview/hardware/network/actions, groups list, rule builder
  with live preview, static membership, scripts, Monaco editor, typed
  parameters, jobs, function modules, settings with the install one-liner
- README gained a screenshot gallery and embeds the rule builder in the
  grouping section

The rule-builder capture doubles as an end-to-end check: the seeded rules
resolved to 2 of 3 devices, correctly excluding the lab VM.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- proxy-headers and websocket snippet contents inlined at server level; the
  map and limit_req_zone directives moved to the top of the same file with a
  note that they belong at http{} level
- Removed the snippets/ directory and the per-location Upgrade/Connection
  duplicates now covered by the server-level block
- README updated: copy one file, no snippet install step

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Compose:
- Backend and webui now reference ${REGISTRY}/<image>:<tag> (Gitea container
  registry) with pull_policy: missing, keeping the build section as the
  fallback path
- docker-compose.proxy.yml adds an OPT-IN in-stack nginx (EXECUTER-PROXY-00001)
  on uncommon host ports with bind-mounted config, certs, logs and ACME webroot

scripts/deploy.sh:
- Bootstrappable straight from a URL (curl ... | bash) or run from a checkout;
  fetches only the files it needs when there is no clone
- Pulls published images first and builds from source only if the pull fails
  (--build / --no-pull to force either way)
- Creates .env with a generated initial admin password, prepares the
  bind-mount tree, and generates real NATS operator/account keys by running
  the backend image's own nats-auth CLI (no dotnet SDK needed on the host)
- --with-proxy is opt-in and rewrites the nginx site to reach services by
  compose service name; --host supplies the public hostname
- Waits for backend health and prints the resulting endpoints

.env.example: REGISTRY/IMAGE/VERSION/pull-policy, proxy settings, and
DEVICE_ORPHAN_AFTER_DAYS.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- CI now tags images as <gitea-host>/<owner-lowercased>/executer-{backend,webui}
  so they match exactly what docker-compose.yml pulls; pushes <version> plus
  latest on main or dev/<version>-dev on dev, and warns (instead of silently
  skipping) when the registry secret is unset
- scripts/Initialize-GiteaSecrets.ps1 creates/updates the Actions secrets and
  variables over the Gitea REST API: registry host/user/password, GITEA_TOKEN,
  the NATS account signing seed, initial admin password, OIDC and S3 secrets,
  plus a REGISTRY variable. Derives owner/repo/URL from the git remote,
  reads values from .env and secrets/nats, is idempotent, and never prints a
  secret value

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Device lifecycle (DEVICE_ORPHAN_AFTER_DAYS, default 0 = off):
- Default behaviour is unchanged and needs no operator action: a silent device
  ages Online -> Stale -> Offline, keeps its credentials, and reconnects by
  itself whenever it returns
- With a positive window, the sweeper orphans devices silent for that long.
  An orphaned device is refused credential refresh (401) and job creation
  (409), and presence from it is logged and ignored rather than resurrecting it
- Recovery is deliberate: pushing a fresh bootstrap token makes the agent
  re-enroll, which clears the flag and reuses the same device record
- Agent needed no new mode: a bootstrap token is erased after each successful
  enrollment, so finding one on an already-enrolled agent is by definition an
  instruction to re-enroll

S3 download caching (skip work when nothing changed):
- If the destination exists and the caller supplied sha256, the agent hashes
  the local file and skips entirely on a match - no request at all
- Otherwise it sends the previously stored ETag as If-None-Match and treats
  304 Not Modified as "already up to date", letting S3 make the call
- Local cache (destination -> ETag, SHA-256, size) lives in the agent's SQLite
  store so it survives restarts; every completed download is hashed to verify
  the transfer and seed the cache
- 5 download-cache tests (39 agent tests)

Migrations added for all three providers. README documents both flows with
diagrams, plus the deploy script and Gitea secrets bootstrap.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add design and stack convention specs
CI / build-test (push) Has been cancelled
CI / images (push) Has been cancelled
21b7182cc9
The MVP design specification plus the Compose and .env conventions the stack
is built against, kept in-repo so the build rules travel with the code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Fix Gitea secrets API, centralize orphan window and per-role log rotation
CI / build-test (push) Has been cancelled
CI / images (push) Has been cancelled
c6517676b2
Gitea secrets:
- The secrets endpoint takes {"data": ...} while variables take {"value": ...};
  sending the wrong field returned HTTP 422 for every secret
- Gitea also reserves the GITEA_ prefix for Actions secret names (HTTP 400), so
  the registry credentials are now REGISTRY_HOST / REGISTRY_USERNAME /
  REGISTRY_PASSWORD, and the instance URL moved to a SERVER_URL variable
- No GITEA_TOKEN secret is created: Actions injects one per run. release.yml
  now uses that built-in token and falls back to github.server_url
- Secrets and variables verified seeded on gsadmin/ExecuteR

Central configuration:
- ProtocolDefaults.DefaultOrphanAfterDays = 30 is the single source of truth;
  DEVICE_ORPHAN_AFTER_DAYS overrides it and 0 disables orphaning. Previously
  an unset value silently meant "disabled"
- LogDefaults gives each role its own rolling policy: agent rolls at 5 MB
  keeping 3 files, backend at 10 MB keeping 7. LOG_RETAIN_FILES replaces the
  misnamed LOG_RETAIN_DAYS (it was always a file count, not days)
- Compose and .env.example updated to the new names and defaults

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Use Gitea's built-in container registry without seeded credentials
CI / build-test (pull_request) Has been cancelled
CI / images (pull_request) Has been cancelled
CI / build-test (push) Has been cancelled
CI / images (push) Has been cancelled
ebc4298924
The images were already being published to Gitea's own registry, but the
workflow required REGISTRY_HOST/USERNAME/PASSWORD to be seeded first, which
made it look and behave like an external registry.

- CI now defaults to the built-in registry with no configuration: the host is
  derived from github.server_url, the user is github.actor, and the password
  is the GITEA_TOKEN that Actions injects per run (verified against
  /v2/token - it returns a valid registry bearer). The REGISTRY_* secrets
  remain as an opt-in override for publishing elsewhere
- Initialize-GiteaSecrets.ps1 no longer writes registry credentials unless
  -ExternalRegistry is passed; the seeded ones have been removed from the repo
- deploy.sh logs in before pulling when REGISTRY_USERNAME/REGISTRY_TOKEN are
  set, which private-repo packages require
- README documents the registry path and the two Gitea API quirks (secrets use
  "data" not "value"; GITEA_/GITHUB_ prefixes are reserved)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
gsadmin merged commit c5c3c6da7d into main 2026-08-07 02:53:25 +00:00
Sign in to join this conversation.