create-astram-app 0.4.0 → 0.6.0

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

@@ -16,6 +16,9 @@
  *                 via `GET access/role-grants` + `GET permission-catalog`, BOTH gated
  *                 `role:read` — "managing/reading grants IS role administration")
  *   - Audit     → `identity:role:read`     (audit.controller.ts `GET audit`)
+ *   - Service accounts → `identity:service_account:read`
+ *                 (service-account.controller.ts `GET service-accounts`; create/edit are
+ *                 service_account:create|update, keys are service_account:manage_keys)
  *   - Cross-tenant → `identity:role:read`  (cross-tenant-grant.controller.ts `GET
  *                 cross-tenant-grants` / `GET .../inbox` / `GET .../offerable-types`,
  *                 all gated `role:read` — reading/managing cross-tenant grants IS role
@@ -24,6 +27,7 @@
  * caller may reach (no admin-only list route backs them).
  */
 import {
+  Bot,
   Building2,
   Handshake,
   History,
@@ -82,6 +86,14 @@ export const NAV_SECTIONS = [
         matchPrefix: true,
         gate: 'identity:role:read',
       },
+      {
+        icon: Bot,
+        label: 'Service accounts',
+        path: '/service-accounts',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:service_account:read',
+      },
       {
         icon: Handshake,
         label: 'Cross-tenant',
@@ -104,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

package/template/server/eslint.config.mjs

@@ -0,0 +1,194 @@
+// ESLint flat config for an Astram consumer app.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// THE PHYSICAL WALL — backstop (do not remove).
+//
+// The Astram paved road is the ONE way features touch data: inject the framework's
+// RecordEngine (from @astram/engine) and go through the pipe (permission gate +
+// audit are mandatory, cross-tenant isolation is enforced). A feature must NEVER
+// reach the database directly — a raw mariadb/typeorm pool, a DataSource, a
+// QueryRunner, or a repository `.save()`/`.query()` skips the security layer
+// entirely (this is exactly how astram-org's ORS got bypassed 165 times).
+//
+// The PRIMARY wall is structural: the framework never hands feature scope a pool
+// (EngineModule seals it). THIS lint rule is the BACKSTOP: it fails the build if any
+// app file under `src/**` imports a raw DB symbol or calls a raw DB method, so an
+// off-road attempt is a red build, not a silent success. Only the composition root
+// (`src/app.module.ts`, `src/main.ts`) and tests (`*.spec.ts`) are exempt: they wire the
+// framework (e.g. `createIdentityAuthzPool()` for ShieldModule.forRoot) and never hold
+// feature logic. Keep raw-DB wiring there; a `src/lib/db.ts` helper is linted like a feature.
+// `scripts/` (dev runner, guide sync) is build tooling that never ships in `dist/` or runs
+// in the request path, so it is not walled.
+//
+// Some framework packages also export their internal adapters for composition and tests
+// (`createIdentityAuthzPool`, `MariaDbUnitOfWork`, …). Those are banned by NAME below, so an
+// import from the package root is caught, not only a deep `dist/` path.
+//
+// If you hit this rule because the pipe can't do what you need: STOP. Do NOT work
+// around it. Record the gap in `.astram/guide/gaps.md` and raise it with the
+// framework — the capability must be added to @astram/engine (the gap-flag loop).
+// ─────────────────────────────────────────────────────────────────────────────
+
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+/** Raw DB packages a feature must never import directly. */
+const FORBIDDEN_DB_IMPORTS = [
+  {
+    name: 'mariadb',
+    message: 'Wall: features never open a DB pool — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'mysql',
+    message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'mysql2',
+    message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+  },
+  { name: 'typeorm', message: 'Wall: no ORM in features — use the RecordEngine (@astram/engine).' },
+  {
+    name: '@nestjs/typeorm',
+    message: 'Wall: no ORM in features — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'pg',
+    message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: 'knex',
+    message: 'Wall: no query builder in features — use the RecordEngine (@astram/engine).',
+  },
+];
+
+/** Driver/ORM SUBPATHS (`paths` above matches exact specifiers only). */
+const FORBIDDEN_DB_SUBPATHS = {
+  group: [
+    'mariadb/*',
+    'mysql/*',
+    'mysql2/*',
+    'typeorm/*',
+    '@nestjs/typeorm/*',
+    'pg/*',
+    'pg-*',
+    'knex/*',
+  ],
+  message: 'Wall: features never open a DB driver — use the RecordEngine (@astram/engine).',
+};
+
+/**
+ * Named imports that hand a feature raw DB access even from an ALLOWED package.
+ * `SHIELD_DB_POOL` is exported from `@astram/guard` (a package a feature legitimately
+ * imports for other reasons), so it must be blocked by NAME on that path — the engine
+ * owns the pool; feature scope must never import the pool token. The same goes for the
+ * composition-only factories/adapters of `@astram/identity` and `@astram/engine`.
+ */
+const FORBIDDEN_DB_NAMED_FROM = [
+  {
+    name: '@astram/guard',
+    importNames: ['SHIELD_DB_POOL'],
+    message:
+      'Wall: the DB pool is sealed inside the engine — features use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: '@astram/identity',
+    importNames: ['createIdentityAuthzPool'],
+    message:
+      'Wall: createIdentityAuthzPool is a raw pool for app.module.ts wiring only — features use the RecordEngine (@astram/engine).',
+  },
+  {
+    name: '@astram/engine',
+    importNames: ['MariaDbUnitOfWork', 'MariaDbAuditSink', 'RecordEngineImpl', 'TableRegistry'],
+    message:
+      'Wall: engine internals (unit of work, audit sink, impl, registry) bypass the gate and audit — inject RECORD_ENGINE / RecordsService instead.',
+  },
+];
+
+/** Every name above, for the syntax ban that also catches `ns.X`, `require(…).X`, `(await import(…)).X`. */
+const FORBIDDEN_FRAMEWORK_NAMES = FORBIDDEN_DB_NAMED_FROM.flatMap((e) => e.importNames);
+
+/** Driver specifiers for dynamic `import()` / `require()` (static imports use the lists above). */
+const DRIVER_SPECIFIER = '/^(mariadb|mysql2?|pg|typeorm|knex|@nestjs.typeorm)(\\W|$)/';
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+  // ── The wall: all app code except the composition root and tests ──────────
+  {
+    files: ['src/**/*.{ts,mts,cts}'],
+    ignores: ['src/app.module.ts', 'src/main.ts', '**/*.spec.ts'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [...FORBIDDEN_DB_IMPORTS, ...FORBIDDEN_DB_NAMED_FROM],
+          patterns: [
+            FORBIDDEN_DB_SUBPATHS,
+            {
+              group: ['**/adapters/mariadb-*', '@astram/*/dist/**', '@astram/*/src/**'],
+              message:
+                'Wall: framework internals (pool/uow/audit adapters, deep dist/src paths) are off-limits — features use the RecordEngine facade only.',
+            },
+          ],
+        },
+      ],
+      // Block raw query-runner / repository calls even if a pool were obtained.
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: "CallExpression[callee.property.name='createQueryRunner']",
+          message: 'Wall: no QueryRunner in features — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='getRepository']",
+          message:
+            'Wall: no repository access in features — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='createPool']",
+          message: 'Wall: features never create a DB pool — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='query']",
+          message: 'Wall: no raw .query() in app code — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: "CallExpression[callee.property.name='getConnection']",
+          message:
+            'Wall: no raw .getConnection() in app code — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: `ImportExpression[source.value=${DRIVER_SPECIFIER}]`,
+          message: 'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
+        },
+        {
+          selector: `CallExpression[callee.name='require'][arguments.0.value=${DRIVER_SPECIFIER}]`,
+          message: 'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
+        },
+        // The banned framework names however they are reached: `ns.SHIELD_DB_POOL`,
+        // `require('@astram/guard').SHIELD_DB_POOL`, `(await import('@astram/engine')).TableRegistry`.
+        // (A named import is already reported by no-restricted-imports, so it is skipped here.)
+        ...FORBIDDEN_FRAMEWORK_NAMES.map((name) => ({
+          selector: `Identifier[name='${name}']:not(ImportSpecifier > Identifier)`,
+          message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
+        })),
+        // …and reached by STRING: `ns['SHIELD_DB_POOL']`, ns[`TableRegistry`],
+        // `const { ['MariaDbUnitOfWork']: x } = ns`. (Import sources are other strings, so the
+        // module specifiers themselves never match.)
+        ...FORBIDDEN_FRAMEWORK_NAMES.flatMap((name) => [
+          {
+            selector: `Literal[value='${name}']`,
+            message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
+          },
+          {
+            selector: `TemplateLiteral[expressions.length=0] > TemplateElement[value.cooked='${name}']`,
+            message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
+          },
+        ]),
+      ],
+    },
+  },
+);

