Repository navigation
feat: Boop service DID countersigns action-record receipts (#286 P3) - #312
Conversation
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>
|
🚅 Deployed to the boop-pr-312 environment in Friends
|
There was a problem hiding this comment.
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 ofconvex/authInternal.tsunchanged. Only thefetchImplparameter and the exports are new.shared/receipt.ts/shared/serviceDid.ts: receipt schema,verifyReceipt(looks up the key at the namedversionId) and the strict service-DID shape check.convex/lib/serviceReceipts.ts/convex/receipts.ts: signing through TurnkeySIGN_RAW_PAYLOAD_V2as the parent org, a self-verify before return,storeReceiptre-verifying against the stored log, digest andoccurredAt, and bounded retries.convex/lib/actionRecords.ts: whenACTION_RECEIPTS_ENABLED === "true",recordActionsschedulesissueForRecordsjobs of 25 forsignedrows only.convex/serviceDid.ts+didProxy.ts: an internal-only publish that goes throughcheckWriteplus 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-custodyanddid-log-authare narrowed to the single new signer and writer, not dropped.
claude-opus-5-5 | 𝕏
- 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>
There was a problem hiding this comment.
✅ 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 callsissueReceiptdirectly instead of a nestedrunActionfor 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 blockedSIGN_RAW_PAYLOAD_V2.CREATE_PRIVATE_KEYSandCREATE_PRIVATE_KEYS_V2are now denied by type, andturnkey-custody.test.mjschecks that no deny names'PRIVATE_KEY'. - Rotation docs:
docs/service-did.mdand the policy$commentnow give the same order. Allow both addresses beforepublish, then remove the old one, so there is no time when Convex cannot sign.
claude-opus-5-5 | 𝕏

PR P3 of the agent-signing plan (
plans/002-agent-signing-decisions.mdondocs/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_ENABLEDis exactlytrue. It is unset by default, sorecordActionsschedules 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
did:webvh:<scid>:<WEBVH_DOMAIN>:boop-service, stored indidLogsand 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 onlyassertionMethod.shared/serviceDid.tsdefines and checks the shape.scripts/boop-service-did.ts(create,rotate,show,publish) over a mockableServiceKeyBackend.createandrotateonly 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 andverifyReceipt(receipt, serviceDidLog, { expected? }), pure and synchronous, resolving the key at the namedversionId.actionRecords.receipt(optional field). Behind the flag,recordActionsschedulesreceipts.issueForRecordsfor the records it stored assigned, 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/action-records.md(format, the receipt-before-revocation rule, limits), anddocs/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'sSHA-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 whatdidwebvh-tscomputes for the same document.Decisions worth a look
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.turnkey-custody.test.mjsforbade any signing call inconvex/; it now allows exactly one, inconvex/lib/serviceReceipts.ts, and asserts it signs as the parent org with the receipt credentials.did-log-auth.test.mjsrequired everydidLogswriter to assert caller ownership;convex/serviceDid.tshas no caller (owner-run vianpx convex run), so it is instead required to be internal-only and to write only the service path.verifyReceiptreads the key at the named version, as asked, and does not comparereceivedAtwith the time the key was retired. Documented as a limit.convex/_generated/api.d.tswas edited by hand for the four new modules; codegen needs a deployment. Regenerate on the nextnpx convex dev.Not in this PR
scripts/verify-action-records.mjsand 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.TURNKEY_ORGANIZATION_ID,TURNKEY_OWNER_API_PUBLIC_KEY,TURNKEY_OWNER_API_PRIVATE_KEY), runbun scripts/boop-service-did.ts create --domain <WEBVH_DOMAIN> --yes. Keepservice-did.jsonland the wallet ID it prints.docs/turnkey/boop-receipt-signer-policies.jsonwith its user ID and the two key addresses.npx convex env set TURNKEY_RECEIPT_API_PUBLIC_KEY …andTURNKEY_RECEIPT_API_PRIVATE_KEY ….bun scripts/boop-service-did.ts publish(add-- --prodfor prod), then confirmhttps://<domain>/boop-service/did.jsonlserves the log.npx convex run receipts:signReceipt '{"recordHash":"<64 hex>","receivedAt":<ms>}'.docs/service-did.mdandAPI.mdso verifiers can pin it.npx convex env set ACTION_RECEIPTS_ENABLED true.Unvalidated against live Turnkey:
create_wallet,create_wallet_accounts,list_wallet_accountsandsign_raw_payloadin the parent org, and every policy expression (wallet_account.addressmost of all).Verification
tsc -p convex/tsconfig.jsonandtsc -b: clean.bun test: 884 pass, 0 fail (866 before this PR).bun run build: green.🤖 Generated with Claude Code
Note
Add Boop service DID countersigning for action-record receipts
did:webvh) with aboop-service-didCLI to create, rotate, show, and publish its DID log, plus Turnkey wallet-backed signing (service-did.ts, boop-service-did.ts)ACTION_RECEIPTS_ENABLEDis exactly"true",recordActionsschedulesreceipts:issueForRecordsin 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)verifyReceipt,parseReceipt) in receipt.ts, plus an optionalreceiptfield on theactionRecordsschemaconvex/authInternal.tsinto turnkeyApi.ts for reuseACTION_RECEIPTS_ENABLED="true"plusTURNKEY_RECEIPT_API_PUBLIC_KEY,TURNKEY_RECEIPT_API_PRIVATE_KEY,TURNKEY_ORGANIZATION_ID, and a published service DID log atSERVICE_DID_PATH. The DID proxy atdidProxy.tsnow also serves/boop-service/did.jsonl. Turnkey interactions are mocked in tests and not yet validated against the live serviceMacroscope summarized 64d8151.