refactor(windows): cut over to immutable installer deployments and retire per-request EXE personalization

[balejosg]

Summary

After #250 and #248 are complete, make the immutable signed installer + external deployment bootstrap the canonical OpenPath Windows installation path and retire the obsolete per-request personalized-EXE lifecycle introduced by earlier work.

This is deliberately a separate cutover/cleanup issue so #250 can deliver the signed immutable release artifact without waiting for the complete multi-device deployment system, and #248 can build against that artifact without requiring the legacy path to disappear in the same change.

Dependencies

Blocked by:

• security(windows): ship one immutable Authenticode-signed installer with zero recurring signing cost #250 — fresh immutable Authenticode-signed installer release artifact + external bootstrap contract
• feat(enrollment): add generic multi-device deployment grants and Windows deployment bundles #248 — generic deployment grants/bundles + per-device redemption

Coordinate final release identity with #251.

Do not start destructive cleanup until both capabilities are proven by OpenPath standalone tests and Windows target-platform evidence.

Target state

OpenPath release
  -> one immutable signed OpenPath-Windows-Setup.exe

OpenPath enrollment/deployment API
  -> one-device or multi-device deployment authority
  -> external bootstrap/bundle

Windows endpoint
  -> same signed EXE
  -> bootstrap redemption
  -> unique durable device credential

No supported runtime request should need to copy a template and mutate PE bytes with applyOverlay().

Ownership

OpenPath remains the sole owner of the generic installer/deployment lifecycle. This issue must not add downstream wrapper concepts.

Cleanup targets

Inventory and retire/rework as appropriate:

• per-request applyOverlay() generation in windows-offline-installer-artifact.service.ts;
• private storage used only for personalized .exe artifacts;
• reference persistence/routes that exist only to stream those personalized .exe files;
• runtime template provisioning/readiness requirements that are obsolete once the immutable signed release artifact is the canonical input;
• personalized-EXE canaries/E2E fixtures superseded by immutable-EXE + deployment-bootstrap coverage;
• API/SPA contracts whose semantics still promise a newly personalized executable on every click.

Do not remove generic primitives still used by deployment-bundle delivery, rollback/provenance, or compatibility windows.

Migration invariant

There must be no long-lived dual authority:

old personalized EXE path = compatibility only
new immutable signed deployment path = canonical

Once the compatibility window ends, repository tests should prevent accidental reintroduction of runtime PE personalization as a supported path.

Related

• security(windows): ship one immutable Authenticode-signed installer with zero recurring signing cost #250 — fresh signed immutable installer implementation
• feat(enrollment): add generic multi-device deployment grants and Windows deployment bundles #248 — fresh multi-device deployments
• feat(release): attest the immutable signed Windows installer in the OpenPath promotion contract #251 — fresh signed-installer promotion provenance
• Historical context only: feat(windows): make personalized offline installer a first-class OpenPath capability #242/feat(windows): publish one immutable Authenticode-signed installer per release #247/feat(release): publish atomic OpenPath Promotion Contract v2 #244
• ClassroomPath chore(deps-dev): update typescript-eslint requirement from ^8.20.0 to ^8.57.1 in /firefox-extension #161 — fresh downstream wrapper migration

Non-goals

• changing Windows policy/runtime behavior unrelated to enrollment bootstrap;
• removing useful generic single-use download primitives if feat(enrollment): add generic multi-device deployment grants and Windows deployment bundles #248 still uses them for bundle delivery;
• changing downstream wrapper code in this repository;
• deleting historical migrations in place;
• claiming downstream production cutover from OpenPath-only evidence.

[balejosg]

Implementation spec / cutover plan

This issue is the cleanup/canonicalization stage. It must not redesign #247 or #248. Read AGENTS.md completely and inspect the final code/contracts delivered by both dependencies before deleting anything.

1. Entry gate

Do not begin destructive removal until all of the following are true:

#247
  final immutable signed EXE published/tested
  external bootstrap contract stable
  final signed EXE Windows E2E green

#248
  deployment create/status/revoke stable
  bundle download stable
  transactional redemption proven
  standalone UI can use deployment flow
  Windows sidecar/pending enrollment E2E green

If either dependency changed names/shapes, follow the shipped OpenPath contract rather than assumptions in this issue.

2. Canonical product behavior after cutover

The OpenPath standalone Windows flow must become conceptually:

