@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/hfs/architecture/supabase.mjs

@@ -1,8 +1,9 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
 import { isServerActionModule } from './server-action.mjs';
-import { callName, chainParts, contextTypesClient, isDatabaseType, isSupabaseCall, isSupabaseValue, moduleNameOf, reportAt, signatureFromSupabase, supabaseClientType, SUPABASE_MODULES, unwrap } from './supabase-ast.mjs';
+import { callName, chainParts, contextTypesClient, isDatabaseType, isSupabaseCall, moduleNameOf, reportAt, signatureFromSupabase, supabaseClientType, SUPABASE_MODULES, unwrap } from './supabase-ast.mjs';
 import { checkBackendJwt } from './supabase-be.mjs';
+import { checkFrontendQueryResults, FE_DB_SLOTS, sameSymbol, symbolOf } from './supabase-results.mjs';
 
 /**
  * L10-L16, the slot-driven Supabase machine. Supabase is one data transport with one owner on each side:
@@ -22,193 +23,74 @@ export const BACKEND_SUPABASE_RULE_IDS = Object.freeze(['BE_SUPABASE_CLIENT_OWNE
 
 const FE_CLIENT_OWNER = 'FE_SUPABASE_CLIENT_OWNER';
 const BE_CLIENT_OWNER = 'BE_SUPABASE_CLIENT_OWNER';
-const FE_RESULT_TYPED = 'FE_DB_RESULT_TYPED';
-const FE_ERROR_HANDLED = 'FE_DB_ERROR_HANDLED';
 const FE_SERVICE_ROLE = 'FE_SERVICE_ROLE_FORBIDDEN';
 const FE_SESSION_TRUST = 'FE_AUTH_SESSION_TRUST';
 const FE_WRITE_SHAPE = 'FE_DB_WRITE_SHAPE';
 const FE_ROUTE_HANDLER = 'FE_ROUTE_HANDLER_FORBIDDEN';
-const FE_DB_SLOTS = new Set(['fe.modules.db', 'fe.package.db', 'fe.modules.db.outcome']);
 const BE_SUPABASE_SLOT = 'be.integrations.supabase';
 const FE_CONFIG_SLOT = 'fe.modules.config';
 const SUPABASE_CALLS = new Set(['from', 'rpc']);
-const QUERY_TERMINALS = new Set(['single', 'maybeSingle', 'returns']);
-const QUERY_WRITES = new Set(['insert', 'update', 'upsert', 'delete']);
-const LIST_BOUNDS = new Set(['gt', 'gte', 'lt', 'lte', 'range']);
 const supabaseSlotEnabled = (input, slotId) => {
   const slot = input.graph.resolver.slot(slotId);
   return Boolean(slot && input.graph.resolver.slotEnabled(slot));
 };
 
-function checkClientOwnership(input, { slots, ruleId }) {
-  const kit = machineKit(input);
-  const { ts } = kit;
-  const violations = [];
-  let imports = 0;
-  let clients = 0;
-  let calls = 0;
-  for (const file of input.graph.files.values()) {
-    const checker = kit.checkerOf(file.sourceFile);
-    const owned = slots.has(file.slot);
-    kit.walk(file.sourceFile, node => {
-      const moduleName = moduleNameOf(ts, node);
-      if (moduleName && SUPABASE_MODULES.has(moduleName)) {
-        imports += 1;
-        if (!owned) reportAt(violations, kit, ruleId, file, node, `${moduleName} is imported by ${file.rel}, whose slot is ${file.slot ?? 'unowned'}; Supabase imports belong only to ${[...slots].join(' or ')}.`, { module: moduleName, slot: file.slot ?? null });
-      }
-      if (ts.isTypeReferenceNode(node) && supabaseClientType(kit, checker, node)) {
-        clients += 1;
-        if (!isDatabaseType(ts, node.typeArguments?.[0])) reportAt(violations, kit, ruleId, file, node, 'SupabaseClient must carry the committed Database type as SupabaseClient<Database>.');
-      }
-      if (!ts.isCallExpression(node)) return true;
-      const binding = kit.importBinding(checker, node.expression);
-      if (binding && SUPABASE_MODULES.has(binding.module) && /^create(?:Client|ServerClient|BrowserClient)$/u.test(binding.name)) {
-        clients += 1;
-        if (!isDatabaseType(ts, node.typeArguments?.[0]) && !contextTypesClient(kit, checker, node)) {
-          reportAt(violations, kit, ruleId, file, node, `${binding.name} creates an untyped Supabase client; create it as ${binding.name}<Database>(...) (or give it the contextual type SupabaseClient<Database>).`);
-        }
-      }
-      if (!isSupabaseCall(kit, checker, node)) return true;
-      const properties = chainParts(ts, node);
-      const method = callName(ts, node);
-      if (!SUPABASE_CALLS.has(method) && !properties.includes('auth') && !properties.includes('storage')) return true;
-      calls += 1;
-      if (!owned) reportAt(violations, kit, ruleId, file, node, `A Supabase ${method ?? 'client'} call is made from ${file.slot ?? 'an unowned path'}; database, auth and storage calls belong only to ${[...slots].join(' or ')}.`, { method, slot: file.slot ?? null });
-      return true;
-    });
-  }
-  return { violations, coverage: { status: 'checked', imports, clients, calls, ownerSlots: [...slots] } };
-}
-
-const symbolOf = (kit, checker, node) => kit.aliased(checker, kit.symbolAt(checker, node)) ?? kit.symbolAt(checker, node);
+const CLIENT_FACTORY = /^create(?:Client|ServerClient|BrowserClient)$/u;
 
-const sameSymbol = (kit, checker, node, symbol) => Boolean(symbol && symbolOf(kit, checker, node) === symbol);
-
-const fromAwaitedSupabase = (kit, checker, node, seen = new Set()) => {
-  const current = unwrap(kit.ts, node);
-  if (!current || seen.has(current)) return false;
-  seen.add(current);
-  if (kit.ts.isCallExpression(current)) return isSupabaseCall(kit, checker, current);
-  if (!kit.ts.isIdentifier(current)) return false;
-  for (const declaration of kit.declarationsOf(checker, current)) {
-    if (kit.ts.isVariableDeclaration(declaration) && declaration.initializer && fromAwaitedSupabase(kit, checker, declaration.initializer, seen)) return true;
-  }
-  return false;
-};
-
-const callIsToOutcome = (kit, checker, graph, call) => {
-  if (!kit.ts.isCallExpression(call)) return false;
-  const expression = call.expression;
-  const name = kit.ts.isIdentifier(expression) ? expression.text : (kit.ts.isPropertyAccessExpression(expression) ? expression.name.text : null);
-  if (name !== 'toOutcome') return false;
-  return kit.declarationsOf(checker, kit.ts.isPropertyAccessExpression(expression) ? expression.name : expression)
-    .some(declaration => {
-      const rel = kit.graphPath(declaration);
-      return rel !== null && FE_DB_SLOTS.has(graph.files.get(rel)?.slot);
-    });
-};
+function inspectSupabaseImport(scope, node) {
+  const { kit, file, slots, ruleId, violations, counters } = scope;
+  const moduleName = moduleNameOf(kit.ts, node);
+  if (!moduleName || !SUPABASE_MODULES.has(moduleName)) return;
+  counters.imports += 1;
+  if (!slots.has(file.slot)) reportAt(violations, kit, ruleId, file, node, `${moduleName} is imported by ${file.rel}, whose slot is ${file.slot ?? 'unowned'}; Supabase imports belong only to ${[...slots].join(' or ')}.`, { module: moduleName, slot: file.slot ?? null });
+}
 
-const parentCall = (ts, node) => {
-  let current = node;
-  while (current.parent && ts.isParenthesizedExpression(current.parent)) current = current.parent;
-  return ts.isCallExpression(current.parent) ? current.parent : null;
-};
+function inspectClientTypeReference(scope, node) {
+  const { kit, checker, file, ruleId, violations, counters } = scope;
+  if (!kit.ts.isTypeReferenceNode(node) || !supabaseClientType(kit, checker, node)) return;
+  counters.clients += 1;
+  if (!isDatabaseType(kit.ts, node.typeArguments?.[0])) reportAt(violations, kit, ruleId, file, node, 'SupabaseClient must carry the committed Database type as SupabaseClient<Database>.');
+}
 
-const handledAwait = (kit, checker, graph, awaitNode) => {
-  const direct = parentCall(kit.ts, awaitNode);
-  if (direct && callIsToOutcome(kit, checker, graph, direct) && direct.arguments.some(argument => argument === awaitNode || argument === awaitNode.parent)) return true;
-  let cursor = awaitNode;
-  while (cursor.parent && kit.ts.isParenthesizedExpression(cursor.parent)) cursor = cursor.parent;
-  const declaration = kit.ts.isVariableDeclaration(cursor.parent) ? cursor.parent : null;
-  if (!declaration) return false;
-  if (kit.ts.isIdentifier(declaration.name)) {
-    const result = symbolOf(kit, checker, declaration.name);
-    let handled = false;
-    kit.walk(fileOf(awaitNode), node => {
-      if (kit.ts.isPropertyAccessExpression(node) && node.name.text === 'error' && sameSymbol(kit, checker, node.expression, result)) handled = true;
-      if (kit.ts.isElementAccessExpression(node) && kit.ts.isStringLiteralLike(node.argumentExpression) && node.argumentExpression.text === 'error' && sameSymbol(kit, checker, node.expression, result)) handled = true;
-      if (kit.ts.isCallExpression(node) && callIsToOutcome(kit, checker, graph, node) && node.arguments.some(argument => sameSymbol(kit, checker, unwrap(kit.ts, argument), result))) handled = true;
-      return !handled;
-    });
-    return handled;
+function inspectClientFactoryCall(scope, node) {
+  const { kit, checker, file, ruleId, violations, counters } = scope;
+  const binding = kit.importBinding(checker, node.expression);
+  if (!binding || !SUPABASE_MODULES.has(binding.module) || !CLIENT_FACTORY.test(binding.name)) return;
+  counters.clients += 1;
+  if (!isDatabaseType(kit.ts, node.typeArguments?.[0]) && !contextTypesClient(kit, checker, node)) {
+    reportAt(violations, kit, ruleId, file, node, `${binding.name} creates an untyped Supabase client; create it as ${binding.name}<Database>(...) (or give it the contextual type SupabaseClient<Database>).`);
   }
-  if (!kit.ts.isObjectBindingPattern(declaration.name)) return false;
-  const errorBinding = declaration.name.elements.find(element => {
-    const property = element.propertyName ?? element.name;
-    return kit.ts.isIdentifier(property) && property.text === 'error';
-  });
-  if (!errorBinding || !kit.ts.isIdentifier(errorBinding.name)) return false;
-  const error = symbolOf(kit, checker, errorBinding.name);
-  let references = 0;
-  kit.walk(fileOf(awaitNode), node => {
-    if (kit.ts.isIdentifier(node) && sameSymbol(kit, checker, node, error)) references += 1;
-    return true;
-  });
-  return references > 1;
-};
+}
 
-const fileOf = node => node.getSourceFile();
+function inspectProviderCall(scope, node) {
+  const { kit, checker, file, slots, ruleId, violations, counters } = scope;
+  const { ts } = kit;
+  if (!isSupabaseCall(kit, checker, node)) return;
+  const properties = chainParts(ts, node);
+  const method = callName(ts, node);
+  if (!SUPABASE_CALLS.has(method) && !properties.includes('auth') && !properties.includes('storage')) return;
+  counters.calls += 1;
+  if (!slots.has(file.slot)) reportAt(violations, kit, ruleId, file, node, `A Supabase ${method ?? 'client'} call is made from ${file.slot ?? 'an unowned path'}; database, auth and storage calls belong only to ${[...slots].join(' or ')}.`, { method, slot: file.slot ?? null });
+}
 
-const dataSymbolFromAwait = (kit, checker, identifier) => {
-  const symbol = symbolOf(kit, checker, identifier);
-  for (const declaration of symbol?.declarations ?? []) {
-    if (!kit.ts.isBindingElement(declaration) || !kit.ts.isObjectBindingPattern(declaration.parent)) continue;
-    const property = declaration.propertyName ?? declaration.name;
-    if (!kit.ts.isIdentifier(property) || property.text !== 'data') continue;
-    const variable = declaration.parent.parent;
-    if (kit.ts.isVariableDeclaration(variable) && variable.initializer && fromAwaitedSupabase(kit, checker, variable.initializer)) return symbol;
-  }
-  return null;
-};
+function inspectOwnershipNode(scope, node) {
+  inspectSupabaseImport(scope, node);
+  inspectClientTypeReference(scope, node);
+  if (!scope.kit.ts.isCallExpression(node)) return;
+  inspectClientFactoryCall(scope, node);
+  inspectProviderCall(scope, node);
+}
 
-function checkFrontendQueryResults(input) {
+function checkClientOwnership(input, { slots, ruleId }) {
   const kit = machineKit(input);
-  const { ts } = kit;
   const violations = [];
-  let awaited = 0;
-  let listReads = 0;
+  const counters = { imports: 0, clients: 0, calls: 0 };
   for (const file of input.graph.files.values()) {
     const checker = kit.checkerOf(file.sourceFile);
-    const seen = new Set();
-    const report = (ruleId, node, message) => {
-      const key = `${ruleId}:${node.pos}:${message}`;
-      if (seen.has(key)) return;
-      seen.add(key);
-      reportAt(violations, kit, ruleId, file, node, message);
-    };
-    kit.walk(file.sourceFile, node => {
-      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && QUERY_TERMINALS.has(node.expression.name.text)
-        && node.typeArguments?.length && isSupabaseValue(kit, checker, node.expression.expression)) {
-        report(FE_RESULT_TYPED, node, `${node.expression.name.text}<T>() supplies a result generic; derive the row type from Database and let the Supabase chain infer it.`);
-      }
-      if ((ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node)) && fromAwaitedSupabase(kit, checker, node.expression)) {
-        report(FE_RESULT_TYPED, node, 'A Supabase query result is cast or non-null asserted; narrow its typed data/error outcome instead.');
-      }
-      if (ts.isAwaitExpression(node) && isSupabaseValue(kit, checker, node.expression)) {
-        const expression = unwrap(ts, node.expression);
-        if (!ts.isCallExpression(expression)) return true;
-        awaited += 1;
-        const methods = chainParts(ts, expression);
-        if (methods.includes('select') && !methods.some(method => QUERY_WRITES.has(method)) && !methods.includes('single') && !methods.includes('maybeSingle')) {
-          listReads += 1;
-          if (!methods.includes('limit') && !methods.some(method => LIST_BOUNDS.has(method))) {
-            report(FE_RESULT_TYPED, node, 'A Supabase list read has no .limit(), .range(), or keyset bound (.gt/.gte/.lt/.lte); bound every multi-row read.');
-          }
-        }
-        if (!handledAwait(kit, checker, input.graph, node)) {
-          report(FE_ERROR_HANDLED, node, 'The awaited Supabase result does not read its error and is not passed whole to toOutcome(result).');
-        }
-      }
-      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken && ts.isArrayLiteralExpression(node.right) && node.right.elements.length === 0) {
-        const left = unwrap(ts, node.left);
-        const swallowed = ts.isIdentifier(left) ? Boolean(dataSymbolFromAwait(kit, checker, left))
-          : ts.isPropertyAccessExpression(left) && left.name.text === 'data' && fromAwaitedSupabase(kit, checker, left.expression);
-        if (swallowed) report(FE_ERROR_HANDLED, node, 'Supabase data is collapsed with ?? []; refused or unavailable is not empty data. Pass the whole result to toOutcome.');
-      }
-      return true;
-    });
+    const scope = { kit, checker, file, slots, ruleId, violations, counters };
+    kit.walk(file.sourceFile, node => inspectOwnershipNode(scope, node));
   }
-  return { violations, coverage: { status: 'checked', awaited, listReads } };
+  return { violations, coverage: { status: 'checked', ...counters, ownerSlots: [...slots] } };
 }
 
 const words = text => String(text).replace(/([a-z0-9])([A-Z])/gu, '$1_$2').toUpperCase();
@@ -226,33 +108,41 @@ const envRead = (ts, node) => {
   return ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
 };
 
+/** Reports a SERVICE_ROLE identifier or string literal: the browser and Next process never hold the service role. */
+function inspectServiceRoleText(ts, node, report) {
+  if (ts.isIdentifier(node) && serviceRoleText(node.text)) report(node, 'A SERVICE_ROLE identifier appears in the front end; the browser and Next process never hold the Supabase service role.', node.text);
+  if (ts.isStringLiteralLike(node) && serviceRoleText(node.text)) report(node, 'A service_role string appears in the front end; the service role belongs behind the back-end guard chain.', node.text);
+}
+
+/** Counts an environment read and reports a credential-shaped or product-specific public variable. */
+function inspectEnvironmentRead(state, file, node, name) {
+  state.reads += 1;
+  if (credentialEnv(name)) state.report(node, `${name} is a credential-shaped environment read in the front end; no *_SECRET, *_PRIVATE, *_TOKEN, *_PASSWORD or service-role value enters fe/.`, name);
+  else if (name.startsWith('NEXT_PUBLIC_') && !CORE_PUBLIC_ENV.has(name) && file.slot !== FE_CONFIG_SLOT) {
+    state.report(node, `${name} is not a core Supabase/site public variable and is read outside ${FE_CONFIG_SLOT}; product public configuration is declared by the one config owner.`, name);
+  }
+}
+
 function checkFrontendSecretNames(input) {
   const kit = machineKit(input);
   const { ts } = kit;
   const violations = [];
-  let reads = 0;
+  const state = { reads: 0, report: null };
   for (const file of input.graph.files.values()) {
     const seen = new Set();
-    const report = (node, message, name) => {
+    state.report = (node, message, name) => {
       const key = `${node.pos}:${name ?? ''}`;
       if (seen.has(key)) return;
       seen.add(key);
       reportAt(violations, kit, FE_SERVICE_ROLE, file, node, message, name ? { name } : {});
     };
     kit.walk(file.sourceFile, node => {
-      if (ts.isIdentifier(node) && serviceRoleText(node.text)) report(node, 'A SERVICE_ROLE identifier appears in the front end; the browser and Next process never hold the Supabase service role.', node.text);
-      if (ts.isStringLiteralLike(node) && serviceRoleText(node.text)) report(node, 'A service_role string appears in the front end; the service role belongs behind the back-end guard chain.', node.text);
+      inspectServiceRoleText(ts, node, state.report);
       const name = envRead(ts, node);
-      if (!name) return true;
-      reads += 1;
-      if (credentialEnv(name)) report(node, `${name} is a credential-shaped environment read in the front end; no *_SECRET, *_PRIVATE, *_TOKEN, *_PASSWORD or service-role value enters fe/.`, name);
-      else if (name.startsWith('NEXT_PUBLIC_') && !CORE_PUBLIC_ENV.has(name) && file.slot !== FE_CONFIG_SLOT) {
-        report(node, `${name} is not a core Supabase/site public variable and is read outside ${FE_CONFIG_SLOT}; product public configuration is declared by the one config owner.`, name);
-      }
-      return true;
+      if (name) inspectEnvironmentRead(state, file, node, name);
     });
   }
-  return { violations, coverage: { status: 'checked', envReads: reads } };
+  return { violations, coverage: { status: 'checked', envReads: state.reads } };
 }
 
 const isClientModule = (ts, sourceFile) => sourceFile.statements.some((statement, index) => index < 4 && ts.isExpressionStatement(statement)
@@ -260,24 +150,25 @@ const isClientModule = (ts, sourceFile) => sourceFile.statements.some((statement
 
 const isDirectiveStatement = (ts, statement) => ts.isExpressionStatement(statement) && ts.isStringLiteralLike(statement.expression);
 
-const exportedValues = (ts, sourceFile) => {
-  const hasExport = node => node.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
-  const out = [];
-  for (const statement of sourceFile.statements) {
-    if (ts.isFunctionDeclaration(statement) && hasExport(statement) && statement.name && statement.body) {
-      out.push({ name: statement.name.text, implementation: statement.body, functionNode: statement });
-    }
-    if (!ts.isVariableStatement(statement) || !hasExport(statement)) continue;
-    for (const declaration of statement.declarationList.declarations) {
-      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
+const hasExportModifier = (ts, node) => node.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
+
+const exportedValuesOf = (ts, statement) => {
+  if (ts.isFunctionDeclaration(statement)) {
+    return hasExportModifier(ts, statement) && statement.name && statement.body
+      ? [{ name: statement.name.text, implementation: statement.body, functionNode: statement }] : [];
+  }
+  if (!ts.isVariableStatement(statement) || !hasExportModifier(ts, statement)) return [];
+  return statement.declarationList.declarations
+    .filter(declaration => ts.isIdentifier(declaration.name) && declaration.initializer)
+    .map(declaration => {
       const functionNode = (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))
         && ts.isBlock(declaration.initializer.body) ? declaration.initializer : null;
-      out.push({ name: declaration.name.text, implementation: declaration.initializer, functionNode });
-    }
-  }
-  return out;
+      return { name: declaration.name.text, implementation: declaration.initializer, functionNode };
+    });
 };
 
+const exportedValues = (ts, sourceFile) => sourceFile.statements.flatMap(statement => exportedValuesOf(ts, statement));
+
 const exportedActions = (ts, sourceFile) => exportedValues(ts, sourceFile).map(value => value.functionNode).filter(Boolean);
 const exportedImplementations = (ts, sourceFile, name) => exportedValues(ts, sourceFile)
   .filter(value => value.name === name).map(value => value.implementation);
@@ -293,8 +184,8 @@ const contains = (kit, root, predicate) => {
 
 const principalCall = (kit, checker, graph, node) => kit.ts.isCallExpression(node) && (() => {
   const expression = node.expression;
-  const name = kit.ts.isIdentifier(expression) ? expression : (kit.ts.isPropertyAccessExpression(expression) ? expression.name : null);
-  if (!name || name.text !== 'getPrincipal') return false;
+  const name = kit.ts.isPropertyAccessExpression(expression) ? expression.name : expression;
+  if (!kit.ts.isIdentifier(name) || name.text !== 'getPrincipal') return false;
   return kit.declarationsOf(checker, name).some(declaration => {
     const rel = kit.graphPath(declaration);
     return rel !== null && FE_DB_SLOTS.has(graph.files.get(rel)?.slot);
@@ -333,82 +224,119 @@ const parameterBindings = (ts, name) => {
   return [];
 };
 
+function inspectServerSessionCalls(kit, file, checker, violations) {
+  const { ts } = kit;
+  if (isClientModule(ts, file.sourceFile)) return;
+  kit.walk(file.sourceFile, node => {
+    if (ts.isCallExpression(node) && callName(ts, node) === 'getSession' && signatureFromSupabase(checker, node)) {
+      reportAt(violations, kit, FE_SESSION_TRUST, file, node, 'auth.getSession() trusts cookie-backed session data in server code; call getPrincipal() (getClaims), and getUser() for sensitive mutations.');
+    }
+    return true;
+  });
+}
+
+function inspectPrincipalProvider(kit, file, checker, violations) {
+  const { ts } = kit;
+  if (!FE_DB_SLOTS.has(file.slot)) return;
+  for (const implementation of exportedImplementations(ts, file.sourceFile, 'getPrincipal')) {
+    const readsClaims = contains(kit, implementation, node => ts.isCallExpression(node) && callName(ts, node) === 'getClaims'
+      && signatureFromSupabase(checker, node));
+    if (!readsClaims) reportAt(violations, kit, FE_SESSION_TRUST, file, implementation,
+      'getPrincipal() must establish the server principal through Supabase auth.getClaims().');
+  }
+}
+
+function inspectActionDirective(kit, file, action, violations) {
+  const { ts } = kit;
+  const first = action.body.statements[0];
+  const functionLevel = first?.expression?.text === 'use server' && isDirectiveStatement(ts, first);
+  if (!isServerActionModule(ts, file.sourceFile) && !functionLevel) {
+    reportAt(violations, kit, FE_WRITE_SHAPE, file, action, 'An exported write function must be a Server Action through a file-level or function-level `use server` directive.');
+  }
+}
+
+function inspectActionPrincipal(input, kit, file, checker, action, authenticatesAnonymous, violations) {
+  const { ts } = kit;
+  // Function directives are the prologue, not work: the principal is the first non-directive statement.
+  const work = action.body.statements.slice(action.body.statements.findIndex(statement => !isDirectiveStatement(ts, statement)) >>> 0);
+  const first = work[0];
+  const principal = first ? firstPrincipal(kit, checker, input.graph, first) : { call: null, symbol: null };
+  if (!principal.call || !principal.symbol) {
+    reportAt(violations, kit, FE_SESSION_TRUST, file, first ?? action, 'A write Server Action must begin with `const principal = await getPrincipal()` from the db owner.');
+  } else if (!authenticatesAnonymous) {
+    const refuses = work.slice(1).some(statement => ts.isIfStatement(statement)
+      && contains(kit, statement.expression, node => ts.isIdentifier(node) && sameSymbol(kit, checker, node, principal.symbol))
+      && typedRefusal(kit, statement.thenStatement));
+    if (!refuses) reportAt(violations, kit, FE_SESSION_TRUST, file, action, 'A write Server Action must refuse an anonymous principal with a typed `refused` Outcome before doing work.');
+  }
+}
+
+function inspectActionInputs(kit, file, action, checker, violations) {
+  const { ts } = kit;
+  for (const parameter of action.parameters.flatMap(item => parameterBindings(ts, item.name))) {
+    const symbol = symbolOf(kit, checker, parameter);
+    const references = [];
+    kit.walk(action.body, node => {
+      if (ts.isIdentifier(node) && sameSymbol(kit, checker, node, symbol)) references.push(node);
+      return true;
+    });
+    references.sort((a, b) => a.getStart() - b.getStart());
+    const firstUse = references[0];
+    if (firstUse && !parseUse(ts, firstUse)) reportAt(violations, kit, FE_WRITE_SHAPE, file, firstUse,
+      `Server Action input ${parameter.text} is used before schema.parse(...) or schema.safeParse(...).`, { parameter: parameter.text });
+  }
+}
+
+function inspectSensitiveAction(kit, file, checker, action, violations) {
+  const { ts } = kit;
+  const sensitive = /(?:^|\/)(?:billing|payment|payout|refund|charge|subscription|password|credential|role|permission|membership)[/.-]/iu.test(file.rel);
+  if (sensitive && !contains(kit, action.body, node => ts.isCallExpression(node) && callName(ts, node) === 'getUser' && signatureFromSupabase(checker, node))) {
+    reportAt(violations, kit, FE_SESSION_TRUST, file, action, 'A money, account-security or role-changing Server Action must call auth.getUser() before the mutation.');
+  }
+}
+
+function inspectWriteAction(input, kit, file, checker, action, authenticatesAnonymous, violations) {
+  inspectActionDirective(kit, file, action, violations);
+  inspectActionPrincipal(input, kit, file, checker, action, authenticatesAnonymous, violations);
+  inspectActionInputs(kit, file, action, checker, violations);
+  inspectSensitiveAction(kit, file, checker, action, violations);
+}
+
+function inspectWriteModule(input, kit, file, checker, state) {
+  const { ts } = kit;
+  if (!FE_DB_SLOTS.has(file.slot) || !path.posix.basename(file.rel).startsWith('write-')) return;
+  const classified = input.graph.resolver.classifyPath(file.rel);
+  const belowSlot = classified.root && file.rel.startsWith(`${classified.root}/`) ? file.rel.slice(classified.root.length + 1) : '';
+  const authenticatesAnonymous = (input.graph.resolver.slot(file.slot)?.anonymousActions ?? []).includes(belowSlot);
+  const declared = exportedActions(ts, file.sourceFile);
+  if (!declared.length) reportAt(state.violations, kit, FE_WRITE_SHAPE, file, file.sourceFile, `${file.rel} is a write module but exports no Server Action function.`);
+  for (const action of declared) {
+    state.actions += 1;
+    inspectWriteAction(input, kit, file, checker, action, authenticatesAnonymous, state.violations);
+  }
+}
+
+function inspectRouteHandler(input, kit, file, state) {
+  if (!file.rel.endsWith('/route.ts')) return;
+  state.routes += 1;
+  const classified = input.graph.resolver.classifyPath(file.rel);
+  const app = classified.bindings?.app;
+  const live = app !== undefined && file.rel === `apps/${app}/src/app/health/live/route.ts`;
+  if (!live && file.slot !== 'fe.route.callback') reportAt(state.violations, kit, FE_ROUTE_HANDLER, file, file.sourceFile,
+    `${file.rel} is a front-end route handler outside health/live and the fe.route.callback slot; webhooks, cron, public APIs and third-party callbacks belong to be features.`);
+}
+
 function checkFrontendAuthAndRoutes(input) {
   const kit = machineKit(input);
-  const { ts } = kit;
-  const violations = [];
-  let actions = 0;
-  let routes = 0;
+  const state = { violations: [], actions: 0, routes: 0 };
   for (const file of input.graph.files.values()) {
     const checker = kit.checkerOf(file.sourceFile);
-    if (!isClientModule(ts, file.sourceFile)) {
-      kit.walk(file.sourceFile, node => {
-        if (ts.isCallExpression(node) && callName(ts, node) === 'getSession' && signatureFromSupabase(checker, node)) {
-          reportAt(violations, kit, FE_SESSION_TRUST, file, node, 'auth.getSession() trusts cookie-backed session data in server code; call getPrincipal() (getClaims), and getUser() for sensitive mutations.');
-        }
-        return true;
-      });
-    }
-    if (FE_DB_SLOTS.has(file.slot)) {
-      for (const implementation of exportedImplementations(ts, file.sourceFile, 'getPrincipal')) {
-        const readsClaims = contains(kit, implementation, node => ts.isCallExpression(node) && callName(ts, node) === 'getClaims'
-          && signatureFromSupabase(checker, node));
-        if (!readsClaims) {
-          reportAt(violations, kit, FE_SESSION_TRUST, file, implementation, 'getPrincipal() must establish the server principal through Supabase auth.getClaims().');
-        }
-      }
-    }
-    if (FE_DB_SLOTS.has(file.slot) && path.posix.basename(file.rel).startsWith('write-')) {
-      const classified = input.graph.resolver.classifyPath(file.rel);
-      const belowSlot = classified.root && file.rel.startsWith(`${classified.root}/`) ? file.rel.slice(classified.root.length + 1) : '';
-      const authenticatesAnonymous = (input.graph.resolver.slot(file.slot)?.anonymousActions ?? []).includes(belowSlot);
-      const declared = exportedActions(ts, file.sourceFile);
-      if (!declared.length) reportAt(violations, kit, FE_WRITE_SHAPE, file, file.sourceFile, `${file.rel} is a write module but exports no Server Action function.`);
-      for (const action of declared) {
-        actions += 1;
-        const functionLevel = action.body.statements[0]?.expression?.text === 'use server' && isDirectiveStatement(ts, action.body.statements[0]);
-        if (!isServerActionModule(ts, file.sourceFile) && !functionLevel) {
-          reportAt(violations, kit, FE_WRITE_SHAPE, file, action, 'An exported write function must be a Server Action through a file-level or function-level `use server` directive.');
-        }
-        // Function directives are the prologue, not work: the principal is the first non-directive statement.
-        const work = action.body.statements.slice(action.body.statements.findIndex(statement => !isDirectiveStatement(ts, statement)) >>> 0);
-        const first = work[0];
-        const principal = first ? firstPrincipal(kit, checker, input.graph, first) : { call: null, symbol: null };
-        if (!principal.call || !principal.symbol) {
-          reportAt(violations, kit, FE_SESSION_TRUST, file, first ?? action, 'A write Server Action must begin with `const principal = await getPrincipal()` from the db owner.');
-        } else if (!authenticatesAnonymous) {
-          const refuses = work.slice(1).some(statement => ts.isIfStatement(statement)
-            && contains(kit, statement.expression, node => ts.isIdentifier(node) && sameSymbol(kit, checker, node, principal.symbol))
-            && typedRefusal(kit, statement.thenStatement));
-          if (!refuses) reportAt(violations, kit, FE_SESSION_TRUST, file, action, 'A write Server Action must refuse an anonymous principal with a typed `refused` Outcome before doing work.');
-        }
-        for (const parameter of action.parameters.flatMap(item => parameterBindings(ts, item.name))) {
-          const symbol = symbolOf(kit, checker, parameter);
-          const references = [];
-          kit.walk(action.body, node => {
-            if (ts.isIdentifier(node) && sameSymbol(kit, checker, node, symbol)) references.push(node);
-            return true;
-          });
-          const firstUse = references.sort((a, b) => a.getStart() - b.getStart())[0];
-          if (firstUse && !parseUse(ts, firstUse)) reportAt(violations, kit, FE_WRITE_SHAPE, file, firstUse, `Server Action input ${parameter.text} is used before schema.parse(...) or schema.safeParse(...).`, { parameter: parameter.text });
-        }
-        const sensitive = /(?:^|\/)(?:billing|payment|payout|refund|charge|subscription|password|credential|role|permission|membership)(?:\/|-|\.)/iu.test(file.rel);
-        if (sensitive && !contains(kit, action.body, node => ts.isCallExpression(node) && callName(ts, node) === 'getUser' && signatureFromSupabase(checker, node))) {
-          reportAt(violations, kit, FE_SESSION_TRUST, file, action, 'A money, account-security or role-changing Server Action must call auth.getUser() before the mutation.');
-        }
-      }
-    }
-    if (file.rel.endsWith('/route.ts')) {
-      routes += 1;
-      const classified = input.graph.resolver.classifyPath(file.rel);
-      const app = classified.bindings?.app;
-      const live = app !== undefined && file.rel === `apps/${app}/src/app/health/live/route.ts`;
-      if (!live && file.slot !== 'fe.route.callback') {
-        reportAt(violations, kit, FE_ROUTE_HANDLER, file, file.sourceFile, `${file.rel} is a front-end route handler outside health/live and the fe.route.callback slot; webhooks, cron, public APIs and third-party callbacks belong to be features.`);
-      }
-    }
+    inspectServerSessionCalls(kit, file, checker, state.violations);
+    inspectPrincipalProvider(kit, file, checker, state.violations);
+    inspectWriteModule(input, kit, file, checker, state);
+    inspectRouteHandler(input, kit, file, state);
   }
-  return { violations, coverage: { status: 'checked', actions, routes } };
+  return { violations: state.violations, coverage: { status: 'checked', actions: state.actions, routes: state.routes } };
 }
 
 export function checkFrontendSupabase(input) {