Bump dependency, enforce https, santize output, version to stable 2.0

Author: devinslick

README.md

@@ -40,6 +40,64 @@ async def main():
 asyncio.run(main())
 ```
 
+### TLS and self-signed certificates
+
+Find My Device always requires HTTPS; plain HTTP is not allowed by this client. If you need to connect to a server with a self-signed certificate, you have two options:
+
+- Preferred (secure): provide a custom SSLContext that trusts your CA or certificate
+- Last resort (not for production): disable certificate validation explicitly
+
+Examples:
+
+```python
+import ssl
+from fmd_api import FmdClient
+
+# 1) Custom CA bundle / pinned cert (recommended)
+ctx = ssl.create_default_context()
+ctx.load_verify_locations(cafile="/path/to/your/ca.pem")
+
+# Via constructor
+client = FmdClient("https://fmd.example.com", ssl=ctx)
+
+# Or via factory
+# async with await FmdClient.create("https://fmd.example.com", "user", "pass", ssl=ctx) as client:
+
+# 2) Disable verification (development only)
+insecure_client = FmdClient("https://fmd.example.com", ssl=False)
+```
+
+Notes:
+- HTTP (http://) is rejected. Use only HTTPS URLs.
+- Prefer a custom SSLContext over disabling verification.
+- For higher security, consider pinning the server cert in your context.
+
+> Warning
+>
+> Passing `ssl=False` disables TLS certificate validation and should only be used in development. For production, use a custom `ssl.SSLContext` that trusts your CA/certificate or pin the server certificate. The client enforces HTTPS and rejects `http://` URLs.
+
+#### Pinning the exact server certificate (recommended for self-signed)
+
+If you're using a self-signed certificate and want to pin to that exact cert, load the server's PEM (or DER) directly into an SSLContext. This ensures only that certificate (or its CA) is trusted.
+
+```python
+import ssl
+from fmd_api import FmdClient
+
+# Export your server's certificate to PEM (e.g., server-cert.pem)
+ctx = ssl.create_default_context()
+ctx.verify_mode = ssl.CERT_REQUIRED
+ctx.check_hostname = True  # keep hostname verification when possible
+ctx.load_verify_locations(cafile="/path/to/server-cert.pem")
+
+client = FmdClient("https://fmd.example.com", ssl=ctx)
+# async with await FmdClient.create("https://fmd.example.com", "user", "pass", ssl=ctx) as client:
+```
+
+Tips:
+- If the server cert changes, pinning will fail until you update the PEM.
+- For intermediate/CA signing chains, prefer pinning a private CA instead of the leaf.
+
 ## What’s in the box
 
 - `FmdClient` (primary API)

debugging/pin_cert_example.py

