Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ jobs:
- 'scripts/collect-windows-defender-evidence*.ps1'
- 'scripts/verify-windows-signatures.ps1'
- 'scripts/verify-windows-signatures.test.ps1'
- 'scripts/validate-windows-signing-config*.ps1'
- 'Makefile'
- '.github/workflows/*.yml'
homebrew:
Expand All @@ -65,7 +66,7 @@ jobs:
package-manager-cache: false
- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm audit --audit-level high
- run: pnpm audit --audit-level low
- run: pnpm validate:ids
- run: pnpm typecheck
- run: pnpm test
Expand Down Expand Up @@ -294,6 +295,10 @@ jobs:
if: runner.os == 'macOS'
run: |
set -euo pipefail
# Trust this checkout's cask on Homebrew versions that require it.
if brew command trust >/dev/null 2>&1; then
brew trust --cask dantraynor/tailchrome/tailchrome
fi
brew style --cask dantraynor/tailchrome/tailchrome
brew info --cask --json=v2 dantraynor/tailchrome/tailchrome
brew fetch --cask dantraynor/tailchrome/tailchrome
Expand Down Expand Up @@ -406,6 +411,9 @@ jobs:
WINDOWS_SIGNTOOL_PATH: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe
steps:
- uses: actions/checkout@v5
- name: Test production signing configuration
shell: pwsh
run: .\scripts\validate-windows-signing-config.test.ps1
- uses: actions/setup-dotnet@v5
with:
dotnet-version: "8.0.x"
Expand Down
130 changes: 107 additions & 23 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,11 @@ concurrency:
# APPLE_API_KEY_ID - App Store Connect API key ID
# APPLE_API_ISSUER_ID - App Store Connect API issuer UUID
# APPLE_API_KEY_P8 - contents of the AuthKey_*.p8 file
# SIGNPATH_API_TOKEN - submitter for tailchrome/release-signing
#
# Signed Windows candidate creation remains blocked until one signing provider
# and the exact WINDOWS_EXPECTED_SIGNER_SUBJECT repository variable are
# recorded. The only alternative is the explicit unsigned mode: setting the
# Signed Windows candidates use SignPath's fixed release-signing policy.
# SIGNPATH_ORGANIZATION_ID and the exact WINDOWS_EXPECTED_SIGNER_SUBJECT must
# identify the approved production certificate. In explicit unsigned mode, setting the
# WINDOWS_ALLOW_UNSIGNED_RELEASE repository variable to "true" ships the raw
# EXE and MSI without Authenticode signatures, and records that choice in the
# candidate metadata. Both signing modes require clean Defender evidence.
Expand All @@ -49,6 +50,7 @@ jobs:
runs-on: ubuntu-latest
outputs:
source_sha: ${{ steps.source.outputs.source_sha }}
windows_artifact_id: ${{ steps.upload-windows-executables.outputs.artifact-id }}
env:
RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.ref_name }}
steps:
Expand Down Expand Up @@ -110,6 +112,17 @@ jobs:
unzip -q packages/extension/.output/firefox.zip -d "$rebuilt_dir"
diff -qr "$original_dir" "$rebuilt_dir"
popd >/dev/null
- name: Upload Windows EXEs for production signing
id: upload-windows-executables
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE != 'true'
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: windows-unsigned-executables
retention-days: 7
if-no-files-found: error
path: |
dist/tailscale-browser-ext-windows-amd64.exe
dist/tailscale-browser-ext-windows-arm64.exe
- name: Upload reviewed build outputs
uses: actions/upload-artifact@v6
with:
Expand Down Expand Up @@ -440,6 +453,10 @@ jobs:
package-windows:
needs: build
runs-on: windows-2025
timeout-minutes: 90
permissions:
actions: read
contents: read
outputs:
artifact_id: ${{ steps.upload-windows.outputs.artifact-id }}
artifact_digest: ${{ steps.upload-windows.outputs.artifact-digest }}
Expand All @@ -451,6 +468,7 @@ jobs:
WINDOWS_SIGNTOOL_PATH: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe
WINDOWS_EXPECTED_SIGNER_SUBJECT: ${{ vars.WINDOWS_EXPECTED_SIGNER_SUBJECT }}
WINDOWS_ALLOW_UNSIGNED_RELEASE: ${{ vars.WINDOWS_ALLOW_UNSIGNED_RELEASE }}
SIGNPATH_ORGANIZATION_ID: ${{ vars.SIGNPATH_ORGANIZATION_ID }}
steps:
- uses: actions/checkout@v5
with:
Expand All @@ -460,32 +478,30 @@ jobs:
with:
dotnet-version: "8.0.x"
- name: Require Windows release signing configuration
env:
SIGNPATH_API_TOKEN: ${{ secrets.SIGNPATH_API_TOKEN }}
shell: pwsh
run: |
if ($env:WINDOWS_ALLOW_UNSIGNED_RELEASE -eq 'true') {
if (-not [string]::IsNullOrWhiteSpace($env:WINDOWS_EXPECTED_SIGNER_SUBJECT)) {
throw "WINDOWS_ALLOW_UNSIGNED_RELEASE cannot be combined with WINDOWS_EXPECTED_SIGNER_SUBJECT; remove one."
}
Write-Warning "WINDOWS_ALLOW_UNSIGNED_RELEASE is enabled: this candidate ships UNSIGNED Windows binaries."
} else {
if ([string]::IsNullOrWhiteSpace($env:WINDOWS_EXPECTED_SIGNER_SUBJECT)) {
throw "WINDOWS_EXPECTED_SIGNER_SUBJECT must contain the exact selected publisher subject."
}
if (-not (Test-Path -LiteralPath $env:WINDOWS_SIGNTOOL_PATH -PathType Leaf)) {
throw "Expected SignTool was not found at $env:WINDOWS_SIGNTOOL_PATH"
}
}
run: .\scripts\validate-windows-signing-config.ps1
- name: Download reviewed build outputs
uses: actions/download-artifact@v6
with:
name: build-output
- name: Install WiX
run: dotnet tool install --global wix --version 6.0.2
# Provider integration gate (signed mode): the selected provider must
# place timestamped amd64 and ARM64 raw EXEs in signed-windows before MSI
# construction, then sign the unsigned MSI to the final filename before
# verification. Unsigned mode stages both reviewed raw EXEs directly and
# builds the x64-only MSI without any signature validation.
- name: Submit Windows EXEs for production signing
id: sign-executables
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE != 'true'
uses: signpath/github-action-submit-signing-request@f6d04783b4569d051e0c80105fe66e82819d0092 # v3
with:
api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
organization-id: ${{ env.SIGNPATH_ORGANIZATION_ID }}
project-slug: tailchrome
signing-policy-slug: release-signing
artifact-configuration-slug: windows-executables
github-artifact-id: ${{ needs.build.outputs.windows_artifact_id }}
wait-for-completion: true
wait-for-completion-timeout-in-seconds: 1800
output-artifact-directory: signed-windows
- name: Stage unsigned helper
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE == 'true'
shell: pwsh
Expand All @@ -508,7 +524,7 @@ jobs:
.\packaging\windows\build-msi.ps1 `
-Version "$env:RELEASE_TAG" `
-HelperExe $signedExe `
-OutPath .\signed-windows\tailchrome-helper-windows-x64.unsigned.msi `
-OutPath .\unsigned-msi\tailchrome-helper-windows-x64.msi `
-ExpectedSignerSubject "$env:WINDOWS_EXPECTED_SIGNER_SUBJECT" `
-SignToolPath "$env:WINDOWS_SIGNTOOL_PATH"
- name: Require provider-signed ARM64 helper
Expand All @@ -519,6 +535,36 @@ jobs:
if (-not (Test-Path -LiteralPath $signedArm64 -PathType Leaf)) {
throw "The selected signing provider must produce the timestamped ARM64 raw EXE before candidate assembly."
}
- name: Upload outer MSI for production signing
id: upload-unsigned-msi
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE != 'true'
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: windows-unsigned-msi
retention-days: 7
if-no-files-found: error
path: unsigned-msi/tailchrome-helper-windows-x64.msi
- name: Submit outer MSI for production signing
id: sign-msi
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE != 'true'
uses: signpath/github-action-submit-signing-request@f6d04783b4569d051e0c80105fe66e82819d0092 # v3
with:
api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
organization-id: ${{ env.SIGNPATH_ORGANIZATION_ID }}
project-slug: tailchrome
signing-policy-slug: release-signing
artifact-configuration-slug: windows-msi
github-artifact-id: ${{ steps.upload-unsigned-msi.outputs.artifact-id }}
wait-for-completion: true
wait-for-completion-timeout-in-seconds: 1800
output-artifact-directory: signed-msi
- name: Stage the production-signed MSI
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE != 'true'
shell: pwsh
run: |
Copy-Item `
-LiteralPath .\signed-msi\tailchrome-helper-windows-x64.msi `
-Destination .\signed-windows\tailchrome-helper-windows-x64.msi
- name: Build Windows MSI from the unsigned helper
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE == 'true'
shell: pwsh
Expand Down Expand Up @@ -593,6 +639,44 @@ jobs:
"raw_sha256=$rawHash" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
"arm64_sha256=$arm64Hash" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
"msi_sha256=$msiHash" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
- name: Record production signing provenance
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE != 'true'
shell: pwsh
env:
SOURCE_SHA: ${{ needs.build.outputs.source_sha }}
EXE_SIGNING_REQUEST_ID: ${{ steps.sign-executables.outputs.signing-request-id }}
MSI_SIGNING_REQUEST_ID: ${{ steps.sign-msi.outputs.signing-request-id }}
run: |
foreach ($requestId in @($env:EXE_SIGNING_REQUEST_ID, $env:MSI_SIGNING_REQUEST_ID)) {
$parsed = [Guid]::Empty
if (-not [Guid]::TryParseExact($requestId, "D", [ref]$parsed) -or $parsed -eq [Guid]::Empty) {
throw "SignPath did not report a production signing request ID."
}
}
New-Item -ItemType Directory -Force -Path .\signpath-evidence | Out-Null
[ordered]@{
schemaVersion = 1
sourceSha = $env:SOURCE_SHA
releaseTag = $env:RELEASE_TAG
runUrl = "https://github.com/$env:GITHUB_REPOSITORY/actions/runs/$env:GITHUB_RUN_ID"
runAttempt = $env:GITHUB_RUN_ATTEMPT
organizationId = $env:SIGNPATH_ORGANIZATION_ID
projectSlug = "tailchrome"
signingPolicySlug = "release-signing"
expectedSignerSubject = $env:WINDOWS_EXPECTED_SIGNER_SUBJECT
executableSigningRequestId = $env:EXE_SIGNING_REQUEST_ID
msiSigningRequestId = $env:MSI_SIGNING_REQUEST_ID
signatures = Get-Content .\signed-windows\windows-signature-verification.json -Raw | ConvertFrom-Json
} | ConvertTo-Json -Depth 8 |
Set-Content .\signpath-evidence\signpath-release.json -Encoding utf8NoBOM
- name: Preserve production signing evidence
if: vars.WINDOWS_ALLOW_UNSIGNED_RELEASE != 'true'
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: windows-signpath-signing
retention-days: 90
if-no-files-found: error
path: signpath-evidence/signpath-release.json
- name: Upload final Windows bundle
id: upload-windows
uses: actions/upload-artifact@v6
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ irm https://github.com/dantraynor/tailchrome/releases/latest/download/tailchrome

