Am/example/tvc cosign by am-hernandez · Pull Request #2 · tkhq/tvc-examples

am-hernandez · 2026-07-10T13:56:09Z

Add tvc-cosign example

tvc-cosign is a Rust service, its core endpoint being POST /cosign: it parses an unsigned EVM transaction, classifies it against a baked-in ruleset (PROGRAMMATIC | ADMIN | REJECT), and returns a stamped SIGN_TRANSACTION_V2 activity signed by one of two quorum-key-derived API keys (programmatic / admin). The caller submits the activity to Turnkey, where policies either auto-complete it (programmatic) or hold it for human approval (admin). It also exposes GET /health (liveness) and GET /pubkeys (the two stamping public keys to register as API users).

The README covers the reproducible build, CLI deploy, Turnkey org setup (users + policies), and the integration flow.

Closes TVC-176.

Testing

Unit tests (cargo test, 35 tests): transaction parsing (EIP-1559 and legacy), classification across the programmatic / admin / reject cases, stamp construction, activity-body shape, and App Proof generation. Crypto is pinned with known-answer tests, including the enclave key derivation byte-checked against the QOS reference.
End-to-end against Turnkey: deployed to a TVC enclave and ran the full flow. GET /pubkeys matched the registered API users. An allowlisted ERC-20 transfer classified PROGRAMMATIC, was stamped, and submitting the activity to Turnkey returned ACTIVITY_STATUS_COMPLETED (policy auto-approved). An admin-selector approve classified ADMIN, returned ACTIVITY_STATUS_CONSENSUS_NEEDED, and completed only after a non-root human approver signed off via passkey, confirming the human-consensus policy gated it.
Each /cosign response carried an App Proof signed by the enclave's ephemeral key.

Note

Uses the current static/well-known TVC quorum key, so the derived stamping keys are not yet secret. Documented in the README's limitations.

socket-security · 2026-07-10T13:56:50Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	tokio@1.52.3
	serde@1.0.228
	serde_json@1.0.150
	alloy-consensus@2.1.1
	alloy-eips@2.1.1
	alloy-primitives@1.6.0
	alloy-rlp@0.3.16
	axum@0.8.9
	base64@0.22.1
	hex@0.4.3
	hkdf@0.13.0
	p256@0.14.0
	sha2@0.11.0
	toml@1.1.2%2Bspec-1.1.0

View full report

socket-security · 2026-07-10T13:56:52Z

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert (click "▶" to expand/collapse)
Warn		Obfuscated code: cargo `hyper-util` is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: `?` → `cargo/axum@0.8.9` → `cargo/hyper-util@0.1.20` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore cargo/hyper-util@0.1.20`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: cargo `libc` is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: `?` → `cargo/sha2@0.11.0` → `cargo/hkdf@0.13.0` → `cargo/tokio@1.52.3` → `cargo/alloy-primitives@1.6.0` → `cargo/p256@0.14.0` → `cargo/alloy-consensus@2.1.1` → `cargo/alloy-eips@2.1.1` → `cargo/libc@0.2.186` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore cargo/libc@0.2.186`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: cargo `tokio` is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: tvc-cosign/Cargo.lock → `cargo/tokio@1.52.3` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore cargo/tokio@1.52.3`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: cargo `zerocopy` is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: `?` → `cargo/alloy-primitives@1.6.0` → `cargo/alloy-consensus@2.1.1` → `cargo/zerocopy@0.8.53` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore cargo/zerocopy@0.8.53`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

git-subtree-dir: tvc-cosign git-subtree-mainline: 55e3e1b git-subtree-split: 7ea2fa1

Copilot

Pull request overview

Adds a new tvc-cosign Rust example service demonstrating a TVC enclave “transaction cosigner” that classifies unsigned EVM transactions and returns a Turnkey-stampable SIGN_TRANSACTION_V2 request plus an enclave-signed App Proof.

Changes:

Introduces an Axum HTTP service with /health, /pubkeys, and /cosign endpoints, including request stamping + App Proof generation.
Implements unsigned-EVM transaction parsing and a TOML-driven rules engine for PROGRAMMATIC | ADMIN | REJECT classification.
Adds reproducible-build packaging (Dockerfile) and extensive documentation (README) describing deployment + verification flow.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tvc-cosign/src/main.rs	Axum server entrypoint, CLI parsing, endpoints, and response shapes.
tvc-cosign/src/activity.rs	Deterministic construction of Turnkey `SIGN_TRANSACTION_V2` request bodies.
tvc-cosign/src/tx.rs	Minimal parser for unsigned EVM transaction signing payloads (typed + legacy).
tvc-cosign/src/rules.rs	TOML-backed ruleset parsing + transaction classification logic.
tvc-cosign/src/stamp.rs	Turnkey request stamp construction (P-256 ECDSA, base64url envelope).
tvc-cosign/src/proof.rs	App Proof envelope + payload construction and signing with ephemeral key.
tvc-cosign/src/keys.rs	Quorum-key HKDF derivation of API keys + QOS ephemeral key reconstruction.
tvc-cosign/src/config.rs	Startup configuration loading (org id + ruleset selection).
tvc-cosign/README.md	End-to-end documentation: setup, reproducible build, deploy, verify proofs.
tvc-cosign/rules.example.toml	Example ruleset schema and documented defaults.
tvc-cosign/Dockerfile	Reproducible build + minimal runtime image, prints expectedPivotDigest.
tvc-cosign/Cargo.toml	Crate manifest and dependencies.
tvc-cosign/Cargo.lock	Locked dependency graph for reproducible builds.
tvc-cosign/.gitignore	Ignores build artifacts and local per-deployment rules files.
tvc-cosign/.dockerignore	Minimizes docker build context for deterministic image digests.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+/// Ruleset compiled into the binary at build time. TVC runs only the pivot binary,
+/// so the ruleset ships inside it rather than as a file in the image.
+const EMBEDDED_RULES_TOML: &str = include_str!("../rules.toml");
+


