refactor(windows): consume OpenPath immutable deployment bundles as a thin wrapper

[balejosg]

Summary

Migrate ClassroomPath to the new canonical OpenPath Windows deployment capability once the fresh OpenPath implementation tickets are complete.

ClassroomPath must behave strictly as a wrapper:

ClassroomPath -> OpenPath

It may provide ClassroomPath-specific presentation, institution/tenant policy and gateway integration, but it must not implement a second generic Windows installer, deployment-grant, bundle, redemption, signing, provenance or per-device credential lifecycle.

This is a fresh implementation ticket. Older ClassroomPath Windows-installer issues may be referenced for historical context only; they are not the implementation contract for this migration.

Dependencies

Blocked by the fresh OpenPath roadmap:

• OpenPath #250 — immutable Authenticode-signed Windows installer + external bootstrap;
• OpenPath #248 — generic one/multi-device deployment grants and bundles;
• OpenPath #249 — OpenPath cutover to the immutable deployment architecture;
• OpenPath #251 — signed-installer promotion/provenance contract.

Use the final public OpenPath contracts shipped by those issues, not assumptions from the legacy personalized-EXE design.

Target ClassroomPath UX

A ClassroomPath operator should be able to select an aula and prepare a deployment for one or many devices, e.g. 30 PCs, while ClassroomPath delegates the complete generic mechanism to OpenPath.

Conceptually:

ClassroomPath aula UI
  -> request OpenPath deployment for OpenPath classroom/scope
  -> OpenPath creates bounded deployment
  -> ClassroomPath presents protected bundle download
  -> same immutable signed EXE installed on all PCs
  -> OpenPath performs redemption/accounting/device credential issuance
  -> ClassroomPath presents safe progress/status

Ownership

ClassroomPath may own:

• mapping ClassroomPath domain concepts to the corresponding OpenPath public identifiers;
• additional tenant/institution authorization before calling OpenPath;
• wrapper UI/branding/text;
• proxy/gateway wiring;
• wrapper-level observability and integration canary.

ClassroomPath must not own:

• Authenticode signing;
• immutable installer build/provenance;
• deployment bearer/reference format;
• deployment limits/atomic redemption;
• bundle schema/generation;
• endpoint bootstrap protocol;
• per-device credential creation;
• OpenPath core readiness/canary;
• Windows runtime behavior.

Historical context only

Previous ClassroomPath installer issues, including #157/#158, may help inventory legacy code and migration hazards, but this ticket is the new implementation authority.

Non-goals

• modifying OpenPath code from the ClassroomPath repository;
• maintaining a fallback second generic implementation indefinitely;
• recreating OpenPath deployment state in ClassroomPath DB;
• live staging/production deployment without explicit authorization.

[balejosg]

Implementation spec / plan

Read ClassroomPath AGENTS.md completely before implementation. This ticket is downstream-only. The final OpenPath public contracts shipped by #250, #248, #249 and #251 are authoritative; older ClassroomPath installer issues are historical reference only.

1. Hard dependencies

Do not begin destructive migration until:

OpenPath #250
  immutable signed EXE + external bootstrap stable

OpenPath #248
  deployment create/status/revoke + bundle + redemption stable

OpenPath #249
  canonical OpenPath runtime no longer depends on per-request personalized EXE

OpenPath #251
  promotion contract identifies exact signed installer identity

Record the exact OpenPath interface/schema versions and required source SHA before editing ClassroomPath integration.

2. Wrapper invariant

Final architecture:

ClassroomPath UI/policy/gateway
        |
        v
OpenPath public deployment API
        |
        +-> protected deployment bundle
        +-> deployment status/revoke
        +-> endpoint redemption/accounting
        +-> unique endpoint credentials

ClassroomPath must not duplicate the generic mechanism.

A useful regression rule is:

If ClassroomPath disappeared, OpenPath standalone would still be able to create and execute the same one/multi-device deployment workflow.

3. Inventory legacy ClassroomPath ownership

