feat(setup): skip OAuth sign-in when a live API key is configured

setup forced an OAuth sign-in, and its account-uid lookup (needed for the
wallet-binding deeplink) was OAuth-bearer-only — so a user who authenticates
via the agent-trade-kit API key could not complete setup without also doing
OAuth. Now:

- account_query::fetch_account_uid resolves auth like require_auth: OAuth
  bearer first, else a live HMAC API key from ~/.okx/config.toml signed with
  OKX OK-ACCESS-* headers (HMAC-SHA256, verified against a reference vector).
  On the fallback path the base URL is region-derived (US -> us.okx.com, EEA
  rejected) via the shared util::fallback_rest_base helper.
- run_wizard skips the OAuth sign-in step entirely when a live API key is
  present (the key authenticates the uid lookup), printing an info line.
- util: extract fallback_rest_base (region -> REST host, EEA errors) and reuse
  it in require_auth so REST and the uid lookup share one source of truth.
- Cargo: hmac + base64 promoted to direct deps, sha2 made non-optional (all
  already in the lockfile transitively); auth-installer feature no longer needs
  dep:sha2.

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

Author: weilong.yang

Cargo.lock

@@ -67,8 +67,13 @@ hex = "0.4"
 # `image` crate pulled in).
 qrcode = { version = "0.14", default-features = false, features = ["svg"] }
 
-# SHA-256 verification for the self-installer (auth-installer feature only).
-sha2 = { version = "0.10.9", optional = true }
+# SHA-256: the self-installer's checksum verifier and the OKX HMAC signature
+# used by the API-key fallback in `account_query` (always compiled).
+sha2 = { version = "0.10.9" }
+# OKX `OK-ACCESS-SIGN` HMAC-SHA256 for the account-uid API-key fallback
+# (`account_query`). Both already in the lockfile transitively via the SDK.
+hmac = "0.12"
+base64 = "0.22"
 
 # Platform IPC for reading the okx-auth access token (see auth_token), plus
 # hostname lookup for the encrypted-file keyring's machine identity.
@@ -106,7 +111,7 @@ websocket = ["okx-outcomes-sdk/websocket", "dep:ratatui", "dep:unicode-width"]
 # Disable for sandboxed builds that must not self-install (e.g.
 # `cargo build --no-default-features --features websocket`); the OKX_AUTH_BIN
 # location override stays available regardless.
-auth-installer = ["dep:sha2"]
+auth-installer = []
 # End-to-end self-test runner (`okx-outcomes selftest`). NOT in default — the
 # public release binary should not ship an order-placing self-runner. Needs the
 # tokio subprocess + io-util APIs and the `ws` surface it exercises.

Cargo.toml

@@ -1,10 +1,14 @@
-//! OAuth-authenticated query for the caller's OKX account `uid`.
+//! Query for the caller's OKX account `uid`.
 //!
 //! Intentionally outside the SDK: a self-contained raw HTTP call to OKX's
-//! "Get account configuration" endpoint (`GET /api/v5/account/config`) using
-//! the OAuth **bearer token** from the `okx-auth` broker, plus parsing to pull
-//! the `uid` out of the response. Required by the setup workflow, so it is
-//! always compiled (not feature-gated).
+//! "Get account configuration" endpoint (`GET /api/v5/account/config`), plus
+//! parsing to pull the `uid` out of the response. Required by the setup
+//! workflow (the wallet-binding deeplink), so it is always compiled.
+//!
+//! Auth mirrors [`crate::util::require_auth`]: the OAuth **bearer token** from
+//! the `okx-auth` broker when a session exists, otherwise a live **HMAC API
+//! key** from `~/.okx/config.toml` (`OK-ACCESS-*` headers). The fallback lets
+//! `setup` resolve the uid without an OAuth sign-in when an API key is present.
 
 use serde::Deserialize;
 
@@ -69,14 +73,37 @@ fn resolve_api_base() -> String {
     base.trim_end_matches('/').to_string()
 }
 
-/// Fetch the caller's account `uid` using the OAuth bearer token from the
-/// `okx-auth` broker (the token reflects the session established at `login`).
+/// Fetch the caller's account `uid`, OAuth-bearer-first with an HMAC API-key
+/// fallback (mirrors [`crate::util::require_auth`]).
 ///
