@biffo/cli 0.41.15 → 0.41.17

package/_skeletons/sibling-template/.github/workflows/deploy.yml

@@ -190,14 +190,47 @@ jobs:
           # would give "s3://bucket//", whose keys all begin with a literal
           # slash and match no request CloudFront ever forwards.
           DEST="s3://${SITE_BUCKET_NAME}/${PATH_PREFIX:+${PATH_PREFIX}/}"
+          # Three passes, split by mutability and content type — kept in lockstep
+          # with the core portal's deploy-app.yml (issue #275, ported in #351).
+          #
+          # Next's App Router emits its RSC flight payloads as *.txt. Left in the
+          # first pass they get two wrong properties that break every client-side
+          # navigation — and, across the portal↔sibling SSO boundary, strand a
+          # returning user on /index.txt showing raw serialised React (#351):
+          #
+          #   - `aws s3 sync` guesses content type from the extension, so they
+          #     serve as text/plain rather than text/x-component. The router does
+          #     not recognise that as an RSC response and falls back to a hard MPA
+          #     navigation TO THE URL IT WAS FETCHING — landing the browser on the
+          #     .txt payload. Typing the URL works, because a full page load never
+          #     fetches the payload.
+          #
+          #   - they get cached immutable for a year, but they change on every
+          #     deploy exactly like the HTML does.
+          #
+          # Hashed assets under _next/static are genuinely immutable and keep the
+          # long cache; HTML and RSC payloads must not.
           aws s3 sync apps/frontend/out/ "$DEST" \
             --delete \
             --cache-control "public, max-age=31536000, immutable" \
-            --exclude "*.html"
+            --exclude "*.html" \
+            --exclude "*.txt"
+          # `--include` only re-includes from an excluded set; on its own it is a
+          # no-op, since everything is included by default. Without the explicit
+          # `--exclude "*"` this pass would upload the .txt payloads too — as
+          # text/plain — and the pass below, being a sync, would then skip them
+          # as unchanged and the wrong content type would survive.
           aws s3 sync apps/frontend/out/ "$DEST" \
             --delete \
             --cache-control "no-cache" \
+            --exclude "*" \
             --include "*.html"
+          aws s3 sync apps/frontend/out/ "$DEST" \
+            --delete \
+            --cache-control "no-cache" \
+            --content-type "text/x-component" \
+            --exclude "*" \
+            --include "*.txt"
       - name: Invalidate the core project's CloudFront path
         if: vars.PARENT_CLOUDFRONT_DISTRIBUTION_ID != ''
         env:

package/_skeletons/sibling-template/README.md

@@ -33,9 +33,10 @@ anywhere in `services/api/`, on purpose.
 ## What's here
 
 ```
-apps/frontend/            # Next.js 15 static export — the ONLY page is "<name> - Hello <username>",
-                           #   proving the shared-session SSO works. Copy the portal's own
-                           #   src/lib/auth.ts pattern here almost verbatim (see that file's comments).
+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.
 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.
@@ -57,6 +58,119 @@ biffo.sibling.json          # This sibling's name, its paired core project's nam
                            #   without also updating the core project's siblings.auto.tfvars.json.
 ```
 