Before deleting anything, classify current Windows installer/deployment code as:

REMOVE
REPLACE_WITH_OPENPATH_PUBLIC_CALL
KEEP_WRAPPER_SPECIFIC
TEMPORARY_COMPATIBILITY
MIGRATE_THEN_REMOVE

Inspect at minimum:

api/src/services/windows-offline-installer-*
api/src/lib/windows-offline-installer-*
api/src/trpc/routers/windows-offline-installer.ts
react-spa/src/components/WindowsOfflineInstallerAction.tsx
scripts/provision-windows-offline-installer-template.mjs
scripts/windows-offline-installer-canary.mjs
Docker mounts/volumes/env
release/deployment state fields
legacy download-ref DB structures
related tests/docs

Do not assume all files still exist at implementation time; inspect current main.

4. ClassroomPath-to-OpenPath mapping

ClassroomPath may translate an aula/domain concept to the corresponding OpenPath scope/classroom identifier already supported by the public OpenPath contract.

Do not pass ClassroomPath-specific metadata merely for convenience unless the OpenPath API has a generic metadata field with defined semantics. OpenPath must not learn about ClassroomPath tenants, schools, billing, branding, etc.

5. API/gateway integration

ClassroomPath should call the documented public OpenPath deployment operations, conceptually:

create deployment
get/status deployment
revoke deployment
download protected bundle

Preserve OpenPath authorization at its own boundary. ClassroomPath may apply additional institution policy first, but must not replace OpenPath authorization with a trusted internal shortcut unless OpenPath explicitly documents such a wrapper integration contract.

Do not import OpenPath API internals or access OpenPath DB/filesystem directly.

6. UX for 30-PC operator

ClassroomPath may present educational terminology, e.g. from an aula page:

Instalar equipos
  Cantidad: 30
  Vigencia: <bounded choice from OpenPath-supported values>
  Crear paquete

Then display only safe OpenPath status:

7 / 30 instalados
23 disponibles
caduca ...
estado active/exhausted/expired/revoked

Download should be the canonical OpenPath-protected bundle containing the same immutable signed EXE plus the deployment sidecar.

Do not expose the raw deployment bearer/reference in UI state, localStorage, analytics, logs or durable ClassroomPath DB.

7. No duplicate deployment state

ClassroomPath may cache ordinary safe presentation/query data using existing frontend/query patterns, but it must not create a second authoritative table for:

maxEnrollments
successfulEnrollments
remaining slots
redemption leases
raw/hash deployment reference
endpoint redemption state

OpenPath owns those values.

If ClassroomPath needs historical/audit presentation, consume a supported OpenPath status/audit API rather than reconstructing state independently.

8. Release/provenance consumption

Consume the fresh OpenPath promotion contract from #251 according to the final supported wrapper interface.

ClassroomPath must not:

derive Windows release tag
select template asset
compute which older OpenPath installer is compatible
choose pre-sign vs post-sign artifact

The exact signed installer identity comes from OpenPath.

If ClassroomPath release tooling needs to project that identity into its own release bundle/state, the projection must remain one-way:

OpenPath contract -> ClassroomPath release state

Never reconstruct OpenPath authority from ClassroomPath env fields.

9. Legacy path migration

Use a staged cutover:

A. add new wrapper integration while old code remains inert/available for controlled rollback if necessary
B. prove local/integration contract
C. with explicit staging authorization, prove ClassroomPath -> OpenPath deployment bundle end-to-end
D. with explicit production authorization, cut over
E. stop all new legacy personalized-EXE writes/refs
F. drain short-lived legacy refs/artifacts
G. remove legacy services/routes/storage/config/DB runtime dependency
H. remove temporary switch/fallback

No long-lived dual implementation.

Do not edit historical DB migrations in place; use forward migrations where retirement is needed.

10. Readiness

ClassroomPath readiness should test only its wrapper dependency on the supported OpenPath capability, not re-hash the installer or revalidate OpenPath deployment storage.