package/template/server/package.json

@@ -14,27 +14,27 @@
     "migration:run": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate",
     "migration:status": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate:status",
     "migration:revert": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate:revert",
-    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint \"src/**/*.{ts,mts,cts}\" \"test/**/*.ts\"",
     "guide:sync": "node scripts/sync-astram-guide.mjs",
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "^1.2.0",
-    "@astram/engine": "^0.2.0",
-    "@astram/guard": "^0.6.0",
-    "@astram/guide": "^0.1.0",
-    "@astram/identity": "^0.3.1",
-    "@astram/migrate": "^0.2.0",
+    "@astram/core": "^1.4.0",
+    "@astram/engine": "^0.4.0",
+    "@astram/guard": "^0.8.0",
+    "@astram/guide": "^0.2.0",
+    "@astram/identity": "^0.5.0",
+    "@astram/migrate": "^0.3.0",
     "@astram/sdk": "^0.2.0",
-    "@nestjs/common": "^11.0.0",
-    "@nestjs/core": "^11.0.0",
-    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/common": "^11.2.7",
+    "@nestjs/core": "^11.2.7",
+    "@nestjs/platform-express": "^11.2.7",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
-    "@nestjs/testing": "^11.0.0",
+    "@nestjs/testing": "^11.2.7",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "@types/supertest": "^6.0.2",

