@biffo/cli 0.244.10 → 0.245.0

package/_skeletons/sibling-template/apps/frontend/src/lib/api-client.test.ts

@@ -61,3 +61,226 @@ describe('createApiClient error handling', () => {
     )
   })
 })
+
+/**
+ * An expired id token is not an error the user can act on — it is a renewal
+ * this app already knows how to perform, and did not (tabsii-lms#3).
+ *
+ * The observed failure: after ~an hour an authoring session's next action
+ * rendered `{"message":"Unauthorized"}` in red in the page. That body is API
+ * Gateway's, produced by the JWT authorizer before the request ever reached the
+ * app, so `extractErrorMessage` has no `detail` to unwrap and correctly falls
+ * back to the raw text — the message layer was working exactly as designed on an
+ * input it was never given a chance to improve. Meanwhile a usable refresh
+ * token sat in localStorage, and reloading the page renewed silently.
+ *
+ * Every assertion below is on observable behaviour rather than on an exported
+ * constant, so each one fails against the unfixed client for the reason the
+ * reporter saw rather than on a missing import.
+ */
+describe('createApiClient session renewal', () => {
+  const GATEWAY_401 = '{"message":"Unauthorized"}'
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  function ok(body: unknown) {
+    return {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      json: () => Promise.resolve(body),
+      text: () => Promise.resolve(JSON.stringify(body)),
+    }
+  }
+
+  function unauthorized(body = GATEWAY_401) {
+    return {
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+      text: () => Promise.resolve(body),
+    }
+  }
+
+  /**
+   * Answers on the token it is given rather than on call count, so a retry that
+   * re-sends the stale token is a failed assertion rather than a passing one.
+   */
+  function fetchAcceptingOnly(freshToken: string, body: unknown = { items: [] }) {
+    return vi.fn((_url: string, init: RequestInit) => {
+      const headers = (init.headers ?? {}) as Record<string, string>
+      return Promise.resolve(
+        headers['Authorization'] === `Bearer ${freshToken}` ? ok(body) : unauthorized(),
+      )
+    })
+  }
+
+  it('renews the session and retries once, so the call succeeds', async () => {
+    const fetchMock = fetchAcceptingOnly('fresh', { items: ['course'] })
+    vi.stubGlobal('fetch', fetchMock)
+    const refresh = vi.fn(() => Promise.resolve<string | null>('fresh'))
+
+    const api = createApiClient(() => 'expired', refresh)
+
+    await expect(api.get('/api/v1/courses')).resolves.toEqual({ items: ['course'] })
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('retries with the refreshed token, never the one that was rejected', async () => {
+    const fetchMock = fetchAcceptingOnly('fresh')
+    vi.stubGlobal('fetch', fetchMock)
+
+    // The shape every caller actually uses: `() => token` closes over React
+    // state, so it still returns the expired token after a renewal. A retry
+    // that re-reads it would send the same rejected credential.
+    const api = createApiClient(
+      () => 'expired',
+      () => Promise.resolve('fresh'),
+    )
+    await api.get('/api/v1/courses')
+
+    const sent = fetchMock.mock.calls.map(
+      ([, init]) => ((init.headers ?? {}) as Record<string, string>)['Authorization'],
+    )
+    expect(sent).toEqual(['Bearer expired', 'Bearer fresh'])
+  })
+
+  it('renews once for concurrent 401s rather than once per caller', async () => {
+    vi.stubGlobal('fetch', fetchAcceptingOnly('fresh'))
+    let resolveRefresh: (token: string) => void = () => {}
+    const refresh = vi.fn(
+      () =>
+        new Promise<string | null>((resolve) => {
+          resolveRefresh = resolve
+        }),
+    )
+
+    const api = createApiClient(() => 'expired', refresh)
+    const inFlight = Promise.all([
+      api.get('/api/v1/courses'),
+      api.get('/api/v1/modules'),
+      api.get('/api/v1/learners'),
+    ])
+    // Let all three reach their 401 before the single refresh settles.
+    await Promise.resolve()
+    resolveRefresh('fresh')
+    await inFlight
+
+    expect(refresh).toHaveBeenCalledTimes(1)
+  })
+
+  it('surfaces an actionable sentence, not API Gateway body, when renewal fails', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(unauthorized()))
+
+    const api = createApiClient(
+      () => 'expired',
+      () => Promise.resolve(null),
+    )
+    const error = await api.get('/api/v1/courses').then(
+      () => {
+        throw new Error('expected the request to reject')
+      },
+      (e: unknown) => e as ApiError,
+    )
+
+    expect(error).toBeInstanceOf(ApiError)
+    expect(error.status).toBe(401)
+    expect(error.message).not.toContain('Unauthorized"')
+    expect(error.message).toBe(
+      'Your session has expired. Reload the page to sign in again, then retry that action.',
+    )
+  })
+
+  it('does not retry in a loop when the renewed token is also rejected', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(unauthorized())
+    vi.stubGlobal('fetch', fetchMock)
+
+    const api = createApiClient(
+      () => 'expired',
+      () => Promise.resolve('also-stale'),
+    )
+
+    await expect(api.get('/api/v1/courses')).rejects.toThrow(/session has expired/i)
+    // The first attempt and exactly one retry. A revoked session must not spin.
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('treats a renewal that hands back the same token as no renewal at all', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(unauthorized())
+    vi.stubGlobal('fetch', fetchMock)
+
+    const api = createApiClient(
+      () => 'expired',
+      () => Promise.resolve('expired'),
+    )
+
+    await expect(api.get('/api/v1/courses')).rejects.toThrow(/session has expired/i)
+    // Re-sending a credential the gateway just rejected cannot succeed, so the
+    // retry is skipped rather than spent.
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports the expiry sentence when the renewal itself throws', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(unauthorized()))
+
+    const api = createApiClient(
+      () => 'expired',
+      () => Promise.reject(new Error('network down')),
+    )
+
+    // The Cognito failure is plumbing the user cannot act on; what they can act
+    // on is signing in again.
+    await expect(api.get('/api/v1/courses')).rejects.toThrow(/session has expired/i)
+  })
+
+  it('keeps a backend 401 that explains itself, rather than overwriting it', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(unauthorized('{"detail":"Token issued for another tenant"}')),
+    )
+
+    const api = createApiClient(
+      () => 'expired',
+      () => Promise.resolve(null),
+    )
+
+    // Same reasoning as extractErrorMessage's: never hide information the
+    // caller already had. A `detail` is the product's own voice already.
+    await expect(api.get('/api/v1/courses')).rejects.toThrow('Token issued for another tenant')
+  })
+
+  it('renews for a mutating verb too, and retries the body', async () => {
+    const fetchMock = fetchAcceptingOnly('fresh', { id: 'c1' })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const api = createApiClient(
+      () => 'expired',
+      () => Promise.resolve('fresh'),
+    )
+    await expect(api.post('/api/v1/courses', { title: 'New' })).resolves.toEqual({ id: 'c1' })
+
+    const [, retry] = fetchMock.mock.calls
+    expect(retry[1].method).toBe('POST')
+    expect(retry[1].body).toBe(JSON.stringify({ title: 'New' }))
+  })
+
+  it('leaves a non-401 failure entirely alone', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      statusText: 'Forbidden',
+      text: () => Promise.resolve('{"detail":"Administrator access required"}'),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    const refresh = vi.fn(() => Promise.resolve<string | null>('fresh'))
+
+    const api = createApiClient(() => 'token', refresh)
+
+    await expect(api.get('/api/v1/users')).rejects.toThrow('Administrator access required')
+    expect(refresh).not.toHaveBeenCalled()
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+})

