feat(release): attest the immutable signed Windows installer in the OpenPath promotion contract

[balejosg]

Summary

Extend OpenPath release/promotion provenance so downstream consumers receive one authoritative identity for the final immutable Authenticode-signed Windows installer produced by the new Windows distribution path.

This is a fresh implementation ticket. Older promotion-contract issues may be referenced for historical context, but this ticket defines the Windows signed-artifact requirement and migration.

Dependency

Blocked by: #250 — fresh immutable signed Windows installer implementation.

Coordinate final cutover with #249 and deployment bundle consumption with #248.

Required authority

The promotion contract must identify the final signed installer bytes, conceptually:

{
  "sourceSha": "<40-char SHA>",
  "inputsSha256": "<64-char SHA256>",
  "version": "<OpenPath version>",
  "releaseTag": "<exact release tag>",
  "installerAsset": "OpenPath-Windows-Setup.exe",
  "installerSha256": "<SHA256 of final signed bytes>",
  "payloadManifestAsset": "payload-manifest.json",
  "payloadManifestSha256": "<SHA256>"
}

Exact names may follow repository conventions. The normative rule is:

promotion contract Windows SHA = final post-sign executable bytes

Downstream wrappers must not derive a Windows tag/template or independently choose which installer is compatible.

OpenPath-first boundary

OpenPath alone decides Windows artifact compatibility, inheritance, provenance and promotion. No downstream wrapper concept belongs in this schema.

Historical context only

Earlier promotion/template work can inform reconnaissance, including OpenPath #244, but this new ticket owns the signed-installer promotion migration.

Downstream

Fresh ClassroomPath wrapper migration is tracked in ClassroomPath #161.

Non-goals

• downstream release-bundle implementation;
• ClassroomPath-specific metadata;
• mutable latest aliases as authoritative identity;
• silently changing the semantics of an existing incompatible public interface version;
• provider-specific volatile signing transaction IDs inside deterministic contract bytes.

[balejosg]

Implementation spec / plan

Read AGENTS.md completely and inspect the final immutable-signed-installer implementation before changing promotion logic. This ticket is intentionally independent of older promotion issues; use them only as historical evidence.

1. Public contract semantics

The authoritative Windows component must identify the final signed installer, not a mutable template.

Normative rule:

windows artifact identity = exact signed EXE bytes

If the current public interface cannot represent this without changing field meaning, introduce a deliberate schema/interface version bump. Do not silently reinterpret templateSha256 as signed-installer SHA.

2. Deterministic contract

Keep content-addressed/deterministic contract bytes. Do not include volatile signing-provider request IDs, workflow run IDs, timestamps, runner IDs, or certificate timestamp metadata if those would make identical release inputs serialize differently.

Stable publisher policy may be documented separately or represented only if deterministic and contractually useful.

3. Physical verification chain

Before publication, OpenPath must verify the complete chain:

source SHA
-> Windows input fingerprint
-> exact release tag
-> exact release artifact
-> signed EXE bytes
-> Authenticode gate from immutable-installer pipeline
-> final SHA-256
-> promotion contract

The promotion publisher must not accept a pre-sign hash or unsigned template as the authoritative Windows component.

4. Component fingerprint

The Windows inputsSha256 (or equivalent) must cover all repository inputs capable of changing the final executable before signing, including as applicable:

NSIS source
Windows runtime/payload files
browser payloads included in installer
payload manifest generation
bootstrap-reader implementation
build scripts
pinned tool/config inputs

Provider transaction metadata must not pollute the deterministic source-input fingerprint.

5. Inheritance

A later promoted OpenPath SHA may inherit an older immutable signed Windows artifact only when:

current Windows input fingerprint == recorded fingerprint
AND inherited artifact/provenance remains valid

Only OpenPath makes this decision. Downstream wrappers receive the result and must not search ancestors or choose a different installer.

6. Migration

During a bounded compatibility window, legacy template fields may remain if real supported consumers still need them. They must be explicitly compatibility-only and not a second authority.

Final state after migration:

signed installer identity = authoritative
legacy mutable-template identity = removed/non-authoritative

Document the exact removal condition/version.

7. Tests first

Add failing tests for at least:

valid signed-installer component
pre-sign/template hash presented as final -> reject
missing installer asset -> reject
installer SHA mismatch -> reject
unsigned/unverified artifact -> reject
wrong release tag/source SHA -> reject
unsupported old/new interface version -> reject
canonical serialization deterministic -> pass
same fingerprint -> inheritance permitted
different fingerprint -> inheritance prohibited
legacy/new dual authority conflict -> reject

Workflow/repo-contract tests must prevent release YAML from bypassing the signed-artifact verification gate.

8. TDD order

1. inspect final signed-installer publication contract;
2. define/version schema tests;
3. implement signed-installer component parsing/serialization;
4. implement physical final-byte verification;
5. update component fingerprint/inheritance logic;
6. update promotion workflow contract tests;
7. document migration and public interface version;
8. verify downstream can consume exact identity without deriving tags/templates.

9. Acceptance criteria

• Promotion contract identifies exact final signed Windows EXE.
• Recorded SHA hashes post-sign bytes.
• Promotion cannot publish before the signature gate succeeds.
• Public interface semantics are versioned explicitly if incompatible.
• Contract bytes remain deterministic.
• Windows source-input fingerprint is canonical and centrally defined.
• Artifact inheritance is decided only by OpenPath.
• Legacy template fields cannot remain an ambiguous second authority.
• No downstream-specific field is added.
• Downstream consumers can consume one exact installer identity without independent resolution.

10. Completion report

Report final schema/interface version, physical verification chain, fingerprint definition, inheritance behavior, migration of legacy fields, focused tests, workflow contract tests and one redacted example contract.

[balejosg]

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

This issue is the signed-installer promotion/provenance workstream for that epic. #252 is coordination-only; this issue remains the implementation authority for its scope.