feat(enrollment): add generic multi-device deployment grants and Windows deployment bundles

[balejosg]

Summary

Add a first-class generic OpenPath deployment capability for enrolling a bounded set of endpoint devices with one operator-prepared bundle, without personalizing or modifying the signed Windows executable.

This is the operator workflow required after #250 moves Windows enrollment data outside the PE bytes.

Target operator experience:

OpenPath admin/teacher
  -> create deployment for N devices
  -> download one deployment bundle
  -> copy to USB/share
  -> run the same signed OpenPath installer on N Windows PCs
  -> zero classroom codes typed per PC
  -> each PC receives its own durable device credential

The core must remain usable by OpenPath standalone. Downstream wrappers may label a deployment as an aula/classroom deployment in their own UI, but no downstream product concept belongs in this implementation.

Architecture boundary

Per AGENTS.md:

wrapper -> OpenPath

OpenPath owns:

• deployment-grant lifecycle;
• authorization;
• max-enrollment accounting;
• expiry/revocation;
• atomic redemption;
• per-device credential issuance;
• generic bundle/config schema;
• Windows installer consumption of the bundle;
• interactive and silent install contract;
• standalone API/UI;
• readiness/observability/security semantics;
• core canary and Windows E2E.

A wrapper owns only presentation, additional upstream policy and mapping its domain concepts to an OpenPath deployment.

Dependency

Blocked by / designed with: #250.

The final Windows .exe must be a release artifact whose bytes and Authenticode signature do not change per deployment. The deployment bundle carries the short-lived enrollment authority outside the PE.

Target artifact

Conceptually:

openpath-windows-deployment.zip
├── OpenPath-Windows-Setup.exe       # immutable signed release artifact
└── openpath-deployment.json         # deployment-specific bootstrap reference

The sidecar must contain an opaque deployment reference, not a long-lived device credential and not a ClassroomPath-specific identifier.

Security invariant

One deployment authority may authorize several initial enrollments, but it must never become the durable credential shared by those devices.

deployment grant
   -> atomic redemption #1 -> device credential A
   -> atomic redemption #2 -> device credential B
   -> ...
   -> redemption #N -> device credential N

The grant is bounded, expiring and revocable. Every successful device gets a distinct durable identity/credential.

Related

• security(windows): ship one immutable Authenticode-signed installer with zero recurring signing cost #250 — fresh immutable Authenticode-signed Windows installer implementation
• refactor(windows): cut over to immutable installer deployments and retire per-request EXE personalization #249 — cutover/removal of per-request EXE personalization after this capability lands
• feat(release): attest the immutable signed Windows installer in the OpenPath promotion contract #251 — fresh promotion-contract migration for the signed installer
• 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
• 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

• ClassroomPath-specific classrooms/tenants/schools
• embedding enrollment secrets into the signed .exe
• one permanent credential shared by multiple endpoints
• unbounded or non-expiring deployment tokens
• making the installer dependent on a wrapper
• replacing normal one-device enrollment where it remains useful

[balejosg]

Implementation spec / planning

This comment is the implementation-ready specification for the generic multi-device deployment capability. Read AGENTS.md completely before implementation. #247 defines the immutable signed executable and external-bootstrap parsing contract; this issue owns the server-side deployment authority, bundle lifecycle, operator workflow and redemption semantics.

1. Product contract

OpenPath standalone must support both a one-device deployment and a batch deployment through the same generic primitive.

Example operator flow:

Classroom -> Enroll -> Windows -> Prepare deployment

number of devices: 30
expiry: bounded choice

Create deployment
  -> Download deployment bundle
  -> copy same bundle to USB/share
  -> install on PC 1..30

The UI should expose progress such as:

7 / 30 enrolled
23 remaining
expires ...
status: active | exhausted | expired | revoked

No code, token or classroom identifier should need to be typed on each endpoint.

2. Scope model

OpenPath already owns classrooms, so the initial deployment may be classroom-scoped:

DeviceDeployment
  id
  classroomId
  createdBy
  maxEnrollments
  successfulEnrollments
  expiresAt
  revokedAt?
  createdAt

Do not add downstream concepts such as organization billing plan, school tenant, ClassroomPath ID, managed-service deployment, etc.

maxEnrollments=1 should be valid so the new primitive can eventually replace the existing one-device personalized-EXE path instead of creating two unrelated enrollment systems.

3. Deployment bearer/reference storage

