chore: establish project baseline

2026-09-21 15:51:47 -03:00
commit 9dcc263217
459 changed files with 447890 additions and 0 deletions
@@ -0,0 +1,88 @@
+# Mission 00E: Threat Model, FDB Provenance, and Real Discovery
+
+## Goal
+
+Formalize the trusted-process threat model, validate the actual `fdb` module
+provenance and Firebird client compatibility, then run read-only discovery only
+against `D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB`.
+
+## Threat model
+
+`TRUSTED_PROCESS = TRUE`: only versioned application code runs in the process;
+there are no untrusted plugins, user-provided scripts, external `eval`/`exec`,
+or externally selected dynamic imports. Deliberate introspection or monkey
+patching by code that already has arbitrary Python execution is equivalent to
+application compromise and is outside this component's boundary.
+
+The boundary protects against implementation mistakes, accidental unauthorized
+operations, arbitrary SQL exposed to normal callers, parameter-to-SQL injection,
+routine execution, wrong database selection, unintended writes, and dependency
+shadowing/import mistakes.
+
+## API boundary
+
+The public API exposes only structured catalog operations and catalog-issued
+bounded sampling. It exposes no `execute(sql)`, `query(sql)`, `raw_execute`,
+operation-registration mutator, procedure/UDF invocation, arbitrary clauses, or
+alternate database path. The registry remains module-private, immutable, and
+centrally constructed. Python internals are not treated as a cryptographic
+sandbox.
+
+The old SQL parser is offline-only diagnostic/test code. It has no authority to
+approve runtime SQL. Internal Firebird query templates may use legitimate
+`CAST`, aggregates, joins, and grouping because they are selected by fixed
+operation keys owned by the project.
+
+## Provenance gate
+
+Before any database connection, inspect the actual `import fdb` module:
+
+- `fdb.__file__` and `fdb.__package__`;
+- module version and `importlib.metadata` distribution/version/location;
+- interpreter, working directory, `sys.path`, and `PYTHONPATH`;
+- local `fdb.py`, `fdb` directory, and unexpected `.pth` shadowing candidates.
+
+The imported module must correspond to the expected installed distribution and
+version, without ambiguous duplicate installations. The installed Firebird
+client/server evidence must match the selected driver compatibility. Any
+ambiguity blocks before import/use of the driver for database access.
+
+## Connection and discovery
+
+After the provenance and safety gates pass, connect only to the authorized FDB,
+using the installed compatible client and a Firebird read-only transaction. Run
+the minimal identity operation first and compare the engine-reported identity
+to the authorized target. Then collect catalog metadata through structured
+operations, use only catalog-issued sample identities, and inspect product,
+stock, fiscal, image, incremental, trigger, and procedure metadata without
+executing routines or reading BLOB contents.
+
+Correlate the ERP UI fields `NCM`, `CFOP`, `CST ICMS`, ICMS rate, `CEST`,
+`CSOSN`, PIS/COFINS, IPI, origin, IAT, incidence, and IPPT to table, column,
+type, domain/FK, dependencies, triggers, evidence, and confidence. Classify
+each as `CONFIRMED`, `INFERRED`, or `UNKNOWN`. Generate a real fingerprint only
+from sanitized complete evidence; otherwise use `SCHEMA_UNKNOWN`.
+
+## Evidence and safety
+
+- Only `D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB` may be opened.
+- External ERP files, services, registry, DLLs, and configuration are read-only.
+- `APPLICATION_DDL_DML_WRITES = 0`.
+- `OTHER_DATABASES_ACCESSED = 0`.
+- `ERP_FILES_MODIFIED = 0`.
+- No credentials, original ERP database path, raw BLOB/image, full rows, or
+  unnecessary customer/commercial data enters source or reports.
+- No fiscal API, image API, Windows service, scheduler, product UPDATE, or
+  migration is implemented.
+
+## Verification and outcome
+
+Tests cover the public API, registry immutability, SQL non-authority,
+quoted-identifier and routine cases, legitimate internal expressions, path
+allowlisting, provenance/shadowing, client compatibility, structured reader,
+sampling, fingerprint, and discovery. The final report includes provenance,
+client/engine facts, connection result, schema mappings, image/incremental/
+trigger evidence, tests, Git state, and real gaps. Missing credentials,
+ambiguous provenance, compatibility failure, identity mismatch, or incomplete
+discovery results in `MISSION_00_BLOCKED` without a database connection or
+fallback to another database.