@@ -0,0 +1,104 @@
+"""
+Quick TLS test for FmdClient with certificate pinning or insecure mode.
+
+Security note:
+- Avoid passing passwords on the command line (they can end up in history). This script supports env vars
+    and secure prompt input so you can omit --password.
+
+Usage (PowerShell):
+    # 1) Export server cert to PEM using Python stdlib
+    #    Replace host as needed
+    python - << 'PY'
+import ssl
+host = "fmd.example.com"
+pem = ssl.get_server_certificate((host, 443))
+open("server-cert.pem", "w").write(pem)
+print("Wrote server-cert.pem for", host)
+PY
+
+    # 2) Set env vars (recommended)
+    $env:FMD_ID = "<FMD_ID>"
+    $env:FMD_PASSWORD = "<PASSWORD>"  # Consider Read-Host -AsSecureString for interactive use
+
+    # 3) Try connecting with pinned cert (preferred for self-signed)
+    python debugging/pin_cert_example.py --base-url https://fmd.example.com --ca server-cert.pem
+
+    # 4) Or try insecure mode (development only)
+    python debugging/pin_cert_example.py --base-url https://fmd.example.com --insecure
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import ssl
+from pathlib import Path
+import os
+import getpass
+
+from fmd_api import FmdClient
+
+
+async def run(base_url: str, fmd_id: str, password: str, ca_path: str | None, insecure: bool) -> int:
+    ssl_arg: object | None
+    if insecure:
+        ssl_arg = False
+    elif ca_path:
+        ctx = ssl.create_default_context()
+        ctx.verify_mode = ssl.CERT_REQUIRED
+        ctx.check_hostname = True
+        ctx.load_verify_locations(cafile=ca_path)
+        ssl_arg = ctx
+    else:
+        ssl_arg = None  # system default validation
+
+    try:
+        async with await FmdClient.create(
+            base_url,
+            fmd_id,
+            password,
+            ssl=ssl_arg,
+        ) as client:
+            # Minimal call that exercises the API with auth
+            # This will call /api/v1/locationDataSize
+            locs = await client.get_locations(num_to_get=0)
+            print("TLS OK; auth OK; available locations:", len(locs))
+            return 0
+    except Exception as e:
+        print("Failed:", e)
+        return 2
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="FmdClient TLS/pinning test")
+    p.add_argument("--base-url", required=True, help="Base URL, must be https://...")
+    p.add_argument("--id", help="FMD user ID (or set FMD_ID env var)")
+    p.add_argument("--password", help="FMD password (or set FMD_PASSWORD env var, or omit to be prompted)")
+    p.add_argument("--ca", dest="ca_path", help="Path to PEM file to trust (pinning or custom CA)")
+    p.add_argument("--insecure", action="store_true", help="Disable certificate validation (development only)")
+    args = p.parse_args()
+
+    if args.base_url.lower().startswith("http://"):
+        p.error("--base-url must be HTTPS (http:// is not allowed)")
+
+    if args.ca_path and not Path(args.ca_path).exists():
+        p.error(f"--ca file not found: {args.ca_path}")
+
+    if args.insecure and args.ca_path:
+        p.error("Use either --ca or --insecure, not both.")
+
+    # Resolve credentials from args, env, or prompt
+    fmd_id = args.id or os.environ.get("FMD_ID")
+    if not fmd_id:
+        fmd_id = input("FMD ID: ")
+
+    password = args.password or os.environ.get("FMD_PASSWORD")
+    if not password:
+        # Prompt securely without echo
+        password = getpass.getpass("Password: ")
+
+    return asyncio.run(run(args.base_url, fmd_id, password, args.ca_path, args.insecure))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docs/HOME_ASSISTANT_REVIEW.md

@@ -68,12 +68,9 @@ async def _make_api_request(self, ..., timeout: int = 30):
 **HA Rationale:** Only stable, released versions accepted as integration dependencies.
 
 **Status:** ✅ FIXED
-- Implemented configurable retry policy in `FmdClient._make_api_request()`
-- Handles 429 with `Retry-After` header and exponential backoff with jitter
-- Retries transient 5xx (500/502/503/504) and connection errors
-- Avoids unsafe retries for `/api/v1/command` POST requests
-- Configurable via constructor: `max_retries`, `backoff_base`, `backoff_max`, `jitter`
-- Added unit tests for 429 + Retry-After and 500 -> success flows
+- Bumped version to stable `2.0.0` in `pyproject.toml` and `fmd_api/_version.py`
+- Built sdist and wheel artifacts for release
+- All unit tests passing after version bump
 
 ---
 
@@ -111,7 +108,13 @@ if resp.status == 429:
 
 **HA Rationale:** Production integrations must handle rate limits gracefully to avoid service disruption.
 
-**Status:** ❌ TODO
+**Status:** ✅ FIXED
+- Implemented 429 handling with Retry-After header support and exponential backoff with optional jitter
+- Retries for transient 5xx (500/502/503/504) and connection errors
+- Avoids unsafe retries for POST /api/v1/command, except on 401 re-auth or 429 with explicit Retry-After
+- Configurable via `max_retries`, `backoff_base`, `backoff_max`, `jitter`
+- Added unit tests: `test_rate_limit_retry_with_retry_after`, `test_server_error_retry_then_success`
+- All unit tests passing
 
 ---
 
@@ -174,7 +177,8 @@ async with await FmdClient.create(...) as client:
 
 **HA Rationale:** Misleading classifiers can cause installation issues.
 
-**Status:** ❌ TODO
+**Status:** ✅ FIXED
+- Removed Python 3.7 classifier; `requires-python` is `>=3.8`
 
 ---
 
@@ -194,7 +198,13 @@ async with await FmdClient.create(...) as client:
 
 **HA Rationale:** Security and privacy requirement for production systems.
 
-**Status:** ❌ TODO
+**Status:** ✅ FIXED
+- Removed logging of full JSON responses (line ~278); now logs only dict keys
+- Removed logging of response body text (line ~285); now logs only length
+- Added `_mask_token()` helper for safe token logging (shows first 8 chars)
+- Added comment to prevent signature logging in `send_command()`
+- Auth flow logs only workflow steps, never actual credentials
+- All 55 unit tests passing after sanitization
 
 ---
 
@@ -203,19 +213,23 @@ async with await FmdClient.create(...) as client:
 
 **Location:** `fmd_api/client.py` `_ensure_session()` method
 
-**Fix:** Add `verify_ssl` parameter to constructor:
+**Fix:** Add SSL parameter/connector configuration to constructor:
 ```python
-def __init__(self, base_url: str, ..., verify_ssl: bool = True):
-    self.verify_ssl = verify_ssl
+def __init__(..., ssl: Optional[ssl.SSLContext|bool] = None, ...):
+    self._ssl = ssl  # None=default verify, False=disable, SSLContext=custom
 
 async def _ensure_session(self):
-    connector = aiohttp.TCPConnector(ssl=self.verify_ssl)
+    connector = aiohttp.TCPConnector(ssl=self._ssl, ...)
     self._session = aiohttp.ClientSession(connector=connector)
 ```
 
 **HA Rationale:** Enterprise users and development environments need SSL configuration flexibility.
 
-**Status:** ❌ TODO
+**Status:** ✅ FIXED
+- New constructor options: `ssl` (None | False | SSLContext)
+- Verified by unit test `test_connector_configuration_applied`
+- Works with self-signed certs when `ssl=False`, or custom trust via SSLContext
+- HTTPS is explicitly enforced: `http://` base URLs are rejected by the client
 
 ---
 
@@ -228,7 +242,8 @@ async def _ensure_session(self):
 
 **HA Rationale:** Improves reliability in production environments with occasional network issues.
 
-**Status:** ❌ TODO
+**Status:** ✅ FIXED
+- Covered by issue 5 implementation; includes exponential backoff for transient errors
 
 ---
 
@@ -280,7 +295,10 @@ async def _ensure_session(self):
 
 **HA Rationale:** Performance tuning capability for production deployments.
 
-**Status:** ❌ TODO
+**Status:** ✅ FIXED
+- New constructor options: `conn_limit`, `conn_limit_per_host`, `keepalive_timeout`
+- Applied via `aiohttp.TCPConnector` in `_ensure_session()`
+- Verified by unit test `test_connector_configuration_applied`
 
 ---
 
@@ -475,15 +493,15 @@ def __init__(self, ..., ssl_context: Optional[ssl.SSLContext] = None):
 4. Fix version string inconsistency
 5. Add `py.typed` file
 6. Implement async context manager
-7. Add rate limit handling
+7. Add rate limit handling — DONE
 
 **For Production Quality (Major):**
-- Fix Python 3.7 classifier
-- Sanitize logs (security)
-- Add SSL verification control
+- Fix Python 3.7 classifier — DONE
+- Sanitize logs (security) — DONE
+- Add SSL verification control — DONE
 - Improve type hints
-- Add retry logic
-- Configure connection pooling
+- Add retry logic — DONE
+- Configure connection pooling — DONE
 - Make decryption async
 
 **For Best Practices (Minor):**

fmd_api/_version.py

@@ -1 +1 @@
-__version__ = "2.0.0.dev11"
+__version__ = "2.0.0"