feat: added docs for SSL configuration and android manifestation

Author: TheNoumanDev

pages/apis/api-ssl-configuration.md

@@ -1,35 +1,247 @@
 # SSL Configuration
 
-SSL (Secure Sockets Layer) configuration in Ensemble allows you to secure your API communications through certificate pinning and verification controls. This guide explains the available SSL configuration options and their proper usage.
+SSL (Secure Sockets Layer) configuration in Ensemble allows you to secure your API communications through certificate pinning and verification controls. This guide explains both global and per-API SSL configuration options and their proper usage.
 
-## Available Configuration Options
+## Configuration Levels
 
-### ssl_pinning_enabled
+Ensemble supports SSL configuration at two levels:
 
+1. **Global Configuration** - Applied to all APIs by default using environment variables and secrets
+2. **Per-API Configuration** - Overrides global settings for specific APIs using the `sslConfig` property
+
+## Global SSL Configuration
+
+### Environment Variables
+
+These settings apply to all APIs unless overridden by per-API configuration:
+
+#### ssl_pinning_enabled
 - **Type:** Environment Variable
-- **Purpose:** Controls whether SSL certificate pinning is active
-- **Behavior:** When set to 'true', the app will only trust connections with certificates matching the provided certificate
+- **Purpose:** Controls whether SSL certificate pinning is active globally
+- **Values:** 'true' or 'false'
+- **Default:** false
 - **Availability:** Only supported in native apps (not available for web apps)
+
+#### bypass_ssl_pinning
+- **Type:** Environment Variable
+- **Purpose:** Allows bypassing SSL certificate verification globally
+- **Values:** 'true' or 'false'
+- **Default:** false
+- **Warning:** Should only be used in development environments, never in production
+
+#### bypass_ssl_pinning_with_validation
+- **Type:** Environment Variable
+- **Purpose:** Bypass SSL pinning while validating against stored certificate fingerprints
+- **Values:** 'true' or 'false'
 - **Default:** false
+- **Usage:** Compares current certificate fingerprint with stored fingerprint from secure storage
 
-### ssl_pinning_certificate
+### Secrets
 
+#### ssl_pinning_certificate
 - **Type:** Secret
 - **Purpose:** Provides the certificate for SSL pinning verification
 - **Format:** Must be Base64 encoded
 - **Behavior:** The app will only trust servers presenting this certificate
 - **Dependencies:** Requires `ssl_pinning_enabled` to be 'true'
 
-### bypass_ssl_pinning
+## Per-API SSL Configuration
 
