create-astram-app 0.9.4 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced NestJS server (deny-by-default, built-in auth/identity to switch on) and, with --with-frontend, a React admin/auth UI, over the immutable @astram/* framework packages.",
   "type": "module",

package/template/README.md

@@ -72,7 +72,9 @@ needs no database or Redis. To turn on login, sessions, MFA and the identity adm
 `server/src/app.module.ts`: `ShieldModule.forRoot({ auth: true, emailSender, rootIds,
 identityActionKeys, identityControlPlaneKeys })` plus
 `IdentityFeatureModule.forRoot({ rootIds, extraObjects })`, which builds the record
-authorization `ShieldModule` decides with (pass no `recordAuthorization`). The framework provides
+authorization `ShieldModule` decides with (pass no `recordAuthorization`). With your own object
+types in `extraObjects`, build the two key lists from the same array with
+`buildIdentityAuthKeys(extraObjects)` so their keys are in `/auth/facts`. The framework provides
 the credential store, MFA, session handling and the decision authority; you write none of them.
 
 ### Before you deploy with auth on

package/template/frontend/package.json

@@ -9,7 +9,7 @@
     "build": "vite build",
     "preview": "vite preview",
     "lint": "eslint \"src/**/*.{js,jsx}\"",
-    "test": "node --test src/**/*.test.mjs"
+    "test": "node scripts/run-tests.mjs"
   },
   "dependencies": {
     "@astram/frontend-core": "^0.6.1",

package/template/frontend/scripts/run-tests.mjs

@@ -0,0 +1,34 @@
+// run-tests.mjs — `npm test`: run every `*.test.mjs` under src/ with Node's built-in runner.
+//
+// An unquoted `node --test src/**/*.test.mjs` is expanded by the shell, and sh has no `**`, so
+// it silently skipped nested folders (src/pages/*/). A quoted glob needs Node >= 21 and a bare
+// directory argument is not portable across Node versions, so the files are listed here and
+// passed explicitly: works the same on Node 20 and later.
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+
+function findTests(dir) {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...findTests(path));
+    else if (entry.isFile() && entry.name.endsWith('.test.mjs')) found.push(path);
+  }
+  return found;
+}
+
+const files = findTests(join(root, 'src'))
+  .map((f) => relative(root, f))
+  .sort();
+
+if (files.length === 0) {
+  console.error('run-tests: no *.test.mjs files found under src/');
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, ['--test', ...files], { cwd: root, stdio: 'inherit' });
+process.exit(result.status ?? 1);

package/template/frontend/src/pages/access/AccessForm.jsx

@@ -22,9 +22,13 @@ import { Input } from '@/components/ui/input';
 import { Checkbox } from '@/components/ui/checkbox';
 import { SearchableSelect } from '@/components/ui/searchable-select';
 import CollapsibleGroup from '@/components/access/CollapsibleGroup';
+import { extraActionsByType, matrixActions } from './accessMatrix';
 
 const ACTIONS = ['read', 'create', 'update', 'delete'];
 