-/// The base URL comes from config.json (else [`DEFAULT_API_BASE`]).
-/// The bearer token is never logged.
+/// On the fallback path the base URL is derived from the profile's region
+/// (`config.json` wins if set), since the HMAC key is region-scoped. No
+/// credential value is ever logged.
 pub async fn fetch_account_uid() -> Result<String, String> {
-    let token = super::auth_token::fetch_token().map_err(|e| e.to_string())?;
-    let url = format!("{}{ACCOUNT_CONFIG_PATH}", resolve_api_base());
+    // Pick the auth method and the matching base URL.
+    let (auth, base) = match super::auth_token::fetch_token() {
+        Ok(token) => (Auth::Bearer(token), resolve_api_base()),
+        Err(oauth_err) => match crate::util::live_api_key_lookup() {
+            crate::util::ApiKeyLookup::Found { creds, site } => {
+                let base = match crate::util::resolve_api_base_opt() {
+                    Some(b) => b.trim_end_matches('/').to_string(),
+                    None => crate::util::fallback_rest_base(site)?,
+                };
+                (Auth::Hmac(creds), base)
+            }
+            crate::util::ApiKeyLookup::DemoOnly => {
+                return Err(
+                    "found only a demo profile in ~/.okx/config.toml — the outcomes API has \
+                     no simulated-trading mode. Configure a live (non-demo) profile, or run \
+                     `okx-outcomes auth login`."
+                        .to_string(),
+                );
+            }
+            crate::util::ApiKeyLookup::None => return Err(oauth_err.to_string()),
+        },
+    };
+
+    let url = format!("{base}{ACCOUNT_CONFIG_PATH}");
 
     // Honor a caller-installed HTTP client (see `crate::set_http_client`) so
     // this raw call shares the same routing as the SDK — e.g. a client with
@@ -90,9 +117,24 @@ pub async fn fetch_account_uid() -> Result<String, String> {
             .build()
             .map_err(|e| format!("failed to build HTTP client: {e}"))?,
     };
-    let resp = client
-        .get(&url)
-        .bearer_auth(&token)
+
+    let req = client.get(&url);
+    let req = match &auth {
+        Auth::Bearer(token) => req.bearer_auth(token),
+        Auth::Hmac(creds) => {
+            // OKX HMAC: prehash = timestamp + METHOD + requestPath (+ body).
+            // No body or query string on this GET.
+            let timestamp = okx_timestamp();
+            let prehash = format!("{timestamp}GET{ACCOUNT_CONFIG_PATH}");
+            let sign = hmac_sha256_base64(&creds.secret_key, &prehash);
+            req.header("OK-ACCESS-KEY", &creds.api_key)
+                .header("OK-ACCESS-SIGN", sign)
+                .header("OK-ACCESS-TIMESTAMP", &timestamp)
+                .header("OK-ACCESS-PASSPHRASE", &creds.passphrase)
+        }
+    };
+
+    let resp = req
         .send()
         .await
         .map_err(|e| format!("request failed: {e}"))?;
@@ -108,6 +150,32 @@ pub async fn fetch_account_uid() -> Result<String, String> {
     parse_uid(&body)
 }
 
+/// Account auth for the uid lookup: an OAuth bearer token, or HMAC API-key
+/// credentials for the `OK-ACCESS-*` signed-request fallback.
+enum Auth {
+    Bearer(String),
+    Hmac(okx_outcomes_sdk::ApiCredentials),
+}
+
+/// OKX request timestamp: ISO-8601 UTC with millisecond precision, e.g.
+/// `2020-12-08T09:08:57.715Z` — the form `OK-ACCESS-TIMESTAMP` expects.
+fn okx_timestamp() -> String {
+    chrono::Utc::now()
+        .format("%Y-%m-%dT%H:%M:%S%.3fZ")
+        .to_string()
+}
+
+/// `OK-ACCESS-SIGN` = Base64(HMAC-SHA256(secret_key, prehash)).
+fn hmac_sha256_base64(secret_key: &str, prehash: &str) -> String {
+    use base64::Engine as _;
+    use hmac::{Hmac, Mac};
+    use sha2::Sha256;
+    let mut mac = <Hmac<Sha256>>::new_from_slice(secret_key.as_bytes())
+        .expect("HMAC-SHA256 accepts a key of any length");
+    mac.update(prehash.as_bytes());
+    base64::engine::general_purpose::STANDARD.encode(mac.finalize().into_bytes())
+}
+
 #[cfg(test)]
 #[allow(clippy::unwrap_used, clippy::expect_used)]
 mod tests {
@@ -141,4 +209,15 @@ mod tests {
             .unwrap_err()
             .contains("parse response JSON"));
     }
+
+    #[test]
+    fn hmac_sign_matches_reference_vector() {
+        // Reference computed with Python's hmac/hashlib (RFC 2104 HMAC-SHA256,
+        // base64-encoded) — must match OKX's `OK-ACCESS-SIGN` scheme.
+        let sign = super::hmac_sha256_base64(
+            "test-secret-key",
+            "2020-12-08T09:08:57.715ZGET/api/v5/account/config",
+        );
+        assert_eq!(sign, "JhnPMxZeBAZBDiFbXMp1ijlwS2s/WCCTsq6+8s0aTd8=");
+    }
 }

