Cursor rule

1---
2paths:
3  - "**/*.dart"
4  - "**/pubspec.yaml"
5  - "**/AndroidManifest.xml"
6  - "**/Info.plist"
7---
8# Dart/Flutter Security
9 
10> This file extends [common/security.md](../common/security.md) with Dart, Flutter, and mobile-specific content.
11 
12## Secrets Management
13 
14- Never hardcode API keys, tokens, or credentials in Dart source
15- Use `--dart-define` or `--dart-define-from-file` for compile-time config (values are not truly secret — use a backend proxy for server-side secrets)
16- Use `flutter_dotenv` or equivalent, with `.env` files listed in `.gitignore`
17- Store runtime secrets in platform-secure storage: `flutter_secure_storage` (Keychain on iOS, EncryptedSharedPreferences on Android)
18 
19```dart
20// BAD
21const apiKey = 'sk-abc123...';
22 
23// GOOD — compile-time config (not secret, just configurable)
24const apiKey = String.fromEnvironment('API_KEY');
25 
26// GOOD — runtime secret from secure storage
27final token = await secureStorage.read(key: 'auth_token');
28```
29 
30## Network Security
31 
32- Enforce HTTPS — no `http://` calls in production
33- Configure Android `network_security_config.xml` to block cleartext traffic
34- Set `NSAppTransportSecurity` in `Info.plist` to disallow arbitrary loads
35- Set request timeouts on all HTTP clients — never leave defaults
36- Consider certificate pinning for high-security endpoints
37 
38```dart
39// Dio with timeout and HTTPS enforcement
40final dio = Dio(BaseOptions(
41  baseUrl: 'https://api.example.com',
42  connectTimeout: const Duration(seconds: 10),
43  receiveTimeout: const Duration(seconds: 30),
44));
45```
46 
47## Input Validation
48 
49- Validate and sanitize all user input before sending to API or storage
50- Never pass unsanitized input to SQL queries — use parameterized queries (sqflite, drift)
51- Sanitize deep link URLs before navigation — validate scheme, host, and path parameters
52- Use `Uri.tryParse` and validate before navigating
53 
54```dart
55// BAD — SQL injection
56await db.rawQuery("SELECT * FROM users WHERE email = '$userInput'");
57 
58// GOOD — parameterized
59await db.query('users', where: 'email = ?', whereArgs: [userInput]);
60 
61// BAD — unvalidated deep link
62final uri = Uri.parse(incomingLink);
63context.go(uri.path); // could navigate to any route
64 
65// GOOD — validated deep link
66final uri = Uri.tryParse(incomingLink);
67if (uri != null && uri.host == 'myapp.com' && _allowedPaths.contains(uri.path)) {
68  context.go(uri.path);
69}
70```
71 
72## Data Protection
73 
74- Store tokens, PII, and credentials only in `flutter_secure_storage`
75- Never write sensitive data to `SharedPreferences` or local files in plaintext
76- Clear auth state on logout: tokens, cached user data, cookies
77- Use biometric authentication (`local_auth`) for sensitive operations
78- Avoid logging sensitive data — no `print(token)` or `debugPrint(password)`
79 
80## Android-Specific
81 
82- Declare only required permissions in `AndroidManifest.xml`
83- Export Android components (`Activity`, `Service`, `BroadcastReceiver`) only when necessary; add `android:exported="false"` where not needed
84- Review intent filters — exported components with implicit intent filters are accessible by any app
85- Use `FLAG_SECURE` for screens displaying sensitive data (prevents screenshots)
86 
87```xml
88<!-- AndroidManifest.xml — restrict exported components -->
89<activity android:name=".MainActivity" android:exported="true">
90    <!-- Only the launcher activity needs exported=true -->
91</activity>
92<activity android:name=".SensitiveActivity" android:exported="false" />
93```
94 
95## iOS-Specific
96 
97- Declare only required usage descriptions in `Info.plist` (`NSCameraUsageDescription`, etc.)
98- Store secrets in Keychain — `flutter_secure_storage` uses Keychain on iOS
99- Use App Transport Security (ATS) — disallow arbitrary loads
100- Enable data protection entitlement for sensitive files
101 
102## WebView Security
103 
104- Use `webview_flutter` v4+ (`WebViewController` / `WebViewWidget`) — the legacy `WebView` widget is removed
105- Disable JavaScript unless explicitly required (`JavaScriptMode.disabled`)
106- Validate URLs before loading — never load arbitrary URLs from deep links
107- Never expose Dart callbacks to JavaScript unless absolutely needed and carefully sandboxed
108- Use `NavigationDelegate.onNavigationRequest` to intercept and validate navigation requests
109 
110```dart
111// webview_flutter v4+ API (WebViewController + WebViewWidget)
112final controller = WebViewController()
113  ..setJavaScriptMode(JavaScriptMode.disabled) // disabled unless required
114  ..setNavigationDelegate(
115    NavigationDelegate(
116      onNavigationRequest: (request) {
117        final uri = Uri.tryParse(request.url);
118        if (uri == null || uri.host != 'trusted.example.com') {
119          return NavigationDecision.prevent;
120        }
121        return NavigationDecision.navigate;
122      },
123    ),
124  );
125 
126// In your widget tree:
127WebViewWidget(controller: controller)
128```
129 
130## Obfuscation and Build Security
131 
132- Enable obfuscation in release builds: `flutter build apk --obfuscate --split-debug-info=./debug-info/`
133- Keep `--split-debug-info` output out of version control (used for crash symbolication only)
134- Ensure ProGuard/R8 rules don't inadvertently expose serialized classes
135- Run `flutter analyze` and address all warnings before release
136