docs: document wallet secret export policy

[drojas1316]

Closes #211

Description

Documents the PocketPay SDK policy for wallet secret export and clarifies the security boundary between supported local-key access and a managed wallet-export feature.

This PR adds a dedicated wallet secret export policy that explains:

• which existing SDK APIs may return or accept a Stellar secret key;
• that the SDK does not provide a dedicated exportWallet(), exportSecretKey(), mnemonic, backup-file, clipboard, QR-code, or recovery workflow;
• why signing capability does not imply that a signer or account has an exportable secret;
• the risks associated with exposing, copying, transmitting, logging, storing, or backing up wallet secrets;
• the responsibilities of consuming applications that decide to implement their own export or backup flow;
• the limitations of local signers, external signers, recovery phrases, encrypted backups, storage, synchronization, deletion, and wallet recovery.

The README documentation index now links directly to the new policy.

Linked Issue

Closes #211

Type of Change

• Bug fix
• New feature
• Refactor
• Documentation update
• Tests only
• Dependency or tooling update

Changes Made

Added

• docs/wallet-secret-export.md
  • Defines the SDK's supported wallet-secret behaviour.
  • States clearly that no dedicated or security-managed wallet export API is provided.
  • Documents that createWallet() returns a local WalletKeypair containing a secret key.
  • Documents that importWallet(secretKey) requires the caller to already possess the secret.
  • Explains that getPublicKey(secretKey) derives only a public key and does not recover or export a secret.
  • Clarifies that transaction signing and secret extraction are separate capabilities.
  • Explains that Signer, AccountAbstraction, LocalSigner, hardware wallets, HSMs, passkeys, MPC signers, and remote signers must not be assumed to expose private key material.
  • Lists unsupported export, backup, mnemonic, synchronization, custody, and recovery behaviour.
  • Documents security risks involving logs, telemetry, clipboards, screenshots, networks, storage, backups, and incomplete deletion.
  • Defines consumer responsibilities for authentication, secure storage, user warnings, recovery design, migration, deletion, and production security review.
  • Links to related security, recovery, account abstraction, logging, architecture, API, and React Native documentation.

Updated

• README.md
  • Added a documentation-index link to docs/wallet-secret-export.md.

Supported Behaviour Documented

The new policy documents the behaviour already present in the SDK:

• createWallet() generates and returns a local keypair in memory.
• importWallet(secretKey) validates a secret already possessed by the caller.
• getPublicKey(secretKey) derives the associated public key.
• Some payment and Soroban operations accept secret material for local transaction signing.
• LocalSigner may hold secret material in memory for signing.
• External signer implementations may support signing without exposing any private key.

No SDK source behaviour or public API was changed by this PR.

Unsupported Behaviour Documented

The policy explicitly states that the SDK does not provide:

• exportWallet() or exportSecretKey() APIs;
• mnemonic or recovery-phrase generation;
• mnemonic account derivation;
• encrypted backup files;
• password-protected wallet archives;
• clipboard, QR-code, printing, download, or sharing flows;
• cloud backup or cross-device synchronization;
• custody, escrow, or secret-recovery services;
• automatic secret persistence;
• secure deletion guarantees;
• secret extraction from signers or account abstractions;
• recovery of a lost Stellar secret key.

Security Guidance

The documentation follows a conservative secret-handling policy:

• Secret keys must not be logged or included in telemetry.
• Secret keys must not be sent to analytics, crash reporting, support systems, or unrelated backends.
• Public keys, transaction hashes, operation names, networks, and sanitized error codes should be used for diagnostics.
• Applications should minimize the lifetime and distribution of secret material.
• Applications must not rely on undocumented internal fields, deep imports, reflection, serialization, or memory inspection to obtain secrets.
• Consumer-created export flows require explicit user intent, appropriate authentication, secure storage, disclosure controls, cleanup, recovery documentation, and independent security review.
• No usable Stellar secret keys were included in the documentation.

Acceptance Criteria

• Wallet export behaviour is documented.
• Security risks are explained.
• Unsupported behaviour is clearly stated.
• README links to the new document.
• Guidance avoids unsafe executable examples.
• Consumer responsibilities are documented.
• Local and external signer limitations are explained.
• No wallet source-code behaviour was changed.
• No secret values were committed.

Validation

Passed

• npm ci
  • Installed dependencies successfully.
  • Reported 0 vulnerabilities.
• npm run check:circular
• git diff --check
• git diff --cached --check
• Markdown code fences are balanced.
• All local documentation links in the new file resolve.
• No complete Stellar secret-key patterns were found.
• Only the intended files are included in the commit:
  • README.md
  • docs/wallet-secret-export.md
• No unstaged or unexpected untracked files remained before the commit.

Repository Validation Limitations

npm run verify could not complete because the current repository state contains unrelated TypeScript export errors in existing source files.

npm run lint

Result: failed with 121 existing TypeScript errors across 14 source files.

The errors include missing exports such as:

• PocketPayError
• SDKConfig
• StellarNetwork
• WalletKeypair
• transaction and payment result types;
• retry-policy types;
• trustline types;
• transaction helper functions.

These errors are located in existing src/ files and are unrelated to the two documentation files changed by this PR.

npm run build

Result: failed with the same 121 TypeScript errors reported by npm run lint.

npm test

Result:

• 347 tests passed;
• 187 tests failed;
• 1 test skipped;
• 5 test files passed;
• 19 test files failed;
• 1 test file skipped.

The failures are primarily caused by the same existing export problems, including:

• PocketPayError is not a constructor;
• Right-hand side of 'instanceof' is not an object;
• transaction helpers such as getTransactions, filterByDirection, and sortTransactionsByDate not being exported;
• one existing mock Horizon timeout.

Relevant account-abstraction tests passed, including the test confirming that LocalSigner does not expose its secret key.

No source files, test files, configuration files, or dependency definitions were modified to address these unrelated repository failures because doing so would expand this documentation-only PR beyond issue #211.

Commit

e2f80de docs: document wallet secret export policy

Files Changed

README.md                     |   1 +
docs/wallet-secret-export.md  | 638 +
2 files changed, 639 insertions(+)

Reviewer Notes

This PR intentionally documents the current security boundary rather than adding an export implementation.

The key distinction is:

• local wallet APIs may explicitly return or accept a raw secret key;
• signing capability does not imply secret exportability;
• a dedicated, managed, or secure wallet-export feature remains unsupported and outside the SDK's current scope;
• any consumer-created export, backup, or recovery flow is owned by the consuming application.