feat(parser_http_server): CLI args for TVC pivot deploys

`tvc deploy create` has no env-var injection mechanism; pivot config
must arrive via `pivotArgs`. Convert parser_http_server's startup from
env-vars to clap-derive args:

  --port                          (env fallback HTTP_PORT)
  --gateway-signing-pubkey-hex    (env fallback GATEWAY_SIGNING_PUBKEY_HEX)

The ephemeral key path is no longer configurable — `EphemeralKeyHandle`
reads `qos_core::EPHEMERAL_KEY_FILE` directly, which already resolves
to `/qos.ephemeral.key` in TVC builds and `./local-enclave/...` in dev
via qos_core's cfg. No caller of parser_http_server overrides this
path today (compose targets parser_grpc_server, not http-server).

Drop `PaymentPolicy::from_env()` for `PaymentPolicy::from_hex(&str)`
when the arg is supplied, `Disabled` otherwise — identical behavior to
the previous env-only path, with no env coupling left in main.

Fix x402-devnet-playbook Part 2 which documented an `envVars` block in
the TVC deploy config that doesn't exist; show `pivotArgs` instead.

Also gitignore deploy-*.json so locally-generated TVC deploy configs
don't get staged accidentally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: prasanna-anchorage

.gitignore

@@ -4,3 +4,4 @@ docs/superpowers/
 .surfpool/
 node_modules/
 *.log
+deploy-*.json

docs/x402-devnet-playbook.md

