fix(brief): keep the dev hatches out of production builds (RB-11)

BIO-012: roleInterceptor/subjectInterceptor are correctly registered
only under isDevMode(), but three hand-written fetch adapters
(reveal-bignummer, letter-preview, org-template's proefbrief) bypass
HttpClient and set X-Role/X-Subject themselves with no guard. The
readers underneath, role.ts and subject.ts, were ungated too: they
read ?role=/?subject= and wrote it into sessionStorage on any
navigation, in any build -- for ?subject= that value is a BSN, which
is exactly what SessionStore's G1 comment promises never happens.

Gate both layers: currentRole()/currentSubject() return their safe
default immediately outside isDevMode() (no query-param read, no
sessionStorage write), and the three adapters additionally wrap their
headers in isDevMode() so a production request carries neither header
at all, matching what an HttpClient request already does once the
interceptors aren't registered.

TE-002: reveal-bignummer's response-shape validation was a "Trust
boundary" a spec could only reach by stubbing globalThis.fetch.
Exported it as parseRevealed(body), matching the other 30 parse*
boundaries in the repo. Same treatment for letter-preview's
errorMessage and org-template's proefbrief error mapping (extracted
from an inline try/catch into a named, exported function first, since
it wasn't already separate).

BIO-006(a): reveal-bignummer sent X-Step-Up: 'true' unconditionally,
so the backend's step-up precondition constrained nothing. reveal()
now takes a stepUp flag; BriefStore.revealBigNummer() -- reachable
only after the UI's confirm() gesture -- is the one that supplies it,
so the literal no longer lives in the transport adapter.

BIO-006(b): documented in roles-and-access.md that drafter is also
the backend's fallback identity (StubIdentityProvider's catch-all
arm), not just the dev switcher's initial choice -- so the
least-privilege consequence of it also being the only role that may
reveal a BSN is visible.

Doc correction, same diff: roles-and-access.md's "wired only under
isDevMode()" claim was false for the three hand-written fetch paths;
it now says where the gate lives (interceptor registration and the
reader functions) so it doesn't go stale the same way again.
CLAUDE.md's dev-only claims needed no correction -- they already
noted these three calls bypass the interceptor.

Every fix has a test confirmed red by temporarily reverting the
source change and rerunning the suite before restoring it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

libs/shared/docs/behaviour-spec.mdx

@@ -20,7 +20,7 @@ tested where._
 
 Every bullet below is a real test name from the suite — an `it()` title (frontend) or a test
 method name (backend), read as a sentence. Nothing here is hand-written prose: this page
-**is** the suite, reshaped for a business reader. 406 frontend behaviours across
+**is** the suite, reshaped for a business reader. 431 frontend behaviours across
 8 contexts; 217 backend behaviours across 36 test
 classes.
 
@@ -186,6 +186,16 @@ classes.
 - swaps the masked value for the revealed one on success
 - keeps the value masked and surfaces the error on failure
 
+#### LetterPreviewAdapter.preview (BIO-012)
+
+- sends no X-Role/X-Subject headers outside isDevMode()
+- sends X-Role (and X-Subject when known) under isDevMode()
+
+#### RevealBigNummerAdapter.reveal (BIO-006a + BIO-012)
+
+- sends X-Step-Up only when the caller passes stepUp: true
+- sends X-Role only under isDevMode()
+
 #### besluitGuidance
 
 - positief: counts inserted passages, no reden needed (positief has no redenen)
@@ -237,6 +247,12 @@ classes.
 - marks added, removed, changed and unchanged by blockId
 - changedBlocks drops unchanged and keeps added/removed/changed
 
+#### errorMessage (TE-002 trust boundary)
+
+- surfaces the ProblemDetails detail when present
+- falls back to PREVIEW_FAILED when the body has no detail
+- falls back to PREVIEW_FAILED when the body is not JSON
+
 #### inferSelection
 
 - round-trips a positief selection
@@ -275,6 +291,13 @@ classes.
 - rejects a missing count field
 - rejects a malformed history entry
 
+#### parseRevealed (TE-002 trust boundary)
+
+- accepts a well-formed body
+- rejects a bigNummer sent as a number
+- rejects a missing bigNummer field
+- rejects null and non-object bodies
+
 #### passagesForBesluit
 
 - positief = shared intro + the positief passage, no negatief/reason passages
@@ -283,6 +306,12 @@ classes.
 - preserves library order (= reading order)
 - never offers non-kern passages
 
