@biffo/cli 0.77.0 → 0.78.0

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

@@ -22,14 +22,38 @@ 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')
 }
 
-// Each test re-imports the module fresh: the pool is memoised after its first
-// construction, so a module instance left over from a previous test would carry
-// that test's env into the next one.
+// 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.
+function mockFetchDocument(overrides: Record<string, unknown> = {}) {
+  const body = {
+    userPoolId: 'us-east-1_DOCPOOL',
+    clientId: 'docclientid',
+    region: 'us-east-1',
+    ...overrides,
+  }
+  global.fetch = vi.fn().mockResolvedValue({
+    ok: true,
+    json: async () => body,
+  }) as unknown as typeof fetch
+}
+
+// A `fetch` that rejects (network error) — drives the env fallback path.
+function mockFetchUnreachable() {
+  global.fetch = vi.fn().mockRejectedValue(new Error('network down')) as unknown as typeof fetch
+}
+
+// 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.
 async function loadAuth() {
   vi.resetModules()
   return await import('@/lib/auth')
@@ -39,10 +63,15 @@ 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()
   })
 
   afterEach(() => {
     vi.unstubAllEnvs()
+    vi.restoreAllMocks()
   })
 
   it('returns null when no user is stored in the shared localStorage session', async () => {
@@ -71,18 +100,113 @@ 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.
+describe('runtime core identity resolution', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    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()
+    mockFetchDocument()
+    const { getCurrentSession } = await loadAuth()
+    getCurrentUser.mockReturnValue(null)
+
+    await getCurrentSession()
+
+    expect(global.fetch).toHaveBeenCalledWith('/.well-known/biffo-identity.json', {
+      cache: 'no-store',
+    })
+    expect(poolConstructor).toHaveBeenCalledWith({
+      UserPoolId: 'us-east-1_DOCPOOL',
+      ClientId: 'docclientid',
+    })
+  })
+
+  it('falls back to env and warns when the document is unreachable', async () => {
+    configureCognitoEnv()
+    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',
+    })
+    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()
+    // 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',
+    })
+    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', '')
+    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()
+  })
+
+  it('fetches the document at most once across multiple session reads (memoised)', async () => {
+    configureCognitoEnv()
+    mockFetchDocument()
+    const { getCurrentSession } = await loadAuth()
+    getCurrentUser.mockReturnValue(null)
+
+    await getCurrentSession()
+    await getCurrentSession()
+    await getCurrentSession()
+
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+    expect(poolConstructor).toHaveBeenCalledTimes(1)
+  })
+})
+
 // The CognitoUserPool constructor throws ("Both UserPoolId and ClientId are
 // required") when either value is missing, and `next build` prerenders `/` in
 // Node — which imports this module. Building the pool at module scope therefore