+pub fn classify(signer: Address, tx: &ParsedTx, rules: &Ruleset) -> Classification {
+    if !rules.allowed_signers.contains(&signer) {
+        return Classification::Reject;
+    }
+
+    let Some(selector) = tx.selector() else {
+        // No calldata (e.g. a native transfer) — out of scope for this POC.
+        return Classification::Reject;
+    };


richardpringle · 2026-07-10T22:12:33Z

+fn decode_transfer_args(input: &[u8]) -> Option<(Address, U256)> {
+    // 4 (selector) + 32 (address) + 32 (amount)
+    let args = input.get(4..68)?;
+    let (addr_word, amount_word) = args.split_at(32);
+    if addr_word[..12].iter().any(|&b| b != 0) {
+        return None; // address must be zero-padded in its 32-byte word
+    }
+    let recipient = Address::from_slice(&addr_word[12..]);
+    let amount = U256::from_be_slice(amount_word);
+    Some((recipient, amount))
+}


Agree, the copilot suggestion is a little more explicit... but 🤷 , I don't think it matters

richardpringle · 2026-07-10T21:58:00Z

+    while let Some(flag) = iter.next() {
+        match flag.as_str() {
+            "--organization-id" => args.organization_id = iter.next(),
+            "--rules-path" => args.rules_path = iter.next(),
+            "--port" => {
+                if let Some(v) = iter.next() {
+                    match v.parse() {
+                        Ok(p) => args.port = p,
+                        Err(_) => {
+                            eprintln!("args: WARNING invalid --port {v:?}, using {DEFAULT_PORT}")
+                        }
+                    }
+                }
+            }
+            other => eprintln!("args: WARNING ignoring unknown argument {other:?}"),
+        }
+    }


I don't agree with copilot here, but you should make sure that the value doesn't start with -- as a minimal check

+        data.extend_from_slice(&[0u8; 12]);
+        data.extend_from_slice(recipient.as_slice()); // right-padded to 32 bytes
+        data.extend_from_slice(&U256::from(amount).to_be_bytes::<32>());


richardpringle · 2026-07-10T21:51:05Z

+#[serde(rename_all = "camelCase")]
+struct SignTransactionActivity {
+    #[serde(rename = "type")]
+    activity_type: &'static str,


On the off chance you didn't know about this, you can do this:

Suggested change

activity_type: &'static str,

r#type: &'static str,

(though I prefer what you did)

richardpringle · 2026-07-10T21:55:03Z

+        let organization_id = cli_organization_id
+            .map(str::to_string)


FYI, best practice is to pass in owned types if you need owned types

richardpringle · 2026-07-10T21:56:27Z

+                    }
+                }
+            }
+            other => eprintln!("args: WARNING ignoring unknown argument {other:?}"),


Maybe do a small help text too?

richardpringle · 2026-07-10T21:58:00Z

+    while let Some(flag) = iter.next() {
+        match flag.as_str() {
+            "--organization-id" => args.organization_id = iter.next(),
+            "--rules-path" => args.rules_path = iter.next(),
+            "--port" => {
+                if let Some(v) = iter.next() {
+                    match v.parse() {
+                        Ok(p) => args.port = p,
+                        Err(_) => {
+                            eprintln!("args: WARNING invalid --port {v:?}, using {DEFAULT_PORT}")
+                        }
+                    }
+                }
+            }
+            other => eprintln!("args: WARNING ignoring unknown argument {other:?}"),
+        }
+    }


I don't agree with copilot here, but you should make sure that the value doesn't start with -- as a minimal check

richardpringle · 2026-07-10T22:01:19Z

+    println!(
+        "keys: programmatic pubkey = {}",
+        keys.programmatic.public_key_hex()
+    );
+    println!(
+        "keys: admin pubkey        = {}",
+        keys.admin.public_key_hex()
+    );


nit:

Suggested change

println!(

"keys: programmatic pubkey = {}",

keys.programmatic.public_key_hex()

);

println!(

"keys: admin pubkey = {}",

keys.admin.public_key_hex()

);