+#### proefbriefErrorMessage (TE-002 trust boundary)
+
+- surfaces the ProblemDetails detail when present
+- falls back to PROEFBRIEF_FAILED when the body has no detail
+- falls back to PROEFBRIEF_FAILED when the body is not JSON
+
 #### redenenFor
 
 - derives reason checkboxes (code + label) from the negatief reason passages
@@ -635,6 +664,29 @@ classes.
 - applies the pure update on dispatch
 - dispatch from inside an effect does not self-loop
 
+#### currentRole (dev mechanism)
+
+- lists the three roles
+- reads a valid ?role= from the URL and persists it for the tab
+- falls back to drafter when nothing is set or the value is invalid
+
+#### currentRole (dev mechanism) › outside isDevMode() (production build)
+
+- ignores a ?role= in the URL and returns the default
+- never touches sessionStorage
+- ignores a role already sitting in sessionStorage from a prior dev session
+
+#### currentSubject (dev mechanism)
+
+- reads a ?subject= from the URL and persists it for the tab
+- returns undefined when nothing has ever been set
+
+#### currentSubject (dev mechanism) › outside isDevMode() (production build)
+
+- ignores a ?subject= (a BSN) in the URL and returns undefined
+- never writes the BSN into sessionStorage
+- ignores a subject already sitting in sessionStorage from a prior dev session
+
 #### delete flow (optimistic, revertible)
 
 - UploadDeleteRequested keeps the documentId for revert

libs/shared/src/infrastructure/role.spec.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { currentRole, ROLES } from './role';
+
+const setUrl = (search: string) => history.pushState({}, '', search || '/');
+
+// isDevMode() reads the `ngDevMode` global the Angular CLI defines away in a
+// production build. There is no ambient type for it in app code, so this is
+// accessed through an untyped bag rather than a `declare const`.
+const globals = globalThis as Record<string, unknown>;
+const originalNgDevMode = globals['ngDevMode'];
+const setDevMode = (on: boolean) => {
+  globals['ngDevMode'] = on;
+};
+
+describe('currentRole (dev mechanism)', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    setUrl('/');
+    setDevMode(true);
+  });
+  afterEach(() => {
+    globals['ngDevMode'] = originalNgDevMode;
+  });
+
+  it('lists the three roles', () => {
+    expect(ROLES).toEqual(['drafter', 'approver', 'admin']);
+  });
+
+  it('reads a valid ?role= from the URL and persists it for the tab', () => {
+    setUrl('?role=admin');
+    expect(currentRole()).toBe('admin');
+    setUrl('/'); // navigation drops the query param — value stays sticky
+    expect(currentRole()).toBe('admin');
+  });
+
+  it('falls back to drafter when nothing is set or the value is invalid', () => {
+    expect(currentRole()).toBe('drafter');
+    setUrl('?role=nonsense');
+    expect(currentRole()).toBe('drafter');
+  });
+
+  // BIO-012: the three hand-written `fetch` adapters call this function directly,
+  // bypassing `roleInterceptor`'s own isDevMode()-gated registration — so the gate
+  // has to hold here, not just at the interceptor, or `?role=` keeps working in a
+  // production build through that side door.
+  describe('outside isDevMode() (production build)', () => {
+    beforeEach(() => setDevMode(false));
+
+    it('ignores a ?role= in the URL and returns the default', () => {
+      setUrl('?role=admin');
+      expect(currentRole()).toBe('drafter');
+    });
+
+    it('never touches sessionStorage', () => {
+      setUrl('?role=admin');
+      currentRole();
+      expect(sessionStorage.getItem('dev-role')).toBeNull();
+    });
+
+    it('ignores a role already sitting in sessionStorage from a prior dev session', () => {
+      sessionStorage.setItem('dev-role', 'admin');
+      expect(currentRole()).toBe('drafter');
+    });
+  });
+});

libs/shared/src/infrastructure/role.ts