-// made the skeleton un-buildable without real Cognito credentials in scope.
-// These tests pin that shut.
+// made the skeleton un-buildable without a resolvable identity in scope. These
+// tests pin that shut.
 describe('lazy pool construction', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    mockFetchUnreachable()
   })
 
   afterEach(() => {
     vi.unstubAllEnvs()
+    vi.restoreAllMocks()
   })
 
   it('does not construct the pool merely by importing the module', async () => {
@@ -91,11 +215,19 @@ describe('lazy pool construction', () => {
     expect(poolConstructor).not.toHaveBeenCalled()
   })
 
-  it('imports cleanly with no Cognito env vars set', async () => {
+  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', '')
-    await expect(loadAuth()).resolves.toBeDefined()
-    expect(poolConstructor).not.toHaveBeenCalled()
+    // 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.
+    delete global.fetch
+    try {
+      await expect(loadAuth()).resolves.toBeDefined()
+      expect(poolConstructor).not.toHaveBeenCalled()
+    } finally {
+      global.fetch = originalFetch
+    }
   })
 
   it('resolves null instead of throwing when Cognito env vars are absent', async () => {
@@ -106,7 +238,7 @@ describe('lazy pool construction', () => {
     expect(poolConstructor).not.toHaveBeenCalled()
   })
 
-  it('constructs the pool once, on first session read, from the core env vars', async () => {
+  it('constructs the pool once, on first session read, from the env fallback', async () => {
     configureCognitoEnv()
     const { getCurrentSession } = await loadAuth()
     getCurrentUser.mockReturnValue(null)
@@ -127,6 +259,9 @@ describe('lazy pool construction', () => {
 // login path that bypasses the portal and silently breaks single-sign-on.
 // If you are here because you deliberately added one of these, that decision
 // belongs in an ADR — not in a green test suite.
+//
+// resolveCoreIdentity lives in identity.ts, deliberately NOT re-exported here:
+// auth.ts's surface stays exactly one export.
 describe('sibling auth surface', () => {
   it('exposes only session reading — no sign-in/sign-out machinery', async () => {
     const authModule = await loadAuth()

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

@@ -4,6 +4,8 @@ import {
   type ICognitoUserPoolData,
 } from 'amazon-cognito-identity-js'
 
+import { resolveCoreIdentity } from './identity'
+
 // ---------------------------------------------------------------------------
 // SHARED-SESSION INVARIANT — read this before changing anything below.
 //
@@ -29,28 +31,38 @@ import {
 // portal too.
 // ---------------------------------------------------------------------------
 // Module-private on purpose: the pool is an implementation detail of
-// getCurrentSession(), not part of this sibling's auth surface.
+// 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).
 //
 // Constructed LAZILY, on first session read — never at module scope. The
 // CognitoUserPool constructor throws ("Both UserPoolId and ClientId are
 // required") when either value is missing, and `next build` prerenders `/` in
 // Node, which imports this module. Constructing eagerly therefore made the
-// whole app un-buildable without the real Cognito env vars in scope — a build
-// is not a sign-in, and it has no business needing pool credentials. Deferring
+// whole app un-buildable without a resolvable identity in scope — a build is
+// not a sign-in, and it has no business needing pool credentials. Deferring
 // keeps `pnpm run build` (and any import of this module) working with no env
-// configured, while an actual session read in a misconfigured deployment
-// surfaces as "signed out" rather than a hard crash.
+// and no reachable document, while an actual session read in a misconfigured
+// deployment surfaces as "signed out" rather than a hard crash.
+//
+// The pool itself is memoised: resolveCoreIdentity() is memoised too, but the
+// CognitoUserPool wrapper is built here exactly once so repeated session reads
+// reuse one instance (and its localStorage view of the shared session).
 let userPool: CognitoUserPool | null = null
 
-function getUserPool(): CognitoUserPool | null {
+async function getUserPool(): Promise<CognitoUserPool | null> {
   if (userPool) return userPool
 
+  const identity = await resolveCoreIdentity()
+  if (!identity) return null
+
   const poolData: ICognitoUserPoolData = {
-    UserPoolId: process.env['NEXT_PUBLIC_CORE_COGNITO_USER_POOL_ID'] ?? '',
-    ClientId: process.env['NEXT_PUBLIC_CORE_COGNITO_CLIENT_ID'] ?? '',
+    UserPoolId: identity.userPoolId,
+    ClientId: identity.clientId,
   }
-  if (!poolData.UserPoolId || !poolData.ClientId) return null
-
   userPool = new CognitoUserPool(poolData)
   return userPool
 }
@@ -62,15 +74,15 @@ function getUserPool(): CognitoUserPool | null {
  * (see `createApiClient`, which takes a `getIdToken` callback). A null result
  * means "redirect the user to the portal's login".
  */
-export function getCurrentSession(): Promise<CognitoUserSession | null> {
+export async function getCurrentSession(): Promise<CognitoUserSession | null> {
+  // Resolving the pool is now async because the core identity is fetched at
+  // runtime (identity.ts). A null pool means no resolvable core Cognito config,
+  // which is indistinguishable from "not signed in" as far as callers are
+  // concerned — the semantics are unchanged from the env-only version.
+  const pool = await getUserPool()
+  if (!pool) return null
+
   return new Promise((resolve) => {
-    // No pool means no core Cognito config, which is indistinguishable from
-    // "not signed in" as far as callers are concerned.
-    const pool = getUserPool()
-    if (!pool) {
-      resolve(null)
-      return
-    }
     const user = pool.getCurrentUser()
     if (!user) {
       resolve(null)

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

@@ -0,0 +1,140 @@
+// ---------------------------------------------------------------------------
+// RUNTIME CORE IDENTITY (#403 / #400)
+//
+// The core project publishes its Cognito coordinates at
+// `/.well-known/biffo-identity.json`, served same-origin from the portal
+// bucket (see modules/cloud/aws/cdn/main.tf and .github/workflows/deploy-infra.yml).
+// This module resolves that document at RUNTIME so a sibling never has to bake
+// the core's User Pool / App Client id into its bundle.
+//
+// WHY runtime, not build-time:
+//   Baking `NEXT_PUBLIC_CORE_COGNITO_*` into the static export copies a
+//   snapshot of the core's pool id into every sibling. When the core replaces
+//   its pool (or client), every sibling still points at the dead one until it
+//   is rebuilt and redeployed — that stranding is exactly the bug class #400
+//   and #403 exist to delete. Reading the published document each page load
+//   removes the copy entirely: the source of truth lives with the core.
+//
+// WHY a RELATIVE, same-origin fetch is valid:
+//   A sibling and the core portal live on the SAME ORIGIN (baseurl.com/ vs
+//   baseurl.com/<name>/). That is the same property that makes shared-session
+//   SSO work (see the SHARED-SESSION INVARIANT in auth.ts). So a relative
+//   `fetch('/.well-known/biffo-identity.json')` reaches the core's document
+//   with no CORS, no configured base URL, and no knowledge of the deployment's
+//   domain.
+//
+// WHY memoised:
+//   The document is immutable for a page's lifetime, and auth is read on many
+//   code paths. Memoising the in-flight/resolved Promise at module scope makes
+//   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.
+// ---------------------------------------------------------------------------
+
+export interface CoreIdentity {
+  userPoolId: string
+  clientId: string
+  region?: string
+  apiUrl?: string
+  portalUrl?: string
+}
+
+// The relative, same-origin path the core publishes its identity document at.
+const IDENTITY_DOCUMENT_PATH = '/.well-known/biffo-identity.json'
+
+// Memoised for the page's lifetime: the first call kicks off the fetch and
+// every subsequent call shares the same Promise, so the document is requested
+// at most once. Storing the Promise (not the resolved value) means concurrent
+// 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 {
+  if (typeof data !== 'object' || data === null) return null
+  const doc = data as Record<string, unknown>
+  const userPoolId = typeof doc['userPoolId'] === 'string' ? doc['userPoolId'] : ''
+  const clientId = typeof doc['clientId'] === 'string' ? doc['clientId'] : ''
+  if (!userPoolId || !clientId) return null
+
+  const identity: CoreIdentity = { userPoolId, clientId }
+  if (typeof doc['region'] === 'string') identity.region = doc['region']
+  if (typeof doc['apiUrl'] === 'string') identity.apiUrl = doc['apiUrl']
+  if (typeof doc['portalUrl'] === 'string') identity.portalUrl = doc['portalUrl']
+  return identity
+}
+
+async function fetchCoreIdentity(): Promise<CoreIdentity | null> {
+  try {
+    // `no-store`: never let a stale document linger in the fetch cache — the
+    // whole point of runtime resolution is to always see the core's current
+    // coordinates.
+    const res = await fetch(IDENTITY_DOCUMENT_PATH, { cache: 'no-store' })
+    if (res.ok) {
+      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.
+  } catch {
+    // Network error, or `fetch` not available (e.g. `next build` prerendering
+    // `/` in Node with no fetch). Fall through to the env fallback.
+  }
+
+  // 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
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function resolveCoreIdentity(): Promise<CoreIdentity | null> {
+  cached ??= fetchCoreIdentity()
+  return cached
+}
+
+/**
+ * Test-only: clear the memoised resolution so the next `resolveCoreIdentity()`
+ * fetches afresh. Production code never calls this — the memo is meant to live
+ * for the whole page. Tests that re-import the module via `vi.resetModules()`
+ * get a fresh module-scope `cached` for free; this hook is for tests that want
+ * to reset within a single module instance.
+ */
+export function __resetCoreIdentityForTests(): void {
+  cached = null
+}

package/package.json

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