@biffo/cli 0.215.1 → 0.215.2

package/_skeletons/sibling-template/apps/frontend/src/lib/auth-gate.test.tsx

@@ -13,9 +13,9 @@ process.env['NEXT_PUBLIC_SIBLING_PATH_PREFIX'] = '/my-sibling'
 const { getCurrentSession } = await import('@/lib/auth')
 const { AuthGate } = await import('./auth-gate')
 
-function fakeSession(idToken: string) {
+function fakeSession(idToken: string, claims: Record<string, unknown> = {}) {
   return {
-    getIdToken: () => ({ getJwtToken: () => idToken }),
+    getIdToken: () => ({ getJwtToken: () => idToken, decodePayload: () => claims }),
   } as unknown as Awaited<ReturnType<typeof getCurrentSession>>
 }
 
@@ -81,3 +81,146 @@ describe('AuthGate', () => {
     })
   })
 })
+
+/**
+ * A session is not an authorisation.
+ *
+ * `AuthGate` used to answer one question — is anybody signed in? — so every
+ * sibling that needed "signed in AND allowed" hand-rolled the second half.
+ * The core portal's own guard had the identical hole and shipped it: any
+ * authenticated user rendered the whole /admin console (biffo-template#1104).
+ * A sibling that hand-rolls it gets it wrong differently each time; one such
+ * gate very nearly shipped gating completion reports on an *authoring*
+ * permission, which would have refused precisely the oversight roles the
+ * reports exist for.
+ *
+ * So the second question is asked here, once, with one refusal surface.
+ */
+describe('AuthGate authorisation', () => {
+  it('renders children when the session carries one of the required groups', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(
+      fakeSession('a-jwt', { 'cognito:groups': ['editor'] }),
+    )
+
+    render(
+      <AuthGate requireGroups={['admin', 'editor']}>
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('secret content')).toBeInTheDocument()
+    })
+  })
+
+  it('refuses a signed-in user whose token has no groups claim at all', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(fakeSession('a-jwt'))
+
+    render(
+      <AuthGate requireGroups={['admin']}>
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('heading')).toHaveTextContent('No access')
+    })
+    expect(screen.queryByText('secret content')).not.toBeInTheDocument()
+  })
+
+  it('does not bounce a refused user to the portal login — they are already signed in', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(fakeSession('a-jwt'))
+
+    const originalLocation = window.location
+    Object.defineProperty(window, 'location', {
+      value: { href: '', pathname: '/my-sibling/reports/', search: '' },
+      writable: true,
+      configurable: true,
+    })
+
+    render(
+      <AuthGate requireGroups={['admin']}>
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('heading')).toHaveTextContent('No access')
+    })
+    expect(window.location.href).toBe('')
+
+    Object.defineProperty(window, 'location', {
+      value: originalLocation,
+      writable: true,
+      configurable: true,
+    })
+  })
+
+  it('honours an `authorize` predicate for anything groups cannot express', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(
+      fakeSession('a-jwt', { 'custom:permissions': 'enrollments.read' }),
+    )
+
+    render(
+      <AuthGate
+        authorize={(session) =>
+          session.getIdToken().decodePayload()['custom:permissions'] === 'enrollments.read'
+        }
+      >
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('secret content')).toBeInTheDocument()
+    })
+  })
+
+  it('shows the caller-supplied refusal message rather than the generic one', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(fakeSession('a-jwt'))
+
+    render(
+      <AuthGate requireGroups={['admin']} noAccessMessage="You don't have access to reports.">
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText("You don't have access to reports.")).toBeInTheDocument()
+    })
+  })
+
+  it('fails closed when the ID token cannot be decoded', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce({
+      getIdToken: () => {
+        throw new Error('malformed token')
+      },
+    } as unknown as Awaited<ReturnType<typeof getCurrentSession>>)
+
+    render(
+      <AuthGate requireGroups={['admin']}>
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByRole('heading')).toHaveTextContent('No access')
+    })
+  })
+
+  it('still yields on the session alone when nothing is required', async () => {
+    // Public-by-default is the sibling contract; asking only for a session
+    // stays a legitimate, and common, thing to want.
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(fakeSession('a-jwt'))
+
+    render(
+      <AuthGate>
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('secret content')).toBeInTheDocument()
+    })
+  })
+})

package/_skeletons/sibling-template/apps/frontend/src/lib/auth-gate.tsx

@@ -20,6 +20,14 @@ import { getCurrentSession } from '@/lib/auth'
 // to the portal's login with `return_to` pointing back at the exact page they
 // were trying to reach, so they land right back here once signed in.
 //
+// A SESSION IS NOT AN AUTHORISATION. "Somebody is signed in" and "this person
+// is allowed here" are different questions, and this gate answers both: pass
+// `requireGroups` and/or `authorize` for the second one. Ask for it explicitly
+// on any page whose content is not for every signed-in user — a wrapper that
+// only checked for a session is exactly how the core portal shipped its whole
+// /admin console to any authenticated visitor (biffo-template#1104), and how
+// each sibling that hand-rolled the missing half got it wrong differently.
+//
 // The session it yields carries the ID token you pass to THIS sibling's own
 // backend (createApiClient in ./api-client.ts) — never to the core API
 // directly (ADR-0002). The backend re-verifies that JWT itself.
@@ -31,6 +39,35 @@ const SIBLING_PATH_PREFIX = process.env['NEXT_PUBLIC_SIBLING_PATH_PREFIX'] ?? ''
 type GateState =
   { kind: 'checking' } | { kind: 'redirecting' } | { kind: 'authed'; session: CognitoUserSession }
 
