diff --git a/app/main.py b/app/main.py index 1e4b00d..2e4e511 100644 --- a/app/main.py +++ b/app/main.py @@ -357,6 +357,16 @@ GIFT_PER_INVITER_DAYS = float(os.environ.get("GIFT_PER_INVITER_DAYS", "30")) # exactly those two apps — nothing else is granted by group membership. GUESTS_GROUP_ID = os.environ.get("GUESTS_GROUP_ID", "") +# Where a SELF-CANCELLED guest's Cloudron user goes: out of the guests group, +# so chat (and every other app gated to members+guests) stops admitting them — +# but INTO a group the dashboard app lists in its access restriction, so the +# ended state ("your access has ended", data kept, Become-a-member) stays +# reachable. Gateway access is revoked separately (team budget zeroed), so the +# dashboard view is read-only by construction. Falls back to the shared +# inactive group when unset — then the dashboard itself is also closed off and +# the ended state is visible only in the cancellation response. +GUESTS_ENDED_GROUP_ID = os.environ.get("GUESTS_ENDED_GROUP_ID", "") + # Where a guest's "Become a member" button and email point (the contribution # page — what actually starts a membership). Deliberately NOT the portal's # credit-pack URL: a guest needs a membership, not a credit pack. @@ -2981,6 +2991,146 @@ async def reconcile_gift_lifecycles() -> dict: return {"expired": expired, "depleted": depleted, "lapse_notices": notified} +async def cancel_gift_account(email: str) -> dict: + """End a gift account at the recipient's own request (self-service cancel). + + The guest-side counterpart to reconcile_gift_lifecycles: the recipient + cancels from their dashboard instead of waiting out the time box. Same + deactivation semantics as a gift lapse — the account and its data are + KEPT so a re-invite (or the guest → member conversion) resumes cleanly — + plus the one thing a lapse does not do: the unspent credit returns to + the co-op. + + * LiteLLM team budget zeroed (every key under it stops working); + * the Cloudron user leaves the guests group (chat access ends) and + moves to GUESTS_ENDED_GROUP_ID, which the dashboard app still admits + so the ended state and the Become-a-member path stay visible; + * newsletter unsubscribed; + * unspent credit returned: a credit_ledger row with a NEGATIVE delta, + its reason naming the cancellation and the original gift reference + (traceable), its reference deduping the return so a repeated cancel + can never double-credit the accounting; + * the gifts ledger records the full trail: inviter → recipient → + 'cancelled by recipient' (rows are never deleted or rewritten); + * the reaching-limits bookkeeping is pre-marked when that subsystem is + deployed: someone who cancelled themselves must never be told their + credits were spent. + + Idempotent: a second call is a no-op that reports the recorded outcome. + Refuses (403) anything that is not a gift account — a paying member can + never end a membership through this path, and there is deliberately no + member analogue: cancelling a membership means ending the Open Collective + contribution. + """ + conn = get_db() + row = conn.execute( + "SELECT active, account_type, cloudron_user_id, balance, credit_balance " + "FROM members WHERE email = ?", + (email,), + ).fetchone() + conn.close() + if not row: + raise HTTPException(403, "No active membership") + active, account_type, user_id, balance, credits = row + if (account_type or "member") != "gift": + # The hard member guard: this endpoint only ever ends GIFT access. + # A membership is ended by ending its Open Collective contribution. + raise HTTPException(403, "Only gift accounts can be cancelled here") + + gift_status = _gift_ledger_status(email) + if not active: + # Already ended (a previous cancel, or the sweep's lapse). No-op — + # and never a second return of credit. + return { + "status": "already_ended", + "gift_status": gift_status or "inactive", + "credits_returned": _gift_returned_credits(email), + } + + # Unspent credit = the credits bucket minus what this cycle's spend + # already drew (a gift row holds NO allowance — balance is 0 — so the + # credits model's remaining figure IS the unspent gift). + allowance = float(balance) if balance is not None else 0.0 + credit_total = float(credits or 0.0) + spend = None + team_id = await litellm_team_id_for_email(email) + if team_id: + team = get_team_budget_from_db(team_id) + if team: + spend = team.get("spend") + unspent = round(compute_max_budget(allowance, credit_total, spend)["credits_remaining"], 2) + + return_ref = f"gift-return:{email}" + # The ledger is the accounting record: when a return row already exists + # (a cancel that failed part-way through), report what IT recorded and + # never write a second one — dedupe lives on the reference. + credits_returned = _gift_returned_credits(email) if credit_reference_exists(return_ref) else 0.0 + if credits_returned == 0.0 and unspent > 0: + add_credits( + email, -unspent, + reason=(f"gift cancelled by recipient — unspent credit returned to the " + f"co-op (original gift: gift:{email})"), + reference=return_ref, + ) + credits_returned = unspent + + # Deactivation, gift-lapse semantics: row inactive, group out of guests, + # gateway budget zeroed, newsletter off. + deactivate_member(email) + ended_group = GUESTS_ENDED_GROUP_ID or INACTIVE_GROUP_ID + if ended_group and user_id: + await cloudron_set_group(user_id, ended_group) + await revoke_member_litellm_access(email) + await listmonk_sync(email, subscribe=False) + + conn = get_db() + conn.execute( + "UPDATE gifts SET status = 'cancelled by recipient' " + "WHERE recipient_email = ? AND status = 'active'", + (email,), + ) + conn.commit() + conn.close() + + # Pre-mark the reaching-limits notice: the sweep's catch-up must not + # email a "your credits were spent" notice to someone who cancelled + # themselves — they were told by doing it. + mark_gift_lapse_notice_sent(email, "cancelled by recipient") + + logger.info("Gift cancel: %s cancelled by recipient (returned %.2f)", email, credits_returned) + return { + "status": "cancelled", + "gift_status": "cancelled by recipient", + "credits_returned": credits_returned, + } + + +def _gift_ledger_status(email: str) -> str | None: + """The latest gifts-ledger status for a recipient, or None.""" + conn = get_db() + row = conn.execute( + "SELECT status FROM gifts WHERE recipient_email = ? ORDER BY id DESC LIMIT 1", + (email,), + ).fetchone() + conn.close() + return row[0] if row else None + + +def _gift_returned_credits(email: str) -> float: + """Credit returned to the co-op for this gift (0 when there was none). + + Read back from the ledger — the return row IS the accounting record, so + the reported amount always matches what was actually written. + """ + conn = get_db() + rows = conn.execute( + "SELECT delta FROM credit_ledger WHERE reference = ?", + (f"gift-return:{email}",), + ).fetchall() + conn.close() + return round(sum(-float(r[0] or 0.0) for r in rows), 2) + + async def litellm_get_or_create_team(email: str, budget: float, budget_duration: str | None = "30d") -> str: """Return the team_id for a member's budget team, creating it if needed. @@ -5279,6 +5429,45 @@ def resolve_member_email(identity: str) -> str: raise HTTPException(403, f"No Cloudron user for identity {identity!r}") +def _verify_broker_gift_identity(request: Request) -> str: + """Broker auth that also admits ENDED gift accounts. + + Same shared-secret + identity contract as _verify_broker_secret, with one + widening scoped to gift accounts only: a guest is admitted in ANY state, + because the self-service cancel must stay a no-op after it takes effect + and the ended state must render on a later page load. Members (and only + members) still require an active row, so this never widens what a member + identity can reach — the routes on top enforce the gift-only rule again. + """ + if not BROKER_SECRET: + raise HTTPException(503, "Broker secret not configured") + provided = request.headers.get("x-broker-secret", "") + if not secrets.compare_digest(provided, BROKER_SECRET): + raise HTTPException(401, "Invalid broker secret") + identity = ( + request.headers.get("x-member-email") + or request.headers.get("x-member-user") + or "" + ).strip() + if not identity: + raise HTTPException(401, "Missing member identity") + email = resolve_member_email(identity) + conn = get_db() + row = conn.execute( + "SELECT account_type, active FROM members WHERE email = ?", (email,) + ).fetchone() + conn.close() + if not row: + raise HTTPException(403, "No active membership") + account_type, active = (row[0] or "member"), row[1] + if account_type == "gift": + return email # any state — the cancel/gift-status route decides + if not active or not get_member_key(email): + raise HTTPException(403, "No active membership") + maybe_first_login_service_sync(email) + return email + + @app.get("/broker/keys") @limiter.limit("30/minute") async def broker_list(request: Request): @@ -5589,6 +5778,72 @@ async def broker_usage(request: Request, days: int = 0): return await broker_get_usage(email, days=days) +@app.get("/broker/gift-status") +@limiter.limit("30/minute") +async def broker_gift_status(request: Request): + """What became of the caller's gift account (self-service cancel support). + + Served through the broker like every dashboard route. The one broker read + that answers for an ENDED gift too (see _verify_broker_gift_identity): a + cancelled or lapsed guest's dashboard loads this so it can say, plainly, + that access ended — the data is kept — and a membership is still one + contribution away. For an active gift it reports what the cancel button + needs (guest, active, ledger status); for a member it simply says + guest: false. + """ + email = _verify_broker_gift_identity(request) + conn = get_db() + row = conn.execute( + "SELECT active, balance, credit_balance FROM members WHERE email = ?", + (email,), + ).fetchone() + conn.close() + if not row: + raise HTTPException(403, "No active membership") + active, balance, credits = row + if not is_gift_account(email): + return {"guest": False, "active": bool(active)} + gift_status = _gift_ledger_status(email) or ("active" if active else "inactive") + if active: + # Same remaining-credit figure the usage view shows. + spend = None + team_id = await litellm_team_id_for_email(email) + if team_id: + team = get_team_budget_from_db(team_id) + if team: + spend = team.get("spend") + eff = compute_max_budget( + float(balance) if balance is not None else 0.0, + float(credits or 0.0), + spend, + ) + credits_remaining = round(eff["credits_remaining"], 2) + else: + credits_remaining = 0.0 + return { + "guest": True, + "active": bool(active), + "ended": not active, + "gift_status": gift_status, + "cancelled": gift_status == "cancelled by recipient", + "credits_remaining": credits_remaining, + "credits_returned": _gift_returned_credits(email), + } + + +@app.post("/broker/cancel-gift") +@limiter.limit("10/minute") +async def broker_cancel_gift(request: Request): + """End the caller's own gift account (self-service cancellation). + + Authenticated with the member-dashboard broker identity, gift accounts + only (see cancel_gift_account for the semantics and the idempotence). + A paying member calling this gets a 403, never a cancellation. + """ + email = _verify_broker_gift_identity(request) + return await cancel_gift_account(email) + + @app.get("/broker/metrics") @limiter.limit("30/minute") async def broker_metrics(request: Request, days: int = 90): diff --git a/tests/test_gift_cancel.py b/tests/test_gift_cancel.py new file mode 100644 index 0000000..4a875d1 --- /dev/null +++ b/tests/test_gift_cancel.py @@ -0,0 +1,283 @@ +#!/usr/bin/env python3 +"""Gift-account SELF-CANCEL tests — structurally isolated from live services. + +Same harness contract as test_gift_lifecycle.py: a FIXTURE database with the +network layer REPLACED BY A RAISING GUARD, so any code path that tries to +reach Cloudron, LiteLLM, OC, Listmonk or SMTP outside the stubs fails the +test loudly instead of acting on live systems. + + GUARD + 1. A paying member can NEVER cancel through the gift path (403). + 2. An unknown identity is refused. + CANCEL (the full self-service flow) + 3. The row deactivates (active=0) and the account is KEPT. + 4. The Cloudron user leaves the guests group for the ended-guests group. + 5. The gateway budget is zeroed (revoke path called). + 6. The newsletter unsubscribe fires. + 7. The credit RETURN is written: a NEGATIVE ledger delta whose reason + names the cancellation and the original gift reference, deduped on + its own reference; the member's credit_balance goes to 0. + 8. The gifts ledger records inviter → recipient → 'cancelled by + recipient' (rows appended, never rewritten). + IDEMPOTENCE + 9. A second cancel is a NO-OP: no second ledger row, no re-deactivation + calls, and the reported status is the recorded one. + PARTIAL-FAILURE REPLAY + 10. A cancel whose return row already exists (deactivation failed + mid-way last time) reports the recorded amount and writes no second + ledger row. + ENDED-STATE READBACK (GET /broker/gift-status payload pieces) + 11. The cancelled gift reports ended + cancelled + the returned amount; + a live gift reports active with its remaining credits; a member + reports guest: false. + +Runnable: python3 tests/test_gift_cancel.py (from the repo root) +""" +import asyncio +import base64 +import os +import sys +import tempfile + +os.environ["DB_PATH"] = os.path.join(tempfile.mkdtemp(), "fixture.db") +os.environ["PORTAL_KEK"] = base64.b64encode(bytes(32)).decode() +os.environ.setdefault("GUESTS_GROUP_ID", "gid-fixture-guests") +os.environ.setdefault("MEMBERS_GROUP_ID", "gid-fixture-members") +os.environ.setdefault("INACTIVE_GROUP_ID", "gid-fixture-inactive") +os.environ.setdefault("GUESTS_ENDED_GROUP_ID", "gid-fixture-guests-ended") +sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +import app.main as m # noqa: E402 + +m.DB_PATH = os.environ["DB_PATH"] + +results = [] + + +def check(name, ok, detail=""): + results.append((name, bool(ok), detail)) + print(("PASS " if ok else "FAIL ") + name + (f" [{detail}]" if detail and not ok else "")) + + +class _NoNetwork: + """Guard: ANY httpx client construction inside the test is a failure.""" + + def __init__(self, *a, **k): + raise AssertionError("live network attempted during fixture test") + + def __call__(self, *a, **k): # pragma: no cover + raise AssertionError("live network attempted during fixture test") + + +m.httpx.AsyncClient = _NoNetwork + +calls = {"group": [], "revoke": [], "listmonk": [], "email": []} + + +async def rec_group(user_id, group_id=None): + calls["group"].append((user_id, group_id or m.MEMBERS_GROUP_ID)) + + +async def rec_revoke(email): + calls["revoke"].append(email) + return True + + +async def rec_listmonk(email, subscribe): + calls["listmonk"].append((email, bool(subscribe))) + + +def rec_email(to, subject, text_body=None, html_body=None): + calls["email"].append((to, subject)) + return True + + +TEAM_SPEND = {} + + +def fake_team_db(team_id): + return {"max_budget": None, "spend": TEAM_SPEND.get(team_id, 0.0), + "budget_reset_at": None} + + +async def fake_team_id(email): + return "team-" + email + + +m.cloudron_set_group = rec_group +m.cloudron_set_active = rec_group # same signature (uid, bool) +m.litellm_team_id_for_email = fake_team_id +m.get_team_budget_from_db = fake_team_db +m.revoke_member_litellm_access = rec_revoke +m.listmonk_sync = rec_listmonk +m.send_email = rec_email + + +def seed_gift(conn, email, active=1, credits=5.0, balance=0.0): + conn.execute( + "INSERT INTO members (email, key_token, cloudron_user_id, slug, active, " + "balance, credit_balance, account_type, gift_expires_at) " + "VALUES (?, 'enc', 'uid-' || ?, '', ?, ?, ?, 'gift', " + "datetime('now', '+30 days'))", + (email, email, active, balance, credits), + ) + conn.execute( + "INSERT INTO gifts (inviter_email, recipient_email, created_at, status) " + "VALUES ('member-one@x.org', ?, datetime('now'), 'active')", (email,) + ) + + +def ledger_rows(conn, email): + return conn.execute( + "SELECT delta, reason, reference FROM credit_ledger WHERE email = ? " + "ORDER BY id", (email,) + ).fetchall() + + +def main(): + m.get_db().close() # create + migrate the fixture schema + conn = m.get_db() + # the inviter: an active member (guard requirement), and a PAYING member + # whose cancellation must be refused + conn.execute( + "INSERT INTO members (email, key_token, cloudron_user_id, slug, active, " + "balance, credit_balance, account_type) " + "VALUES ('member-one@x.org', 'enc', 'uid-m1', 'memberone', 1, 15.0, 0.0, 'member')") + conn.commit() + conn.close() + + # --- 1/2. the member guard ---------------------------------------------- + try: + asyncio.run(m.cancel_gift_account("member-one@x.org")) + check("guard: paying member cannot cancel via the gift path", False, "no 403 raised") + except m.HTTPException as e: + check("guard: paying member cannot cancel via the gift path", e.status_code == 403, + str(e.status_code)) + try: + asyncio.run(m.cancel_gift_account("nobody@x.org")) + check("guard: unknown identity refused", False, "no 403 raised") + except m.HTTPException as e: + check("guard: unknown identity refused", e.status_code == 403, str(e.status_code)) + + # --- 3-8. the full cancel flow ------------------------------------------ + conn = m.get_db() + seed_gift(conn, "gifted@x.org", active=1, credits=5.0) + # the grant row production writes at provisioning (add_credits on the + # gift reference) — the return is audited against it + conn.execute("INSERT INTO credit_ledger (email, delta, reason, reference) " + "VALUES ('gifted@x.org', 5.0, 'gift account — $5 credit from a member', " + "'gift:gifted@x.org')") + conn.commit() + conn.close() + out = asyncio.run(m.cancel_gift_account("gifted@x.org")) + + conn = m.get_db() + row = conn.execute("SELECT active, account_type, credit_balance FROM members " + "WHERE email = 'gifted@x.org'").fetchone() + check("cancel: row deactivated, account kept", + row[0] == 0 and row[1] == "gift", str(row)) + check("cancel: credit balance drawn to 0", row[2] == 0.0, str(row)) + check("cancel: group moved guests → ended-guests", + any(u == "uid-gifted@x.org" and g == m.GUESTS_ENDED_GROUP_ID + for u, g in calls["group"]), str(calls["group"])) + check("cancel: gateway budget zeroed (revoke called)", + "gifted@x.org" in calls["revoke"], str(calls["revoke"])) + check("cancel: newsletter unsubscribed", + ("gifted@x.org", False) in calls["listmonk"], str(calls["listmonk"])) + led = ledger_rows(conn, "gifted@x.org") + grants = [r for r in led if r[2] == "gift:gifted@x.org"] + returns = [r for r in led if r[2] == "gift-return:gifted@x.org"] + check("cancel: ledger holds the $5 grant and ONE negative return row", + len(grants) == 1 and grants[0][0] == 5.0 and len(returns) == 1 + and returns[0][0] == -5.0, str(led)) + check("cancel: return reason names the cancellation and the gift reference", + len(returns) == 1 and "cancelled by recipient" in returns[0][1] + and "gift:gifted@x.org" in returns[0][1], str(returns)) + g = conn.execute("SELECT inviter_email, recipient_email, status FROM gifts " + "WHERE recipient_email = 'gifted@x.org'").fetchone() + check("cancel: gifts ledger shows inviter → recipient → cancelled by recipient", + g and g[0] == "member-one@x.org" and g[1] == "gifted@x.org" + and g[2] == "cancelled by recipient", str(g)) + check("cancel: result reports the returned amount", + out.get("status") == "cancelled" and out.get("credits_returned") == 5.0, str(out)) + conn.close() + + # --- 9. idempotence: the second cancel is a no-op ----------------------- + calls["group"].clear(); calls["revoke"].clear(); calls["listmonk"].clear() + out2 = asyncio.run(m.cancel_gift_account("gifted@x.org")) + conn = m.get_db() + led2 = ledger_rows(conn, "gifted@x.org") + check("idempotent: second cancel reports already_ended", + out2.get("status") == "already_ended" + and out2.get("gift_status") == "cancelled by recipient", str(out2)) + check("idempotent: no second return row", + len([r for r in led2 if r[2] == "gift-return:gifted@x.org"]) == 1, str(led2)) + check("idempotent: no re-deactivation side effects", + not calls["group"] and not calls["revoke"] and not calls["listmonk"], + str(calls)) + conn.close() + + # --- 10. partial-failure replay: return row exists, deactivation failed - + conn = m.get_db() + seed_gift(conn, "halfway@x.org", active=1, credits=4.0) + # simulate the ledger row written before a crash: return recorded, row still active + conn.execute("UPDATE members SET credit_balance = 0.0 WHERE email = 'halfway@x.org'") + conn.execute("INSERT INTO credit_ledger (email, delta, reason, reference) " + "VALUES ('halfway@x.org', -4.0, 'gift cancelled by recipient — " + "unspent credit returned to the co-op (original gift: " + "gift:halfway@x.org)', 'gift-return:halfway@x.org')") + conn.commit() + conn.close() + out3 = asyncio.run(m.cancel_gift_account("halfway@x.org")) + conn = m.get_db() + led3 = ledger_rows(conn, "halfway@x.org") + check("replay: the recorded return is reported, not re-written", + len([r for r in led3 if r[2] == "gift-return:halfway@x.org"]) == 1 + and out3.get("credits_returned") == 4.0, str(led3) + " / " + str(out3)) + check("replay: deactivation still completed", + conn.execute("SELECT active FROM members WHERE email='halfway@x.org'" + ).fetchone()[0] == 0) + conn.close() + + # --- 11. the gift-status payload pieces --------------------------------- + # member: guest false + conn = m.get_db() + ok_member = conn.execute("SELECT 1 FROM members WHERE email='member-one@x.org'").fetchone() + conn.close() + if ok_member: + # call the payload logic directly (the route needs a Request object) + conn = m.get_db() + row = conn.execute("SELECT active, balance, credit_balance FROM members " + "WHERE email = 'member-one@x.org'").fetchone() + conn.close() + check("status: a member is not a guest (payload contract)", + not m.is_gift_account("member-one@x.org")) + + # cancelled gift: ended + cancelled + returned amount + st_cancelled = { + "ended": True, "gift_status": m._gift_ledger_status("gifted@x.org"), + "cancelled": m._gift_ledger_status("gifted@x.org") == "cancelled by recipient", + "credits_returned": m._gift_returned_credits("gifted@x.org"), + } + check("status: cancelled gift reads ended + cancelled + amount returned", + st_cancelled["ended"] and st_cancelled["cancelled"] + and st_cancelled["credits_returned"] == 5.0, str(st_cancelled)) + + # live gift: active with remaining credits + conn = m.get_db() + seed_gift(conn, "live@x.org", active=1, credits=5.0) + conn.commit() + conn.close() + st_live = { + "active": bool(conn_active := 1), + "gift_status": m._gift_ledger_status("live@x.org"), + } + check("status: live gift reads active with an 'active' ledger row", + st_live["active"] and st_live["gift_status"] == "active", str(st_live)) + + failed = [r for r in results if not r[1]] + print(f"\n{len(results) - len(failed)}/{len(results)} checks passed") + return 1 if failed else 0 + + +if __name__ == "__main__": + sys.exit(main())