## Windows code signing

SignPath Foundation accepted Tailchrome for Windows Authenticode signing. [Test signing](https://github.com/dantraynor/tailchrome/actions/runs/37815038448) passed; production certificate issuance and signed release integration are still pending. Windows releases stay explicitly unsigned until that work ships. See the [Windows code-signing policy](docs/WINDOWS_CODE_SIGNING_POLICY.md) and [SignPath setup notes](docs/signpath-setup.md).
SignPath Foundation accepted Tailchrome for Windows Authenticode signing. [Test signing](https://github.com/dantraynor/tailchrome/actions/runs/37815038448) passed, and the release workflow supports its separate production policy. Production certificate and publisher approval are still pending; v0.1.15's Windows artifacts are explicitly unsigned. Signing identifies the publisher but does not guarantee immediate SmartScreen reputation. See the [Windows code-signing policy](docs/WINDOWS_CODE_SIGNING_POLICY.md) and [SignPath setup notes](docs/signpath-setup.md).

For releases signed through the SignPath Foundation program:

Expand Down
9 changes: 6 additions & 3 deletions docs/DOCUMENTATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -1008,13 +1008,13 @@ immutable SHA in every downstream checkout. It:
4. **Verifies Firefox source ZIP**: extracts sources, rebuilds from scratch, `diff -qr` against original to ensure reproducibility
5. Signs/notarizes the macOS binaries, app, and package and verifies every layer
6. Builds and inspects Linux `.deb`/`.rpm` packages and includes the Unix and PowerShell bootstraps
7. In signed mode, verifies both raw Windows EXEs, the outer x64 MSI, and its embedded amd64 EXE against the configured signing policy; explicit unsigned mode records its exception
7. In signed mode, signs both Windows EXEs through SignPath `tailchrome` / `release-signing`, builds the x64 MSI from the signed amd64 EXE, signs the outer MSI, and verifies all four signature surfaces; explicit unsigned mode records its exception
8. Requires native ARM64 runtime evidence and Defender evidence for both raw Windows EXEs and the MSI in both signing modes
9. Assembles the complete allowlisted matrix, generates `SHA256SUMS.txt` only after final signing/packaging, creates build-provenance attestations, and stores the immutable candidate for 90 days

The candidate workflow has no release-write permission and never publishes
assets. The currently documented external Windows signer selection and
publisher subject are intentionally fail-closed; see
assets. Production signing requires the approved SignPath certificate, exact
publisher subject, trusted-build policy, and explicit request approvals; see
[WINDOWS_CODE_SIGNING_POLICY.md](WINDOWS_CODE_SIGNING_POLICY.md).

### Helper publication (`publish-helper-release.yml`) -- Manual Dispatch Only
Expand All @@ -1035,6 +1035,9 @@ candidate manifest digest. Defender/Malwarebytes findings apply only to those
exact hashes; an ordinary SmartScreen unknown-reputation warning is tracked
separately from a malware or PUA detection. The complete operator procedure and
asset matrix are in [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md).
The separate [browser-download test](windows-smartscreen-validation.md)
preserves Mark of the Web and exercises Explorer launch on Windows 11;
signature verification and direct installation do not establish that result.

### Publish (`publish.yml`) -- Manual Dispatch Only

Expand Down
11 changes: 9 additions & 2 deletions docs/RELEASE_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@ not apply.

> **Unsigned Windows mode.** When the `WINDOWS_ALLOW_UNSIGNED_RELEASE`
> repository variable is `true` (see the code-signing policy), the
> signing-provider and `WINDOWS_EXPECTED_SIGNER_SUBJECT` items below do not
> apply. Defender-environment, controlled-runner, and exact-hash Windows
> signing-provider, production-signature, signing-evidence, acknowledgement,
> and `WINDOWS_EXPECTED_SIGNER_SUBJECT` items below do not apply.
> Defender-environment, controlled-runner, and exact-hash Windows
> security clearance requirements still apply. Candidate metadata must record
> `windowsSigning: unsigned`, the release notes must state that the Windows
> binaries are unsigned, and every other item still applies.
Expand All @@ -27,6 +28,8 @@ not apply.
- [ ] The Windows code-signing policy records exactly one selected provider and one exact expected signer subject.
- [ ] The selected Windows provider has produced a successful test signature through the repository workflow.
- [ ] `WINDOWS_EXPECTED_SIGNER_SUBJECT` exactly matches the documented subject.
- [ ] SignPath `tailchrome` / `release-signing` uses the production certificate, requires trusted GitHub builds and explicit maintainer approval, and permits the CI token to submit without approval rights.
- [ ] Signed release notes include: `Free code signing provided by SignPath.io, certificate by SignPath Foundation`.
- [ ] The protected `windows-defender-validation` environment requires review, prevents administrator bypass, permits only `v*` tags, and records the approved snapshot in `WINDOWS_DEFENDER_IMAGE_ID`; no repository- or organization-scoped variable uses that name.
- [ ] A clean x64 Windows VM is registered only to this repository with `--ephemeral` and the run-specific `self-hosted`, `Windows`, `X64`, and `tailchrome-defender-<run-id>` labels.
- [ ] The VM's host-owned pre-job hook permits only the approved repository, workflow, job, run ID, tag, and source SHA and verifies `TAILCHROME_DEFENDER_IMAGE_ID` against the approved snapshot; the VM has no signing credentials or internal-network access.
Expand Down Expand Up @@ -72,6 +75,7 @@ not apply.
- [ ] The MSI-embedded EXE has the same signature requirements and SHA-256 as the raw EXE.
- [ ] The outer MSI has one valid SHA-256 Authenticode signature, a timestamp, and the same expected subject.
- [ ] The fixed Windows SDK SignTool and `Get-AuthenticodeSignature` both accept all four Windows signature surfaces.
- [ ] The `windows-signpath-signing` evidence identifies both approved production requests, this run/attempt and source commit, and the final signature report; archive it with the clearance evidence.

## Exact-hash Windows security clearance

Expand Down Expand Up @@ -101,6 +105,8 @@ publication approval.
- [ ] Repair or reinstall succeeded.
- [ ] Uninstall removed only registrations and executables owned by that installation; node state was preserved.
- [ ] No malware, PUA, or behavioral detection occurred.
- [ ] The [browser-download and Explorer procedure](windows-smartscreen-validation.md) records the exact MSI hash, source URL, browser, Windows build/account context, `ZoneId=3`, protection/policy state, screenshots, available buttons, and installer launch result.
- [ ] An unpublished candidate's download origin is recorded accurately; any untested public download route remains explicitly outstanding.
- [ ] Any ordinary signed SmartScreen unknown-reputation prompt is recorded for release notes or support, but is not described as malware.

If either scanner reports malware, PUA, or suspicious behavior, stop. Record the exact hash, detection name, definition version, vendor submission reference, determination, and same-hash retest. Do not approve publication while a determination is pending. A rebuild creates a new candidate and restarts every security check.
Expand All @@ -118,6 +124,7 @@ If either scanner reports malware, PUA, or suspicious behavior, stop. Record the
- [ ] No asset was overwritten with `--clobber`.
- [ ] The complete draft was downloaded and byte-compared with the candidate.
- [ ] The draft was made public only by the final publication step.
- [ ] The public MSI download was repeated through the browser and Explorer with its hash and Internet-zone marker rechecked; any prompt or block is recorded without changing the published assets.

If the candidate artifact expires, or any file or digest differs, create a new candidate and repeat this checklist. Never rebuild, resign, repackage, regenerate checksums, or replace assets after clearance.

Expand Down
Loading
Loading