Files
member-portal/README.md
T
inference-bot 6d9074eefe gift accounts: $5 guest passes with time box, inviter ledger, auto member conversion
Operator feature: a member gives a friend access with $5 of credits, no OC
membership. Cloudron user lands in the guests group (chat + dashboard only),
LiteLLM team capped at GIFT_BUDGET with NO monthly reset, portal row marked
account_type='gift' with gift_expires_at set, gift welcome email, newsletter
subscription, and a gifts ledger recording inviter -> recipient (one gift per
inviter per 30 days, one per recipient ever).

Sweep safety: reconcile_memberships never deactivates a gift for lacking an
OC contribution; reconcile_gift_lifecycles lapses gifts by their own rules
(credits spent out, or the GIFT_DAYS time box) with member-deactivation
semantics. Guests are excluded from Loomio/Matrix invite lists, the reinvite
path, budget notices, the allowance reconciliation and the metrics member
counts.

Conversion: a gift whose OC identity appears under its own email converts
automatically (webhook + sweep + /admin/provision all funnel through
provision_member): group guests->members, cap lifted to allowance + carried
credits, anchor day kept, congrats email, full member onboarding.
/admin/gift-convert links a membership paid under a different OC email
(members.oc_email, matched by the sweep and webhook).

Fixture test: tests/test_gift_lifecycle.py (37 checks, network replaced by
a raising guard).
2026-11-08 02:05:37 +00:00

15 KiB
Raw Blame History

Member Portal — membership middleware for the Inference Cooperative

Reconciles three systems into one membership lifecycle:

System Role Source of truth for
Open Collective Billing Who is a paying member
Cloudron Identity/SSO Who can log in
LiteLLM Inference Who can use models, and how much

Architecture

Open Collective (billing)
        │ webhook
        ▼
┌─────────────────────────────┐
│  Member Portal (this app)   │
│  - OC webhook handler       │
│  - Cloudron user management │
│  - LiteLLM key management   │
│  - key-injection proxy      │
└─────────────────────────────┘
        ▲
        │ X-User-Email header (LibreChat forwards identity)
        │
LibreChat ──→ Member Portal ──→ LiteLLM ──→ backend

