# GTI FISCAL WINDOWS INSTALLER EXE V1 — Implementation Plan

- Date: 2026-09-23
- Spec: `docs/superpowers/specs/2026-09-23-windows-installer-exe-v1-design.md`
- Branch strategy: work on `master` in focused commits (repo convention; no remote).

## Order of work (TDD front-loaded)

Phase A — Backend install_code (code-first, tests first)
1. `central/app/enrollment.py`: add Crockford Base32 install-code module
   (`generate_install_code`, `normalize_install_code`, `install_code_digest`,
   `valid_install_code`). 16 chars, alphabet `0123456789ABCDEFGHJKMNPQRSTVWXYZ`,
   grouped `XXXX-XXXX-XXXX-XXXX`.
2. Migration `0023_install_codes.py` on `agent_enrollments`:
   `install_code_hash`, `install_code_expires_at`, `install_code_attempts`,
   `install_code_created_at`. Update `AgentEnrollment` model.
3. `central/app/agent_distribution.py` — `POST /v1/agents/enroll`:
   - Accept `install_code` (primary) OR legacy (`installation_id` +
     `enrollment_token`).
   - If both bodies present → 400 `INVALID_REQUEST` (ENROLLMENT_REJECTED).
   - Install-code path resolves Installation by hash alone; validates status,
     expiry, one-time, attempts, release PUBLISHED; mints agent+installation,
     marks code used (hash cleared after success → replay-proof), audits
     `ENROLLMENT_STARTED/SUCCEEDED/REJECTED` (never the code).
   - Rate limit: keep per-IP `enroll` bucket AND per-code/installation bucket
     (add `record_attempt("enroll_code:<enrollment_uuid>", ip)`).
   - `install_code_attempts` increments on each failed attempt.
4. `central/app/web.py` + templates:
   - `agent_pending_detail.html` / `agent_detail.html`: Código de instalação
     `XXXX-XXXX-XXXX-XXXX` + [Copiar], Expira em, [Baixar instalador (.EXE)],
     [Gerar novo código], [Revogar]. No raw tokens.
   - POST `/agents/pending/{uuid}/code` → generate/rotate code (audit
     `INSTALLATION_CODE_CREATED`); POST `/agents/pending/{uuid}/revoke` already
     exists → also clear code + audit `INSTALLATION_CODE_REVOKED`.
   - `agent_releases.html` main button → EXE.
5. Downloads serve universal EXE: `build_and_serve` → when release artifact is
   an EXE, serve the stored EXE bytes (no bundle zip / no enrollment.json for the
   EXE flow). Filename for EXE = stored release filename. Audit
   `INSTALLER_DOWNLOADED`.
6. `central/scripts/publish_agent_release.py`: generalize `--zip` to `--artifact`
   (accept `.zip` or `.exe`); filename derivation handles `GTIFiscalAgent-Setup-<v>.exe`;
   enforce immutability (refuse replacing a PUBLISHED artifact). `published_at`
   fix already in place (commit 21c9261).
7. Tests in `central/tests/test_agent_distribution.py` + new
   `test_install_codes.py` (RED→GREEN). Full suite green.

Phase B — Agent runtime credential isolation
8. `agent/src/gti_fiscal_agent/credential_store.py`: DPAPI LocalMachine
   encrypt/decrypt (`win32crypt.CryptProtectData`/`CryptUnprotectData` with
   `CRYPTPROTECT_LOCAL_MACHINE`), ACL enforcing (SYSTEM/Administrators),
   plaintext-token fallback only in dev (env `GTI_ALLOW_PLAINTEXT_CREDENTIAL=1`).
9. `run_agent_service.py` Config: read AGENT_TOKEN from env OR decrypt from
   `credentials.bin` (`GTI_CREDENTIAL_FILE`, default Program Files path);
   keep `agent.env` non-secret; enforce FIREBIRD_WRITES=0 (already fail-closed).
10. Tests: credential_store round-trip + no-write enforcement.

Phase C — Installer (Windows build host = this dev machine)
11. `installer/` package (self-contained sources bundled by PyInstaller):
    - `installer/setup_main.py` (uac-admin entitlement via PyInstaller
      `--uac-admin`): tkinter UI with single code field; fixed prod Hub URL
      (dev override only via `GTI_HUB_URL` env/CLI); POST enroll; write
      `agent.env` (non-secret) + `credentials.bin` (DPAPI LocalMachine + ACL);
      extract bundled Service host + Uninstall.exe into Program Files;
      register service + recovery `sc.exe failure ...`; report preflight;
      write ARP key; best-effort `WINDOWS_INSTALL_COMPLETED`.
    - `installer/service_main.py`: minimal Windows Service host entry reusing
      `gti_agent_windows_service` logic (token from credential_store).
    - `installer/uninstall_main.py`: stop/remove service, remove Program Files
      tree + ARP, remove credentials.
12. `scripts/build_windows_installer.ps1`: clean dist/installer, read
    `release/VERSION` (1.1.1), PyInstaller builds (Setup onefile --uac-admin,
    service host onedir, uninstall onefile), embed service+uninstaller as data
    in Setup, write `.sha256`. Fails on missing tool/dep.
    Reproducibility = automated/repeatable + immutable release (not byte-identical
    hashes).
13. Local build + smoke: produce EXE; validate layout, sha256, no credential in
    `agent.env`, FIREBIRD_WRITES=0.

Phase D — Local E2E (this Windows dev machine)
14. Run Setup against a LOCAL Hub (control-plane image, scratch postgres or
    SQLite test env) for the UI/install flow: invalid code → clear error; valid
    code → enroll → verify utils/env/credential/service registration; reinstall
    idempotence; uninstall.
    (Real production E2E happens after deploy, Phase F.)

Phase E — Production deploy + release
15. Backup: pg_dump of `gti_fiscal` + release storage volume copy (via container)
    to backup location; validate restore (EXE + metadata) from the backup copy.
16. Build + deploy Hub image (migration 0023 via `alembic upgrade head`);
    postgres intact; smoke: health, panel, downloads.
17. Publish release 1.1.1 EXE (immutable), `AGEING NOT overwritten`: 1.1.0 zip
    untouched.

Phase F — Production E2E (REAL Windows)
18. Create E2E installation in production panel; generate code; download real
    EXE from `https://gtifiscal.gtigrupo.com.br`; run on this real Windows host,
    enter code, enroll. Verify Installation→ENROLLED, Agent created,
    `credentials.bin` DPAPI-protected (ACL), `agent.env` no token, service
    registered (Automatic/Delayed, recovery, NOT started since Firebird blank),
    WINDOWS_INSTALL_COMPLETED audit.
19. Rejection E2E: invalid code, expired code, replayed/used code, code+token
    together → 400. Each audited.
20. Uninstall via Uninstall.exe; revoke/deactivate E2E agent in panel; audit
    preserved.

Phase G — Report
21. Final report in the mission's exact field list + COMMITS + GIT_STATUS.

## Verification gates
- Entire `central/tests` suite green: `python -m pytest central/tests -q` and
  `python -m pytest tests -q` (repo-level offline tests) after each phase.
- Migration head check: `0023` newest; fresh-DB upgrade test green.
- Artifacts: `dist/installer/GTIFiscalAgent-Setup-1.1.1.exe` + `*.sha256`.
- No `AGENT_TOKEN` literal anywhere in `agent.env`/installed tree.