@@ -714,21 +714,24 @@ Steps:
    # Prints GATEWAY_SIGNING_PUBKEY_HEX=<260-char-hex>
    ```
 
-2. **Deploy `parser_http_server` to TVC** with the public half pinned in
-   its env. Add to the TVC deploy config's env block:
+2. **Deploy `parser_http_server` to TVC** with the public half pinned at
+   pivot launch. `tvc deploy create` has no env-injection mechanism, so
+   the pubkey is passed via `pivotArgs` (clap on the binary side):
 
    ```json
    {
-     "envVars": [
-       { "name": "GATEWAY_SIGNING_PUBKEY_HEX",
-         "value": "<260-char-hex from step 1>" }
+     "pivotArgs": [
+       "--gateway-signing-pubkey-hex",
+       "<260-char-hex from step 1>"
      ]
    }
    ```
 
    After re-deploy, `parser_app` (linked into `parser_http_server`)
    rejects every parse request whose `payment_marker` doesn't carry a
-   VPM signed by exactly this key.
+   VPM signed by exactly this key. The HTTP listener defaults to port
+   3000; the ephemeral key is read from `qos_core::EPHEMERAL_KEY_FILE`
+   (provisioned by QOS) with no override.
 
 3. **Deploy `parser_gateway` outside TVC** with `HTTP_BACKEND_URL`
    pointing at the TVC app URL:

src/Cargo.lock

@@ -21,6 +21,10 @@ serde = { workspace = true }
 serde_json = { workspace = true }
 base64 = "0.22"
 
+# CLI args. TVC pivots receive config via `pivotArgs`, not env vars; clap's
+# `env = "..."` attribute keeps compose + integration tests working unchanged.
+clap = { version = "4.0", features = ["derive", "env"] }
+
 [lints]
 workspace = true
 

src/parser/http-server/Cargo.toml

@@ -21,14 +21,17 @@
 //!   visualsign-turnkey-client (and any HTTP-only client) keeps working
 //!   byte-for-byte.
 //! - `POST /visualsign/api/v2/parse` — same payload; additionally
-//!   enforces `GATEWAY_SIGNING_PUBKEY_HEX` when set (TVC-enforced mode
-//!   from plan v3). When unset, behaves the same as v1.
+//!   enforces a pinned gateway pubkey when supplied (TVC-enforced mode
+//!   from plan v3). When omitted, behaves the same as v1.
 //!
-//! Env vars:
-//! - `HTTP_PORT` (default: 3000) — Turnkey TVC public ingress default.
-//! - `EPHEMERAL_FILE` (required) — path to the parser_app ephemeral key.
-//! - `GATEWAY_SIGNING_PUBKEY_HEX` (optional) — pinned gateway P256 sign
-//!   pubkey for VPM verification on v2.
+//! Configuration (CLI args; env vars listed are clap fallbacks):
+//! - `--port <u16>` / `HTTP_PORT` (default 3000) — Turnkey TVC public ingress.
+//! - `--gateway-signing-pubkey-hex <hex>` / `GATEWAY_SIGNING_PUBKEY_HEX`
+//!   (optional) — pinned gateway P256 sign pubkey for VPM verification on v2.
+//!
+//! The ephemeral key is read from `qos_core::EPHEMERAL_KEY_FILE` (provisioned
+//! by QOS inside the enclave). No override flag — if a deployment ever needs
+//! a non-canonical path, bind-mount it instead.
 
 use axum::{
     Json, Router,
@@ -37,6 +40,7 @@ use axum::{
     routing::{get, post},
 };
 use base64::Engine;
+use clap::Parser;
 use generated::parser::{Chain, ChainMetadata, SignatureScheme};
 use host_primitives::turnkey::{
     TurnkeyParsedTransaction, TurnkeyPayload, TurnkeyRequestWrapper, TurnkeyResponse,
@@ -49,11 +53,26 @@ use qos_p256::P256Pair;
 use std::net::SocketAddr;
 use std::sync::Arc;
 
+#[derive(Parser, Debug)]
+#[command(version = env!("VERSION"))]
+struct Args {
+    /// HTTP port to listen on.
+    #[arg(long, env = "HTTP_PORT", default_value_t = 3000)]
+    port: u16,
+
+    /// Hex-encoded P256 SEC1 uncompressed sign pubkey of `parser_gateway`.
+    /// When supplied, `/visualsign/api/v2/parse` is TVC-enforced: it
+    /// requires a valid VerifiedPaymentMarker signed by this key.
+    /// When omitted, v2 behaves the same as v1.
+    #[arg(long, env = "GATEWAY_SIGNING_PUBKEY_HEX")]
+    gateway_signing_pubkey_hex: Option<String>,
+}
+
 #[derive(Clone)]
 struct AppState {
     ephemeral_key: Arc<P256Pair>,
-    /// Disabled when GATEWAY_SIGNING_PUBKEY_HEX is unset. The v1 route
-    /// always passes `Disabled`; the v2 route uses this policy.
+    /// Disabled when `--gateway-signing-pubkey-hex` is unset. The v1
+    /// route always passes `Disabled`; the v2 route uses this policy.
     policy: Arc<PaymentPolicy>,
 }
 
@@ -180,28 +199,27 @@ fn handle_parse(
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let port: u16 = std::env::var("HTTP_PORT")
-        .ok()
-        .and_then(|s| s.parse().ok())
-        .unwrap_or(3000);
-
-    let ephemeral_file = std::env::var("EPHEMERAL_FILE")
-        .unwrap_or_else(|_| "integration/fixtures/ephemeral.secret".to_string());
-    let handle = EphemeralKeyHandle::new(ephemeral_file.clone());
+    let args = Args::parse();
+
+    let handle = EphemeralKeyHandle::new(qos_core::EPHEMERAL_KEY_FILE.to_string());
     let ephemeral_key = handle
         .get_ephemeral_key()
         .expect("failed to load ephemeral key");
     eprintln!(
-        "parser_http_server {} loaded ephemeral key from {ephemeral_file}",
-        env!("VERSION")
+        "parser_http_server {} loaded ephemeral key from {}",
+        env!("VERSION"),
+        qos_core::EPHEMERAL_KEY_FILE,
     );
 
-    let policy =
-        PaymentPolicy::from_env().expect("invalid GATEWAY_SIGNING_PUBKEY_HEX configuration");
+    let policy = match args.gateway_signing_pubkey_hex.as_deref() {
+        Some(hex) => PaymentPolicy::from_hex(hex)
+            .expect("invalid --gateway-signing-pubkey-hex configuration"),
+        None => PaymentPolicy::Disabled,
+    };
     if matches!(policy, PaymentPolicy::Required { .. }) {
-        eprintln!("v2 route is TVC-enforced (GATEWAY_SIGNING_PUBKEY_HEX is set)");
+        eprintln!("v2 route is TVC-enforced (gateway signing pubkey supplied)");
     } else {
-        eprintln!("v2 route is open (GATEWAY_SIGNING_PUBKEY_HEX unset)");
+        eprintln!("v2 route is open (no gateway signing pubkey)");
     }
 
     let state = AppState {
@@ -215,7 +233,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         .route("/visualsign/api/v2/parse", post(parse_v2))
         .with_state(state);
 
-    let addr = SocketAddr::from(([0, 0, 0, 0], port));
+    let addr = SocketAddr::from(([0, 0, 0, 0], args.port));
     eprintln!("parser_http_server listening on {addr}");
     let listener = tokio::net::TcpListener::bind(addr).await?;
     axum::serve(listener, app)