M6: a single-page ?per_page=100 fetch silently truncates past 100 users — the box is at 99. New shared walkers (async + sync) page through /api/v1/users like the Matrix paths, capped at 50 pages. All six single- page call sites now walk: duplicate-email check (provisioning 409s), reinvite loop, Loomio activation filter, admin overview, member-email resolution, local MXID resolution. Failure behavior per site is preserved (page-1 failure fails loudly; later-page failure keeps what was read). M5: provisioning-time held-credit grant moved into grant_held_credits(): per hold, the status flip, balance move and ledger row commit in ONE transaction (the old code committed the flip before add_credits, so an exception between them left hold=granted and the member uncredited). Mirrors admin_held_grant, keyed on held:<hold_id> so re-runs are no-ops; mixed-case emails normalized. Tests in tests/test_portal_hardening.py.
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
- Webhook handler (
POST /webhook/opencollective) — listens for Open Collective membership events and activates/deactivates members. - Key injector (
/v1/*) — reads the member's email from theX-User-Emailheader, looks up their LiteLLM key, and forwards the request to the gateway with that key. - 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 |
OPENCOLLECTIVE_WEBHOOK_SECRET |
Optional webhook signature secret |
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). |
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). |
Tier budgets
Governance decision (set in Loomio). Defaults:
free— $2/month of tokensmember— $15/monthsupporter— $30/month
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),firstPaymentflag - Verify Cloudron user-creation API payload (role/group assignment)
→
POST /api/v1/userswith{username, email, displayName, role, active}→ group assignment viaPUT /api/v1/users/:userId/groupswith{groupIds: [...]} - Add a persistent store (SQLite) for email→key mapping
→
key/listreturns token strings (not objects), so we store email→token locally - Verify LiteLLM key/generate + key/list payload shapes against live gateway
→
key/generatereturns{key: "sk-..."};key/listreturns{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 (nightly 3am) —
sweep.shcalls the portal's own/admin/sweep(auth:X-Admin-Token=WEBHOOK_TOKEN) 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 24 hours. The same sweep also runs the payment-driven allowance reconciliation (below). - rag_refresh (nightly 3:30am) —
rag_refresh.pypulls 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 (nightly 3:15am) —
metrics_snapshot.pyrecords one row per day into themetrics_dailytable: members, newsletter subscribers, Matrix membership, spend, request counts, and energy/CO₂. A source that cannot be read yields NULL for that metric rather than a zero.spend_usdis the co-op-wide total and deliberately spans every team, the co-op's own operator accounts included;operator_spend_usdis the breakout of that portion, served through/broker/metricsso the member dashboard can show the co-op's own share alongside the total.--backfillrebuilds history idempotently. 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.