package/template/server/scripts/dev.mjs

@@ -10,6 +10,12 @@
  * hot-reload AND correct DI. Same compiler as the production build, no extra deps.
  *
  * `.env` is loaded by the node child via --env-file-if-exists.
+ *
+ * NODE_ENV: the child runs with NODE_ENV=development unless your shell already set it.
+ * `npm run dev` is a dev box by definition, and @astram/guard keys dev-only defaults
+ * off the RAW NODE_ENV (e.g. with `auth: true` and no `emailSender`, the dev email
+ * logger that prints reset links is used ONLY under development/test; an unset
+ * NODE_ENV fails boot). `npm start` does NOT set it — production must configure a sender.
  */
 
 import { spawn } from 'node:child_process';
@@ -20,7 +26,13 @@ mkdirSync('dist', { recursive: true });
 // 1) tsc in watch mode → dist/ (emits decorator metadata; the whole point).
 const tsc = spawn(
   process.execPath,
-  [new URL('../node_modules/typescript/bin/tsc', import.meta.url).pathname, '-w', '-p', 'tsconfig.build.json', '--preserveWatchOutput'],
+  [
+    new URL('../node_modules/typescript/bin/tsc', import.meta.url).pathname,
+    '-w',
+    '-p',
+    'tsconfig.build.json',
+    '--preserveWatchOutput',
+  ],
   { stdio: 'inherit' },
 );
 
@@ -33,11 +45,10 @@ const startNode = () => {
     return;
   }
   started = true;
-  const node = spawn(
-    process.execPath,
-    ['--env-file-if-exists=.env', '--watch', 'dist/main.js'],
-    { stdio: 'inherit' },
-  );
+  const node = spawn(process.execPath, ['--env-file-if-exists=.env', '--watch', 'dist/main.js'], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_ENV: process.env.NODE_ENV || 'development' },
+  });
   node.on('exit', (code) => {
     tsc.kill();
     process.exit(code ?? 0);