"""OAuth 接线脚手架（GitHub / Google，首版）。

诚实边界：这只是脚手架，不是已接通的真实登录。
- 本模块不向真实 GitHub / Google 发任何请求：默认的 HTTP 路径
  （``_urllib_post``）只在调用方真的传入真实 code 且配好
  client_secret 时才会被走到；单测一律用注入的 fake http 客户端。
- 本模块不硬编码任何真实 client_id / client_secret：client_id 由
  调用方以参数传入，client_secret 只从环境变量读
  （GitHub：``GITHUB_OAUTH_CLIENT_SECRET``，
  Google：``GOOGLE_OAUTH_CLIENT_SECRET``），绝不写文件、绝不
  硬编码、绝不出现在授权 URL 里。
- 本模块不存储 access_token：回调成功后只返回外部身份信息，
  access_token 在提取身份后即丢弃。如后续需要用 token 调 provider
  API，需另设计加密存储，本模块不提供。
- 本模块不创建本站会话：回调成功返回的只是外部身份字典，
  映射到本站用户、建会话、记审计由 server 层用 ``auth.AuthStore``
  完成（见 ``handle_oauth_callback`` 文档里的 server 层示例）。
  附带的 ``map_external_identity_to_local_user`` 只复用 auth.py 已有
  的 users 表（按确定性用户名查找/创建），不发明新的身份表，
  也不发明新的审计格式。

流程（标准 OAuth2 授权码流程的接线点）：
    state 生成（OAuthStateStore.create_state，存库，默认 10 分钟过期）
      -> 授权 URL（build_authorization_url / start_oauth_login）
      -> 用户在 provider 处授权，provider 回调本站并带回 code + state
      -> 回调（handle_oauth_callback）：验 state -> 换 token
         -> 取外部身份 -> 返回身份字典（server 层再映射 + 记审计）

零第三方依赖，只用 Python 标准库。
"""

import json
import os
import secrets
import sqlite3
import time
import urllib.parse
import urllib.request
from urllib.parse import parse_qs

# state 默认有效期：10 分钟。
STATE_TTL_SECONDS = 600

# 各 provider 的公开端点与默认 scope、client_secret 环境变量名。
# 这些是 OAuth 协议的公开端点地址，不是本站的任何凭证；真实应用
# 的 client_id / client_secret 仍需另行注册并经环境变量供给。
PROVIDERS = {
    "github": {
        "authorize_url": "https://github.com/login/oauth/authorize",
        "token_url": "https://github.com/login/oauth/access_token",
        "default_scope": "read:user",
        "client_secret_env": "GITHUB_OAUTH_CLIENT_SECRET",
    },
    "google": {
        "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth",
        "token_url": "https://oauth2.googleapis.com/token",
        "default_scope": "openid email profile",
        "client_secret_env": "GOOGLE_OAUTH_CLIENT_SECRET",
    },
}


class OAuthError(Exception):
    """OAuth 流程失败：state 无效/过期、换 token 失败、身份取不到等。

    ``reason`` 供调用方区分（例如记日志或返回不同的错误提示），
    取值：``unknown_provider`` / ``state_not_found`` / ``state_expired`` /
    ``state_mismatch`` / ``client_secret_missing`` / ``token_exchange_failed``
    / ``identity_missing``。
    """

    def __init__(self, message, reason=None):
        super().__init__(message)
        self.reason = reason


def _provider_config(provider):
    """取 provider 配置，未知 provider 抛 OAuthError（不猜端点）。"""
    config = PROVIDERS.get(provider)
    if config is None:
        raise OAuthError(
            "unknown provider: %r (supported: %s)"
            % (provider, ", ".join(sorted(PROVIDERS))),
            reason="unknown_provider",
        )
    return config


