feat(diagnostics): add HumbleFax diagnostics functionality

- Introduced a new endpoint `/admin/diagnostics/humblefax` to check HumbleFax connectivity, including DNS resolution, authentication presence, and webhook URL reachability.
- Added a method `getHumbleFaxDiagnostics` in AdminAPIClient to fetch diagnostics data for the HumbleFax provider.
- Enhanced the TunnelSettings component with a button to run HumbleFax diagnostics, displaying results in the UI.
- Implemented local QR code generation for pairing codes, improving user experience during tunnel setup.

These changes enhance the troubleshooting capabilities for the HumbleFax provider, allowing users to easily verify connectivity and configuration issues directly from the admin interface.

Author: Faxbot Agent

api/admin_ui/package-lock.json

@@ -18,13 +18,15 @@
     "@xterm/addon-web-links": "^0.11.0",
     "@xterm/xterm": "^5.5.0",
     "date-fns": "^4.1.0",
+    "qrcode": "^1.5.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-hook-form": "^7.48.2",
     "react-router-dom": "^6.20.1"
   },
   "devDependencies": {
     "@testing-library/react": "^14.1.2",
+    "@types/qrcode": "^1.5.5",
     "@types/react": "^18.2.43",
     "@types/react-dom": "^18.2.17",
     "@vitejs/plugin-react": "^4.2.0",

api/admin_ui/package.json

@@ -109,6 +109,11 @@ export class AdminAPIClient {
     return res.json();
   }
 
+  async getHumbleFaxDiagnostics(): Promise<any> {
+    const res = await this.fetch('/admin/diagnostics/humblefax');
+    return res.json();
+  }
+
   // Hierarchical Configuration (v4)
   async getEffectiveConfig(): Promise<{ values: Record<string, any>; cache_stats?: any }> {
     const res = await this.fetch('/admin/config/v4/effective');

api/admin_ui/src/api/client.ts

@@ -17,13 +17,16 @@ export default function TunnelSettings({ client, docsBase, hipaaMode, inboundBac
   const [testing, setTesting] = useState<boolean>(false);
   const [registering, setRegistering] = useState<boolean>(false);
   const [pairDialog, setPairDialog] = useState<{ open: boolean; code?: string; expires_at?: string }>({ open: false });
+  const [pairQr, setPairQr] = useState<string | null>(null);
   const [logsLoading, setLogsLoading] = useState<boolean>(false);
   const [logs, setLogs] = useState<string[]>([]);
   const [isSinchActive, setIsSinchActive] = useState<boolean>(false);
   const [inboundEnabled, setInboundEnabled] = useState<boolean>(false);
   const [notice, setNotice] = useState<{ severity: 'success' | 'error' | 'info'; message: string } | null>(null);
   const [sinchDiag, setSinchDiag] = useState<any | null>(null);
   const [diagLoading, setDiagLoading] = useState<boolean>(false);
+  const [hfDiag, setHfDiag] = useState<any | null>(null);
+  const [hfDiagLoading, setHfDiagLoading] = useState<boolean>(false);
 
   const [provider, setProvider] = useState<'none' | 'cloudflare' | 'wireguard' | 'tailscale'>('none');
   const [wg, setWg] = useState<{ endpoint?: string; server_key?: string; client_ip?: string; dns?: string }>({});
@@ -189,6 +192,12 @@ export default function TunnelSettings({ client, docsBase, hipaaMode, inboundBac
     try {
       const res = await client.createTunnelPairing();
       setPairDialog({ open: true, code: res.code, expires_at: res.expires_at });
+      // Generate QR locally (no external network dependency)
+      try {
+        const { default: QRCode } = await import('qrcode');
+        const dataUrl = await QRCode.toDataURL(String(res.code || ''), { width: 256, margin: 1 });
+        setPairQr(dataUrl);
+      } catch { setPairQr(null); }
     } catch (e: any) {
       setNotice({ severity: 'error', message: e?.message || 'Could not create pairing code' });
     }
@@ -235,6 +244,21 @@ export default function TunnelSettings({ client, docsBase, hipaaMode, inboundBac
     }
   };
 
+  const runHumbleFaxDiagnostics = async () => {
+    setHfDiagLoading(true);
+    setHfDiag(null);
+    try {
+      const res = await (client as any).getHumbleFaxDiagnostics?.();
+      setHfDiag(res || {});
+      const ok = Boolean(res?.dns_ok) && Boolean(res?.auth_present) && Boolean(res?.auth_ok) && Boolean(res?.webhook_url_ok);
+      setNotice({ severity: ok ? 'success' : 'error', message: ok ? 'HumbleFax diagnostics: OK' : 'HumbleFax diagnostics found issues' });
+    } catch (e: any) {
+      setNotice({ severity: 'error', message: e?.message || 'Diagnostics failed' });
+    } finally {
+      setHfDiagLoading(false);
+    }
+  };
+
   const cloudflareDisabled = Boolean(hipaaMode);
 
   const fetchLogs = async () => {
@@ -483,6 +507,12 @@ export default function TunnelSettings({ client, docsBase, hipaaMode, inboundBac
               <InlineLoader loading={registering} />
             </Button>
           )}
+          {(String(inboundBackend || '').toLowerCase() === 'humblefax') && (
+            <Button variant="outlined" onClick={runHumbleFaxDiagnostics} disabled={hfDiagLoading} sx={{ borderRadius: 2 }}>
+              Run HumbleFax Diagnostics
+              <InlineLoader loading={hfDiagLoading} />
+            </Button>
+          )}
           {provider === 'cloudflare' && !cloudflareDisabled && (
             <Button variant="text" onClick={fetchLogs} disabled={logsLoading} sx={{ borderRadius: 2 }}>
               View Cloudflared Logs (tail)
@@ -505,6 +535,15 @@ export default function TunnelSettings({ client, docsBase, hipaaMode, inboundBac
         </Paper>
       )}
 
+      {hfDiag && (
+        <Paper sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 2, mb: 2 }}>
+          <Typography variant="subtitle2" sx={{ mb: 1 }}>HumbleFax Diagnostics</Typography>
+          <Box component="pre" sx={{ m: 0, p: 0, whiteSpace: 'pre-wrap', wordBreak: 'break-word', fontSize: '0.8rem' }}>
+            {JSON.stringify(hfDiag, null, 2)}
+          </Box>
+        </Paper>
+      )}
+
       {provider === 'cloudflare' && !cloudflareDisabled && logs.length > 0 && (
         <Paper sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 2, mb: 2 }}>
           <Typography variant="subtitle2" sx={{ mb: 1 }}>Cloudflared logs (last 50 lines)</Typography>
@@ -515,7 +554,7 @@ export default function TunnelSettings({ client, docsBase, hipaaMode, inboundBac
       )}
 
       {/* Pairing dialog */}
-      <Dialog open={pairDialog.open} onClose={() => setPairDialog({ open: false })}>
+      <Dialog open={pairDialog.open} onClose={() => { setPairDialog({ open: false }); setPairQr(null); }}>
         <DialogTitle>iOS Pairing</DialogTitle>
         <DialogContent>
           <Typography variant="body2" sx={{ mb: 1 }}>
@@ -524,6 +563,11 @@ export default function TunnelSettings({ client, docsBase, hipaaMode, inboundBac
           <Typography variant="h4" sx={{ textAlign: 'center', letterSpacing: 4, my: 2 }}>
             {pairDialog.code}
           </Typography>
+          {pairQr && (
+            <Box sx={{ display: 'flex', justifyContent: 'center', my: 1 }}>
+              <img src={pairQr} alt="Pairing QR" style={{ maxWidth: 256, width: '100%' }} />
+            </Box>
+          )}
           {pairDialog.expires_at && (
             <Typography variant="caption" color="text.secondary" sx={{ display: 'block', textAlign: 'center' }}>
               Expires at {new Date(pairDialog.expires_at).toLocaleTimeString()}

api/admin_ui/src/components/TunnelSettings.tsx

@@ -1999,6 +1999,136 @@ async def admin_diagnostics_sinch():
     return SinchDiagnosticsOut(dns_ok=dns_ok, host=host, resolved=resolved, auth_present=auth_present, auth_ok=auth_ok, path_ok=path_ok, probes=probes)
 
 
+# ===== Lightweight diagnostics (HumbleFax) =====
+class HumbleFaxDiagnosticsOut(BaseModel):
+    backend: str = "humblefax"
+    dns_ok: bool
+    host: str
+    resolved: list[str] = []
+    auth_present: bool
+    auth_ok: bool
+    webhook_base: Optional[str] = None
+    webhook_url: Optional[str] = None
+    webhook_url_ok: bool = False
+    probes: dict[str, Any]
+    error: Optional[str] = None
+
+
+@app.get("/admin/diagnostics/humblefax", response_model=HumbleFaxDiagnosticsOut, dependencies=[Depends(require_admin)])
+async def admin_diagnostics_humblefax():
+    """Check HumbleFax connectivity from inside the API container.
+
+    Non-destructive checks:
+    - DNS resolution for api.humblefax.com
+    - Basic auth presence and HTTP reachability
+    - Public webhook URL resolvable and reachable (HEAD/GET tolerance)
+    """
+    import socket as _socket
+    from urllib.parse import urlparse as _urlparse
+
+    base_host = os.getenv("HUMBLEFAX_API_HOST", "api.humblefax.com").strip()
+    scheme = os.getenv("HUMBLEFAX_API_SCHEME", "https").strip()
+    base_url = f"{scheme}://{base_host}"
+    host = _urlparse(base_url).hostname or base_host
+
+    # DNS check
+    dns_ok = False
+    resolved: list[str] = []
+    try:
+        _, _, ips = _socket.gethostbyname_ex(host)
+        resolved = ips or []
+        dns_ok = len(resolved) > 0
+    except Exception:
+        dns_ok = False
+
+    # Auth presence
+    ak = (getattr(settings, 'humblefax_access_key', '') or os.getenv('HUMBLEFAX_ACCESS_KEY', '')).strip()
+    sk = (getattr(settings, 'humblefax_secret_key', '') or os.getenv('HUMBLEFAX_SECRET_KEY', '')).strip()
+    auth_present = bool(ak and sk)
+
+    probes: dict[str, Any] = {}
+    auth_ok = False
+
+    # Compute webhook base and URL similar to registration logic
+    try:
+        public_base = (
+            (_TUNNEL_STATE.get("public_url") if not _hipaa_posture_enabled() else None)
+            or (getattr(settings, 'humblefax_callback_base', '') or None)
+            or (settings.public_api_url or None)
+        )
+        webhook_base = (public_base or "").rstrip("/") or None
+    except Exception:
+        webhook_base = None
+    webhook_url = f"{webhook_base}/inbound/humblefax/webhook" if webhook_base else None
+
+    # Perform HTTP checks
+    try:
+        import httpx
+        # 1) HEAD unauthenticated to /webhook for general reachability
+        try:
+            with httpx.Client(timeout=8.0) as client:
+                r0 = client.head(f"{base_url}/webhook")
+                probes[f"{base_url}/webhook:HEAD"] = {"status": r0.status_code}
+        except Exception as e:
+            probes[f"{base_url}/webhook:HEAD"] = {"error": str(e)}
+
+        # 2) HEAD with basic auth to /webhook to validate credentials (status < 400 → good)
+        if auth_present:
+            try:
+                with httpx.Client(timeout=8.0) as client:
+                    r1 = client.head(f"{base_url}/webhook", auth=(ak, sk))
+                    probes[f"{base_url}/webhook:HEAD:auth"] = {"status": r1.status_code}
+                    if r1.status_code < 400:
+                        auth_ok = True
+            except Exception as e:
+                probes[f"{base_url}/webhook:HEAD:auth"] = {"error": str(e)}
+
+        # 3) Validate webhook target URL exists/reachable (tolerate 405 for method not allowed)
+        webhook_url_ok = False
+        if webhook_url:
+            try:
+                with httpx.Client(timeout=6.0, follow_redirects=True) as client:
+                    r2 = client.head(webhook_url)
+                    probes[f"{webhook_url}:HEAD"] = {"status": r2.status_code}
+                    webhook_url_ok = (r2.status_code in (200, 201, 202, 204, 301, 302, 307, 308, 401, 403, 405))
+                    if not webhook_url_ok:
+                        # Fallback to GET to accommodate servers that do not support HEAD
+                        r3 = client.get(webhook_url, headers={"Accept": "application/json"})
+                        probes[f"{webhook_url}:GET"] = {"status": r3.status_code}
+                        webhook_url_ok = (r3.status_code in (200, 201, 202, 204, 301, 302, 307, 308, 401, 403, 405))
+            except Exception as e:
+                probes[f"{webhook_url}:HEAD"] = {"error": str(e)}
+                webhook_url_ok = False
+        else:
+            webhook_url_ok = False
+
+    except Exception as e:
+        return HumbleFaxDiagnosticsOut(
+            dns_ok=dns_ok,
+            host=host,
+            resolved=resolved,
+            auth_present=auth_present,
+            auth_ok=False,
+            webhook_base=webhook_base,
+            webhook_url=webhook_url,
+            webhook_url_ok=False,
+            probes=probes,
+            error=str(e),
+        )
+
+    return HumbleFaxDiagnosticsOut(
+        dns_ok=dns_ok,
+        host=host,
+        resolved=resolved,
+        auth_present=auth_present,
+        auth_ok=auth_ok,
+        webhook_base=webhook_base,
+        webhook_url=webhook_url,
+        webhook_url_ok=bool(webhook_url) and webhook_url_ok,
+        probes=probes,
+    )
+
+
 # ===== Mobile pairing (dev-friendly) =====
 class PairIn(BaseModel):
     code: str

api/app/main.py

@@ -77,3 +77,12 @@ Troubleshooting
 - 413: file too large → raise `MAX_FILE_SIZE_MB`.
 - 415: unsupported file type → only PDF/TXT.
 - Sinch API errors: verify Project ID, API key/secret, and region.
+
+Diagnostics
+- Admin → Tools → Tunnels → Run Sinch Diagnostics
+- API: `GET /admin/diagnostics/sinch`
+  - Checks DNS resolution, OAuth/basic auth reachability, and v3 path compatibility.
+
+Implementation notes
+- The outbound adapter prefers the two‑step upload + send flow with multipart fallback.
+- The client automatically tries unversioned and `/v3` paths, and both unscoped and project‑scoped endpoints.

docs/SINCH_SETUP.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: Diagnostics
+nav_order: 45
+permalink: /diagnostics
+---
+
+# Diagnostics
+
+Faxbot includes lightweight, non-destructive diagnostics to validate provider connectivity and webhook reachability from inside the API container.
+
+Endpoints (admin)
+- GET `/admin/diagnostics/sinch` → DNS, auth presence, OAuth/basic probe, v3 path compatibility; returns exact probed URLs + status codes.
+- GET `/admin/diagnostics/humblefax` → DNS, Basic auth reachability, computed webhook URL reachability (HEAD/GET tolerant), exact probe statuses.
+- POST `/admin/diagnostics/run` → Bounded, trait-driven checks across active providers (health, Ghostscript if required, storage when inbound requires it).
+
+Admin Console
+- Tools → Tunnels page exposes “Run Sinch Diagnostics” and “Run HumbleFax Diagnostics” when relevant, and shows the raw JSON report.
+
+Troubleshooting Tips
+- DNS failures: verify container DNS or override `SINCH_BASE_URL`/`HUMBLEFAX_API_HOST` if using a custom region/host.
+- Auth failures: confirm credentials in Settings and ensure the selected auth method (OAuth2 vs Basic) matches provider configuration.
+- Webhook URL not reachable: set `PUBLIC_API_URL` (HTTPS) or use a stable named tunnel. Quick tunnels can be rejected by providers.
+
+Security
+- No PHI is logged. Probes avoid sending recipient numbers or document content.
+- Webhook reachability checks tolerate 405 Method Not Allowed to avoid accidental side effects.
+

docs/diagnostics.md

@@ -57,6 +57,7 @@ Webhooks
 Admin UI
 - Use Setup Wizard (HumbleFax) to enter keys and webhook secret.
 - “Register HumbleFax Webhook” button registers callbacks to `${public_api_url}/inbound/humblefax/webhook`.
+ - Run diagnostics: Tools → Tunnels → “Run HumbleFax Diagnostics” or `GET /admin/diagnostics/humblefax`.
 
 Security
 - No PHI is logged (only job IDs and meta counters). Recipients and fromNumber are masked in debug logs.
@@ -66,6 +67,17 @@ One‑shot tunnel + webhook setup
 - scripts/setup-humblefax-tunnel.sh starts the API + Cloudflare sidecar, detects the public URL, sets HUMBLEFAX_CALLBACK_BASE, and registers the webhook.
 - Requirements: Docker running; API_KEY (defaults to fbk_live_local_admin if unset).
 
+Diagnostics
+```
+curl -sS -H "X-API-Key: ${API_KEY:-fbk_live_local_admin}" \
+  http://localhost:8080/admin/diagnostics/humblefax | jq .
+```
+Fields
+- `dns_ok`: provider host resolves from inside the container
+- `auth_present`/`auth_ok`: credentials configured and accepted by the endpoint
+- `webhook_url_ok`: your computed webhook URL is reachable (tolerant of 405)
+  - If false, set `PUBLIC_API_URL` or `HUMBLEFAX_CALLBACK_BASE` to a stable HTTPS URL and retry.
+
 Run
 ```
 scripts/setup-humblefax-tunnel.sh

docs/humblefax.md

@@ -0,0 +1,36 @@
+---
+layout: default
+title: Mobile Pairing (iOS)
+nav_order: 50
+permalink: /apps/ios/pairing
+---
+
+# Mobile Pairing (iOS)
+
+The iOS app pairs to your Faxbot server using a short numeric code. Pairing returns a scoped API key and base URLs so the app can reach your server.
+
+Flow
+1) Admin Console → Tools → Tunnels → Generate iOS Pairing Code
+   - Shows the numeric code and a QR (no secrets) that expires quickly.
+2) iOS app → Settings → Pairing
+   - Enter the code or scan the QR. In dev (`ENABLE_LOCAL_ADMIN=true`), any code is accepted unless `MOBILE_PAIRING_CODE` is set.
+3) Server returns:
+   - `base_urls`: `{ local, tunnel, public }` – the app chooses a remote base when available.
+   - `token`: API key with minimal scopes: `inbound:list`, `inbound:read`, `fax:send`.
+
+API
+- POST `/admin/tunnel/pair` (admin) → `{ code, expires_at }`
+- POST `/mobile/pair` (no admin) → `{ base_urls, token }` (validates code; dev bypass available)
+
+Environment
+```
+ENABLE_LOCAL_ADMIN=true            # dev only; bypasses code check unless MOBILE_PAIRING_CODE is set
+# Optional fixed code (dev labs / demos)
+MOBILE_PAIRING_CODE=123456
+```
+
+Security Notes
+- Codes contain no secrets and expire rapidly.
+- The returned token is scoped and can be revoked from Admin → Keys.
+- In HIPAA mode, public/quick tunnel URLs are suppressed; prefer stable HTTPS (`PUBLIC_API_URL`) or HIPAA-capable VPN.
+

docs/mobile-pairing.md

@@ -21,7 +21,7 @@ Options
 
 Admin Console
 - Go to Settings → VPN Tunnel to configure provider and test connectivity.
-- Generate a short‑lived iOS pairing code (no secrets in QR or UI).
+- Generate a short‑lived iOS pairing code (no secrets in QR or UI). The Admin Console now renders the QR locally (no external QR service).
 - Terminal and Admin Actions remain local‑only; do not expose via tunnels.
 
 Environment reference (examples)
@@ -48,4 +48,4 @@ Security notes
 Troubleshooting
 - Use Tools → Scripts & Tests to tail cloudflared logs (dev only) and run reachability checks.
 - Ensure Ghostscript is installed; see readiness and diagnostics pages if tests fail.
-
+ - For HumbleFax, unstable quick tunnels can be rejected during webhook validation. Prefer a stable HTTPS `PUBLIC_API_URL` or a named tunnel.