security(windows): ship one immutable Authenticode-signed installer with zero recurring signing cost

[balejosg]

Summary

Introduce a fresh canonical Windows distribution path in OpenPath where each release publishes one immutable Authenticode-signed installer whose bytes never change per classroom, deployment, wrapper, or download.

Target invariant:

same OpenPath release
-> same OpenPath-Windows-Setup.exe bytes
-> same SHA-256
-> same Authenticode signature
-> no runtime PE mutation

The signing solution must preserve the project's requirement of 0 EUR recurring service cost. Preferred implementation path: a free OSS signing program such as SignPath Foundation, subject to eligibility/approval. Signing occurs in the release pipeline, never per API request.

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

OpenPath-first boundary

Per AGENTS.md:

wrapper -> OpenPath

OpenPath owns the signed installer artifact, external bootstrap contract, signature/provenance verification, release publication, Windows E2E and maintained docs. No ClassroomPath-specific concepts belong here.

Required architecture

The installer must consume deployment/enrollment context outside the signed PE bytes through a generic OpenPath bootstrap mechanism, e.g. a sidecar supplied next to the executable or an explicit installer argument.

Conceptually:

build immutable installer
-> Authenticode sign
-> verify expected publisher/signature
-> SHA-256 final signed bytes
-> publish immutable artifact + provenance

No file writes are allowed after the signature is applied.

Zero-cost constraint

Do not introduce a paid per-signature/runtime signing service under this issue. If the preferred free OSS signing provider is unavailable or the project is ineligible, fail the implementation decision explicitly rather than silently adding a recurring paid dependency.

Historical context only

Relevant earlier work may help with reconnaissance, including OpenPath #242/#247 and the existing Windows offline-installer implementation, but this ticket defines the new target architecture.

Non-goals

• per-request Authenticode signing;
• self-signed certificates as a public SmartScreen solution;
• embedding classroom/deployment secrets in the signed EXE;
• claiming SmartScreen warnings disappear immediately after first release;
• downstream wrapper UX;
• multi-device deployment accounting (tracked separately).

[balejosg]

Implementation spec / plan

This comment is the implementation-ready contract for this ticket. Read AGENTS.md completely before changing code. Older issues may be consulted for history, but do not inherit their target architecture automatically.

1. Release artifact contract

The canonical Windows artifact must be a final signed executable, not a mutable template:

OpenPath-Windows-Setup.exe

Required invariant for one release:

all downloads -> exact same bytes
all deployments -> exact same SHA-256
all wrappers -> exact same Authenticode signature

The PE must not contain classroom ID, deployment token, enrollment token, API-specific secret, or wrapper-specific data.

2. External bootstrap contract

Add a generic bootstrap input owned by OpenPath. Prefer a strict shared schema, e.g. in @openpath/shared, for a sidecar/argument contract such as:

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

Exact fields may follow the final deployment design, but the immutable EXE must be able to:

• auto-detect a well-known sidecar next to itself for operator double-click UX;
• accept an explicit path/switch for unattended deployment;
• validate schema strictly;
• avoid logging raw bootstrap credentials;
• persist pending bootstrap securely when installation succeeds offline but enrollment must retry later.

Do not encode ClassroomPath semantics in the schema.

3. Signing provider boundary

Introduce a small release-signing integration boundary rather than scattering provider commands through YAML. The release pipeline must be able to prove:

unsigned build artifact
-> signing request
-> signed artifact returned/produced
-> Authenticode validation succeeds
-> expected publisher identity matches

The implementation should prefer SignPath Foundation or another genuinely zero-recurring-cost OSS signing path. Provider-specific credentials/configuration must remain outside the repository and must not be copied into runtime containers.

If provider onboarding is external/manual, document the prerequisite clearly and keep CI fail-closed when signing is required but unavailable.

4. Signing order

Normative order:

compile NSIS
-> assemble all immutable payload/trailer/bootstrap-reading code
-> final binary bytes
-> Authenticode sign
-> verify signature/publisher
-> calculate SHA-256 of signed bytes
-> publish

Never:

sign
-> append/overlay/mutate bytes

No operation after signing may modify the published executable.

5. Authenticode verification

On Windows CI, validate at minimum:

