From 83ac5738abc8ad3cc76f34c6cd837bd4d48a1ec9 Mon Sep 17 00:00:00 2001 From: Truphile Date: Mon, 27 Jul 2026 22:57:59 -0400 Subject: [PATCH 1/5] docs(security): Document threat model for wallet helpers --- src/wallet/index.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/wallet/index.ts b/src/wallet/index.ts index 364069a..9771df2 100644 --- a/src/wallet/index.ts +++ b/src/wallet/index.ts @@ -3,10 +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'; import { getHorizonServer, getFriendbotUrl, resolveConfig } from '../config'; From c3ae3b275b16843a2a23d00231167f04c4c8f8e0 Mon Sep 17 00:00:00 2001 From: Truphile Date: Mon, 27 Jul 2026 22:58:34 -0400 Subject: [PATCH 2/5] docs(security): Document threat model for transaction helpers --- src/transactions/index.ts | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/transactions/index.ts b/src/transactions/index.ts index be45642..a9db324 100644 --- a/src/transactions/index.ts +++ b/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'; From fae1eb0c0c824003dbd24d457144d5f9d12f980b Mon Sep 17 00:00:00 2001 From: Truphile Date: Mon, 27 Jul 2026 22:59:10 -0400 Subject: [PATCH 3/5] docs(security): Document threat model for vault helpers --- src/soroban/index.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/soroban/index.ts b/src/soroban/index.ts index 9880ef2..9800ae9 100644 --- a/src/soroban/index.ts +++ b/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'; From 58120712fd8e1cc220854ee63cc97da95e56252e Mon Sep 17 00:00:00 2001 From: Truphile Date: Mon, 27 Jul 2026 22:59:32 -0400 Subject: [PATCH 4/5] docs(security): Add security threat model links to README --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 928a3e4..d35a96d 100644 --- a/README.md +++ b/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 From 0aab5b97bc7ba1fd600723013faff89829234ac4 Mon Sep 17 00:00:00 2001 From: Truphile Date: Wed, 29 Jul 2026 01:16:42 -0400 Subject: [PATCH 5/5] fix: restore missing JSDoc closing tag in wallet index.ts to fix imported capabilities error --- src/wallet/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/wallet/index.ts b/src/wallet/index.ts index 9771df2..fd3bef0 100644 --- a/src/wallet/index.ts +++ b/src/wallet/index.ts @@ -10,6 +10,7 @@ * - **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'; import { getHorizonServer, getFriendbotUrl, resolveConfig } from '../config';