Skip to content

Colota - Android GPS Location tracker

fix: support self-signed certs and any HTTP hostname for self-hosted servers (#239)

Max Dietrichfa4953523873
diff --git a/apps/docs/docs/api-reference.md b/apps/docs/docs/api-reference.md
index c9e4be4a..bc19edcf 100644
--- a/apps/docs/docs/api-reference.md
+++ b/apps/docs/docs/api-reference.md
@@ -150,13 +150,9 @@ By default, failed items are permanently deleted from the sync queue after 5 fai
## Network Requirements
- **HTTPS required** for all public endpoints
-- **HTTP allowed** only for private/local addresses:
- - `127.0.0.1` / `localhost`
- - `192.168.x.x`
- - `10.x.x.x`
- - `172.16–31.x.x`
+- **HTTP allowed** for private/local addresses - enforced at the native layer via DNS resolution at request time
- Non-standard ports are supported (e.g., `https://my-server.com:8443/api`)
-- Colota uses Android's default SSL trust store - custom CA certificates and self-signed certificates are not supported
+- Self-signed certificates are supported - see [Server Settings](/docs/configuration/server-settings#endpoint-url) for setup instructions
## Connectivity Check
diff --git a/apps/docs/docs/configuration/server-settings.md b/apps/docs/docs/configuration/server-settings.md
index f5bc3663..4db1a143 100644
--- a/apps/docs/docs/configuration/server-settings.md
+++ b/apps/docs/docs/configuration/server-settings.md
@@ -6,7 +6,7 @@ sidebar_position: 3
| Setting | Description | Default | Range |
| -------------------- | ----------------------------------------- | --------------- | ----------- |
-| Endpoint | HTTPS URL of your server | Empty (offline) | -- |
+| Endpoint | HTTP(S) URL of your server | Empty (offline) | -- |
| HTTP Method | POST (JSON body) or GET (query params) | POST | POST / GET |
| Sync Interval | Batch mode interval | Instant (0) | 0s - Custom |
| Retry Failed Uploads | Keep retrying failed uploads indefinitely | Off | On/Off |
@@ -14,14 +14,9 @@ sidebar_position: 3
## Endpoint URL
-Your server endpoint must accept HTTPS requests (POST or GET depending on your HTTP Method setting). HTTP is only allowed for private/local addresses:
+Your server endpoint must accept HTTP or HTTPS requests (POST or GET depending on your HTTP Method setting). HTTPS is required for public endpoints. HTTP is restricted to private/local addresses at the network level - public HTTP endpoints will be blocked at request time.
-- `127.0.0.1` / `localhost`
-- `192.168.x.x`
-- `10.x.x.x`
-- `172.16.x.x – 172.31.x.x`
-- `100.64.x.x – 100.127.x.x` (CGNAT)
-- `169.254.x.x` (link-local)
+Self-signed certificates are supported - install your CA certificate on the device via Settings → Security → Encryption & credentials → Install a certificate.
On **Android 17+**, connecting to another device on the local network (everything above except `localhost`) requires the **ACCESS_LOCAL_NETWORK** permission. Colota requests this when you use **Test Connection**. See [Permissions](/docs/development/permissions#local-network-access) for details.
diff --git a/apps/docs/docs/guides/troubleshooting.md b/apps/docs/docs/guides/troubleshooting.md
index e7b420b6..f8c8209e 100644
--- a/apps/docs/docs/guides/troubleshooting.md
+++ b/apps/docs/docs/guides/troubleshooting.md
@@ -19,13 +19,13 @@ sidebar_position: 4
## Server sync not working
-1. Check endpoint URL format - must be `https://` or `http://localhost`
+1. Check endpoint URL format - must be `https://` for public endpoints, or `http://` for private/local addresses
2. Use the **Test Connection** button in settings
3. Check server logs for incoming requests
4. Verify network connectivity
5. Check the queue count in **Data Management**
-**Common causes**: Wrong URL, HTTPS required for non-localhost, expired SSL certificate, incorrect authentication, mismatched field mapping, self-signed certificate (not supported), **Wi-Fi Only Sync** enabled while on cellular data, missing local network permission on Android 16+.
+**Common causes**: Wrong URL, HTTPS required for public endpoints, expired SSL certificate, incorrect authentication, mismatched field mapping, self-signed certificate (install your CA via Settings → Security → Encryption & credentials), **Wi-Fi Only Sync** enabled while on cellular data, missing local network permission on Android 16+.
## Exporting app logs
diff --git a/apps/docs/docs/integrations/custom-backend.md b/apps/docs/docs/integrations/custom-backend.md
index 2aabe961..9ed9ebc8 100644
--- a/apps/docs/docs/integrations/custom-backend.md
+++ b/apps/docs/docs/integrations/custom-backend.md
@@ -15,7 +15,7 @@ Your server needs to:
- Handle `alt`, `vel`, and `bear` fields being absent (they are conditional)
- Handle up to 10 concurrent requests during batch sync
-HTTPS is required for public endpoints. HTTP is allowed for local addresses (`127.0.0.1`, `192.168.x.x`, `10.x.x.x`, `172.16-31.x.x`). On Android 17+, connecting to local network addresses (not localhost) requires the Nearby Wi-Fi Devices permission, which Colota requests when you use **Test Connection**.
+HTTPS is required for public endpoints. HTTP is restricted to private/local addresses at the network level. Self-signed certificates are supported - see [Server Settings](/docs/configuration/server-settings#endpoint-url). On Android 17+, connecting to local network addresses (not localhost) requires the Local Network Access permission, which Colota requests when you use **Test Connection**.
## Default Payload
diff --git a/apps/mobile/android/app/src/main/res/xml/network_security_config.xml b/apps/mobile/android/app/src/main/res/xml/network_security_config.xml
index 9e786278..65cffa9d 100644
--- a/apps/mobile/android/app/src/main/res/xml/network_security_config.xml
+++ b/apps/mobile/android/app/src/main/res/xml/network_security_config.xml
@@ -12,6 +12,7 @@
<base-config cleartextTrafficPermitted="true">
<trust-anchors>
<certificates src="system" />
+ <certificates src="user" />
</trust-anchors>
</base-config>
</network-security-config>
\ No newline at end of file
diff --git a/apps/mobile/src/utils/__tests__/settingsValidation.test.ts b/apps/mobile/src/utils/__tests__/settingsValidation.test.ts
index f026b97b..bc5c6db9 100644
--- a/apps/mobile/src/utils/__tests__/settingsValidation.test.ts
+++ b/apps/mobile/src/utils/__tests__/settingsValidation.test.ts
@@ -69,38 +69,21 @@ describe("isPrivateHost", () => {
})
describe("isEndpointAllowed", () => {
- describe("HTTPS endpoints", () => {
- it("allows any HTTPS endpoint", () => {
- expect(isEndpointAllowed("https://example.com/api")).toBe(true)
- expect(isEndpointAllowed("https://api.server.io:443/v1")).toBe(true)
- })
+ it("allows valid http and https URLs", () => {
+ expect(isEndpointAllowed("https://example.com/api")).toBe(true)
+ expect(isEndpointAllowed("http://192.168.1.1/api")).toBe(true)
})
- describe("HTTP endpoints", () => {
- it("allows HTTP to private hosts", () => {
- expect(isEndpointAllowed("http://192.168.1.1/api")).toBe(true)
- expect(isEndpointAllowed("http://localhost:3000/locations")).toBe(true)
- expect(isEndpointAllowed("http://10.0.0.1:8080")).toBe(true)
- })
-
- it("rejects HTTP to public hosts", () => {
- expect(isEndpointAllowed("http://google.com")).toBe(false)
- expect(isEndpointAllowed("http://api.example.com/v1")).toBe(false)
- })
+ it("rejects empty string", () => {
+ expect(isEndpointAllowed("")).toBe(false)
})
- describe("invalid inputs", () => {
- it("rejects empty string", () => {
- expect(isEndpointAllowed("")).toBe(false)
- })
-
- it("rejects URLs without protocol", () => {
- expect(isEndpointAllowed("example.com/api")).toBe(false)
- })
+ it("rejects URLs without protocol", () => {
+ expect(isEndpointAllowed("example.com/api")).toBe(false)
+ })
- it("rejects non-HTTP protocols", () => {
- expect(isEndpointAllowed("ftp://example.com")).toBe(false)
- expect(isEndpointAllowed("ws://example.com")).toBe(false)
- })
+ it("rejects non-HTTP protocols", () => {
+ expect(isEndpointAllowed("ftp://example.com")).toBe(false)
+ expect(isEndpointAllowed("ws://example.com")).toBe(false)
})
})
diff --git a/apps/mobile/src/utils/settingsValidation.ts b/apps/mobile/src/utils/settingsValidation.ts
index 99175522..3caa3873 100644
--- a/apps/mobile/src/utils/settingsValidation.ts
+++ b/apps/mobile/src/utils/settingsValidation.ts
@@ -42,17 +42,8 @@ export function isPrivateHost(url: string) {
}
}
+// Validates that a URL has a valid http(s):// scheme and hostname.
+// HTTP enforcement (private-IP restriction) happens at the native layer via DNS resolution.
export function isEndpointAllowed(url: string) {
- if (!url) return false
-
- const match = url.match(/^(https?):\/\/([^/:]+)(:\d+)?/)
- if (!match) return false
-
- const protocol = match[1] // http or https
- const host = match[2]
-
- if (protocol === "https") return true
- if (protocol === "http" && isPrivateHost(host)) return true
-
- return false
+ return /^https?:\/\/[^/:]+/.test(url)
}