+## Your app goes here — from the SSO demo to a public go-live
+
+This skeleton is a **blank canvas**. Everything below is additive: the app
+ships with one demo page and a thin auth helper, and your job is to build on
+top, not to unpick anything.
+
+### What the `/` demo is (and that it's replaceable)
+
+`apps/frontend/src/app/page.tsx` is an **SSO demonstration**, not the app you
+ship. It proves the shared-Cognito round-trip (ADR-0007) works end to end: a
+signed-out visitor is bounced to the core portal's login and returned here; a
+signed-in visitor's session ID token is sent to **this sibling's own backend**
+(`/api/v1/whoami`), which re-verifies the JWT and echoes the username back.
+
+Keep it as a working reference, or replace its contents with your own home
+page once you've seen it work — it's your route to do with as you like. Nothing
+else depends on it.
+
+### Where your content goes, and how routing works
+
+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) |
+
+**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
+forwards the full URI with no prefix stripping, so the static export's own asset
+and link URLs must already carry `/<name>`. `next.config.ts` reads
+`NEXT_PUBLIC_BASE_PATH` (set by `deploy.yml` from your `path_prefix`) and Next
+prepends it to every asset and every `next/link` href for you. Two rules follow:
+
+- **Always link with `next/link`** (`<Link href="/pricing/">`), never a bare
+  `<a href>` — `Link` adds the base path; a raw anchor doesn't and 404s in the
+  deployed sibling.
+- The **root application sibling** created by `biffo init` serves `/` itself, so
+  its `path_prefix` is empty and `NEXT_PUBLIC_BASE_PATH` is `""` — the same code
+  works unchanged, prefix or no prefix.
+
+### Reaching your backend (never the core API directly)
+
+The frontend talks **only to this sibling's own backend** (`services/api/`),
+never to the core project's API — ADR-0002/ADR-0007. Use `createApiClient` from
+`src/lib/api-client.ts`, pass it the session's ID token, and call your own
+routes (`NEXT_PUBLIC_API_URL` points at this sibling's API Gateway). If you need
+core-owned data, your backend calls the core API server-side
+(`services/api/src/api/core_client.py`) and re-verifies the JWT itself — the
+browser never holds a core credential.
+
+### Public is the default; auth is opt-in per page
+
+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.
+
+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:
+
+```tsx
+'use client'
+import { AuthGate } from '@/lib/auth-gate'
+
+export default function Dashboard() {
+  return (
+    <AuthGate>
+      {(session) => {
+        const token = session.getIdToken().getJwtToken()
+        // pass `token` to createApiClient to call this sibling's backend
+        return <h1>Members only</h1>
+      }}
+    </AuthGate>
+  )
+}
+```
+
+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.
+
+### 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.
+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 —
+   your public page is live at `baseurl.com/<name>/`.
+
+### Running the frontend locally
+
+```bash
+cd apps/frontend
+cp .env.example .env.local   # fill in your core project's Cognito/API values
+pnpm install
+pnpm dev                     # http://localhost:3000
+```
+
+Public pages render with no configuration. The SSO demo and any `<AuthGate>`
+page need the real `NEXT_PUBLIC_CORE_*` values in `.env.local` to complete the
+portal round-trip; without them they resolve as "signed out" rather than
+crashing (the Cognito pool is constructed lazily — see "The build must not need
+Cognito credentials" below).
+
 ## Standalone repo, not a monorepo package
 
 Both `apps/frontend/package.json` and `services/api/pyproject.toml` are

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

@@ -0,0 +1,31 @@
+'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

@@ -0,0 +1,24 @@
+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>
+  )
+}

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

@@ -0,0 +1,83 @@
+import { render, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/lib/auth', () => ({
+  getCurrentSession: vi.fn(),
+}))
+
+// Read at module-evaluation time; stub before the dynamic import below so the
+// component sees the value (same pattern as page.test.tsx).
+process.env['NEXT_PUBLIC_CORE_PORTAL_URL'] = 'https://core.example.com'
+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) {
+  return {
+    getIdToken: () => ({ getJwtToken: () => idToken }),
+  } as unknown as Awaited<ReturnType<typeof getCurrentSession>>
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('AuthGate', () => {
+  it('renders children once a valid session resolves', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(fakeSession('a-jwt'))
+
+    render(
+      <AuthGate>
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('secret content')).toBeInTheDocument()
+    })
+  })
+
+  it('passes the session to a render-prop child', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(fakeSession('token-1234'))
+
+    render(<AuthGate>{(session) => <p>token: {session.getIdToken().getJwtToken()}</p>}</AuthGate>)
+
+    await waitFor(() => {
+      expect(screen.getByText('token: token-1234')).toBeInTheDocument()
+    })
+  })
+
+  it('redirects to the core portal login, returning to the current path, when there is no session', async () => {
+    vi.mocked(getCurrentSession).mockResolvedValueOnce(null)
+
+    // jsdom's real window.location throws on navigation — swap in a plain
+    // object so we can inspect the attempted href (same trick as page.test.tsx).
+    const originalLocation = window.location
+    Object.defineProperty(window, 'location', {
+      value: { href: '', pathname: '/my-sibling/example/members/', search: '' },
+      writable: true,
+      configurable: true,
+    })
+
+    render(
+      <AuthGate>
+        <p>secret content</p>
+      </AuthGate>,
+    )
+
+    await waitFor(() => {
+      expect(window.location.href).toBe(
+        'https://core.example.com/login?return_to=' +
+          encodeURIComponent('/my-sibling/example/members/'),
+      )
+    })
+    expect(screen.queryByText('secret content')).not.toBeInTheDocument()
+
+    Object.defineProperty(window, 'location', {
+      value: originalLocation,
+      writable: true,
+      configurable: true,
+    })
+  })
+})

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