+// Column header for an action key: `manage_keys` → `manage keys` (cells carry the catalog label).
+const actionHeading = (a) => a.replace(/_/g, ' ');
+
 // Object → group mapping. An unmapped typeKey falls into "Other" (fail-safe).
 const GROUPS = [
   {
@@ -86,6 +90,14 @@ export default function AccessForm() {
   const keyExists = useCallback((key) => Boolean(labelOf[key]), [labelOf]);
   const cellKey = useCallback((t, a) => `${moduleName}:${t}:${a}`, [moduleName]);
 
+  // Declared extra (non-CRUD) actions per type, catalog order. A type without extras keeps
+  // exactly the four CRUD cells.
+  const extrasByType = useMemo(() => extraActionsByType(catalog), [catalog]);
+  const actionsOf = useCallback(
+    (t) => [...ACTIONS, ...(extrasByType.get(t) ?? [])],
+    [extrasByType],
+  );
+
   const keyHeld = useCallback((key, set) => {
     if (set.has(key)) return true;
     const [mod, type] = key.split(':');
@@ -180,7 +192,7 @@ export default function AccessForm() {
 
   const toggleGroupAll = (group) => {
     const groupKeys = group.types
-      .flatMap((t) => ACTIONS.map((a) => cellKey(t, a)))
+      .flatMap((t) => actionsOf(t).map((a) => cellKey(t, a)))
       .filter(keyExists);
     const allHeld = groupKeys.every((k) => keyHeld(k, working));
     setWorking((prev) => {
@@ -219,14 +231,14 @@ export default function AccessForm() {
   const { permCount, objectCount } = useMemo(() => {
     const held = new Set();
     for (const t of typeKeys) {
-      for (const a of ACTIONS) {
+      for (const a of actionsOf(t)) {
         const k = cellKey(t, a);
         if (keyExists(k) && keyHeld(k, working)) held.add(k);
       }
     }
     const types = new Set([...held].map((k) => k.split(':')[1]));
     return { permCount: held.size, objectCount: types.size };
-  }, [working, typeKeys, cellKey, keyExists, keyHeld]);
+  }, [working, typeKeys, actionsOf, cellKey, keyExists, keyHeld]);
 
   // The applied presets (derived) — shown in the footer. Multiple can be applied.
   const appliedPresetLabels = bundles.filter(isBundleApplied).map((b) => b.label);
@@ -358,8 +370,11 @@ export default function AccessForm() {
               const visibleTypes = group.types.filter(matchesSearch);
               if (visibleTypes.length === 0) return null;
               const groupCells = group.types
-                .flatMap((t) => ACTIONS.map((a) => cellKey(t, a)))
+                .flatMap((t) => actionsOf(t).map((a) => cellKey(t, a)))
                 .filter(keyExists);
+              // Extra-action columns this group needs (union over its types); empty for a
+              // CRUD-only group, which then renders exactly as before.
+              const columns = [...ACTIONS, ...matrixActions(catalog, group.types)];
               const heldCount = groupCells.filter((k) => keyHeld(k, working)).length;
               return (
                 <CollapsibleGroup
@@ -396,9 +411,9 @@ export default function AccessForm() {
                       <thead>
                         <tr className="text-left text-xs uppercase tracking-wide text-muted-foreground">
                           <th className="py-1 pr-3 font-medium">Object</th>
-                          {ACTIONS.map((a) => (
+                          {columns.map((a) => (
                             <th key={a} className="px-2 py-1 text-center font-medium capitalize">
-                              {a}
+                              {actionHeading(a)}
                             </th>
                           ))}
                         </tr>
@@ -407,7 +422,7 @@ export default function AccessForm() {
                         {visibleTypes.map((t) => (
                           <tr key={t} className="border-t border-border">
                             <td className="py-1.5 pr-3 text-foreground">{t}</td>
-                            {ACTIONS.map((a) => {
+                            {columns.map((a) => {
                               const key = cellKey(t, a);
                               const exists = keyExists(key);
                               const covered = keyHeld(key, working) && !working.has(key);

package/template/frontend/src/pages/access/accessMatrix.js

@@ -0,0 +1,55 @@
+/**
+ * accessMatrix — the pure (no React, no I/O) logic behind the role access matrix's extra,
+ * non-CRUD action columns (custom-object-actions Phase 5). An object type may declare its own
+ * actions (`activate`, `approve`, `manage_keys`, …); the permission catalog lists one row per
+ * `<module>:<type>:<action>` key. These helpers work out which extra actions each type shows,
+ * in catalog order. Kept separate so it is unit-tested with `node --test` (accessMatrix.test.mjs).
+ *
+ * UX only: the server catalog and the grant ceiling stay the authority. Wildcard rows
+ * (`<module>:*`, `<module>:<type>:*`) are never columns; their coverage is the form's `keyHeld`.
+ */
+
+/** The CRUD actions the matrix always renders as its fixed columns. */
+export const CRUD_ACTIONS = ['read', 'create', 'update', 'delete'];
+
+const CRUD = new Set(CRUD_ACTIONS);
+
+const isExtraRow = (row) =>
+  Boolean(row) &&
+  typeof row.typeKey === 'string' &&
+  typeof row.action === 'string' &&
+  row.typeKey !== '' &&
+  row.action !== '' &&
+  row.typeKey !== '*' &&
+  row.action !== '*' &&
+  !CRUD.has(row.action);
+
+/**
+ * typeKey → its extra (non-CRUD) actions, in first-seen catalog order, no duplicates.
+ * Types with only CRUD rows are absent. Malformed rows are skipped; the input is not mutated.
+ */
+export function extraActionsByType(catalog) {
+  const out = new Map();
+  for (const row of Array.isArray(catalog) ? catalog : []) {
+    if (!isExtraRow(row)) continue;
+    const list = out.get(row.typeKey) ?? [];
+    if (!list.includes(row.action)) list.push(row.action);
+    out.set(row.typeKey, list);
+  }
+  return out;
+}
+
+/**
+ * Union of extra actions across `types` (all types when omitted), first-seen catalog order,
+ * no duplicates — the extra columns a group of types needs.
+ */
+export function matrixActions(catalog, types) {
+  const scope = Array.isArray(types) ? new Set(types) : null;
+  const out = [];
+  for (const row of Array.isArray(catalog) ? catalog : []) {
+    if (!isExtraRow(row)) continue;
+    if (scope && !scope.has(row.typeKey)) continue;
+    if (!out.includes(row.action)) out.push(row.action);
+  }
+  return out;
+}

package/template/frontend/src/pages/access/accessMatrix.test.mjs

@@ -0,0 +1,168 @@
+// accessMatrix.test.mjs — custom-object-actions Phase 5: the role access matrix's pure logic
+// (which extra, non-CRUD action columns each type shows). No React/DOM; runs under Node's
+// built-in runner with zero dependencies:
+//
+//   node --test src/pages/access/accessMatrix.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { extraActionsByType, matrixActions } from './accessMatrix.js';
+
+const row = (typeKey, action, label = `${typeKey} ${action}`) => ({
+  key: `app:${typeKey}:${action}`,
+  label,
+  module: 'app',
+  typeKey,
+  action,
+});
+
+// extraActionsByType may return a Map or a plain object; read either.
+const extrasOf = (res, typeKey) => {
+  const v = res instanceof Map ? res.get(typeKey) : res?.[typeKey];
+  return v === undefined ? [] : [...v];
+};
+const typesWithExtras = (res) =>
+  (res instanceof Map ? [...res.keys()] : Object.keys(res)).filter(
+    (t) => extrasOf(res, t).length > 0,
+  );
+
+describe('extraActionsByType', () => {
+  test('no extras (CRUD only) => no type has extras', () => {
+    const catalog = ['read', 'create', 'update', 'delete'].map((a) => row('invoice', a));
+    assert.deepEqual(typesWithExtras(extraActionsByType(catalog)), []);
+  });
+
+  test('empty, null and undefined catalogs => nothing, no throw', () => {
+    for (const c of [[], null, undefined]) {
+      assert.deepEqual(typesWithExtras(extraActionsByType(c)), []);
+      assert.deepEqual([...matrixActions(c)], []);
+    }
+  });
+
+  test('extras per type, CRUD never listed as an extra', () => {
+    const catalog = [
+      row('invoice', 'read'),
+      row('invoice', 'create'),
+      row('invoice', 'update'),
+      row('invoice', 'delete'),
+      row('invoice', 'activate'),
+      row('invoice', 'approve'),
+      row('contact', 'read'),
+    ];
+    const res = extraActionsByType(catalog);
+    assert.deepEqual(extrasOf(res, 'invoice'), ['activate', 'approve']);
+    assert.deepEqual(extrasOf(res, 'contact'), []);
+  });
+
+  test('crudActions:false type (only its own actions in the catalog) shows only those', () => {
+    const catalog = [row('workflow', 'activate'), row('workflow', 'publish')];
+    const res = extraActionsByType(catalog);
+    assert.deepEqual(extrasOf(res, 'workflow'), ['activate', 'publish']);
+  });
+
+  test('extras keep catalog order (stable, not alphabetical)', () => {
+    const catalog = [row('t', 'zeta'), row('t', 'alpha'), row('t', 'mid')];
+    assert.deepEqual(extrasOf(extraActionsByType(catalog), 't'), ['zeta', 'alpha', 'mid']);
+  });
+
+  test('stable: same input twice gives the same output; input is not mutated', () => {
+    const catalog = [row('t', 'b'), row('u', 'a'), row('t', 'a')];
+    const snapshot = JSON.stringify(catalog);
+    const a = extraActionsByType(catalog);
+    const b = extraActionsByType(catalog);
+    assert.deepEqual(extrasOf(a, 't'), extrasOf(b, 't'));
+    assert.deepEqual(extrasOf(a, 't'), ['b', 'a']);
+    assert.equal(JSON.stringify(catalog), snapshot);
+  });
+
+  test('duplicate rows do not duplicate an extra', () => {
+    const catalog = [row('t', 'x'), row('t', 'x')];
+    assert.deepEqual(extrasOf(extraActionsByType(catalog), 't'), ['x']);
+  });
+
+  test('identity extras appear (manage_keys, share/accept/revoke)', () => {
+    const catalog = [
+      { key: 'identity:service_account:read', typeKey: 'service_account', action: 'read' },
+      {
+        key: 'identity:service_account:manage_keys',
+        typeKey: 'service_account',
+        action: 'manage_keys',
+      },
+      { key: 'identity:record_share:share', typeKey: 'record_share', action: 'share' },
+      {
+        key: 'identity:cross_tenant_grant:accept',
+        typeKey: 'cross_tenant_grant',
+        action: 'accept',
+      },
+      {
+        key: 'identity:cross_tenant_grant:revoke',
+        typeKey: 'cross_tenant_grant',
+        action: 'revoke',
+      },
+    ];
+    const res = extraActionsByType(catalog);
+    assert.deepEqual(extrasOf(res, 'service_account'), ['manage_keys']);
+    assert.deepEqual(extrasOf(res, 'record_share'), ['share']);
+    assert.deepEqual(extrasOf(res, 'cross_tenant_grant'), ['accept', 'revoke']);
+  });
+
+  test('wildcard rows are not extra columns (coverage is the form`s keyHeld concern)', () => {
+    const catalog = [
+      { key: 'app:*', typeKey: '*', action: '*' },
+      { key: 'app:invoice:*', typeKey: 'invoice', action: '*' },
+      row('invoice', 'approve'),
+    ];
+    const res = extraActionsByType(catalog);
+    assert.deepEqual(extrasOf(res, 'invoice'), ['approve']);
+    assert.ok(!typesWithExtras(res).includes('*'));
+  });
+
+  test('unknown or missing fields are tolerated and skipped', () => {
+    const catalog = [
+      null,
+      undefined,
+      {},
+      { key: 'app:x:y' },
+      { typeKey: 'x' },
+      { action: 'y' },
+      { typeKey: 7, action: 'y' },
+      { typeKey: 'x', action: null },
+      { ...row('invoice', 'approve'), somethingNew: { nested: true } },
+    ];
+    const res = extraActionsByType(catalog);
+    assert.deepEqual(extrasOf(res, 'invoice'), ['approve']);
+    assert.deepEqual(typesWithExtras(res), ['invoice']);
+  });
+});
+
+describe('matrixActions', () => {
+  const catalog = [
+    row('invoice', 'read'),
+    row('invoice', 'approve'),
+    row('invoice', 'activate'),
+    row('contact', 'read'),
+    row('contact', 'activate'),
+    row('contact', 'archive'),
+    row('workflow', 'publish'),
+  ];
+
+  test('union of extras across all types, first-seen catalog order, no CRUD, no dupes', () => {
+    assert.deepEqual([...matrixActions(catalog)], ['approve', 'activate', 'archive', 'publish']);
+  });
+
+  test('scoped to a group of types', () => {
+    assert.deepEqual([...matrixActions(catalog, ['contact'])], ['activate', 'archive']);
+    assert.deepEqual(
+      [...matrixActions(catalog, ['invoice', 'workflow'])],
+      ['approve', 'activate', 'publish'],
+    );
+  });
+
+  test('group with no extras or unknown types => empty', () => {
+    assert.deepEqual([...matrixActions(catalog, ['nope'])], []);
+    assert.deepEqual([...matrixActions(catalog, [])], []);
+  });
+
+  test('tolerates malformed rows', () => {
+    assert.deepEqual([...matrixActions([null, {}, row('t', 'go')])], ['go']);
+  });
+});

package/template/server/_env.example

@@ -43,6 +43,11 @@ NODE_ENV=development
 # APP_DB_USER=shield_core
 # APP_DB_PASSWORD=change-me
 # APP_DB_NAME=shield_identity
+# TLS to MariaDB: off (default) | on. Production DB accounts are provisioned REQUIRE SSL, so set
+# `on` there (it always verifies the server). APP_DB_TLS_CA = PEM file of your own CA, if any.
+# Migrations read DDL_DB_TLS / DDL_DB_TLS_CA first, then these.
+# APP_DB_TLS=on
+# APP_DB_TLS_CA=/etc/ssl/shield-db-ca.pem
 #
 # Deploy-time DDL account (CREATE/ALTER/DROP — used only by `npm run migration:run`,
 # NEVER by the running server; least-privilege). Host/port/db inherit APP_DB_* above.
@@ -74,6 +79,39 @@ NODE_ENV=development
 # RESET_LINK_BASE_URL=https://app.example.com/reset-password
 # EMAIL_CHANGE_LINK_BASE_URL=https://app.example.com/confirm-email
 
+# --- OPTIONAL: secret references (ADR-0032) ---
+# Any variable above or below may hold `secret-ref:<path>` instead of a value, e.g.
+#   APP_DB_PASSWORD=secret-ref:db/app-password
+#   REFRESH_HMAC_KEY=secret-ref:auth/refresh-hmac-key
+# src/main.ts calls resolveBootSecrets() before AppModule loads and replaces each reference
+# with the secret from the provider below. An unresolvable reference, or a reference with no
+# provider configured, fails boot. Nothing is logged.
+# Provider: none (default; references are refused) | encrypted-file (`vault` is reserved).
+# SECRETS_PROVIDER=encrypted-file
+# Encrypted secrets store, and the secrets DEK wrapped by the KEK.
+# SECRETS_FILE=/etc/astram/secrets.enc.json
+# SECRETS_DEK_FILE=/etc/astram/secrets.dek
+# The 32-byte KEK is a FILE mounted by the platform (mode 0400), never an env value.
+# SECRETS_KEK_FILE=/run/secrets/astram-kek
+
+# --- OPTIONAL: file storage (S3-compatible bucket) ---
+# Read only when src/app.module.ts passes ShieldModule.forRoot({ storage: 'env' }), and even then
+# storage stays OFF while OBJECT_STORAGE_BUCKET is unset (FilesService then answers 501).
+# Used by FileIntake (@astram/guard) and FilesService / GET /files/:uuid (@astram/identity).
+# The bucket is private with SSE-S3; the app checks it at boot and fails if unreachable.
+# Endpoint must be https outside development/test (a loopback host is allowed).
+# OBJECT_STORAGE_ENDPOINT=https://s3.example.com
+# OBJECT_STORAGE_BUCKET=prod-documents
+# OBJECT_STORAGE_REGION=us-east-1
+# Credentials: outside development/test they MUST be `secret-ref:` references (a literal
+# value fails boot).
+# OBJECT_STORAGE_ACCESS_KEY_ID=secret-ref:object-storage/access-key-id
+# OBJECT_STORAGE_SECRET_ACCESS_KEY=secret-ref:object-storage/secret-access-key
+# Server-side encryption: AES256 (SSE-S3, the default and only accepted value).
+# OBJECT_STORAGE_SSE=AES256
+# Upload size cap in bytes (default 10 MiB; above the 50 MiB ceiling fails boot).
+# OBJECT_STORAGE_MAX_BYTES=10485760
+
 # --- Migrations (optional; @astram/identity's migrations run automatically) ---
 # APP_MIGRATION_DIR=migrations         # your app's own migrations, run after identity's
 # APP_MIGRATION_TABLE=schema_migrations

package/template/server/eslint.config.mjs

@@ -30,6 +30,11 @@
 // (`scripts/check-wall.mjs`, part of `npm run lint`) also greps `src/features/**` for any
 // `/internal` or `node_modules/@astram` specifier, independent of this config.
 //
+// FILES: under `src/features/**` the wall also bans `multer`, `@aws-sdk/*`, `minio`, `fs`,
+// `node:fs` (and `fs/promises`) in every import form. Uploads come in through `FileIntake`
+// (@astram/guard) and are stored/read through `FilesService` (@astram/identity), which gate,
+// tenant-scope and audit every file; `lint:wall` greps for the same specifiers.
+//
 // SCOPE: the wall catches ACCIDENTAL use. Deliberate bypass is a CODE-REVIEW matter, not a
 // lint matter — no static rule can stop code that sets out to evade it. Known, by design
 // not linted: indirect calls (`fn.call(pool, …)`, `.apply`, `.bind`, `Reflect.apply`),
@@ -262,11 +267,138 @@ const UUID_INPUTS = [
   },
 ];
 
+/**
+ * File storage (FILE_STORAGE SPEC §11): features never touch the bucket, the multipart parser
+ * or the filesystem directly. Uploads arrive through `FileIntake` (@astram/guard) and are
+ * stored/read through `FilesService` (@astram/identity), which gate, tenant-scope and audit
+ * every access. Banned under `src/features/**` in every import form (static, `export … from`,
+ * `import()`, `require()`, TS `import x = require()`): `multer`, `@aws-sdk/*`, `minio`, `fs`,
+ * `node:fs`, `fs/promises`, `node:fs/promises` (and their subpaths).
+ */
+const STORAGE_SPECIFIER =
+  '/^(multer|minio|(node\\u003A)?fs|@aws-sdk\\u002F[^\\u002F]+)(\\u002F|$)/';
+const STORAGE_BANS = specifierBan(
+  STORAGE_SPECIFIER,
+  'Wall: features never import multer, an S3/MinIO client or fs — take uploads with FileIntake (@astram/guard) and store/read them with FilesService (@astram/identity).',
+  { statics: true },
+);
+
 /** App source files: TypeScript and plain JavaScript in every module flavour. */
 const SRC_FILES = ['src/**/*.{ts,mts,cts,js,mjs,cjs}'];
+const FEATURE_FILES = ['src/features/**/*.{ts,mts,cts,js,mjs,cjs}'];
 const COMPOSITION_ROOT = ['src/app.module.ts', 'src/main.ts'];
 const SPECS = ['**/*.spec.*', '**/*.test.*'];
 
+/** The wall's import options (shared by the src/** and src/features/** blocks). */
+const WALL_IMPORTS = [
+  'error',
+  {
+    paths: [...FORBIDDEN_DB_IMPORTS, ...FORBIDDEN_DB_NAMED_FROM],
+    patterns: [
+      FORBIDDEN_DB_SUBPATHS,
+      INTERNAL_SUBPATHS,
+      COMPOSITION_ROOT_IMPORTS,
+      {
+        // (Deep `@astram/*/dist|src` and `node_modules/` paths: DEEP_PATHS, every import form.)
+        group: ['**/adapters/mariadb-*'],
+        message:
+          'Wall: framework internals (pool/uow/audit adapters) are off-limits — features use the RecordEngine facade only.',
+      },
+    ],
+  },
+];
+
+/**
+ * The wall's syntax selectors. A later flat-config block REPLACES a rule's options for the
+ * files it matches (it does not merge), so the src/features/** block below repeats these and
+ * appends STORAGE_BANS.
+ */
+const WALL_SYNTAX = [
+  // Block raw query-runner / repository calls even if a pool were obtained.
+  {
+    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: `CallExpression > MemberExpression.callee[computed=false][property.name=${MORE_RAW_METHOD_RE}]`,
+    message: RAW_METHOD_MESSAGE,
+  },
+  // The same methods by COMPUTED key: `pool['query']()`, pool[`getConnection`]().
+  {
+    selector: `CallExpression > MemberExpression.callee[computed=true][property.value=${RAW_METHOD_RE}]`,
+    message: RAW_METHOD_MESSAGE,
+  },
+  {
+    selector: `CallExpression > MemberExpression.callee[computed=true] > TemplateLiteral.property[expressions.length=0] > TemplateElement[value.cooked=${RAW_METHOD_RE}]`,
+    message: RAW_METHOD_MESSAGE,
+  },
+  // …and DESTRUCTURED off anything: `const { query } = pool`, `{ ['query']: q } = pool`.
+  {
+    selector: `ObjectPattern > Property[computed=false][key.name=${RAW_METHOD_RE}]`,
+    message: RAW_METHOD_MESSAGE,
+  },
+  {
+    selector: `ObjectPattern > Property[computed=true][key.value=${RAW_METHOD_RE}]`,
+    message: RAW_METHOD_MESSAGE,
+  },
+  {
+    selector: `ObjectPattern > Property[computed=true] > TemplateLiteral.key[expressions.length=0] > TemplateElement[value.cooked=${RAW_METHOD_RE}]`,
+    message: RAW_METHOD_MESSAGE,
+  },
+  ...specifierBan(
+    DRIVER_SPECIFIER,
+    'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
+  ),
+  ...INTERNAL_DYNAMIC,
+  ...DEEP_PATHS,
+  ...NON_STATIC_SPECIFIERS,
+  ...UUID_INPUTS,
+  // 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 from the listed package is already reported by no-restricted-imports,
+  // so plain import specifiers are skipped here; an ALIASED one is reported below, from
+  // any module, because the alias hides the name from every later use.)
+  ...FORBIDDEN_FRAMEWORK_NAMES.flatMap((name) => [
+    {
+      selector: `Identifier[name='${name}']:not(ImportSpecifier > Identifier)`,
+      message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
+    },
+    {
+      selector: `ImportSpecifier[imported.name='${name}'][local.name!='${name}']`,
+      message: `Wall: ${name} is framework-internal DB access (imported under an alias) — 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).`,
+    },
+  ]),
+];
+
 export default tseslint.config(
   js.configs.recommended,
   ...tseslint.configs.recommended,
@@ -278,111 +410,16 @@ export default tseslint.config(
     files: SRC_FILES,
     ignores: [...COMPOSITION_ROOT, ...SPECS],
     rules: {
-      'no-restricted-imports': [
-        'error',
-        {
-          paths: [...FORBIDDEN_DB_IMPORTS, ...FORBIDDEN_DB_NAMED_FROM],
-          patterns: [
-            FORBIDDEN_DB_SUBPATHS,
-            INTERNAL_SUBPATHS,
-            COMPOSITION_ROOT_IMPORTS,
-            {
-              // (Deep `@astram/*/dist|src` and `node_modules/` paths: DEEP_PATHS, every import form.)
-              group: ['**/adapters/mariadb-*'],
-              message:
-                'Wall: framework internals (pool/uow/audit adapters) 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: `CallExpression > MemberExpression.callee[computed=false][property.name=${MORE_RAW_METHOD_RE}]`,
-          message: RAW_METHOD_MESSAGE,
-        },
-        // The same methods by COMPUTED key: `pool['query']()`, pool[`getConnection`]().
-        {
-          selector: `CallExpression > MemberExpression.callee[computed=true][property.value=${RAW_METHOD_RE}]`,
-          message: RAW_METHOD_MESSAGE,
-        },
-        {
-          selector: `CallExpression > MemberExpression.callee[computed=true] > TemplateLiteral.property[expressions.length=0] > TemplateElement[value.cooked=${RAW_METHOD_RE}]`,
-          message: RAW_METHOD_MESSAGE,
-        },
-        // …and DESTRUCTURED off anything: `const { query } = pool`, `{ ['query']: q } = pool`.
-        {
-          selector: `ObjectPattern > Property[computed=false][key.name=${RAW_METHOD_RE}]`,
-          message: RAW_METHOD_MESSAGE,
-        },
-        {
-          selector: `ObjectPattern > Property[computed=true][key.value=${RAW_METHOD_RE}]`,
-          message: RAW_METHOD_MESSAGE,
-        },
-        {
-          selector: `ObjectPattern > Property[computed=true] > TemplateLiteral.key[expressions.length=0] > TemplateElement[value.cooked=${RAW_METHOD_RE}]`,
-          message: RAW_METHOD_MESSAGE,
-        },
-        ...specifierBan(
-          DRIVER_SPECIFIER,
-          'Wall: features never load a DB driver — use the RecordEngine (@astram/engine).',
-        ),
-        ...INTERNAL_DYNAMIC,
-        ...DEEP_PATHS,
-        ...NON_STATIC_SPECIFIERS,
-        ...UUID_INPUTS,
-        // 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 from the listed package is already reported by no-restricted-imports,
-        // so plain import specifiers are skipped here; an ALIASED one is reported below, from
-        // any module, because the alias hides the name from every later use.)
-        ...FORBIDDEN_FRAMEWORK_NAMES.flatMap((name) => [
-          {
-            selector: `Identifier[name='${name}']:not(ImportSpecifier > Identifier)`,
-            message: `Wall: ${name} is framework-internal DB access — use the RecordEngine (@astram/engine).`,
-          },
-          {
-            selector: `ImportSpecifier[imported.name='${name}'][local.name!='${name}']`,
-            message: `Wall: ${name} is framework-internal DB access (imported under an alias) — 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).`,
-          },
-        ]),
-      ],
+      'no-restricted-imports': WALL_IMPORTS,
+      'no-restricted-syntax': ['error', ...WALL_SYNTAX],
+    },
+  },
+  // ── Features: the wall above plus the file-storage bans ────────────────────
+  {
+    files: FEATURE_FILES,
+    ignores: SPECS,
+    rules: {
+      'no-restricted-syntax': ['error', ...WALL_SYNTAX, ...STORAGE_BANS],
     },
   },
   // ── Tests: exempt from the DB wall, but not from the /internal and deep-path bans ──

package/template/server/package.json

@@ -20,12 +20,12 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "^1.5.0",
-    "@astram/engine": "^0.5.3",
-    "@astram/guard": "^0.12.0",
-    "@astram/guide": "^0.2.4",
-    "@astram/identity": "^0.9.2",
-    "@astram/migrate": "^0.3.2",
+    "@astram/core": "^1.6.0",
+    "@astram/engine": "^0.7.0",
+    "@astram/guard": "^0.14.0",
+    "@astram/guide": "^0.2.5",
+    "@astram/identity": "^0.11.0",
+    "@astram/migrate": "^0.4.0",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",

package/template/server/scripts/check-wall.mjs

@@ -5,7 +5,9 @@
  * an `@astram/<pkg>/internal` subpath, or any path through `node_modules/@astram`
  * (e.g. `../../../node_modules/@astram/identity/dist/internal.js`). Those carry the raw
  * pools and units of work that only the composition root (`src/app.module.ts`,
- * `src/main.ts`) may wire; features use the RecordEngine (@astram/engine).
+ * `src/main.ts`) may wire; features use the RecordEngine (@astram/engine). It also fails on
+ * `multer`, `@aws-sdk/*`, `minio`, `fs`, `node:fs` (and `/promises` subpaths): uploads go
+ * through FileIntake (@astram/guard) and FilesService (@astram/identity).
  *
  * This is a plain text scan, independent of the ESLint config, so a weakened or
  * mis-scoped eslint.config.mjs still cannot let such an import through. It reads every
@@ -22,8 +24,23 @@ import { join, relative, resolve } from 'node:path';
 const EXTENSIONS = /\.(ts|mts|cts|tsx|js|mjs|cjs|jsx)$/;
 /** A module specifier: the quoted string after `from` / `import` / `require(` / `import(`. */
 const SPECIFIER = /\b(?:from|import|require)\s*\(?\s*(['"`])([^'"`\n]+)\1/g;
-/** What a feature may never name. */
-const FORBIDDEN = /^@astram\/[^/]+\/internal(\/|\.|$)|node_modules\/@astram(\/|$)/;
+/** What a feature may never name: framework internals, and the storage/fs back doors. */
+const FORBIDDEN = [
+  {
+    re: /^@astram\/[^/]+\/internal(\/|\.|$)|node_modules\/@astram(\/|$)/,
+    why: 'framework internal (use the RecordEngine, @astram/engine)',
+  },
+  {
+    // FILE_STORAGE SPEC §11: uploads go through FileIntake (@astram/guard) and FilesService
+    // (@astram/identity); features never parse multipart, reach the bucket or the filesystem.
+    // Feature specs (`*.spec.*` / `*.test.*`) may read fixtures with fs, as in eslint.config.mjs.
+    re: /^(multer|minio|(node:)?fs|@aws-sdk\/[^/]+)(\/|$)/,
+    why: 'storage/fs access (use FileIntake from @astram/guard and FilesService from @astram/identity)',
+    specsExempt: true,
+  },
+];
+/** Spec/test files (exempt from the storage ban only). */
+const SPEC_FILE = /\.(spec|test)\.[^/.]+$/;
 
 function walk(dir, out) {
   for (const name of readdirSync(dir)) {
@@ -47,9 +64,12 @@ for (const root of roots) {
     const text = readFileSync(file, 'utf8');
     for (const m of text.matchAll(SPECIFIER)) {
       const spec = m[2].replace(/\\/g, '/');
-      if (FORBIDDEN.test(spec)) {
+      const rule = FORBIDDEN.find(
+        (f) => f.re.test(spec) && !(f.specsExempt && SPEC_FILE.test(file)),
+      );
+      if (rule) {
         const line = text.slice(0, m.index).split('\n').length;
-        hits.push(`${relative(process.cwd(), file)}:${line}  ${spec}`);
+        hits.push(`${relative(process.cwd(), file)}:${line}  ${spec}  — ${rule.why}`);
       }
     }
   }
@@ -57,10 +77,13 @@ for (const root of roots) {
 
 if (hits.length > 0) {
   console.error(
-    'lint:wall: features may not import @astram/*/internal or node_modules/@astram paths — ' +
-      'those are for src/app.module.ts and src/main.ts only; use the RecordEngine (@astram/engine).',
+    'lint:wall: features may not import @astram/*/internal or node_modules/@astram paths ' +
+      '(those are for src/app.module.ts and src/main.ts only; use the RecordEngine, @astram/engine), ' +
+      'nor multer, @aws-sdk/*, minio or fs (use FileIntake / FilesService).',
   );
   for (const h of hits) console.error(`  ${h}`);
   process.exit(1);
 }
-console.log('lint:wall: no /internal or node_modules/@astram imports under src/features');
+console.log(
+  'lint:wall: no /internal or node_modules/@astram imports, and no multer/@aws-sdk/minio/fs imports, under src/features',
+);

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

@@ -68,10 +68,20 @@ import { DemoController } from './health/demo.controller';
  *
  *   ⛔ IF YOU REGISTER YOUR OWN OWNED OBJECT TYPES (e.g. a `Note`): pass them to
  *   `IdentityFeatureModule.forRoot({ extraObjects: [Note] })` (the ONE place: their action
- *   keys then project into gate-5 grants, and the GUIDED RULE-BUILDER schema, the
- *   OWNER-SHARE resolver and cross-tenant grants know them — else a record of your type is
- *   denied, NOT policy-authorable and NOT shareable: "type '…' is not registered — cannot
- *   share"). The frontend ships the matching pages/widget (RecordPoliciesPage, ShareDialog)
+ *   keys then project into gate-5 grants, the permission catalog (so their keys are
+ *   grantable), the GUIDED RULE-BUILDER schema, the OWNER-SHARE resolver and cross-tenant
+ *   grants — else a record of your type is denied, NOT grantable, NOT policy-authorable and
+ *   NOT shareable: "type '…' is not registered — cannot share"). Build the auth-facts keys
+ *   from the SAME list so `/auth/facts` knows them too:
+ *        import { buildIdentityAuthKeys, IdentityFeatureModule } from '@astram/identity';
+ *        const extraObjects = [Note];
+ *        const { actionKeys, controlPlaneKeys } = buildIdentityAuthKeys(extraObjects);
+ *        imports: [
+ *          ShieldModule.forRoot({ auth: true, identityActionKeys: actionKeys,
+ *            identityControlPlaneKeys: controlPlaneKeys }),
+ *          IdentityFeatureModule.forRoot({ extraObjects }),
+ *        ],
+ *   The frontend ships the matching pages/widget (RecordPoliciesPage, ShareDialog)
  *   already wired to `useAuth().recordPolicy` / `.recordShare`.
  */
 @Module({

package/template/server/src/main.ts

@@ -1,8 +1,7 @@
 import 'reflect-metadata';
 import { NestFactory } from '@nestjs/core';
 import type { NestExpressApplication } from '@nestjs/platform-express';
-import { loadAppConfig } from '@astram/guard';
-import { AppModule } from './app.module';
+import { loadAppConfig, resolveBootSecrets } from '@astram/guard';
 
 /**
  * HTTP bootstrap for this Astram consumer app.
@@ -12,8 +11,16 @@ import { AppModule } from './app.module';
  * guard) and starts the HTTP listener. No security logic lives here —
  * `loadAppConfig` comes from the installed `@astram/guard` framework package and
  * reads PORT / ENVIRONMENT from the environment (see `.env.example`).
+ *
+ * Boot order matters: `resolveBootSecrets()` replaces every `secret-ref:<path>` env value
+ * (see `SECRETS_*` in `.env.example`) with the resolved secret BEFORE `AppModule` is
+ * loaded, because its `forRoot()` calls read the environment when the module file is
+ * evaluated. That is why `AppModule` is imported dynamically below, never statically at
+ * the top of this file. An unresolvable reference aborts boot.
  */
 export async function bootstrap(): Promise<void> {
+  await resolveBootSecrets();
+  const { AppModule } = await import('./app.module');
   const config = loadAppConfig();
   const app = await NestFactory.create<NestExpressApplication>(AppModule, { bufferLogs: false });
   // TRUST_PROXY = the number of reverse-proxy hops in front of this app: 0 = no proxy