inference-bot d63f702ec3 privacy: redact member emails from portal logs (audit M1)
The _RedactWebhookPath filter now also strips email-shaped strings from
every log record — messages, %-format args (recursing into tuple/list/
dict args), and any exception text already attached to the record — the
same retention discipline the webhook token got in ops/security#2.
_send_email recipients, listmonk failures, Loomio invite lists and
provisioning/credit lines carry member addresses into container logs,
which persist on the host and ride the backups. MXIDs, counts, slugs and
amounts stay readable; the daily digest's own sanitisation is unchanged.
Filter keeps its never-break-logging guarantee (all redaction inside
try/except; non-string args untouched).

Live pre-state measured: 99 email-bearing lines in the current app log.
2026-11-05 16:17:21 +00:00

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:

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 (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.

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.

S
Description
Membership middleware: syncs Open Collective members with Cloudron users and LiteLLM keys
Readme
15 MiB
0 Stars 2 Watchers 0 Forks
Languages
Python 99.4%
Shell 0.5%
Dockerfile 0.1%