fix(api-keys): support imported key wallets

Reuse the existing KeyType-aware secret resolution for API-key signing so imported private-key wallets no longer get parsed as mnemonics.

Add Rust and Node regressions for API-key signing on imported wallets, and update API-key docs/comments to describe encrypted secret copies instead of mnemonic-only copies.

Author: ggonzalez94

bindings/node/__test__/index.spec.mjs

@@ -301,6 +301,53 @@ describe('@open-wallet-standard/core', () => {
     deleteWallet(wallet.id, vaultDir);
   });
 
+  it('signs with an API key for a wallet imported from a private key', () => {
+    createPolicy(JSON.stringify({
+      id: 'test-imported-wallet',
+      name: 'Imported Wallet',
+      version: 1,
+      created_at: '2026-03-31T00:00:00Z',
+      rules: [
+        { type: 'allowed_chains', chain_ids: ['eip155:8453'] },
+      ],
+      action: 'deny',
+    }), vaultDir);
+
+    const wallet = importWalletPrivateKey(
+      'policy-imported-wallet',
+      'ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+      '',
+      vaultDir,
+      'evm',
+    );
+    const key = createApiKey(
+      'imported-wallet-agent',
+      [wallet.id],
+      ['test-imported-wallet'],
+      '',
+      null,
+      vaultDir,
+    );
+
+    const msgSig = signMessage(
+      wallet.id,
+      'base',
+      'hello',
+      key.token,
+      undefined,
+      undefined,
+      vaultDir,
+    );
+    assert.ok(msgSig.signature.length > 0);
+
+    const txSig = signTransaction(wallet.id, 'base', 'deadbeef', key.token, null, vaultDir);
+    assert.ok(txSig.signature.length > 0);
+
+    revokeApiKey(key.id, vaultDir);
+    deletePolicy('test-imported-wallet', vaultDir);
+    deleteWallet(wallet.id, vaultDir);
+  });
+
   it('executable policy gates signing', () => {
     const wallet = createWallet('exe-test', undefined, 12, vaultDir);
 

docs/01-storage-format.md

@@ -129,11 +129,11 @@ Each API key is stored as a JSON file in `~/.ows/keys/`. The key file contains m
 | `wallet_ids` | array | yes | Wallet IDs this key is authorized to access |
 | `policy_ids` | array | yes | Policy IDs evaluated on every request made with this key |
 | `expires_at` | string | no | ISO 8601 expiry timestamp. `null` means no expiry. |
-| `wallet_secrets` | object | yes | Map of wallet ID → CryptoEnvelope. Each entry is the wallet's mnemonic re-encrypted under HKDF(token). |
+| `wallet_secrets` | object | yes | Map of wallet ID → CryptoEnvelope. Each entry is the wallet's decrypted secret re-encrypted under HKDF(token), whether that secret is a mnemonic phrase or private-key JSON. |
 
 The `keys/` directory and its contents use the same strict permissions as `wallets/` (`700` for the directory, `600` for files) because `wallet_secrets` contains encrypted key material and `token_hash` must be protected against local reads.
 
-Revoking an API key means deleting the key file. The encrypted mnemonic copies are destroyed. The original wallet file and other API keys are unaffected.
+Revoking an API key means deleting the key file. The encrypted secret copies are destroyed. The original wallet file and other API keys are unaffected.
 
 ### Crypto Object
 

docs/03-policy-engine.md

@@ -29,7 +29,7 @@ If the owner wants policy-constrained access for themselves, they create an API
 
 ### Token-as-capability
 
-When the owner creates an API key, OWS decrypts the wallet mnemonic using the owner's passphrase and **re-encrypts it under a key derived from the API token**. The encrypted copy is stored in the API key file. The agent presents the token with each signing request; the token serves as both authentication and decryption capability.
+When the owner creates an API key, OWS decrypts the wallet secret using the owner's passphrase and **re-encrypts it under a key derived from the API token**. The encrypted copy is stored in the API key file. The agent presents the token with each signing request; the token serves as both authentication and decryption capability.
 
 ### Key derivation (HKDF-SHA256)
 
@@ -62,14 +62,14 @@ ows key create --name "claude-agent" --wallet agent-treasury --policy spending-l
 ```
 
 1. Owner enters wallet passphrase
-2. OWS decrypts the wallet mnemonic using scrypt(passphrase)
+2. OWS decrypts the wallet secret using scrypt(passphrase)
 3. Generates random token: `T = "ows_key_" + hex(random 256 bits)`
 4. Generates random salt S
 5. Derives key: `K = HKDF-SHA256(S, T, "ows-api-key-v1", 32)`
-6. Encrypts mnemonic with K via AES-256-GCM
-7. Stores key file with `token_hash: SHA256(T)`, policy IDs, and encrypted mnemonic copy
+6. Encrypts the wallet secret with K via AES-256-GCM
+7. Stores key file with `token_hash: SHA256(T)`, policy IDs, and encrypted secret copy
 8. Displays T once — owner provisions it to the agent
-9. Zeroizes mnemonic from memory
+9. Zeroizes the decrypted secret from memory
 
 ### Agent signing flow
 
@@ -84,16 +84,16 @@ Agent calls: sign_transaction(wallet, chain, tx, "ows_key_a1b2c3...")
 6. Build `PolicyContext` (chain ID, wallet ID, API key ID, transaction context, spending context, timestamp)
 7. Evaluate all policies (AND semantics, short-circuit on first deny)
 8. If denied → return POLICY_DENIED error (key material never touched)
-9. HKDF-SHA256(salt, token) → AES key → decrypt mnemonic from key.wallet_secrets
-10. HD-derive chain-specific key
+9. HKDF-SHA256(salt, token) → AES key → decrypt secret from key.wallet_secrets
+10. Resolve the chain-specific signing key from that secret (HD derivation for mnemonic wallets, direct curve-key selection for private-key wallets)
 11. Sign transaction
-12. Zeroize mnemonic and derived key
+12. Zeroize decrypted secret and derived key
 13. Return signature
 ```
 
 ### Revocation
 
-Delete the API key file. The encrypted mnemonic copy is gone. `SHA256(T)` matches nothing. The token is useless. The original wallet and other API keys are unaffected.
+Delete the API key file. The encrypted secret copy is gone. `SHA256(T)` matches nothing. The token is useless. The original wallet and other API keys are unaffected.
 
 ### Security properties
 

docs/05-key-isolation.md

@@ -87,7 +87,7 @@ Agent → sign_transaction(wallet, chain, tx, "ows_key_...")
           │
           └─► ows-lib (same process)
                 ├── token lookup + policy evaluation
-                ├── HKDF decrypt mnemonic (mlock'd, zeroized on drop)
+                ├── HKDF decrypt wallet secret (mlock'd, zeroized on drop)
                 ├── sign
                 └── return signature
 ```
@@ -103,14 +103,14 @@ Agent → sign_transaction(wallet, chain, tx, "ows_key_...")
                 ├── token lookup + policy evaluation
                 └── fork/exec ows-enclave
                       ├── receive (token, wallet_id, tx) over stdin
-                      ├── HKDF decrypt mnemonic
+                      ├── HKDF decrypt wallet secret
                       ├── sign
                       ├── zeroize
                       ├── write signature to stdout
                       └── exit
 ```
 
-The decrypt→sign→wipe path moves to a child process. The parent (agent's process) never has the mnemonic in its address space. The child is stateless — spawned per request, no daemon, no unlock step. If it crashes, the next request spawns a new one.
+The decrypt→sign→wipe path moves to a child process. The parent (agent's process) never has the decrypted secret in its address space. The child is stateless — spawned per request, no daemon, no unlock step. If it crashes, the next request spawns a new one.
 
 ## References
 

docs/sdk-cli.md

@@ -196,7 +196,7 @@ Lists all keys with ID, name, wallets, policies, and creation time. Tokens are n
 ows key revoke --id <key-id> --confirm
 ```
 
-Deletes the key file. The encrypted mnemonic copy is gone — the token becomes useless.
+Deletes the key file. The encrypted secret copy is gone — the token becomes useless.
 
 ## End-to-End Example: Agent Access
 

ows/crates/ows-core/src/api_key.rs

@@ -16,7 +16,7 @@ pub struct ApiKeyFile {
     /// Optional expiry timestamp.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub expires_at: Option<String>,
-    /// Per-wallet encrypted mnemonic copies, keyed by wallet ID.
+    /// Per-wallet encrypted secret copies, keyed by wallet ID.
     /// Each value is a CryptoEnvelope encrypted with HKDF(token).
     pub wallet_secrets: HashMap<String, serde_json::Value>,
 }

ows/crates/ows-lib/src/key_ops.rs

@@ -1,10 +1,8 @@
 use std::collections::HashMap;
 use std::path::Path;
 
-use ows_core::{ApiKeyFile, OwsError};
-use ows_signer::{
-    decrypt, encrypt_with_hkdf, signer_for_chain, CryptoEnvelope, HdDeriver, Mnemonic, SecretBytes,
-};
+use ows_core::{ApiKeyFile, KeyType, OwsError};
+use ows_signer::{decrypt, encrypt_with_hkdf, signer_for_chain, CryptoEnvelope, SecretBytes};
 
 use crate::error::OwsLibError;
 use crate::key_store;
@@ -15,9 +13,9 @@ use crate::vault;
 /// Create an API key for agent access to one or more wallets.
 ///
 /// 1. Authenticates with the owner's passphrase
-/// 2. Decrypts the mnemonic for each wallet
+/// 2. Decrypts the wallet secret for each wallet
 /// 3. Generates a random token (`ows_key_...`)
-/// 4. Re-encrypts each mnemonic under HKDF(token)
+/// 4. Re-encrypts each secret under HKDF(token)
 /// 5. Stores the key file with token hash, policy IDs, and encrypted copies
 /// 6. Returns the raw token (shown once to the user)
 pub fn create_api_key(
@@ -77,8 +75,8 @@ pub fn create_api_key(
 /// 1. Look up key file by SHA256(token)
 /// 2. Check expiry and wallet scope
 /// 3. Load and evaluate policies
-/// 4. HKDF(token) → decrypt mnemonic
-/// 5. HD derive → sign
+/// 4. HKDF(token) → decrypt wallet secret
+/// 5. Resolve signing key → sign
 pub fn sign_with_api_key(
     token: &str,
     wallet_name_or_id: &str,
@@ -133,8 +131,15 @@ pub fn sign_with_api_key(
         }));
     }
 
-    // 6. Decrypt mnemonic from key file using HKDF(token)
-    let key = decrypt_key_from_api_key(&key_file, &wallet.id, token, chain.chain_type, index)?;
+    // 6. Decrypt wallet secret from key file using HKDF(token)
+    let key = decrypt_key_from_api_key(
+        &key_file,
+        &wallet.id,
+        wallet.key_type.clone(),
+        token,
+        chain.chain_type,
+        index,
+    )?;
 
     // 7. Sign (extract signable portion first — e.g. strips Solana sig-slot headers)
     let signer = signer_for_chain(chain.chain_type);
@@ -195,7 +200,14 @@ pub fn sign_message_with_api_key(
         }));
     }
 
-    let key = decrypt_key_from_api_key(&key_file, &wallet.id, token, chain.chain_type, index)?;
+    let key = decrypt_key_from_api_key(
+        &key_file,
+        &wallet.id,
+        wallet.key_type.clone(),
+        token,
+        chain.chain_type,
+        index,
+    )?;
     let signer = signer_for_chain(chain.chain_type);
     let output = signer.sign_message(key.expose(), msg_bytes)?;
 
@@ -255,7 +267,14 @@ pub fn enforce_policy_and_decrypt_key(
         }));
     }
 
-    let key = decrypt_key_from_api_key(&key_file, &wallet.id, token, chain.chain_type, index)?;
+    let key = decrypt_key_from_api_key(
+        &key_file,
+        &wallet.id,
+        wallet.key_type.clone(),
+        token,
+        chain.chain_type,
+        index,
+    )?;
 
     Ok((key, key_file))
 }
@@ -297,6 +316,7 @@ fn load_policies_for_key(
 fn decrypt_key_from_api_key(
     key_file: &ApiKeyFile,
     wallet_id: &str,
+    key_type: KeyType,
     token: &str,
     chain_type: ows_core::ChainType,
     index: Option<u32>,
@@ -309,17 +329,7 @@ fn decrypt_key_from_api_key(
 
     let envelope: CryptoEnvelope = serde_json::from_value(envelope_value.clone())?;
     let secret = decrypt(&envelope, token)?;
-
-    // The secret is a mnemonic phrase — derive the signing key
-    let phrase = std::str::from_utf8(secret.expose())
-        .map_err(|_| OwsLibError::InvalidInput("wallet contains invalid UTF-8 mnemonic".into()))?;
-    let mnemonic = Mnemonic::from_phrase(phrase)?;
-    let signer = signer_for_chain(chain_type);
-    let path = signer.default_derivation_path(index.unwrap_or(0));
-    let curve = signer.curve();
-    Ok(HdDeriver::derive_from_mnemonic_cached(
-        &mnemonic, "", &path, curve,
-    )?)
+    crate::ops::secret_to_signing_key(&secret, key_type, chain_type, index)
 }
 
 #[cfg(test)]
@@ -557,6 +567,67 @@ mod tests {
         assert!(!sign_result.signature.is_empty());
     }
 
+    #[test]
+    fn imported_private_key_wallet_signs_with_api_key() {
+        let dir = tempfile::tempdir().unwrap();
+        let vault = dir.path().to_path_buf();
+
+        let wallet = crate::import_wallet_private_key(
+            "imported-wallet",
+            "ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+            Some("evm"),
+            Some(""),
+            Some(&vault),
+            None,
+            None,
+        )
+        .unwrap();
+        let policy_id = setup_test_policy(&vault);
+
+        let (token, _) = create_api_key(
+            "imported-wallet-agent",
+            std::slice::from_ref(&wallet.id),
+            std::slice::from_ref(&policy_id),
+            "",
+            None,
+            Some(&vault),
+        )
+        .unwrap();
+
+        let chain = ows_core::parse_chain("base").unwrap();
+        let tx_bytes = vec![0u8; 32];
+
+        let tx_result = sign_with_api_key(
+            &token,
+            "imported-wallet",
+            &chain,
+            &tx_bytes,
+            None,
+            Some(&vault),
+        );
+        assert!(
+            tx_result.is_ok(),
+            "sign_with_api_key failed: {:?}",
+            tx_result.err()
+        );
+        assert!(!tx_result.unwrap().signature.is_empty());
+
+        let msg_result = sign_message_with_api_key(
+            &token,
+            "imported-wallet",
+            &chain,
+            b"hello",
+            None,
+            Some(&vault),
+        );
+        assert!(
+            msg_result.is_ok(),
+            "sign_message_with_api_key failed: {:?}",
+            msg_result.err()
+        );
+        assert!(!msg_result.unwrap().signature.is_empty());
+    }
+
     #[test]
     fn sign_with_api_key_wrong_chain_denied() {
         let dir = tempfile::tempdir().unwrap();