Files
member-portal/README.md
T
inference-bot db64dac235 allowances: credit the shortfall when OC's billing day truncates a paid cycle
Open Collective aligns recurring charges onto the collective's common billing
day, so a mid-month joiner is charged again before a full month is up: they pay
for a full month and receive less than one. Credit the missing ALLOWANCE (the
flat MEMBER_BUDGET pro-rated for the days lost, unrounded) as non-expiring
credits.

- derived from the collective's real per-order charge history, on every sweep;
  any consecutive pair on the same order < a full month apart is truncated
- idempotent on the OC charge reference (dedupe on the charge, not the member)
- skips and logs any cycle whose dates cannot be determined
- ledger reason names the cycle; the notice is staged and defaults OFF
- [redacted member reference]'s remediated charge is excluded by ref

Tests: tests/test_allowance_shortfall.py (pure derivation).
2026-11-04 20:01:10 +00:00

190 lines
9.9 KiB
Markdown

# 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 |
| `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 tokens
- `member` — $15/month
- `supporter` — $30/month
## 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: ["<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.sh` calls 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.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** (nightly 3:15am) — `metrics_snapshot.py` records one row per
day into the `metrics_daily` table: 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_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. `--backfill` rebuilds history idempotently. 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`.