From 34a61e8f0a78c2de9f86bc4c6a0a22c3c5e255db Mon Sep 17 00:00:00 2001 From: kikiola Date: Sat, 25 Jul 2026 22:37:08 +0100 Subject: [PATCH 1/2] docs: add mobile security checklist and link it in README --- README.md | 2 +- docs/mobile-security-checklist.md | 46 ++++++++++++++++++++++++++++ docs/pr-mobile-security-checklist.md | 31 +++++++++++++++++++ 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 docs/mobile-security-checklist.md create mode 100644 docs/pr-mobile-security-checklist.md diff --git a/README.md b/README.md index be7ce6f..7f85e36 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ See [CHANGELOG.md](./CHANGELOG.md) for a full list of notable changes across rel ## Security See the full [Security Guide](docs/security.md) for details on secret key handling, device storage, backups, and safe development practices. - +- [Mobile Security Checklist](docs/mobile-security-checklist.md) - Checklist for reviewing security-sensitive changes ## License MIT diff --git a/docs/mobile-security-checklist.md b/docs/mobile-security-checklist.md new file mode 100644 index 0000000..d7ddc43 --- /dev/null +++ b/docs/mobile-security-checklist.md @@ -0,0 +1,46 @@ +# Mobile Security Checklist + +This checklist should be reviewed by contributors when making changes that affect security-sensitive parts of the PocketPay mobile app. + +## Secret Handling +- [ ] Ensure secret keys (`S…`) are never logged or printed to console. +- [ ] Verify that any new code handling keys reads from `expo-secure-store` and does not persist them to `AsyncStorage` or the filesystem. +- [ ] If exposing a secret for debugging, guard with `if (__DEV__)` and ensure it is removed before production. + +## Signing Flows +- [ ] Confirm that transaction signing occurs via the `Signer` abstraction and that the secret never leaves SecureStore. +- [ ] When adding new signing pathways, ensure they respect the existing `Signer` interface and do not introduce direct key usage. +- [ ] Validate that any external signer integration follows the documented handoff design. + +## Logging & Diagnostics +- [ ] Audit new log statements to ensure no sensitive data (secret keys, mnemonics, seed phrases) are included. +- [ ] Use `console.log` for non-sensitive debugging only under `__DEV__` guards. +- [ ] Remove or mask error objects that may contain request parameters or private data before logging. + +## Screenshots & Clipboard +- [ ] Avoid displaying secret keys or QR codes containing private information on-screen in screenshots. +- [ ] Verify that any UI that copies public keys to the clipboard includes a warning about clipboard privacy. +- [ ] Ensure test screenshots used in documentation do not contain real secret keys. + +## Secure Storage +- [ ] Ensure all stored secrets use `expo-secure-store` (Keychain on iOS, Android Keystore on Android). +- [ ] Do not fallback to `AsyncStorage` for any secret material. +- [ ] Add error handling for SecureStore read/write failures without auto‑deleting keys. + +## Error & Recovery Flows +- [ ] Confirm that storage errors surface appropriate user‑friendly messages and do not purge the secret key. +- [ ] Verify that any reset flow clearly warns users about key loss and requires manual backup confirmation. +- [ ] Ensure that error boundaries do not expose stack traces or internal details in production. + +## Diagnostics & Telemetry +- [ ] If adding analytics or telemetry, exclude any fields that could contain secret keys or personal identifiers. +- [ ] Review that any performance logs respect privacy guidelines. + +## Peer Review Checklist +- [ ] All above items have been checked for the modified code. +- [ ] Documentation updated to reflect any new security-relevant behavior. +- [ ] Tests added/updated to cover security-critical paths. + +--- + +*This checklist is intended to maintain the high security standards of PocketPay on the Stellar Testnet.* diff --git a/docs/pr-mobile-security-checklist.md b/docs/pr-mobile-security-checklist.md new file mode 100644 index 0000000..aa439b6 --- /dev/null +++ b/docs/pr-mobile-security-checklist.md @@ -0,0 +1,31 @@ +# PR: Add Mobile Security Checklist + +## Description +This PR introduces a **Mobile Security Checklist** to help contributors review security‑sensitive changes in the PocketPay mobile app. The checklist covers secret handling, signing flows, logging, screenshots, secure storage, error handling, and more. Additionally, the README has been updated to link to this new checklist. + +## Motivation +- Ensure consistent security practices across all contributions. +- Provide a clear, reviewer‑friendly reference to verify that new code does not introduce security regressions. +- Align with the existing Security Guide and improve overall code health. + +## Changes Made +- **New file:** `docs/mobile-security-checklist.md` – contains the comprehensive checklist. +- **README update:** Added a bullet link under the **Security** section pointing to the new checklist. + +## Testing / Verification +- Run the app locally and verify that the README link resolves correctly. +- Review the checklist manually to ensure it covers all relevant security aspects. +- Ensure the project builds without lint or type errors (`npm run lint`, `npm test`). + +## Checklist for Reviewers +- [ ] Documentation updated and linked correctly. +- [ ] No new lint warnings introduced. +- [ ] Build passes (`npm run build` / `npm start`). +- [ ] Security checklist content is accurate and complete. +- [ ] All tests (if any) pass. + +## Related Issues +- None (new feature). + +--- +*Generated automatically by Antigravity on 2026‑07‑25.* From b4b4c35260d7057cf63c3ad8bc5352f97a823d9c Mon Sep 17 00:00:00 2001 From: kikiola Date: Sat, 25 Jul 2026 22:46:27 +0100 Subject: [PATCH 2/2] docs: add analytics security design documentation and update README reference --- README.md | 5 ++ docs/analytics-security-design.md | 104 +++++++++++++++++++++++++++ docs/pr-analytics-security-design.md | 31 ++++++++ 3 files changed, 140 insertions(+) create mode 100644 docs/analytics-security-design.md create mode 100644 docs/pr-analytics-security-design.md diff --git a/README.md b/README.md index 7f85e36..1fd253a 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,11 @@ See [CHANGELOG.md](./CHANGELOG.md) for a full list of notable changes across rel See the full [Security Guide](docs/security.md) for details on secret key handling, device storage, backups, and safe development practices. - [Mobile Security Checklist](docs/mobile-security-checklist.md) - Checklist for reviewing security-sensitive changes +## Analytics Design + +- [Analytics Security Design](docs/analytics-security-design.md) - Design guidelines for safe analytics events. + ## License MIT +MIT diff --git a/docs/analytics-security-design.md b/docs/analytics-security-design.md new file mode 100644 index 0000000..6a362d3 --- /dev/null +++ b/docs/analytics-security-design.md @@ -0,0 +1,104 @@ +# Analytics Security Design + +**Purpose**: Define a safe, privacy‑preserving approach to screen‑level analytics events for PocketPay mobile. The goal is to gather useful product insights while ensuring no wallet secrets, private keys, or transaction‑level data ever leave the device. + +--- + +## 1. Scope of Analytics +- **Screen Views** – when a user navigates to a new screen, record the screen identifier (e.g., `walletScreen`, `sendScreen`). +- **Action Outcomes** – success/failure of user actions (e.g., `sendSuccess`, `importFailed`). +- **Performance Timings** – duration of API calls, loading spinners, etc. +- **Feature Flags** – whether a user has opted‑in to optional features (e.g., biometric lock). + +*Never* record: +- Full secret keys, seed phrases, or any `S…` value. +- Complete transaction blobs (XDR) or memo contents. +- Account balances expressed in XLM values (only record that a balance was fetched, not the amount). +- Personal identifiers (email, phone, address) – the app does not collect these. + +--- + +## 2. Event Naming Convention +``` +__ +``` +- **Category** – logical area (`wallet`, `send`, `receive`, `vault`). +- **Action** – user intent (`view`, `open`, `copy`, `submit`). +- **Outcome** – `success`, `error`, `cancel`. + +*Examples*: +- `wallet_view_success` +- `send_submit_error` +- `vault_open_success` + +--- + +## 3. Redaction Rules +| Data Type | Allowed | Redaction Rule | +|----------|---------|----------------| +| Screen ID | ✅ | Use static, non‑PII identifiers (e.g., `walletScreen`). | +| Action Verb | ✅ | Use generic verbs (`view`, `submit`). | +| Outcome | ✅ | Use generic states (`success`, `error`). | +| Secret Key | ❌ | **Never** send. | +| Transaction XDR | ❌ | **Never** send; if you need to know a transaction was attempted, send `transaction_attempted` without payload. | +| Account Balance | ❌ | Do **not** send numeric balance; you may send `balance_fetched` flag. | +| QR Code Data | ❌ | Never send the raw QR payload. | +| Error Message | ⚠️ | Only send error **code** (e.g., `ERR_NETWORK`) – strip any embedded parameters. | + +--- + +## 4. Opt‑Out / Privacy Controls +1. **Global Opt‑Out** – Users can disable analytics entirely from *Settings → Privacy → Analytics*. +2. **Granular Opt‑Out** – Future‑proof: each event checks `analyticsEnabled` flag before dispatch. +3. **On‑Device Storage** – Events are queued locally; they are sent only if analytics is enabled at send‑time. +4. **Data Retention** – Analytics library should purge events after successful upload or after 30 days. + +--- + +## 5. Implementation Guidance (React Native / Expo) +```tsx +// analytics.ts – thin wrapper around your analytics provider +import * as SecureStore from 'expo-secure-store'; + +export const logEvent = (name: string, params: Record = {}) => { + // Global opt‑out check – stored in SecureStore (encrypted) + SecureStore.getItemAsync('analyticsEnabled').then(enabled => { + if (enabled !== 'true') return; + // Redact any prohibited fields + const safeParams = Object.fromEntries( + Object.entries(params).filter(([key, value]) => { + // Simple rule: block keys containing "secret", "key", "xdr", "balance" + return !/(secret|key|xdr|balance)/i.test(key); + }) + ); + // Replace with your analytics SDK call + // analytics().logEvent(name, safeParams); + }); +}; +``` + +Use the wrapper throughout the app, e.g.: +```tsx +logEvent('wallet_view_success'); +logEvent('send_submit_error', { errorCode: err.code }); +``` + +--- + +## 6. Review Checklist (for contributors) +- [ ] Event name follows `__` pattern. +- [ ] No secret/key/balance values are passed in `params`. +- [ ] All error params are limited to error **codes**, not messages. +- [ ] The event is wrapped with `logEvent` to ensure opt‑out handling. +- [ ] Documentation (this file) is updated if a new category or rule is introduced. + +--- + +## 7. References +- [Mobile Security Checklist](docs/mobile-security-checklist.md) +- [Security Guide](docs/security.md) +- [Expo SecureStore](https://docs.expo.dev/versions/latest/sdk/securestore/) + +--- + +*Generated by Antigravity on 2026‑07‑25* diff --git a/docs/pr-analytics-security-design.md b/docs/pr-analytics-security-design.md new file mode 100644 index 0000000..3ac54bb --- /dev/null +++ b/docs/pr-analytics-security-design.md @@ -0,0 +1,31 @@ +# PR: Add Analytics Security Design Document + +## Description +This PR adds a **Analytics Security Design** document (`docs/analytics-security-design.md`) that outlines safe, privacy‑preserving screen‑level analytics events for the PocketPay mobile app. The design covers event scope, naming conventions, redaction rules, opt‑out handling, and implementation guidance. + +## Motivation +- Prevent accidental collection of wallet secrets, transaction data, or personal information. +- Provide a clear, reviewer‑friendly reference for contributors building new analytics events. +- Align analytics practices with the existing security checklist and overall security posture of the app. + +## Changes Made +- **New file:** `docs/analytics-security-design.md` – comprehensive analytics design and guidelines. +- **README update:** Added an "Analytics Design" section with a link to the new document (see line 100‑102). + +## Testing / Verification +- Verify that the README link resolves to the new document. +- Run `npm run lint` and `npm test` to ensure no new lint warnings or failing tests. +- Manually review the design to confirm no secret or transaction data is included in example events. + +## Review Checklist +- [ ] Documentation is clear, complete, and follows the repository’s style guidelines. +- [ ] No new lint warnings introduced. +- [ ] Build passes (`npm run build` / `npm start`). +- [ ] All examples respect the redaction rules defined in the design. +- [ ] Links in README are correct and functional. + +## Related Issues +- None – this is a new design document. + +--- +*Generated automatically by Antigravity on 2026‑07‑25.*