@biffo/cli 0.244.9 → 0.244.11

package/_skeletons/sibling-template/README.md

@@ -34,9 +34,10 @@ anywhere in `services/api/`, on purpose.
 
 ```
 apps/frontend/            # Next.js 15 static export. `/` is the SSO demo ("<name> - Hello <username>",
-                           #   proving the shared-session SSO works); src/lib/auth-gate.tsx + the
-                           #   src/app/example/ routes show the public-default / opt-in-auth pattern
-                           #   ("Your app goes here" below). src/lib/auth.ts reads the shared session.
+                           #   proving the shared-session SSO works end to end, gate included);
+                           #   src/lib/auth-gate.tsx is the reusable wrapper for any OTHER page that
+                           #   needs the same gate ("Your app goes here" below). src/lib/auth.ts reads
+                           #   the shared session.
 services/api/              # FastAPI + Mangum backend. Verifies the core project's Cognito JWT itself
                            #   (defense in depth — API Gateway's own JWT authorizer is the first layer).
                            #   core_client.py is the ONLY sanctioned way to reach core-owned data.
@@ -81,12 +82,10 @@ else depends on it.
 This is a Next.js **App Router** app with `output: 'export'` (a static site).
 A route is just a folder with a `page.tsx` under `apps/frontend/src/app/`:
 
-| File                            | URL served                          |
-| ------------------------------- | ----------------------------------- |
-| `src/app/page.tsx`              | `/` (the demo — replace or keep)    |
-| `src/app/pricing/page.tsx`      | `/pricing/`                         |
-| `src/app/example/page.tsx`      | `/example/` (public example, below) |
-| `src/app/example/members/page.tsx` | `/example/members/` (gated example) |
+| File                        | URL served                       |
+| --------------------------- | --------------------------------- |
+| `src/app/page.tsx`          | `/` (the demo — replace or keep) |
+| `src/app/pricing/page.tsx`  | `/pricing/`                       |
 
 **The `basePath` / `PATH_PREFIX` wiring is automatic — don't hand-write it.**
 The core project's CloudFront routes `baseurl.com/<name>/*` to this sibling and
@@ -116,8 +115,7 @@ browser never holds a core credential.
 
 The go-live state for most products is a **public** app. That is the easy path
 here: any `page.tsx` you add is served **unauthenticated** the moment it
-deploys — no auth code, no bounce. `src/app/example/page.tsx` is a one-screen
-demonstration of exactly that; copy it or delete it.
+deploys — no auth code, no bounce, nothing to opt out of.
 
 When a page _does_ need a signed-in user, opt in with the `<AuthGate>` helper
 (`src/lib/auth-gate.tsx`) — one wrapper, and only that page becomes private:
@@ -142,15 +140,18 @@ export default function Dashboard() {
 A signed-out visitor is redirected to the core portal's login and returned to
 that exact route afterwards; a signed-in visitor sees the content. `AuthGate`
 builds on `getCurrentSession`/`auth.ts` and never signs anyone in itself
-(ADR-0007). `src/app/example/members/page.tsx` is the runnable version of the
-snippet above. Wrap only what must be private — never gate the whole app.
+(ADR-0007) — it is the same round-trip `/` already runs, packaged as a
+one-line wrapper for any page besides `/`. Wrap only what must be private —
+never gate the whole app. There is no separate demo route for this: `/`
+already proves the mechanism works end to end, and the snippet above is the
+runnable form.
 
 ### The path a founder actually walks
 
 1. Run locally (`pnpm dev`, below) and open `/` — watch the SSO demo work.
 2. Replace `src/app/page.tsx` with your own public home page (or add
    `src/app/<something>/page.tsx`). It's public by default — that's your
-   go-live state. Delete the `example/` routes once you've read them.
+   go-live state.
 3. For any area that needs a login, wrap its `page.tsx` in `<AuthGate>`.
 4. Push to `main`; `deploy.yml` builds the static export with the right
    `NEXT_PUBLIC_BASE_PATH` and syncs it to S3 behind the core CloudFront —

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.9",
+  "version": "0.244.11",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",

package/_skeletons/sibling-template/apps/frontend/src/app/example/members/page.tsx

@@ -1,31 +0,0 @@
-'use client'
-
-import { AuthGate } from '@/lib/auth-gate'
-
-// The SAME page, made private by a single wrapper. Opting into auth is one
-// deliberate line — <AuthGate> — not the default. A signed-out visitor is
-// bounced to the core portal's login (ADR-0007) and returned here afterwards;
-// a signed-in visitor sees the content below.
-//
-// The render-prop form hands you the session, whose ID token you pass to THIS
-// sibling's own backend via createApiClient (never the core API directly,
-// ADR-0002). This example doesn't call the backend, but shows where the token
-// comes from.
-export default function ExampleMembersPage() {
-  return (
-    <AuthGate>
-      {(session) => (
-        <main className="center-screen">
-          <div>
-            <h1>Members only</h1>
-            <p>You&apos;re signed in — this rendered because a valid session exists.</p>
-            <p>
-              Your ID token (for calls to this sibling&apos;s backend) is{' '}
-              {session.getIdToken().getJwtToken().slice(0, 8)}…
-            </p>
-          </div>
-        </main>
-      )}
-    </AuthGate>
-  )
-}

package/_skeletons/sibling-template/apps/frontend/src/app/example/page.tsx

@@ -1,24 +0,0 @@
-import Link from 'next/link'
-
-// A minimal PUBLIC page — the go-live default.
-//
-// There is no auth code here, and that is the whole point: anything you drop
-// under src/app/ is served unauthenticated the moment it deploys. Delete this
-// route once you've seen how it works, or copy it as the starting point for
-// your own public content. To make a page private instead, wrap it in
-// <AuthGate> — see ./members/page.tsx.
-export default function ExamplePublicPage() {
-  return (
-    <main className="center-screen">
-      <div>
-        <h1>This page is public</h1>
-        <p>
-          Anyone can see it — no login, no redirect. This is how most of your app ships at go-live.
-        </p>
-        <p>
-          <Link href="/example/members/">See the same pattern, but auth-gated →</Link>
-        </p>
-      </div>
-    </main>
-  )
-}