class OAuthStateStore:
    """基于 SQLite 的 OAuth state 存储。

    表 oauth_states：state（主键，随机串）、provider、redirect_uri、
    created_at（epoch 秒）。与 AuthStore 的 users / project_members /
    audit_log 表名不冲突，可共用同一个 db 文件。
    """

    def __init__(self, db_path):
        self.db_path = str(db_path)
        self.conn = sqlite3.connect(self.db_path)
        self.conn.execute(
            "CREATE TABLE IF NOT EXISTS oauth_states("
            "state TEXT PRIMARY KEY, "
            "provider TEXT, "
            "redirect_uri TEXT, "
            "created_at REAL)"
        )
        self.conn.commit()

    def create_state(self, provider, redirect_uri, ttl_seconds=STATE_TTL_SECONDS):
        """生成并入库一个随机 state，返回 state 字符串。

        ``ttl_seconds`` 只影响后续 ``validate_state`` 的过期判定，
        本函数不把过期时间单独存一列：判定统一用
        ``created_at + ttl_seconds``（validate 时传入的 ttl 须与
        创建时一致，默认两边都是 600 秒）。
        """
        _provider_config(provider)
        if not redirect_uri or not isinstance(redirect_uri, str):
            raise ValueError("redirect_uri required")
        state = secrets.token_urlsafe(32)
        self.conn.execute(
            "INSERT INTO oauth_states(state, provider, redirect_uri, created_at)"
            " VALUES(?, ?, ?, ?)",
            (state, provider, redirect_uri, time.time()),
        )
        self.conn.commit()
        return state

    def validate_state(self, state, provider, redirect_uri=None,
                       ttl_seconds=STATE_TTL_SECONDS, now=None):
        """校验 state，成功返回记录 dict，失败返回 None（绝不抛错）。

        校验规则（任一不满足即拒绝）：
        - state 在库里存在，否则 None（不存在）；
        - 记录的 provider 与传入一致，否则 None（不匹配，且不消耗
          该 state，避免一次错 provider 的尝试烧掉合法 state）；
        - redirect_uri 若传入，须与记录一致，否则 None（不匹配）；
        - ``now``（默认 time.time()）未超过
          ``created_at + ttl_seconds``，否则删除该行并返回 None（过期）。

        成功是“一次性”的：返回前删除该行，同一 state 第二次校验
        必然失败，防止重放。``now`` 参数只为单测注入时间，
        生产调用传默认即可。
        """
        if not state:
            return None
        if now is None:
            now = time.time()
        row = self.conn.execute(
            "SELECT state, provider, redirect_uri, created_at"
            " FROM oauth_states WHERE state = ?",
            (state,),
        ).fetchone()
        if row is None:
            return None
        stored_state, stored_provider, stored_redirect_uri, created_at = row
        if stored_provider != provider:
            return None
        if redirect_uri is not None and stored_redirect_uri != redirect_uri:
            return None
        if now > created_at + ttl_seconds:
            self.conn.execute(
                "DELETE FROM oauth_states WHERE state = ?", (state,))
            self.conn.commit()
            return None
        self.conn.execute(
            "DELETE FROM oauth_states WHERE state = ?", (state,))
        self.conn.commit()
        return {
            "state": stored_state,
            "provider": stored_provider,
            "redirect_uri": stored_redirect_uri,
            "created_at": created_at,
        }


def build_authorization_url(provider, client_id, redirect_uri, scope=None,
                            state=None):
    """拼授权 URL（纯字符串拼接，不发任何请求、不含任何 secret）。

    参数：
    - provider：``"github"`` 或 ``"google"``，未知抛 OAuthError；
    - client_id：调用方传入的真实应用 id，本模块不硬编码、不校验
      其真实性（注册见模块文档“真实 OAuth 仍缺什么”）；
    - redirect_uri：须与在 provider 处注册的回调地址一致；
    - scope：不传则用该 provider 的默认 scope（GitHub ``read:user``，
      Google ``openid email profile``）；
    - state：不传则现场随机生成一个（调用方若要校验，必须自己
      用 OAuthStateStore 存下它；推荐直接用 ``start_oauth_login``，
      它把生成 + 入库 + 拼 URL 一次做完）。

    返回的 URL 只含 client_id / redirect_uri / scope / state（Google
    另含 response_type=code），绝不含 client_secret。
    """
    config = _provider_config(provider)
    if not client_id or not isinstance(client_id, str):
        raise ValueError("client_id required")
    if not redirect_uri or not isinstance(redirect_uri, str):
        raise ValueError("redirect_uri required")
    if state is None:
        state = secrets.token_urlsafe(32)
    params = {
        "client_id": client_id,
        "redirect_uri": redirect_uri,
        "scope": scope or config["default_scope"],
        "state": state,
    }
    if provider == "google":
        params["response_type"] = "code"
    return config["authorize_url"] + "?" + urllib.parse.urlencode(params)


def start_oauth_login(state_store, provider, client_id, redirect_uri,
                      scope=None):
    """登录起点：生成并入库 state，再拼授权 URL。

    返回 ``(state, authorization_url)``：调用方把用户重定向到该 URL，
    provider 回调时带回的 state 交给 ``handle_oauth_callback`` 校验。
    """
    state = state_store.create_state(provider, redirect_uri)
    url = build_authorization_url(
        provider, client_id, redirect_uri, scope=scope, state=state)
    return state, url


