Capture the SSR request cookie eagerly so nested fetches stay authenticated (#263)

`CwaFetch`'s ofetch `onRequest` called `useRequestHeaders(['cookie'])`,
which threw `[nuxt] instance unavailable` for every nested/batch resource
fetched during SSR.

The reported mechanism — "ofetch runs interceptors asynchronously" — is
wrong. `$fetchRaw`'s body runs synchronously up to its first `await`, and
`callHooks` is invoked before it suspends, so `onRequest` inherits its
caller's context.

The real cause is in our own code. `useRequestHeaders` resolves the Nuxt
instance via `useNuxtApp()`, which throws rather than degrading. Nuxt's
`asyncContext` defaults to false, so unctx keeps that instance in a plain
module variable and clears it at the first suspension, and its
`__restore()` hook only covers code rewritten by `unctx/transform` — a
closed list of `defineNuxtPlugin`, `defineNuxtRouteMiddleware` and
friends. `fetcher.ts` is an untransformed plain class, so every `await`
in it destroys the context for everything downstream: the primary fetch
reached the interceptor synchronously and worked, while everything after
`await result.response` -> `fetchBatch` threw. ofetch's retry path loses
the context too, re-entering `onRequest` after a `setTimeout`.

It hid well: the throw surfaces as a rejected promise, so each nested
resource was quietly marked errored instead of crashing the render. And
`credentials: 'include'` does nothing server-side — no cookie jar in
undici — so that header append is the ONLY thing forwarding auth cookies
during SSR, and authenticated SSR requests silently downgraded to
anonymous. Not a regression despite the "latest deps" framing:
`asyncContext: false` is unchanged and the interceptor has not changed
since dfcf340 (Jan 2025).

Capture the cookie in the constructor instead, where the plugin still has
a live Nuxt context, and close over it. `onRequest` stays synchronous and
needs no context, so nested resources and retries both work.

Safe because exactly one CwaFetch exists per Cwa per plugin invocation —
per SSR request; `new Cwa(` and `new CwaFetch(` each have exactly one
non-spec call site. The cookie must stay in that closure: hoisting it to
module scope would leak one user's auth cookie into another's request.
The constructor already requires Nuxt context for `useRuntimeConfig()`
and `useCookie()`, so this widens nothing, and the only cookie mutations
(sign-in/sign-out) are client-side actions.

Rejected `runWithContext()` in the interceptor: on the server it always
returns a Promise, forcing an async interceptor and changing request
timing. Rejected app-side `experimental.asyncContext: true`: a module
must not require an app-level experimental flag to forward auth cookies.

cwa-fetch.spec.ts moves to the nuxt environment with mockNuxtImport — the
existing `vi.mock('#imports', ...)` was not intercepting at all, which
went unnoticed because no test ever invoked `onRequest`.

Author: silverbackdan

CLAUDE.md

@@ -452,6 +452,26 @@ Reached **71.0%** statement coverage (2026-06-28). See `### Coverage progress` a
 
 ---
 
+## Bug: `[nuxt] instance unavailable` — SSR auth cookies dropped on nested resources ✅ Fixed ([#263](https://github.com/components-web-app/cwa-nuxt-module/issues/263))
+
+Fixed 2026-07-16. `CwaFetch`'s ofetch `onRequest` interceptor called `useRequestHeaders(['cookie'])`, which threw for every nested/batch resource during SSR.
+
+**The reported mechanism ("ofetch runs interceptors asynchronously") is wrong** — `$fetchRaw`'s body runs synchronously up to its first `await`, and `callHooks` is invoked before it suspends, so `onRequest` inherits its *caller's* context.
+
+**Real mechanism:** `useRequestHeaders` → `useRequestEvent` → `useNuxtApp()`, which **throws** (not `tryUseNuxtApp`). Nuxt's `asyncContext` defaults to `false`, so unctx holds the instance in a plain module variable and clears it at the first suspension (`callAsync`: `currentInstance = void 0`). Its `__restore()` hook only applies to code rewritten by `unctx/transform` — a **closed list** (`defineNuxtPlugin`, `defineNuxtRouteMiddleware`, `defineNuxtComponent`, `definePageMeta`). **`fetcher.ts` is an untransformed plain class, so every `await` in it destroys the Nuxt context for everything downstream.** The primary fetch reaches `onRequest` synchronously and works; everything after `await result.response` (`fetcher.ts:214`) → `fetchBatch` threw. ofetch's retry path (`await new Promise(setTimeout)` → re-enter) loses it too.
+
+**Why it hid:** the throw surfaces as a *rejected promise*, so `fetcher.ts:169` caught it and marked each nested resource errored rather than crashing. And `credentials: 'include'` does nothing server-side (no cookie jar in undici) — that header `append` is the **only** SSR cookie forwarding — so authenticated SSR requests silently downgraded to anonymous. Not a regression despite the "latest deps" framing: `asyncContext: false` is unchanged and the interceptor hasn't changed since `dfcf3406` (Jan 2025).
+
+**Fix:** capture the cookie **eagerly in the constructor** (live Nuxt context, via the plugin) and close over it; `onRequest` stays synchronous and context-free.
+
+> **⚠️ Why this is safe, and the one way to make it catastrophic.** Exactly one `CwaFetch` exists per `Cwa` per plugin invocation — i.e. **per SSR request** (`new Cwa(` and `new CwaFetch(` each have exactly one non-spec call site: `plugin.ts:14`, `cwa.ts:71`). The captured cookie **must stay in the constructor closure**. Hoisting it to module scope — as `ResourceTypeFromIri` (`resource-utils.ts:79`) does with its shared singleton, mutated per-request from `cwa.ts:68` — would leak one user's auth cookie into another user's request. The constructor already requires Nuxt context (`useRuntimeConfig()`, `useCookie()`), so eager capture widens nothing, and the only cookie mutations (`signIn`/`signOut`) are client-side, so it cannot go stale mid-render.
+
+**Rejected:** `runWithContext()` in the interceptor (always returns a Promise server-side → forces an async interceptor and changes timing); app-side `experimental.asyncContext: true` (a mitigation that pushes the burden onto every consuming app).
+
+**Testing note:** `cwa-fetch.spec.ts` moved to `@vitest-environment nuxt` + `mockNuxtImport('useRequestHeaders', ...)` — the pre-existing `vi.mock('#imports', ...)` **was not intercepting at all**, which went unnoticed because no test ever invoked `onRequest`. Uses `useProcess()` rather than `import.meta.server` because `import.meta.server` isn't settable in this test env (see the `test.todo` in `process.spec.ts`).
+
+---
+
 ## Bug: dynamic position loses its `component` after an SSR load of a nested page ✅ Fixed ([#261](https://github.com/components-web-app/cwa-nuxt-module/issues/261))
 
 **Reported from:** SRNTE (a nested static page whose parent is a data page using the dynamic page template). Fixed 2026-07-16.

src/runtime/api/fetcher/cwa-fetch.spec.ts

@@ -1,11 +1,16 @@
-// @vitest-environment happy-dom
+// @vitest-environment nuxt
 
-import { describe, expect, test, vi } from 'vitest'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
 import { $fetch } from 'ofetch'
+import { mockNuxtImport } from '@nuxt/test-utils/runtime'
+import * as processComposables from '#cwa/composables/process'
 import CwaFetch from './cwa-fetch'
 
 vi.mock('ofetch')
-vi.mock('#imports', () => ({ useRequestHeaders: vi.fn(() => ({})) }))
+
+// `vi.mock('#imports')` does not intercept here — use mockNuxtImport (see CLAUDE.md)
+const mockUseRequestHeaders = vi.hoisted(() => vi.fn(() => ({}) as Record<string, string | undefined>))
+mockNuxtImport('useRequestHeaders', () => mockUseRequestHeaders)
 
 describe('Create a fetch instances with defaults', () => {
   test('Correct defaults are set on fetch', () => {
@@ -42,3 +47,103 @@ describe('CwaFetch -> getRequestOptions', () => {
     expect(opts.headers['content-type']).toBe(expectedContentType)
   })
 })
+
+/**
+ * Server-side cookie forwarding must not depend on the Nuxt async context being alive when ofetch
+ * runs `onRequest`.
+ *
+ * `useRequestHeaders` -> `useRequestEvent` -> `useNuxtApp()`, which THROWS `[nuxt] instance
+ * unavailable` (it does not use `tryUseNuxtApp`). Nuxt's `asyncContext` defaults to false, so unctx
+ * keeps the instance in a plain module variable and clears it the moment a callback suspends
+ * (`unctx` `callAsync`: `currentInstance = void 0`). unctx's `__restore()` only works in code
+ * rewritten by `unctx/transform`, which Nuxt applies to a closed list (`defineNuxtPlugin`,
+ * `defineNuxtRouteMiddleware`, ...) — `fetcher.ts` is an untransformed plain class, so every `await`
+ * in it destroys the context for everything downstream. The primary resource fetch reaches
+ * `onRequest` synchronously and works; every nested/batch resource after `await result.response`
+ * did not. ofetch's retry path (`await new Promise(setTimeout)` then re-enter) loses it too.
+ *
+ * So the cookie is captured EAGERLY in the constructor, which the plugin runs inside a live Nuxt
+ * context. Safe because exactly one CwaFetch exists per Cwa per plugin invocation — i.e. per SSR
+ * request — so it can never leak across requests. See #263.
+ */
+describe('CwaFetch -> server-side cookie forwarding', () => {
+  // ofetch normalises `ctx.options.headers` to a Headers instance before calling onRequest, so a
+  // real Headers here is faithful to runtime.
+  const createRequestCtx = () => ({
+    request: '/_/routes//',
+    options: { headers: new Headers() },
+  })
+
+  function captureOnRequest() {
+    // @ts-expect-error mocked
+    const createSpy = vi.spyOn($fetch, 'create').mockReturnValue(vi.fn())
+    void new CwaFetch('https://my-api')
+    return createSpy.mock.calls[0][0].onRequest
+  }
+
+  function contextIsLost() {
+    mockUseRequestHeaders.mockImplementation(() => {
+      throw new Error('[nuxt] instance unavailable')
+    })
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('captures the request cookie at construction and still forwards it once the Nuxt context is gone', () => {
+    vi.spyOn(processComposables, 'useProcess').mockReturnValue({ isClient: false, isServer: true })
+    mockUseRequestHeaders.mockReturnValue({ cookie: 'api_component=jwt; cwa_auth=1' })
+
+    const onRequest = captureOnRequest()
+
+    // read eagerly, inside the plugin's live Nuxt context
+    expect(mockUseRequestHeaders).toHaveBeenCalledWith(['cookie'])
+    expect(mockUseRequestHeaders).toHaveBeenCalledTimes(1)
+
+    contextIsLost()
+
+    const ctx = createRequestCtx()
+    expect(() => onRequest(ctx)).not.toThrow()
+    expect(ctx.options.headers.get('cookie')).toBe('api_component=jwt; cwa_auth=1')
+    // never re-read per request — the point of the fix
+    expect(mockUseRequestHeaders).toHaveBeenCalledTimes(1)
+  })
+
+  test('forwards the captured cookie on every request from the same instance, including ofetch retries', () => {
+    vi.spyOn(processComposables, 'useProcess').mockReturnValue({ isClient: false, isServer: true })
+    mockUseRequestHeaders.mockReturnValue({ cookie: 'api_component=jwt' })
+
+    const onRequest = captureOnRequest()
+    contextIsLost()
+
+    // a retry re-enters onRequest across a setTimeout, so it can never have Nuxt context
+    for (const _attempt of [1, 2]) {
+      const ctx = createRequestCtx()
+      onRequest(ctx)
+      expect(ctx.options.headers.get('cookie')).toBe('api_component=jwt')
+    }
+  })
+
+  test('does not read or forward request headers on the client', () => {
+    vi.spyOn(processComposables, 'useProcess').mockReturnValue({ isClient: true, isServer: false })
+
+    const onRequest = captureOnRequest()
+    expect(mockUseRequestHeaders).not.toHaveBeenCalled()
+
+    const ctx = createRequestCtx()
+    onRequest(ctx)
+    // the browser attaches its own cookies via `credentials: 'include'`
+    expect(ctx.options.headers.get('cookie')).toBeNull()
+  })
+
+  test('appends no cookie header when the incoming request has none', () => {
+    vi.spyOn(processComposables, 'useProcess').mockReturnValue({ isClient: false, isServer: true })
+    mockUseRequestHeaders.mockReturnValue({})
+
+    const onRequest = captureOnRequest()
+    const ctx = createRequestCtx()
+    onRequest(ctx)
+    expect(ctx.options.headers.get('cookie')).toBeNull()
+  })
+})

src/runtime/api/fetcher/cwa-fetch.ts

@@ -1,6 +1,7 @@
 import { $fetch } from 'ofetch'
 import type { $Fetch } from 'ofetch'
 import type { RequestHeaders } from 'h3'
+import { useProcess } from '../../composables/process'
 import { useRequestHeaders } from '#imports'
 
 interface RequestOptions {
@@ -13,6 +14,28 @@ export default class CwaFetch {
   public readonly fetch: $Fetch
 
   constructor(baseURL: string) {
+    // Capture the incoming request's cookie NOW, while the plugin still has a live Nuxt context.
+    //
+    // `useRequestHeaders` resolves the Nuxt instance via `useNuxtApp()`, which THROWS `[nuxt]
+    // instance unavailable` rather than degrading. Nuxt's `asyncContext` defaults to false, so unctx
+    // holds that instance in a plain module variable and clears it as soon as a callback suspends —
+    // and its `__restore()` hook only applies to code rewritten by `unctx/transform` (a closed list:
+    // `defineNuxtPlugin`, `defineNuxtRouteMiddleware`, ...). `fetcher.ts` is an untransformed plain
+    // class, so every `await` in it destroys the context for everything downstream. Reading the
+    // cookie inside `onRequest` therefore worked only for the primary fetch (which reaches the
+    // interceptor synchronously) and threw for every nested/batch resource, silently downgrading
+    // authenticated SSR requests to anonymous. ofetch's retry path loses the context too, since it
+    // re-enters `onRequest` after a `setTimeout`.
+    //
+    // SAFETY: exactly one CwaFetch exists per Cwa, per plugin invocation — i.e. per SSR request —
+    // so this cookie can never leak into another user's request. It MUST stay in this closure and
+    // must never be hoisted to module scope or onto shared state. The only cookie mutations are
+    // sign-in/sign-out, which are client-side actions, so it cannot go stale mid-render. This adds
+    // no new constraint: the constructor already requires Nuxt context for `useRuntimeConfig()` and
+    // `useCookie()`. See #263.
+    const { isServer } = useProcess()
+    const requestCookie = isServer ? useRequestHeaders(['cookie']).cookie : undefined
+
     this.fetch = $fetch.create({
       baseURL,
       retryDelay: 200,
@@ -37,10 +60,9 @@ export default class CwaFetch {
           checkRequestForPrefix(ctx.request.url)
         }
 
-        if (import.meta.server) {
-          const { cookie } = useRequestHeaders(['cookie'])
-          cookie && ctx.options.headers.append('cookie', cookie)
-        }
+        // captured at construction — needs no Nuxt context, so this stays synchronous and works
+        // for nested/batch resources and retries alike
+        requestCookie && ctx.options.headers.append('cookie', requestCookie)
       },
     })
   }