Security Overview - WalletSuite

WalletSuite’s security model has three orthogonal axes:

Axis	Members
Surface (how you integrate)	Hosted MCP · SDK · REST API
Signing layer (where keys live)	Non-custodial MPC threshold signing · External BYO (KMS / HSM / multisig — SDK or REST)
Cross-cutting controls	Tool profiles & scopes · Policy gates · Decision provenance · Audit trail · Structured errors · Input validation · Secret isolation · HTTPS

Trust Model

Component	Layer	Holds keys?	What it can access
WalletSuite REST API	Surface	No	Blockchain data, transaction preparation, fee estimation
Hosted MCP endpoint	Surface	No	Tool orchestration, input validation, tool-profile gating
SDK (`@walletsuite/wallet-sdk`)	Surface	No	Typed client; signer-agnostic
Agent key	Identity	No	Scoped, revocable agent identity; held server-side and used to authorize the agent. Grants no signing authority on its own
WalletSuite cosigner share	Signing	1 of 2 key shares	Fully-managed cosigner; envelope-encrypted at rest behind the scenes; releases its share only after policy clears
Customer share	Signing	1 of 2 key shares	Held customer-side in your own storage (database, HSM, device, or passkey-wrapped envelope); the WalletSuite cosigner never assembles it into a full key
External Signer (BYO)	Signing	Customer-managed	KMS / HSM / multisig — outside WalletSuite
Your LLM / chat	Caller	No	Proposes tool calls and reads responses. Holds no authority — the policy engine decides, not the model

Trust boundary: no single party ever holds enough to sign alone, regardless of which surface initiates the request.

Defense in Depth

1. Tool Profile · Agent surfaces

An agent’s callable surface is the server-owned tool profile bound to the agent, narrowed by the scopes in its short-lived token. Tools outside that intersection are never registered in the MCP schema handed to the agent — the model cannot discover, name, or call them, so a poisoned prompt or hostile tool output has nothing to invoke. The profile is set on WalletSuite’s side, never by the caller. SDK and REST have no equivalent: they expose their full surface to whatever code holds the key. See Execution Levels and Security & Trust (AI Agents).

2. Policy Gates · Signing layer

A deterministic policy decision point evaluates every signing intent before it can be signed. Your allowlist rules are opt-in and deny-by-default once armed: each rule matches on chain, operation type, contract address, method selector, an optional destination pin, and an optional per-transaction amount cap in base units, with a mandatory expiry. Intents on chains you’re not entitled to are denied, as are operations that can’t be typed. Rules roll out in stages: off, shadow, enforce. No LLM sits in the decision path, and the same gate applies whether the call comes from MCP, SDK, or REST. See Policy Gates.

3. Structured Errors · MCP + SDK

Every error includes a category and code. flow errors include a requiredAction. Agents recover programmatically. See Structured Errors.

4. Input Validation · All surfaces

Zod schemas (MCP/SDK) and request validators (REST) check inputs before they reach the API:

Address format per chain family (0x-prefixed for EVM, T-prefixed for Tron)
Amounts as positive numeric strings (no scientific notation)
Mutually exclusive fields (amount vs amountWei)
Token contracts validated when provided

5. Secret Isolation · All surfaces

Long-lived credentials stay server-side and never reach a tool argument, request body, or the model:

Agents: the agent’s key stays server-side and authorizes the agent; the raw key never reaches the model, a prompt, or a downstream MCP call. See Connect Your Agent.
SDK / REST: the x-api-key credential is sent only as a request header.

Secrets stay out of prompt history, tool-argument logs, and MCP traffic.

6. HTTPS Enforcement · All surfaces

Every WalletSuite endpoint and callback is HTTPS-only. External URLs (chain RPCs, webhook targets) are validated as HTTPS before use.

7. Audit Trail · Signing layer

Every sign_transaction and send_transaction operation appends a receipt to a hash-chained, append-only JSONL log — tamper-evident and exportable to your SIEM. See Audit Trail.

8. Decision Provenance · Signing layer

