Skip to content
Merged
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
8 changes: 4 additions & 4 deletions .agents/skills/develop-opensecret-sdk/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
10 changes: 6 additions & 4 deletions docs/opensecret-import.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/sdk-publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
11 changes: 5 additions & 6 deletions services/opensecret/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
159 changes: 58 additions & 101 deletions services/opensecret/docs/pcr-compatibility.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Signed PCR files and the legacy compatibility mirror
# Signed PCR files

OpenSecret keeps its existing files directly under `services/opensecret/`:

Expand All @@ -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

Expand All @@ -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,
Expand All @@ -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

Expand Down