def _urllib_post(token_url, payload):
    """默认的真实换 token 实现（urllib POST，返回解析后的 dict）。

    只在调用方未注入 http_client 且配好 client_secret 时走到；
    GitHub 的 token 端点默认回表单编码，本函数先试 JSON、
    失败再按表单解析，两种都解析不出则返回空 dict（由调用方
    判为换 token 失败）。
    """
    data = urllib.parse.urlencode(payload).encode("utf-8")
    request = urllib.request.Request(
        token_url, data=data, method="POST",
        headers={
            "Accept": "application/json",
            "Content-Type": "application/x-www-form-urlencoded",
        },
    )
    with urllib.request.urlopen(request, timeout=30) as response:
        raw = response.read().decode("utf-8", "replace")
    try:
        parsed = json.loads(raw)
        if isinstance(parsed, dict):
            return parsed
    except ValueError:
        pass
    form = parse_qs(raw)
    return {key: values[0] for key, values in form.items() if values}


def exchange_code_for_token(provider, code, client_id, redirect_uri,
                            http_client=None, client_secret=None):
    """用授权码换 token，返回 provider 的 token 响应 dict。

    http_client 注入约定（单测与未来真实接线共用同一签名）：
    ``http_client(token_url, payload_dict) -> dict``，其中 payload 含
    client_id / code / redirect_uri，Google 另含
    grant_type=authorization_code；client_secret 仅在有值时才放进
    payload。返回的 dict 须含 ``access_token``，否则视为换 token 失败；
    http_client 抛异常、或返回含 ``error`` 的 dict，同样视为失败。

    client_secret 供给：参数优先，未传则读该 provider 对应的环境变量
    （见 PROVIDERS 的 client_secret_env）。真实路径（http_client
    为 None）下仍无 secret 时，在发任何请求前就抛 OAuthError，
    绝不以空 secret 去撞真实端点。注入了 http_client 的测试路径
    允许 secret 缺省（fake 不需要真实 secret），生产调用不得依赖
    这一宽松分支。
    """
    config = _provider_config(provider)
    if not code or not isinstance(code, str):
        raise OAuthError("code required", reason="token_exchange_failed")
    if client_secret is None:
        client_secret = os.environ.get(config["client_secret_env"])
    if http_client is None and not client_secret:
        raise OAuthError(
            "client_secret not configured: set %s (never hard-code it)"
            % config["client_secret_env"],
            reason="client_secret_missing",
        )
    payload = {
        "client_id": client_id,
        "code": code,
        "redirect_uri": redirect_uri,
    }
    if provider == "google":
        payload["grant_type"] = "authorization_code"
    if client_secret is not None:
        payload["client_secret"] = client_secret
    client = http_client if http_client is not None else _urllib_post
    try:
        result = client(config["token_url"], payload)
    except Exception as exc:
        raise OAuthError(
            "token exchange failed: %s" % (exc,), reason="token_exchange_failed"
        ) from exc
    if not isinstance(result, dict) or result.get("error"):
        raise OAuthError(
            "token exchange failed: %r" % (result,),
            reason="token_exchange_failed",
        )
    if not result.get("access_token"):
        raise OAuthError(
            "token exchange returned no access_token",
            reason="token_exchange_failed",
        )
    return result


def _identity_from_token_or_userinfo(provider, token_result, userinfo_client):
    """从 token 响应或 userinfo 回调里抽外部身份。

    顺序：先看 token 响应自带的身份字段（fake / 某些 provider 会带
    id、login、email），没有则调 userinfo_client(access_token)；
    两边都没有可用身份时返回 None。真实 GitHub 的 token 响应不带
    身份，生产调用必须传 userinfo_client（例如调
    https://api.github.com/user 并取 login/id）；真实 Google 的
    id_token 解析同样走 userinfo_client 这一注入点，本模块不解析 JWT。
    """
    for source in (token_result,):
        external_id = source.get("id") or source.get("sub")
        login = source.get("login") or source.get("name")
        email = source.get("email")
        if external_id is not None or login is not None or email is not None:
            return {
                "provider": provider,
                "external_id": str(external_id) if external_id is not None else None,
                "login": login,
                "email": email,
            }
    if userinfo_client is None:
        return None
    try:
        info = userinfo_client(token_result["access_token"])
    except Exception:
        return None
    if not isinstance(info, dict):
        return None
    external_id = info.get("id") or info.get("sub")
    login = info.get("login") or info.get("name")
    email = info.get("email")
    if external_id is None and login is None and email is None:
        return None
    return {
        "provider": provider,
        "external_id": str(external_id) if external_id is not None else None,
        "login": login,
        "email": email,
    }


