ci: require signed release tag flow

Author: bhdicaire

.github/CODEOWNERS

@@ -1,11 +1,10 @@
 # Reference: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
 
-# These owners will be the default owners for everything in
-# the repo. Unless a later match takes precedence,they will
-# be requested for review when someone opens a pull request.
-*       @bhdicaire
+# These owners are the default owners for everything in the repo.
+# Unless a later match takes precedence, they are requested for review
+# when someone opens a pull request.
+*       @bhdicaire @felleg
 
-# In this example, @bhdicaire owns any file in the `/docs`
-# directory and any of its subdirectories.
-/docs/ @bhdicaire
+# Maintainers own documentation changes too.
+/docs/ @bhdicaire @felleg

.github/GOVERNANCE.md

@@ -13,6 +13,10 @@ things simple, transparent, and welcoming.
 Currently, this project is maintained by:
 
 - [Benoît H. Dicaire](https://github.com/bhdicaire)
+- [Felix Leger](https://github.com/felleg)
+
+Trusted release signers are listed in [MAINTAINERS.md](MAINTAINERS.md). Release signers create Sigstore/gitsign tags for
+published `vX.Y.Z` releases.
 
 ## Decision-Making
 
@@ -26,6 +30,9 @@ Currently, this project is maintained by:
 This project is currently maintained by a single individual. If the project grows and consistent contributors emerge,
 they may be invited to join as co-maintainers.
 
+Becoming a release signer is a separate trust decision. Release signers must use phishing-resistant account protection
+and must be added to `.github/release-signers.json` before their release tags are trusted by upgrade tooling.
+
 ## Conflict Resolution
 
 We encourage respectful, constructive discussions. Most discussions and decisions happen publicly on GitHub through

.github/MAINTAINERS.md

@@ -6,6 +6,15 @@ contributions, managing releases, and guiding the overall direction of the proje
 ## Current Maintainer(s)
 
 - [Benoît H. Dicaire](https://github.com/bhdicaire)
+- [Felix Leger](https://github.com/felleg)
+
+## Trusted Release Signer(s)
+
+Release signers are maintainers trusted to create Sigstore/gitsign release tags for `vX.Y.Z` releases. The pinned
+machine-readable signer list lives in [release-signers.json](release-signers.json).
+
+- Benoît H. Dicaire — `code@Dicaire.com`
+- [Felix Leger](https://github.com/felleg) — `felix@felixleger.com`
 
 ## Contact
 

.github/release-signers.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": "1.0",
+  "sigstore": {
+    "certificate_oidc_issuer": "https://github.com/login/oauth",
+    "trusted_certificate_identities": ["code@Dicaire.com", "felix@felixleger.com"]
+  }
+}

.github/workflows/release-please.yml

@@ -17,3 +17,5 @@ jobs:
         with:
           # Standard GITHUB_TOKEN works perfectly for basic setups
           token: ${{ secrets.GITHUB_TOKEN }}
+          # Release tags are created separately by trusted maintainers with Sigstore/gitsign.
+          skip-github-release: true

RELEASE_CHECKLIST.md

@@ -6,6 +6,11 @@ the code-repository activities close to the scripts and generated artifacts they
 ## Before release
 
 - Confirm the worktree only contains intended release changes: `git status --short`
+- Confirm the release signer is listed in `.github/release-signers.json`
+- Confirm Git tag signing uses Sigstore/gitsign:
+  - `git config --get gpg.format` returns `x509`
+  - `git config --get gpg.x509.program` returns `gitsign`
+  - `git config --get tag.gpgsign` returns `true`
 - Review runtime registry schema changes with `docs/adr/`
 - Run `npm run clean`
 - Run `npm run check`
@@ -17,6 +22,17 @@ the code-repository activities close to the scripts and generated artifacts they
 - Confirm `build/v8s.json` includes both `tree` and `links[]`
 - Confirm `src/worker.mjs` is generated from `scripts/workers/`
 
+## Release tag
+
+- Merge the release-please release pull request
+- Pull the clean release commit locally: `git pull`
+- Create the signed release tag: `git tag -s vX.Y.Z -m "vX.Y.Z"`
+- Verify the tag with the signing identity:
+  `gitsign verify --certificate-identity code@Dicaire.com --certificate-oidc-issuer https://github.com/login/oauth vX.Y.Z`
+- Push the tag only after verification: `git push origin vX.Y.Z`
+- Confirm GitHub release tag rules protect `refs/tags/v*` from deletion, updates, and force-pushes, including
+  administrator bypass
+
 ## Runtime smoke checks
 
 - Start local Worker runtime with `npm run dev`

docs/adr/0001-use-release-please-and-semantic-versioning.md

@@ -17,7 +17,12 @@ build, lint, and tests.
 
 ## Decision
 
-Use release-please to automate release pull requests and tags from Conventional Commits.
+Use release-please to automate release pull requests, version bumps, changelog entries, and release notes from
+Conventional Commits.
+
+Release tags are created separately by a trusted maintainer using Sigstore/gitsign, as described in
+[0015. Require signed release tags for trusted upgrades](0015-require-signed-release-tags.md). Release-please is not the
+final release signer.
 
 Use semantic versioning for code releases:
 
@@ -33,7 +38,7 @@ repositories should not publish vanityURLs product releases.
 
 ## Consequences
 
-- Product releases are repeatable and tied to commit intent
+- Product releases are repeatable, tied to commit intent, and signed by a trusted release identity
 - Instance owners can refer to release notes before upgrading
 - Conventional Commits matter for release automation, not just readability
 - Formatting, lint, build, and test automation exist through npm scripts

docs/adr/0004-detach-and-upgrade-product-files.md

@@ -18,6 +18,10 @@ instance.
 `npm run upgrade` refreshes product-owned paths from upstream while protecting instance-owned paths such as `custom/`,
 `wrangler.toml`, `.dev.vars`, and `README.md`.
 
+The upstream ref used for upgrade is a supply-chain trust boundary because upgrade verification can execute synced
+product scripts. Release trust is governed by
+[0015. Require signed release tags for trusted upgrades](0015-require-signed-release-tags.md).
+
 The default upgrade path includes product files such as `defaults/`, `scripts/`, `package.json`, `package-lock.json`,
 `LICENSE`, `.npmrc`, and `.prettierignore`. It does not refresh `README.md`, because `npm run detach` replaces the
 upstream README with the operator-focused instance README.
@@ -42,3 +46,5 @@ defaults can reach existing instances without asking operators to rerun setup or
   diff with the refreshed product files
 - Additive default config fields can ship in `defaults/` and be inherited by existing instances without stored-config
   migrations
+- Upgrade tooling should prefer verified signed release tags over mutable branch refs before executing synced product
+  code

docs/adr/0015-require-signed-release-tags.md

@@ -0,0 +1,80 @@
+# 0015. Require signed release tags for trusted upgrades
+
+Date: 2026-06-04
+
+Status: Accepted
+
+## Context
+
+Instance operators refresh product-owned files with `npm run upgrade`. The upgrade process fetches an upstream Git ref,
+syncs product files such as `defaults/`, `scripts/`, and `package.json`, then can run build, test, and doctor commands
+from the synced product code.
+
+That means an upgrade ref is a supply-chain trust boundary. If the default ref is a mutable branch such as `main`, or if
+an unsigned release tag can be moved or recreated, a compromised upstream account or workflow could cause an instance
+operator to execute unreviewed upstream code during upgrade verification.
+
+Release signatures do not prove that the code is safe. They prove that a trusted release identity authorized the Git
+object being consumed. That is still valuable: it raises the cost of compromise, gives operators a stable provenance
+check before execution, and makes unauthorized or disputed release publication easier to detect.
+
+## Decision
+
+Use release-please to prepare release pull requests, version bumps, changelog entries, and release notes. Do not treat
+release-please as the final release signer.
+
+After the release pull request is merged, a trusted maintainer creates and pushes the release tag with Sigstore/gitsign.
+Release tags use the `vX.Y.Z` format.
+
+Trusted release signatures are Sigstore/gitsign signatures whose certificate identity is one of the pinned release
+signer identities in `.github/release-signers.json`, and whose certificate OIDC issuer is
+`https://github.com/login/oauth`.
+
+The initial trusted release signers are:
+
+- `code@Dicaire.com`
+- `felix@felixleger.com`
+
+Protect release tags with GitHub tag rules for `refs/tags/v*`:
+
+- block tag deletion
+- block tag updates and force-pushes
+- require the release tag to be created by a trusted maintainer
+- include administrators in the rules and avoid bypass actors
+
+Future upgrade hardening should make `npm run upgrade` default to the latest verified release tag instead of `main`,
+support explicit `--ref vX.Y.Z` pinning, warn on mutable branch refs, verify the selected release tag before extracting
+or executing product files, and document `--no-check` as the high-assurance "sync, review, then run checks" path.
+
+## Release Tag Procedure
+
+Configure gitsign for tag signing:
+
+```sh
+git config --global gpg.format x509
+git config --global gpg.x509.program gitsign
+git config --global tag.gpgsign true
+```
+
+After the release pull request has merged and `main` is clean:
+
+```sh
+git pull
+git tag -s vX.Y.Z -m "vX.Y.Z"
+gitsign verify --certificate-identity code@Dicaire.com --certificate-oidc-issuer https://github.com/login/oauth vX.Y.Z
+git push origin vX.Y.Z
+```
+
+Use the signer identity that matches the maintainer creating the release. A second trusted signer may independently
+verify the pushed tag.
+
+## Consequences
+
+- Operators have a concrete provenance check before upgrade verification executes upstream product code.
+- Release publication depends on trusted maintainer identity rather than only GitHub workflow authority.
+- A compromised mutable branch is no longer an acceptable default upgrade source.
+- A compromised maintainer account can still sign a malicious release if its identity controls are defeated; this model
+  is provenance and detection, not an anti-tamper guarantee.
+- GitHub tag protection becomes part of release operations. Some controls must be applied through GitHub repository or
+  organization settings, or through the GitHub API with administrative credentials.
+- Future SLSA provenance can add build-process guarantees beyond tag identity.

scripts/workers/worker.test.mjs

@@ -292,6 +292,26 @@ function base64UrlBytes(bytes) {
   return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/g, "");
 }
 
+function corruptJwtSignature(token) {
+  const parts = token.split(".");
+  const signature = base64UrlToBytesForTest(parts[2]);
+  signature[0] = signature[0] ^ 0xff;
+  return `${parts[0]}.${parts[1]}.${base64UrlBytes(signature)}`;
+}
+
+function base64UrlToBytesForTest(value) {
+  const normalized = value.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+
+  return bytes;
+}
+
 function request(path, init = {}) {
   return new Request(new URL(path, "https://dicai.re"), {
     ...init,
@@ -735,7 +755,7 @@ await run("rejects Cloudflare Access tokens with invalid JWT headers or signatur
   const missingKid = await signAccessJwt(fixture, { header: { kid: "" } });
   const wrongAlgorithm = await signAccessJwt(fixture, { header: { alg: "HS256" } });
   const valid = await signAccessJwt(fixture);
-  const invalidSignature = `${valid.slice(0, -1)}${valid.endsWith("A") ? "B" : "A"}`;
+  const invalidSignature = corruptJwtSignature(valid);
 
   for (const [name, token] of [
     ["missing kid", missingKid],