@biffo/cli 0.79.0 → 0.80.0

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

@@ -67,15 +67,16 @@ jobs:
       - name: Test
         if: ${{ !cancelled() }}
         run: pnpm run test
-      # Deliberately run with NO NEXT_PUBLIC_CORE_COGNITO_* in scope (issue
-      # #286). `next build` prerenders `/`, which imports src/lib/auth.ts; when
-      # that module built its Cognito pool eagerly the build blew up on any
-      # machine without the real pool ids exported, and nothing in CI caught it
-      # — the first person to find out was whoever had just scaffolded the
-      # sibling, debugging template code they did not write. A sibling's build
-      # must not need auth credentials, so this step is the assertion of that.
-      # Provide the real values in deploy.yml, where they are inlined into the
-      # artifact that actually ships.
+      # Run with NO NEXT_PUBLIC_CORE_COGNITO_* in scope — this is now the
+      # PERMANENT state, not a build-guard quirk. The frontend NEVER reads those
+      # vars: it resolves the core's Cognito identity at runtime from
+      # /.well-known/biffo-identity.json (#403 Stage 3), so nothing is baked into
+      # the bundle and deploy.yml no longer sets them either. `next build`
+      # prerenders `/`, which imports src/lib/auth.ts; that module builds its
+      # Cognito pool lazily (never at module scope) so the build succeeds with no
+      # identity in scope. Originally added as a guard for the eager-construction
+      # crash (issue #286); it now simply asserts a sibling's build needs no auth
+      # credentials at all.
       - name: Build
         if: ${{ !cancelled() }}
         run: pnpm run build

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

@@ -153,8 +153,12 @@ jobs:
           NEXT_PUBLIC_SIBLING_PATH_PREFIX: ${{ vars.PATH_PREFIX && format('/{0}', vars.PATH_PREFIX) || '' }}
           NEXT_PUBLIC_BASE_PATH: ${{ vars.PATH_PREFIX && format('/{0}', vars.PATH_PREFIX) || '' }}
           NEXT_PUBLIC_CORE_PORTAL_URL: ${{ vars.CORE_PORTAL_URL }}
-          NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID: ${{ vars.CORE_COGNITO_USER_POOL_ID }}
-          NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID: ${{ vars.CORE_COGNITO_CLIENT_ID }}
+          # The frontend no longer bakes NEXT_PUBLIC_CORE_COGNITO_* into the
+          # bundle: it resolves the core's Cognito identity at RUNTIME from the
+          # core-published /.well-known/biffo-identity.json document (#403), so
+          # the build no longer needs the pool/client ids. (The BACKEND still
+          # consumes CORE_COGNITO_* via TF_VAR for JWT validation — see the
+          # deploy-infra job above; that is deliberately unchanged.)
           NEXT_PUBLIC_API_URL: ${{ vars.API_URL }}
         run: pnpm run build
       - uses: aws-actions/configure-aws-credentials@v6

package/_skeletons/sibling-template/README.md

@@ -198,14 +198,21 @@ part of the install, so its lifecycle scripts never run.)
 
 ## The build must not need Cognito credentials
 
-`pnpm run build` has to succeed with **no** `NEXT_PUBLIC_CORE_COGNITO_*` set,
-and `.github/workflows/ci.yml` runs it that way on every PR to keep it that
-way. `next build` prerenders `/` in Node, which imports `src/lib/auth.ts`; that
-module therefore constructs its Cognito user pool lazily, on first session
-read, never at module scope (the `CognitoUserPool` constructor throws outright
-when either id is missing). If you add module-scope code that requires real
-core config, the build breaks for everyone who has not exported the pool ids —
-starting with CI. Read config inside the function that needs it.
+The frontend resolves the core's Cognito identity at **runtime** from the
+core-published `/.well-known/biffo-identity.json` document (#403) — it never
+bakes `NEXT_PUBLIC_CORE_COGNITO_*` into the bundle. So `pnpm run build` succeeds
+with **no** `NEXT_PUBLIC_CORE_COGNITO_*` set, and `.github/workflows/ci.yml`
+runs it that way on every PR to keep it that way. `next build` prerenders `/` in
+Node, which imports `src/lib/auth.ts`; that module constructs its Cognito user
+pool lazily, on first session read, never at module scope (the `CognitoUserPool`
+constructor throws outright when either id is missing). If you add module-scope
+code that requires real core config, the build breaks for everyone — starting
+with CI. Read config inside the function that needs it.
+
+(The sibling's **backend** still receives the core pool/client ids at deploy
+time via `TF_VAR_core_cognito_*` — its Terraform builds a JWKS URL from the pool
+id to validate JWTs. That is a separate concern from the frontend bundle and is
+deliberately unchanged.)
 
 ## The two-phase CDN registration
 
@@ -267,12 +274,19 @@ this repo's own `statusChecks` list — see that method's third parameter):
 
 1. Rename `biffo.sibling.json`'s `name`/`core_project`/`path_prefix`.
 2. Copy `apps/frontend/.env.example` to `.env.local` and fill in your core