@@ -0,0 +1,110 @@
+'use client'
+
+import { useEffect, useState, type ReactNode } from 'react'
+import type { CognitoUserSession } from 'amazon-cognito-identity-js'
+import { getCurrentSession } from '@/lib/auth'
+
+// ---------------------------------------------------------------------------
+// PUBLIC IS THE DEFAULT — read this before reaching for auth.
+//
+// A sibling app serves UNAUTHENTICATED content by default. That is the
+// go-live state for most products: a page you drop under src/app/ is public
+// the moment it deploys, with no auth code at all. Do NOT gate the whole app.
+//
+// This module is the *opt-in*: wrap only the routes/pages that genuinely need
+// a signed-in user in <AuthGate>. Everything you don't wrap stays public.
+//
+// AuthGate does NOT sign anyone in — a sibling never owns authentication
+// (ADR-0007). It reads the session the core portal already established (via
+// getCurrentSession in ./auth.ts); if there isn't one, it bounces the visitor
+// 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.
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+const CORE_PORTAL_URL = process.env['NEXT_PUBLIC_CORE_PORTAL_URL'] ?? ''
+const SIBLING_PATH_PREFIX = process.env['NEXT_PUBLIC_SIBLING_PATH_PREFIX'] ?? ''
+
+type GateState =
+  { kind: 'checking' } | { kind: 'redirecting' } | { kind: 'authed'; session: CognitoUserSession }
+
+/**
+ * The URL to send an unauthenticated visitor back to after they log in.
+ *
+ * Prefer the live location (so a deep protected route returns to itself); fall
+ * back to this sibling's root prefix when there is no DOM (SSR/prerender).
+ */
+function currentReturnTo(): string {
+  if (typeof window !== 'undefined') {
+    return window.location.pathname + window.location.search
+  }
+  return `${SIBLING_PATH_PREFIX}/`
+}
+
+type AuthGateProps = {
+  /**
+   * What to render once a valid session exists. Either plain nodes, or a
+   * render function that receives the session — use the function form when the
+   * protected UI needs the ID token to call this sibling's backend:
+   *
+   *   <AuthGate>{(session) => <Dashboard token={session.getIdToken().getJwtToken()} />}</AuthGate>
+   */
+  children: ReactNode | ((session: CognitoUserSession) => ReactNode)
+  /**
+   * Shown while the session is being read and during the redirect bounce.
+   * Defaults to a centered spinner (see globals.css).
+   */
+  fallback?: ReactNode
+}
+
+/**
+ * Gate a route/page behind the shared portal session.
+ *
+ * Public is the default for a sibling; this is how you make ONE page private
+ * without touching the rest of the app:
+ *
+ *   'use client'
+ *   import { AuthGate } from '@/lib/auth-gate'
+ *   export default function Page() {
+ *     return <AuthGate><h1>Members only</h1></AuthGate>
+ *   }
+ *
+ * No session → the visitor is redirected to the core portal's login and
+ * returned here afterwards. Valid session → `children` render.
+ */
+export function AuthGate({ children, fallback }: AuthGateProps) {
+  const [state, setState] = useState<GateState>({ kind: 'checking' })
+
+  useEffect(() => {
+    let cancelled = false
+    void getCurrentSession().then((session) => {
+      if (cancelled) return
+      setState(session === null ? { kind: 'redirecting' } : { kind: 'authed', session })
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  useEffect(() => {
+    if (state.kind === 'redirecting' && CORE_PORTAL_URL) {
+      const returnTo = encodeURIComponent(currentReturnTo())
+      window.location.href = `${CORE_PORTAL_URL}/login?return_to=${returnTo}`
+    }
+  }, [state])
+
+  if (state.kind !== 'authed') {
+    return (
+      fallback ?? (
+        <main className="center-screen">
+          <div className="spinner" />
+        </main>
+      )
+    )
+  }
+
+  return <>{typeof children === 'function' ? children(state.session) : children}</>
+}

package/core.version

@@ -1 +1 @@
-0.41.15
+0.41.17

package/package.json

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