@@ -1,3 +1,4 @@
+import { isDevMode } from '@angular/core';
 import { Role } from '@shared/domain/role';
 
 /**
@@ -14,13 +15,22 @@ import { Role } from '@shared/domain/role';
  * don't carry it), which would silently revert an admin to drafter mid-session and
  * 403 the admin endpoints. So a `?role=` seen in the URL is remembered for the tab;
  * later requests use the remembered value. Set `?role=drafter` (or a fresh tab) to
- * reset. Dev-only — the interceptor itself is only wired under `isDevMode()`.
+ * reset.
+ *
+ * **Gated here, not only at the interceptor (BIO-012):** the `roleInterceptor` that
+ * consumes this for `HttpClient` traffic is only registered under `isDevMode()`
+ * (`app.config.ts`), but `brief`'s three hand-written `fetch` adapters call this
+ * function directly, bypassing that interceptor entirely. Reading `?role=` and
+ * writing it to `sessionStorage` is therefore gated in the function itself — outside
+ * `isDevMode()` the query param is never read, `sessionStorage` is never touched, and
+ * the fixed default (`drafter`, the least-privileged role) is returned every time.
  */
 const STORAGE_KEY = 'dev-role';
 export const ROLES: readonly Role[] = ['drafter', 'approver', 'admin'];
 const isRole = (v: string | null): v is Role => !!v && ROLES.includes(v as Role);
 
 export function currentRole(): Role {
+  if (!isDevMode()) return 'drafter';
   const fromUrl = new URLSearchParams(window.location.search).get('role');
   if (isRole(fromUrl)) {
     sessionStorage.setItem(STORAGE_KEY, fromUrl);

libs/shared/src/infrastructure/subject.spec.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { currentSubject } from './subject';
+
+const setUrl = (search: string) => history.pushState({}, '', search || '/');
+
+// isDevMode() reads the `ngDevMode` global the Angular CLI defines away in a
+// production build. There is no ambient type for it in app code, so this is
+// accessed through an untyped bag rather than a `declare const`.
+const globals = globalThis as Record<string, unknown>;
+const originalNgDevMode = globals['ngDevMode'];
+const setDevMode = (on: boolean) => {
+  globals['ngDevMode'] = on;
+};
+
+describe('currentSubject (dev mechanism)', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    setUrl('/');
+    setDevMode(true);
+  });
+  afterEach(() => {
+    globals['ngDevMode'] = originalNgDevMode;
+  });
+
+  it('reads a ?subject= from the URL and persists it for the tab', () => {
+    setUrl('?subject=111222333');
+    expect(currentSubject()).toBe('111222333');
+    setUrl('/'); // navigation drops the query param — value stays sticky
+    expect(currentSubject()).toBe('111222333');
+  });
+
+  it('returns undefined when nothing has ever been set', () => {
+    expect(currentSubject()).toBeUndefined();
+  });
+
+  // BIO-012: a BSN is art. 9 GDPR special-category data. Prior to this fix this
+  // function wrote it into sessionStorage on any navigation, in any build.
+  describe('outside isDevMode() (production build)', () => {
+    beforeEach(() => setDevMode(false));
+
+    it('ignores a ?subject= (a BSN) in the URL and returns undefined', () => {
+      setUrl('?subject=111222333');
+      expect(currentSubject()).toBeUndefined();
+    });
+
+    it('never writes the BSN into sessionStorage', () => {
+      setUrl('?subject=111222333');
+      currentSubject();
+      expect(sessionStorage.getItem('dev-subject')).toBeNull();
+    });
+
+    it('ignores a subject already sitting in sessionStorage from a prior dev session', () => {
+      sessionStorage.setItem('dev-subject', '111222333');
+      expect(currentSubject()).toBeUndefined();
+    });
+  });
+});

libs/shared/src/infrastructure/subject.ts

@@ -1,3 +1,5 @@
+import { isDevMode } from '@angular/core';
+
 /**
  * Dev-only role stand-in's sibling (the reading MECHANISM for `X-Subject`; see
  * `role.ts`'s own doc comment for the twin `X-Role` mechanism this mirrors). This
@@ -13,6 +15,13 @@
  * hand-written `fetch`, which bypasses every `HttpInterceptorFn` — the same reason
  * that adapter already sets `X-Role` explicitly via `currentRole()`).
  *
+ * **Gated here, not only at the interceptor (BIO-012):** `subjectInterceptor` is only
+ * registered under `isDevMode()`, but `letter-preview.adapter.ts` calls this function
+ * directly and bypasses that interceptor. The value read here is a **BSN** — a GDPR
+ * special-category identifier — so outside `isDevMode()` the query param is never
+ * read and `sessionStorage` is never written; `undefined` is returned unconditionally,
+ * exactly as if no `?subject=` had ever been seen.
+ *
  * `undefined` (not a default BSN) when nothing has ever set `?subject=`: unlike
  * `currentRole()` (a closed enum with a sensible default), there is no "default
  * subject" to fall back to here — omitting the header entirely lets the backend's
@@ -21,6 +30,7 @@
 const STORAGE_KEY = 'dev-subject';
 
 export function currentSubject(): string | undefined {
+  if (!isDevMode()) return undefined;
   const fromUrl = new URLSearchParams(window.location.search).get('subject');
   if (fromUrl) {
     sessionStorage.setItem(STORAGE_KEY, fromUrl);