docs: plan local-only logout visibility

2026-08-22 17:55:58 +02:00
parent 6475ea39f9
commit f79b89b026
1 changed files with 337 additions and 0 deletions
@@ -0,0 +1,337 @@
 # Local-Only Logout Visibility Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Show ThothII's `Log out` control only for standalone installations using local authentication, while keeping it absent from the Aritmolab server and every other non-local mode.
 **Architecture:** Reuse the already validated `GET /auth/config` response as the single runtime authority. `AuthGate` derives `canLogout` from `config.mode === "local"`, passes that explicit capability into `AppShell`, and `AppShell` conditionally renders only the existing button while leaving identity display and logout mechanics unchanged.
 **Tech Stack:** React 18, TypeScript 5.6, Vitest 2, React Testing Library, MSW, Vite 6.
 ## Global Constraints
 - Source baseline is `6475ea3`; the approved design is `docs/superpowers/specs/2026-08-22-local-only-logout-visibility-design.md`.
 - `GET /auth/config` is the sole authority. Do not add platform, hostname, URL, issuer, packaging, or build-time detection.
 - The exact visibility rule is `config.mode === "local"`; `upstream`, `oidc`, `none`, `mock`, an absent config, or an invalid config must never enable the control.
 - Keep the authenticated username or display name visible in every mode.
 - Preserve the existing `POST /auth/logout` route, logout coordinator, authentication-state cleanup, query cleanup, and session/transcript isolation behavior.
 - Do not change backend, Compose, native `tht`, deployment, or packaging files.
 - Do not add dependencies or change the English UI string `Log out`.
 - Use strict TDD: add the focused regression tests, observe the intended RED, implement the minimum change, then run focused and full GREEN gates.
 - Preserve and do not stage the pre-existing changes in `.superpowers/sdd/progress.md`, `brain/index.md`, and `brain/codebase/psd-dwh-transport.md`.
 ---
 ### Task 1: Propagate the local-auth capability and conditionally render logout
 **Files:**
 - Modify: `frontend/src/auth/AuthGate.test.tsx:10-17,63-68`
 - Modify: `frontend/src/shell/AppShell.auth.test.tsx:11-28,45-89,90-153`
 - Modify: `frontend/src/auth/AuthGate.tsx:20-29,79-81`
 - Modify: `frontend/src/shell/AppShell.tsx:39-40,715-722`
 - Modify: `frontend/src/shell/AppShell.new-session.test.tsx:12-15`
 - Modify: `frontend/src/shell/AppShell.session-mgmt.test.tsx:22-26`
 - Modify: `frontend/src/shell/AppShell.session-target.test.tsx:12-15`
 **Interfaces:**
 - Consumes: validated `AuthPublicConfig.mode` from the existing `getAuthConfig()` call in `AuthGate`.
 - Produces:
 ```ts
 interface AppShellProps {
  canLogout: boolean;
 }
 export function AppShell({ canLogout }: AppShellProps): JSX.Element;
 ```
 - `canLogout` is required at every `AppShell` call site. Production passes
  `config?.mode === "local"`; focused non-auth shell tests pass `false`; existing local-auth shell
  tests pass `true`.
 - [ ] **Step 1: Add RED tests for capability propagation and shell visibility**
 In `frontend/src/auth/AuthGate.test.tsx`, replace the `AppShell` mock with a capability-observing
 mock:
 ```tsx
 vi.mock("../shell/AppShell", () => ({
  AppShell: ({ canLogout }: { canLogout: boolean }) => (
    <div data-testid="authenticated-shell" data-can-logout={String(canLogout)}>
      Authenticated shell
      {canLogout && (
        <button type="button" onClick={() => { window.dispatchEvent(new Event("test-logout")); }}>
          Log out
        </button>
      )}
    </div>
  ),
 }));
 ```
 Extend the existing local authenticated-shell test so it proves the positive contract:
 ```tsx
 test("renders the authenticated shell from the safe /me DTO", async () => {
  render(<AuthGate />);
  const shell = await screen.findByTestId("authenticated-shell");
  expect(shell).toHaveAttribute("data-can-logout", "true");
  expect(screen.getByRole("button", { name: "Log out" })).toBeInTheDocument();
  expect(screen.queryByRole("heading", { name: /sign in/i })).not.toBeInTheDocument();
 });
 ```
 Add an upstream regression beside it:
 ```tsx
 test("disables shell logout for trusted upstream authentication", async () => {
  server.use(
    http.get("/api/auth/config", () => HttpResponse.json({
      mode: "upstream", localLogin: false, oidcLogin: false,
    })),
    http.get("/api/me", () => HttpResponse.json({
      issuer: "portal",
      subject: "portal-user",
      displayName: "Portal user",
      roles: ["user"],
      permissions: ["session.use"],
      isAdmin: false,
      csrfToken: null,
      session: null,
    })),
  );
  render(<AuthGate />);
  const shell = await screen.findByTestId("authenticated-shell");
  expect(shell).toHaveAttribute("data-can-logout", "false");
  expect(screen.queryByRole("button", { name: "Log out" })).not.toBeInTheDocument();
 });
 ```
 In `frontend/src/shell/AppShell.auth.test.tsx`, add a `canLogout` argument to the existing helper
 and make the keyed/direct local-auth renders explicit:
 ```tsx
 function renderShell(user: {
  subject: string;
  isAdmin: boolean;
  roles: readonly ("user" | "admin")[];
  permissions: readonly string[];
 }, canLogout = true) {
  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
  setAuthState({
    issuer: "local", ...user, csrfToken: null, session: null,
  });
  return render(
    <QueryClientProvider client={client}>
      <AppShell canLogout={canLogout} />
    </QueryClientProvider>,
  );
 }
 function KeyedAuthenticatedShell() {
  const user = useAuthUser();
  const generation = useAuthGeneration();
  return user
    ? <AppShell key={`${user.issuer}:${user.subject}:${generation}`} canLogout />
    : null;
 }
 ```
 Change the direct render in the stale-logout test to `<AppShell canLogout />`. Then add this
 negative shell test before the existing local logout test:
 ```tsx
 test("hides logout outside local authentication while preserving the identity", async () => {
  let logoutCalls = 0;
  server.use(http.post("/api/auth/logout", () => {
    logoutCalls += 1;
    return new HttpResponse(null, { status: 204 });
  }));
  renderShell({
    subject: "portal-user",
    isAdmin: false,
    roles: ["user"],
    permissions: ["session.use"],
  }, false);
  expect(await screen.findByText("portal-user")).toBeInTheDocument();
  expect(screen.queryByRole("button", { name: "Log out" })).not.toBeInTheDocument();
  expect(logoutCalls).toBe(0);
 });
 ```
 - [ ] **Step 2: Run the focused tests and capture RED**
 Run from `frontend/`:
 ```bash
 npx vitest run src/auth/AuthGate.test.tsx src/shell/AppShell.auth.test.tsx
 ```
 Expected: FAIL. The local `AuthGate` test receives no `canLogout` prop, and the real `AppShell`
 still renders `Log out` when the new negative test passes `false`.
 - [ ] **Step 3: Implement the minimal explicit capability flow**
 In `frontend/src/auth/AuthGate.tsx`, replace `AuthenticatedContent` with:
 ```tsx
 function AuthenticatedContent({
  canLogout,
  onExpired,
 }: {
  canLogout: boolean;
  onExpired: () => void;
 }) {
  const user = useAuthUser();
  const authGeneration = useAuthGeneration();
  useEffect(() => {
    if (!user) onExpired();
  }, [onExpired, user]);
  return user
    ? <AppShell key={`${user.issuer}:${user.subject}:${authGeneration}`} canLogout={canLogout} />
    : null;
 }
 ```
 Replace the authenticated branch with the closed local-only rule:
 ```tsx
 if (status === "authenticated") {
  return (
    <AuthenticatedContent
      canLogout={config?.mode === "local"}
      onExpired={() => setStatus("login")}
    />
  );
 }
 ```
 In `frontend/src/shell/AppShell.tsx`, add the required prop at the component boundary:
 ```tsx
 interface AppShellProps {
  canLogout: boolean;
 }
 export function AppShell({ canLogout }: AppShellProps) {
  const authenticatedUser = useAuthUser();
 ```
 Keep the identity row unchanged and wrap only the existing button:
 ```tsx
 {authenticatedUser && (
  <div className="mt-4 flex items-center justify-between gap-2 border-t border-border/70 pt-3 text-left">
    <span className="min-w-0 truncate text-xs text-muted-foreground" title={authenticatedUser.displayName ?? authenticatedUser.subject}>
      {authenticatedUser.displayName ?? authenticatedUser.subject}
    </span>
    {canLogout && (
      <Button variant="ghost" size="xs" onClick={() => { void signOut().catch(() => undefined); }}>
        Log out
      </Button>
    )}
  </div>
 )}
 ```
 Update the three non-authentication shell test helpers so their intent is explicit and they do
 not render an irrelevant logout control:
 ```tsx
 // frontend/src/shell/AppShell.new-session.test.tsx
 return render(
  <QueryClientProvider client={client}>
    <AppShell canLogout={false} />
  </QueryClientProvider>,
 );
 // frontend/src/shell/AppShell.session-mgmt.test.tsx
 return render(
  <QueryClientProvider client={client}>
    <AppShell canLogout={false} />
  </QueryClientProvider>,
 );
 // frontend/src/shell/AppShell.session-target.test.tsx
 return render(
  <QueryClientProvider client={client}>
    <AppShell canLogout={false} />
  </QueryClientProvider>,
 );
 ```
 Do not alter `signOut()`, `logoutUser()`, `frontend/src/api/auth.ts`, or any backend route.
 - [ ] **Step 4: Run the focused tests and confirm GREEN**
 Run from `frontend/`:
 ```bash
 npx vitest run src/auth/AuthGate.test.tsx src/shell/AppShell.auth.test.tsx
 ```
 Expected: both test files PASS, including the new local-positive and upstream-negative cases.
 - [ ] **Step 5: Prove every `AppShell` caller supplies the capability**
 Run from `frontend/`:
 ```bash
 npx tsc -b
 ```
 Expected: exit code 0 with no TypeScript diagnostics. A missing `canLogout` at any production or
 test call site is a compile error.
 - [ ] **Step 6: Run complete frontend verification**
 Run from `frontend/`:
 ```bash
 npx vitest run
 npm run build
 ```
 Expected: the complete Vitest suite passes; the build completes TypeScript project checking and
 Vite production bundling with exit code 0.
 - [ ] **Step 7: Review scope and commit the implementation**
 Run from the repository root:
 ```bash
 git diff --check
 git diff -- frontend/src/auth/AuthGate.tsx \
  frontend/src/auth/AuthGate.test.tsx \
  frontend/src/shell/AppShell.tsx \
  frontend/src/shell/AppShell.auth.test.tsx \
  frontend/src/shell/AppShell.new-session.test.tsx \
  frontend/src/shell/AppShell.session-mgmt.test.tsx \
  frontend/src/shell/AppShell.session-target.test.tsx
 git status --short
 ```
 Expected: no whitespace errors; the implementation diff contains only capability propagation,
 conditional button rendering, and the corresponding test updates. The pre-existing brain and SDD
 files remain unstaged.
 Commit only the implementation files:
 ```bash
 git add frontend/src/auth/AuthGate.tsx \
  frontend/src/auth/AuthGate.test.tsx \
  frontend/src/shell/AppShell.tsx \
  frontend/src/shell/AppShell.auth.test.tsx \
  frontend/src/shell/AppShell.new-session.test.tsx \
  frontend/src/shell/AppShell.session-mgmt.test.tsx \
  frontend/src/shell/AppShell.session-target.test.tsx
 git commit -m "fix(frontend): hide logout outside local auth"
 ```
 Expected: one commit containing only the seven listed frontend files. Do not stage or commit the
 pre-existing workspace changes.