package/_skeletons/sibling-template/apps/frontend/src/lib/api-client.ts

@@ -38,67 +38,204 @@ export class ApiError extends Error {
  * status text, because a browser rendering `''` shows the user nothing at all.
  */
 export function extractErrorMessage(body: string, statusText: string): string {
+  const detail = parsedDetail(body)
+  if (detail !== null) return detail || statusText
+  return body || statusText
+}
+
+/**
+ * The `detail` a Biffo backend put in its error body, or null if there isn't
+ * one to read.
+ *
+ * Split out of `extractErrorMessage` so the 401 path can ask the same question
+ * without re-implementing the answer — writing this parse a second time in the
+ * same file is precisely the mistake `_extract_detail` records (#1107/#1108),
+ * and a second copy would drift on the next FastAPI change.
+ *
+ * Returns null for "the backend did not speak", and a string — possibly `''` —
+ * for "it did". Callers need that distinction: an empty `detail` still means the
+ * body was the product's own shape, and collapsing the two would make an empty
+ * string indistinguishable from a CloudFront HTML page.
+ */
+function parsedDetail(body: string): string | null {
   let parsed: unknown
   try {
     parsed = JSON.parse(body)
   } catch {
-    return body || statusText
+    return null
   }
   if (typeof parsed === 'object' && parsed !== null && 'detail' in parsed) {
     const { detail } = parsed
-    if (typeof detail === 'string') return detail || statusText
+    // A non-string `detail` also falls back. FastAPI's own 422 makes it a list
+    // of field errors; picking something out of it would move the problem
+    // rather than fix it.
+    if (typeof detail === 'string') return detail
   }
-  return body || statusText
+  return null
+}
+
+/** A response body as text, or `''` if it could not be read. */
+async function bodyOf(res: Response): Promise<string> {
+  return res.text().catch(() => '')
 }
 
 async function handleResponse<T>(res: Response): Promise<T> {
   if (!res.ok) {
-    const body = await res.text().catch(() => '')
-    throw new ApiError(res.status, extractErrorMessage(body, res.statusText))
+    throw new ApiError(res.status, extractErrorMessage(await bodyOf(res), res.statusText))
   }
   return res.json() as Promise<T>
 }
 
-export function createApiClient(getIdToken: () => string | null) {
-  function authHeaders(): HeadersInit {
-    const token = getIdToken()
+/**
+ * What a person is told when their session could not be renewed.
+ *
+ * "Unauthorized" is not an instruction, and it was not even the app's word: a
+ * 401 from the API Gateway JWT authorizer never reaches this app, so its body is
+ * `{"message":"Unauthorized"}` — a wire format with no `detail` for
+ * `extractErrorMessage` to unwrap (tabsii-lms#3). Reloading is named explicitly
+ * because it is what actually works: the mount path renews from the refresh
+ * token in localStorage, and if that token is dead too the reload lands on the
+ * portal's login, which is where the user needs to be either way.
+ */
+const SESSION_EXPIRED_MESSAGE =
+  'Your session has expired. Reload the page to sign in again, then retry that action.'
+
+/**
+ * The message for a 401 that survived a renewal attempt.
+ *
+ * This deliberately keeps `extractErrorMessage`'s first principle — never hide
+ * information the caller already had — rather than stamping the expiry sentence
+ * over every 401. A body carrying a `detail` is the product's own voice and may
+ * say something the expiry sentence would erase ("Token issued for another
+ * tenant"); a body without one is upstream plumbing the user cannot act on, and
+ * that is the only case worth replacing.
+ *
+ * It takes no `statusText`, unlike `extractErrorMessage`: the fallback here is a
+ * full sentence rather than a bare status, so there is nothing left for "401" or
+ * "Unauthorized" to add.
+ */
+function unauthorizedMessage(body: string): string {
+  const detail = parsedDetail(body)
+  return detail !== null && detail !== '' ? detail : SESSION_EXPIRED_MESSAGE
+}
+
+/**
+ * One renewal in flight at a time, across every client this module hands out.
+ *
+ * The Cognito session lives in localStorage, shared by the whole page, so a
+ * refresh is a property of the app rather than of one client instance — and a
+ * page load routinely fans out several calls at once, each of which would
+ * otherwise expire together and fire its own refresh. Cognito would then serve
+ * concurrent renewals for one session, and the losers could persist a token
+ * older than the winner's.
+ *
+ * Module scope rather than per-client is what makes that true even though
+ * `createApiClient` is called in several components independently.
+ */
+let inFlightRenewal: Promise<string | null> | null = null
+let renewalCount = 0
+
+function renewSessionOnce(refreshIdToken: () => Promise<string | null>): Promise<string | null> {
+  if (inFlightRenewal) return inFlightRenewal
+
+  // Compared in the `finally` so a settling renewal can only clear itself,
+  // never a newer one. (Identity on the promise would say the same thing, but
+  // it cannot reference itself before it is assigned.)
+  const id = ++renewalCount
+  inFlightRenewal = (async () => {
+    try {
+      return await refreshIdToken()
+    } catch {
+      // A refresh that throws is indistinguishable, to the user, from one that
+      // returns no session: either way they need to sign in again. Rejecting
+      // here instead would surface a Cognito internal at them.
+      return null
+    } finally {
+      if (renewalCount === id) inFlightRenewal = null
+    }
+  })()
+
+  return inFlightRenewal
+}
+
+/**
+ * Renew through the portal session this sibling already reads (`./auth`).
+ *
+ * Imported dynamically, for two reasons. It keeps `api-client.ts` free of a
+ * load-time dependency on `auth.ts` — which is NOT distributed with this file
+ * (it carries a declared per-repo divergence, biffo-template#1117), so a static
+ * import would couple a synced file's module graph to one that may legitimately
+ * differ. And it keeps the Cognito SDK out of the bundle of any module that only
+ * ever calls the API and never hits a 401.
+ *
+ * `getCurrentSession()` is the renewal: `CognitoUser.getSession()` exchanges the
+ * stored refresh token for a fresh id token when the current one has expired.
+ * That is exactly what a page reload was already doing by accident, and nothing
+ * did on a live call.
+ */
+async function refreshViaPortalSession(): Promise<string | null> {
+  const { getCurrentSession } = await import('./auth')
+  const session = await getCurrentSession()
+  return session?.getIdToken().getJwtToken() ?? null
+}
+
+export function createApiClient(
+  getIdToken: () => string | null,
+  refreshIdToken: () => Promise<string | null> = refreshViaPortalSession,
+) {
+  function authHeaders(token: string | null): HeadersInit {
     return {
       'Content-Type': 'application/json',
       ...(token != null ? { Authorization: `Bearer ${token}` } : {}),
     }
   }
 
+  /**
+   * Send the request; on a 401, renew the session once and send it again.
+   *
+   * The retry is a second statement rather than a recursive call, which is what
+   * makes "once" structural: there is no path back to the top, so a genuinely
+   * revoked session cannot spin however many 401s it produces.
+   *
+   * It also carries the token the renewal returned rather than re-reading
+   * `getIdToken()`. Every caller passes `() => token` closing over React state,
+   * which a renewal outside React has not updated — so re-reading it would
+   * re-send the credential the gateway just rejected and burn the one retry.
+   */
+  async function send<T>(path: string, init: RequestInit): Promise<T> {
+    const sentToken = getIdToken()
+    const res = await fetch(`${API_URL}${path}`, { ...init, headers: authHeaders(sentToken) })
+    if (res.status !== 401) return handleResponse<T>(res)
+
+    const renewed = await renewSessionOnce(refreshIdToken)
+    // An unchanged token means the renewal had nothing newer to give, so the
+    // retry would re-send what was just rejected. Skip it rather than spend it.
+    if (renewed == null || renewed === sentToken) {
+      throw new ApiError(401, unauthorizedMessage(await bodyOf(res)))
+    }
+
+    const retried = await fetch(`${API_URL}${path}`, { ...init, headers: authHeaders(renewed) })
+    if (retried.status === 401) {
+      throw new ApiError(401, unauthorizedMessage(await bodyOf(retried)))
+    }
+    return handleResponse<T>(retried)
+  }
+
   return {
-    get: <T>(path: string): Promise<T> =>
-      fetch(`${API_URL}${path}`, { headers: authHeaders() }).then((r) => handleResponse<T>(r)),
+    get: <T>(path: string): Promise<T> => send<T>(path, {}),
 
     post: <T>(path: string, body: unknown): Promise<T> =>
-      fetch(`${API_URL}${path}`, {
-        method: 'POST',
-        headers: authHeaders(),
-        body: JSON.stringify(body),
-      }).then((r) => handleResponse<T>(r)),
+      send<T>(path, { method: 'POST', body: JSON.stringify(body) }),
 
     put: <T>(path: string, body: unknown): Promise<T> =>
-      fetch(`${API_URL}${path}`, {
-        method: 'PUT',
-        headers: authHeaders(),
-        body: JSON.stringify(body),
-      }).then((r) => handleResponse<T>(r)),
+      send<T>(path, { method: 'PUT', body: JSON.stringify(body) }),
 
     // Folded in from tabsii-crm, which had added it locally. It costs a sibling
     // that never calls it nothing, and leaving it out would mean this file
     // could never be distributed without destroying crm's copy.
     patch: <T>(path: string, body: unknown): Promise<T> =>
-      fetch(`${API_URL}${path}`, {
-        method: 'PATCH',
-        headers: authHeaders(),
-        body: JSON.stringify(body),
-      }).then((r) => handleResponse<T>(r)),
-
-    delete: <T>(path: string): Promise<T> =>
-      fetch(`${API_URL}${path}`, { method: 'DELETE', headers: authHeaders() }).then((r) =>
-        handleResponse<T>(r),
-      ),
+      send<T>(path, { method: 'PATCH', body: JSON.stringify(body) }),
+
+    delete: <T>(path: string): Promise<T> => send<T>(path, { method: 'DELETE' }),
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.244.10",
+  "version": "0.245.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",