-- **Type:** Environment Variable
-- **Purpose:** Allows bypassing SSL certificate verification
-- **Warning:** Should only be used in development environments, never in production
-- **Behavior:** When 'true', bypasses all SSL certificate verification
-- **Default:** false
+For more granular control, you can override global SSL settings for individual APIs using the `sslConfig` property in your API definition.
+
+### Basic Syntax
+
+```yaml
+API:
+  mySecureAPI:
+    uri: https://api.example.com/data
+    method: GET
+    sslConfig:
+      pinningEnabled: true
+      bypassPinning: false
+      bypassPinningWithFingerprint: false
+      fingerprintKey: "api_example_com_fingerprint"
+    headers:
+      Authorization: Bearer ${token}
+```
+
+### sslConfig Properties
+
+#### pinningEnabled
+- **Type:** Boolean
+- **Purpose:** Enable/disable SSL certificate pinning for this specific API
+- **Values:** true or false
+- **Overrides:** Global `ssl_pinning_enabled` environment variable
+- **Example:** `pinningEnabled: true`
+
+#### bypassPinning
+- **Type:** Boolean
+- **Purpose:** Bypass SSL certificate verification for this specific API
+- **Values:** true or false
+- **Overrides:** Global `bypass_ssl_pinning` environment variable
+- **Warning:** Use only in development
+- **Example:** `bypassPinning: true`
+
+#### bypassPinningWithFingerprint
+- **Type:** Boolean
+- **Purpose:** Bypass SSL pinning while validating against stored certificate fingerprints
+- **Values:** true or false
+- **Overrides:** Global `bypass_ssl_pinning_with_validation` environment variable
+- **Example:** `bypassPinningWithFingerprint: true`
+- **Requirement:** `fingerprintKey` should be set with the same key given in API defination as secureStorage.
+
+#### fingerprintKey
+- **Type:** String
+- **Purpose:** Specifies the key in secure storage where the certificate fingerprint is stored
+- **Default:** "bypass_ssl_fingerprint"
+- **Usage:** Used with `bypassPinningWithFingerprint` to retrieve the stored certificate fingerprint for validation
+- **Example:** `fingerprintKey: "api_example_com_fingerprint"`
+
+## Certificate Fingerprint Management
+
+When using `bypassPinningWithFingerprint`, you need to store the certificate fingerprint in secure storage. There are two main approaches:
+
+### Method 1: Using Ensemble's setSecureStorage Action
+
+Store the certificate fingerprint manually using Ensemble's secure storage:
+
+```yaml
+Button:
+  label: Store Certificate Fingerprint
+  onTap:
+    setSecureStorage:
+      key: "api_example_com_fingerprint"
+      value: "a1b2c3d4e5f6..." # SHA256 fingerprint of the certificate
+      onComplete:
+        showToast:
+          message: Certificate fingerprint stored
+```
+
+### Method 2: Using External Methods (Dynamic Certificate Capture)
+
+For dynamic certificate capture, you can expose external methods from your host application:
+
+#### Host Application Setup (Flutter/Dart Example)
+
+```dart
+// In your main.dart or wherever you initialize EnsembleApp
+Future<Map<String, dynamic>> captureCertificateForHost({
+  required String host, 
+  int port = 443
+}) async {
+  HttpClient httpClient = HttpClient();
+  httpClient.connectionTimeout = const Duration(seconds: 10);
+  
+  String sha256Certificate = '';
+  
+  httpClient.badCertificateCallback = (X509Certificate cert, String certHost, int certPort) {
+    if (certHost.toLowerCase() == host.toLowerCase()) {
+      sha256Certificate = sha256.convert(cert.der).toString();
+      return true;
+    }
+    return false;
+  };
+  
+  try {
+    HttpClientRequest request = await httpClient.getUrl(Uri.parse('https://$host:$port/'));
+    HttpClientResponse response = await request.close();
+    await response.drain();
+    httpClient.close();
+    
+    if (sha256Certificate != '') {
+      await StorageManager().writeSecurely(
+        key: 'bypass_ssl_certificate',
+        value: sha256Certificate,
+      );
+      return {'status': true, 'fingerprint': sha256Certificate};
+    } else {
+      return {'success': false, 'error': 'Failed to capture certificate'};
+    }
+  } catch (e) {
+    return {'success': false, 'error': e.toString()};
+  }
+}
+
+// Register the external method
+EnsembleApp(
+  externalMethods: const {
+    'captureCertificateForHost': captureCertificateForHost,
+  },
+  // ... other properties
+)
+```
+
+#### Using External Method in Ensemble EDL
+
+```yaml
+View:
+  onLoad:
+    callExternalMethod:
+        name: captureCertificateForHost
+        payload:
+            host: ${HOST}
+            port: ${PORT_NUMBER}
+        onComplete:
+            invokeAPI:
+                name: secureAPI
+        onError:
+            showToast:
+            message: "Failed to capture certificate: ${response.error}"
+            options:
+                type: error
+
+API:
+  secureAPI:
+    uri: ${HOST}/endpoint
+    method: GET
+    sslConfig:
+      bypassPinningWithFingerprint: true
+      fingerprintKey: "api_fingerprint"
+    headers:
+      Authorization: Bearer ${token}
+```
+
+
+
+## Configuration Examples
+
+### Example 1: High-Security API with Certificate Pinning
+
+```yaml
+API:
+  paymentAPI:
+    uri: https://secure-payment.example.com/process
+    method: POST
+    sslConfig:
+      pinningEnabled: true
+      bypassPinning: false
+      bypassPinningWithFingerprint: false
+    headers:
+      Authorization: Bearer ${paymentToken}
+      Content-Type: application/json
+    body:
+      amount: ${amount}
+      currency: USD
+```
+
+### Example 2: Development API with SSL Bypass
+
+```yaml
+API:
+  devTestAPI:
+    uri: https://dev-server.example.com/test
+    method: GET
+    sslConfig:
+      pinningEnabled: false
+      bypassPinning: true  # Only for development!
+      bypassPinningWithFingerprint: false
+    headers:
+      Authorization: Bearer ${devToken}
+```
 
-## Security Considerations
+## Security Best Practices
 
-1. Certificate pinning provides protection against man-in-the-middle attacks
-2. SSL bypass shouldn't be used in production environments as it will create security concerns.
-3. Web applications cannot use SSL pinning and rely on browser-based verification
+1. **Production Environment**: Always use certificate pinning (`pinningEnabled: true`) for production APIs
+2. **Development Environment**: Use `bypassPinning: true` only during development
+3. **Dynamic Environments**: Use `bypassPinningWithFingerprint: true` when dealing with dynamic certificates or multiple environments
+4. **Certificate Storage**: Store certificate fingerprints securely using `setSecureStorage` or external methods

pages/tips-and-tricks.md

@@ -2,28 +2,46 @@
 
 Welcome to our Tips and Tricks page! Here, you'll find a collection of expert insights and best practices to help you make the most of our platform. Discover shortcuts, time-saving techniques, and hidden features to enhance your productivity.
 
+## Development and Build Tips
+
 - [Getting help from Ensemble team](/tips-and-tricks/getting-help)