src/account_query.rs

@@ -391,18 +391,27 @@ async fn run_wizard() -> Result<(), String> {
     //    and continue so the user can still save credentials now and sign in
     //    later with `auth login`.
     println!();
-    println!(
-        "  {} Signing in to your OKX account ({})…",
-        "->".with(Color::Cyan),
-        region.label()
-    );
-    match super::auth_cmds::perform_login(Some(region.okx_auth_site())).await {
-        Ok(()) => println!("  {} signed in.", "+".with(Color::Green)),
-        Err(e) => eprintln!(
-            "  {} sign-in did not complete ({e}). Continuing — an existing session \
-             (if any) will still be used.",
-            "!".with(Color::Yellow)
-        ),
+    if crate::util::has_live_api_key() {
+        // A live API key in ~/.okx/config.toml already authenticates the account
+        // (including the uid lookup below), so the OAuth sign-in is unnecessary.
+        println!(
+            "  {} API key found in ~/.okx/config.toml — skipping OAuth sign-in.",
+            "i".with(Color::Cyan)
+        );
+    } else {
+        println!(
+            "  {} Signing in to your OKX account ({})…",
+            "->".with(Color::Cyan),
+            region.label()
+        );
+        match super::auth_cmds::perform_login(Some(region.okx_auth_site())).await {
+            Ok(()) => println!("  {} signed in.", "+".with(Color::Green)),
+            Err(e) => eprintln!(
+                "  {} sign-in did not complete ({e}). Continuing — an existing session \
+                 (if any) will still be used.",
+                "!".with(Color::Yellow)
+            ),
+        }
     }
 
     // Look up the account uid for the address-binding deeplink. This works off

src/setup_cmds.rs

@@ -171,20 +171,7 @@ pub fn require_auth(_args: &[String]) -> Result<okx_outcomes_sdk::OutcomesSdkCli
     if !base.is_empty() {
         builder = builder.base_url(base);
     } else if let Some(site) = fallback_site {
-        match site {
-            ProfileSite::Eea => {
-                return Err(format!(
-                    "the API key in ~/.okx/config.toml targets the EEA region (my.okx.com), \
-                     which {APP_NAME} does not support. Use a Global or US profile there, \
-                     or run `{APP_NAME} auth login`."
-                ));
-            }
-            ProfileSite::Us => {
-                builder = builder.base_url(crate::setup_cmds::RegionChoice::Us.rest_host());
-            }
-            // Global / Unknown → the SDK default (global, www.okx.com) is correct.
-            ProfileSite::Global | ProfileSite::Unknown => {}
-        }
+        builder = builder.base_url(fallback_rest_base(site)?);
     }
     let lang = config_value("lang");
     if !lang.is_empty() {
@@ -270,6 +257,26 @@ pub(crate) fn has_live_api_key() -> bool {
     matches!(live_api_key_lookup(), ApiKeyLookup::Found { .. })
 }
 
+/// REST base URL for the API-key fallback path given a profile's region, used
+/// when no explicit outcomes `api_base` is configured. The HMAC key is
+/// region-scoped, so a US key must hit the US host rather than the default
+/// global endpoint. Errors for EEA — the outcomes API has no EEA endpoint.
+/// Shared by `require_auth` (REST) and `account_query` (the setup uid lookup).
+pub(crate) fn fallback_rest_base(site: ProfileSite) -> Result<String, String> {
+    use crate::setup_cmds::RegionChoice;
+    match site {
+        ProfileSite::Eea => Err(format!(
+            "the API key in ~/.okx/config.toml targets the EEA region (my.okx.com), \
+             which {APP_NAME} does not support. Use a Global or US profile there, \
+             or run `{APP_NAME} auth login`."
+        )),
+        ProfileSite::Us => Ok(RegionChoice::Us.rest_host().to_string()),
+        ProfileSite::Global | ProfileSite::Unknown => {
+            Ok(RegionChoice::Global.rest_host().to_string())
+        }
+    }
+}
+
 /// Select the first live (`demo != true`) profile from a `~/.okx/config.toml`
 /// document and return its HMAC credentials.
 ///