create-astram-app 0.11.0 → 0.12.0

package/template/frontend/src/viteConfig.test.mjs

@@ -0,0 +1,63 @@
+// viteConfig.test.mjs — the Vite config's own plugins must not return anything from
+// `configureServer` / `configurePreviewServer`. Vite treats a returned function as a POST hook and
+// calls it later with no arguments, so an arrow body like `(s) => s.middlewares.use(fn)` (which
+// returns the connect app) crashed `npm run dev` with "Cannot read properties of undefined
+// (reading 'url')". Middleware is installed during the call; the return value must be undefined.
+//
+//   node --test src/viteConfig.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import config from '../vite.config.js';
+
+/** A fake dev/preview server whose `middlewares.use` returns the app, as connect does. */
+function fakeServer() {
+  const used = [];
+  const middlewares = {
+    use(fn) {
+      used.push(fn);
+      return middlewares;
+    },
+  };
+  return { server: { middlewares, httpServer: null, config: {} }, used };
+}
+
+const ours = (config.plugins ?? [])
+  .flat(Infinity)
+  .filter((p) => p && typeof p.name === 'string' && p.name.startsWith('astram-'));
+
+describe('vite.config.js plugins', () => {
+  test('the astram plugins are present', () => {
+    assert.ok(ours.some((p) => p.name === 'astram-confirm-email-no-referrer'));
+  });
+
+  for (const hook of ['configureServer', 'configurePreviewServer']) {
+    test(`every astram plugin's ${hook} installs its middleware and returns undefined`, async () => {
+      for (const plugin of ours) {
+        const fn = plugin[hook];
+        if (fn === undefined) continue;
+        const { server, used } = fakeServer();
+        const handler = typeof fn === 'function' ? fn : fn.handler;
+        const out = await handler.call(plugin, server);
+        assert.equal(out, undefined, `${plugin.name}.${hook} must not return a post hook`);
+        assert.ok(used.length > 0, `${plugin.name}.${hook} installed its middleware`);
+      }
+    });
+  }
+
+  test('the confirm-email middleware sets no-referrer only on /confirm-email', () => {
+    const plugin = ours.find((p) => p.name === 'astram-confirm-email-no-referrer');
+    const { server, used } = fakeServer();
+    plugin.configureServer(server);
+    const run = (url) => {
+      const headers = {};
+      let nexted = false;
+      used[0]({ url }, { setHeader: (k, v) => (headers[k] = v) }, () => (nexted = true));
+      return { headers, nexted };
+    };
+    assert.deepEqual(run('/confirm-email?x=1'), {
+      headers: { 'Referrer-Policy': 'no-referrer' },
+      nexted: true,
+    });
+    assert.deepEqual(run('/dashboard'), { headers: {}, nexted: true });
+  });
+});

package/template/frontend/vite/captchaCsp.js

