rfc-app/backend/app/funder.py

"""§6.7: per-RFC credential delegation — the funder role.

Three responsibilities live here:

  1. The runtime resolver. Given a (slug, picker_key) tuple, return the
     `BaseProvider` instance that should serve calls. When no consenting
     funder is in effect, this is the operator's pre-built provider.
     When a consenting funder is named on the RFC and has registered
     credentials for the picker_key's provider family, a fresh provider
     instance is constructed with the funder's credentials.

  2. The universe resolver. `resolve_funder_universe(slug, operator)`
     returns the funder's per-RFC universe — the subset of operator-
     enabled picker keys served by provider families the funder has
     registered. Returns None when no funder is in effect; an empty
     list when a consenting funder has no registrations intersecting
     the operator's enabled set.

  3. The consent + credential CRUD. Small helpers that the §17
     `/api/users/me/funder` endpoints in api.py call into.

The lighter half (this module) deliberately does NOT handle:

  - Mid-call failure with fallback. Per §6.7, the resolution is
    attribution-clean: a consenting-funder RFC is paid entirely from
    funder credentials. If construction fails or the call fails,
    that's a failure — no silent fallback to operator credentials.
  - Per-instance caching. Constructs fresh on every call. The cost is
    real (HTTP client setup) but bounded; caching across calls is
    deferred until evidence shows the cost bites.
  - Billing attribution surface, rotation ceremony, rate-limit
    attribution. All deferred to the operational-realities §19.2
    candidate.
"""
from __future__ import annotations

from . import db, providers as providers_mod
from .providers import BaseProvider


# ---------------------------------------------------------------------------
# Universe + provider resolution
# ---------------------------------------------------------------------------


def resolve_funder_universe(
    slug: str, operator_providers: dict[str, BaseProvider]
) -> list[str] | None:
    """The funder's registered universe for this RFC, or None.

    None means no consenting funder is in effect — caller falls back to
    the operator universe per §6.7. A list (possibly empty) means a
    consenting funder is in effect; the list is the subset of operator-
    enabled picker keys for which the funder has supplied a provider-
    family API key. An empty list means the named-and-consenting
    funder's registered providers don't intersect the operator's
    enabled set — the RFC drops into the §6.6 opt-out shape.
    """
    funder_user_id = consenting_funder_user_id(slug)
    if funder_user_id is None:
        return None
    registered = registered_provider_families(funder_user_id)
    return [
        picker_key
        for picker_key in operator_providers
        if (family := providers_mod.provider_family_for_picker_key(picker_key))
        and family in registered
    ]


def provider_for_rfc(
    slug: str,
    picker_key: str,
    operator_providers: dict[str, BaseProvider],
) -> BaseProvider | None:
    """The `BaseProvider` that should serve calls for (slug, picker_key).

    When a consenting funder is named on the RFC and has registered
    credentials for picker_key's provider family, returns a fresh
    funder-credentials provider instance. Otherwise returns the
    operator's pre-built provider. Returns None when picker_key isn't
    available in the resolved universe — caller refuses per §6.6/§6.7.
    """
    funder_user_id = consenting_funder_user_id(slug)
    if funder_user_id is None:
        return operator_providers.get(picker_key)
    family = providers_mod.provider_family_for_picker_key(picker_key)
    if family is None:
        return None
    row = db.conn().execute(
        "SELECT api_key FROM user_funder_credentials WHERE user_id = ? AND provider = ?",
        (funder_user_id, family),
    ).fetchone()
    if not row:
        return None
    return providers_mod.construct_for_funder(picker_key, row["api_key"])


# ---------------------------------------------------------------------------
# Consenting-funder lookup (the two-key §6.7 rule)
# ---------------------------------------------------------------------------


