This document covers three things:

1. Reporting a vulnerability — how to disclose a hole responsibly.
2. Deploying Agora securely — the operator hardening checklist (TLS, database encryption, secrets, network posture).
3. Security model and known limitations — what the server enforces by design, and the honest list of what to harden next.

Agora is pre-1.0 software. The model below is sound, but the surface is still evolving — read the known-limitations section before running it on untrusted, high-stakes traffic.

Please do not open a public GitHub issue for security problems.

• Preferred: GitHub Private Vulnerability Reporting — the Security → Report a vulnerability button on this repository (creates a private advisory only maintainers can see).
• Email fallback: security@recoverysky.org (or jenova@recoverysky.org). PGP available on request.

Please include: affected version/commit, a description, reproduction steps or a PoC, and impact. If you can, suggest a fix.

What to expect: acknowledgement within 3 business days, an initial assessment within 7 days, and coordinated disclosure once a fix ships. We'll credit you in the release notes unless you'd rather stay anonymous. We don't run a paid bounty (yet), but we're deeply grateful — this is a community project and you're helping keep real people safe. 💜

Being pre-1.0, only the latest minor receives security fixes. Run the most recent tagged release.

Agora is self-hosted, so a meaningful share of its security is your deployment. The application is written to be the trust boundary (see Security model), but it deliberately delegates transport security, TLS, and network isolation to your infrastructure. This checklist is the contract.

