Improve maintainability and auditability of S7CommPlus V1 SessionKey code

[gijzelaerr]

Context

PR #775 added the SessionKey handshake required by V1-initial S7-1200 firmware. This is valuable functionality and has hardware validation, but the implementation is much harder to understand, audit, and maintain than the rest of python-snap7.

The current s7commplus/session_auth package is approximately 19 MB and contains:

• 95,809 lines of generated Python under family0/_generated
• 2,656 lines of human-oriented Python outside _generated
• Four runtime binary lookup/metadata files totaling approximately 328 KB
• A substantial collection of generated transforms, lookup tables, magic constants, and binary fixtures

ARCHITECTURE.md, the HarpoS7 license, generated-code separation, and tools/transpile_harpo_monolith.py are good foundations. The remaining problem is that a contributor still cannot easily determine where behavior comes from, which parts are safe to change, how every generated artifact was produced, or how to verify that checked-in output matches its source.

This is not a request to remove SessionKey support or casually rewrite reverse-engineered cryptographic machinery. The goal is to make the small human-maintained boundary clear and make the opaque/generated parts reproducible and verifiable.

Problems to address

• Generated implementation details dominate the package and obscure the actual authentication flow.
• The provenance, upstream version/commit, format, expected size, and checksum of each binary/generated artifact are not available from one authoritative manifest.
• Regenerating or independently validating all checked-in artifacts is not a single documented workflow.
• Magic constants and transform names are difficult to trace back to HarpoS7 or protocol captures.
• Reviewers cannot easily distinguish handwritten behavior changes from mechanical generated-output changes.
• Debugging failures requires navigating very large transpiled modules rather than a small, stable interface with useful diagnostics.

Proposed direction

1. Inventory and classify every file as human-maintained, generated source, generated binary data, or test fixture.
2. Add an authoritative artifact manifest containing provenance, upstream revision, license, generation method, size, and checksum.
3. Define a small documented interface around key selection, fingerprint matching, SessionKey derivation, blob generation, and legitimation.
4. Make generation and verification reproducible through one documented command. If an artifact cannot be regenerated in this repository, document why and provide deterministic integrity validation instead.
5. Add CI verification that generated artifacts and the manifest have not drifted.
6. Improve traceability from transforms and constants to upstream HarpoS7 code, captures, or published references.
7. Evaluate more compact data-driven or lazily loaded representations for the generated Python, but only where equivalence can be proven with existing vectors and hardware behavior.
8. Keep generated changes separate from handwritten changes in pull requests whenever practical.
9. Document how to debug and extend a new key family without reading the generated monoliths.

Acceptance criteria

• A contributor can quickly identify the human-maintained authentication flow and the supported extension points.
• Every generated or binary runtime artifact has documented provenance and deterministic validation.
• One command verifies or regenerates the artifacts used in a release.
• Generated-output drift fails CI with an actionable message.
• Existing unit vectors, package builds, and V1/TLS compatibility tests remain unchanged or improve.
• Any representation change is demonstrated to be byte-for-byte or behaviorally equivalent before it replaces the current implementation.
• Hardware-validated SessionKey behavior is preserved throughout the work.

Out of scope

• Changing S7CommPlus wire behavior as part of cleanup
• Removing binary/generated artifacts merely to reduce repository size
• Reimplementing the cryptographic transforms from scratch without a verified migration path
• Combining this with unrelated S7CommPlus protocol work

This should be delivered incrementally in focused pull requests so that structural cleanup remains reviewable and does not destabilize the V1 implementation.