lukas/webmail-client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Gmail (app-password) onboarding: auth_strategy routing + credential-helper panel

Browse Source 
Implements SPEC v1.5 §6.2.1–6.2.3 so Gmail (and Yahoo/iCloud/Outlook-personal)
onboard via a provider app password on the existing plain-password sync path —
no OAuth, no new sync code. Gmail was oauth2-only with OAuth unimplemented, so it
was previously un-addable.

Backend:
- presets.yaml: each preset declares an ordered `auth_strategy`; Gmail becomes
  `auth: password` + `[app_password, oauth2]`. App-password providers ship a
  data-driven `help:` block (deep_link, app_name_hint, i18n step keys, docs_url).
- discovery/types: CandidateConfig carries `auth_strategy` + `HelpBlock`; presets
  load them and autoconfig candidates derive a default from the detected auth.
- schemas/api: CandidateOut exposes auth_strategy + help; DiscoverResponse adds
  `google_oauth_enabled`.
- config: GOOGLE_OAUTH_ENABLED flag (default false) gates the OAuth fallback.

Frontend:
- ProviderCredentialPanel (wizard step 1.5): deep-link popup (user gesture),
  rendered steps, single paste field that strips whitespace, instant verify
  (auto POST /accounts/test at 16 chars → Connected ✓ / mapped error), and the
  auth_failed recovery branch with a gated "Sign in with Google instead" button.
- AccountWizard routes app-password providers to the panel, then a details step.
- i18n keys (en) for the panel + provider steps.

