feat: add POST /admin/flush-auth-settings endpoint with step-up auth

Admin-only endpoint to flush cached auth settings for the current tenant.
Requires administrator role + password_or_mfa access level (step-up auth).
Clears both svcCache and graphileCache entries so the next request
re-queries auth settings from the tenant DB.

Author: pyramation

graphql/server/src/middleware/flush.ts

@@ -23,6 +23,58 @@ export const flush = async (
   return next();
 };
 
+/**
+ * Admin-only endpoint to flush auth settings from the svcCache.
+ *
+ * Requires:
+ *  - Admin role (role === 'administrator')
+ *  - Step-up authentication (access_level === 'password_or_mfa')
+ *
+ * Clears both svcCache and graphileCache entries for the current tenant
+ * so the next request re-queries auth settings from the tenant DB.
+ */
+export const flushAuthSettingsCache = async (
+  req: Request,
+  res: Response,
+): Promise<void> => {
+  const token = req.token;
+
+  // Require authentication
+  if (!token?.role) {
+    res.status(401).json({ error: 'Authentication required' });
+    return;
+  }
+
+  // Require admin role (database-level superuser, not org-level)
+  if (token.role !== 'administrator') {
+    log.warn(`[flush-auth-settings] Denied: role=${token.role}, expected administrator`);
+    res.status(403).json({ error: 'Administrator role required' });
+    return;
+  }
+
+  // Require step-up authentication
+  if (token.access_level !== 'password_or_mfa') {
+    log.warn(`[flush-auth-settings] Denied: access_level=${token.access_level}, expected password_or_mfa`);
+    res.status(403).json({
+      error: 'Step-up authentication required (access_level must be password_or_mfa)',
+    });
+    return;
+  }
+
+  const svcKey = req.svc_key;
+  if (!svcKey) {
+    log.warn('[flush-auth-settings] No svc_key on request, nothing to flush');
+    res.status(400).json({ error: 'Could not determine tenant cache key' });
+    return;
+  }
+
+  graphileCache.delete(svcKey);
+  svcCache.delete(svcKey);
+  log.info(`[flush-auth-settings] Flushed cache for key=${svcKey} (requested by user_id=${token.user_id})`);
+
+  res.status(200).json({ flushed: true, cacheKey: svcKey });
+};
+
 export const flushService = async (
   opts: ConstructiveOptions,
   databaseId: string

graphql/server/src/server.ts

@@ -26,7 +26,7 @@ import { createAuthenticateMiddleware } from './middleware/auth';
 import { cors } from './middleware/cors';
 import { errorHandler, notFoundHandler } from './middleware/error-handler';
 import { favicon } from './middleware/favicon';
-import { flush, flushService } from './middleware/flush';
+import { flush, flushAuthSettingsCache, flushService } from './middleware/flush';
 import { graphile } from './middleware/graphile';
 import { multipartBridge } from './middleware/multipart-bridge';
 import { createDebugDatabaseMiddleware } from './middleware/observability/debug-db';
@@ -179,6 +179,9 @@ class Server {
 
     app.use(createCaptchaMiddleware(effectiveOpts));
 
+    // Admin: flush auth settings cache (requires administrator + step-up auth)
+    app.post('/admin/flush-auth-settings', flushAuthSettingsCache);
+
     // Cookie lifecycle: set/clear session cookies on auth mutations (when enabled)
     app.use(createCookieMiddleware());