docs: Update documentation for controller PR #2375

src/pages/controller/native/capacitor.md

@@ -46,11 +46,50 @@ const config: CapacitorConfig = {
   appId: "com.yourapp.id",
   appName: "Your App Name",
   webDir: "dist",  // Your build output directory
+  server: {
+    hostname: "my-custom-app",  // Recommended: Set a custom hostname for production
+    androidScheme: "https",
+    iosScheme: "capacitor",
+  },
 };
 
 export default config;
 ```
 
+### Security and Custom Hostnames
+
+For production apps, it is **strongly recommended** to set a custom hostname to prevent other Capacitor apps from potentially spoofing your origin.
+
+By default, Capacitor apps use `localhost` as the hostname (`capacitor://localhost` on iOS). While this is automatically verified by the Keychain for development convenience, custom hostnames require explicit authorization in your Controller preset configuration.
+
+#### Setting up Custom Hostnames:
+
+1. **Configure your Capacitor app** with a custom hostname:
+
+```typescript
+// capacitor.config.ts
+server: {
+  hostname: "my-custom-app",
+  iosScheme: "capacitor", 
+  androidScheme: "https"
+}
+```
+
+2. **Authorize the hostname in your Controller preset**. The Keychain will only verify custom Capacitor origins if the hostname is explicitly listed in your preset's allowed origins:
+
+```json
+{
+  "origin": ["my-custom-app"],
+  // ... other preset configuration
+}
+```
+
+This ensures your app is verified on both platforms:
+- **iOS**: `capacitor://my-custom-app`
+- **Android**: `https://my-custom-app`
+
+**Important**: The default `localhost` origin (`capacitor://localhost`) is always allowed for development convenience, but custom hostnames must be explicitly authorized in your preset configuration.
+
 ## Controller Setup
 
 Use `SessionProvider` from `@cartridge/controller/session` for native apps.

src/pages/controller/presets.md

@@ -24,6 +24,42 @@ To create a theme, teams should commit their theme config to the `configs` folde
 }
 ```
 
+### Origin Configuration
+
+The `origin` field specifies which origins are authorized to use your preset. This is important for security and preventing unauthorized use of your configuration.
+
+#### Web Applications
+For standard web applications, use your domain:
+```json
+{
+  "origin": "https://yourdomain.com"
+}
+```
+
+#### Multiple Origins
+You can specify multiple origins as an array:
+```json
+{
+  "origin": ["https://yourdomain.com", "https://staging.yourdomain.com"]
+}
+```
+
+#### Capacitor Apps with Custom Hostnames
+For Capacitor mobile apps using custom hostnames, include the custom hostname in your origins:
+
+```json
+{
+  "origin": ["https://yourdomain.com", "my-custom-app"]
+}
+```
+
+This authorizes both your web app and your Capacitor app with the custom hostname:
+- **Web**: `https://yourdomain.com` 
+- **iOS Capacitor**: `capacitor://my-custom-app`
+- **Android Capacitor**: `https://my-custom-app`
+
+**Note**: The default `localhost` origin (`capacitor://localhost`) is always allowed for development convenience and doesn't need to be explicitly listed in presets.
+
 See an example pull request [`here`](https://github.com/cartridge-gg/presets/pull/8/files)
 
 ## Verified Sessions