Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
@carbon/auth
Authentication, RBAC, session management, Supabase client factories, API key auth, and OAuth 2.0 server. The single auth source of truth for ERP and MES.
Always
- Gate loaders/actions with
requirePermissions(request, { view?, create?, update?, delete? })— never construct Supabase clients directly in routes. requirePermissionsalso returnscaller("session"or"apiKey") andpermissions(the session user's claims, or the key's scopes, per module).serviceContext(ERP) builds the service-function actor from them, so the gate indefineServiceFnchecks the same grants this function read.requirePermissionsrefuses customer and supplier portal sessions with a 403 (API keys are unaffected).{}used to admit them everywhere, and ~50 routes that then read with the service role were reachable by a portal account. PassallowPortalAccounts: trueONLY on a route that acts on the user's own identity (onboarding, company switch, notification links, academy progress) — never on one that returns company data.- Use the factory from
@carbon/auth/client.server:getCarbon(accessToken)for user-scoped (RLS),getCarbonServiceRole()for privileged server ops only. - Every server client built while a request is being handled is bound to it through
requestFetch()(lib/supabase/client.server.ts): all of that request's clients share one limit of 8 calls in flight (a wait for a slot is asupabase slot waitspan), and on a GET/HEAD request their reads (PostgREST GET/HEAD, storage reads) are cancelled when the request is. RPCs, table writes, auth and edge-function calls are never cancelled. Outside a request (jobs, scripts)requestFetch()isundefinedand the client is unbound. A new client factory must passrequestFetch()too, or its calls escape both. - Invalidate Redis permission cache (
redis.del(getPermissionCacheKey(userId))) when changing user permissions — stale cache is the #1 cause of "Access Denied" bugs. - API key
scopes: {}denies all — never treat empty scopes as full access. - Import env constants from
@carbon/auth(re-exports@carbon/env) — notprocess.envdirectly. - Keep
securityMiddlewarein every app's rootmiddleware. It refuses cross-origin POST/PUT/PATCH/DELETE (CSRF), issues the CSP nonce and setsnosniff/X-Frame-Options/Referrer-Policy/HSTS on every response. A route that browsers must reach from another origin goes inCROSS_ORIGIN_ENDPOINTS(lib/security.ts) — webhooks and API-key callers do not need it (servers send neitherSec-Fetch-SitenorOrigin). - A loader that writes on GET calls
rejectCrossSiteNavigation(request)first: theSameSite=Laxsession cookie still rides a top-level link from another site. - Re-issue the session cookie after any
supabase.auth.mfa.challengeAndVerify— it rotates the refresh token, and the old one dies after GoTrue's reuse interval.
Ask First
- Adding new auth providers or modifying the
isAuthProviderEnabledgate. - Changing session cookie config (
SESSION_MAX_AGE,sameSite,secure, cookie name). - Modifying the OAuth 2.0 server routes (
_oauth+/) or MCP token resolution.
Never
- Expose
getCarbonServiceRole()client to code that hasn't verified permissions viarequirePermissionswithbypassRls: true+ employee role. - Return or log raw API keys — only
keyHash(SHA-256) andkeyPrevieware stored; raw key is shown once at creation. - Skip rate limiting on login or API key endpoints.
Validation Commands
pnpm --filter @carbon/auth typecheck
pnpm --filter @carbon/auth test
Key Exports
| Subpath | Provides |
|---|---|
. (index) |
Env re-exports, Supabase client factories, getClaims, cookie/http/result utils, validators |
./auth.server |
requirePermissions, API key auth (30s Redis-cached getApiKeyRecord + bustApiKeyCache, from services/api-key.server.ts), hashApiKey, hashOAuthSecret |
./mfa.server |
TOTP MFA: enrollTotpFactor, verifyTotpChallenge, unenrollTotpFactor, userHasVerifiedTotpFactor (Redis-cached), adminDeleteTotpFactors |
./session.server |
createCookieSessionStorage, requireAuthSession (incl. MFA re-check), destroyAuthSession, session refresh, pending-MFA session + completeMfaChallenge; pushEndpointCookie (signed carbon-push, this browser's Web Push endpoint) — clearAuthCookies deletes that endpoint's pushSubscription rows on every same-site sign-out (a cross-site navigation skips it, per the GET-write rule) |
./company.server |
Company switching, updateCompanySession; the cached plan lookups getCompanyPlanId and isCarbonOwnedCompany (Redis 5 min, a missing plan row cached as "") |
./users.server |
getUserClaims, deactivation flows, cache invalidation |
./passkey.server |
WebAuthn/passkey registration and authentication |
./console-pin.server |
MES console pin-in cookie (signed, bound to company + terminal session user): setConsolePinIn, clearConsolePinIn, resolveConsolePinIn (re-validated against the DB, memoized per read), ConsolePinIn; requirePermissions uses it to derive userId in console mode |
./self-signup.server |
Cloud self-signup blocklist: isSelfSignupBlockedForEmail, SELF_SIGNUP_BLOCKED_MESSAGE (free/disposable email domains; used by ERP login/verify/callback + MES callback) |
./middleware/flash.server |
Flash message middleware |
./middleware/maintenance.server |
maintenanceMiddleware (with MAINTENANCE_MODE on: 503 for every request, 200 for /health, /templates/ passes through); keep it after securityMiddleware in each root middleware. The decision is the pure maintenanceVerdict |
./middleware/security.server |
securityMiddleware (CSRF check + CSP nonce + baseline headers), rejectCrossSiteNavigation, getNonce, setStrictContentSecurityPolicy (report-only for now; entry.server calls it), cspReportAction + CSP_REPORT_PATH. The decisions are pure and tested in lib/security.ts |
SAML SSO lives in @carbon/ee/sso.server (Enterprise-gated), NOT here — auth
only carries AuthSession.ssoProviderId and its preservation across refresh.
The Onshape panel's bearer credential (the cps_ iframe session) lives in
@carbon/ee/onshape/panel-session.server, not here, with its own gate
requireOnshapePanelPermissions. requirePermissions stays cookie and API key
only. ee imports getUserClaims, userHasVerifiedTotpFactor,
getUserScopedClient and hasPermission from auth, never the reverse.
Cross-References
.claude/rules/authentication-system.md— full auth architecture, login flows, claims cachingpackages/env/— env var definitions (getEnv,SUPABASE_URL,SESSION_SECRET, etc.)packages/kv/— Redis client for permission caching and login rate limitingpackages/database/—Databasetype,checkApiKeyRateLimitRPC wrapper