-   project's real Cognito/API values for local dev.
+   project's real API/portal values for local dev. No Cognito values are
+   needed: the frontend resolves the core's Cognito identity at runtime from
+   `/.well-known/biffo-identity.json` (#403). A locally-run frontend with no
+   reachable document just treats the visitor as signed-out.
 3. `cd infra && terraform init -backend-config=backend.hcl && terraform apply`
    (generate `backend.hcl` yourself for local use — CI generates it inline,
    see `deploy.yml`).
 4. Wire the GitHub Environment variables/secrets `deploy.yml` reads
    (`CORE_COGNITO_USER_POOL_ID`, `CORE_COGNITO_CLIENT_ID`, `CORE_API_URL`,
-   `CORE_PORTAL_URL`, `SIBLING_OIDC_ROLE_ARN`, `TF_STATE_BUCKET`, etc.).
+   `CORE_PORTAL_URL`, `SIBLING_OIDC_ROLE_ARN`, `TF_STATE_BUCKET`, etc.). The
+   `CORE_COGNITO_*` variables are still required: the **backend** consumes them
+   via `TF_VAR_core_cognito_*` for JWT validation (its Terraform derives a JWKS
+   URL from the pool id). They are no longer inlined into the frontend bundle —
+   the frontend resolves the core's Cognito identity at runtime (#403).
 5. Open the registration PR against your core project (`infra/siblings.auto.tfvars.json`)
    yourself, or let `biffo sibling create` do it for you.

package/_skeletons/sibling-template/apps/frontend/.env.example

@@ -6,8 +6,11 @@ NEXT_PUBLIC_SIBLING_NAME=example-sibling
 NEXT_PUBLIC_SIBLING_PATH_PREFIX=/example-sibling
 NEXT_PUBLIC_BASE_PATH=/example-sibling
 NEXT_PUBLIC_CORE_PORTAL_URL=https://baseurl.com
-NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
-NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXX
+# No Cognito env is needed: the sibling resolves the core's Cognito identity at
+# RUNTIME from /.well-known/biffo-identity.json (served by the core), so nothing
+# is baked into the bundle (#403). A locally-run frontend with no reachable
+# document simply treats the visitor as signed-out — a sibling never signs
+# anyone in (ADR-0007).
 # This sibling's OWN API Gateway endpoint (from `terraform output api_url`),
 # NOT the core project's API — the frontend never calls the core API
 # directly (ADR-0002/ADR-0007).

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

@@ -22,16 +22,16 @@ function userWithSession(session: unknown, err: Error | null = null) {
   }
 }
 