Classroom -> Enroll -> Windows
  -> prepare deployment (1 or N devices)
  -> download bundle
  -> immutable signed EXE + external bootstrap

There must no longer be a canonical user-facing action whose semantics are:

click -> mutate template bytes with classroom/token -> publish unique EXE

3. Inventory before deletion

Classify every current #242 component as:

REMOVE
REUSE FOR BUNDLE DELIVERY
REUSE AS GENERIC PRIMITIVE
REPLACE WITH #247/#248
TEMPORARY COMPATIBILITY

At minimum inspect:

api/src/services/windows-offline-installer-artifact.service.ts
api/src/services/windows-offline-installer-download-refs.service.ts
api/src/services/windows-offline-installer-provision.service.ts
api/src/lib/windows-offline-installer.ts
api/src/lib/windows-offline-installer-config.ts
api/src/routes/windows-offline-installer.ts
api/src/trpc/routers/windows-offline-installer.ts
shared/src/windows-offline-installer.ts
react-spa Windows enrollment action/components
scripts/windows-offline-installer-canary.mjs
tests/e2e/ci/run-windows-personalized-offline-installer-e2e.ps1
.github/workflows/release-scripts.yml
docs/windows-offline-installer.md
Docker/compose/runtime env for template/artifact storage
DB migration/table used by personalized download refs

Do not assume an entire service disappears just because its current name says offline-installer; keep generic protected-download/reference primitives if #248 legitimately reuses them.

4. Retire runtime PE personalization

Final regression invariant:

supported production runtime
  -> never calls applyOverlay() to create a distributable Windows EXE

applyOverlay() may remain only if still needed for historical tests/migration tooling and clearly marked non-canonical. Prefer deleting dead production wiring once compatibility ends.

Add a repository-level guard/test that fails if the canonical Windows generate/deployment path reintroduces per-request PE mutation without an explicit architecture change.

5. Artifact storage cleanup

The old architecture needs writable private storage for unique personalized EXEs. After #248:

• remove storage/config/readiness requirements used only for per-request EXE artifacts;
• retain storage only if needed for protected deployment ZIPs or another current generic lifecycle;
• do not leave an empty persistent volume/env contract because it is convenient;
• preserve bounded cleanup for any remaining secret-bearing bundle artifacts;
• do not delete release/provenance caches needed for the immutable signed EXE.

6. Template/provisioning migration

The old runtime provisions an unsigned/mutable template for API-time personalization. The new architecture needs the exact immutable signed release installer identity.

After final #247/#244 integration:

runtime/deployment consumes exact signed installer identity

not:

runtime needs writable/personalizable template

Refactor config/readiness/docs accordingly. Preserve exact-SHA, sidecar, provenance and fail-closed verification; remove only the obsolete assumption that API generation will mutate those bytes.

7. API migration

Deprecate/remove the old public contract only after a supported replacement exists.

The current operation:

windowsOfflineInstaller.generate({ classroomId })
  -> unique EXE download metadata

must be replaced in standalone product code by #248's deployment API.

If a short compatibility period is required:

• mark the old API deprecated;
• do not expose it as the default SPA path;
• define an explicit removal condition/date/version in docs/code comments;
• do not keep both indefinitely.

At final completion, unsupported legacy calls should fail predictably rather than silently generating personalized EXEs through hidden code.

8. Database/reference migration

If the old personalized-download reference table/service becomes unused:

1. stop all new legacy writes;
2. allow active short-lived refs to expire or revoke them according to policy;
3. verify no supported old application instance still needs them;
4. remove runtime dependency;
5. add a forward migration for obsolete structures according to repo migration policy;
6. do not edit/delete historical migration files in place.

If #248 reuses the same table generically, rename/refactor only if justified by repository conventions and contract tests; do not force a risky migration merely for aesthetics.

9. SPA migration

The default OpenPath Windows enrollment UI must use #248.

Required regression tests:

one-device flow -> deployment max=1
batch flow -> deployment max=N
bundle download uses immutable EXE
progress/status visible
revoke works
no personalized EXE generation request
manual fallback remains only if still supported

Remove stale UI state/cache semantics tied to downloadUrl for a unique per-click personalized EXE.

10. Canary/E2E migration

Replace obsolete canonical evidence:

generate personalized EXE
-> download
-> replay=410
-> inspect embedded classroom/token payload

with the new authoritative ladder:

