create-astram-app 0.5.0 → 0.7.0

package/template/frontend/src/platform/httpClient.js

@@ -3,6 +3,11 @@
  * contract. Uses the browser `fetch`, same-origin `/api` (proxied by Vite to the
  * server's /auth/* routes). A mobile app provides its OWN adapter (RN fetch + its
  * base URL) implementing the same shape; the shared logic is identical for both.
+ *
+ * This is the RAW transport: it does not refresh tokens. AuthContext wraps it with
+ * @astram/frontend-core's `createRefreshingHttp` (single-flight refresh on a 401, one retry,
+ * cross-tab lock) and hands only the wrapped client to the services and the shield
+ * transport. Use the raw client directly only for the refresh call itself.
  */
 
 const BASE = '/api';
@@ -17,6 +22,14 @@ async function toResponse(res) {
   return { ok: res.ok, status: res.status, data };
 }
 
+/**
+ * Forward the caller's abort signal to fetch (a stale search, or the refresh timeout in
+ * `createRefreshingHttp`). An abort rejects fetch, which every method maps to status 0.
+ */
+function withSignal(opts) {
+  return opts && opts.signal ? { signal: opts.signal } : {};
+}
+
 /**
  * The app-wide enforced-re-enroll interceptor. When a request is rejected with a 403
  * whose body is EXACTLY `{ error: 'reenrollment_required' }` (the server's re-enroll
@@ -60,6 +73,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -75,6 +89,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -90,6 +105,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -105,6 +121,7 @@ export function createWebHttpClient(config = {}) {
             ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
           },
           body: JSON.stringify(body),
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {
@@ -115,6 +132,7 @@ export function createWebHttpClient(config = {}) {
       try {
         const res = await fetch(`${BASE}${path}`, {
           headers: opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {},
+          ...withSignal(opts),
         });
         return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
       } catch {

package/template/frontend/src/platform/httpClient.test.mjs

@@ -0,0 +1,60 @@
+// httpClient.test.mjs — the web HttpClient forwards `opts.signal` to fetch on every
+// method (Phase 8 #6), so the refresh timeout in @astram/frontend-core can abort a hung
+// /auth/refresh, and an aborted request maps to the transport-failure shape.
+//
+//   node --test src/platform/httpClient.test.mjs
+//
+// `fetch` is stubbed on globalThis, so this runs under plain Node.
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWebHttpClient } from './httpClient.js';
+
+let realFetch;
+let seen;
+
+beforeEach(() => {
+  realFetch = globalThis.fetch;
+  seen = [];
+  globalThis.fetch = async (url, init = {}) => {
+    seen.push({ url, init });
+    if (init.signal?.aborted) {
+      throw Object.assign(new Error('aborted'), { name: 'AbortError' });
+    }
+    return { ok: true, status: 200, json: async () => ({ ok: true }) };
+  };
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('createWebHttpClient — abort signal forwarding', () => {
+  const methods = [
+    ['get', (c, o) => c.get('/x', o)],
+    ['post', (c, o) => c.post('/x', {}, o)],
+    ['patch', (c, o) => c.patch('/x', {}, o)],
+    ['put', (c, o) => c.put('/x', {}, o)],
+    ['delete', (c, o) => c.delete('/x', {}, o)],
+  ];
+
+  for (const [name, call] of methods) {
+    test(`${name} passes opts.signal to fetch`, async () => {
+      const ctl = new AbortController();
+      const r = await call(createWebHttpClient(), { signal: ctl.signal });
+      assert.equal(r.status, 200);
+      assert.equal(seen[0].init.signal, ctl.signal);
+    });
+
+    test(`${name} with an aborted signal resolves { ok: false, status: 0 } (never throws)`, async () => {
+      const ctl = new AbortController();
+      ctl.abort();
+      const r = await call(createWebHttpClient(), { signal: ctl.signal });
+      assert.deepEqual(r, { ok: false, status: 0, data: null });
+    });
+
+    test(`${name} without a signal sends no signal`, async () => {
+      await call(createWebHttpClient(), undefined);
+      assert.equal('signal' in seen[0].init, false);
+    });
+  }
+});

package/template/frontend/src/platform/sessionStore.js

@@ -2,28 +2,70 @@
  * The WEB session store — the platform half of @astram/frontend-core's SessionStore contract,
  * backed by localStorage. A mobile app provides its own (AsyncStorage). The shared
  * session helpers never touch storage directly; the app injects this.
+ *
+ * localStorage is shared by every tab of the app, so a token rotation or logout in one tab
+ * is visible to the others: `createRefreshingHttp` re-reads it inside its cross-tab lock,
+ * and `subscribe` turns the browser's `storage` event (fired in the OTHER tabs) into a
+ * session-change callback for AuthContext.
+ *
+ * Token storage note (D11): the refresh token sits in localStorage, readable by any script
+ * on the origin, which is why index.html ships a strict Content-Security-Policy. Moving the
+ * refresh token to an HttpOnly cookie is a planned follow-up ADR.
  */
 
