docs(01-03): complete .intunewin builder plan

- Add 01-03-SUMMARY.md with byte-level format validation results - Update STATE.md: progress 33%, decisions recorded, session updated - Update ROADMAP.md: phase 1 in progress (1/3 summaries) - Mark INFRA-02 complete in REQUIREMENTS.md
2026-04-10 11:26:44 +02:00
parent 25f82e67a2
commit 139503944b
4 changed files with 131 additions and 10 deletions
@@ -0,0 +1,118 @@
+---
+phase: 01-foundation
+plan: "03"
+subsystem: infra
+tags: [intunewin, pycryptodome, aes-256-cbc, hmac-sha256, python, zipfile]
+
+# Dependency graph
+requires: []
+provides:
+  - "build_intunewin() function: Python-native .intunewin assembler using pycryptodome"
+  - "14 byte-level validation tests for .intunewin format compliance"
+  - "Verified encrypted blob layout: HMAC(32) + IV(16) + AES-256-CBC ciphertext"
+  - "Detection.xml schema with all 8 EncryptionInfo sub-elements and correct namespace"
+affects:
+  - "05-export (uses build_intunewin directly for Intune package generation)"
+
+# Tech tracking
+tech-stack:
+  added:
+    - "pycryptodome 3.20.x — AES-256-CBC encryption and PKCS7 padding"
+    - "pytest — test runner (already required)"
+  patterns:
+    - "TDD: failing tests committed first, then implementation"
+    - "Encrypted blob layout: HMAC(32) + IV(16) + ciphertext (AES-256-CBC)"
+    - "Inner ZIP uses DEFLATE; outer ZIP uses STORED (no double-compression of encrypted content)"
+    - "All crypto values in Detection.xml use standard base64 encoding"
+
+key-files:
+  created:
+    - "imptune/generators/intunewin_builder.py"
+    - "imptune/generators/__init__.py"
+    - "tests/test_intunewin.py"
+    - "tests/__init__.py"
+  modified: []
+
+key-decisions:
+  - "IV is 16 bytes (not 32) — corrected from STACK.md documentation error; aligns with AES standard and svrooij.io verification"
+  - "MacKey is 32 bytes — same size as EncryptionKey, consistent with SvRooij.ContentPrep behavior"
+  - "Inner ZIP uses DEFLATE compression (matches C# reference implementation .NET default)"
+  - "Real Intune upload validation deferred to Phase 5 gate — local byte-level tests are necessary but not sufficient"
+
+patterns-established:
+  - "Pattern: .intunewin encrypted blob = HMAC-SHA256(32) + IV(16) + AES-256-CBC-ciphertext"
+  - "Pattern: build_intunewin(source_dir, setup_file, output_path) is the public API"
+  - "Pattern: All crypto roundtrip tests in test_intunewin.py verify encrypt-then-decrypt recovers original files"
+
+requirements-completed:
+  - INFRA-02
+
+# Metrics
+duration: 7min
+completed: 2026-04-10
+---
+
+# Phase 1 Plan 03: .intunewin Builder Summary
+
+**Python-native .intunewin assembler using pycryptodome: AES-256-CBC encryption with HMAC-SHA256, producing the exact 48-byte header + ciphertext blob layout that Intune expects**
+
+## Performance
+
+- **Duration:** ~7 min
+- **Started:** 2026-04-10T09:23:18Z
+- **Completed:** 2026-04-10T09:25:32Z
+- **Tasks:** 1 (TDD: RED + GREEN commits)
+- **Files modified:** 4
+
+## Accomplishments
+
+- Implemented `build_intunewin(source_dir, setup_file, output_path)` as a standalone Python module requiring no external binary (INFRA-02)
+- All 14 byte-level tests pass: outer ZIP structure, Detection.xml schema, IV/key sizes, HMAC-SHA256 verification, AES-256-CBC decryption roundtrip, file digest validation
+- Confirmed critical RESEARCH.md correction: IV is 16 bytes (not 32 as incorrectly documented in STACK.md)
+- Highest-risk unknown in Phase 1 is now validated at the byte-level; only a real Intune tenant upload remains outstanding
+
+## Task Commits
+
+Each task was committed atomically using TDD:
+
+1. **RED — Failing tests** - `4d455e7` (test)
+2. **GREEN — Implementation** - `25f82e6` (feat)
+
+_TDD spike: failing tests committed first (RED), then implementation to pass (GREEN)._
+
+## Files Created/Modified
+
+- `imptune/generators/intunewin_builder.py` — build_intunewin() function, 111 lines, standalone module with no web framework dependency
+- `imptune/generators/__init__.py` — generators package marker
+- `tests/test_intunewin.py` — 14 byte-level tests organized into 4 test classes
+- `tests/__init__.py` — tests package marker
+
+## Decisions Made
+
+- **IV is 16 bytes:** STACK.md stated 32 bytes — this is a documentation error. AES block size is always 16 bytes. pycryptodome raises `ValueError: IV must be 16 bytes long` with 32-byte IV. Implementation uses `os.urandom(16)`.
+- **MacKey is 32 bytes:** svrooij articles do not specify exact MacKey size; chose 32 bytes (same as EncryptionKey) consistent with SvRooij.ContentPrep source behavior.
+- **Inner ZIP uses DEFLATE:** Matches the C# reference implementation (.NET `ZipArchive` default). The conflicting "no compression" WebSearch result was treated as low-confidence (tertiary source); DEFLATE will be confirmed/corrected in the Phase 5 real Intune upload gate.
+- **Real Intune validation deferred:** Pitfall 5 from RESEARCH.md is explicitly acknowledged — local byte-level tests confirm format structure, but the definitive validation requires a real Intune tenant upload in Phase 5.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None — all crypto operations succeeded on first implementation. pycryptodome correctly enforced 16-byte IV constraint (which would have caught the STACK.md documentation error if it had been used with 32 bytes).
+
+## User Setup Required
+
+None — no external service configuration required. The `.intunewin` format validation against a real Intune tenant is a manual gate in Phase 5, not a configuration step.
+
+## Next Phase Readiness
+
+- `build_intunewin()` is ready for use in Phase 5 (package export)
+- Module is standalone — no dependency on FastAPI, SQLite, or any web framework
+- Outstanding concern: byte-level format confidence is MEDIUM until a real Intune tenant upload confirms acceptance
+- Blocker for Phase 5 only: access to a real Intune tenant for upload testing
+
+---
+*Phase: 01-foundation*
+*Completed: 2026-04-10*