chore(release): define 1.8.12 publication gates

docs/1.8.12-RELEASE-PLAN.md

@@ -0,0 +1,242 @@
+# Archipelago 1.8.12-alpha Release Plan
+
+**Target date:** 2026-09-11
+**Scope:** OTA, signed app registry, canonical Nostr source publication,
+Companion 0.5.32 alpha, and an x86_64 installer ISO
+**Candidate base:** `f5c0ba85` plus the release-preparation changes documented
+here
+
+## Release Outcome
+
+This release is complete only when all of the following are true:
+
+1. Existing nodes can install the signed OTA and retain AIUI, app data, app
+   manifests, Nostr identities, Lightning state, and network configuration.
+2. A fresh ISO installation boots, reports `1.8.12-alpha`, and serves the same
+   dashboard/runtime payload as the OTA.
+3. The signed app registry contains GitWorkshop, its embedded manifest, and the
+   registry-owned Source promotion.
+4. Archipelago's canonical repository is announced by
+   `npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg` as the
+   stable identifier `archy`, is cloneable through `nostr://`, and opens in
+   GitWorkshop from the Source promotion.
+5. Contributors can create an issue or proposal without gaining canonical
+   merge, release-tag, catalog-signing, or OTA-signing authority.
+
+Shipping GitWorkshop alone does not satisfy item 4. The client is the interface;
+the signed NIP-34 announcement and reachable Git object servers are the source
+publication.
+
+## Audited Candidate State
+
+### Ready
+
+- The accumulated candidate is committed and the development node is healthy.
+- GitWorkshop is healthy behind the authenticated same-origin app gate.
+- The app works as a top-level Companion WebView and as a browser tab; the node
+  signer remains consent-gated and identity-switchable.
+- The Source icon, description, banner, Popular/All Apps placement, and
+  maintainer npub are present in the development catalog.
+- Payment receipts, Minibits claim persistence, update cancellation, app
+  credential interstitials, Gitea limits, certificate guidance, and the pasta
+  listener repair are included in the candidate.
+- `ngit 2.6.3` and `git-remote-nostr 2.6.3` are installed on the node.
+- The existing public Gitea source and Smart HTTP clone endpoints respond with
+  HTTP 200.
+- The release-root signer exists locally as a binary, while its mnemonic
+  remains correctly offline.
+- ISO dependencies (`xorriso`, `mksquashfs`, and QEMU) are installed.
+- The corrected release gate passed on 2026-09-11: 1,091 frontend tests,
+  production UI build, registry candidate/trust checks, Rust check, 114 focused
+  backend tests plus orchestration, and live dashboard/AIUI/RPC probes. Android
+  lint and the mobile Chromium signer-handoff regression also pass.
+- The locally served Companion candidate is 28,157,847 bytes with SHA-256
+  `30e0b6257f17bb5e072941ccce6fde04b6c8ae59a49b45169e1920aec1b108cf`.
+- The owner accepted the risk of redistributing the pinned, unlicensed
+  GitWorkshop revision on 2026-09-11. `NOTICE` and `UPSTREAM.md` disclose that
+  decision without claiming an upstream license.
+
+### Not Yet Complete
+
+- This checkout is not logged into `ngit` and has no Nostr repository remote or
+  cached kind `30617` announcement.
+- The production signed catalog still contains 61 apps but not
+  `archipelago-source` or `storefront`; a freshly generated candidate contains
+  62 apps, 61 embedded manifests, GitWorkshop 0.4.0, and the Source promotion.
+- The previous public Companion download was 0.5.28-debug. A 0.5.32-debug
+  candidate has now been built with the same certificate and can update that
+  alpha channel; the accepted 0.5.32-uat build remains a separate package.
+- The shared debug certificate is intentionally public and its private key is
+  reachable in an existing public Git branch. It provides upgrade continuity,
+  not production authenticity. A future production Companion must use the
+  `com.archipelago.app` package with a privately held release key.
+- The pinned GitWorkshop revision has 4 high and 6 moderate production npm
+  advisories. The final image is static nginx, reducing exposure to Node-server
+  advisories, but browser dependencies remain reachable. Release requires an
+  owner accept/fix decision.
+- The repository is large: this checkout has about 5.4 GiB of packed objects,
+  and the Gitea repository is about 5 GiB. Public GRASP replication must be
+  allowed enough time and verified rather than assumed complete.
+- The provided secrets audit reports known false positives in documentation,
+  path-variable names, and deliberate test keys. Before Nostr publication,
+  record that review and ensure local Git remote credentials are rotated; local
+  `.git/config` credentials are not tracked and must never be copied into an
+  announcement or release log.
+
+## Required Owner Inputs
+
+These secrets must be entered interactively and must not be sent in chat,
+committed, placed in shell history, or stored on the node:
+
+1. Access to the Nostr maintainer identity matching the npub above. Prefer an
+   interactive NIP-46 connection through `ngit account connect`; do not pass an
+   nsec on a command line.
+2. The 24-word Archipelago release-master mnemonic for three signing actions:
+   the OTA manifest, the app catalog, and the ISO checksum document.
+3. A decision to accept the recorded GitWorkshop dependency advisories for
+   1.8.12-alpha or pause for a dependency update.
+4. A decision to publish 0.5.32 on the existing explicitly non-production
+   `.debug` Companion channel, omit it, or pause for a secure production-app
+   signing ceremony.
+
+The shared Companion update certificate is not a production secret. It was
+temporarily recovered from the public branch, verified against the distributed
+0.5.28 APK, used to build the 0.5.32 alpha upgrade candidate, and removed from
+the working tree. Neither it nor the UAT keystore belongs in the release commit.
+
+## Execution Order
+
+### Gate A — Freeze And Production Companion
+
+1. Verify the shared Companion certificate against the existing public APK
+   before building anything. This is complete for the alpha candidate.
+2. Build the 0.5.32 shared-key alpha APK with v1, v2, and v3 signature schemes.
+3. Verify package ID, version code/name, signing digest, and install-as-upgrade
+   behavior on the owner's phone.
+4. Stage the APK and its JSON version metadata in the dashboard payload.
+5. Run formatting, frontend type checking/unit tests/build, Android lint/build,
+   focused backend tests, manifest validation, registry-candidate validation,
+   secret review, and live node smoke probes.
+6. Deploy that exact build on this node and perform the short final UAT:
+   GitWorkshop and IndeedHub first login, identity switching, Companion WebView,
+   external tab, certificate install, payment receipt, update cancellation, and
+   credential interstitial.
+
+Stop on any failure. Do not sign or publish a workaround build.
+
+### Gate B — Publish Archipelago Source Through Nostr
+
+Run Nostr publication from a disposable clean clone so `ngit init` cannot
+repoint or rewrite the release checkout's remotes.
+
+1. Confirm the clean clone matches the final candidate and contains `LICENSE`,
+   `CONTRIBUTING.md`, `SECURITY.md`, and `NOTICE`.
+2. Connect `ngit` interactively to the canonical maintainer identity and verify
+   `ngit account whoami` reports the expected npub.
+3. Publish identifier `archy`, title `Archipelago`, the public project
+   description/homepage, the existing Gitea HTTPS clone URL, and multiple
+   current public GRASP services. Use at least `relay.ngit.dev` and
+   `gitnostr.com`; add an Archipelago-operated GRASP service later without
+   changing the repository coordinate.
+4. Allow the complete repository push to finish. Do not treat a published
+   announcement as proof that all Git objects arrived.
+5. Verify the announcement author, identifier, relays, clone URLs, default
+   branch, and release tags with `ngit repo`.
+6. In a second empty directory, clone the printed `nostr://` URL and compare its
+   `HEAD` tree to the candidate.
+7. Open
+   `/npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg/archy`
+   in the packaged GitWorkshop and confirm README/code browsing works.
+8. Publish a test issue/proposal from a non-maintainer identity, review it from
+   the maintainer identity, and confirm it cannot change canonical refs without
+   maintainer authorization.
+9. Confirm clone/browse still work with one GRASP server unavailable. A later
+   infrastructure release must add an Archipelago-operated GRASP endpoint; the
+   signed coordinate remains stable when servers change.
+
+The Source promotion carries the deterministic npub/identifier deep-link. It
+must not be published to the registry until steps 5–8 pass.
+
+### Gate C — Prepare And Publish OTA 1.8.12-alpha
+
+1. Convert the top `Unreleased` changelog section into
+   `v1.8.12-alpha (2026-09-11)` and synchronize What's New.
+2. Run `bash scripts/create-release.sh 1.8.12-alpha`. Enter the release mnemonic
+   once when prompted and terminate input with Ctrl-D.
+3. Verify the new release commit, annotated tag, staged backend/frontend
+   artifacts, signed pending manifest, embedded AIUI, APK version, and clean
+   tree.
+4. Publish with
+   `SKIP_ISO=1 scripts/publish-release-assets.sh 1.8.12-alpha gitea-vps2`.
+   The script uploads and hashes artifacts before pushing the fleet-visible
+   manifest. Never push `main` manually around this ordering.
+5. Verify both local and public manifests, both asset hashes, public HTTPS
+   download links, and update availability from this node.
+6. Apply the OTA to this node first, reboot if requested, and rerun live smoke
+   probes before allowing the catalog publication.
+
+### Gate D — Publish The Signed App Registry
+
+This follows the OTA canary because GitWorkshop's manifest builds from
+`/opt/archipelago/docker/archipelago-source`, which older nodes do not have.
+
+1. Generate `releases/app-catalog.json` from the final manifests.
+2. Require 62 entries, 61 embedded manifests, `archipelago-source` 0.4.0,
+   registry-owned storefront metadata, and the canonical Source deep-link.
+3. Run strict metadata, manifest, and deployed-registry trust-floor checks.
+4. Sign the exact catalog bytes using `bash scripts/sign-catalog.sh` and verify
+   the pinned release-root DID.
+5. Commit and push only the signed catalog after the OTA canary succeeds.
+6. Confirm `/api/app-catalog` verifies the signature and a fresh node can see,
+   install, launch, stop, start, and uninstall GitWorkshop.
+
+### Gate E — Build, Test, Sign, And Attach The ISO
+
+1. From clean `main` with the live signed 1.8.12 manifest and tag, run
+   `bash scripts/build-iso-release.sh`. Do not use `--skip-gates` or `--no-qemu`
+   for the publishable candidate.
+2. Require the release harness, strict catalog check, full Rust test suite,
+   version/artifact checks, ISO mount smoke test, and QEMU boot attempt.
+3. Record the ISO filename, byte size, SHA-256, build commit, and whether QEMU
+   was conclusive. If QEMU is inconclusive, boot the ISO on the target test
+   machine before publication.
+4. Sign the checksum document with
+   `bash scripts/sign-iso-checksums.sh <iso>` and cryptographically verify it.
+5. Attach the ISO, plain checksum, and signed checksum JSON by rerunning
+   `scripts/publish-release-assets.sh 1.8.12-alpha gitea-vps2`.
+6. Verify Gitea's stored sizes and public HTTPS links, then download/hash the
+   public checksum documents. Flash/boot/install on real hardware before
+   calling the ISO generally available.
+
+## Rollback Rules
+
+- OTA: the live manifest remains 1.8.11-alpha until all 1.8.12 artifacts have
+  uploaded and verified. If canary application fails, do not publish the new
+  catalog; restore the previous manifest/artifacts through the established
+  rollback path.
+- Registry: retain the previously signed catalog. Roll back by publishing a
+  newly signed catalog that removes GitWorkshop or restores its prior entry;
+  never edit signed JSON in place.
+- Nostr source: repository state is authoritative only when signed by the
+  configured maintainer. Add replacement servers before removing failed ones,
+  then republish and run `ngit sync`.
+- ISO: an ISO is not referenced by the OTA manifest. A failed ISO build/upload
+  cannot block or corrupt an already verified OTA; do not advertise a partial
+  attachment.
+- Companion: retain 0.5.28 and the verified alpha signer until 0.5.32 installs
+  as an upgrade. Never replace the public APK with the differently signed UAT
+  build. Do not describe the public debug-key channel as production-secure.
+
+## Final Release Record
+
+Before announcing completion, record in the release notes:
+
+- release/tag/commit and signed manifest DID;
+- backend and frontend SHA-256 values;
+- signed catalog commit, app count, and verification result;
+- canonical `nostr://` URL, NIP-34 coordinate, GRASP/clone endpoints, and clone
+  verification commit;
+- Companion package/version/signing digest and APK SHA-256;
+- ISO filename/size/SHA-256/signature and smoke/QEMU/real-hardware results;
+- owner UAT acceptance and the explicit GitWorkshop no-license/dependency-risk
+  decisions.