+/** The default refusal wording, used when a caller supplies none of its own. */
+const DEFAULT_NO_ACCESS_MESSAGE =
+  "Your account doesn't have access to this page. Contact your administrator if you think that's wrong."
+
+/**
+ * The caller's Cognito groups, or `[]`.
+ *
+ * Fails CLOSED in every degenerate case — no `cognito:groups` claim (the
+ * ordinary state of a user in no groups), a claim that is not an array of
+ * strings, or a token that cannot be decoded at all. An empty list satisfies
+ * no requirement, so a malformed token is refused rather than waved through:
+ * the alternative is a gate whose bypass is "present a token it cannot parse".
+ *
+ * Exported because a sibling's own code often needs the same reading — do not
+ * re-derive it, and do not treat it as authorisation. The core API re-verifies
+ * the JWT and applies the real scoping on every forwarded call (ADR-0002);
+ * this only decides what the UI offers.
+ */
+export function sessionGroups(session: CognitoUserSession): string[] {
+  let claim: unknown
+  try {
+    claim = session.getIdToken().decodePayload()['cognito:groups']
+  } catch {
+    return []
+  }
+  if (!Array.isArray(claim)) return []
+  return claim.filter((group): group is string => typeof group === 'string')
+}
+
 /**
  * The URL to send an unauthenticated visitor back to after they log in.
  *
@@ -44,6 +81,32 @@ function currentReturnTo(): string {
   return `${SIBLING_PATH_PREFIX}/`
 }
 
+/**
+ * Whether a resolved session satisfies the gate's requirements.
+ *
+ * Both conditions must hold, and an `authorize` predicate that throws counts
+ * as a refusal — same reasoning as `sessionGroups`: the failure mode of an
+ * authorisation check must never be "allowed".
+ */
+function permitted(
+  session: CognitoUserSession,
+  requireGroups: string[] | undefined,
+  authorize: ((session: CognitoUserSession) => boolean) | undefined,
+): boolean {
+  if (requireGroups !== undefined && requireGroups.length > 0) {
+    const held = sessionGroups(session)
+    if (!requireGroups.some((group) => held.includes(group))) return false
+  }
+  if (authorize !== undefined) {
+    try {
+      if (!authorize(session)) return false
+    } catch {
+      return false
+    }
+  }
+  return true
+}
+
 type AuthGateProps = {
   /**
    * What to render once a valid session exists. Either plain nodes, or a
@@ -58,6 +121,30 @@ type AuthGateProps = {
    * Defaults to a centered spinner (see globals.css).
    */
   fallback?: ReactNode
+  /**
+   * Cognito groups, ANY of which admits the caller. Omitting this means "any
+   * signed-in user" — a real and common answer, but make it a decision rather
+   * than an oversight.
+   */
+  requireGroups?: string[]
+  /**
+   * Anything group membership cannot express: a permission claim, a role
+   * fetched from this sibling's own backend and closed over, a tenant match.
+   * Applied in addition to `requireGroups`; both must pass.
+   *
+   * Name the predicate after what the PAGE needs, not after the nearest role
+   * you already have a helper for. A completion report is for whoever may read
+   * enrolments — gating it on an authoring permission refuses exactly the
+   * oversight roles it is built for, and that one nearly shipped.
+   */
+  authorize?: (session: CognitoUserSession) => boolean
+  /**
+   * Refusal wording, in this product's voice. Say what the page was, not what
+   * the check was: "You don't have access to training reports."
+   */
+  noAccessMessage?: string
+  /** Replace the whole refusal surface, when a message is not enough. */
+  noAccess?: ReactNode
 }
 
 /**
@@ -74,8 +161,25 @@ type AuthGateProps = {
  *
  * No session → the visitor is redirected to the core portal's login and
  * returned here afterwards. Valid session → `children` render.
+ *
+ * And when the page is not for every signed-in user, say so:
+ *
+ *   <AuthGate requireGroups={['admin']} noAccessMessage="You don't have access to reports.">
+ *     <Reports />
+ *   </AuthGate>
+ *
+ * A refused caller is shown the no-access surface, NOT redirected: they are
+ * already signed in, so sending them to a login page either loops them
+ * straight back or strands them on a form that cannot help.
  */
-export function AuthGate({ children, fallback }: AuthGateProps) {
+export function AuthGate({
+  children,
+  fallback,
+  requireGroups,
+  authorize,
+  noAccessMessage,
+  noAccess,
+}: AuthGateProps) {
   const [state, setState] = useState<GateState>({ kind: 'checking' })
 
   useEffect(() => {
@@ -106,5 +210,21 @@ export function AuthGate({ children, fallback }: AuthGateProps) {
     )
   }
 
+  // Authorisation is decided during render, not stored in `state`, so a caller
+  // may pass a fresh array or arrow literal on every render without either
+  // re-running the session fetch or needing a dependency-array escape hatch.
+  if (!permitted(state.session, requireGroups, authorize)) {
+    return (
+      noAccess ?? (
+        <main className="center-screen">
+          <div>
+            <h1>No access</h1>
+            <p>{noAccessMessage ?? DEFAULT_NO_ACCESS_MESSAGE}</p>
+          </div>
+        </main>
+      )
+    )
+  }
+
   return <>{typeof children === 'function' ? children(state.session) : children}</>
 }

package/package.json

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