WalletSuite records a decision on every signing intent at the point it is authorized. Each record carries a policyDecisionId, the decision reason, and the matched rule when one admitted the operation. Allowed and denied intents alike are written to the signing-intents ledger, so a denial is durable evidence, not a silent drop. See Policy Decisions.

Surface-Specific Notes

Hosted MCP

The tool profile and token scopes bound which tools exist in the agent’s schema
Tool arguments carry only wallet identifiers, chain ids, and unsigned tx hex — never key material
The agent’s key stays server-side; the agent connects with a short-lived token — see Connect Your Agent
Closed-source orchestration; trust is enforced architecturally, not via source review

SDK

Signer-agnostic: composes with MPC or External BYO (KMS/HSM/multisig)
No tool profile — the SDK exposes its full surface to whatever code imports it
Typed errors share the category / code taxonomy with MCP

REST API

Stateless HTTPS with x-api-key header
Same input validation and structured error envelope as the SDK
Customer brings the signer (External BYO) or routes signing through hosted MPC

Non-Custodial Architecture

MPC threshold signing

WalletSuite operates a fully-managed cosigner holding one share; you hold the other share in your own storage (database, HSM, device, or passkey-wrapped envelope). Both are required for every signature.

Any surface (MCP/SDK/REST) → prepare unsigned tx (no key access)
                           → policy engine authorizes the intent
                           → customer share signs (customer-side storage)
                           → WalletSuite cosigner share signs (only after policy clears)
                           → combined threshold signature → broadcast
                           → neither party ever held a full key

No full private key ever exists. Both shares are required to produce a signature, and neither party can sign alone. See Key Management.

Attack Model

Hosted MCP endpoint compromised / poisoned prompt:

The model only ever sees its bounded tool surface — tools outside its profile and scopes were never registered, so there is nothing to invoke
No full key is exposed — no full key ever exists
Every signing intent still clears the policy engine; send_transaction additionally requires confirmBroadcast=true

WalletSuite cosigner share compromised:

Attacker has 1 of 2 shares — cannot produce a valid signature without the customer share
Internal access is M-of-N gated and audit-logged

Customer share compromised:

Attacker has 1 of 2 shares — cannot produce a valid signature without WalletSuite’s cosigner share
Policy gates are still evaluated on every co-signing request

Read-only agent (Read level): Worst case is information disclosure (balances, prices, transaction history). No signing scope is present, so no value can be moved. See Execution Levels.

What WalletSuite Does Not Do

Hold a full private key (one of two key shares only)
Custody funds
Sign transactions alone — both shares are required
Move funds without a passing policy decision

Remaining Risks

Non-custodial does not mean zero risk. Operator-side risks:

Granting a broader tool profile than the workflow needs
Leaking the agent’s key or an API key
Enabling signing before arming policy rules

Mitigation: Grant the narrowest tool profile, arm deny-by-default rules on the signing layer, and keep credentials server-side.

Practical Guidance

Control	Default	When to change
Tool profile	`read`	Raise to `prepare` / `execute` / `governed` as the workflow needs — see Execution Levels
Policy rules	None active	Arm deny-by-default rules before enabling signing — see Policy Gates
Broadcast	Requires `confirmBroadcast=true`	Confirm only transactions the agent presented clearly

See Production Checklist.

Key Management - MPC share custody and lifecycle
Audit Trail - co-signing event logging and SIEM export
Execution Levels - tool profiles and scopes per agent
Security & Trust (AI Agents) - the tool profile as prompt-injection boundary
Policy Gates - deny-by-default authorization on the signing layer
Responsible Disclosure

​Trust Model

​Defense in Depth

​1. Tool Profile · Agent surfaces

​2. Policy Gates · Signing layer

​3. Structured Errors · MCP + SDK

​4. Input Validation · All surfaces

​5. Secret Isolation · All surfaces

​6. HTTPS Enforcement · All surfaces

​7. Audit Trail · Signing layer

​8. Decision Provenance · Signing layer

​Surface-Specific Notes

​Hosted MCP

​SDK

​REST API

​Non-Custodial Architecture

​MPC threshold signing

​Attack Model

​What WalletSuite Does Not Do

​Remaining Risks

​Practical Guidance

​Related