def handle_oauth_callback(state_store, provider, code, state, client_id,
                          redirect_uri, http_client=None, userinfo_client=None,
                          client_secret=None, now=None,
                          ttl_seconds=STATE_TTL_SECONDS):
    """处理 provider 回调：验 state -> 换 token -> 返回外部身份。

    成功返回 dict：``{"provider", "external_id", "login", "email"}``
    （缺失的字段为 None；external_id 至少与 login/email 其一存在，
    否则抛 OAuthError）。

    失败一律抛 OAuthError，不建任何会话、不写任何用户或审计记录：
    - state 不存在 -> reason=state_not_found；
    - state 过期 -> reason=state_expired（过期行在拒绝时被删除）；
    - state 与 provider / redirect_uri 不匹配 ->
      reason=state_mismatch；
    - 换 token 失败 -> reason=token_exchange_failed；
    - 拿不到外部身份 -> reason=identity_missing。

    本函数 deliberately 不做以下三件事，全部留给 server 层（签名
    与 auth.py 完全兼容，不发明新格式）：
    1. 映射到本站用户：可用 ``map_external_identity_to_local_user``
       （复用 AuthStore 的 users 表）或 server 层自己的映射；
    2. 建会话：本站首版会话就是 AuthStore 的 API key，OAuth 登录后
       是否发 key、发给谁，由 server 层决定，本模块不发；
    3. 记审计：server 层在映射出本站 user_id 后调用
       ``AuthStore.audit(user_id, project_id, "oauth_login",
       "%s:%s" % (provider, external_id))``——与 auth.py 现有
       audit(action, detail) 写法一致，project_id 为登录发生的
       项目上下文、无项目上下文时 server 层自定（例如空串），
       本模块不替 server 层选 project_id。

    access_token 在本函数内只用于取身份（经 userinfo_client），
    返回前即丢弃，本模块不存储、不返回它。
    """
    # 先区分拒绝原因（validate_state 本身只返回记录或 None）：
    # 不存在 / provider 或 redirect_uri 不匹配 / 过期各有 reason；
    # 过期行在此处删除（validate_state 的过期分支同样会删，幂等）。
    if now is None:
        now = time.time()
    peek = state_store.conn.execute(
        "SELECT provider, redirect_uri, created_at"
        " FROM oauth_states WHERE state = ?",
        (state,),
    ).fetchone() if state else None
    if peek is None:
        raise OAuthError("unknown state", reason="state_not_found")
    peek_provider, peek_redirect_uri, peek_created_at = peek
    if peek_provider != provider or (
            redirect_uri is not None and peek_redirect_uri != redirect_uri):
        raise OAuthError("state does not match provider/redirect_uri",
                         reason="state_mismatch")
    if now > peek_created_at + ttl_seconds:
        state_store.conn.execute(
            "DELETE FROM oauth_states WHERE state = ?", (state,))
        state_store.conn.commit()
        raise OAuthError("state expired", reason="state_expired")
    record = state_store.validate_state(
        state, provider, redirect_uri=redirect_uri, now=now,
        ttl_seconds=ttl_seconds)
    if record is None:
        raise OAuthError(
            "invalid state", reason="state_not_found")
    token_result = exchange_code_for_token(
        provider, code, client_id, redirect_uri,
        http_client=http_client, client_secret=client_secret)
    identity = _identity_from_token_or_userinfo(
        provider, token_result, userinfo_client)
    if identity is None:
        raise OAuthError(
            "cannot determine external identity: token response carries"
            " no identity fields and no userinfo_client was provided",
            reason="identity_missing",
        )
    if identity["external_id"] is None and identity["login"] is None \
            and identity["email"] is None:
        raise OAuthError(
            "empty external identity", reason="identity_missing")
    return identity


def map_external_identity_to_local_user(auth_store, provider, identity):
    """把外部身份映射到本站用户（复用 AuthStore 的 users 表）。

    确定性用户名：``oauth:<provider>:<login 或 external_id>``。
    已存在则返回 ``(user_id, False)``，不存在则经
    ``AuthStore.create_user`` 创建并返回 ``(user_id, True)``——
    创建时生成的 API key 明文按 auth.py 约定只应返回给调用方一次，
    本函数不返回它（调用方如需发 key 给登录用户，须另行决定
    发放方式，本模块不代发）。这只是脚手架的默认映射：生产若要
    把外部身份绑定到已有本站账号（而非每次新建），需另加绑定表
    与绑定流程，本函数不假装已做绑定。
    """
    _provider_config(provider)
    login = identity.get("login") or identity.get("external_id") \
        or identity.get("email")
    if login is None:
        raise OAuthError(
            "identity has no login/external_id/email to map from",
            reason="identity_missing",
        )
    username = "oauth:%s:%s" % (provider, login)
    row = auth_store.conn.execute(
        "SELECT id FROM users WHERE username = ?", (username,)
    ).fetchone()
    if row is not None:
        return row[0], False
    user_id, _api_key_plain = auth_store.create_user(username)
    return user_id, True