create deployment
-> protected bundle download
-> immutable EXE hash/signature exact
-> sidecar/bootstrap valid
-> endpoint redemption
-> endpoint-specific durable identity
-> exhaustion/idempotency where applicable

Keep historical personalized-path tests only while the compatibility path is intentionally supported. Remove them when the path is removed so CI does not enshrine dead architecture.

11. Readiness

Final readiness should prove the dependencies required by the canonical path and nothing obsolete.

Expected checks may include:

exact immutable installer available/verified
required deployment DB/schema ready
bundle output path/stream capability ready if applicable

It should no longer fail merely because a writable personalized-EXE artifacts directory/template-overlay capability is absent after that feature has been removed.

Readiness remains local/cheap and must not fetch GitHub or repair assets.

12. Documentation

Rewrite docs/windows-offline-installer.md (or successor doc) around the final architecture:

immutable signed installer
external bootstrap
deployment grant
one/multi-device flow
protected bundle
unique per-device credential
offline pending enrollment
silent deployment
wrapper integration

Document the old personalized EXE architecture only as migration/history if still useful. Do not present it as current canonical behavior.

13. Promotion Contract v2 consistency

Before removing old template fields/assumptions, inspect final #244 contract. Do not leave downstream consumers forced to infer which legacy/new Windows field is authoritative.

Final rule:

promotion contract identifies exact immutable signed installer

Any compatibility template identity must be explicitly non-authoritative or removed after the migration window.

14. TDD/cutover order

Phase 0 — dependency inventory

Record the final #247/#248 contracts and classify old components.

Phase 1 — make new path default

Change standalone API/UI integration so normal OpenPath users no longer invoke personalized generation. Add regression tests before removal.

Phase 2 — stop legacy writes/generation

Disable new personalized artifact/ref creation while preserving bounded compatibility for already-issued refs if needed.

Phase 3 — expire/drain legacy state

Prove no active supported consumer remains. Do not rush DB/storage deletion.

Phase 4 — remove dead API/services/storage/config

Delete only after tests show the new path owns the product behavior.

Phase 5 — migrate canaries/E2E/docs

Remove tests that would otherwise preserve the obsolete architecture; retain/update target-platform evidence for the new path.

Phase 6 — repository regression guard

Add explicit test/contract asserting canonical runtime does not personalize PE bytes per request.

15. Acceptance criteria

• OpenPath standalone Windows enrollment uses feat(enrollment): add generic multi-device deployment grants and Windows deployment bundles #248 deployment API by default.
• One-device enrollment works through maxEnrollments=1 rather than a separate personalized-EXE architecture.
• No supported runtime path mutates the signed installer bytes per request.
• Canonical downloads contain the exact immutable signed feat(windows): publish one immutable Authenticode-signed installer per release #247 EXE.
• Old personalized EXE generation API is removed or explicitly time-bounded deprecated during a short migration window.
• No new legacy personalized download refs/artifacts are written after cutover.
• Obsolete writable personalized-artifact storage/config/readiness requirements are removed.
• Obsolete template-personalization provisioning assumptions are removed without weakening immutable artifact provenance.
• Legacy DB state is retired safely using forward migrations if applicable.
• Default SPA contains no hidden fallback that regenerates a personalized PE.
• Core canary/E2E validates deployment bundle + immutable EXE + redemption instead of embedded personalized payload.
• Maintained docs describe only the canonical new architecture.
• Repository regression test prevents accidental reintroduction of per-request PE personalization.
• No downstream wrapper concepts are introduced.

16. Completion report

Report:

1. inventory/classification of feat(windows): make personalized offline installer a first-class OpenPath capability #242 components;
2. exact old API/service/storage removed or retained;
3. final canonical API/UI path;
4. DB/config/runtime migration;
5. readiness changes;
6. canary/E2E replacement;
7. docs updated;
8. compatibility surface remaining, with explicit removal condition if nonzero;
9. focused tests and required repository verification results;
10. Windows target-platform evidence.

[balejosg]

Dependency update: the active immutable-installer dependency for this issue is #250, not #247. The active release-provenance follow-up is #251. Older #242/#244/#247 are context only. The fresh downstream ClassroomPath migration is #161.

[balejosg]

Tracked under epic #252 — immutable signed installer and multi-device deployment architecture.

This issue is the final OpenPath cutover/legacy-retirement workstream for that epic. #252 is coordination-only; this issue remains the implementation authority for its scope.