# 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. | | `GUESTS_ENDED_GROUP_ID` | Cloudron group a SELF-CANCELLED guest's user lands in: out of guests (chat access ends) but still admitted by the dashboard app, so the ended state and Become-a-member stay visible. Unset → the shared inactive group (dashboard access ends too). | ## 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": ""}` 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. **Self-service cancellation (recipient-initiated).** `POST /broker/cancel-gift` (dashboard broker identity) ends a gift at the recipient's own request: deactivation with the same kept-account semantics, the newsletter unsubscribed, and — the part a lapse does not do — any UNSPENT credit returned to the co-op as a negative `credit_ledger` row whose reason names the cancellation and the original gift reference (`gift-return:` is the dedupe reference, so a repeat cancel can never double-return). The gifts-ledger row records the full trail: inviter → recipient → 'cancelled by recipient'. The Cloudron user leaves the guests group for `GUESTS_ENDED_GROUP_ID` — chat and API access end, while the dashboard app (which lists that group in its access restriction) still admits them, so `GET /broker/gift-status` can show the ended state: access ended, data kept, Become-a-member still one contribution away. A paying member calling either route gets a 403 — cancelling a membership means ending the Open Collective contribution, and this endpoint is deliberately gift-only. **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": "", "oc_email": ""}` — 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: ```yaml 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: - [x] Verify Open Collective webhook event names + payload shape → `order.processed` (every payment), `new member` (first only), `firstPayment` flag - [x] 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: [...]}` - [x] Add a persistent store (SQLite) for email→key mapping → `key/list` returns token strings (not objects), so we store email→token locally - [x] Verify LiteLLM key/generate + key/list payload shapes against live gateway → `key/generate` returns `{key: "sk-..."}`; `key/list` returns `{keys: ["", ...]}` - [ ] 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](docs/energy-metrics.md). 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](docs/energy-metrics.md) 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`.