@@ -0,0 +1,99 @@
+/**
+ * CAPTCHA origins for the static Content-Security-Policy `<meta>` in index.html (R7.6, D-10).
+ *
+ * The CSP is fixed when the frontend is built, so the build takes `VITE_CAPTCHA_PROVIDER` (the
+ * same value as the server's `CAPTCHA_PROVIDER`, or unset) and adds that ONE provider's fixed
+ * origins to `script-src`, `frame-src` and `connect-src`. Never `'unsafe-inline'`. The site key
+ * is not baked in: the login page reads it from `GET /auth/login-options` at run time, and shows
+ * a "misconfigured" notice if the server's provider differs from this build's.
+ *
+ *   unset / ''      index.html is left byte-identical
+ *   unknown value   the build (and dev server) fails with a message
+ *
+ * Origins, from the providers' CSP guidance:
+ *   Turnstile  https://developers.cloudflare.com/turnstile/reference/content-security-policy/
+ *              (script-src, frame-src; the widget also connects to challenges.cloudflare.com)
+ *   reCAPTCHA  https://developers.google.com/recaptcha/docs/faq (CSP answer)
+ */
+
+const TURNSTILE = 'https://challenges.cloudflare.com';
+const RECAPTCHA = {
+  'script-src': ['https://www.google.com/recaptcha/', 'https://www.gstatic.com/recaptcha/'],
+  'frame-src': ['https://www.google.com/recaptcha/', 'https://recaptcha.google.com/recaptcha/'],
+  'connect-src': ['https://www.google.com/recaptcha/'],
+};
+
+/** Provider → directive → origins to add. Values match the server's `CAPTCHA_PROVIDER`. */
+export const CAPTCHA_CSP_ORIGINS = Object.freeze({
+  turnstile: {
+    'script-src': [TURNSTILE],
+    'frame-src': [TURNSTILE],
+    'connect-src': [TURNSTILE],
+  },
+  'recaptcha-v3': RECAPTCHA,
+  'recaptcha-v2': RECAPTCHA,
+});
+
+export const CAPTCHA_PROVIDERS = Object.freeze(Object.keys(CAPTCHA_CSP_ORIGINS));
+
+const CSP_META = /(<meta\s+http-equiv="Content-Security-Policy"\s+content=")([^"]*)(")/;
+
+/** Throws on a value that is not a known provider; returns null for unset/empty. */
+function checkProvider(provider) {
+  if (provider === undefined || provider === null || provider === '') return null;
+  if (!Object.hasOwn(CAPTCHA_CSP_ORIGINS, provider)) {
+    throw new Error(
+      `VITE_CAPTCHA_PROVIDER="${provider}" is not supported; use one of ` +
+        `${CAPTCHA_PROVIDERS.join(', ')}, or leave it unset for no CAPTCHA.`,
+    );
+  }
+  return provider;
+}
+
+/**
+ * Add `provider`'s origins to the CSP `<meta>` in `html`. Unset provider ⇒ `html` unchanged.
+ * A directive the policy lacks (`frame-src` today) is added as `'self'` plus the origins, which
+ * keeps its old fallback (`default-src 'self'`) for everything else.
+ */
+export function extendCsp(html, provider) {
+  const known = checkProvider(provider);
+  if (known === null) return html;
+  const match = CSP_META.exec(html);
+  if (!match) return html;
+
+  const additions = CAPTCHA_CSP_ORIGINS[known];
+  const directives = match[2]
+    .split(';')
+    .map((d) => d.trim())
+    .filter(Boolean);
+  for (const [name, origins] of Object.entries(additions)) {
+    const index = directives.findIndex((d) => d.split(/\s+/)[0] === name);
+    if (index === -1) {
+      const after = directives.findIndex((d) => d.split(/\s+/)[0] === 'connect-src');
+      const entry = [name, "'self'", ...origins].join(' ');
+      directives.splice(after === -1 ? directives.length : after + 1, 0, entry);
+    } else {
+      const existing = directives[index].split(/\s+/);
+      const missing = origins.filter((o) => !existing.includes(o));
+      directives[index] = [...existing, ...missing].join(' ');
+    }
+  }
+  return html.replace(CSP_META, `$1${directives.join('; ')}$3`);
+}
+
+/**
+ * Vite plugin. Reads `VITE_CAPTCHA_PROVIDER` from the resolved config env (`.env*` files and the
+ * process environment), so the value is checked once at startup and an unknown one fails the build.
+ */
+export function captchaCsp() {
+  let provider = null;
+  return {
+    name: 'astram-captcha-csp',
+    configResolved(config) {
+      provider = checkProvider(config.env?.VITE_CAPTCHA_PROVIDER);
+    },
+    transformIndexHtml(html) {
+      return extendCsp(html, provider);
+    },
+  };
+}

package/template/frontend/vite.config.js

@@ -2,6 +2,7 @@ import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
 import { fileURLToPath, URL } from 'node:url';
+import { captchaCsp } from './vite/captchaCsp.js';
 
 /**
  * Dev-server only: relax the Content-Security-Policy in index.html just enough for Vite.
@@ -34,22 +35,32 @@ function confirmEmailNoReferrer() {
     }
     next();
   };
+  // Block bodies on purpose: Vite treats a function RETURNED from these hooks as a post hook and
+  // calls it later with no arguments, and `middlewares.use()` returns the connect app (a function).
   return {
     name: 'astram-confirm-email-no-referrer',
-    configureServer: (server) => server.middlewares.use(setHeader),
-    configurePreviewServer: (server) => server.middlewares.use(setHeader),
+    configureServer(server) {
+      server.middlewares.use(setHeader);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(setHeader);
+    },
   };
 }
 
 /**
  * __APP_NAME__ frontend — Vite config (shadcn/ui + Tailwind v4).
  *
+ * `captchaCsp()` adds the CAPTCHA provider's origins to the CSP <meta> when the build sets
+ * `VITE_CAPTCHA_PROVIDER` (same value as the server's `CAPTCHA_PROVIDER`; unset ⇒ index.html
+ * unchanged, unknown ⇒ the build fails). See vite/captchaCsp.js.
+ *
  * `/api` is proxied to the framework server (default :3000), stripping the `/api`
  * prefix so the browser calls same-origin `/api/auth/login` while the server sees
  * `/auth/login`. `@` aliases `src/` (the shadcn import convention).
  */
 export default defineConfig({
-  plugins: [react(), tailwindcss(), devCsp(), confirmEmailNoReferrer()],
+  plugins: [react(), tailwindcss(), captchaCsp(), devCsp(), confirmEmailNoReferrer()],
   resolve: {
     alias: {
       '@': fileURLToPath(new URL('./src', import.meta.url)),

package/template/server/_env.example

@@ -172,6 +172,31 @@ NODE_ENV=development
 # INVITE_LINK_TTL_HOURS=72
 # INVITE_RATE_PER_ADMIN=30
 
+# --- OPTIONAL: CAPTCHA on sign-in (Cloudflare Turnstile or Google reCAPTCHA) ---
+# Read only when src/app.module.ts passes ShieldModule.forRoot({ captcha: 'env' }); a missing or
+# invalid value then fails boot. One of turnstile | recaptcha-v3 | recaptcha-v2.
+# The frontend build needs the SAME value in frontend/.env as VITE_CAPTCHA_PROVIDER (it adds the
+# provider's origins to the static CSP); `create-astram-app --captcha <provider>` writes both.
+# If the two differ, the login page shows a "misconfigured" notice and loads no widget.
+# CAPTCHA_PROVIDER=turnstile
+# Public site key from the provider's dashboard (served to the login page at run time).
+# CAPTCHA_SITE_KEY=
+# Secret key: outside development/test it MUST be a `secret-ref:` reference (a literal fails boot).
+# CAPTCHA_SECRET=secret-ref:captcha/secret
+# Hostnames a solved challenge must come from, comma-separated (required outside development/test).
+# CAPTCHA_EXPECTED_HOSTNAMES=app.example.com
+# adaptive (challenge after CAPTCHA_THRESHOLD failed attempts) | always.
+# CAPTCHA_MODE=adaptive
+# CAPTCHA_THRESHOLD=3
+# reCAPTCHA v3 only: lowest accepted score (0.0-1.0).
+# CAPTCHA_MIN_SCORE=0.5
+# Provider outage: closed (refuse; default) | open (allow, audited; limits and lockout still apply).
+# CAPTCHA_FAIL_MODE=closed
+# Verification call timeout in ms (default 5000, max 10000).
+# CAPTCHA_TIMEOUT_MS=5000
+# Endpoints that ask for a challenge, comma-separated (default: all three).
+# CAPTCHA_ENDPOINTS=login,forgot_password,reset_password
+
 # --- OPTIONAL: organisation bootstrap (`npm run bootstrap:org`; needs IdentityFeatureModule wired) ---
 # Platform-root user uuids, comma-separated, lower-case canonical form. Read by rootIdsFromEnv()
 # in src/app.module.ts (pass it to BOTH forRoot calls); bootstrap:org prints the uuid of each root.

package/template/server/package.json

@@ -21,13 +21,13 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "1.9.0",
-    "@astram/engine": "0.10.1",
-    "@astram/guard": "0.18.0",
+    "@astram/core": "1.11.0",
+    "@astram/engine": "0.11.0",
+    "@astram/guard": "0.20.0",
     "@astram/guide": "^0.2.8",
-    "@astram/identity": "0.15.0",
-    "@astram/messaging": "^0.1.1",
-    "@astram/migrate": "0.6.1",
+    "@astram/identity": "0.17.0",
+    "@astram/messaging": "^0.1.3",
+    "@astram/migrate": "0.7.1",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",
@@ -48,5 +48,8 @@
     "typescript-eslint": "^8.0.0",
     "unplugin-swc": "^1.5.1",
     "vitest": "^2.1.8"
+  },
+  "overrides": {
+    "vitest": "$vitest"
   }
 }

package/template/server/src/app.module.ts

@@ -32,7 +32,10 @@ import { DemoController } from './health/demo.controller';
  * The framework ships a complete Auth surface you can turn on WITHOUT writing any
  * auth code. It is OFF by default so this app boots with NO `.env` at all (pure
  * enforcement). To enable it:
- *   1. Change `ShieldModule.forRoot()` below to `ShieldModule.forRoot({ auth: true })`.
+ *   1. Change `ShieldModule.forRoot()` below to
+ *      `ShieldModule.forRoot({ auth: true, logoutRequiresProof: true })`. This app's frontend
+ *      sends its refresh and access tokens on logout, so the server can require that proof
+ *      (an unproven `POST /auth/logout` then ends nothing).
  *   2. Provide the DB/Redis/HMAC config in `.env` (see the AUTH block in
  *      `.env.example`) — auth needs a real MariaDB + Redis and a refresh HMAC key.
  *   3. Create a user in the `shield_identity.identity_credential` table.
@@ -47,6 +50,14 @@ import { DemoController } from './health/demo.controller';
  *      Admins can then invite users (`POST /identity/users/:uuid/invite`, the Users page
  *      Invite button); `IdentityFeatureModule.forRoot({ invite: { returnLinkToAdmin: true } })`
  *      also shows the one-time link to the admin once.
+ *   5. Optional sign-in options (all off by default; see CAPABILITIES.md):
+ *        ShieldModule.forRoot({ auth: true, logoutRequiresProof: true,
+ *          signInWith: ['email', 'username'], // one field takes the email or the login name
+ *          captcha: 'env' })                  // CAPTCHA_* in `.env.example`, and the same
+ *                                             // provider as VITE_CAPTCHA_PROVIDER in frontend
+ *      Login names are set by an admin (Users page) or by `bootstrap:org`, never by the user.
+ *      Mandatory 2FA is not an option here: with IdentityFeatureModule wired, admins set it
+ *      per tenant, role or permission on the Security page (`/identity/security-policies`).
  * You then get framework-owned `POST /auth/{login,mfa,refresh,logout}` for free —
  * no controllers to write. (Leaving `auth` off keeps the zero-config enforcement
  * boot; turning it on requires the config above, by design — fail-closed.)
@@ -63,7 +74,7 @@ import { DemoController } from './health/demo.controller';
  *        import { identityAuthActionKeys, identityControlPlaneKeys,
  *                 IdentityFeatureModule } from '@astram/identity';
  *        imports: [
- *          ShieldModule.forRoot({ auth: true, rootIds: rootIdsFromEnv(),
+ *          ShieldModule.forRoot({ auth: true, logoutRequiresProof: true, rootIds: rootIdsFromEnv(),
  *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys }),
  *          // mounts /identity/{companies,users,roles,…}
  *          IdentityFeatureModule.forRoot({ rootIds: rootIdsFromEnv() }),
@@ -89,8 +100,8 @@ import { DemoController } from './health/demo.controller';
  *        const extraObjects = [Note];
  *        const { actionKeys, controlPlaneKeys } = buildIdentityAuthKeys(extraObjects);
  *        imports: [
- *          ShieldModule.forRoot({ auth: true, identityActionKeys: actionKeys,
- *            identityControlPlaneKeys: controlPlaneKeys }),
+ *          ShieldModule.forRoot({ auth: true, logoutRequiresProof: true,
+ *            identityActionKeys: actionKeys, identityControlPlaneKeys: controlPlaneKeys }),
  *          IdentityFeatureModule.forRoot({ extraObjects }),
  *        ],
  *   The frontend ships the matching pages/widget (RecordPoliciesPage, ShareDialog)
@@ -101,8 +112,8 @@ import { DemoController } from './health/demo.controller';
   // admin console (incl. the guided rule-builder + owner shares), use (see the OPTIONAL
   // blocks above for the full form + the extraObjects note for your OWN owned types):
   //   imports: [
-  //     ShieldModule.forRoot({ auth: true, rootIds: rootIdsFromEnv(), identityActionKeys,
-  //       identityControlPlaneKeys }),
+  //     ShieldModule.forRoot({ auth: true, logoutRequiresProof: true, rootIds: rootIdsFromEnv(),
+  //       identityActionKeys, identityControlPlaneKeys }),
   //     IdentityFeatureModule.forRoot({ rootIds: rootIdsFromEnv() /*, extraObjects: [YourType] */ }),
   //   ],
   imports: [ShieldModule.forRoot()],