Feature/unsupported errors

README.md

@@ -63,7 +63,8 @@ npm install @axionvera/pocketpay-sdk
 - [SDK Diagnostics](./docs/diagnostics.md) - Opt-in redacted lifecycle hooks and support-safe reports
 - [Logging: Transaction Payloads & Debug Mode](./docs/logging-payloads-and-debug.md) - Safely logging signed transaction XDR, memos, and debug output
 - [Security Best Practices](./docs/security.md) - Key management and transaction safety
-- [SDK Security Threat Model](./docs/security_threat_model.md) - Trust boundaries, wallet risks, and mitigation strategies for the SDK environment
+- [SDK Security Threat Model](./docs/security_threat_model.md) - Trust boundaries, secret handling, transaction submission risks, mitigation strategies, and consumer responsibilities
+- [Signing Boundaries](./docs/signing-boundaries.md) - Detailed rules on secret boundaries, capability checking, and transaction signing limits
 - [Dependency Review](./docs/dependency-review.md) - How SDK dependencies are evaluated, added, updated, and justified
 - [Wallet Recovery Limitations](./docs/wallet-recovery-limitations.md) - What happens when keys are lost, what the SDK does not provide, and your application's responsibilities
 - [Wallet Secret Export Policy](./docs/wallet-secret-export.md) - Supported local-key access, unsupported export behaviour, security risks, and consumer responsibilities

src/soroban/index.ts

@@ -7,8 +7,13 @@
  * NOTE: This module requires a deployed Soroban vault contract.
  * The contract ID should be provided via params or VAULT_CONTRACT_ID env var.
  *
- * @security See the [SDK Security Threat Model](../../docs/security_threat_model.md)
- * for risks related to contract ID spoofing and malicious payload injection.
+ * @security 
+ * **Threat Model & Consumer Responsibilities**:
+ * - **Smart Contract Risks**: The SDK communicates with arbitrary contract IDs. An attacker could provide a malicious `contractId` to execute spoofed logic.
+ * - **Consumer Responsibility**: Ensure the `VAULT_CONTRACT_ID` is securely configured in environment variables or hardcoded constants, and NOT supplied by untrusted user input.
+ * - **Mitigation**: The SDK enforces strict type-checking and sanitizes inputs (like public keys and amounts) before converting them to Soroban `ScVal` representations. Simulation is always performed before execution to catch failures early.
+ * - **Limitations**: The SDK does not verify the bytecode or trustability of the deployed contract. Ensure the target contract is audited.
+ * See [Security Threat Model](../../docs/security_threat_model.md).
  */
 
 import * as StellarSDK from '@stellar/stellar-sdk';

src/transactions/index.ts

@@ -3,9 +3,13 @@
  *
  * Query transaction history and payment operations for a Stellar account.
  * 
- * @security See the [SDK Security Threat Model](../../docs/security_threat_model.md) 
- * for mitigation strategies regarding transaction malleability, replay attacks, 
- * and strict sequence number handling.
+ * @security 
+ * **Threat Model & Consumer Responsibilities**:
+ * - **Signing Boundaries**: Unsigned transactions MUST be built and verified prior to entering the signing phase. The SDK enforces capability checks (`canSign`) before attempting to sign.
+ * - **Transaction Submission Risks**: Malleability and replay attacks are mitigated by enforcing strict sequence numbers and time bounds (`setTimeout`) on every transaction builder.
+ * - **Consumer Responsibility**: Ensure destinations, amounts, and memos are validated correctly before building transactions. Handle retries carefully, taking note of HTTP 5xx versus 4xx responses.
+ * - **Limitations**: If network responses are delayed or ambiguous (e.g. timeout during submission), the SDK cannot definitively know if a transaction succeeded. Consumers must query the ledger.
+ * See [Security Threat Model](../../docs/security_threat_model.md) and [Signing Boundaries](../../docs/signing-boundaries.md).
  */
 
 import { getHorizonServer } from '../config';

src/wallet/index.ts

@@ -3,9 +3,13 @@
  *
  * Create, import, and manage Stellar keypairs. Query balances. Fund testnet accounts.
  * 
- * @security See the [SDK Security Threat Model](../../docs/security_threat_model.md)
- * for mitigation strategies regarding memory scraping, insecure key generation,
- * and accidental secret export.
+ * @security 
+ * **Threat Model & Consumer Responsibilities**:
+ * - **Secret Handling**: Wallet secrets (`secretKey`) are held in memory only as long as necessary. The SDK NEVER persists these to disk or remote storage.
+ * - **Consumer Responsibility**: The host application MUST securely encrypt and store `secretKey` (e.g., in iOS Keychain or Android Keystore) immediately after creation.
+ * - **Mitigation**: `createWallet` does not expose internals. The `LocalSigner` implementation protects against accidental serialization leaks.
+ * - **Limitations**: If the host application memory is scraped or the device is compromised (rooted/jailbroken), secrets are vulnerable.
+ * See [Security Threat Model](../../docs/security_threat_model.md) and [Wallet Backup Responsibility](../../docs/security.md#wallet-backup-responsibility).
  */
 
 import * as StellarSDK from '@stellar/stellar-sdk';