+- [Securing API calls with SSL Configuration](/apis/api-ssl-configuration.md)
+- [Using local assets](/tips-and-tricks/using-local-assets)
+- [Managing Unnecessary Android Permissions](/tips-and-tricks/managing-android-permissions)
+
+## UI and Styling
+
 - [Custom BottomNavBar item styling](/tips-and-tricks/custom-navbar-items)
 - [Making the UI responsive](/tips-and-tricks/responsive-ui)
-- [Use device's camera for updating profile picture](/tips-and-tricks/user-profile-picture)
-- [Inputs to ChartJs](/tips-and-tricks/inputs-chartjs)
 - [How to modify the BottomNavBar with custom styling and widgets](/tips-and-tricks/how-to-modify-bottom-navbar)
-- [Open Maps with Coordinates on Android and iOS](/tips-and-tricks/open-maps-with-coordinates)
-- [Using navigate Screen with BottomNavBar](/tips-and-tricks/navigateScreen-with-bottomNavBar)
 - [Dynamic color modification](/tips-and-tricks/dynamic-color-modification)
 - [Icons in bottomNavBar](/tips-and-tricks/icons-in-bottomNavBar)
+- [Using BottomSafeArea for responsive layouts](/tips-and-tricks/bottom-safe-area.md)
+- [Floating Button](/tips-and-tricks/floatingButton.md)
+
+## Device and Platform Features
+
+- [Use device's camera for updating profile picture](/tips-and-tricks/user-profile-picture)
+- [Using device width and height](/tips-and-tricks/using-device-dimentions.md)
 - [InvokeHaptic](/tips-and-tricks/invoke-haptic.md)
+- [Open Maps with Coordinates on Android and iOS](/tips-and-tricks/open-maps-with-coordinates)
+- [Push Notification](/tips-and-tricks/push-notification.md)
+
+## Navigation and User Experience
+
+- [Using navigate Screen with BottomNavBar](/tips-and-tricks/navigateScreen-with-bottomNavBar)
+
+## Advanced Features
+
+- [Inputs to ChartJs](/tips-and-tricks/inputs-chartjs)
 - [Lottie Animations](/tips-and-tricks/lottie-animations.md)
 - [HTML Widget](/tips-and-tricks/html-widget.md)
-- [Push Notification](/tips-and-tricks/push-notification.md)
-- [Using device width and height](/tips-and-tricks/using-device-dimentions.md)
-- [Using BottomSafeArea for responsive layouts](/tips-and-tricks/bottom-safe-area.md)
-- [Floating Button](/tips-and-tricks/floatingButton.md)
-- [Securing API calls with SSL Configuration](/apis/api-ssl-configuration.md)
+
+## Common Error Solutions
 
 Below are some common error messages and their solutions:
 
 - [Widget requires a width](/error/no-bounded-width)
 - [Widget requires a height](/error/no-bounded-height)
 - [FlexRow requires a width for child distribution](/error/flexrow-no-bounded-width)
-- [FlexColumn requires a height for child distribution](/error/flexcolumn-no-bounded-height)
+- [FlexColumn requires a height for child distribution](/error/flexcolumn-no-bounded-height)

pages/tips-and-tricks/managing-android-permissions.md

@@ -0,0 +1,55 @@
+# Managing Unnecessary Android Permissions
+
+When we include Ensemble dependencies in our host project, the merged Android manifest file of APK can include permissions from all plugins, even those we're not actively using. This can lead to unnecessary permissions being requested from users and potential app store rejections.
+
+## The Problem
+
+For example, if we include Firebase Analytics in our dependencies, it might automatically add advertising-related permissions like:
+- `com.google.android.gms.permission.AD_ID`
+- `android.permission.ACCESS_ADSERVICES_ATTRIBUTION` 
+- `android.permission.ACCESS_ADSERVICES_AD_ID`
+
+Even if we're not using advertising features, these permissions will be included in our final APK.
+
+## The Solution
+
+we can explicitly remove unwanted permissions from our Android manifest using the `tools:node="remove"` attribute.
+
+### Step 1: Add the tools namespace
+
+Make sure our `android/app/src/main/AndroidManifest.xml` file includes the tools namespace in the root manifest tag:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+```
+
+### Step 2: Remove unwanted permissions
+
+Add the following permissions with `tools:node="remove"` to explicitly remove them from our final manifest:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Remove ad-related permissions -->
+    <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />
+    <uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" tools:node="remove" />
+    <uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" tools:node="remove" />
+
+    <!-- our other permissions and application tag -->
+    <application>
+        <!-- our app content -->
+    </application>
+</manifest>
+```
+
+### Step 3: Verify the changes
+
+After making these changes:
+
+1. Clean our project: `flutter clean`
+2. Rebuild our app: `flutter build apk --debug`
+3. Verify the permissions oure removed by checking the final APK using tools like `aapt` or Android Studio's APK Analyzer
+
+This approach ensures our Ensemble app only requests the permissions it actually needs, providing a better user experience and maintaining security best practices.