chore(webapp): trim impersonation flag comments

Author: myftija

apps/webapp/app/env.server.ts

@@ -332,9 +332,7 @@ const EnvironmentSchema = z
       .refine(isValidRegex, "WHITELISTED_EMAILS must be a valid regex.")
       .optional(),
     ADMIN_EMAILS: z.string().refine(isValidRegex, "ADMIN_EMAILS must be a valid regex.").optional(),
-    // When disabled, user impersonation is fully off for this instance:
-    // existing impersonation cookies are ignored, the start endpoints 404,
-    // and the impersonation UI isn't rendered.
+    // Instance-level kill switch for user impersonation.
     IMPERSONATION_ENABLED: BoolEnv.default(true),
     REMIX_APP_PORT: z.string().optional(),
     // Opt-in, dev-only: stream this process's logs over a local telnet/TCP socket on this port.

apps/webapp/app/models/admin.server.ts

@@ -16,12 +16,8 @@ import { env } from "~/env.server";
 
 const pageSize = 20;
 
-/**
- * Guard for everything that starts an impersonation (the model function and
- * the routes that render or serve the flow). With IMPERSONATION_ENABLED off,
- * those surfaces don't exist: 404, not 403, so the instance doesn't advertise
- * the feature. Stopping an impersonation is deliberately never gated.
- */
+// 404, not 403, so a disabled instance doesn't advertise the feature.
+// Stopping an impersonation is deliberately never gated.
 export function requireImpersonationEnabled(): void {
   if (!env.IMPERSONATION_ENABLED) {
     throw new Response("Not Found", { status: 404 });
@@ -347,8 +343,7 @@ export async function startImpersonation(
 
 export async function clearImpersonation(request: Request, path: string) {
   const authUser = await authenticator.isAuthenticated(request);
-  // Raw read: stopping must clear and audit the session even when the gated
-  // reader no longer resolves it (IMPERSONATION_ENABLED off).
+  // Raw read: stops must audit and clear even with IMPERSONATION_ENABLED off.
   const targetId = await getRawImpersonationId(request);
 
   if (targetId && authUser?.userId) {

apps/webapp/app/root.tsx

@@ -118,9 +118,8 @@ export const loader = async ({ request }: LoaderFunctionArgs) => {
   // the `user.isViewingAsUser` the server computes could disagree, and the
   // client-side admin UI would hide itself on a session that is not
   // impersonating.
-  // Flag off: actively terminate any lingering impersonation session (STOP
-  // audit row + cookie cleared + one self-redirect) instead of leaving an
-  // inert cookie that would resurrect if the flag were ever re-enabled.
+  // Flag off: terminate lingering impersonation sessions (audit + clear)
+  // rather than leaving a cookie that would resurrect on a later re-enable.
   if (!env.IMPERSONATION_ENABLED && (await getRawImpersonationId(request))) {
     const url = new URL(request.url);
     throw await clearImpersonation(request, `${url.pathname}${url.search}`);

apps/webapp/app/services/impersonation.server.ts

@@ -37,17 +37,13 @@ export function commitImpersonationSession(session: Session) {
 }
 
 export async function getImpersonationId(request: Request) {
-  // Flag off: any impersonation cookie is inert, however it was obtained.
   if (!env.IMPERSONATION_ENABLED) return undefined;
 
   return getRawImpersonationId(request);
 }
 
-/**
- * The raw cookie value, ignoring IMPERSONATION_ENABLED. Only for terminating
- * or auditing a session the gated reader no longer resolves — never for
- * authorizing anything.
- */
+// Ignores IMPERSONATION_ENABLED — only for terminating or auditing a session
+// the gated reader no longer resolves, never for authorizing anything.
 export async function getRawImpersonationId(request: Request) {
   const session = await getImpersonationSession(request);
 

apps/webapp/test/impersonationDisabled.test.ts

@@ -16,14 +16,11 @@ function suffix() {
   return Math.random().toString(36).slice(2, 10);
 }
 
-// IMPERSONATION_ENABLED=false must make impersonation fully inert: starting
-// one 404s, and an existing cookie resolves to nothing however it was
-// obtained. Stopping stays possible with the flag off — that's how lingering
-// sessions get terminated — and must still clear the cookie.
+// IMPERSONATION_ENABLED=false: starting 404s, cookies resolve to nothing,
+// stopping still works so lingering sessions can be terminated.
 describe("impersonation disabled", () => {
   postgresTest("the flag defaults to enabled", async () => {
-    // Flipping this default would kill impersonation on every existing
-    // deployment that never heard of the flag.
+    // Flipping the default would kill impersonation on every existing deployment.
     expect(env.IMPERSONATION_ENABLED).toBe(true);
   });
 
@@ -50,8 +47,8 @@ describe("impersonation disabled", () => {
       new Request("http://localhost:3030/", { headers: { Cookie: cookie } });
 
     expect(await getImpersonationId(requestWithCookie())).toBe(target.id);
-    // resolvedUserId must match the impersonated id for the state to count as
-    // impersonating — that's what getUserId resolves to while the cookie works.
+    // resolvedUserId must be the impersonated id or the state is false even
+    // with the flag on, making the disabled assertion below vacuous.
     const enabledState = await getImpersonationState(requestWithCookie(), target.id);
     expect(enabledState.isImpersonating).toBe(true);
 
@@ -76,8 +73,7 @@ describe("impersonation disabled", () => {
       const disabledState = await getImpersonationState(requestWithCookie(), target.id);
       expect(disabledState.isImpersonating).toBe(false);
 
-      // The ungated reader still sees the cookie — it's what stop/scrub paths
-      // use to terminate a session the gated reader no longer resolves.
+      // The ungated reader still sees the cookie (stop/scrub paths need it).
       expect(await getRawImpersonationId(requestWithCookie())).toBe(target.id);
 
       // Stopping works with the flag off and clears the cookie.