---
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*