println!(

r#"keys:

programmatic pubkey = {}

admin pubkey = {}"#,

keys.programmatic.public_key_hex(),

keys.admin.public_key_hex(),

);

richardpringle

Top notch 🥇

The only comment that I'm leaving in this review that I do feel strongly about is the mermaid diagram comment. The rest are even less minor than nits, take them or leave them... probably leave most of them 😅

richardpringle · 2026-07-10T22:06:41Z

+impl fmt::Display for ParseError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ParseError::Empty => write!(f, "empty transaction"),
+            ParseError::UnsupportedType(b) => {
+                write!(f, "unsupported transaction type byte {b:#04x}")
+            }
+            ParseError::Rlp(e) => write!(f, "malformed RLP: {e}"),
+        }
+    }
+}


Can use thiserror for this instead, I don't think it'll hurt compiles times that much and makes the code surface area a little smaller for someone reading

richardpringle · 2026-07-10T22:08:25Z

+        Turnkey policies evaluate the stamping API user:
+          • TVC programmatic  → policy ALLOW           → COMPLETED
+          • TVC admin         → require human consensus → CONSENSUS_NEEDED
+```


Would look nicer as a mermaid diagram

richardpringle · 2026-07-10T22:10:42Z

Just have the one comment about the mermaid diagram, otherwise, 🥇

richardpringle · 2026-07-10T22:11:03Z

richardpringle · 2026-07-10T22:12:33Z

+fn decode_transfer_args(input: &[u8]) -> Option<(Address, U256)> {
+    // 4 (selector) + 32 (address) + 32 (amount)
+    let args = input.get(4..68)?;
+    let (addr_word, amount_word) = args.split_at(32);
+    if addr_word[..12].iter().any(|&b| b != 0) {
+        return None; // address must be zero-padded in its 32-byte word
+    }
+    let recipient = Address::from_slice(&addr_word[12..]);
+    let amount = U256::from_be_slice(amount_word);
+    Some((recipient, amount))
+}


Agree, the copilot suggestion is a little more explicit... but 🤷 , I don't think it matters

richardpringle · 2026-07-10T22:14:36Z

+        let raw: RawRuleset = toml::from_str(EMBEDDED_RULES_TOML)
+            .map_err(|e| format!("parse embedded rules.toml: {e}"))?;
+        raw.into_ruleset()


Could use a LazyLock here so that you're not deserializing every time.

richardpringle · 2026-07-10T22:17:02Z

+/// sub-derived with the exact [`QOS_SIGN_PATH`]/[`QOS_ENCRYPT_PATH`] construction
+/// QOS uses. Each of a TVC's replicas boots its own ephemeral key.
+pub struct EphemeralKey {
+    signing_key: SigningKey,


Should we be using Zeroize here just to promote best practices with keys?

am-hernandez added 15 commits July 6, 2026 00:00

chore: scaffold cargo project with /health endpoint

42eb624

feat(keys): derive P256 API keys from quorum seed

1648fb3

feat(stamp): build Turnkey X-Stamp from signed request body

c515c13

feat(activity): build SIGN_TRANSACTION_V2 request body

75d5d83

feat(server): wire GET /pubkeys and POST /cosign

aaecf4e

feat(tx): parse unsigned EIP-1559/legacy transactions

6858730

feat(rules): classify transactions PROGRAMMATIC|ADMIN|REJECT

6a448ac

style: apply rustfmt and fix clippy lint

f08f3b9

feat(rules): gate on allowlisted signer address

5b47319

feat(proof): generate app proof

7456124

feat(config): configure via CLI args for pivotArgs deploy

53cf2bd

chore: add reproducible Dockerfile

115e49a

docs: add README

5d73f9b

fix(rules): embed ruleset in binary so it reaches the TVC enclave

6062513

docs(readme): CLI deploy flow, provenance, and quorum-key limitation

7ea2fa1

Add 'tvc-cosign/' from commit '7ea2fa180c24d1cb2ae8917a8987ff71577321f8'

7ce4dd7

git-subtree-dir: tvc-cosign git-subtree-mainline: 55e3e1b git-subtree-split: 7ea2fa1

am-hernandez force-pushed the am/example/tvc-cosign branch from 2327fe3 to 7ce4dd7 Compare July 10, 2026 14:57

am-hernandez requested a review from Copilot July 10, 2026 19:43

Copilot started reviewing on behalf of am-hernandez July 10, 2026 19:44 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

richardpringle reviewed Jul 10, 2026

View reviewed changes

richardpringle approved these changes Jul 10, 2026

View reviewed changes

		let organization_id = cli_organization_id
		.map(str::to_string)

Uh oh!

Conversation

am-hernandez commented Jul 10, 2026

Add tvc-cosign example

Testing

Note

Uh oh!

socket-security Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richardpringle Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richardpringle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

socket-security Bot commented Jul 10, 2026 •

edited

Loading

socket-security Bot commented Jul 10, 2026 •

edited

Loading

richardpringle Jul 10, 2026 •

edited

Loading