-// The env vars are the TRANSITIONAL fallback (#403 Stage 3 removes them). The
-// document is now the preferred source, so most tests set env AND control
-// `fetch` to prove which one wins.
-function configureCognitoEnv() {
-  vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID', 'us-east-1_TESTPOOL')
-  vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID', 'testclientid')
+// The sibling is DOC-ONLY (#403 Stage 3): it NEVER reads NEXT_PUBLIC_CORE_COGNITO_*.
+// This helper only exists to set BOGUS env values in the "env is ignored" tests,
+// proving the pool is never built from env even when it is present.
+function stubBogusCognitoEnv() {
+  vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID', 'us-east-1_BOGUSENV')
+  vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID', 'bogusenvclientid')
 }
 
-// A `fetch` returning a valid identity document. The ids differ from the env
-// values on purpose so a test can prove the DOCUMENT wins over baked env.
+// A `fetch` returning a valid identity document. The ids are what the pool must
+// be built from — the ONLY source of Cognito coordinates now.
 function mockFetchDocument(overrides: Record<string, unknown> = {}) {
   const body = {
     userPoolId: 'us-east-1_DOCPOOL',
@@ -45,7 +45,8 @@ function mockFetchDocument(overrides: Record<string, unknown> = {}) {
   }) as unknown as typeof fetch
 }
 
-// A `fetch` that rejects (network error) — drives the env fallback path.
+// A `fetch` that rejects (network error) — the document is unreachable, so the
+// sibling resolves to null (no env fallback).
 function mockFetchUnreachable() {
   global.fetch = vi.fn().mockRejectedValue(new Error('network down')) as unknown as typeof fetch
 }
@@ -53,7 +54,7 @@ function mockFetchUnreachable() {
 // Each test re-imports the module fresh: both the pool (auth.ts) and the
 // resolved-identity Promise (identity.ts) are memoised at module scope, so a
 // module instance left over from a previous test would carry that test's
-// document/env into the next one.
+// document into the next one.
 async function loadAuth() {
   vi.resetModules()
   return await import('@/lib/auth')
@@ -62,11 +63,9 @@ async function loadAuth() {
 describe('getCurrentSession', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    configureCognitoEnv()
-    // Default: document unreachable, so these behaviour tests build the pool
-    // from the env fallback (us-east-1_TESTPOOL / testclientid) exactly as the
-    // pre-runtime version did.
-    mockFetchUnreachable()
+    // The document is reachable, so these behaviour tests build the pool from
+    // the DOCUMENT (us-east-1_DOCPOOL / docclientid) — never from env.
+    mockFetchDocument()
   })
 
   afterEach(() => {
@@ -100,9 +99,9 @@ describe('getCurrentSession', () => {
   })
 })
 
-// The core now publishes its Cognito coordinates at runtime; the sibling
-// prefers that document over its baked env vars (#403/#400). These tests pin
-// which source wins under each condition.
+// The core publishes its Cognito coordinates at runtime; the sibling is
+// DOC-ONLY (#403 Stage 3) and resolves them from that document alone. These
+// tests pin that the document is the sole source — env is never consulted.
 describe('runtime core identity resolution', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -113,9 +112,9 @@ describe('runtime core identity resolution', () => {
     vi.restoreAllMocks()
   })
 
-  it('builds the pool from the published document, not from env', async () => {
-    // Env is set to DIFFERENT values so a pass proves the document won.
-    configureCognitoEnv()
+  it('builds the pool from the published document', async () => {
+    // Bogus env is set to prove the document — not env — is the source.
+    stubBogusCognitoEnv()
     mockFetchDocument()
     const { getCurrentSession } = await loadAuth()
     getCurrentUser.mockReturnValue(null)
@@ -131,55 +130,44 @@ describe('runtime core identity resolution', () => {
     })
   })
 
-  it('falls back to env and warns when the document is unreachable', async () => {
-    configureCognitoEnv()
+  it('resolves null and never builds the pool from env when the document is unreachable', async () => {
+    // Env is present but BOGUS: a DOC-ONLY sibling must ignore it entirely.
+    stubBogusCognitoEnv()
     mockFetchUnreachable()
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
     const { getCurrentSession } = await loadAuth()
     getCurrentUser.mockReturnValue(null)
 
-    await getCurrentSession()
-
-    expect(poolConstructor).toHaveBeenCalledWith({
-      UserPoolId: 'us-east-1_TESTPOOL',
-      ClientId: 'testclientid',
-    })
+    await expect(getCurrentSession()).resolves.toBeNull()
+    // Proves env is ignored: the pool was never constructed from the bogus env.
+    expect(poolConstructor).not.toHaveBeenCalled()
     expect(warn).toHaveBeenCalledOnce()
-    expect(warn.mock.calls[0]?.[0]).toContain('DEGRADED')
   })
 
-  it('falls back to env when the document is served but missing ids', async () => {
-    configureCognitoEnv()
+  it('resolves null and never builds the pool when the document is served but missing ids', async () => {
+    stubBogusCognitoEnv()
     // ok:true but the body lacks a clientId — treated as unusable.
     mockFetchDocument({ clientId: '' })
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
     const { getCurrentSession } = await loadAuth()
     getCurrentUser.mockReturnValue(null)
 
-    await getCurrentSession()
-
-    expect(poolConstructor).toHaveBeenCalledWith({
-      UserPoolId: 'us-east-1_TESTPOOL',
-      ClientId: 'testclientid',
-    })
+    await expect(getCurrentSession()).resolves.toBeNull()
+    expect(poolConstructor).not.toHaveBeenCalled()
     expect(warn).toHaveBeenCalledOnce()
   })
 
-  it('resolves null and never constructs the pool when both document and env are absent', async () => {
-    vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID', '')
-    vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID', '')
+  it('resolves null when the document is unreachable', async () => {
     mockFetchUnreachable()
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
     const { getCurrentSession } = await loadAuth()
 
     await expect(getCurrentSession()).resolves.toBeNull()
     expect(poolConstructor).not.toHaveBeenCalled()
-    // No document AND no env is an unconfigured build, not degradation — quiet.
-    expect(warn).not.toHaveBeenCalled()
+    expect(warn).toHaveBeenCalledOnce()
   })
 
   it('fetches the document at most once across multiple session reads (memoised)', async () => {
-    configureCognitoEnv()
     mockFetchDocument()
     const { getCurrentSession } = await loadAuth()
     getCurrentUser.mockReturnValue(null)
@@ -210,14 +198,12 @@ describe('lazy pool construction', () => {
   })
 
   it('does not construct the pool merely by importing the module', async () => {
-    configureCognitoEnv()
+    mockFetchDocument()
     await loadAuth()
     expect(poolConstructor).not.toHaveBeenCalled()
   })
 
-  it('imports cleanly with no Cognito env vars set and no fetch available', async () => {
-    vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID', '')
-    vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID', '')
+  it('imports cleanly with no fetch available (next build prerender)', async () => {
     // Simulate `next build` prerendering `/` in Node with no fetch in scope.
     const originalFetch = global.fetch
     // @ts-expect-error deliberately remove fetch to mimic the Node prerender.
@@ -230,16 +216,14 @@ describe('lazy pool construction', () => {
     }
   })
 
-  it('resolves null instead of throwing when Cognito env vars are absent', async () => {
-    vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID', '')
-    vi.stubEnv('NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID', '')
+  it('resolves null instead of throwing when the document is unreachable', async () => {
     const { getCurrentSession } = await loadAuth()
     await expect(getCurrentSession()).resolves.toBeNull()
     expect(poolConstructor).not.toHaveBeenCalled()
   })
 
-  it('constructs the pool once, on first session read, from the env fallback', async () => {
-    configureCognitoEnv()
+  it('constructs the pool once, on first session read, from the document', async () => {
+    mockFetchDocument()
     const { getCurrentSession } = await loadAuth()
     getCurrentUser.mockReturnValue(null)
 
@@ -248,8 +232,8 @@ describe('lazy pool construction', () => {
 
     expect(poolConstructor).toHaveBeenCalledTimes(1)
     expect(poolConstructor).toHaveBeenCalledWith({
-      UserPoolId: 'us-east-1_TESTPOOL',
-      ClientId: 'testclientid',
+      UserPoolId: 'us-east-1_DOCPOOL',
+      ClientId: 'docclientid',
     })
   })
 })

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

@@ -32,11 +32,12 @@ import { resolveCoreIdentity } from './identity'
 // ---------------------------------------------------------------------------
 // Module-private on purpose: the pool is an implementation detail of
 // getCurrentSession(), not part of this sibling's auth surface. Its Cognito
-// coordinates now come from resolveCoreIdentity() (identity.ts), which prefers
-// the core's runtime-published /.well-known/biffo-identity.json document and
-// only falls back to the baked NEXT_PUBLIC_CORE_COGNITO_* env vars when that
-// document is unreachable — see identity.ts for why runtime resolution kills
-// the stale-baked-pool bug class (#403/#400).
+// coordinates come from resolveCoreIdentity() (identity.ts), which resolves the
+// core's runtime-published /.well-known/biffo-identity.json document. The
+// sibling is now DOC-ONLY (#403 Stage 3): there is NO NEXT_PUBLIC_CORE_COGNITO_*
+// env fallback. An unreachable document resolves to null → the caller treats it
+// as "signed out" — see identity.ts for why runtime resolution kills the
+// stale-baked-pool bug class (#403/#400).
 //
 // Constructed LAZILY, on first session read — never at module scope. The
 // CognitoUserPool constructor throws ("Both UserPoolId and ClientId are

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

@@ -29,12 +29,13 @@
 //   this exactly ONE network request per page load, shared by every caller,
 //   rather than one per session read.
 //
-// The env fallback below is TRANSITIONAL (Stage 3 of #403 removes it). It lets
-// an instance whose core has not yet started publishing the document keep
-// working off its baked env vars, so instances can upgrade at their own pace.
-// A baked value that shadows a live document is precisely the stale-copy bug
-// we are removing, so falling back because the document was UNREACHABLE is a
-// degraded path and warns loudly.
+// A sibling is DOC-ONLY (#403 Stage 3): it carries NO CORE_COGNITO_* env vars —
+// `biffo sibling create` no longer sets them and this module no longer reads
+// them. When the document is unreachable, resolution returns null, and the
+// caller (getCurrentSession) treats that as "no session" — the sibling redirects
+// to the portal's login rather than trusting a stale baked value, because a
+// stale value is exactly the bug (#400) this removes. A clean redirect beats a
+// silent point at a dead pool.
 // ---------------------------------------------------------------------------
 
 export interface CoreIdentity {
@@ -54,16 +55,6 @@ const IDENTITY_DOCUMENT_PATH = '/.well-known/biffo-identity.json'
 // callers before the fetch settles also coalesce onto the one request.
 let cached: Promise<CoreIdentity | null> | null = null
 
-// Read the transitional env fallback. Returns a valid CoreIdentity only when
-// BOTH ids are present; otherwise null (an unconfigured build has neither a
-// document nor env, and that is not an error to shout about).
-function identityFromEnv(): CoreIdentity | null {
-  const userPoolId = process.env['NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID'] ?? ''
-  const clientId = process.env['NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID'] ?? ''
-  if (!userPoolId || !clientId) return null
-  return { userPoolId, clientId }
-}
-
 // A parsed document counts only when it carries both ids non-empty; a document
 // missing either is treated as unusable and triggers the fallback.
 function identityFromDocument(data: unknown): CoreIdentity | null {
@@ -90,38 +81,31 @@ async function fetchCoreIdentity(): Promise<CoreIdentity | null> {
       const identity = identityFromDocument(await res.json())
       if (identity) return identity
     }
-    // Reached here => the document was served but unusable (non-ok status or
-    // missing ids). Fall through to the degraded env fallback below.
+    // Served but unusable (non-ok status or missing ids). Fall through to null.
   } catch {
     // Network error, or `fetch` not available (e.g. `next build` prerendering
-    // `/` in Node with no fetch). Fall through to the env fallback.
+    // in Node with no fetch — though resolution is lazy and never runs there).
+    // Fall through to null.
   }
 
-  // DEGRADED path: the document was unreachable/unusable, so we lean on the
-  // baked env vars. If those exist, warn once — a stale baked value silently
-  // shadowing a live document is the #403/#400 bug. If they DON'T exist, this
-  // is simply an unconfigured build (no document, no env) — not degradation,
-  // so stay quiet.
-  const fallback = identityFromEnv()
-  if (fallback) {
-    console.warn(
-      '[biffo] DEGRADED: could not resolve the core identity document at ' +
-        `${IDENTITY_DOCUMENT_PATH}; falling back to baked ` +
-        'NEXT_PUBLIC_CORE_COGNITO_* env vars. This is transitional (#403) and ' +
-        'risks pointing at a stale/dead Cognito pool — ensure the core is ' +
-        'publishing the runtime identity document.',
-    )
-  }
-  return fallback
+  // The document was unreachable or unusable. A sibling has NO baked fallback
+  // (#403 Stage 3), so this resolves to null and the caller treats it as
+  // "signed out" — a clean redirect to the portal login beats trusting a stale
+  // local pool id, which is the exact bug (#400) this removes.
+  console.warn(
+    `[biffo] could not resolve the core identity document at ${IDENTITY_DOCUMENT_PATH}; ` +
+      'treating the visitor as signed out. If this persists, confirm the core is publishing it.',
+  )
+  return null
 }
 
 /**
- * Resolve the core's Cognito identity at runtime, preferring the published
- * `/.well-known/biffo-identity.json` document and falling back to baked
- * `NEXT_PUBLIC_CORE_COGNITO_*` env vars when the document is unreachable.
+ * Resolve the core's Cognito identity at runtime from the published
+ * `/.well-known/biffo-identity.json` document. A sibling has no env fallback
+ * (#403 Stage 3).
  *
  * Memoised: at most one fetch per page load, shared by every caller. Returns
- * null when neither the document nor the env vars supply both ids.
+ * null when the document is unreachable or does not supply both ids.
  */
 export function resolveCoreIdentity(): Promise<CoreIdentity | null> {
   cached ??= fetchCoreIdentity()

package/package.json

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