Get-AuthenticodeSignature <exe>

and/or signtool verify /pa where available.

Acceptance must check more than Status=Valid: assert the expected publisher/certificate identity according to the chosen provider contract.

Add a negative tamper test:

signed EXE
-> modify one covered byte
-> verification fails

Also prove the external bootstrap is not part of the signed EXE: different sidecars must leave EXE hash/signature unchanged.

6. SmartScreen scope

Do not encode a false acceptance criterion such as “SmartScreen never warns”. The guarantee is:

• valid stable Authenticode publisher identity;
• immutable release hash that can accumulate reputation;
• no per-classroom hash churn.

New publisher/file reputation may still require time to establish.

7. Release workflow

Inspect .github/workflows/release-scripts.yml and existing Windows E2E before editing. Reuse existing build/payload/NSIS paths; do not create a second installer builder.

The Windows release job should produce safe evidence containing at least:

source SHA
OpenPath version
signed installer SHA-256
signature valid boolean
expected publisher matched boolean
payload/runtime E2E result

Do not put signing secrets, provider tokens, bootstrap refs, or certificate private material in evidence.

8. Windows E2E

Retain physical target-platform evidence. Add/update E2E proving:

same immutable signed EXE
+ bootstrap sidecar A
-> installs and consumes A

same exact EXE bytes
+ bootstrap sidecar B
-> installs and consumes B

Assert the EXE SHA is identical in both cases.

The runtime should still support offline payload staging and protected pending enrollment/retry.

9. API/runtime boundary

Do not make the OpenPath API sign binaries or mutate PE bytes. Runtime responsibilities should move toward delivering/referenceing the immutable release executable and creating deployment bootstrap data (the latter belongs to the deployment ticket).

Do not remove the old personalized path in this ticket unless that removal is necessary to make the signed artifact testable; final cutover/cleanup is tracked separately.

10. TDD implementation order

Phase 0 — reconnaissance

1. read AGENTS.md;
2. inspect release-scripts.yml;
3. inspect NSIS source and current trailer/overlay reader;
4. inspect Windows physical installer E2E;
5. inspect final executable publication/tag/provenance path;
6. document the selected zero-cost signing provider prerequisites.

Phase 1 — external bootstrap schema/runtime

Write failing schema/parser/precedence tests before changing NSIS/runtime behavior.

Phase 2 — immutable build

Prove the executable no longer requires deployment-specific PE mutation for the new path.

Phase 3 — signing integration

Add fail-closed signing and signature-verification gates.

Phase 4 — final-byte provenance

Compute SHA only after signing and publish the exact signed bytes + sidecar/provenance required by repository conventions.

Phase 5 — Windows E2E

Prove two bootstrap contexts use identical signed EXE bytes.

Phase 6 — docs

Document immutable artifact, zero-cost signing prerequisite, bootstrap contract, validation and wrapper-facing implications.

11. Acceptance criteria

• One OpenPath release produces one canonical signed Windows EXE.
• Final EXE contains no deployment/classroom credential.
• External bootstrap contract is generic and versioned.
• Different deployments do not change EXE bytes/SHA/signature.
• Signing has 0 EUR recurring service cost under the selected supported path.
• No private signing key/PFX is stored in repo, image, DB or runtime config.
• Signature is applied after all executable-byte mutations.
• Final SHA-256 is calculated after signing.
• Windows CI verifies valid signature and expected publisher identity.
• Tampering invalidates signature.
• Physical Windows E2E proves bootstrap A/B with the exact same EXE hash.
• Offline pending enrollment remains protected and retryable.
• Release evidence contains no signing/bootstrap secrets.
• No downstream wrapper concept is added.

12. Completion report

Report:

1. selected signing provider and zero-cost eligibility/prerequisites;
2. final bootstrap schema and precedence rules;
3. exact signing/verification commands or integration boundary;
4. publisher identity assertion;
5. signed installer SHA/provenance publication;
6. Windows E2E evidence;
7. files changed;
8. focused tests and repository verification results;
9. any remaining legacy personalized path handed to the cutover ticket.

[balejosg]

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

This issue is the signing/immutable-binary workstream for that epic. #252 is coordination-only; this issue remains the implementation authority for its scope.