def consenting_funder_user_id(slug: str) -> int | None:
    """Resolve the consenting funder for an RFC, or None.

    The two-key rule per §6.7: `cached_rfcs.funder_login` names a user
    AND a `funder_consents` row exists for the (user, slug) pair. The
    third revocation path (account-disabled) is a structural commitment
    — when the disable affordance lands per §6.1, it joins this check
    as a third AND clause; until then, the two-key rule stands alone.
    """
    row = db.conn().execute(
        """
        SELECT u.id AS user_id
          FROM cached_rfcs r
          JOIN users u ON u.gitea_login = r.funder_login
         WHERE r.slug = ? AND r.funder_login IS NOT NULL
        """,
        (slug,),
    ).fetchone()
    if not row:
        return None
    consent = db.conn().execute(
        "SELECT 1 FROM funder_consents WHERE user_id = ? AND rfc_slug = ?",
        (row["user_id"], slug),
    ).fetchone()
    if not consent:
        return None
    return row["user_id"]


# ---------------------------------------------------------------------------
# Credential + consent CRUD (called by the §17 funder endpoints)
# ---------------------------------------------------------------------------


def registered_provider_families(user_id: int) -> set[str]:
    """The provider families this user has registered credentials for."""
    rows = db.conn().execute(
        "SELECT provider FROM user_funder_credentials WHERE user_id = ?",
        (user_id,),
    ).fetchall()
    return {r["provider"] for r in rows}


def list_credentials(user_id: int) -> list[dict[str, str]]:
    """Per-provider registration metadata for the funder surface.

    The API key itself is never returned to the client. The list shape
    is one row per registered family, with the registration timestamp
    for the settings page's display.
    """
    rows = db.conn().execute(
        """
        SELECT provider, created_at, updated_at
          FROM user_funder_credentials
         WHERE user_id = ?
         ORDER BY provider
        """,
        (user_id,),
    ).fetchall()
    return [
        {"provider": r["provider"], "created_at": r["created_at"], "updated_at": r["updated_at"]}
        for r in rows
    ]


def upsert_credential(user_id: int, provider: str, api_key: str) -> None:
    """Register or replace an API key for a provider family.

    Idempotent. Callers gate the provider against
    `providers_mod.FUNDER_PROVIDER_FAMILIES` and against the operator's
    enabled set (per §6.7, the funder cannot expand the operator
    universe) before calling here.
    """
    db.conn().execute(
        """
        INSERT INTO user_funder_credentials (user_id, provider, api_key)
        VALUES (?, ?, ?)
        ON CONFLICT(user_id, provider) DO UPDATE SET
            api_key = excluded.api_key,
            updated_at = datetime('now')
        """,
        (user_id, provider, api_key),
    )


def delete_credential(user_id: int, provider: str) -> bool:
    """Remove a registered key. Returns True if a row was deleted.

    Existing `funder_consents` rows are intentionally left in place —
    the resolved funder universe for affected RFCs simply shrinks. If
    the funder later re-registers the family, those RFCs resume
    drawing on the funder's universe without re-consenting.
    """
    cur = db.conn().execute(
        "DELETE FROM user_funder_credentials WHERE user_id = ? AND provider = ?",
        (user_id, provider),
    )
    return cur.rowcount > 0


def list_consents(user_id: int) -> list[str]:
    """The RFC slugs this user has consented to fund. Sorted for stable display."""
    rows = db.conn().execute(
        "SELECT rfc_slug FROM funder_consents WHERE user_id = ? ORDER BY rfc_slug",
        (user_id,),
    ).fetchall()
    return [r["rfc_slug"] for r in rows]


def add_consent(user_id: int, slug: str) -> None:
    """Idempotent funder-side opt-in to fund this RFC.

    Callers gate with `has_any_credentials` so a consent without any
    registered universe (which would be inert) is refused at the API
    layer rather than written.
    """
    db.conn().execute(
        """
        INSERT INTO funder_consents (user_id, rfc_slug) VALUES (?, ?)
        ON CONFLICT(user_id, rfc_slug) DO NOTHING
        """,
        (user_id, slug),
    )


def remove_consent(user_id: int, slug: str) -> bool:
    """Withdraw consent per §6.7's first revocation path. Returns True
    if a row was removed."""
    cur = db.conn().execute(
        "DELETE FROM funder_consents WHERE user_id = ? AND rfc_slug = ?",
        (user_id, slug),
    )
    return cur.rowcount > 0


def has_any_credentials(user_id: int) -> bool:
    row = db.conn().execute(
        "SELECT 1 FROM user_funder_credentials WHERE user_id = ? LIMIT 1",
        (user_id,),
    ).fetchone()
    return row is not None