Honors the §6.2.2 prohibitions: no page automation, no real-password capture,
no scraping — deep-link + guide + paste + test only. Adds the v1.5 spec.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U72FZiF1W1pb8XxyWBTREA
This commit is contained in:
lukas
2026-08-04 19:59:52 +02:00
co-authored by Claude Opus 4.8
parent 0f686bbd5c
commit e5a87b37b1
11 changed files with 1380 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/accounts/discovery.py
+45 -4
View File
@@ -18,7 +18,13 @@ import yaml
from defusedxml import ElementTree as SafeET
from app.accounts.ssrf import SsrfError, assert_host_is_public, guarded_get
from app.accounts.types import CandidateConfig, DiscoveryResult, DiscoveryStep, ServerConfig
from app.accounts.types import (
CandidateConfig,
DiscoveryResult,
DiscoveryStep,
HelpBlock,
ServerConfig,
)
_PROBE_TIMEOUT = 5.0
@@ -28,6 +34,24 @@ _presets_cache: dict[str, CandidateConfig] | None = None
# --- presets -----------------------------------------------------------------
def _strategy_from_auth(auth: str) -> tuple[str, ...]:
"""Default credential flow when a preset doesn't declare one (SPEC §6.2.1)."""
return ("oauth2",) if auth == "oauth2" else ("password",)
def _help_block(raw: object) -> HelpBlock | None:
if not isinstance(raw, dict):
return None
steps = raw.get("steps", [])
return HelpBlock(
help_id=str(raw["help_id"]),
deep_link=str(raw["deep_link"]),
app_name_hint=str(raw.get("app_name_hint", "")),
steps=tuple(str(s) for s in steps) if isinstance(steps, list) else (),
docs_url=str(raw.get("docs_url", "")),
)
def _load_presets() -> dict[str, CandidateConfig]:
global _presets_cache
if _presets_cache is None:
@@ -41,7 +65,15 @@ def _load_presets() -> dict[str, CandidateConfig]:
smtp = ServerConfig(
prov["smtp"]["host"], prov["smtp"]["port"], prov["smtp"]["tls"], auth
)
candidate = CandidateConfig(imap, smtp, "preset", prov.get("oauth_provider"))
strategy = tuple(prov.get("auth_strategy", [])) or _strategy_from_auth(auth)
candidate = CandidateConfig(
imap,
smtp,
"preset",
prov.get("oauth_provider"),
strategy,
_help_block(prov.get("help")),
)
for domain in prov["domains"]:
mapping[domain.lower()] = candidate
_presets_cache = mapping
@@ -91,7 +123,9 @@ def parse_autoconfig_xml(xml_text: str) -> CandidateConfig | None:
smtp = _server("outgoingServer", "smtp")
if imap is None or smtp is None:
return None
return CandidateConfig(imap, smtp, "autoconfig")
return CandidateConfig(
imap, smtp, "autoconfig", auth_strategy=_strategy_from_auth(imap.auth)
)
# --- DNS SRV (RFC 6186) ------------------------------------------------------
@@ -191,7 +225,14 @@ async def _try_http_config(url: str, source: str) -> CandidateConfig | None:
candidate = parse_autoconfig_xml(xml_text)
if candidate is None:
return None
return CandidateConfig(candidate.imap, candidate.smtp, source, candidate.oauth_provider)
return CandidateConfig(
candidate.imap,
candidate.smtp,
source,
candidate.oauth_provider,
candidate.auth_strategy,
candidate.help,
)
async def discover(email: str) -> DiscoveryResult:
backend/app/accounts/presets.yaml
+59 -2
View File
@@ -2,27 +2,59 @@
# Matched by the domain of the email address. Each entry gives IMAP + SMTP
# host/port/tls, the auth kind, and an oauth provider id when applicable.
# tls: "ssl" (implicit TLS) | "starttls"; auth: "password" | "oauth2".
#
# auth_strategy (SPEC §6.2.1): ordered list of the credential flows the wizard
# offers, first = default. Values: app_password | oauth2 | password.
# - app_password → renders the ProviderCredentialPanel keyed by help.help_id
# (deep-link + guide + paste + test); the value is used as a normal IMAP/SMTP
# password, so it reuses the plain-password sync path (zero new sync code).
# - oauth2 → XOAUTH2 (M2); for Google it is the *fallback* offered when the app
# password path fails and GOOGLE_OAUTH_ENABLED is set.
# - password → the generic password box (self-hosted / ISP accounts).
# help (SPEC §6.2.2/6.2.3): data for the panel. steps are i18n message keys so
# the copy is translatable; app_name_hint is a suggested app-password label.
providers:
google:
domains: [gmail.com, googlemail.com]
imap: { host: imap.gmail.com, port: 993, tls: ssl }
smtp: { host: smtp.gmail.com, port: 465, tls: ssl }
auth: oauth2
auth: password
auth_strategy: [app_password, oauth2]
oauth_provider: google
help:
help_id: gmail
deep_link: https://myaccount.google.com/apppasswords
app_name_hint: "ultimo.email"
docs_url: https://support.google.com/mail/answer/185833
steps:
- wizard.help.gmail.step1
- wizard.help.gmail.step2
- wizard.help.gmail.step3
microsoft:
domains: [outlook.com, hotmail.com, live.com, msn.com]
imap: { host: outlook.office365.com, port: 993, tls: ssl }
smtp: { host: smtp.office365.com, port: 587, tls: starttls }
auth: oauth2
auth: password
auth_strategy: [app_password, oauth2]
oauth_provider: microsoft
help:
help_id: outlook
deep_link: https://account.microsoft.com/security
app_name_hint: "Webmail"
docs_url: https://support.microsoft.com/account-billing/using-app-passwords-with-apps-that-don-t-support-two-step-verification-5896ed9b-4263-e681-128a-a6f2979a7944
steps:
- wizard.help.outlook.step1
- wizard.help.outlook.step2
- wizard.help.outlook.step3
office365:
domains: [office365.com]
imap: { host: outlook.office365.com, port: 993, tls: ssl }
smtp: { host: smtp.office365.com, port: 587, tls: starttls }
auth: oauth2
auth_strategy: [oauth2]
oauth_provider: microsoft
yahoo:
@@ -30,39 +62,64 @@ providers:
imap: { host: imap.mail.yahoo.com, port: 993, tls: ssl }
smtp: { host: smtp.mail.yahoo.com, port: 465, tls: ssl }
auth: password
auth_strategy: [app_password]
help:
help_id: yahoo
deep_link: https://login.yahoo.com/account/security/app-passwords
app_name_hint: "Webmail"
docs_url: https://help.yahoo.com/kb/SLN15241.html
steps:
- wizard.help.yahoo.step1
- wizard.help.yahoo.step2
- wizard.help.yahoo.step3
icloud:
domains: [icloud.com, me.com, mac.com]
imap: { host: imap.mail.me.com, port: 993, tls: ssl }
smtp: { host: smtp.mail.me.com, port: 587, tls: starttls }
auth: password
auth_strategy: [app_password]
help:
help_id: icloud
deep_link: https://account.apple.com/account/manage
app_name_hint: "Webmail"
docs_url: https://support.apple.com/102654
steps:
- wizard.help.icloud.step1
- wizard.help.icloud.step2
- wizard.help.icloud.step3
gmx:
domains: [gmx.com, gmx.net, gmx.de]
imap: { host: imap.gmx.com, port: 993, tls: ssl }
smtp: { host: mail.gmx.com, port: 587, tls: starttls }
auth: password
auth_strategy: [password]
wp:
domains: [wp.pl]
imap: { host: imap.wp.pl, port: 993, tls: ssl }
smtp: { host: smtp.wp.pl, port: 465, tls: ssl }
auth: password
auth_strategy: [password]
onet:
domains: [onet.pl, poczta.onet.pl, op.pl]
imap: { host: imap.poczta.onet.pl, port: 993, tls: ssl }
smtp: { host: smtp.poczta.onet.pl, port: 465, tls: ssl }
auth: password
auth_strategy: [password]
o2:
domains: [o2.pl, tlen.pl]
imap: { host: imap.poczta.o2.pl, port: 993, tls: ssl }
smtp: { host: smtp.poczta.o2.pl, port: 465, tls: ssl }
auth: password
auth_strategy: [password]
interia:
domains: [interia.pl, interia.eu]
imap: { host: imap.poczta.interia.pl, port: 993, tls: ssl }
smtp: { host: smtp.poczta.interia.pl, port: 465, tls: ssl }
auth: password
auth_strategy: [password]
backend/app/accounts/schemas.py
+12
View File
@@ -22,11 +22,21 @@ class DiscoverRequest(BaseModel):
email: str
class HelpBlockOut(BaseModel):
help_id: str
deep_link: str
app_name_hint: str = ""
steps: list[str] = []
docs_url: str = ""
class CandidateOut(BaseModel):
imap: ServerConfigIn
smtp: ServerConfigIn
source: str
oauth_provider: str | None = None
auth_strategy: list[str] = ["password"]
help: HelpBlockOut | None = None
class DiscoveryStepOut(BaseModel):
@@ -38,6 +48,8 @@ class DiscoveryStepOut(BaseModel):
class DiscoverResponse(BaseModel):
candidates: list[CandidateOut]
steps: list[DiscoveryStepOut]
# Whether the wizard may offer the Google OAuth fallback (SPEC §6.2.1).
google_oauth_enabled: bool = False
class TestRequest(BaseModel):
backend/app/accounts/types.py
+15
View File
@@ -13,12 +13,27 @@ class ServerConfig:
auth: str = "password" # "password" | "oauth2"
@dataclass(frozen=True)
class HelpBlock:
"""Data-driven content for the wizard's ProviderCredentialPanel (SPEC §6.2.2)."""
help_id: str # gmail | yahoo | icloud | outlook
deep_link: str # provider app-password page (opened from a user gesture)
app_name_hint: str # suggested app-password label
steps: tuple[str, ...] # i18n message keys
docs_url: str = ""
@dataclass(frozen=True)
class CandidateConfig:
imap: ServerConfig
smtp: ServerConfig
source: str # preset | autoconfig | ispdb | srv | probe | manual
oauth_provider: str | None = None
# Ordered credential flows the wizard offers (SPEC §6.2.1): first = default.
# Values: app_password | oauth2 | password.
auth_strategy: tuple[str, ...] = ("password",)
help: HelpBlock | None = None
@dataclass(frozen=True)
backend/app/api/accounts.py
+15
View File
@@ -17,6 +17,7 @@ from app.accounts.schemas import (
DiscoverRequest,
DiscoverResponse,
DiscoveryStepOut,
HelpBlockOut,
ServerConfigIn,
TestRequest,
TestResponse,
@@ -27,6 +28,7 @@ from app.accounts.testing import AccountTestError, test_account
from app.accounts.types import CandidateConfig, ServerConfig
from app.api.errors import raise_api_error
from app.api.schemas import AccountOut
from app.config import get_settings
from app.db import get_session
from app.identity.deps import CurrentUser, require_csrf
from app.models import Account
@@ -62,6 +64,18 @@ def _candidate_out(c: CandidateConfig) -> CandidateOut:
smtp=_server_in(c.smtp),
source=c.source,
oauth_provider=c.oauth_provider,
auth_strategy=list(c.auth_strategy),
help=(
HelpBlockOut(
help_id=c.help.help_id,
deep_link=c.help.deep_link,
app_name_hint=c.help.app_name_hint,
steps=list(c.help.steps),
docs_url=c.help.docs_url,
)
if c.help
else None
),
)
@@ -109,6 +123,7 @@ async def discover_account(body: DiscoverRequest, user: CurrentUser) -> Discover
DiscoveryStepOut(method=s.method, status=s.status, detail=s.detail)
for s in result.steps
],
google_oauth_enabled=get_settings().google_oauth_enabled,
)
backend/app/config.py
+3
View File
@@ -59,6 +59,9 @@ class Settings(BaseSettings):
oauth_google_client_secret: str = Field(default="", alias="OAUTH_GOOGLE_CLIENT_SECRET")
oauth_ms_client_id: str = Field(default="", alias="OAUTH_MS_CLIENT_ID")
oauth_ms_client_secret: str = Field(default="", alias="OAUTH_MS_CLIENT_SECRET")
# Gates the "Sign in with Google instead" OAuth fallback in the wizard (SPEC
# §6.2.1). Off until an operator configures a verified Cloud project.
google_oauth_enabled: bool = Field(default=False, alias="GOOGLE_OAUTH_ENABLED")
@lru_cache(maxsize=1)