The three responsibilities

  1. Webhook handler (POST /webhook/opencollective) — listens for Open Collective membership events and activates/deactivates members.
  2. Key injector (/v1/*) — reads the member's email from the X-User-Email header, looks up their LiteLLM key, and forwards the request to the gateway with that key.
  3. Admin (/health, /) — health and status.

Configuration (environment variables)

Variable Purpose
CLOUDRON_API Cloudron API origin (auto-set by Cloudron)
CLOUDRON_TOKEN Cloudron API token (Read+Write)
MEMBERS_GROUP_ID Cloudron group ID for members (grants chat access)
LITELLM_BASE LiteLLM gateway URL
LITELLM_MASTER_KEY LiteLLM master key
PORTAL_KEK Required. Base64-encoded 32-byte key-encryption key. Member chat keys (members.key_token) are stored AES-256-GCM-encrypted at rest (enc1: prefix) and decrypted in memory only when served (dashboard, LibreChat key feed, LiteLLM management). Generate with python3 -c "import base64,os;print(base64.b64encode(os.urandom(32)).decode())". If unset, the portal runs but refuses to encrypt new keys, keeps legacy plaintext, and logs CRITICAL. Rotating it requires re-encrypting every row (decrypt with the old key, encrypt with the new).
ADMIN_TOKEN The portal's admin token (X-Admin-Token header) for the /admin/* endpoints the panel calls. Never the webhook URL token — that one cannot unlock /admin/* by design.
ALLOWANCE_POLICY report (default) | on. report computes every allowance decision and changes nothing; on performs renewals and sends the one reminder. Deactivation is gated separately by ALLOWANCE_DEACTIVATE.
ALLOWANCE_DEACTIVATE off (default) | on. When on, a member who was reminded and is still unpaid after the grace window is moved to the inactive group. Defaults off so renewals/reminders can run before anyone loses access.
PAYMENT_GRACE_DAYS Days after the single reminder before an unpaid member is deactivated (default 7).
GIFT_BUDGET Gift-account credit in USD (default 5.0).
GIFT_DAYS Gift-account time box in days from provisioning (default 60). The sweep deactivates an expired gift even with credits left.
GIFT_PER_INVITER_DAYS Rolling window for the one-gift-per-inviter limit (default 30).
GUESTS_GROUP_ID Cloudron group ID for gift accounts. The chat and dashboard apps' access restrictions list BOTH the members and guests groups, so a guest reaches exactly those two apps.

Gift accounts

A member can give a friend access to the co-op with $5 of credits — no Open Collective membership required. POST /admin/provision-gift (X-Admin-Token) with {"email", "name", "inviter": "<the gifting member's email>"} runs the gift pipeline: Cloudron user in the guests group, a LiteLLM team capped at GIFT_BUDGET with no monthly reset (the cap is the gift's whole life), the portal row marked account_type='gift' with the $5 held as non-expiring credit, gift_expires_at set to now + GIFT_DAYS, the gift welcome email (setup link, what they can use, Become-a-member, newsletter note), and a gifts ledger row (gifts table: inviter → recipient, expiry, status) for the abuse audit. Guards: one gift per inviter per GIFT_PER_INVITER_DAYS; one gift per recipient ever; the inviter must be an active member; an existing portal row under the recipient address is refused. Guests are subscribed to the newsletter and invited to NOTHING else (no Loomio, no Matrix).

Sweep safety. reconcile_memberships() never deactivates a gift for lacking an OC contribution. A gift lapses only by its own rules, handled by reconcile_gift_lifecycles() inside the sweep: credits spent out (LiteLLM's cap enforces the limit; the sweep retires the row) or the GIFT_DAYS time box. Deactivation is the same semantics as a member's — guests group → inactive, budget zeroed, row active=0, newsletter unsubscribed — and the account is KEPT so a returning payer resumes cleanly.

Guest → member conversion (automatic). When a gift's OC identity appears as a live BACKER/ADMIN with the account's own email — via the webhook or the nightly sweep — provision_member() routes the call to convert_gift_to_member(): the Cloudron user moves guests → members, the LiteLLM cap lifts to the member allowance + credits (unspent gift credit is carried — it already lives in credit_balance), the row becomes a normal member with the standard MEMBER_BUDGET, the anchor day (the gift's start date) is kept and the reset pinned to it, the congratulations email goes out, and the normal member onboarding runs (newsletter, Loomio + Matrix syncs, docs-RAG group, held-credit grants). When the contribution arrives under a DIFFERENT OC email it cannot auto-match: the operator links it with POST /admin/gift-convert {"email": "<gift account>", "oc_email": "<the OC email the contribution is under>"} — the row records members.oc_email, and the sweep and webhook treat that address as an additional matcher from then on.

Budget model

Governance decision (set in Loomio): a single sliding-scale Membership tier ($5–$20/month flexible) with a FLAT allowance for every member — MEMBER_BUDGET (default 15), reset on each membership payment and extendable with non-expiring purchased credit packs. The per-tier budgets the portal once shipped (free/member/supporter) are retired — there are no per-tier portal settings; the single env knob is MEMBER_BUDGET.

LibreChat wiring

Point LibreChat's custom endpoint at this portal (not directly at LiteLLM), and add the identity header:

endpoints:
  custom:
    - name: "Inference Cooperative"
      apiKey: "${LITELLM_KEY}"
      baseURL: "https://portal.inference.coop/v1"
      headers:
        X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"
      models:
        default: ["deepseek-v4-flash", "gpt-oss-120b"]
        fetch: true

Status

Scaffold — the three handlers are stubbed with the correct integration points. Remaining work before production:

  • Verify Open Collective webhook event names + payload shape → order.processed (every payment), new member (first only), firstPayment flag
  • Verify Cloudron user-creation API payload (role/group assignment) → POST /api/v1/users with {username, email, displayName, role, active} → group assignment via PUT /api/v1/users/:userId/groups with {groupIds: [...]}
  • Add a persistent store (SQLite) for email→key mapping → key/list returns token strings (not objects), so we store email→token locally
  • Verify LiteLLM key/generate + key/list payload shapes against live gateway → key/generate returns {key: "sk-..."}; key/list returns {keys: ["<token>", ...]}
  • Add HMAC signature verification for the OC webhook (if OC supports it)
  • Wire the OIDC addon for admin access

Scheduled tasks (scheduler addon)

Three jobs run inside the container via CloudronManifest.json → addons.scheduler:

  • membership_sweep (0 3,11,19 * * * UTC — three times a day) — sweep.sh calls the portal's own /admin/sweep (auth: the X-Admin-Token header with the portal's ADMIN_TOKEN — never WEBHOOK_TOKEN, which is the webhook's URL token and returns 403 on /admin/*) to reconcile members against the live Open Collective list: provisions missed signups, deactivates lapsed members, syncs Loomio + Matrix. Idempotent; a missed webhook self-heals within a day. The same sweep also runs the payment-driven allowance reconciliation (below).

    First-login activation hook: the sweep is also the backstop for service invites, but it is no longer the only trigger. When a member first presents themselves on the broker identity path (the dashboard's first login), the portal checks — only if their Loomio invite is still outstanding (loomio_invited_at is null) — that their Cloudron account is now activated (inviteAccepted), and if so fires the same idempotent Loomio + Matrix syncs as a background task. Established members cost one SELECT; the response never waits on Loomio or Matrix; failures are logged and non-fatal; unactivated accounts are never invited (the check fails closed). So a new member gets forum + Space access at their first login instead of at the next sweep.

  • rag_refresh (daily 3:30am UTC) — rag_refresh.py pulls this repo's sibling docs from the Gitea raw API (public, no credentials), uploads changed files to Open WebUI (OWUI_API_KEY), attaches them to the shared knowledge collection (DOCS_KNOWLEDGE_ID), reindexes, and re-grants the members group. State persists in /app/data/rag_refresh_state.json.

  • metrics_snapshot (daily 3:15am UTC) — metrics_snapshot.py records one row per day into the metrics_daily table: members, newsletter subscribers, Matrix membership, spend, request counts, energy/CO₂, and the Open Collective balance. A source that cannot be read yields NULL for that metric rather than a zero. spend_usd is the co-op-wide total and deliberately spans every team, the co-op's own operator accounts included; operator_spend_usd is the breakout of that portion, served through /broker/metrics so the member dashboard can show the co-op's own share alongside the total. oc_balance_usd is a daily snapshot of the collective's OC balance (the OC API has no historical series, so balance history accrues from these snapshots only — 2026-11-08 onward). --backfill rebuilds history idempotently (balance history cannot be backfilled: past balances were never recorded). Methodology: Energy and carbon metrics.

Verify after any manifest change: the deploy log must show setupAddons: ... scheduler ... listing all three tasks, and each script must succeed when run manually inside the container.

Allowance renewal (payment-driven, join-day anchored)

Each member has a monthly allowance (MEMBER_BUDGET, currently $15). The allowance renews on the day of the month the member joined, never on the day Open Collective happened to charge them — OC aligns every member's charge onto the collective's common billing day, so anchoring to the payment date let an early charge move the boundary and skip a cycle entirely. The join day is stored per member (members.anchor_day) and the reset is pinned there.

Whether the allowance renews is decided by asking Open Collective directly, on the sweep's own schedule (not inferred from webhook delivery): a member with a live recurring contribution (order status ACTIVE or PROCESSING — a payment in flight is not a missed payment) renews; a member with no live recurring contribution gets one reminder email, and is deactivated only after PAYMENT_GRACE_DAYS. One-time payments are not an allowance cycle — they top up the non-expiring credit balance and are untouched here. There are no annual contributors (verified 2026-11-04: 104 orders, 87 MONTHLY, 17 ONETIME, zero annual), so only the monthly case is implemented.

Every decision (renewed / reminded / deactivated, plus the payment date or its absence) is written to allowance_log and answerable from that record. Run POST /admin/allowance?mode=report (X-Admin-Token) for a no-op report that changes nothing; mode=send performs renewals and sends the reminder and requires ALLOWANCE_POLICY=on. Deactivation additionally requires ALLOWANCE_DEACTIVATE=on.

Allowance shortfall (a paid cycle OC truncated)

Open Collective aligns every recurring charge onto the collective's common billing day, so a member who joins mid-month is charged again well before a full month has elapsed — they pay for a full month and receive less than one. The co-op's remedy: credit the missing allowance (the flat MEMBER_BUDGET pro-rated for the days lost, FULL_PAID_MONTH_DAYS = 30, unrounded) as non-expiring credits — the same balance that extends the allowance and is spent only after it. It is never a share of what they paid.

The set is derived FROM DATA, on every sweep (POST /admin/sweep calls reconcile_allowance_shortfalls, as does POST /admin/shortfall-credits): each MONTHLY order's real charge history is read from Open Collective, and any consecutive pair on the SAME order less than a full month apart is a truncated cycle. Two subscriptions a member happens to hold are judged separately; a gap whose dates cannot be determined is skipped and logged. Each credit is keyed to the specific OC charge that caused it (credit_ledger.reference = the charge publicId), so a re-run credits nothing twice — dedupe is on the charge, not the member — and the ledger reason names the cycle so a member's question is answerable from it.

Member notices ride the same pass, but default OFF (ALLOWANCE_SHORTFALL_EMAILS=off); set it to on to send the staged notice, at most once per charge (shortfall_notices). mode=report on /admin/shortfall-credits previews the affected set and changes nothing.

Energy & carbon metrics

The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens, using per-model factors whose provenance varies: measured for GreenPT, assumed equal for one sibling model, and an explicit order-of-magnitude estimate for providers that disclose nothing. Only output tokens count, and a day with no measured tokens is recorded as NULL rather than zero.

Energy and carbon metrics documents the factor table, the formulas, the tripwire that catches unit errors, the schedule, and — most importantly — which parts are measurements and which are estimates. What members are told is in co-op/docs/energy.md.