feat(webapp,rbac): REQUIRE_PLUGINS=1 fail-fast for required plugin loads

Adds a deployment-mode opt-in that hardens the plugin loader against
silent degradation. Today, when the RBAC plugin module fails to load —
whether because it's not installed or because a transitive dep is broken —
the loader catches the error and returns the default fallback
implementation. Correct for self-hosters; dangerous in deployments where
the fallback's permissive auth is not an acceptable degraded state.

- internal-packages/rbac/src/index.ts: in LazyController.load()'s catch
  block, after logging, throw an Error when `process.env.REQUIRE_PLUGINS
  === "1"`. The throw is captured into `this._init` (a rejected promise),
  so it surfaces on the first method call on the lazy controller. The
  forceFallback option (used by tests) still wins — it short-circuits
  before this code path, so tests aren't broken if a test runner happens
  to inherit REQUIRE_PLUGINS from its parent env.
- apps/webapp/app/routes/healthcheck.tsx: call `rbac.isUsingPlugin()`
  after the DB ping. For self-hosters (and any deployment with the
  plugin loading cleanly) this is a noop. With REQUIRE_PLUGINS=1 and a
  failed plugin load, the throw surfaces here — healthcheck returns 500
  and the rollout's readiness probe fails, so the new revision is
  rolled back before traffic shifts.

REQUIRE_PLUGINS is intentionally plural and generic — future plugin
contracts (audit logs, SSO) can read the same flag without renaming.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: matt-aitken

.server-changes/require-plugins-fail-fast.md

@@ -0,0 +1,8 @@
+---
+area: webapp
+type: feature
+---
+
+Add `REQUIRE_PLUGINS=1` env var. When set, the RBAC plugin loader throws instead of silently falling back to the default implementation if the plugin module fails to load (missing, broken transitive dep, etc.). The webapp's `/healthcheck` route now resolves the lazy plugin controller so the throw surfaces during readiness probes — a deploy where the plugin didn't load fails the probe and is rolled back.
+
+Self-hosters leave `REQUIRE_PLUGINS` unset and continue to use the fallback when no plugin is installed.

apps/webapp/app/routes/healthcheck.tsx

@@ -1,6 +1,7 @@
 import { prisma } from "~/db.server";
 import type { LoaderFunction } from "@remix-run/node";
 import { env } from "~/env.server";
+import { rbac } from "~/services/rbac.server";
 
 export const loader: LoaderFunction = async ({ request }) => {
   try {
@@ -9,6 +10,13 @@ export const loader: LoaderFunction = async ({ request }) => {
     }
 
     await prisma.$queryRaw`SELECT 1`;
+
+    // Resolve the lazy plugin controller so plugin-load failures surface
+    // during readiness probes. With REQUIRE_PLUGINS=1, a failed plugin
+    // load throws here and the rollout's readiness probe fails. Without
+    // REQUIRE_PLUGINS, the fallback resolves cleanly and this is a noop.
+    await rbac.isUsingPlugin();
+
     return new Response("OK");
   } catch (error: unknown) {
     console.log("healthcheck ❌", { error });

internal-packages/rbac/src/index.ts

@@ -105,6 +105,20 @@ class LazyController implements RoleBaseAccessController {
           "RBAC: no plugin installed (ERR_MODULE_NOT_FOUND); using fallback"
         );
       }
+
+      // Fail-fast for deployments that require plugins to be present. Set
+      // REQUIRE_PLUGINS=1 in environments where the fallback is not an
+      // acceptable degraded state — the throw surfaces on the first method
+      // call on the lazy controller (e.g. via the webapp's /healthcheck
+      // route), so the rollout's readiness probe fails and the deploy is
+      // rolled back. Self-hosters leave REQUIRE_PLUGINS unset and continue
+      // to use the fallback when no plugin is installed.
+      if (process.env.REQUIRE_PLUGINS === "1") {
+        throw new Error(
+          `REQUIRE_PLUGINS=1 but plugin "${moduleName}" did not load: ${message}`
+        );
+      }
+
       return new RoleBaseAccessFallback(prisma).create();
     }
   }