Treat the deployment reference as a bearer credential with constrained authority.

Required storage invariant:

client/bundle has raw deploymentRef
server DB stores only referenceHash

Do not persist or log the raw reference server-side after creation unless repository-approved encrypted secret storage is genuinely required by the chosen idempotency design. Prefer a design that does not require raw-secret recovery.

The reference authorizes only:

initial endpoint enrollment into its bound OpenPath scope

It must not authorize general classroom administration, policy changes, arbitrary API calls or reads.

4. Bundle schema

Preferred initial sidecar contract:

{
  "schemaVersion": 1,
  "apiUrl": "https://openpath.example.test",
  "deploymentRef": "<opaque bearer>",
  "deploymentExpiresAt": "<ISO-8601>"
}

deploymentExpiresAt is advisory metadata for local UX; the server is authoritative.

Do not include a raw long-lived device credential. Avoid putting classroomId in the sidecar unless the final runtime genuinely requires it; the deployment reference already binds scope server-side.

The JSON contract belongs in @openpath/shared (or the repository's canonical shared-contract location) with strict schema validation and bounded lengths.

5. Bundle artifact

OpenPath generates a deployment-specific ZIP from:

immutable signed release EXE from #247
+
openpath-deployment.json

Required invariant:

sha256(EXE inside bundle A)
== sha256(EXE inside bundle B)
== #247 release installer SHA

Only the JSON sidecar changes between deployments.

The bundle itself contains a bearer credential, so:

• do not place it in public SPA/static storage;
• serve it only to an authorized actor through an authenticated or short-lived protected download path;
• use Cache-Control: no-store;
• never print the raw sidecar/deploymentRef in logs or canary evidence;
• cleanup temporary ZIPs deterministically if ZIPs are materialized on disk.

Prefer streaming/ephemeral bundle construction if that is simpler and avoids a new persistent secret-bearing artifact store, but do not sacrifice deterministic integrity checks.

6. Public API surface

Exact names may follow repository conventions. Conceptually expose supported operations equivalent to:

deviceDeployments.create
  input: classroomId, maxEnrollments, expiresIn
  output: id, status metadata, protected bundle download metadata

deviceDeployments.get
  input: deploymentId
  output: safe status/progress metadata

deviceDeployments.revoke
  input: deploymentId
  output: revoked status

deviceDeployments.list (optional if needed by standalone UX)

The raw deploymentRef should preferably be delivered only inside the protected bundle, not as ordinary JSON that frontend code stores in state/localStorage.

Authorization must reuse the same OpenPath authority that permits endpoint enrollment for the target classroom. Do not create a weaker parallel classroom authorization check.

7. Redemption protocol

The deployment ref must not itself become a device credential.

Required flow:

endpoint reads sidecar
  -> calls OpenPath redemption endpoint
  -> OpenPath validates deployment
  -> atomically reserves one enrollment slot
  -> OpenPath issues/links one endpoint-specific enrollment authority
  -> existing endpoint enrollment completes
  -> reservation finalizes as one successful enrollment
  -> endpoint stores its normal unique durable credential

Critical accounting rule

maxEnrollments counts successfully established distinct endpoint enrollments, not HTTP attempts.

A transient network failure must not permanently burn several seats for one PC.

8. Concurrency and idempotency

30 PCs may start at nearly the same time. Design this as a database concurrency problem, not an in-memory counter.

Required invariants:

successfulEnrollments <= maxEnrollments

under concurrent requests and multi-instance API deployment.

Use transactional/conditional database semantics and a server-visible redemption/reservation record. Do not implement read count -> increment -> write without an atomic guard.

Each endpoint redemption must carry a client-generated high-entropy/idempotency identifier created once and persisted before the first network attempt, e.g. conceptually:

redemptionId = UUID/random 128-bit+

Retries from the same installation must map to the same logical reservation and must not consume another slot.

The implementation may use short-lived reservation leases before final enrollment. If so:

reservation created
  -> lease active
  -> endpoint enrollment succeeds -> finalized
  -> timeout/crash before success -> reservation reclaimable

Do not let abandoned reservations permanently reduce remaining.

9. Revocation/expiry semantics

Required terminal behavior:

unknown/malformed ref -> generic invalid response
expired -> no new redemption
revoked -> no new redemption
exhausted -> no new redemption

Revocation should block new/unfinalized bootstrap attempts. It must not invalidate already enrolled endpoint credentials unless the operator separately revokes those devices through the normal device lifecycle.

Do not reveal whether a guessed raw reference ever existed more precisely than needed by the endpoint protocol.

10. TTL and bounds

Add explicit bounded config/schema constraints for:

maxEnrollments
maximum deployment lifetime
reservation/lease lifetime

Choose repository-appropriate defaults after inspecting existing enrollment TTLs and operational needs. The limits must be finite and covered by tests; do not allow an unbounded multi-use bearer.

The UX for a 30-PC operator should allow a practical window (for example a working day or administrator-selected bounded period), but the implementation should not encode ClassroomPath-specific assumptions.

11. Windows runtime/offline behavior

The installer must remain useful as an offline payload installer even when the network is temporarily unavailable.

Expected behavior:

read/validate deployment sidecar
  -> install bundled OpenPath payloads locally
  -> if API reachable: redeem and enroll
  -> if API unreachable: persist pending bootstrap safely
  -> existing retry mechanism redeems later

Pending local state containing the deployment bearer must be protected using the repository's existing Windows secret-protection approach (for example DPAPI where already used) and must never be written to logs/evidence in plaintext.

Do not delete or mutate the source openpath-deployment.json on a USB/share; the same bundle must remain reusable for the other PCs. Clean only endpoint-local temporary/plaintext copies created by the installer.

12. Interactive and silent deployment

Support both:

operator double-click

and a stable unattended contract conceptually equivalent to:

OpenPath-Windows-Setup.exe /S /EnrollmentFile openpath-deployment.json

Exact switches may follow NSIS conventions. Document and test them.

The interactive installer should auto-detect the well-known sidecar next to the EXE according to #247's precedence rules so a normal operator does not type anything.

13. Standalone OpenPath UI

OpenPath standalone owns the reference UX. Add the Windows enrollment UI needed to:

• choose number of devices;
• create deployment;
• download bundle;
• display safe deployment status/progress;
• revoke an active deployment;
• create a replacement deployment when expired/exhausted;
• retain the appropriate manual/single-device alternative during migration.

A wrapper may replace presentation but should call this same public API.

14. Observability

Use safe structured categories such as:

deployment_create_denied
deployment_invalid
deployment_expired
deployment_revoked
deployment_exhausted
redemption_reserved
redemption_recovered
redemption_finalized
redemption_failed
bundle_unavailable
bundle_integrity_failed

Never log:

raw deploymentRef
sidecar JSON
endpoint durable credential
enrollment token
Authorization/Cookie/JWT

Metrics/status may expose counts and deployment IDs that are not bearer secrets, subject to existing auth rules.

15. Data model and cleanup

Inspect existing DB/migration conventions before choosing exact tables. A likely normalized model is:

device_deployments
  id
  classroom_id
  reference_hash
  max_enrollments
  expires_at
  revoked_at
  created_by
  created_at

device_deployment_redemptions
  deployment_id
  redemption_id
  state (reserved/finalized/...)
  lease_expires_at
  device_id? after success
  created_at
  finalized_at?

Do not store the raw bearer.

Cleanup may remove expired reservation bookkeeping after a bounded retention period, but preserve enough audit/status data according to existing OpenPath retention conventions. Cleanup must not delete an active deployment or break already enrolled endpoints.

16. Core canary

Add a generic OpenPath canary that proves at least:

create deployment max=2
  -> download protected bundle
  -> EXE hash == immutable release/fixture EXE hash
  -> sidecar schema valid (without logging raw ref)
  -> redeem endpoint A -> success
  -> retry endpoint A with same redemptionId -> idempotent, still 1/2
  -> redeem endpoint B -> success, 2/2
  -> redeem endpoint C -> exhausted/rejected
  -> status reports 2/2

Also cover revoke/expiry paths in focused tests.

Canary evidence must contain only safe booleans/counts/hashes/status codes, never raw refs or credentials.

17. Windows E2E

Target-platform E2E must use the same immutable EXE bytes for multiple enrollment cases.

Required evidence ladder:

signed/fixture immutable EXE
  + deployment sidecar
  -> NSIS executes
  -> sidecar parsed
  -> pending state works offline
  -> network retry redeems deployment
  -> unique endpoint credential/state established

For a multi-device E2E, prove two separate endpoint identities are created from one deployment without sharing a durable credential. Do not require 30 real VMs in CI; concurrency/accounting can be covered in API integration tests while Windows E2E proves the physical runtime contract.

18. TDD implementation order

Phase 0 — reconnaissance

1. read AGENTS.md completely;
2. inspect existing enrollment ticket/device-credential lifecycle;
3. inspect DB transaction/migration conventions;
4. inspect current offline pending enrollment/DPAPI retry path;
5. inspect final feat(windows): publish one immutable Authenticode-signed installer per release #247 bootstrap schema and immutable EXE identity;
6. inspect public SPA extension/export rules before adding wrapper-facing UI/API.

Phase 1 — shared schemas + DB model

Write failing validation/migration tests for deployment bounds, reference hashing, status transitions and schema compatibility.

Phase 2 — create/get/revoke service

Implement authorization and safe metadata without bundle generation yet.

Phase 3 — transactional redemption

Write concurrency/idempotency tests first. Prove N+1 concurrent distinct redemptions cannot exceed N and retries of one redemptionId do not consume multiple slots.

Phase 4 — bridge to existing enrollment lifecycle

Reuse existing endpoint enrollment/ticket/credential primitives. Do not invent a second durable device identity model.

Phase 5 — bundle generation/download

Package exact immutable EXE + sidecar and prove EXE hash identity. Add protected download lifecycle and secret-safe cleanup.

Phase 6 — Windows runtime

Consume external bootstrap, pending/offline state and silent install switches. Run focused Windows tests first per repository policy.

Phase 7 — standalone UI

Add deployment creation/progress/revoke UX using public OpenPath APIs.

Phase 8 — canary/docs

Add generic core canary and maintained docs. Then hand off to #249 for legacy cutover/cleanup.

19. Acceptance criteria

• OpenPath can create a bounded classroom-scoped device deployment.
• maxEnrollments=1 and batch values are supported through the same primitive.
• Raw deployment reference is never stored plaintext server-side or logged.
• Deployment reference cannot authorize operations beyond endpoint bootstrap.
• Bundle contains the exact immutable installer from feat(windows): publish one immutable Authenticode-signed installer per release #247 plus a validated sidecar.
• EXE bytes/hash are identical across different deployment bundles for one release.
• Same bundle can enroll multiple PCs up to the configured limit.
• Every endpoint receives a distinct durable credential/identity.
• Concurrent redemption cannot exceed maxEnrollments.
• Retry of one logical endpoint redemption is idempotent and does not burn another seat.
• Abandoned reservations are recoverable and do not permanently consume capacity.
• Expiry, exhaustion and revocation fail closed for new enrollments.
• Revoking a deployment does not revoke already enrolled devices.
• Offline payload installation can persist a protected pending bootstrap and retry later.
• Operator can double-click without entering a code on each PC.
• Silent deployment has a documented stable switch/sidecar contract.
• Standalone OpenPath UI can create/download/observe/revoke deployments.
• Core canary and Windows E2E contain no bearer/enrollment secrets.
• No downstream wrapper concepts are introduced.

20. Completion report

Report:

1. final deployment/sidecar schemas;
2. authorization boundary;
3. DB model and atomic redemption algorithm;
4. idempotency/reservation behavior;
5. expiry/revocation semantics;
6. bundle generation/download behavior;
7. offline pending-state protection;
8. silent/interactive installer contract;
9. standalone UI/API surface;
10. concurrency tests and results;
11. Windows E2E evidence;
12. remaining cleanup handed to refactor(windows): cut over to immutable installer deployments and retire per-request EXE personalization #249.

[balejosg]

Dependency correction

For the implementation spec above, every dependency/reference that treated #247 as the active immutable-installer implementation ticket must be read as #250.

• security(windows): ship one immutable Authenticode-signed installer with zero recurring signing cost #250 is the implementation dependency and source of truth.
• feat(windows): publish one immutable Authenticode-signed installer per release #247 may be consulted only as historical context.
• ClassroomPath downstream work is tracked by the fresh ClassroomPath chore(deps-dev): update typescript-eslint requirement from ^8.20.0 to ^8.57.1 in /firefox-extension #161, not chore(deps): bump dotenv from 16.6.1 to 17.3.1 #158.

No implementation under #248 should wait on, extend, or modify #247 as its delivery contract.

[balejosg]

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

This issue is the deployment-grant/bundle/redemption workstream for that epic. #252 is coordination-only; this issue remains the implementation authority for its scope.