gift cancel: self-service cancellation with credit return and full audit trail

POST /broker/cancel-gift (dashboard broker identity, gift accounts only,
idempotent) + GET /broker/gift-status for the ended-state view. Semantics
match the gift lapse: row deactivated, account kept for a clean resume,
gateway budget zeroed, newsletter off — plus the return a lapse does not
do: unspent credit back to the co-op as a NEGATIVE credit_ledger row whose
reason names the cancellation and the original gift reference, deduped on
its own reference. Gifts ledger records inviter → recipient → 'cancelled
by recipient'. The user leaves the guests group for GUESTS_ENDED_GROUP_ID
(dashboard-only visibility for the ended state); the reaching-limits
notice is pre-marked so a self-cancelled guest is never told their
credits were spent. Tests: tests/test_gift_cancel.py (19 fixture checks,
network-guarded).
This commit is contained in:
inference-bot committed 2026-11-08 02:28:45 +00:00
1 parent 9c441dc0aa
commit 40fb75a34b
2 files changed
+538

No files matched your search

+255
View File
@@ -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. # exactly those two apps — nothing else is granted by group membership.
GUESTS_GROUP_ID = os.environ.get("GUESTS_GROUP_ID", "") 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 # Where a guest's "Become a member" button and email point (the contribution
# page — what actually starts a membership). Deliberately NOT the portal's # page — what actually starts a membership). Deliberately NOT the portal's
# credit-pack URL: a guest needs a membership, not a credit pack. # 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} 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, async def litellm_get_or_create_team(email: str, budget: float,
budget_duration: str | None = "30d") -> str: budget_duration: str | None = "30d") -> str:
"""Return the team_id for a member's budget team, creating it if needed. """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}") 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") @app.get("/broker/keys")
@limiter.limit("30/minute") @limiter.limit("30/minute")
async def broker_list(request: Request): 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) 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") @app.get("/broker/metrics")
@limiter.limit("30/minute") @limiter.limit("30/minute")
async def broker_metrics(request: Request, days: int = 90): async def broker_metrics(request: Request, days: int = 90):
+283
View File
@@ -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())