Skip to content

feat: Boop service DID countersigns action-record receipts (#286 P3) - #312

Merged
brianorwhatever merged 4 commits into
mainfrom
feat/boop-service-did
Nov 18, 2026
Merged

brianorwhatever merged 4 commits into
mainfrom
feat/boop-service-did

Conversation

@brianorwhatever

@brianorwhatever brianorwhatever commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

PR P3 of the agent-signing plan (plans/002-agent-signing-decisions.md on docs/agent-signing-plan, Track A), for #286. Implements D11 (receipt signer) and the mechanism behind D10 (a record stays valid if Boop's signed receipt time predates revocation).

Main behavior is unchanged. Receipts are requested only when the Convex env var ACTION_RECEIPTS_ENABLED is exactly true. It is unset by default, so recordActions schedules nothing and no record gets a receipt until P6.

No real Turnkey key, DID or deploy. Every Turnkey call in this PR has run only against a mock. Nothing was deployed to dev or prod.

What's here

  • Boop service did:webvh at did:webvh:<scid>:<WEBVH_DOMAIN>:boop-service, stored in didLogs and served like account DIDs (/d/boop-service/did.jsonl, proxied at /boop-service/did.jsonl). Two Ed25519 keys in one wallet of the Turnkey parent org: an update key (owner's script only) and a receipt key #receipt-<n>, the DID's only verification method and only assertionMethod. shared/serviceDid.ts defines and checks the shape.
  • Owner-run script scripts/boop-service-did.ts (create, rotate, show, publish) over a mockable ServiceKeyBackend. create and rotate only describe what they would do unless given --yes.
  • receipts.signReceipt({ recordHash, receivedAt }), an internal action in Convex's default runtime (the Turnkey client is Web Crypto and fetch, so no Node action is needed). Returns { type, recordHash, receivedAt, signer, versionId, proof }. It verifies the signature Turnkey returns against the served log before returning, so a wrong key or a wrong API assumption is an error, not a bad receipt.
  • shared/receipt.ts: the schema and verifyReceipt(receipt, serviceDidLog, { expected? }), pure and synchronous, resolving the key at the named versionId.
  • Storage and wiring: actionRecords.receipt (optional field). Behind the flag, recordActions schedules receipts.issueForRecords for the records it stored as signed, in jobs of 25. The receipt is signed after the mutation, so a write never waits on Turnkey; failures retry at 5 s, 30 s and 3 min, then the record stays without a receipt.
  • Docs: a Receipts section in docs/action-records.md (format, the receipt-before-revocation rule, limits), and docs/service-did.md (keys, owner setup, rotation, env vars).

Signing convention: eddsa-jcs-2022

Receipts are W3C Data Integrity documents with eddsa-jcs-2022, not the repo's SHA-256(domain) || SHA-256(payload) form used for action records. Reasons: a receipt is a small JSON object handed to third parties and signed by a service identity, so a standard suite lets any Data Integrity verifier check it without Boop's code; it is the suite did:webvh log entries already use here and the one the planned delegations use (D5a), so P6 has one proof format; and the signed proof options give the domain separation the prefix gives records. A test checks the signed bytes equal what didwebvh-ts computes for the same document.

Decisions worth a look

  • A separate Turnkey API user signs receipts (TURNKEY_RECEIPT_API_*), with its own policy file. The existing relay user's policy still denies every signing activity and is untouched. D11 says "a Convex action calls Turnkey" and does not say which user; say if you would rather widen the existing user.
  • Two guard tests changed, each narrowed rather than removed. turnkey-custody.test.mjs forbade any signing call in convex/; it now allows exactly one, in convex/lib/serviceReceipts.ts, and asserts it signs as the parent org with the receipt credentials. did-log-auth.test.mjs required every didLogs writer to assert caller ownership; convex/serviceDid.ts has no caller (owner-run via npx convex run), so it is instead required to be internal-only and to write only the service path.
  • Rotation does not bound old receipts. verifyReceipt reads the key at the named version, as asked, and does not compare receivedAt with the time the key was retired. Documented as a limit.
  • convex/_generated/api.d.ts was edited by hand for the four new modules; codegen needs a deployment. Regenerate on the next npx convex dev.

Not in this PR

  • Nothing applies the receipt-before-revocation rule yet (P6).
  • scripts/verify-action-records.mjs and the provenance UI do not check or show receipts.

Owner setup (before the flag can be turned on)

Full detail in docs/service-did.md. Do it against a test parent org and a dev deployment first.

  1. With owner credentials in your shell (TURNKEY_ORGANIZATION_ID, TURNKEY_OWNER_API_PUBLIC_KEY, TURNKEY_OWNER_API_PRIVATE_KEY), run bun scripts/boop-service-did.ts create --domain <WEBVH_DOMAIN> --yes. Keep service-did.jsonl and the wallet ID it prints.
  2. Create an API-only receipt-signer user in the parent org (not in the root quorum) and apply docs/turnkey/boop-receipt-signer-policies.json with its user ID and the two key addresses.
  3. Check the policy against the live API: signing with the receipt key succeeds; signing with the update key, creating wallet accounts and exporting are denied.
  4. npx convex env set TURNKEY_RECEIPT_API_PUBLIC_KEY … and TURNKEY_RECEIPT_API_PRIVATE_KEY ….
  5. bun scripts/boop-service-did.ts publish (add -- --prod for prod), then confirm https://<domain>/boop-service/did.jsonl serves the log.
  6. Try one: npx convex run receipts:signReceipt '{"recordHash":"<64 hex>","receivedAt":<ms>}'.
  7. Record the service DID in docs/service-did.md and API.md so verifiers can pin it.
  8. In P6, not before: npx convex env set ACTION_RECEIPTS_ENABLED true.

Unvalidated against live Turnkey: create_wallet, create_wallet_accounts, list_wallet_accounts and sign_raw_payload in the parent org, and every policy expression (wallet_account.address most of all).

Verification

  • tsc -p convex/tsconfig.json and tsc -b: clean.
  • bun test: 884 pass, 0 fail (866 before this PR).
  • bun run build: green.
  • New tests: sign and verify round trip; every altered field, a foreign signer and a foreign log rejected; receipts from before and after a rotation each verifying only under their own version's key; the mocked Turnkey request shape and fail-closed answers; flag off schedules nothing; flag on gives one receipt per signed record and none for unsigned or failed ones; retries; publishing refused for anything but a valid continuation of the service log.

🤖 Generated with Claude Code

Note

Add Boop service DID countersigning for action-record receipts

  • Adds a Boop service DID (did:webvh) with a boop-service-did CLI to create, rotate, show, and publish its DID log, plus Turnkey wallet-backed signing (service-did.ts, boop-service-did.ts)
  • Signed action records can now receive an EdDSA data-integrity receipt from the service DID. When ACTION_RECEIPTS_ENABLED is exactly "true", recordActions schedules receipts:issueForRecords in batches of at most 25, with retries after 5s, 30s, and 180s. Receipts are stored only after verification against the published service DID log (serviceReceipts.ts, receipts.ts)
  • Adds shared receipt types, parsing, and Ed25519 verification (verifyReceipt, parseReceipt) in receipt.ts, plus an optional receipt field on the actionRecords schema
  • Moves Turnkey request signing and API helpers from convex/authInternal.ts into turnkeyApi.ts for reuse
  • Behavioral Change: receipts are off by default; enabling requires ACTION_RECEIPTS_ENABLED="true" plus TURNKEY_RECEIPT_API_PUBLIC_KEY, TURNKEY_RECEIPT_API_PRIVATE_KEY, TURNKEY_ORGANIZATION_ID, and a published service DID log at SERVICE_DID_PATH. The DID proxy at didProxy.ts now also serves /boop-service/did.jsonl. Turnkey interactions are mocked in tests and not yet validated against the live service

Macroscope summarized 64d8151.

brianorwhatever and others added 2 commits November 15, 2026 13:09
Move the Web Crypto request stamping out of convex/authInternal.ts into
convex/lib/turnkeyApi.ts so the receipt signer and the owner-run service
DID script can use it. No behavior change; turnkeyRequest takes an optional
fetch for tests.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A Boop service did:webvh, served at /boop-service/did.jsonl beside the
account DIDs, whose receipt key lives in the Turnkey parent org. The
internal action receipts.signReceipt({ recordHash, receivedAt }) returns an
eddsa-jcs-2022 receipt naming the service key and the DID log version, and
shared/receipt.ts verifyReceipt checks one offline against the service log
at that version, so receipts survive a key rotation.

recordActions requests a receipt for newly accepted signed records only
when ACTION_RECEIPTS_ENABLED is "true". It is unset by default, so nothing
is scheduled and behavior is unchanged until P6.

The DID is created and rotated by an owner-run script
(scripts/boop-service-did.ts) behind a mockable key backend. No Turnkey key
or DID was created: every Turnkey call here has run only against a mock.
The receipt signer is its own API user with its own policy; the auth relay
user still cannot sign.

plans/002-agent-signing-decisions.md D10, D11.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@railway-app
railway-app Bot temporarily deployed to Friends / boop-pr-312 November 15, 2026 20:10 Destroyed
@railway-app

railway-app Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

🚅 Deployed to the boop-pr-312 environment in Friends

Service Status Web Updated
boop ✅ Success (View Logs) Web Nov 18, 2026 at 8:46 am UTC

@brianorwhatever
brianorwhatever marked this pull request as ready for review November 18, 2026 08:40
@railway-app
railway-app Bot temporarily deployed to Friends / boop-pr-312 November 18, 2026 08:40 Destroyed

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important

The receipt signer's Turnkey policy file, applied as written, would deny the one activity it exists to allow. Setup step 3 would hit this before anything ships, but the file should be fixed before an owner applies it.

Approach: sound. Receipts are a standard eddsa-jcs-2022 document signed outside the write path, checked against the served log both before return and before storage, behind an off-by-default flag, with a separate least-privilege Turnkey user. The flag-off path changes nothing.

Reviewed changes

I reviewed the full diff at 64d8151. All five touched suites pass locally under bun test (43 pass, 0 fail).

  • convex/lib/turnkeyApi.ts: the stamped Turnkey client moved out of convex/authInternal.ts unchanged. Only the fetchImpl parameter and the exports are new.
  • shared/receipt.ts / shared/serviceDid.ts: receipt schema, verifyReceipt (looks up the key at the named versionId) and the strict service-DID shape check.
  • convex/lib/serviceReceipts.ts / convex/receipts.ts: signing through Turnkey SIGN_RAW_PAYLOAD_V2 as the parent org, a self-verify before return, storeReceipt re-verifying against the stored log, digest and occurredAt, and bounded retries.
  • convex/lib/actionRecords.ts: when ACTION_RECEIPTS_ENABLED === "true", recordActions schedules issueForRecords jobs of 25 for signed rows only.
  • convex/serviceDid.ts + didProxy.ts: an internal-only publish that goes through checkWrite plus the service shape check. The log is served at /boop-service/did.jsonl, and the /d/ handler was already path-agnostic.
  • scripts/boop-service-did.ts / scripts/lib/service-did.ts: owner-run genesis, rotation and publish against a mockable backend.
  • Guard tests: turnkey-custody and did-log-auth are narrowed to the single new signer and writer, not dropped.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread convex/receipts.ts Resolved
Comment thread docs/service-did.md Resolved
- The deny policy no longer names resource PRIVATE_KEY, which Turnkey files
  SIGN_RAW_PAYLOAD_V2 under; private-key creation is denied by type instead.
- issueForRecords reads the service log once per batch and signs directly
  rather than through a nested action per record.
- Rotation docs: allow both addresses during a rotation, so there is no gap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@railway-app
railway-app Bot temporarily deployed to Friends / boop-pr-312 November 18, 2026 08:44 Destroyed

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. All three earlier threads are fixed and resolved.

Reviewed changes

I reviewed f0e7ad1, the fix commit pushed after the last review. The three touched suites pass locally under bun test (36 pass, 0 fail).

  • Batched signing in issueForRecords: it now reads the service log and builds the Turnkey signer once per job, then calls issueReceipt directly instead of a nested runAction for each record. If setup fails, every owed record is marked failed, so the job still goes through the 5 s / 30 s / 3 min retries as before.
  • Receipt-signer deny policy: the deny no longer lists resource PRIVATE_KEY, which would have blocked SIGN_RAW_PAYLOAD_V2. CREATE_PRIVATE_KEYS and CREATE_PRIVATE_KEYS_V2 are now denied by type, and turnkey-custody.test.mjs checks that no deny names 'PRIVATE_KEY'.
  • Rotation docs: docs/service-did.md and the policy $comment now give the same order. Allow both addresses before publish, then remove the old one, so there is no time when Convex cannot sign.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@brianorwhatever
brianorwhatever merged commit 0f53694 into main Nov 18, 2026
9 checks passed

This branch was successfully deployed

No deployments
Friends / boop-pr-312 — f0e7ad14 Deployed Nov 18, 2026 by railway-app[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant