@duffcloudservices/cms 0.13.1 → 0.13.2

package/src/composables/anonymousSessionGate.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import {
+  readSiteVisitorSessionResponse,
+  siteVisitorFromSessionPayload,
+  useSiteVisitorSession,
+} from './useSiteVisitorSession'
+
+/**
+ * THE A-35 DEFECT CLASS — "any 2xx == authenticated".
+ *
+ * `GET /api/v1/site-auth/session` answers an ANONYMOUS visitor with
+ * `200 { "visitor": null }` (server commit a384d3a15, 2026-07-03, A-35) so a signed-out
+ * page load does not log a red console error. Any gate that reads the STATUS instead of
+ * the PAYLOAD therefore reports "authenticated" for every anonymous visitor, and the
+ * member-gated fetches it guards fire and 401 — once per page view.
+ *
+ * That is not hypothetical: kept's hand-rolled `useVisitorStore().checkAuth()` did exactly
+ * this and produced 346 profile-401s in a single day on kineticenergypt.com, a 1.00 ratio
+ * to session-200s on EVERY day observed (C-619, kept commit 85ba35c).
+ *
+ * The shared composable was already payload-derived — but it OWNS its own fetch, so a site
+ * with an existing store (Pinia, caching, in-flight dedup, its own `apiFetch`) could not
+ * adopt it and re-derived `return true`. These tests pin the payload-level seams that such
+ * a store CAN adopt, so the defect class cannot recur on the next site that grows member
+ * features.
+ *
+ * Every case here is stated as: what the caller may conclude from a given response. The
+ * only response that may ever conclude "authenticated" is one carrying a real visitor.
+ */
+
+function installConsoleSpies() {
+  return {
+    error: vi.spyOn(console, 'error').mockImplementation(() => {}),
+    warn: vi.spyOn(console, 'warn').mockImplementation(() => {}),
+  }
+}
+
+function expectSilent(spies: ReturnType<typeof installConsoleSpies>) {
+  expect(spies.error).not.toHaveBeenCalled()
+  expect(spies.warn).not.toHaveBeenCalled()
+}
+
+/** A minimal `Response` double: what a hand-rolled store's own `fetch` hands back. */
+function jsonResponse(status: number, body: unknown): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    clone: () => jsonResponse(status, body),
+    text: async () => JSON.stringify(body),
+    json: async () => body,
+  } as unknown as Response
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('siteVisitorFromSessionPayload — the payload is the only source of truth', () => {
+  it('the anonymous 200 body {visitor:null} yields no visitor', () => {
+    expect(siteVisitorFromSessionPayload({ visitor: null })).toBeNull()
+  })
+
+  it('a MISSING visitor key yields null, never a truthy undefined', () => {
+    // kept's pre-fix store assigned `data.visitor` raw, so a missing key stored
+    // `undefined` — falsy by luck, and truthy under any `!== null` test written later.
+    expect(siteVisitorFromSessionPayload({})).toBeNull()
+  })
+
+  it('a server claiming authenticated:true with NO visitor still yields null', () => {
+    // Fail closed: the envelope's own boolean is not evidence of a visitor.
+    expect(siteVisitorFromSessionPayload({ authenticated: true, visitor: null })).toBeNull()
+  })
+
+  it('a visitor object with no email is not a visitor', () => {
+    expect(siteVisitorFromSessionPayload({ visitor: { id: 'g-1' } })).toBeNull()
+  })
+
+  it('non-object bodies yield null', () => {
+    expect(siteVisitorFromSessionPayload(null)).toBeNull()
+    expect(siteVisitorFromSessionPayload(undefined)).toBeNull()
+    expect(siteVisitorFromSessionPayload('ok')).toBeNull()
+    expect(siteVisitorFromSessionPayload(true)).toBeNull()
+  })
+
+  it('a real visitor is returned, normalized', () => {
+    const v = siteVisitorFromSessionPayload({
+      visitor: { id: 'g-1', email: 'v@example.com', name: 'Visitor' },
+    })
+    expect(v?.email).toBe('v@example.com')
+    expect(v?.name).toBe('Visitor')
+  })
+
+  it('the contracts-spec {authenticated,user} shape is accepted too', () => {
+    expect(siteVisitorFromSessionPayload({ authenticated: true, user: { email: 'u@example.com' } })?.email).toBe(
+      'u@example.com',
+    )
+    // name defaults to the email rather than inventing one.
+    expect(siteVisitorFromSessionPayload({ user: { email: 'u@example.com' } })?.name).toBe('u@example.com')
+  })
+})
+
+describe('readSiteVisitorSessionResponse — status alone can NEVER conclude authenticated', () => {
+  it('THE REGRESSION PIN: 200 {visitor:null} is NOT authenticated', async () => {
+    const spies = installConsoleSpies()
+
+    const result = await readSiteVisitorSessionResponse(jsonResponse(200, { visitor: null }))
+
+    // A status-only gate (`return response.ok`) passes every other test in this file
+    // but fails this one. That is the whole point.
+    expect(result.authenticated).toBe(false)
+    expect(result.visitor).toBeNull()
+    expect(result.apiUnreachable).toBeFalsy()
+    expectSilent(spies)
+  })
+
+  it('200 with a missing visitor key is NOT authenticated', async () => {
+    const result = await readSiteVisitorSessionResponse(jsonResponse(200, {}))
+    expect(result.authenticated).toBe(false)
+    expect(result.visitor).toBeNull()
+  })
+
+  it('200 with a real visitor IS authenticated', async () => {
+    const result = await readSiteVisitorSessionResponse(
+      jsonResponse(200, { visitor: { id: 'g-1', email: 'v@example.com', name: 'Visitor' } }),
+    )
+    expect(result.authenticated).toBe(true)
+    expect(result.visitor?.email).toBe('v@example.com')
+  })
+
+  it('a legacy 401 is not authenticated, and is silent (the anonymous path on old servers)', async () => {
+    const spies = installConsoleSpies()
+    const result = await readSiteVisitorSessionResponse(jsonResponse(401, { error: 'Not authenticated' }))
+    expect(result.authenticated).toBe(false)
+    expect(result.visitor).toBeNull()
+    expectSilent(spies)
+  })
+
+  it('a 500 is not authenticated — fail closed, never fail open', async () => {
+    const result = await readSiteVisitorSessionResponse(jsonResponse(500, { error: 'boom' }))
+    expect(result.authenticated).toBe(false)
+  })
+
+  it('a non-2xx that somehow carries a visitor is STILL not authenticated', async () => {
+    // Fail closed: a rejected status is a rejection whatever the body says.
+    const result = await readSiteVisitorSessionResponse(
+      jsonResponse(401, { visitor: { email: 'v@example.com', name: 'V' } }),
+    )
+    expect(result.authenticated).toBe(false)
+    expect(result.visitor).toBeNull()
+  })
+
+  it('a missing response (the callers fetch threw) is not authenticated, and silent', async () => {
+    const spies = installConsoleSpies()
+    expect((await readSiteVisitorSessionResponse(null)).authenticated).toBe(false)
+    expect((await readSiteVisitorSessionResponse(undefined)).authenticated).toBe(false)
+    expectSilent(spies)
+  })
+
+  it('a body that will not parse is not authenticated, and silent', async () => {
+    const broken = {
+      ok: true,
+      status: 200,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      clone: () => broken,
+      text: async () => '',
+      json: async () => {
+        throw new Error('connection reset')
+      },
+    } as unknown as Response
+    const spies = installConsoleSpies()
+
+    const result = await readSiteVisitorSessionResponse(broken)
+
+    expect(result.authenticated).toBe(false)
+    expect(result.apiUnreachable).toBeFalsy()
+    expectSilent(spies)
+  })
+})
+
+describe('readSiteVisitorSessionResponse — a misroute is not an anonymous visit (C-298 layer 2)', () => {
+  const SPA_SHELL =
+    '<!DOCTYPE html><html><head><script type="module" src="/assets/index.js"></script></head><body><div id="app"></div></body></html>'
+
+  function htmlResponse(): Response {
+    const build = (): Response =>
+      ({
+        ok: true,
+        status: 200,
+        headers: new Headers({ 'content-type': 'text/html; charset=utf-8' }),
+        clone: () => build(),
+        text: async () => SPA_SHELL,
+        json: async () => JSON.parse(SPA_SHELL),
+      }) as unknown as Response
+    return build()
+  }
+
+  it('200 text/html is signed-out for the UI, apiUnreachable, and LOUD', async () => {
+    const spies = installConsoleSpies()
+
+    const result = await readSiteVisitorSessionResponse(htmlResponse())
+
+    expect(result.authenticated).toBe(false)
+    expect(result.apiUnreachable).toBe(true)
+    expect(spies.error).toHaveBeenCalledTimes(1)
+    const message = String(spies.error.mock.calls[0][0])
+    expect(message).toContain('bodyClass=spa-html')
+  })
+})
+
+describe('useSiteVisitorSession — consumers inherit the payload gate without opting in', () => {
+  it('isAuthenticated stays false across an anonymous 200-null probe', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ visitor: null }) }),
+    )
+
+    const session = useSiteVisitorSession({ fetchOnMount: false })
+    expect(session.isAuthenticated.value).toBe(false)
+    await session.refresh()
+
+    expect(session.isAuthenticated.value).toBe(false)
+    expect(session.visitor.value).toBeNull()
+  })
+
+  it('isAuthenticated flips true only when a visitor is present', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ visitor: { id: 'g-1', email: 'v@example.com', name: 'Visitor' } }),
+      }),
+    )
+
+    const session = useSiteVisitorSession({ fetchOnMount: false })
+    await session.refresh()
+
+    expect(session.isAuthenticated.value).toBe(true)
+    expect(session.visitor.value?.email).toBe('v@example.com')
+  })
+})

package/src/composables/useSiteVisitorSession.ts

@@ -28,7 +28,12 @@
  * The anonymous path — `200 {"visitor":null}`, a legacy `401`, a network error — stays
  * exactly as silent as before.
  */
-import { platformFetch, isPlatformFetchError } from '@duffcloudservices/cms-core'
+import {
+  platformFetch,
+  readPlatformJson,
+  isPlatformFetchError,
+  type PlatformBodyClass,
+} from '@duffcloudservices/cms-core'
 import { ref, computed, onMounted, type Ref, type ComputedRef } from 'vue'
 
 /** A signed-in site visitor. */
@@ -67,11 +72,23 @@ const SIGNED_OUT: SiteVisitorSessionResult = { visitor: null, authenticated: fal
 const apiBase = (value?: string): string => (value ?? '/api/v1').replace(/\/$/u, '')
 
 /**
- * Normalize the various session-response shapes into a `SiteVisitor | null`.
- * Accepts the primary/legacy `{ visitor: {...} | null }` envelope and the
- * contracts-spec `{ authenticated, user: {...} }` shape defensively.
+ * Normalize a parsed `/site-auth/session` BODY into a `SiteVisitor | null`.
+ *
+ * This is the payload-level answer to "is anyone signed in?" — the question the HTTP
+ * status cannot answer, because an anonymous visitor gets `200 { "visitor": null }`
+ * (A-35). Use it when your own code already parsed the body; use
+ * {@link readSiteVisitorSessionResponse} when you are holding a `Response`.
+ *
+ * `null` means signed out. Deliberately fail-closed on every ambiguity:
+ *  - a MISSING `visitor` key yields `null`, never a truthy `undefined` — the trap that
+ *    made kept's `visitor.value = data.visitor` a latent defect (C-619);
+ *  - an envelope claiming `authenticated: true` with no visitor object yields `null`;
+ *  - a visitor object without an email is not a visitor.
+ *
+ * Accepts the primary/legacy `{ visitor: {...} | null }` envelope and the contracts-spec
+ * `{ authenticated, user: {...} }` shape defensively.
  */
-function extractVisitor(data: unknown): SiteVisitor | null {
+export function siteVisitorFromSessionPayload(data: unknown): SiteVisitor | null {
   if (!data || typeof data !== 'object') {
     return null
   }
@@ -94,6 +111,81 @@ function extractVisitor(data: unknown): SiteVisitor | null {
   }
 }
 
+/**
+ * Body classes that mean the request never reached the platform API, as opposed to an
+ * API that answered. `empty` and `json` are NOT here: an empty 200 or a truncated body
+ * is an ordinary failed read, and reporting it as a misroute would cry wolf.
+ */
+const UNREACHABLE_BODY_CLASSES: ReadonlySet<PlatformBodyClass> = new Set<PlatformBodyClass>([
+  'spa-html',
+  'html',
+  'other',
+])
+
+/**
+ * Decide "is a visitor signed in?" from a `/site-auth/session` `Response` you already
+ * fetched yourself.
+ *
+ * THIS IS THE SEAM FOR HAND-ROLLED SESSION STORES. {@link useSiteVisitorSession} owns its
+ * own fetch, which a site with an existing store (Pinia, caching, in-flight dedup, its own
+ * authenticated `apiFetch`) cannot adopt — so it hand-rolls the gate and re-derives the
+ * A-35 defect: `if (response.ok) return true`, which reports EVERY anonymous visitor as
+ * authenticated because anonymous is `200 { "visitor": null }`. Measured cost when that
+ * happened on kept: one member-gated 401 per page view, 346 in a day (C-619).
+ *
+ * Keep your fetch; hand the `Response` here and read the payload-derived answer:
+ *
+ * ```ts
+ * const response = await apiFetch('/api/v1/site-auth/session')
+ * const { visitor: v } = await readSiteVisitorSessionResponse(response)
+ * visitor.value = v
+ * return v !== null            // never `return response.ok`
+ * ```
+ *
+ * Fails CLOSED everywhere: a non-2xx (incl. a legacy `401`), a missing response (your
+ * fetch threw), an unparseable body, or a `null` visitor all resolve to signed-out. The
+ * status can never on its own produce `authenticated: true` — only a real visitor object
+ * in the body can.
+ *
+ * Silent on every anonymous path. LOUD exactly once when the body was not JSON at all
+ * (`apiUnreachable: true`), because "this host does not route `/api/v1/*` to the API" must
+ * not masquerade as "signed out" — that ambiguity is how kept ran with nine dead login
+ * routes for ~2 weeks (C-261 / C-298 layer 2).
+ *
+ * Never throws.
+ */
+export async function readSiteVisitorSessionResponse(
+  response: Response | null | undefined,
+): Promise<SiteVisitorSessionResult> {
+  // The caller's fetch rejected (network / abort / CORS) and passed us nothing.
+  if (!response) {
+    return SIGNED_OUT
+  }
+
+  // Old servers reply 401 to an anonymous probe; new servers reply 200-null. Treat any
+  // non-OK status as signed-out WITHOUT logging — and without reading the body, so a
+  // visitor object smuggled alongside a rejected status can never authenticate.
+  if (!response.ok) {
+    return SIGNED_OUT
+  }
+
+  let data: unknown
+  try {
+    // `silent: true`: we decide what deserves the console below, so an ordinary failed
+    // read stays as quiet as it has always been.
+    data = await readPlatformJson<unknown>(response, { silent: true })
+  } catch (e) {
+    if (isPlatformFetchError(e) && UNREACHABLE_BODY_CLASSES.has(e.bodyClass)) {
+      console.error(e.message)
+      return { visitor: null, authenticated: false, apiUnreachable: true }
+    }
+    return SIGNED_OUT
+  }
+
+  const visitor = siteVisitorFromSessionPayload(data)
+  return { visitor, authenticated: visitor !== null }
+}
+
 /**
  * Fetch the current site-visitor session. Never throws and never logs for the
  * anonymous case: any network error, non-OK status (incl. a legacy `401`), or
@@ -123,21 +215,9 @@ export async function fetchSiteVisitorSession(
     return SIGNED_OUT
   }
 
-  // Old servers reply 401 to an anonymous probe; new servers reply 200-null.
-  // Treat any non-OK status as signed-out WITHOUT logging.
-  if (!response.ok) {
-    return SIGNED_OUT
-  }
-
-  let data: unknown
-  try {
-    data = await response.json()
-  } catch {
-    return SIGNED_OUT
-  }
-
-  const visitor = extractVisitor(data)
-  return { visitor, authenticated: visitor !== null }
+  // ONE implementation of the gate: the composable, this function, and any site that
+  // adopts the seam directly all decide "authenticated" the same way, so they cannot drift.
+  return readSiteVisitorSessionResponse(response)
 }
 
 export interface UseSiteVisitorSessionOptions extends FetchSiteVisitorSessionOptions {