Conceptually:

ClassroomPath ready
 = ClassroomPath dependencies ready
 + required OpenPath public capability compatible/available

OpenPath owns deep installer/deployment readiness.

11. Canary ownership

OpenPath core canaries own:

bundle integrity
immutable EXE hash/signature
redemption concurrency/idempotency
endpoint credential issuance
Windows runtime

ClassroomPath integration canary should prove only the extra boundary:

ClassroomPath auth/policy
-> ClassroomPath UI/API wrapper
-> OpenPath create deployment
-> protected bundle download succeeds through wrapper path
-> safe status observable

It may verify downloaded EXE SHA against the OpenPath contract to catch proxy corruption, but must not duplicate OpenPath internal lifecycle tests.

No raw refs/tokens/cookies/JWTs in evidence.

12. TDD order

Phase 0 — contract inventory

Read final OpenPath #250/#248/#249/#251 docs/code/tests and create a migration matrix for all legacy ClassroomPath components.

Phase 1 — thin adapter

Write failing API integration tests, then implement the smallest supported OpenPath client/proxy surface.

Phase 2 — wrapper UI

Write tests for create N-device deployment, bundle download, progress/status, revoke and replacement after terminal state.

Phase 3 — release/readiness integration

Consume exact OpenPath interface/provenance and remove independent Windows artifact selection.

Phase 4 — integration canary

Add secret-safe ClassroomPath boundary canary.

Phase 5 — authorized staging/production cutover

Only when explicitly requested. Do not infer authorization from this ticket.

Phase 6 — legacy drain/cleanup

Stop old writes, expire refs, forward-migrate obsolete DB/runtime dependencies, remove dead code/config/storage and temporary fallback.

13. Required tests

At minimum prove:

ClassroomPath creates deployment via public OpenPath API
wrapper-specific deny can stop request before OpenPath call
OpenPath authorization still executes
30-device value passes through as supported bounded OpenPath input
bundle bytes are not rebuilt/repacked with a different EXE
raw deployment bearer never enters ClassroomPath durable storage/logging
status/progress comes from OpenPath
revoke calls OpenPath
ClassroomPath cannot exceed/reimplement OpenPath accounting
signed installer identity comes from OpenPath promotion contract
legacy personalized generator is not invoked by new UI
removed legacy config/modules cannot be silently reintroduced

Use ClassroomPath command semantics from its AGENTS.md, including relevant deployment, public-surface, docs and commit verification gates.

14. Acceptance criteria

• ClassroomPath is only a wrapper over OpenPath deployment capability.
• Operator can prepare a deployment for one or many PCs from ClassroomPath UX.
• Generic deployment grant/bundle/redemption is implemented only in OpenPath.
• Same immutable signed OpenPath EXE is delivered; ClassroomPath never modifies it.
• ClassroomPath does not store raw deployment bearer or recreate deployment accounting.
• OpenPath authorization remains enforced.
• ClassroomPath consumes exact signed-installer provenance from OpenPath.
• No independent Windows tag/template selection remains in the wrapper for this capability.
• Deep readiness/canary remains OpenPath-owned.
• Wrapper canary contains no secrets.
• Legacy personalized installer implementation is fully retired after controlled cutover.
• No permanent migration switch/fallback remains.
• No files inside upstream/openpath/ are modified directly for ClassroomPath-only work.

15. Completion report

Report:

1. final OpenPath public contracts consumed;
2. migration matrix of legacy ClassroomPath components;
3. adapter/API surface;
4. wrapper UX behavior;
5. release/provenance integration;
6. readiness/canary boundary;
7. legacy DB/config/storage cleanup;
8. focused and repository verification results;
9. staging/production evidence only if explicitly authorized and actually executed;
10. any remaining compatibility surface (expected final value: none).

[balejosg]

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

This issue is the downstream thin-wrapper workstream. The epic is coordination-only; this issue remains the ClassroomPath implementation authority for its scope.