create-astram-app 0.9.8 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "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

@@ -59,7 +59,7 @@ wiring:
 import { ShieldModule } from '@astram/guard';
 
 @Module({
-  imports: [ShieldModule.forRoot()],          // framework owns enforcement
+  imports: [ShieldModule.forRoot()], // framework owns enforcement
   controllers: [HealthController, DemoController],
 })
 export class AppModule {}
@@ -100,7 +100,7 @@ The full list, and how to upgrade an app scaffolded with an earlier version, is
 2. Register it in `server/src/app.module.ts` (add the module to `imports`, or its
    controller to `controllers`).
 3. **Classify every route:** `@Public()` for open routes, `@Classified({ typeKey,
-   action })` for guarded ones. Anything unclassified is denied by design (403; with
+action })` for guarded ones. Anything unclassified is denied by design (403; with
    `IdentityFeatureModule` wired, the app refuses to boot).
 4. **Data access goes through the framework's RecordEngine** — never a raw DB pool.
    The `server/eslint.config.mjs` wall fails lint on off-road DB access anywhere in
@@ -114,6 +114,42 @@ The full list, and how to upgrade an app scaffolded with an earlier version, is
 
 `server/src/features/` starts empty — it's your space.
 
+## Bootstrap your organisation
+
+`npm run bootstrap:org` (in `server/`) creates your organisation (tenants, companies,
+departments, branches, roles, users and grants) from one JSON file, through the framework's
+own services against your `AppModule`. It needs auth on and `IdentityFeatureModule` wired in
+`server/src/app.module.ts` (see its header), a built app (`npm run build`) and the migrations
+applied. Without the module it exits non-zero with "wire IdentityFeatureModule in AppModule
+before running bootstrap:org". The file format is in the framework capabilities synced into
+`.claude/rules/astram-framework-capabilities.md` (section "Organisation bootstrap").
+
+```bash
+cd server
+npm run build
+# Dry run: prints the plan, writes nothing.
+npm run bootstrap:org -- --file ../deploy/org.json
+# Apply (needs ASTRAM_BOOTSTRAP_OPERATOR; safe to re-run, it converges).
+ASTRAM_BOOTSTRAP_OPERATOR=jane.doe npm run bootstrap:org -- --file ../deploy/org.json --apply
+```
+
+- Flags: `--apply`, `--claim-unowned-roles`, `--reissue-links`, `--link-ttl-hours <n>`,
+  `--links-to-stdout`, `--interactive` (prompt for root passwords without echo).
+- Every non-root user gets a one-time set-password link, printed once, only to a terminal
+  (pass `--links-to-stdout` to print them to a pipe). Links are never logged or written to a file.
+- Root passwords come from `ASTRAM_BOOTSTRAP_ROOT_PASSWORD_<USERNAME>` (a `secret-ref:` outside
+  development) or `--interactive`. Put the printed root uuids in `SHIELD_ROOT_IDS` and pass
+  `rootIdsFromEnv()` to both `forRoot` calls (see `server/_env.example`).
+
+### Existing apps
+
+An app scaffolded before this release has no `bootstrap:org`. To add it: upgrade
+`@astram/identity` and `@astram/guard` (`npm update @astram/identity @astram/guard`), copy
+`src/bootstrap-org.ts` and `src/bootstrap-org.args.ts` from a freshly scaffolded app (or from
+`create-astram-app/template/server/src/` in the framework repo) into `server/src/`, and add
+`"bootstrap:org": "node --env-file-if-exists=.env dist/bootstrap-org.js"` to the `scripts` of
+`server/package.json`. `npm run build` compiles both files; no other change is needed.
+
 ## The frontend
 
 With `--with-frontend` (or `npx -p create-astram-app astram-add-frontend` from this

package/template/server/_env.example

@@ -135,6 +135,17 @@ NODE_ENV=development
 # Upload size cap in bytes (default 10 MiB; above the 50 MiB ceiling fails boot).
 # OBJECT_STORAGE_MAX_BYTES=10485760
 
+# --- 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.
+# SHIELD_ROOT_IDS=
+# Who is running the bootstrap (audit "on behalf of"). Required with --apply.
+# ASTRAM_BOOTSTRAP_OPERATOR=jane.doe
+# Password of each root user declared in the org file, one variable per username (upper-cased).
+# Outside development/test it must be a `secret-ref:` reference (a literal fails the run);
+# or pass --interactive to be prompted without echo.
+# ASTRAM_BOOTSTRAP_ROOT_PASSWORD_ADMIN=secret-ref:bootstrap/root-password-admin
+
 # --- 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/package.json

@@ -9,6 +9,7 @@
     "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsc -p tsconfig.build.json",
     "start": "node --env-file-if-exists=.env dist/main.js",
+    "bootstrap:org": "node --env-file-if-exists=.env dist/bootstrap-org.js",
     "dev": "node scripts/dev.mjs",
     "test": "vitest run",
     "migration:run": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate",
@@ -21,10 +22,10 @@
   },
   "dependencies": {
     "@astram/core": "^1.8.0",
-    "@astram/engine": "^0.9.0",
-    "@astram/guard": "^0.16.0",
-    "@astram/guide": "^0.2.7",
-    "@astram/identity": "^0.13.0",
+    "@astram/engine": "^0.10.0",
+    "@astram/guard": "^0.17.0",
+    "@astram/guide": "^0.2.8",
+    "@astram/identity": "^0.14.0",
     "@astram/migrate": "^0.6.0",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",

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

@@ -52,13 +52,18 @@ import { DemoController } from './health/demo.controller';
  * identity → guard), so the consumer wires it (ADR-0026):
  *   1. Turn auth on (above), pass the identity permission keys (so the frontend admin
  *      nav lights up), and import the identity module:
+ *        import { rootIdsFromEnv, ShieldModule } from '@astram/guard';
  *        import { identityAuthActionKeys, identityControlPlaneKeys,
  *                 IdentityFeatureModule } from '@astram/identity';
  *        imports: [
- *          ShieldModule.forRoot({ auth: true,
+ *          ShieldModule.forRoot({ auth: true, rootIds: rootIdsFromEnv(),
  *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys }),
- *          IdentityFeatureModule.forRoot(),   // mounts /identity/{companies,users,roles,…}
+ *          // mounts /identity/{companies,users,roles,…}
+ *          IdentityFeatureModule.forRoot({ rootIds: rootIdsFromEnv() }),
  *        ],
+ *   `rootIdsFromEnv()` reads `SHIELD_ROOT_IDS` (comma-separated platform-root user uuids; unset
+ *   means no roots), so both calls get the same list. `npm run bootstrap:org` creates your
+ *   organisation from a file and needs `IdentityFeatureModule` wired (see the README).
  *   `IdentityFeatureModule.forRoot()` self-wires the engine from your `APP_DB_*` env
  *   (no separate engine setup) and builds the record authorization `ShieldModule` decides
  *   with, so the guard renders REAL decisions from your roles' grants. Do NOT also pass
@@ -89,8 +94,9 @@ 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, identityActionKeys, identityControlPlaneKeys }),
-  //     IdentityFeatureModule.forRoot({ /* extraObjects: [YourType] */ }),
+  //     ShieldModule.forRoot({ auth: true, rootIds: rootIdsFromEnv(), identityActionKeys,
+  //       identityControlPlaneKeys }),
+  //     IdentityFeatureModule.forRoot({ rootIds: rootIdsFromEnv() /*, extraObjects: [YourType] */ }),
   //   ],
   imports: [ShieldModule.forRoot()],
   controllers: [HealthController, DemoController],

package/template/server/src/bootstrap-org.args.ts

@@ -0,0 +1,87 @@
+/**
+ * Command-line flags of `npm run bootstrap:org` (see `bootstrap-org.ts`).
+ *
+ * A pure module (no framework imports) so the flag parser is unit-testable. Unknown flags
+ * and stray arguments are refused: a typo such as `--aply` must never silently fall back
+ * to a dry run, and error text never echoes the offending value (it could be a secret).
+ */
+export interface BootstrapArgs {
+  /** Path of the org JSON file. */
+  file: string;
+  /** Write. Without it the run is a dry run. */
+  apply: boolean;
+  claimUnownedRoles: boolean;
+  reissueLinks: boolean;
+  /** Link lifetime in whole hours; the runner validates the range. */
+  linkTtlHours: number | undefined;
+  linksToStdout: boolean;
+  /** Prompt for the root passwords (no echo) instead of reading the environment. */
+  interactive: boolean;
+}
+
+export class BootstrapArgsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BootstrapArgsError';
+  }
+}
+
+export const BOOTSTRAP_USAGE =
+  'usage: npm run bootstrap:org -- --file <path> [--apply] [--claim-unowned-roles] ' +
+  '[--reissue-links] [--link-ttl-hours <n>] [--links-to-stdout] [--interactive]';
+
+export function parseBootstrapArgs(argv: readonly string[]): BootstrapArgs {
+  const args: BootstrapArgs = {
+    file: '',
+    apply: false,
+    claimUnownedRoles: false,
+    reissueLinks: false,
+    linkTtlHours: undefined,
+    linksToStdout: false,
+    interactive: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i] as string;
+    switch (flag) {
+      case '--file': {
+        const value = argv[i + 1];
+        if (value === undefined || value === '' || value.startsWith('--')) {
+          throw new BootstrapArgsError('--file needs a path');
+        }
+        args.file = value;
+        i += 1;
+        break;
+      }
+      case '--apply':
+        args.apply = true;
+        break;
+      case '--claim-unowned-roles':
+        args.claimUnownedRoles = true;
+        break;
+      case '--reissue-links':
+        args.reissueLinks = true;
+        break;
+      case '--links-to-stdout':
+        args.linksToStdout = true;
+        break;
+      case '--interactive':
+        args.interactive = true;
+        break;
+      case '--link-ttl-hours': {
+        const value = argv[i + 1];
+        if (value === undefined || !/^\d+$/.test(value)) {
+          throw new BootstrapArgsError('--link-ttl-hours needs a whole number of hours');
+        }
+        args.linkTtlHours = Number(value);
+        i += 1;
+        break;
+      }
+      default:
+        throw new BootstrapArgsError(
+          flag.startsWith('--') ? 'unknown option' : 'unexpected argument',
+        );
+    }
+  }
+  if (args.file === '') throw new BootstrapArgsError('--file <path> is required');
+  return args;
+}

package/template/server/src/bootstrap-org.ts

@@ -0,0 +1,122 @@
+import 'reflect-metadata';
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { NestFactory } from '@nestjs/core';
+import { resolveBootSecrets } from '@astram/guard';
+import { OrgBootstrapError, runOrgBootstrap } from '@astram/identity';
+import {
+  BOOTSTRAP_USAGE,
+  BootstrapArgsError,
+  parseBootstrapArgs,
+  type BootstrapArgs,
+} from './bootstrap-org.args';
+
+/**
+ * `npm run bootstrap:org -- --file org.json [--apply]`: creates your organisation (tenants,
+ * companies, roles, users, grants) from a declarative file, through the framework's own
+ * services, against THIS app's `AppModule` (so grants can name your own object types).
+ * Without `--apply` it is a dry run that prints the plan and writes nothing.
+ *
+ * No security logic lives here: `runOrgBootstrap` (from `@astram/identity`) does the work.
+ * Same boot order as `main.ts`: `resolveBootSecrets()` runs BEFORE `AppModule` is loaded,
+ * so `AppModule` is imported dynamically. Exit code 0 on success, non-zero otherwise.
+ *
+ * Needs `IdentityFeatureModule` wired in `AppModule` (see the header of `app.module.ts`).
+ */
+
+/** Prompt without echo (TTY only): the typed characters never reach the terminal. */
+async function promptHidden(question: string): Promise<string> {
+  let muted = false;
+  const output = new Writable({
+    write(chunk, _encoding, done) {
+      if (!muted) process.stdout.write(chunk);
+      done();
+    },
+  });
+  const rl = createInterface({ input: process.stdin, output, terminal: true });
+  return new Promise<string>((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      process.stdout.write('\n');
+      resolve(answer);
+    });
+    muted = true;
+  });
+}
+
+async function run(args: BootstrapArgs): Promise<number> {
+  if (args.interactive && !process.stdin.isTTY) {
+    console.error('--interactive needs a terminal');
+    return 1;
+  }
+  await resolveBootSecrets();
+  const { AppModule } = await import('./app.module');
+  // Warn level only: the Nest boot chatter is noise, and nothing here may log a secret.
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: ['warn', 'error'],
+  });
+  try {
+    const report = await runOrgBootstrap(app, {
+      file: args.file,
+      apply: args.apply,
+      claimUnownedRoles: args.claimUnownedRoles,
+      reissueLinks: args.reissueLinks,
+      ...(args.linkTtlHours !== undefined ? { linkTtlHours: args.linkTtlHours } : {}),
+      linksToStdout: args.linksToStdout,
+      ...(process.env.ASTRAM_BOOTSTRAP_OPERATOR !== undefined
+        ? { operator: process.env.ASTRAM_BOOTSTRAP_OPERATOR }
+        : {}),
+      isTTY: process.stdout.isTTY === true,
+      out: console.log,
+      ...(args.interactive
+        ? {
+            promptRootPassword: (username: string) =>
+              promptHidden(`Password for root "${username}": `),
+          }
+        : {}),
+    });
+    // Counts only: links and passwords were already shown through `out`, never repeated.
+    console.log(
+      `${report.applied ? 'applied' : 'dry run (nothing written; pass --apply to write)'}: ` +
+        `${report.plan.entries.length} planned, ${report.links} link(s) issued, ` +
+        `${report.rootIds.length} root(s)`,
+    );
+    return 0;
+  } finally {
+    await app.close();
+  }
+}
+
+async function main(): Promise<void> {
+  let args: BootstrapArgs;
+  try {
+    args = parseBootstrapArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof BootstrapArgsError) {
+      console.error(`${err.message}\n${BOOTSTRAP_USAGE}`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+  try {
+    process.exitCode = await run(args);
+  } catch (err) {
+    process.exitCode = 1;
+    if (err instanceof OrgBootstrapError) {
+      if (err.code === 'not_wired') {
+        console.error(
+          'wire IdentityFeatureModule in AppModule before running bootstrap:org (see the header of src/app.module.ts)',
+        );
+      }
+      console.error(`bootstrap:org failed [${err.code}]: ${err.message}`);
+    } else {
+      // Generic on purpose: an unexpected error can carry values from the file or the database.
+      console.error(
+        'bootstrap:org failed: unexpected error (no details printed; see the app logs)',
+      );
+    }
+  }
+}
+
+void main();