From 2266f33c9a86e253f6eba8481a47d2c352fc6b04 Mon Sep 17 00:00:00 2001 From: Anthony Ronning <101225832+AnthonyRonning@users.noreply.github.com> Date: Thu, 19 Nov 2026 12:19:14 -0800 Subject: [PATCH] OpenSecret: retire the legacy signed-PCR copy Signed PCR approvals were published twice: in this repository, which Research 3.4.0 and both SDKs at 4.0 read, and by hand in OpenSecretCloud/opensecret, which older clients read. Those older clients speak only Transport V1, which the backend no longer serves, so nothing that can reach a current backend reads the old copy. The procedure now publishes approvals here only and leaves the old repository as it is. It keeps one exception, with its command: a build from a commit that still serves Transport V1. Co-Authored-By: Claude --- .../skills/develop-opensecret-sdk/SKILL.md | 8 +- docs/opensecret-import.md | 10 +- docs/sdk-publishing.md | 4 +- sdk/README.md | 10 +- services/opensecret/README.md | 11 +- services/opensecret/docs/pcr-compatibility.md | 159 +++++++----------- 6 files changed, 80 insertions(+), 122 deletions(-) diff --git a/.agents/skills/develop-opensecret-sdk/SKILL.md b/.agents/skills/develop-opensecret-sdk/SKILL.md index c25d0fabc..90abc7f50 100644 --- a/.agents/skills/develop-opensecret-sdk/SKILL.md +++ b/.agents/skills/develop-opensecret-sdk/SKILL.md @@ -93,10 +93,10 @@ them; there is no separate integration revision to advance. Provider-spending tests remain opt-in through `RUN_LIVE_AI=1` and require explicit credential, egress, and cost authorization. Both SDKs use signed-PCR histories under `MaplePrivacyLabs/Maple/master/services/opensecret/`, with the -existing verification key and separate development/production policies. Keep -the legacy `OpenSecretCloud/opensecret` histories available for older clients -through the backend's manual compatibility procedure. Source changes do not -publish SDKs or update installed clients. +existing verification key and separate development/production policies. The +`OpenSecretCloud/opensecret` copy that SDKs before 4.0 read is retired and gets +no new approvals. Source changes do not publish SDKs or update installed +clients. Before handoff, inspect package boundaries as applicable: diff --git a/docs/opensecret-import.md b/docs/opensecret-import.md index 49429af8d..ed7fa7467 100644 --- a/docs/opensecret-import.md +++ b/docs/opensecret-import.md @@ -81,10 +81,12 @@ Each captured history contains 145 entries. All 290 captured PCR0 signatures ver against the public key pinned by both SDKs. PCR1/PCR2 are present in the JSON but are not covered by those signatures; this import preserves that format. -Keep `OpenSecretCloud/opensecret` at its current name, public, writable, and -unarchived. Installed clients still request its raw history URLs. Its current -default branch is a compatibility mirror; backend implementation lives here. -Historical source, issues, and branches do not create a second active backend. +`OpenSecretCloud/opensecret` stays at its current name, public and unarchived. +Its signed-PCR copy served clients that spoke Transport V1 and was retired with +it in November 2026; it receives no new approvals. See +[the signed PCR procedure](../services/opensecret/docs/pcr-compatibility.md). +Backend implementation lives here. Historical source, issues, and branches do +not create a second active backend. Current TypeScript and Rust SDK defaults read the canonical histories under `MaplePrivacyLabs/Maple/master/services/opensecret/`. The SDK package names are diff --git a/docs/sdk-publishing.md b/docs/sdk-publishing.md index 5b5d9ebd3..3bc32a3c8 100644 --- a/docs/sdk-publishing.md +++ b/docs/sdk-publishing.md @@ -89,8 +89,8 @@ next. For enclave trust changes, review the affected embedded PCR0 roots in `sdk/src/lib/pcr.ts` and `sdk/rust/src/pcr.rs` against the signed environment histories. Bundle refreshes are optional fast-path/offline compatibility - updates, separate from approving an EIF. Preserve the signed histories and - [legacy mirror](../services/opensecret/docs/pcr-compatibility.md). + updates, separate from approving an EIF. Preserve the + [signed histories](../services/opensecret/docs/pcr-compatibility.md). 2. **Publish the affected SDKs** when the fix must reach external users or Auth. From `sdk/` on merged `master`, use `just publish-npm VERSION trusted false` for TypeScript or diff --git a/sdk/README.md b/sdk/README.md index 3bff2b588..df72de2c5 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -304,11 +304,11 @@ signed PCR history on a miss from production and `pcrDevHistory.json` for development. The existing verification key, custom history URL overrides, and redirect rejection are unchanged. Embedded roots are versioned with each shipped SDK: editing or pruning in-tree -roots does not replace the roots in published packages. Older published SDKs and -installed clients still use the legacy -`OpenSecretCloud/opensecret` URLs, which remain a manual compatibility mirror. -Changing source defaults does not update those clients or publish an SDK. See -the [backend compatibility procedure](../services/opensecret/docs/pcr-compatibility.md). +roots does not replace the roots in published packages. SDKs before 4.0 read the +`OpenSecretCloud/opensecret` URLs instead. That copy is retired and receives no +new approvals: those SDKs speak only Transport V1, which the backend no longer +serves. See the +[signed PCR procedure](../services/opensecret/docs/pcr-compatibility.md). Inspect the publishable npm artifact with: diff --git a/services/opensecret/README.md b/services/opensecret/README.md index d8d0e75ec..1d94f80fd 100644 --- a/services/opensecret/README.md +++ b/services/opensecret/README.md @@ -109,12 +109,11 @@ and deliberately update/verify the target measurements; never update checked-in PCRs solely to clear ordinary pull-request CI. The PCR files retain their existing names and signed format. Follow -[`docs/pcr-compatibility.md`](docs/pcr-compatibility.md) for validation and manual -publication of identical bytes to the legacy `OpenSecretCloud/opensecret` -repository. Current Maple SDK defaults read the canonical histories under -`MaplePrivacyLabs/Maple/master/services/opensecret/`; the legacy raw URLs -remain available for older installed clients. Keep both locations synchronized -through the manual compatibility procedure. +[`docs/pcr-compatibility.md`](docs/pcr-compatibility.md) to validate and verify +them. Maple SDKs read the signed histories under +`MaplePrivacyLabs/Maple/master/services/opensecret/`. The copy in +`OpenSecretCloud/opensecret` is retired: only Transport V1 clients read it, and +it receives no new approvals. See [`docs/nitro-deploy.md`](docs/nitro-deploy.md) for operator procedures. Changing PCR references or KMS policy, copying artifacts, starting or stopping diff --git a/services/opensecret/docs/pcr-compatibility.md b/services/opensecret/docs/pcr-compatibility.md index 8345f1daa..c53221272 100644 --- a/services/opensecret/docs/pcr-compatibility.md +++ b/services/opensecret/docs/pcr-compatibility.md @@ -1,4 +1,4 @@ -# Signed PCR files and the legacy compatibility mirror +# Signed PCR files OpenSecret keeps its existing files directly under `services/opensecret/`: @@ -21,31 +21,46 @@ those fields and preserve the existing development/production separation. The helper below validates their shape and consistency; it does not change the signed message or make additional cryptographic claims. -## Keep existing clients working +## Where clients read them -Retain `OpenSecretCloud/opensecret`, its `master` branch, and these exact root -paths, including the two signed histories: +Both SDKs fetch the signed history for their environment from this repository: -- [Development history](https://raw.githubusercontent.com/OpenSecretCloud/opensecret/master/pcrDevHistory.json) -- [Production history](https://raw.githubusercontent.com/OpenSecretCloud/opensecret/master/pcrProdHistory.json) +- [Development history](https://raw.githubusercontent.com/MaplePrivacyLabs/Maple/master/services/opensecret/pcrDevHistory.json) +- [Production history](https://raw.githubusercontent.com/MaplePrivacyLabs/Maple/master/services/opensecret/pcrProdHistory.json) -Keep that repository public, unarchived, and writable for the operator. A -repository move or redirect is not a substitute: current TypeScript and Rust -SDK history fetches reject redirects. Existing clients continue to use the old -URLs; they do not discover the monorepo layout automatically. +These must return HTTP 200 directly and match the reviewed files. The SDK +history fetches reject redirects, so a moved or renamed repository is not a +substitute. -The in-tree TypeScript and Rust SDK defaults use these canonical histories: +## The legacy copy is retired -- [Canonical development history](https://raw.githubusercontent.com/MaplePrivacyLabs/Maple/master/services/opensecret/pcrDevHistory.json) -- [Canonical production history](https://raw.githubusercontent.com/MaplePrivacyLabs/Maple/master/services/opensecret/pcrProdHistory.json) +Until September 2026 clients read the same four files from the root of +`OpenSecretCloud/opensecret`, and every approval was published there by hand as +well. Research 3.4.0 and both SDKs at 4.0 moved to the URLs above in the same +releases that moved them to Transport V2. Everything older speaks only +Transport V1, which the backend no longer serves, so nothing that can still +reach a current backend reads the old copy. -Both locations must return HTTP 200 directly and match the reviewed files; -use the verification procedure below for every authorized measurement update. -SDK URL changes are independent of registry renaming or publishing. Older -published SDKs and installed clients retain their existing URLs until upgraded. -Do not remove the legacy history or set a calendar cutoff as a consequence of -the source cutover. An eventual cutoff needs an explicit client compatibility -decision. +New approvals are therefore published here only. Leave the old repository and +its files as they are: do not publish to it, prune it, or archive it as part of +a release. + +One exception: a build from a commit that still serves Transport V1 can still +be reached by old clients. If such a build is ever deployed, publish its +approval to the old copy too. From `services/opensecret/`, in the same shell as +the check below: + +```sh +python3 scripts/pcr_compatibility.py prepare \ + --source-repo /absolute/path/to/Maple --source-ref FULL_REVIEWED_MAPLE_COMMIT_SHA \ + --legacy-repo /absolute/path/to/a/clean/legacy/worktree \ + --legacy-ref FULL_FETCHED_LEGACY_MASTER_SHA +``` + +It reads the four files from the committed Maple revision, verifies both sides, +and reports what would change. Repeated with `--apply`, it copies the files +into the legacy worktree and leaves them unstaged for review. Publish that with +an ordinary pull request to the old repository. ## Validate an authorized measurement update @@ -64,13 +79,13 @@ from `services/opensecret/`: OPENSECRET_DEV_POSTGRES=0 OPENSECRET_DEV_ENV=0 OPENSECRET_DEV_CONTAINERS=0 \ nix develop --no-update-lock-file -c \ python3 scripts/pcr_compatibility.py check . \ - --baseline-dir /absolute/path/to/a/fresh/legacy/worktree + --baseline-dir /absolute/path/to/services/opensecret/at/the/previous/master ``` The `update-pcr-dev` and `update-pcr-prod` recipes copy measurements and append a verified signature. This additional check verifies all four files, every PCR0 signature against the SDK's existing public key, snapshot membership in the appropriate -history, and preservation of every prior legacy entry. Snapshot membership may +history, and preservation of every prior entry in the baseline. Snapshot membership may refer to an earlier entry to permit a deliberate rollback. The helper rejects malformed or empty histories, duplicate JSON fields, @@ -82,95 +97,37 @@ introduce a new format. Never prune history or relax limits just to make an update pass: investigate and coordinate a separate compatibility change. The offline baseline check cannot establish that a checkout is current on -GitHub. Fetch the legacy repository immediately before preparing the copy. If -another operator has written to either history, reconcile the exact entries -into the canonical history first; do not choose a winner by overwriting files. -Keep a single operator responsible for each update across both repositories. - -## Prepare a manual legacy publication - -Use a dedicated, clean legacy worktree on a fresh branch from fetched -`origin/master`. The example variables below must identify your exact local -checkouts and reviewed **full commit SHAs**. The helper reads source files from -the specified committed monorepo revision, not uncommitted working files. - -```sh -maple_repo=/absolute/path/to/Maple -legacy_repo=/absolute/path/to/opensecret-pcr-worktree -maple_pcr_ref=FULL_REVIEWED_40_CHARACTER_MAPLE_COMMIT_SHA - -git -C "$legacy_repo" fetch origin refs/heads/master:refs/remotes/origin/master -legacy_pcr_ref="$(git -C "$legacy_repo" rev-parse refs/remotes/origin/master)" -# In a clean dedicated worktree, create this operator-chosen branch at that ref. -git -C "$legacy_repo" switch -c pcr-compatibility-update "$legacy_pcr_ref" - -cd "$maple_repo/services/opensecret" -OPENSECRET_DEV_POSTGRES=0 OPENSECRET_DEV_ENV=0 OPENSECRET_DEV_CONTAINERS=0 \ - nix develop --no-update-lock-file -c python3 scripts/pcr_compatibility.py prepare \ - --source-repo "$maple_repo" --source-ref "$maple_pcr_ref" \ - --legacy-repo "$legacy_repo" --legacy-ref "$legacy_pcr_ref" -``` - -The default command only reports entry counts, SHA-256 file hashes, sizes, and -which files would change. Inspect that result. It requires the expected GitHub -origins, tracked regular files, the exact legacy HEAD and fetched -`origin/master`, a clean legacy worktree/index, valid signatures in both -revisions, and an unchanged legacy history prefix. A stale or divergent local -baseline fails before any copy. The helper performs no network requests and -cannot detect an unfetched remote update. - -Repeat the same command with `--apply` to copy the exact verified bytes into -only the four legacy files. The helper rechecks local state before copying. It -does not stage, commit, push, sign, load a private key, or require a CI token. -An import with identical files produces no changes and needs no mirror commit. - -For a real update, inspect and commit the result through the normal operator -review process: - -```sh -git -C "$legacy_repo" diff --check -git -C "$legacy_repo" diff -- pcrDev.json pcrProd.json pcrDevHistory.json pcrProdHistory.json -git -C "$legacy_repo" add -- pcrDev.json pcrProd.json pcrDevHistory.json pcrProdHistory.json -git -C "$legacy_repo" commit -m 'Mirror reviewed OpenSecret PCR approvals from Maple' -git -C "$legacy_repo" fetch origin refs/heads/master:refs/remotes/origin/master -test "$(git -C "$legacy_repo" rev-parse refs/remotes/origin/master)" = "$legacy_pcr_ref" -``` - -If the last check fails, stop and reconcile against the newer legacy master in -a fresh worktree before publishing. Publish the reviewed branch with an ordinary -non-force push and PR. Include the immutable Maple source SHA and helper output -in the PR. Recheck the latest legacy master immediately before merge and verify -that every existing history entry remains unchanged. Do not resolve a concurrent -history edit by replacing the other operator's file wholesale. +GitHub. Fetch `master` immediately before taking the baseline. If another +operator has written to either history, reconcile the exact entries first; do +not choose a winner by overwriting files. Keep a single operator responsible +for each update. -## Verify publication before deployment or SDK URL cutover +## Verify publication before deployment -After the approved changes are merged in both repositories, fetch each of the -four raw files from each repository and compare the downloaded bytes with the -reviewed source commit. For each URL, use a temporary output path and a bounded -request that does not follow redirects, for example: +After the approval is merged, fetch each of the four raw files and compare the +downloaded bytes with the reviewed source commit. For each URL, use a temporary +output path and a bounded request that does not follow redirects, for example: ```sh curl --fail --silent --show-error --proto '=https' --max-time 15 \ --max-filesize 1048576 --output /absolute/path/to/check/pcrProdHistory.json \ --write-out '%{http_code}\n' \ - https://raw.githubusercontent.com/OpenSecretCloud/opensecret/master/pcrProdHistory.json + https://raw.githubusercontent.com/MaplePrivacyLabs/Maple/master/services/opensecret/pcrProdHistory.json ``` Require the printed status to be **200**; a 3xx is a failed check even if curl -itself exits successfully. Never add `--location`. Check immutable commit URLs -as well as `master` URLs, compare all four files byte-for-byte, and run the -offline helper's `check` against each downloaded four-file directory. A cached -old `master` response is not successful publication; wait for matching bytes. -Record both commit SHAs and hashes. The current deployment keeps serving during -this repository work; these checks do not prove its live EIF or KMS policy. - -Before deploying an authorized new measurement, both histories must be -published and verified so clients using either location can approve it. Keep -the existing release process and its deployment gates. The GitHub-managed -release workflow produces canonical approvals only; there is still no automatic -legacy backpublisher, GitHub-managed EIF deployment, signing-key migration, or -Sigstore change in this compatibility path. +itself exits successfully. Never add `--location`. Check the immutable commit +URL as well as the `master` URL, compare all four files byte-for-byte, and run +the offline helper's `check` against the downloaded four-file directory. A +cached old `master` response is not successful publication; wait for matching +bytes. Record the commit SHA and hashes. The current deployment keeps serving +during this repository work; these checks do not prove its live EIF or KMS +policy. + +Before deploying an authorized new measurement, its approval must be published +and verified so clients can approve it. Keep the existing release process and +its deployment gates. There is still no GitHub-managed EIF deployment, +signing-key migration, or Sigstore change in this path. ## Regression checks