Bundled shortcut: docker compose --profile supabase up (or --profile selfhost) brings up the API with a Caddy front door that does all of this automatically — auto-HTTPS (Let's Encrypt, auto-renewed), http → https redirect, HSTS + security headers, WebSocket upgrade, body-size cap, and an authoritative X-Forwarded-For — and it also serves the admin SPA + routes every service (one hop). Set SERVER_NAME + RATE_LIMIT_TRUSTED_HOPS=1. See deploy/proxy/README.md. The rest of this checklist is for bringing your own proxy/CDN instead.

Put a reverse proxy (Caddy, nginx, Traefik) or a CDN (Cloudflare) in front and terminate HTTPS there. Agora speaks HTTP behind it; the public hop must be HTTPS.

• Redirect http → https.
• Send HSTS: Strict-Transport-Security: max-age=63072000; includeSubDomains; preload.
• The API does not set security headers itself — your proxy must add at minimum: X-Content-Type-Options: nosniff, a sensible Content-Security-Policy, and Referrer-Policy: strict-origin-when-cross-origin.
• socket.io (chat realtime) needs WebSocket upgrade proxied on the same origin.

Rate limiting derives the client IP from X-Forwarded-For, read RATE_LIMIT_TRUSTED_HOPS hops from the right (the entries trusted proxies appended), so a client-supplied left-most value can't poison it. Your edge must set X-Forwarded-For to the real peer and not trust an inbound one — the bundled Caddy front door does this by default (set RATE_LIMIT_TRUSTED_HOPS=1 — Caddy is the only proxy; use 2 if you chain a CDN/LB in front of it). Only expose the API through the proxy — never bind it to a public interface directly.

• Managed Supabase Postgres (the default target) is encrypted at rest (AES-256) by the platform, with automated backups. Nothing to do beyond keeping your project access controls tight.
• In transit: ensure DATABASE_URL enforces TLS — append ?sslmode=require (or stricter, verify-full, with the CA) so the app↔Postgres hop is encrypted. Verify this is present; the app does not force it for you.
• Self-hosted Postgres: enable ssl = on with a real certificate, turn on transparent data-encryption / encrypted volumes (LUKS/EBS-encryption), and restrict pg_hba.conf to the app's network. Use the transaction pooler connection (port 6543, prepare:false) the app expects.

• ACCESS_TOKEN_SECRET signs every access JWT (HS256). Use ≥ 32 bytes of randomness: openssl rand -base64 48. Rotating it invalidates all live access tokens (refresh still works) — a useful emergency lever.
• CRON_SECRET, MODERATION_SERVICE_SECRET, project webhook_secret — random, high-entropy, unique per deployment. These gate internal/cron routes and sign webhooks (all compared in constant time).
• SUPABASE_SERVICE_ROLE_KEY is god-mode over your Supabase project. Agora confines it to Auth + Storage only (lazy client) — keep it server-side only, never in any client bundle or the admin app. The admin/SDK use the anon/publishable key.
• Inject secrets via your platform's secret store or env — never commit .env, never bake secrets into the Docker image. The root .env is git-ignored; keep it that way.

CORS_ORIGIN defaults to *. For production set it to your exact app origin(s) (https://app.example.com) — both the REST API and socket.io read it. A wildcard with credentialed requests is a cross-origin risk.

Edge rate limiting is off unless configured. Set RATE_LIMIT_MAX (per-IP per window) and the stricter RATE_LIMIT_AUTH_MAX for /auth/*, with RATE_LIMIT_WINDOW_SECONDS (default 60). Note it is in-memory per process by default — see known limitations. Set REDIS_URL to hold the cap in a shared Redis store across replicas (fail-open to in-memory if Redis is down); either way, pair it with proxy/WAF/CDN rate limiting for real quota enforcement.

The app does not currently enforce a global body-size limit (see roadmap). The bundled Caddy edge caps it (MAX_BODY_SIZE, default 25MB); with your own proxy set client_max_body_size (nginx) / equivalent to bound uploads and JSON bodies.

• OPERATOR_USER_IDS / OPERATOR_EMAILS grant a project-wide god-view. Keep the allowlist minimal; prefer the steward role (least-privilege, DB-granted) for day-to-day moderation/conflict work.
• The Supabase Storage agora bucket is public — an accepted design choice (most media is public by nature: post images, avatars, public-space content). Paths are random projectId/.../fileId v4 UUIDs (~122 bits each), so objects can't be enumerated/guessed — the only exposure is a leaked URL (a forwarded link, a referrer header, a log). So: don't upload secrets, and be aware that a leaked URL to a private attachment (DM / private-space) is world-readable. If that matters for your deployment, put private uploads behind your own signed-URL/download gate.
• The self-hosted storage backend (STORAGE_PROVIDER=s3 → MinIO/S3, docs/SELF-HOSTING.md) carries the identical posture: the api creates the bucket with an anonymous public-read policy and the same unguessable-UUID keys — same accepted trade-off, same "don't upload secrets" caveat. Serve it through the Caddy front door /media mount (never expose MinIO :9000 publicly), and treat the MinIO root credentials + POSTGRES_PASSWORD as real secrets (strong values, .env out of VCS).
• Verify Supabase automated backups (or your own pg_dump schedule) and test a restore.

Track releases (security fixes land in the latest minor), and keep Supabase, the proxy, and the base image current.

The selfhost profile runs Supabase Auth (GoTrue) as its own container. Its posture, and the knobs that keep it that way:

• /auth/v1/* is public on purpose — OAuth providers redirect to /auth/v1/callback and confirmation emails link to /auth/v1/verify. That is the same exposure as cloud Supabase. The admin surface under /auth/v1/admin/* is gated by GoTrue itself: it accepts only a JWT whose role is service_role, verified against GOTRUE_JWT_SECRET.
• SUPABASE_SERVICE_ROLE_KEY is a root credential for the identity store (it can mint, read and delete any user). It belongs on the API service only, from a secrets store — never in a client, a /config.js, or a log. The anon key is deliberately low-privilege and is the one supabase-js uses for password sign-in.
• The :9998 shim is internal-only. The proxy exposes a second, unauthenticated path-stripping listener so the API can reach GoTrue; it must never be published to the host or a public network. In dev compose it is published (the API runs on the host there) — a dev-only concession.
• Redirect targets are allowlisted twice. /oauth/callback hands the browser a live Agora session in the URL fragment, so redirectAfterAuth is validated on /oauth/authorize and re-validated on the callback against OAUTH_REDIRECT_ALLOWED_ORIGINS (falling back to PUBLIC_BASE_URL; failing closed with 503 when neither is set). GoTrue's own GOTRUE_URI_ALLOW_LIST guards its hop. Keep both lists to exact origins you control.
• Provider secrets rotate. Apple's client secret is a ≤180-day JWT (gen-apple-client-secret.mjs); treat its expiry as an operational deadline. Google/GitHub secrets are long-lived — revoke and regenerate from the provider console if they leak.
• GoTrue's database role is least-privilege by design — supabase_auth_admin owns only the auth schema. On a non-supabase/postgres database use apps/api/scripts/bootstrap-gotrue-role.sql rather than reusing the application's DB role, which would hand GoTrue read/write on every table. See docs/SELF-HOSTING.md.

How Agora is designed to be secure — useful context for both operators and reviewers.

• The server is the trust boundary. The app connects to Postgres with a role that bypasses RLS; all authorization (ownership, space roles, operator/steward checks, moderation visibility) is enforced in the request handlers, not in the database. Treat the API as the only thing standing between a client and the data.
• Private by default (auth wall). Every /v7/:projectId/* request requires an authenticated account. The gate is authWall (packages/core/src/middleware/auth.ts), mounted group-wide; its AUTH_WALL_ALLOWLIST constant is the API's entire anonymous surface (the pre-sign-in flows: /auth/*, OAuth authorize/callback, /projects/lean, the VAPID public key, and the dev JWT-signing stub). New routes are authed by default — fail closed. Adding an allowlist entry is a security decision requiring spec rationale; a unit test pins the list's exact contents. The RLS 0008 anon public-read policies were revoked (0064) so the DB layer states the same posture. Uploaded media remains fetchable by unguessable URL (see the storage section) — the one anonymous-readable artifact class, queued for a signed-URL follow-up.
• /v7/:projectId/public/* — the second deliberate hole (internet-public entities). Full guide: docs/PUBLIC-API.md. GET-only; each route independently re-derives entity.public AND space-is-public live (the gate itself is never cached) and 404s (never 403s) the moment any of that goes false — soft-delete, moderation removal, or the space going members-only un-exposes a post even while its public flag is still true. Takedown is instant at the origin and for any reader who reloads, but bounded — not instant — at shared caches. Success responses carry Cache-Control: public, max-age=0, s-maxage=300, must-revalidate plus an ETag (lib/public-cache.ts): max-age=0 forces every browser to revalidate, so a reload always reflects a takedown, while a CDN/proxy may keep serving a stored copy for up to 300s after one. That window is the deliberate, ratified cost of making embeds cacheable; deployments needing a hard-instant takedown should front the surface with a cache they can purge, or drop s-maxage. Error responses are never cacheable — no-store is set on every error envelope (app.ts), which matters most for the gate's own 404: a cached one would keep a freshly-published post invisible at the edge for the whole window. Responses set Access-Control-Allow-Origin: * with no credentials (both a route-local post-next() override in routes/public.ts for normal responses, and, since hono's app-wide cors() short-circuits OPTIONS before routing, a matching case in the app-level cors() origin callback for the preflight itself — see app.ts) so third-party origins can embed the content; the rest of the API keeps the configured CORS_ORIGIN. ?include=user redacts PII before it reaches the anonymous internet: birthdate and the free-form profile metadata jsonb are always nulled/emptied on this surface (username/name/avatar/bio still ride along). The shared /v7/* rate limiter (lib/rate-limit.ts) covers this prefix too, but only when RATE_LIMIT_MAX is configured — unset, anonymous internet-public reads are unlimited like every other /v7/* route. Spec: docs/superpowers/specs/2026-07-18-internet-public-entities-design.md.
• Row-Level Security is defense-in-depth. Every table has RLS enabled with a deny-all backstop. The 0008 anon public-read policies were revoked (migration 0064, alongside the auth wall) and anon's SELECT grants pulled with them — anon now has no read access at all. The only remaining read policies are authenticated self-access reads (a signed-in user sees only their own private rows, via SECURITY DEFINER helpers in a non-exposed private schema). There are no client write policies — all writes are server-only — and profiles is intentionally not exposed (RLS can't mask the email / secure_metadata columns). So even if an anon/authed key ever reached the DB directly, the blast radius is bounded (anon gets nothing; an authed key gets only its own rows).
• Multi-tenant isolation by project_id. :projectId is validated (UUID + existence) in middleware and every query is scoped to it; tenants can't read across each other.
• DB resolution fails closed. The per-project DB resolver seam (@agora/core/db) propagates resolver errors — there is no "resolver failed → shared database" fallback, so a misconfigured multi-DB deployment can never silently serve one project's request from another's database. Single-DATABASE_URL deployments are unaffected (no resolver is ever registered; every request uses the one shared handle).
• Authentication. Identity is backed by Supabase Auth (passwords never touch Agora code — they go straight to Supabase; never logged or stored). Agora mints its own HS256 access JWTs (short-lived, ~30 min) plus rotating refresh tokens with reuse-detection (a replayed token revokes the whole family), a 30-second grace window for racing tabs, SHA-256-hashed storage, and a cron that purges expired tokens. External identity (verify-external-user) uses RS256 with per-project public keys and pinned audience + issuer. Native-auth email links fail closed: the confirm/reset/resend paths require AUTH_EMAIL_LINK_ALLOWED_ORIGINS (there's no way to validate a client-supplied emailRedirectTo without it) — unset, they return 503 auth/email-not-configured rather than email a link built from an unvalidated origin; a supplied emailRedirectTo is checked against that allowlist (open-redirect guard, else 400 auth/email-redirect-not-allowed). Supabase-backed auth brokers its own emails and is unaffected.
• Authorization tiers. A hierarchy operator ⊇ owner ⊇ admin ⊇ steward ⊇ member. The deployment platform-operator (env allowlist, cross-tenant) plus DB-granted per-project owner/admin/steward (project_roles) are stamped into the JWT (operator/powner/padmin/steward claims) and read back per request — no extra DB hit. Within-project powers (moderation, reports, suspensions, project config, private-space access) accept owner/admin; deployment powers (running config, DB size, server resources) stay operator-only. Role grants take effect on the user's next token refresh (see the revocation-latency limitation below).
• Settings-read-only principals (OPERATOR_RO_EMAILS): a shared demo/operator login can hold the full operator view yet is server-blocked (assertSettingsWritable, after the project-admin gate) from persisting any of the five settings-save endpoints. Per-identity and server-enforced — independent of, and stricter than, the client-side VITE_SETTINGS_READ_ONLY display flag. Additive; no existing gate is relaxed.
• Internal endpoints & webhooks (cron, moderation apply, webhook signatures) are gated by secrets compared in constant time (crypto.timingSafeEqual); webhooks are HMAC-SHA256 signed with a timestamp, in both directions.
• Injection-resistant data access. All SQL goes through Drizzle's parameterized sql template — including the raw RPC/search/rollup queries; no user input is concatenated into SQL. Email-enumeration is avoided on auth flows (uniform 200s), and the link-preview fetch is SSRF-guarded (scheme allowlist, private-IP/loopback/metadata blocking, timeout, response-size cap).
• Secrets don't leak. The operator config endpoint reports secrets as booleans and strips credentials from DATABASE_URL; request logging records method/path/status/duration only — no bodies, tokens, or headers.

Honest disclosure of where the implementation is thinner than the model, roughly by priority. These are the areas we're actively looking into; contributions welcome.

Security is a practice, not a checkbox. If something here is wrong, unclear, or out of date, please tell us — privately for anything exploitable.