gustavosantos/GTI_GERENCIADOR_FISCAL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Agent distribution with secure enrollment from the control panel

Browse Source 
One universal Windows Agent package per version (agent_releases: version/
platform/architecture/sha256/status DRAFT|PUBLISHED|REVOKED; the binary
lives on a local release-storage volume, never in PostgreSQL). An operator
creates a pending installation (agent_enrollments) from Agents / Servidores
-> + Nova instalação, then either downloads it directly or generates a
one-time HTTPS link (short TTL, single use). Either path streams the
package plus a freshly minted enrollment.json whose token is never written
to storage in plaintext, only its SHA-256 hash. On the client host,
gti-agent.ps1 install-auto verifies the bundle's SHA-256, refuses a non-
HTTPS Hub, enrolls via POST /v1/agents/enroll (deleting the enrollment
token immediately after, success or failure), writes an ACL-restricted
.env with the newly issued permanent Agent token, and registers the
Windows Service without starting it (Firebird stays unconfigured on
purpose). Idempotent, replay-proof, rate-limited per IP, fully audited,
never logs a secret.

Migration 0022_agent_releases_enrollment (verified fresh-DB ==
upgrade-from-0021 by pg_dump diff). GTI_FISCAL_VERSION/AGENT_VERSION
bumped to 1.1.0 as the single source of truth across code, packages, the
release manifest and every published AgentRelease row.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
gti
2026-09-23 13:19:31 -03:00
co-authored by Claude Sonnet 5
parent b1c496fc1b
commit 8d6122c096
36 changed files with 1515 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AI_PROJECT_STATE.md
+39 -2
View File
@@ -1,5 +1,42 @@
# AI Project State
## Agent distribution + secure enrollment V1 (2026-09-23)
`AGENT_DISTRIBUTION_V1_IMPLEMENTED` — the Windows Agent is now installable
end to end from the control panel instead of a manual `register_agent.py` +
hand-copied `.env`. One universal package per version
(`agent_releases`: version/platform/architecture/sha256/status
DRAFT|PUBLISHED|REVOKED, binary on a local `agent_releases` volume, never in
PostgreSQL, published by `central/scripts/publish_agent_release.py`, never a
browser upload). `Agents / Servidores -> + Nova instalação` creates a pending
installation (`agent_enrollments`); its page offers an authenticated direct
download or a one-time HTTPS link (`/dl/agent/{token}`, single use, short
TTL). Either path streams the package plus a freshly minted `enrollment.json`
— a one-time enrollment token whose plaintext is never written to storage,
only its SHA-256 hash. On the client host, `gti-agent.ps1 install-auto`
verifies the bundle's SHA-256 against `MANIFEST.json`, refuses a non-HTTPS
Hub, calls `POST /v1/agents/enroll` (deletes `enrollment.json` immediately
after either outcome), writes an ACL-restricted `.env` with the newly issued
**permanent** Agent token, and registers the Windows Service without
starting it (Firebird stays unconfigured on purpose — the operator fills it
in, then `preflight`/`start`). Idempotent re-run, replay-proof (the
enrollment token's hash is cleared on use), rate-limited per IP
(`central/app/rate_limit.py`), fully audited
(`INSTALLATION_CREATED`/`DOWNLOAD_LINK_CREATED`/`PACKAGE_DOWNLOADED`/
`ENROLLMENT_SUCCEEDED`/`ENROLLMENT_REJECTED`/`AGENT_CREDENTIAL_ISSUED`/
`INSTALLATION_REVOKED`, real IP, never a token). Migration
`0022_agent_releases_enrollment`; verified fresh-DB == upgrade-from-0021
(pg_dump identical) on both local dev and production Postgres. Real
end-to-end proof ran over HTTP against the running Hub (not just
TestClient): create -> link -> single-use download -> tamper/replay
rejection -> enroll -> the minted Agent token authenticates
`GET /v1/datasets/status`. `GTI_FISCAL_VERSION`/`AGENT_VERSION` bumped to
`1.1.0` (single source of truth: `release/VERSION`, both `pyproject.toml`,
`run_agent_service.py`'s default, the release manifest and every published
`AgentRelease` row). See docs/PILOT_DEPLOYMENT.md, "Agent distribution:
install from the panel". No real client Agent was installed by this pass
— `FIRST_REAL_AGENT_INSTALLED=false`; the operator chooses the first pilot.
## Autonomous operations closure V1 (2026-09-22)
`AUTONOMOUS_OPERATIONS_CLOSURE_VALIDATED` — the Agent now models per-product
@@ -440,7 +477,7 @@ allowlist and the fiscal rule engines still decide what may actually be written
Hub `classification_cache` fixed: fingerprint (tenant + input + ENGINE_VERSION + dataset_versions()) is computed first and a HIT returns without running the Classifier (test: `central/tests/test_classification_cache.py`). Live benchmark (100 products): MISS 337 ms/product, HIT 15 ms/product, 100/100 hits, identical results. Fingerprint inputs unchanged, so existing cache entries stay valid and version bumps still invalidate naturally.
## Release Candidate 1.0.0-rc1 (2026-09-19) — COMPLETE_LOCAL_RC
Frozen: `release/VERSION`, `central/app/version.py` (`GET /version`), `release/RELEASE_MANIFEST.json` (versions + ACTIVE dataset hashes + migrations; head `0021_sso_federated_identity` since 2026-09-23). See `docs/RELEASE_CANDIDATE_V1.md`.
Frozen: `release/VERSION`, `central/app/version.py` (`GET /version`), `release/RELEASE_MANIFEST.json` (versions + ACTIVE dataset hashes + migrations; head `0022_agent_releases_enrollment` since 2026-09-23). See `docs/RELEASE_CANDIDATE_V1.md`.
Architecture: Hub central (Docker Hub+PostgreSQL, `deploy/hub`) <-HTTPS- Agent Windows (`deploy/agent-windows`, service GTIFiscalAgent) -local read-only-> SGV Firebird. The Hub never accesses Firebird.
Agent: `FISCAL_MODE` DRY_RUN|AUTO_APPLY (DRY_RUN = technically no writes), `COMPANY_CODE/COMPANY_CNPJ/COMPANY_CRT_SOURCE(AUTO|EMISSOR|C000004)`, `COMPANY_UF` explicit override only; single preflight `agent/scripts/preflight.py` (also enforced at service start); REPROCESS_ALL job result includes the coverage report + company context (`gti_fiscal_agent/coverage.py`, shared with multi-db tooling); `scripts/prove_zero_write.py` (DML counters + table digests). Packaging: `scripts/build_agent_package.py` (secret-scanned zip). Hub prod: `deploy/hub/docker-compose.prod.yml` (Postgres internal only), backup/restore, dataset seed export/import; `APP_ENV=production` refuses AGENT_DEV_TOKEN.
Pilot profile: CONSTRUCAO (`pilot-construcao.env.example`); planned, not installed: MMMODAS/RINCAO/UNIAO with `COMPANY_CRT_SOURCE=EMISSOR`. No real host was accessed: a local simulation ran the Agent (registered agent, DRY_RUN) end-to-end on the CONSTRUCAO copy. Follow-up: memoize `dataset_versions()`.
@@ -487,7 +524,7 @@ See `docs/PRE_AI_LOCAL_COMPLETION_V3_REPORT.md` for measured values.
collaborators in `admin_users` with `auth_source=GTI_GERENCIADOR`, no password);
local admin only as break-glass at `/login/local`. Same visual identity as the
panel (`static/gti-theme.css` is a copy of its design system).
- Migration head: `0021_sso_federated_identity`. An empty database is initialized
- Migration head: `0022_agent_releases_enrollment`. An empty database is initialized
by `alembic upgrade head` alone — never `stamp`/`create_all`.
- `0001` is a frozen explicit baseline (it used to call `create_all()`, which
broke every fresh install). `0019` fixes the frozen `created_at` defaults
docs/PILOT_DEPLOYMENT.md
+82 -5
View File
@@ -5,7 +5,7 @@ Agent installations. See `docs/OPERATIONS.md` for the day-to-day command
reference (creating jobs, checking status); this document is about getting a
new environment stood up and kept alive.
## RC1 (1.0.0-rc1) — supported path
## RC1 (1.1.0) — supported path
```
Hub central (Docker: Hub + PostgreSQL, deploy/hub)
@@ -27,8 +27,8 @@ Firebird. RC1 pilots run `FISCAL_MODE=DRY_RUN` + `FIREBIRD_WRITES=0`: the Agent
5. Health: `GET /health` (Postgres included), `GET /version` (release/engine/decision versions). `APP_ENV=production` refuses to start when `AGENT_DEV_TOKEN` is set.
6. Backup/restore: `sh backup.sh` (pg_dump -Fc into `BACKUP_DIR`, keeps 14) and `sh restore.sh <dump>` (asks for the word RESTORE, stops the Hub, restores, restarts; migrations rerun at start).
### Agent (client host, PowerShell as Administrator, inside the extracted `GTIFiscalAgent-1.0.0-rc1` folder)
Build the package on the release machine: `python scripts/build_agent_package.py` -> `dist/GTIFiscalAgent-1.0.0-rc1.zip` (+ `.sha256`; secret-scanned, no `.env`).
### Agent (client host, PowerShell as Administrator, inside the extracted `GTIFiscalAgent-<version>` folder)
Build the package on the release machine: `python scripts/build_agent_package.py` -> `dist/GTIFiscalAgent-<version>.zip` (the version is `release/VERSION`) (+ `.sha256`; secret-scanned, no `.env`).
| step | command |
|---|---|
@@ -132,8 +132,9 @@ Agents with `central/scripts/register_agent.py` (see below).
keep that frozen value — their real creation time is not recoverable).
- `0020` enforces NOT NULL on 20 timestamp columns that always had
`DEFAULT now()`. It aborts, changing nothing, if any NULL exists — clean
those rows explicitly first. `0021` adds the SSO federated identity (see "Human access"). Current head:
`0021_sso_federated_identity`
those rows explicitly first. `0021` adds the SSO federated identity (see "Human
access"); `0022` adds Agent releases + secure enrollment (see "Agent
distribution"). Current head: `0022_agent_releases_enrollment`
(also recorded in `release/RELEASE_MANIFEST.json`).
### HTTPS / reverse proxy
@@ -211,6 +212,82 @@ stored in Postgres (same `token_hash` mechanism `/v1/classify` already used
never authenticates another Agent's jobs (`agent_id` is checked on every
Job operation).
## Agent distribution: install from the panel (secure enrollment)
An alternative to `register_agent.py` for a real pilot: the panel drives the
whole installation, and the technician on the client's Windows host never
gets a permanent secret by hand.
**One-time: publish a release.** The Agent's universal package (one zip per
version — never one per client) is built and published by script, never
uploaded through a browser:
```bash
python scripts/build_agent_package.py # -> dist/GTIFiscalAgent-<version>.zip
docker exec <fiscal-hub-container> python central/scripts/publish_agent_release.py \
--zip dist/GTIFiscalAgent-<version>.zip --notes "..."
```
Publishing the same version again with different bytes is refused (bump the
version instead); publishing identical bytes again is a no-op. The zip lives
on the Hub's local `agent_releases` volume (`AGENT_RELEASE_STORAGE_PATH`,
default `/app/data/releases`), never in PostgreSQL — only its metadata
(`agent_releases`: version, sha256, size, status DRAFT/PUBLISHED/REVOKED) is
a row. `Agents / Servidores -> Releases` lists and can revoke a release.
**Per installation:** `Agents / Servidores -> + Nova instalação` — pick the
client, a display name, an optional expected hostname and the release,
"Criar instalação". That installation's page then offers:
- **Baixar Agent agora** — an authenticated, immediate download (the operator
is already logged in).
- **Gerar link temporário** — a one-time HTTPS URL
(`/dl/agent/<download-token>`), shown exactly once, TTL
`AGENT_DOWNLOAD_LINK_TTL_SECONDS` (default 30 min), single use
(`AGENT_DOWNLOAD_MAX_USES_DEFAULT`, default 1). Hand it to a technician or
open it directly on the client's server — no login required to use it.
Either path streams a bundle = the universal package + a freshly minted
`enrollment.json` (installation id, a one-time enrollment token, the Hub URL)
written at download time. Only that enrollment token's SHA-256 hash is ever
stored (`agent_enrollments.enrollment_token_hash`); its plaintext exists only
inside that one HTTP response — never on disk on the Hub, never logged.
**On the client Windows host**, elevated PowerShell, inside the extracted
package:
```powershell
.\gti-agent.ps1 install-auto
```
This checks every file in the bundle against `MANIFEST.json`'s SHA-256,
refuses a non-HTTPS Hub URL, calls `POST /v1/agents/enroll` with the
enrollment token (deleting `enrollment.json` immediately after, success or
failure), writes `.env` with the newly issued **permanent** `AGENT_TOKEN`
(ACL-restricted to Administrators/SYSTEM, same as `configure`), and
registers the Windows Service — **without starting it**: Firebird is still
unconfigured on purpose (this script never guesses a client's database path
or credentials, same rule as the manual path). Edit `FIREBIRD_DATABASE_PATH`
/ `FB_USER` / `FB_PASSWORD` / `COMPANY_CODE` in `.env`, then
`.\gti-agent.ps1 preflight ; .\gti-agent.ps1 start`. Running `install-auto`
again after a successful enrollment is a no-op (idempotent).
The Hub rejects: an expired or already-used download link, a revoked
installation or release, a wrong/tampered/replayed enrollment token, and a
second enrollment attempt for an already-enrolled installation. A hostname
that doesn't match what the operator expected is recorded
(`hostname_mismatch`) and audited, but does not block enrollment. Both
public routes (`GET /dl/agent/{token}`, `POST /v1/agents/enroll`) are
rate-limited per source IP. Audit actions: `INSTALLATION_CREATED`,
`DOWNLOAD_LINK_CREATED`, `DOWNLOAD_LINK_REJECTED`, `PACKAGE_DOWNLOADED`,
`ENROLLMENT_SUCCEEDED`, `ENROLLMENT_REJECTED`, `AGENT_CREDENTIAL_ISSUED`,
`INSTALLATION_REVOKED`, `AGENT_RELEASE_REVOKED` — the real IP, never a token.
Revoking a pending or enrolled installation (`Revogar` on its detail page)
invalidates any outstanding link/enrollment token immediately and, if an
Agent was already provisioned, disables it (`agents.enabled = false`) — its
existing sessions/jobs stop authenticating on the next request.
## Configuring an Agent installation
On the client machine, copy `agent/.env.example` to `agent/.env` and fill in
docs/RELEASE_CANDIDATE_V1.md
+1 -1
View File
@@ -19,7 +19,7 @@ The Hub never accesses Firebird and never stores Firebird credentials or paths.
| GTI_FISCAL_VERSION (Hub, Agent, packages) | 1.0.0-rc1 (`release/VERSION`, `central/app/version.py`, `GET /version`) |
| fiscal engine (`ENGINE_VERSION`) / decision (`DECISION_VERSION`) | 0.3.0 / mission-04c-ipi-ex-split (unchanged: no fiscal semantics touched) |
| decision engines | fiscal-decision-v1, product-defaults-v1, icms-context-v1 |
| migrations | 0001..0021 (head `0021_sso_federated_identity`, applied in production 2026-09-23; a fresh database is initialized by `alembic upgrade head` alone) |
| migrations | 0001..0022 (head `0022_agent_releases_enrollment`, applied in production 2026-09-23; a fresh database is initialized by `alembic upgrade head` alone) |
| datasets | 13 ACTIVE kinds with sha256/record_count in the manifest |
## What RC1 adds (no fiscal rule changes)