-const KEY = 'app-session';
+export const SESSION_STORAGE_KEY = 'app-session';
+
+/**
+ * @param {{ storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>,
+ *           events?: Pick<EventTarget, 'addEventListener' | 'removeEventListener'> }} [deps]
+ *   Injected for tests; default to the browser's `localStorage` and `window`.
+ * @returns {import('@astram/frontend-core').SessionStore & {
+ *   subscribe: (listener: (state: object | null) => void) => () => void }}
+ */
+export function createWebSessionStore(deps = {}) {
+  const storage = () => deps.storage ?? globalThis.localStorage;
+  const events = () => deps.events ?? globalThis.window;
+
+  const load = () => {
+    try {
+      const raw = storage().getItem(SESSION_STORAGE_KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch {
+      return null;
+    }
+  };
 
-/** @returns {import('@astram/frontend-core').SessionStore} */
-export function createWebSessionStore() {
   return {
-    load() {
-      try {
-        const raw = localStorage.getItem(KEY);
-        return raw ? JSON.parse(raw) : null;
-      } catch {
-        return null;
-      }
-    },
+    load,
     save(state) {
       try {
-        if (state) localStorage.setItem(KEY, JSON.stringify(state));
-        else localStorage.removeItem(KEY);
+        if (state) storage().setItem(SESSION_STORAGE_KEY, JSON.stringify(state));
+        else storage().removeItem(SESSION_STORAGE_KEY);
       } catch {
         /* storage unavailable — session stays in memory only */
       }
     },
+    /**
+     * Call `listener(state | null)` when ANOTHER tab changes the session (rotation, logout,
+     * a different sign-in). Returns an unsubscribe function.
+     */
+    subscribe(listener) {
+      const target = events();
+      if (!target || typeof target.addEventListener !== 'function') return () => {};
+      const onStorage = (event) => {
+        // `key === null` means the other tab called localStorage.clear().
+        if (event.key !== SESSION_STORAGE_KEY && event.key !== null) return;
+        let area;
+        try {
+          area = storage();
+        } catch {
+          return;
+        }
+        if (event.storageArea && event.storageArea !== area) return;
+        listener(load());
+      };
+      target.addEventListener('storage', onStorage);
+      return () => target.removeEventListener('storage', onStorage);
+    },
   };
 }

package/template/frontend/src/platform/sessionStore.test.mjs

@@ -0,0 +1,89 @@
+// sessionStore.test.mjs — the web session store's cross-tab half (#12): a logout or a
+// token rotation in one tab must reach the others through the `storage` event.
+//
+//   node --test src/platform/sessionStore.test.mjs
+//
+// Storage and the event target are injected, so this runs under plain Node.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWebSessionStore, SESSION_STORAGE_KEY } from './sessionStore.js';
+
+function memoryStorage() {
+  const m = new Map();
+  return {
+    getItem: (k) => (m.has(k) ? m.get(k) : null),
+    setItem: (k, v) => m.set(k, String(v)),
+    removeItem: (k) => m.delete(k),
+  };
+}
+
+function eventTarget() {
+  const listeners = new Set();
+  return {
+    addEventListener: (type, fn) => type === 'storage' && listeners.add(fn),
+    removeEventListener: (type, fn) => type === 'storage' && listeners.delete(fn),
+    fire: (event) => [...listeners].forEach((fn) => fn(event)),
+    get size() {
+      return listeners.size;
+    },
+  };
+}
+
+const fake = (label) => `fake-${label}`;
+const STATE = {
+  session: { sessionId: 's1' },
+  tokens: { accessToken: fake('a2'), refreshToken: fake('r2') },
+};
+
+describe('createWebSessionStore.subscribe — cross-tab session changes', () => {
+  test('another tab rotated the tokens → listener gets the new state', () => {
+    const storage = memoryStorage();
+    const events = eventTarget();
+    const store = createWebSessionStore({ storage, events });
+    const seen = [];
+    store.subscribe((s) => seen.push(s));
+
+    storage.setItem(SESSION_STORAGE_KEY, JSON.stringify(STATE)); // the other tab's write
+    events.fire({ key: SESSION_STORAGE_KEY, storageArea: storage });
+
+    assert.deepEqual(seen, [STATE]);
+  });
+
+  test('another tab logged out (key removed, or storage cleared) → listener gets null', () => {
+    const storage = memoryStorage();
+    const events = eventTarget();
+    const store = createWebSessionStore({ storage, events });
+    const seen = [];
+    store.subscribe((s) => seen.push(s));
+
+    events.fire({ key: SESSION_STORAGE_KEY, storageArea: storage });
+    events.fire({ key: null, storageArea: storage }); // localStorage.clear()
+
+    assert.deepEqual(seen, [null, null]);
+  });
+
+  test('unrelated keys and other storage areas are ignored; unsubscribe detaches', () => {
+    const storage = memoryStorage();
+    const events = eventTarget();
+    const store = createWebSessionStore({ storage, events });
+    const seen = [];
+    const off = store.subscribe((s) => seen.push(s));
+
+    events.fire({ key: 'app-return-path', storageArea: storage });
+    events.fire({ key: SESSION_STORAGE_KEY, storageArea: memoryStorage() }); // sessionStorage
+    assert.deepEqual(seen, []);
+
+    off();
+    assert.equal(events.size, 0);
+  });
+
+  test('load/save round-trip through the injected storage', () => {
+    const storage = memoryStorage();
+    const store = createWebSessionStore({ storage, events: eventTarget() });
+    assert.equal(store.load(), null);
+    store.save(STATE);
+    assert.deepEqual(store.load(), STATE);
+    store.save(null);
+    assert.equal(store.load(), null);
+  });
+});

package/template/frontend/src/platform/shieldTransport.js

@@ -22,6 +22,12 @@
  *     deny-everything projection past a token refresh. Treated as TRANSIENT (throw), so
  *     the engine holds its last-good/empty projection and the NEXT session-established
  *     fetch (post-refresh/re-login) supersedes it, rather than baking in a deny.
+ *     AuthContext hands this transport the REFRESHING http client (`createRefreshingHttp`,
+ *     #12), so an expired access token is refreshed and the call retried BEFORE a status
+ *     reaches here: a 401 seen here means the refresh itself failed (the session is being
+ *     cleared → login) or the session was replaced, and a refresh outage arrives as a 503.
+ *     Never build this transport over the raw client: a 401 would then be retried forever
+ *     as "transient" instead of refreshing.
  *   - a real 403 (or any other non-5xx !ok)  → TERMINAL deny → return an EMPTY projection
  *     `{ principalId:'', facts:[], projectedAt: Date.now() }` (deny-all).
  *   - 200 with a body                        → return `r.data` (the projection) AS-IS.

package/template/frontend/src/platform/shieldTransport.test.mjs

@@ -13,6 +13,7 @@ import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
 import { createWebShieldTransport } from './shieldTransport.js';
 import { TransportUnavailableError } from '@astram/sdk';
+import { createRefreshingHttp } from '@astram/frontend-core';
 
 /** A mock `http` whose `.get` resolves exactly the given `{ok, status, data}` result —
  *  mirrors `createWebHttpClient`'s contract (never throws). */
@@ -50,7 +51,11 @@ describe('shieldTransport.fetchProjection — HTTP -> outcome classification', (
 
   test('a 503 (our own loadCoarseGrants outage mapping) -> throws TransportUnavailableError', async () => {
     const transport = createWebShieldTransport({
-      http: mockHttp({ ok: false, status: 503, data: { message: 'permission facts store unavailable' } }),
+      http: mockHttp({
+        ok: false,
+        status: 503,
+        data: { message: 'permission facts store unavailable' },
+      }),
       getToken: () => 'tok',
     });
     await assert.rejects(
@@ -148,11 +153,10 @@ describe('shieldTransport — deferred capabilities stay fail-closed stubs (slic
     });
     assert.deepEqual(result, { challengeId: 'c1', satisfied: false });
   });
-
 });
 
 describe('shieldTransport.currentVersion — ADR-0011 bump-driven refetch probe (Phase E slice 2)', () => {
-  test('is implemented (opts this transport into the SDK\'s isVersionAware duck-type)', () => {
+  test("is implemented (opts this transport into the SDK's isVersionAware duck-type)", () => {
     const transport = createWebShieldTransport({ http: mockHttp({}), getToken: () => 'tok' });
     assert.equal(typeof transport.currentVersion, 'function');
   });
@@ -186,7 +190,11 @@ describe('shieldTransport.currentVersion — ADR-0011 bump-driven refetch probe
 
   test('a 503 (permission-version store outage) -> resolves +Infinity, does NOT throw', async () => {
     const transport = createWebShieldTransport({
-      http: mockHttp({ ok: false, status: 503, data: { message: 'permission version store unavailable' } }),
+      http: mockHttp({
+        ok: false,
+        status: 503,
+        data: { message: 'permission version store unavailable' },
+      }),
       getToken: () => 'tok',
     });
     const version = await transport.currentVersion();
@@ -236,10 +244,81 @@ describe('shieldTransport.currentVersion — ADR-0011 bump-driven refetch probe
     // SDK's client.ts calls currentVersion() completely unguarded (no try/catch at
     // its call site), so a throw here would escape getAuthFacts uncaught.
     const transport = createWebShieldTransport({
-      http: { get: async () => { throw new Error('boom'); } },
+      http: {
+        get: async () => {
+          throw new Error('boom');
+        },
+      },
       getToken: () => 'tok',
     });
     const version = await transport.currentVersion();
     assert.equal(version, Number.POSITIVE_INFINITY);
   });
 });
+
+describe('shieldTransport over the refreshing http client (#12 wiring, as in AuthContext)', () => {
+  const fake = (label) => `fake-${label}`;
+  const OLD = fake('old-access');
+  const NEW = fake('new-access');
+
+  function setup(refreshResult) {
+    let stored = {
+      session: { sessionId: 's1' },
+      tokens: { accessToken: OLD, refreshToken: fake('rt') },
+    };
+    const store = { load: () => stored, save: (s) => (stored = s) };
+    const raw = {
+      get: async (path, opts) =>
+        opts?.bearerToken === NEW
+          ? { ok: true, status: 200, data: { principalId: 'p1', facts: [], projectedAt: 1 } }
+          : { ok: false, status: 401, data: null },
+    };
+    let expired = 0;
+    let current = OLD;
+    const http = createRefreshingHttp({
+      http: raw,
+      store,
+      locks: null,
+      refresh: async () => refreshResult,
+      onRefreshed: (next) => (current = next.tokens.accessToken),
+      onSessionExpired: () => (expired += 1),
+    });
+    const transport = createWebShieldTransport({ http, getToken: () => current });
+    return { transport, store: () => stored, expired: () => expired };
+  }
+
+  test('an expired token is refreshed and the projection fetched — never a transient 401', async () => {
+    const t = setup({
+      ok: true,
+      session: { sessionId: 's1' },
+      tokens: { accessToken: NEW, refreshToken: fake('rt2') },
+    });
+    const projection = await t.transport.fetchProjection('p1');
+    assert.deepEqual(projection, { principalId: 'p1', facts: [], projectedAt: 1 });
+    assert.equal(t.store().tokens.accessToken, NEW);
+  });
+
+  test('a rejected refresh clears the session and surfaces as transient (no cached deny)', async () => {
+    const t = setup({ ok: false, status: 401, error: 'Session expired. Please sign in again.' });
+    await assert.rejects(
+      () => t.transport.fetchProjection('p1'),
+      (e) => e instanceof TransportUnavailableError,
+    );
+    assert.equal(t.store(), null);
+    assert.equal(t.expired(), 1);
+  });
+
+  test('a refresh outage (503) keeps the session and surfaces as transient', async () => {
+    const t = setup({
+      ok: false,
+      status: 503,
+      error: 'Authentication is temporarily unavailable. Please try again.',
+    });
+    await assert.rejects(
+      () => t.transport.fetchProjection('p1'),
+      (e) => e instanceof TransportUnavailableError,
+    );
+    assert.equal(t.store().tokens.accessToken, OLD);
+    assert.equal(t.expired(), 0);
+  });
+});

package/template/frontend/src/shell/AppShell.jsx

@@ -6,16 +6,7 @@
 import { useCallback, useEffect, useState } from 'react';
 import { useLocation, useNavigate } from 'react-router-dom';
 import { saveReturnPath } from '@/platform/returnPathStore';
-import {
-  Bell,
-  HelpCircle,
-  LogOut,
-  Menu,
-  PanelLeft,
-  Search,
-  Settings,
-  X,
-} from 'lucide-react';
+import { Bell, HelpCircle, LogOut, Menu, PanelLeft, Search, Settings, X } from 'lucide-react';
 import { useAuth } from '@/auth/AuthContext';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
@@ -103,7 +94,11 @@ export default function AppShell({ children, title: _title, section: _section })
   const companyName = profile?.company?.name || '';
   // Prefer the part before "@" for a cleaner label + initials.
   const shortName = displayName.includes('@') ? displayName.split('@')[0] : displayName;
-  const initials = shortName.replace(/[^a-zA-Z0-9]/g, '').slice(0, 2).toUpperCase() || 'U';
+  const initials =
+    shortName
+      .replace(/[^a-zA-Z0-9]/g, '')
+      .slice(0, 2)
+      .toUpperCase() || 'U';
 
   return (
     <div className="flex h-screen overflow-hidden bg-background">
@@ -221,7 +216,10 @@ export default function AppShell({ children, title: _title, section: _section })
                   <ThemeToggle />
                 </div>
                 <DropdownMenuSeparator />
-                <DropdownMenuItem onClick={onLogout} className="text-destructive focus:text-destructive">
+                <DropdownMenuItem
+                  onClick={onLogout}
+                  className="text-destructive focus:text-destructive"
+                >
                   <LogOut className="mr-2 size-4" />
                   Sign out
                 </DropdownMenuItem>

package/template/frontend/src/shell/Sidebar.jsx

@@ -21,9 +21,17 @@ import { NAV_SECTIONS } from './nav';
 function initialsOf(name) {
   if (!name) return 'U';
   const clean = name.includes('@') ? name.split('@')[0] : name;
-  const parts = clean.trim().split(/[\s._-]+/).filter(Boolean);
+  const parts = clean
+    .trim()
+    .split(/[\s._-]+/)
+    .filter(Boolean);
   const letters = parts.length >= 2 ? parts[0][0] + parts[1][0] : clean.slice(0, 2);
-  return letters.replace(/[^a-zA-Z0-9]/g, '').slice(0, 2).toUpperCase() || 'U';
+  return (
+    letters
+      .replace(/[^a-zA-Z0-9]/g, '')
+      .slice(0, 2)
+      .toUpperCase() || 'U'
+  );
 }
 
 /**
@@ -114,7 +122,11 @@ function BrandTile({ collapsed }) {
         // Theme-adaptive logo: the COLOR logo on the light rail, the WHITE variant on
         // the dark rail (the sidebar surface now follows the theme).
         <>
-          <img src={branding.logo.light} alt={branding.appName} className="h-7 w-auto dark:hidden" />
+          <img
+            src={branding.logo.light}
+            alt={branding.appName}
+            className="h-7 w-auto dark:hidden"
+          />
           <img
             src={branding.logo.dark}
             alt={branding.appName}

package/template/frontend/src/shell/nav.js

@@ -116,8 +116,6 @@ export const NAV_SECTIONS = [
     label: 'Settings',
     // `/account` redirects to `/account/profile`; `matchPrefix` keeps the nav item
     // highlighted across ALL /account/* sub-tabs (profile / password / 2fa).
-    items: [
-      { icon: UserCog, label: 'Account', path: '/account', badge: null, matchPrefix: true },
-    ],
+    items: [{ icon: UserCog, label: 'Account', path: '/account', badge: null, matchPrefix: true }],
   },
 ];

package/template/frontend/vite.config.js

@@ -3,6 +3,24 @@ import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
 import { fileURLToPath, URL } from 'node:url';
 
+/**
+ * Dev-server only: relax the Content-Security-Policy in index.html just enough for Vite.
+ * `@vitejs/plugin-react` injects an inline React-refresh preamble script, and HMR talks over
+ * a websocket. `vite build` / `vite preview` never run this, so the built app ships the
+ * strict policy unchanged.
+ */
+function devCsp() {
+  return {
+    name: 'astram-dev-csp',
+    apply: 'serve',
+    transformIndexHtml(html) {
+      return html
+        .replace("script-src 'self'", "script-src 'self' 'unsafe-inline'")
+        .replace("connect-src 'self'", "connect-src 'self' ws: wss:");
+    },
+  };
+}
+
 /**
  * __APP_NAME__ frontend — Vite config (shadcn/ui + Tailwind v4).
  *
@@ -11,7 +29,7 @@ import { fileURLToPath, URL } from 'node:url';
  * `/auth/login`. `@` aliases `src/` (the shadcn import convention).
  */
 export default defineConfig({
-  plugins: [react(), tailwindcss()],
+  plugins: [react(), tailwindcss(), devCsp()],
   resolve: {
     alias: {
       '@': fileURLToPath(new URL('./src', import.meta.url)),

package/template/server/_env.example

@@ -7,7 +7,20 @@
 # HTTP port the app listens on (default: 3000).
 PORT=3000
 
-# Runtime environment: development | production | test (default: development).
+# Reverse-proxy hop count in front of this app (read by src/main.ts → Express
+# `trust proxy`). 0 = no proxy (app exposed directly); 1 = behind the Astram Traefik.
+# Must be the REAL count: too high lets clients spoof their IP via X-Forwarded-For.
+# Unset → `trust proxy` stays unset and the framework's per-IP limiters (login,
+# forgot-password, reset-password) are OFF (boot warning); per-account limits still apply.
+# TRUST_PROXY=1
+
+# Runtime environment: development | production | test.
+# `npm run dev` sets NODE_ENV=development itself when your shell has not set it.
+# With auth on and no `emailSender`, the framework uses its dev email logger (prints
+# password-reset links to stdout) ONLY when NODE_ENV is exactly development or test;
+# any other value, INCLUDING unset, fails boot until you pass
+# ShieldModule.forRoot({ auth: true, emailSender: <your sender> }) or
+# `emailSender: 'disabled'` (no reset emails; forgot-password still answers 204).
 NODE_ENV=development
 
 # --- ADR-0018 connection-pool budget (all optional; framework defaults apply) ---
@@ -38,7 +51,15 @@ NODE_ENV=development
 #
 # Redis + refresh-token secret:
 # REDIS_URL=redis://127.0.0.1:6379
+# Redis command timeout (ms). A Redis outage then fails requests closed within this bound instead
+# of hanging (default 2000).
+# REDIS_COMMAND_TIMEOUT_MS=2000
 # REFRESH_HMAC_KEY=change-me-to-a-long-random-secret   # REQUIRED when auth is on
+#
+# Per-client-IP login failure limit (default 50 failures per 15 min). Enforced ONLY when
+# TRUST_PROXY (above) is set, so the client IP is real rather than the proxy's.
+# LOGIN_IP_MAX_FAILURES=50
+# LOGIN_IP_WINDOW_MS=900000
 
 # --- Migrations (optional; @astram/identity's migrations run automatically) ---
 # APP_MIGRATION_DIR=migrations         # your app's own migrations, run after identity's