feat(web): own tenant BFF sessions and close browser admission

.claude/skills/add-feature-gated-ui/SKILL.md

@@ -30,8 +30,10 @@ to a `mailto:` on Self-Hosted). All of this lives in
 
 ## When not to use
 
-- Authorisation (permission checks). Those use `auth().permissions.includes(...)`,
-  not feature flags.
+- Authentication or authorization. The current app-local
+  `@/server/auth/auth` helper returns only a safe session projection, with no
+  permissions/roles. Phase 03 owns permission-aware UI, backed by API enforcement;
+  a feature flag never grants a permission.
 - Greying-out a feature instead of hiding. Three UI patterns the project picked:
   **hide** for missing features, **visualise** for limits, **block-then-link** for
   exceeded hard limits.
@@ -48,6 +50,13 @@ to a `mailto:` on Self-Hosted). All of this lives in
 
 ## Workflow
 
+The hook/package examples below describe the Phase 06 entitlement-aware UI
+target, not exports in the current SDK. P02b-7 supplies session UI only; do not
+invent entitlement hooks, a permissions array or SSE transport while adding a
+session-protected page. Follow
+[add-frontend-route](../add-frontend-route/SKILL.md#step-5-authentication--permission-gating)
+for the implemented authentication boundary.
+
 ### Step 1: Feature gating with `useFeatureFlag`
 
 ```tsx

.claude/skills/add-frontend-route/SKILL.md

@@ -3,12 +3,12 @@ name: add-frontend-route
 description: >
   Add a Next.js App Router route under `frontend/apps/web/src/app/(public)/` /
   `(studio)/` / `(portal)/` with the right route group, tenant + organization +
-  locale resolution, Server Component default, permission guards (for studio /
-  portal), and SDK-based data fetching. USE FOR: a new public page, Studio screen,
-  or learner / instructor portal screen. DO NOT USE FOR: thin BFF proxy endpoints
-  (those live in `app/api/`), routes for the operator portal (that's the separate
-  `operator-portal` app), or hand-rolled `fetch` to the backend (use the typed
-  SDK).
+  locale resolution, Server Component default, the owning phase's permission
+  guards, and admitted SDK-based data fetching. USE FOR: a new public page,
+  Studio screen, or learner / instructor portal screen. DO NOT USE FOR: native
+  BFF protocol changes or generic proxy endpoints, routes for the operator
+  portal (that's the separate `operator-portal` app), or hand-rolled `fetch` to
+  the backend (use the typed SDK).
 ---
 
 # Adding a frontend route
@@ -26,7 +26,6 @@ SDK contract per
 - A new public page (marketing / CMS-rendered).
 - A new Studio screen for tenant admin / org admin.
 - A new portal screen for learner / instructor.
-- A new BFF route handler under `api/` (rare; mostly auth callbacks).
 
 ## When not to use
 
@@ -36,6 +35,8 @@ SDK contract per
   `frontend/packages/config/eslint/index.cjs`).
 - Routes that bypass tenant resolution — every authenticated route requires a
   resolved tenant.
+- Generic BFF proxies or a new authentication action. ADR-0070's auth protocol
+  belongs to its native response owner; `app/api` currently contains only healthz.
 
 ## Inputs
 
@@ -54,8 +55,8 @@ SDK contract per
 | Group | Purpose | Auth | Default render |
 |-------|---------|------|----------------|
 | `(public)` | Tenant public site (marketing, catalog, blog). | Anonymous by default; auth optional. | Dynamic SSR, no-store per ADR-0053; see Step 8. |
-| `(studio)` | Tenant admin Studio. | Tenant-admin or org-admin. Required at the edge. | SSR, no cache (always fresh). |
-| `(portal)` | Learner / instructor portal. | Membership in the resolved tenant. | SSR shell + Client Component for interactivity. |
+| `(studio)` | Current `/studio` account scaffold; future admin screens. | Native BFF session admission; permission-sensitive screens require Phase 03's real authorization. | SSR, no cache (always fresh). |
+| `(portal)` | Current `/portal` account scaffold; future learner/instructor screens. | Native BFF session admission; the current projection proves no membership or permission. | SSR shell + Client Component for interactivity. |
 
 ### Step 2: Create the route folder
 
@@ -70,13 +71,15 @@ localized section names.
 ```
 frontend/apps/web/src/app/
   (studio)/
-    dashboard/
-      users/
-        page.tsx
-        loading.tsx
-        error.tsx
+    studio/page.tsx
+  (portal)/
+    portal/page.tsx
 ```
 
+These exact paths are the current authenticated scaffold census. New screens
+need their owning phase's admission/authorization decision and matching route
+census controls; a route-group folder alone grants no access.
+
 Use the `layout.tsx` already present in the route group; do not add a new layout
 unless the screen genuinely needs one.
 
@@ -117,8 +120,10 @@ Rules:
 
 - Default to Server Component. `"use client"` only when the screen needs hooks,
   browser APIs, or third-party client-only libs.
-- The SDK (`@learnstack/sdk/server`) is the **only** sanctioned way to call the
-  API. Hand-rolled `fetch('/v1/...')` is blocked by lint.
+- Public pages use admitted resource loaders backed by `@learnstack/sdk/server`.
+  The exact authenticated AccountSite caller stays in the native BFF owner;
+  neither a page nor the SDK selects credentials, host or tenancy headers.
+  Hand-rolled `fetch('/v1/...')` is blocked by lint.
 - Pass typed primitives across the RSC → Client boundary — no class instances, no
   closures.
 
@@ -146,9 +151,11 @@ through bootstrap and the configured caller; Phase 11 owns participation/samplin
 **ADR-0054 native/URL controls delivered — 2026-10-09.**
 [The replacement contract](../../../docs/decisions/0054-bounded-public-renderer-admission.md)
 requires native GET/HEAD admission on every HTTP callback path, including
-middleware-exempt health/assets/scaffolds, with masked no-store refusal of other
-methods and bodyless HEAD. Production upgrades close; development retains only
-validated GET HMR. The [remediation record](../../../docs/roadmap/phase-02d-delivery-log.md#remediation-step-2--native-ingress-and-url-boundary)
+middleware-exempt health/assets/scaffolds. ADR-0070 adds POST only on exact
+`/api/auth/signin/keycloak`, `/api/auth/signout` and `/api/auth/extend`,
+with their closed Origin/CSRF/body controls. Other methods retain masked
+no-store refusal; HEAD remains bodyless. Production upgrades close; development
+retains only validated GET HMR. The [remediation record](../../../docs/roadmap/phase-02d-delivery-log.md#remediation-step-2--native-ingress-and-url-boundary)
 owns validation and both independent review rounds. Do not add
 Server Actions/write routes or WebSocket consumers without an explicit owning
 Phase 02b/Phase 06
@@ -159,33 +166,25 @@ accepted HTTPS port and local path select the destination.
 
 ### Step 5: Authentication + permission gating
 
-Authentication below is the Phase 02b target, not current scaffold behavior.
-Today's exact `/studio` and `/portal` roots pass only after public host bootstrap;
-no sign-in/session helper is implemented. Phase 02b must explicitly admit its
-login/callback namespace before adding authenticated routes.
-
-For those future `(studio)` and `(portal)` routes:
-
-- Unauthenticated requests redirect through the accepted BFF/Keycloak sign-in flow.
-- A page-level permission check uses the future `auth()` helper:
-
-```tsx
-import { auth } from "@learnstack/auth/server"; // illustrative: no such package exists yet; Phase 02b's session work owns the real helper
-import { redirect } from "next/navigation";
-
-export default async function UsersPage() {
-  const session = await auth();
-  if (!session) redirect("/login");
-  if (!session.permissions.includes("identity.user.read")) {
-    redirect("/dashboard");   // or render a 403 UI
-  }
-  // ...
-}
-```
-
-`auth()` reads from the HttpOnly cookie session set by the BFF; never touch tokens
-in a Client Component. The frontend permission check is **mirror-only** — the API
-is authoritative.
+P02b-7 implements the optional native BFF under
+[ADR-0070](../../../docs/decisions/0070-owned-tenant-bff-sessions.md).
+Host bootstrap precedes cookie/provider work. Disabled mode refuses auth paths
+with 404 and the exact `/studio` and `/portal` shells with 503. Enabled mode
+redirects anonymous shell requests to `/api/auth/signin` with a closed local
+return destination. Add no generic proxy or new auth action.
+
+The app-local `auth()` is a passive safe projection lookup in the admitted native
+request; it does not parse cookies, refresh or mutate idle state. Layout and page
+consumers still check their own admission after awaits. Follow the actual
+[`components/auth/shell.tsx`](../../../frontend/apps/web/src/components/auth/shell.tsx)
+owner for those checks and the exact `/studio` or `/portal` return destination,
+rather than constructing a second authentication path in a page.
+
+Never touch tokens in a Client Component. The projection has no permissions or
+roles. Phase 03 owns permission-based screens and their mirror-only UI checks;
+the API remains authoritative. Current shells grant no authoring capability.
+Use full document anchors, no-store responses and the protected history guard;
+do not introduce prefetch/Router Cache reuse for protected navigation.
 
 ### Step 6: Feature gating (entitlement-aware UI)
 
@@ -222,7 +221,8 @@ export default async function CoursesPage() {
 ```
 
 Messages live in `frontend/apps/web/src/i18n/messages/<locale>/<namespace>.json`;
-P02d-6 supplies complete `en/public.json` and `tr/public.json`. General UI keys
+P02d-6 supplies complete `en/public.json` and `tr/public.json`; P02b-7 supplies
+`en/auth.json` and `tr/auth.json` through the same catalogue guard. General UI keys
 are dotted feature identifiers, distinct from backend `lockey_*` wire keys. The
 web app owns closed page-outcome mappings; the SDK supplies no translations.
 See [add-i18n-key](../add-i18n-key/SKILL.md).
@@ -236,8 +236,8 @@ authority. Only whole-catalogue fallback is allowed for unauthored UI languages;
 missing used keys in supported catalogues fail validation. Preserve exact content
 locale, document language and actual resolved-label language.
 
-The guarded frontend suite supplies ICU, argument and callsite checks. No
-`lint:i18n` command or screenshot/axe tooling exists. The
+The guarded frontend suite supplies ICU, argument and callsite checks; there is
+no separate `lint:i18n` command. The full Playwright/axe suite belongs to Phase 06.
 [Step 1 delivery record](../../../docs/roadmap/phase-02d-delivery-log.md#p02d-6-step-1-localization-and-document-foundation)
 owns foundation validation; the
 [packet closeout](../../../docs/roadmap/phase-02d-delivery-log.md#p02d-6-packet-closeout-2026-10-10)
@@ -330,8 +330,10 @@ records passing production replacement proofs, completed reviews and verified fi
   which bans a direct `fetch` call outside the SDK.
 - The route renders under the resolved tenant/org/locale and rejects mismatched
   authn.
-- A `(studio)` route returns 403 when the actor lacks the required permission;
-  the API was already authoritative — confirm.
+- Current `/studio` and `/portal` follow the native enabled/disabled session
+  outcomes, with no authoring permission implied. Before adding a screen that
+  requires permission, Phase 03's API authorization must refuse unauthorized work;
+  a hidden button or successful session projection is insufficient.
 - The public-route budgets in
   [Performance Standards](../../../docs/standards/15-performance.md) hold on
   representative routes — judged by reading until CI's `lighthouse budget` job is
@@ -340,7 +342,8 @@ records passing production replacement proofs, completed reviews and verified fi
 ## Common pitfalls
 
 - **Mounting under the wrong route group.** Public institution routes are dynamic
-  and no-store under ADR-0053; Studio/Portal authentication remains Phase 02b.
+  and no-store under ADR-0053; exact Studio/Portal scaffolds use ADR-0070's native
+  BFF session admission. Future screens do not inherit permission from that shell.
 - **Hand-rolled `fetch`.** Only the configured server adapter has an API transport
   exemption. Page consumers call its SDK; no second header setter is permitted.
 - **Reading `host` inside a page.** The API resolves authority. The native ingress

.claude/skills/add-i18n-key/SKILL.md

@@ -70,11 +70,13 @@ frontend/apps/web/src/i18n/
   messages/
     en/public.json
     tr/public.json
+    en/auth.json
+    tr/auth.json
 ```
 
-P02d-6 supplies only `public`; later features add a namespace beneath each locale.
-`catalogues.ts` statically imports the two public files, and `request.ts` explicitly
-mounts them as `messages.public`. There is no automatic file discovery. JSON nesting
+P02d-6 supplies `public`; P02b-7 adds `auth`. `catalogues.ts` and
+`auth-catalogues.ts` statically import their complete en/tr files; `request.ts`
+explicitly mounts both namespaces. There is no automatic file discovery. JSON nesting
 supplies dotted identifiers: `public.catalog.course_count` is
 `catalog.course_count` within the `public` translator.
 
@@ -141,7 +143,7 @@ same layout; they do not introduce an enrollment catalogue in P02d-6.
 
 For a new namespace, adding JSON files is insufficient. Wire their static imports
 and locale map into `catalogues.ts`, mount the namespace in `request.ts`, and add
-its typed translator and callsite-census coverage. Do not pass a catalogue to a
+its typed translator and callsite-census coverage (`auth` uses typed `copy`). Do not pass a catalogue to a
 Client Component. For public keys with new ICU arguments, update
 `PublicMessageArguments` alongside the messages and their callsites.
 

.claude/skills/code-review/SKILL.md

@@ -84,7 +84,7 @@ Walk every change against the project's
 | **Tenant id from the resolved context only** | Resolved per [ADR-0036](../../../docs/decisions/0036-tenant-resolution-trusted-inputs.md): from the host lookup of the effective host, or on a platform host from validated claims confirmed by live membership; off HTTP, from the validated authoritative job row or the integration-event envelope. Never from a request body, query string, cookie or tenant header — `X-Tenant-Id` and `X-Organization-Id` are assertions that can only reject, on every hop. Check command and DTO surfaces. |
 | **SQL injection** | EF Core LINQ or `FromSqlInterpolated`; never raw string concatenation. Raw SQL has parameters. |
 | **XSS** | No `dangerouslySetInnerHTML` outside a sanitisation wrapper; CSP nonces in place; markdown via allowlist. Nothing sets a CSP today: the [standards index](../../../docs/standards/README.md#honest-status-today) row for Security Standards carves § HTTP Headers out to [Phase 11](../../../docs/roadmap/phase-11-production-hardening.md#security), so a missing nonce is not a Blocker until that phase sets one. Accepted P02d-6 G42 requires atomic four-color validation and a fixed style element, with whole-palette fallback; output must be safe without CSP. [The accepted package](../../../docs/roadmap/phase-02d-delivery-log.md#p02d-6-accepted-answers) owns its proof obligations; acceptance alone is not delivery. |
-| **CSRF** | Server Actions / Auth.js session check; non-Action mutating fetches carry CSRF tokens. |
+| **CSRF** | ADR-0070's closed BFF POSTs require the exact verified Origin and explicit CSRF proof; OIDC callbacks require their bound state/nonce/PKCE transaction. Server Actions remain unadmitted until their owning phase authorizes them. |
 | **Secrets** | No secret in source / appsettings / env-file-committed; reads through `ISecretProvider`. No log of token / password / national id. |
 | **PII redaction** | `[PiiSensitive]` fields carry `SensitiveTokenCatalog.RedactedValue` in audit snapshots — the property stays, so the diff still records *that* it changed; logs don't carry raw PII. |
 | **File upload** | MIME sniff + extension allowlist + size limit + EXIF strip + tenant-scoped key. |

.env.example

@@ -73,6 +73,12 @@ KEYCLOAK_ADMIN_PASSWORD=admin-dev-secret
 # reconciliation verifies an existing confidential secret and never rotates it.
 # Never pass this value to the API, public renderer or .NET Seeder.
 KEYCLOAK_WEB_CLIENT_SECRET=learnstack-web-dev-secret
+# Optional native tenant BFF (ADR-0070). Explicit false keeps the anonymous demo
+# independent of Keycloak. For local watch mode, opt in with true and the issuer
+# below; production launch requires an HTTPS issuer and a trusting private CA.
+# All present root/web/process values must agree. Private source files are 0600.
+LEARNSTACK_BFF_ENABLED=false
+# LEARNSTACK_BFF_ISSUER=http://localhost:8080/realms/learnstack
 
 # ─── Vault (-dev mode; token shared with Dapr secret-store component) ────
 # Boots the `vault` compose service via `-dev-root-token-id` AND is passed

.github/workflows/ci.yml

@@ -289,6 +289,10 @@ jobs:
         working-directory: frontend
         run: pnpm install --frozen-lockfile
 
+      - name: Compile native web and authenticated SDK fixture entries
+        working-directory: frontend
+        run: pnpm --filter @learnstack/web build:ingress
+
       - name: Prepare pinned provider fixture images within the whole-job budget
         timeout-minutes: 2
         run: python3 scripts/ci-test-shards.py prepare-fixtures

CLAUDE.md

@@ -40,16 +40,10 @@ repository holds only LearnStack's side of the boundary, in
 ## What state this is in
 
 **Phase 01, Phase 02a and Phase 02d are complete; Phase 02b is the live phase.**
-[Phase 02d](docs/roadmap/phase-02d-walking-skeleton.md), the two-tenant walking
-skeleton and the first user-visible milestone, merged through PR #28 on
-2026-10-11: two hosts, two tenants, two education sites, one binary and one
-database. In [Phase 02b](docs/roadmap/phase-02b-events-auth.md), P02b-0 through
-P02b-5 are complete and P02b-1–5 merged through PRs #29–#33 — transactional event
-production, durable dispatch, subscriber delivery, background jobs and tenant API
-authentication — and P02b-6's realm and identity implementation is merged through
-PR #34, with post-merge CI corrections continuing on `development`. P02b-7 (BFF
-session) and P02b-8 (exit enforcement) are pending, and G13's session part stays
-Open, so browser sign-in is not implemented. Phase 06 retains the full
+[Phase 02d](docs/roadmap/phase-02d-walking-skeleton.md) owns the two-tenant walking
+skeleton. [Phase 02b](docs/roadmap/phase-02b-events-auth.md) owns current packet
+and decision state for events, background jobs, identity and sessions.
+[Phase 06](docs/roadmap/phase-06-renderer-admin-studio.md) owns the full
 renderer/Studio expansion.
 
 **Status lives in one place.** Each phase document's Status block owns packet