Gate managed aliases behind public resolver readiness

Author: lucaomul

frontend/src/lib/api-client.ts

@@ -685,6 +685,8 @@ export interface EmailAliasListResponse {
   managed_enabled?: boolean;
   managed_ready?: boolean;
   managed_resolver_configured?: boolean;
+  managed_resolver_base_url?: string | null;
+  managed_public_backend_ready?: boolean;
   managed_inbound_ready?: boolean;
   managed_blockers?: string[];
   plus_fallback_enabled?: boolean;

frontend/src/routes/settings.tsx

@@ -51,6 +51,8 @@ function SettingsPage() {
   const [managedAliasEnabled, setManagedAliasEnabled] = useState(false);
   const [managedAliasReady, setManagedAliasReady] = useState(false);
   const [managedAliasResolverConfigured, setManagedAliasResolverConfigured] = useState(false);
+  const [managedAliasResolverBaseUrl, setManagedAliasResolverBaseUrl] = useState("");
+  const [managedAliasPublicBackendReady, setManagedAliasPublicBackendReady] = useState(false);
   const [managedAliasInboundReady, setManagedAliasInboundReady] = useState(false);
   const [managedAliasBlockers, setManagedAliasBlockers] = useState<string[]>([]);
   const [plusFallbackEnabled, setPlusFallbackEnabled] = useState(false);
@@ -68,6 +70,8 @@ function SettingsPage() {
   const frontendLoginRedirect =
     typeof window === "undefined" ? "http://127.0.0.1:4173/login" : `${window.location.origin}/login`;
   const authEmail = getAuthEmail();
+  const canGenerateFallbackAlias =
+    plusFallbackEnabled && gmailConnected && (!managedAliasEnabled || !managedAliasReady);
 
   useEffect(() => {
     const currentApiUrl = getApiUrl();
@@ -128,6 +132,8 @@ function SettingsPage() {
       setManagedAliasEnabled(Boolean(response.managed_enabled));
       setManagedAliasReady(Boolean(response.managed_ready));
       setManagedAliasResolverConfigured(Boolean(response.managed_resolver_configured));
+      setManagedAliasResolverBaseUrl(response.managed_resolver_base_url || "");
+      setManagedAliasPublicBackendReady(Boolean(response.managed_public_backend_ready));
       setManagedAliasInboundReady(Boolean(response.managed_inbound_ready));
       setManagedAliasBlockers(response.managed_blockers || []);
       setPlusFallbackEnabled(Boolean(response.plus_fallback_enabled));
@@ -504,13 +510,27 @@ function SettingsPage() {
                   Managed aliases are not live yet.
                   {" "}
                   {!managedAliasResolverConfigured ? "The backend resolver secret is missing. " : ""}
+                  {!managedAliasPublicBackendReady ? "The Cloudflare worker has no public backend URL it can reach. " : ""}
                   {!managedAliasInboundReady ? "Cloudflare inbound routing still needs to be marked ready. " : ""}
                 </p>
+                {managedAliasResolverBaseUrl ? (
+                  <p>
+                    Current resolver base URL:
+                    {" "}
+                    <span className="font-medium text-foreground">{managedAliasResolverBaseUrl}</span>
+                  </p>
+                ) : null}
                 {managedAliasBlockers.map((item) => (
                   <p key={item}>
                     {item}
                   </p>
                 ))}
+                {plusFallbackEnabled ? (
+                  <p>
+                    InboxAnchor can still generate a working Gmail fallback alias while the managed
+                    path is offline.
+                  </p>
+                ) : null}
               </div>
             ) : null}
             {!managedAliasEnabled ? (
@@ -552,14 +572,16 @@ function SettingsPage() {
                   onClick={handleGenerateAlias}
                   disabled={
                     aliasLoading ||
-                    (managedAliasEnabled && !managedAliasReady) ||
+                    (managedAliasEnabled && !managedAliasReady && !canGenerateFallbackAlias) ||
                     (!managedAliasEnabled && !plusFallbackEnabled)
                   }
                 >
                   {aliasLoading
                     ? "Generating..."
                     : managedAliasEnabled && managedAliasReady
                       ? "Generate InboxAnchor alias"
+                      : managedAliasEnabled && canGenerateFallbackAlias
+                        ? "Generate Gmail fallback alias"
                       : managedAliasEnabled
                         ? "Managed alias setup incomplete"
                       : plusFallbackEnabled

inboxanchor/api/v1/routers/frontend.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 import asyncio
+import ipaddress
 import json
 import secrets
 import threading
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Optional
+from urllib.parse import urlparse
 
 from fastapi import APIRouter, Header, HTTPException, Query
 from fastapi.responses import StreamingResponse
@@ -209,6 +211,29 @@ def _alias_resolver_secret_configured() -> bool:
     return bool(SETTINGS.alias_resolver_secret.strip())
 
 
+def _managed_alias_resolver_base_url() -> str:
+    return SETTINGS.alias_resolver_base_url.strip().rstrip("/")
+
+
+def _managed_alias_public_backend_ready() -> bool:
+    base_url = _managed_alias_resolver_base_url()
+    if not base_url:
+        return False
+    parsed = urlparse(base_url)
+    if parsed.scheme != "https":
+        return False
+    hostname = (parsed.hostname or "").strip().lower()
+    if not hostname or hostname in {"localhost", "127.0.0.1", "::1"}:
+        return False
+    if hostname.endswith(".local"):
+        return False
+    try:
+        address = ipaddress.ip_address(hostname)
+    except ValueError:
+        return True
+    return not (address.is_private or address.is_loopback or address.is_link_local)
+
+
 def _current_actor_email(authorization: Optional[str]) -> str:
     token = _extract_bearer_token(authorization)
     if not token:
@@ -796,6 +821,15 @@ def _managed_alias_blockers() -> list[str]:
         return blockers
     if not _alias_resolver_secret_configured():
         blockers.append("Set INBOXANCHOR_ALIAS_RESOLVER_SECRET on the backend.")
+    if not _managed_alias_resolver_base_url():
+        blockers.append(
+            "Set INBOXANCHOR_ALIAS_RESOLVER_BASE_URL to a public HTTPS URL for the InboxAnchor API."
+        )
+    elif not _managed_alias_public_backend_ready():
+        blockers.append(
+            "INBOXANCHOR_ALIAS_RESOLVER_BASE_URL must be a public HTTPS URL, "
+            "not localhost or a private IP."
+        )
     if not _managed_alias_inbound_ready():
         blockers.append(
             "Deploy the Cloudflare Email Routing worker, then set "
@@ -2956,6 +2990,8 @@ def frontend_list_aliases(
         "managed_enabled": _managed_aliases_enabled(),
         "managed_ready": _managed_aliases_ready(),
         "managed_resolver_configured": _alias_resolver_secret_configured(),
+        "managed_resolver_base_url": _managed_alias_resolver_base_url() or None,
+        "managed_public_backend_ready": _managed_alias_public_backend_ready(),
         "managed_inbound_ready": _managed_alias_inbound_ready(),
         "managed_blockers": _managed_alias_blockers(),
         "plus_fallback_enabled": _plus_alias_fallback_enabled(),
@@ -2992,7 +3028,8 @@ def frontend_generate_alias(
             "Revoking it in InboxAnchor blocks future reuse here."
         )
     else:
-        if _managed_aliases_enabled():
+        managed_configured_but_not_ready = _managed_aliases_enabled()
+        if managed_configured_but_not_ready and not _plus_alias_fallback_enabled():
             raise HTTPException(
                 status_code=503,
                 detail=(
@@ -3027,11 +3064,21 @@ def frontend_generate_alias(
         )
         alias_type = "plus"
         provider = "gmail"
-        note = (
-            "Fallback Gmail alias. It still lands in your mailbox automatically, but it exposes "
-            "part of the underlying inbox address because Gmail requires the original local-part "
-            "before the + tag."
-        )
+        if managed_configured_but_not_ready:
+            note = (
+                "Managed InboxAnchor aliases are not live yet, so InboxAnchor generated a "
+                "working Gmail fallback alias instead. "
+                + " ".join(_managed_alias_blockers())
+                + " This fallback still lands in your mailbox automatically, but it exposes "
+                "part of the underlying inbox address because Gmail requires the original "
+                "local-part before the + tag."
+            )
+        else:
+            note = (
+                "Fallback Gmail alias. It still lands in your mailbox automatically, but it "
+                "exposes part of the underlying inbox address because Gmail requires the "
+                "original local-part before the + tag."
+            )
     routing_label = _configure_alias_inbox_routing(
         alias_address=alias,
         label=payload.label,

inboxanchor/config/settings.py

@@ -83,6 +83,7 @@ class Settings:
         False,
     )
     alias_resolver_secret: str = os.getenv("INBOXANCHOR_ALIAS_RESOLVER_SECRET", "")
+    alias_resolver_base_url: str = os.getenv("INBOXANCHOR_ALIAS_RESOLVER_BASE_URL", "")
     alias_inbound_ready: bool = _as_bool(
         os.getenv("INBOXANCHOR_ALIAS_INBOUND_READY"),
         False,

tests/test_api.py

@@ -1525,6 +1525,11 @@ def test_frontend_managed_aliases_use_clean_domain(monkeypatch):
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_managed_enabled", True)
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_domain", "inboxanchor.com")
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_resolver_secret", "resolver-secret")
+    monkeypatch.setattr(
+        frontend_router.SETTINGS,
+        "alias_resolver_base_url",
+        "https://api.inboxanchor.com",
+    )
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_inbound_ready", True)
 
     signup = client.post(
@@ -1557,6 +1562,8 @@ def test_frontend_managed_aliases_use_clean_domain(monkeypatch):
     assert listed_payload["managed_enabled"] is True
     assert listed_payload["managed_ready"] is True
     assert listed_payload["managed_resolver_configured"] is True
+    assert listed_payload["managed_resolver_base_url"] == "https://api.inboxanchor.com"
+    assert listed_payload["managed_public_backend_ready"] is True
     assert listed_payload["managed_inbound_ready"] is True
     assert listed_payload["managed_blockers"] == []
     assert listed_payload["domain"] == "inboxanchor.com"
@@ -1568,6 +1575,7 @@ def test_frontend_managed_alias_generation_requires_live_inbound(monkeypatch):
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_managed_enabled", True)
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_domain", "inboxanchor.com")
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_resolver_secret", "")
+    monkeypatch.setattr(frontend_router.SETTINGS, "alias_resolver_base_url", "http://127.0.0.1:8010")
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_inbound_ready", False)
 
     signup = client.post(
@@ -1586,6 +1594,8 @@ def test_frontend_managed_alias_generation_requires_live_inbound(monkeypatch):
     assert listed_payload["managed_enabled"] is True
     assert listed_payload["managed_ready"] is False
     assert listed_payload["managed_resolver_configured"] is False
+    assert listed_payload["managed_resolver_base_url"] == "http://127.0.0.1:8010"
+    assert listed_payload["managed_public_backend_ready"] is False
     assert listed_payload["managed_inbound_ready"] is False
     assert listed_payload["managed_blockers"]
 
@@ -1599,6 +1609,49 @@ def test_frontend_managed_alias_generation_requires_live_inbound(monkeypatch):
     assert "managed aliases are configured but not live yet" in generated.json()["detail"].lower()
 
 
+def test_frontend_alias_generation_falls_back_to_plus_when_managed_path_is_not_live(monkeypatch):
+    from inboxanchor.api.v1.routers import frontend as frontend_router
+
+    monkeypatch.setattr(frontend_router.SETTINGS, "alias_managed_enabled", True)
+    monkeypatch.setattr(frontend_router.SETTINGS, "alias_domain", "inboxanchor.com")
+    monkeypatch.setattr(frontend_router.SETTINGS, "alias_resolver_secret", "")
+    monkeypatch.setattr(frontend_router.SETTINGS, "alias_resolver_base_url", "http://127.0.0.1:8010")
+    monkeypatch.setattr(frontend_router.SETTINGS, "alias_inbound_ready", False)
+    monkeypatch.setattr(frontend_router.SETTINGS, "alias_allow_plus_fallback", True)
+
+    signup = client.post(
+        "/auth/signup",
+        json={
+            "full_name": "Fallback Alias Operator",
+            "email": "fallback-managed-owner@example.com",
+            "password": "fallback-managed-pass",
+        },
+    )
+    token = signup.json()["token"]
+    client.put(
+        "/providers/gmail/connection",
+        json={
+            "status": "connected",
+            "account_hint": "fallback-owner@gmail.com",
+            "sync_enabled": True,
+            "dry_run_only": False,
+            "notes": "Connected for alias fallback tests.",
+        },
+    )
+
+    generated = client.post(
+        "/aliases/generate",
+        headers={"Authorization": f"Bearer {token}"},
+        json={"label": "travel", "purpose": "airlines"},
+    )
+
+    assert generated.status_code == 200
+    payload = generated.json()
+    assert payload["alias_type"] == "plus"
+    assert "+ia-travel" in payload["alias_address"]
+    assert "Managed InboxAnchor aliases are not live yet" in payload["note"]
+
+
 def test_frontend_alias_resolve_returns_forwarding_payload(monkeypatch):
     from inboxanchor.api.v1.routers import frontend as frontend_router
 
@@ -1609,6 +1662,11 @@ def test_frontend_alias_resolve_returns_forwarding_payload(monkeypatch):
         "alias_resolver_secret",
         "resolver-secret",
     )
+    monkeypatch.setattr(
+        frontend_router.SETTINGS,
+        "alias_resolver_base_url",
+        "https://api.inboxanchor.com",
+    )
     monkeypatch.setattr(frontend_router.SETTINGS, "alias_inbound_ready", True)
 
     signup = client.post(

workers/alias-gateway/README.md

@@ -25,6 +25,8 @@ Set this on the InboxAnchor API:
 INBOXANCHOR_ALIAS_MANAGED_ENABLED=true
 INBOXANCHOR_ALIAS_DOMAIN=inboxanchor.com
 INBOXANCHOR_ALIAS_RESOLVER_SECRET=replace-with-a-long-random-secret
+INBOXANCHOR_ALIAS_RESOLVER_BASE_URL=https://your-public-inboxanchor-api.example.com
+INBOXANCHOR_ALIAS_INBOUND_READY=true
 ```
 
 ## Required Worker vars
@@ -46,5 +48,7 @@ INBOXANCHOR_ALIAS_RESOLVER_SECRET=replace-with-the-same-random-secret
 ## Notes
 
 - This is the app-side and Worker-side scaffold.
+- The Worker must call a public HTTPS InboxAnchor API. A backend running only on
+  `127.0.0.1` or `localhost` cannot resolve aliases for Cloudflare.
 - Real `@inboxanchor.com` delivery still requires domain ownership, MX setup, and live Cloudflare
   Email Routing configuration.