create-astram-app 0.3.0 → 0.5.0

package/template/frontend/src/pages/service-accounts/accessModel.js

@@ -0,0 +1,136 @@
+/**
+ * accessModel — the pure (no React, no I/O) logic behind the service-account access dialog
+ * (Phase 4): turn the server's `assignable` set + an existing account into picker options, work out
+ * which of the agent's items are LOCKED (assigned by someone with more access), validate, and build
+ * a minimal PATCH. Kept separate so it is unit-tested with `node --test` (accessModel.test.mjs).
+ *
+ * The server is the authority (ADR-0029 ceiling): `assignable` is computed from the same ceiling the
+ * write enforces. An agent's existing role/node that is NOT assignable to the editor is shown checked
+ * + disabled and is NEVER sent — a non-root PATCH keeps it server-side (sending it would be a 403).
+ * Options carry `name` for display; `id` is only the value sent back (never rendered, ADR-0012).
+ */
+
+export const LOCKED_HINT = 'assigned by someone with more access';
+export const NO_ROLES_WARNING = 'This agent will be denied everything until it has a role.';
+export const SCOPE_REQUIRED = 'Choose at least one scope node.';
+
+/** Depth of each node by walking `parentId` inside the set (cycle-safe; unknown parent ⇒ top). */
+export function withDepth(nodes) {
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const depthOf = (n) => {
+    let depth = 0;
+    const seen = new Set([n.id]);
+    let p = n.parentId;
+    while (p && byId.has(p) && !seen.has(p)) {
+      seen.add(p);
+      depth += 1;
+      p = byId.get(p).parentId;
+    }
+    return depth;
+  };
+  return nodes.map((n) => ({ id: n.id, name: n.name, depth: depthOf(n) }));
+}
+
+/** Items the agent holds that the editor cannot grant, labelled from the view (same order as ids). */
+function lockedItems(ids, labels, assignableIds) {
+  const out = [];
+  (ids || []).forEach((id, i) => {
+    if (!assignableIds.has(id))
+      out.push({ id, name: (labels && labels[i]) || 'Unnamed', depth: 0, locked: true });
+  });
+  return out;
+}
+
+/**
+ * Build the picker model. `account` is null for create.
+ *  - create: no roles ticked; every assignable scope node ticked ("defaults to everything you can reach").
+ *  - edit:   the agent's assignable items ticked; its non-assignable items appended as locked.
+ */
+export function buildAccessModel(assignable, account) {
+  const roles = (assignable && assignable.roles) || [];
+  const nodes = (assignable && assignable.scopeNodes) || [];
+  const roleIds = new Set(roles.map((r) => r.id));
+  const nodeIds = new Set(nodes.map((n) => n.id));
+
+  const roleOptions = roles.map((r) => ({ id: r.id, name: r.name, depth: 0 }));
+  const scopeOptions = withDepth(nodes);
+
+  if (!account) {
+    return {
+      roleOptions,
+      scopeOptions,
+      initialRoles: [],
+      initialScope: nodes.map((n) => n.id),
+    };
+  }
+  const lockedRoles = lockedItems(account.roleIds, account.roleLabels, roleIds);
+  const lockedScope = lockedItems(account.scopeSubtreeNodeIds, account.scopeLabels, nodeIds);
+  return {
+    roleOptions: [...roleOptions, ...lockedRoles],
+    scopeOptions: [...scopeOptions, ...lockedScope],
+    initialRoles: (account.roleIds || []).filter((id) => roleIds.has(id)),
+    initialScope: (account.scopeSubtreeNodeIds || []).filter((id) => nodeIds.has(id)),
+  };
+}
+
+/** Number of locked options (always held by the agent, never sent). */
+export function lockedCount(options) {
+  return options.filter((o) => o.locked).length;
+}
+
+/** Order-insensitive equality of two id lists. */
+export function sameIds(a, b) {
+  const sa = new Set(a);
+  const sb = new Set(b);
+  if (sa.size !== sb.size) return false;
+  for (const x of sa) if (!sb.has(x)) return false;
+  return true;
+}
+
+/**
+ * Field errors for the form (empty object ⇒ valid). When the scope will be sent (`requireScope`,
+ * default true) it needs ≥1 node — the server rejects an empty scope on edit with a 400.
+ */
+export function validateAccess({ label, scope, requireScope = true }) {
+  const errors = {};
+  if (!label || !label.trim()) errors.label = 'Give the service account a name.';
+  if (requireScope && (!scope || scope.length === 0)) errors.scope = SCOPE_REQUIRED;
+  return errors;
+}
+
+/** Does the agent end up with no role at all (ticked + locked)? → show the non-blocking warning. */
+export function hasNoRoles(roles, roleOptions) {
+  return roles.length === 0 && lockedCount(roleOptions) === 0;
+}
+
+/** Create body: always sends roles + ≥1 scope node (only assignable ids — never locked ones). */
+export function createBody({ label, roles, scope }) {
+  return { label: label.trim(), roleIds: [...roles], scopeSubtreeNodeIds: [...scope] };
+}
+
+/**
+ * Minimal PATCH for an edit: only the fields that changed. `roles` / `scope` hold assignable ids
+ * only (locked items are preserved by the server). Returns `{}` when nothing changed.
+ */
+export function editPatch({ account, label, roles, scope, initialRoles, initialScope }) {
+  const patch = {};
+  const nextLabel = label.trim();
+  if (nextLabel !== account.label) patch.label = nextLabel;
+  if (!sameIds(roles, initialRoles)) patch.roleIds = [...roles];
+  if (!sameIds(scope, initialScope)) patch.scopeSubtreeNodeIds = [...scope];
+  return patch;
+}
+
+/** Route a 400 server message to the field it is about (else the form-level error). */
+export function fieldOfServerError(message) {
+  const m = (message || '').toLowerCase();
+  if (m.includes('scope')) return 'scope';
+  if (m.includes('label') || m.includes('name')) return 'label';
+  return null;
+}
+
+/** First `max` names + a "+N" overflow count, for the row badges. */
+export function summarizeNames(names, max = 3) {
+  const list = names || [];
+  return { shown: list.slice(0, max), more: Math.max(0, list.length - max) };
+}

package/template/frontend/src/pages/service-accounts/accessModel.test.mjs

@@ -0,0 +1,161 @@
+// accessModel.test.mjs — Phase 4: the service-account access dialog's pure logic (picker
+// options, locked items, validation, minimal PATCH). No React/DOM; runs under Node's built-in
+// runner with zero dependencies:
+//
+//   node --test src/pages/service-accounts/accessModel.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  withDepth,
+  buildAccessModel,
+  lockedCount,
+  sameIds,
+  validateAccess,
+  hasNoRoles,
+  createBody,
+  editPatch,
+  fieldOfServerError,
+  summarizeNames,
+  SCOPE_REQUIRED,
+} from './accessModel.js';
+
+const ASSIGNABLE = {
+  roles: [
+    { id: 'r-ingest', name: 'Ingest' },
+    { id: 'r-audit', name: 'Auditor' },
+  ],
+  scopeNodes: [
+    { id: 'n-acme', name: 'Acme', parentId: null },
+    { id: 'n-east', name: 'Acme East', parentId: 'n-acme' },
+    { id: 'n-east-1', name: 'East 1', parentId: 'n-east' },
+  ],
+};
+
+const ACCOUNT = {
+  id: 'sa-1',
+  label: 'Ingest Bot',
+  roleIds: ['r-ingest', 'r-finance'],
+  roleLabels: ['Ingest', 'Finance Admin'],
+  scopeSubtreeNodeIds: ['n-east', 'n-beta'],
+  scopeLabels: ['Acme East', 'Beta'],
+};
+
+describe('withDepth', () => {
+  test('indents by parent chain inside the set', () => {
+    assert.deepEqual(
+      withDepth(ASSIGNABLE.scopeNodes).map((n) => n.depth),
+      [0, 1, 2],
+    );
+  });
+  test('a parent outside the set, or a cycle, does not loop or over-indent', () => {
+    const d = withDepth([
+      { id: 'a', name: 'A', parentId: 'b' },
+      { id: 'b', name: 'B', parentId: 'a' },
+      { id: 'c', name: 'C', parentId: 'zzz' },
+    ]);
+    assert.equal(d.find((n) => n.id === 'c').depth, 0);
+    assert.ok(d.every((n) => n.depth <= 1));
+  });
+});
+
+describe('buildAccessModel', () => {
+  test('create: no roles ticked, every reachable node ticked, nothing locked', () => {
+    const m = buildAccessModel(ASSIGNABLE, null);
+    assert.deepEqual(m.initialRoles, []);
+    assert.deepEqual(m.initialScope, ['n-acme', 'n-east', 'n-east-1']);
+    assert.equal(lockedCount(m.roleOptions) + lockedCount(m.scopeOptions), 0);
+  });
+
+  test('edit: assignable items ticked; out-of-ceiling items appended LOCKED with their names', () => {
+    const m = buildAccessModel(ASSIGNABLE, ACCOUNT);
+    assert.deepEqual(m.initialRoles, ['r-ingest']);
+    assert.deepEqual(m.initialScope, ['n-east']);
+    const lockedRole = m.roleOptions.find((o) => o.locked);
+    assert.deepEqual(lockedRole, {
+      id: 'r-finance',
+      name: 'Finance Admin',
+      depth: 0,
+      locked: true,
+    });
+    const lockedNode = m.scopeOptions.find((o) => o.locked);
+    assert.equal(lockedNode.name, 'Beta');
+  });
+
+  test('edit by root (everything assignable): nothing locked', () => {
+    const all = {
+      roles: [...ASSIGNABLE.roles, { id: 'r-finance', name: 'Finance Admin' }],
+      scopeNodes: [...ASSIGNABLE.scopeNodes, { id: 'n-beta', name: 'Beta', parentId: null }],
+    };
+    const m = buildAccessModel(all, ACCOUNT);
+    assert.equal(lockedCount(m.roleOptions) + lockedCount(m.scopeOptions), 0);
+    assert.deepEqual(m.initialRoles.sort(), ['r-finance', 'r-ingest']);
+  });
+});
+
+describe('validation + warnings', () => {
+  test('a name and at least one scope node are required', () => {
+    assert.deepEqual(validateAccess({ label: ' ', scope: [] }), {
+      label: 'Give the service account a name.',
+      scope: SCOPE_REQUIRED,
+    });
+    assert.deepEqual(validateAccess({ label: 'Bot', scope: ['n-acme'] }), {});
+  });
+  test('an unsent (unchanged) scope is not validated — rename of an all-locked agent still works', () => {
+    assert.deepEqual(validateAccess({ label: 'Bot', scope: [], requireScope: false }), {});
+  });
+  test('no-roles warning only when nothing is ticked AND nothing is locked', () => {
+    const create = buildAccessModel(ASSIGNABLE, null);
+    assert.equal(hasNoRoles([], create.roleOptions), true);
+    const edit = buildAccessModel(ASSIGNABLE, ACCOUNT);
+    assert.equal(hasNoRoles([], edit.roleOptions), false); // the locked role still applies
+  });
+});
+
+describe('request bodies never carry locked items', () => {
+  test('createBody sends trimmed name + roles + scope', () => {
+    assert.deepEqual(createBody({ label: ' Bot ', roles: ['r-ingest'], scope: ['n-acme'] }), {
+      label: 'Bot',
+      roleIds: ['r-ingest'],
+      scopeSubtreeNodeIds: ['n-acme'],
+    });
+  });
+
+  test('editPatch: unchanged → {}; only changed fields are sent; locked ids never appear', () => {
+    const m = buildAccessModel(ASSIGNABLE, ACCOUNT);
+    const base = { account: ACCOUNT, initialRoles: m.initialRoles, initialScope: m.initialScope };
+    assert.deepEqual(
+      editPatch({ ...base, label: 'Ingest Bot', roles: ['r-ingest'], scope: ['n-east'] }),
+      {},
+    );
+    assert.deepEqual(
+      editPatch({ ...base, label: 'Renamed', roles: ['r-ingest'], scope: ['n-east'] }),
+      {
+        label: 'Renamed',
+      },
+    );
+    const p = editPatch({ ...base, label: 'Ingest Bot', roles: [], scope: ['n-east', 'n-acme'] });
+    assert.deepEqual(p, { roleIds: [], scopeSubtreeNodeIds: ['n-east', 'n-acme'] });
+    assert.ok(!JSON.stringify(p).includes('r-finance'));
+    assert.ok(!JSON.stringify(p).includes('n-beta'));
+  });
+
+  test('sameIds is order-insensitive', () => {
+    assert.equal(sameIds(['a', 'b'], ['b', 'a']), true);
+    assert.equal(sameIds(['a'], ['a', 'b']), false);
+  });
+});
+
+describe('misc', () => {
+  test('fieldOfServerError routes 400s to the right field', () => {
+    assert.equal(fieldOfServerError('choose at least one scope node'), 'scope');
+    assert.equal(fieldOfServerError('label cannot be empty'), 'label');
+    assert.equal(fieldOfServerError('no fields to update'), null);
+  });
+  test('summarizeNames: first 3 + overflow count', () => {
+    assert.deepEqual(summarizeNames(['a', 'b', 'c', 'd', 'e']), {
+      shown: ['a', 'b', 'c'],
+      more: 2,
+    });
+    assert.deepEqual(summarizeNames(undefined), { shown: [], more: 0 });
+  });
+});

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,
@@ -74,6 +78,22 @@ export const NAV_SECTIONS = [
         matchPrefix: true,
         gate: 'identity:role:read',
       },
+      {
+        icon: ShieldCheck,
+        label: 'Record policies',
+        path: '/record-policies',
+        badge: null,
+        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',

package/template/server/package.json

@@ -19,11 +19,11 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "^1.0.0",
-    "@astram/engine": "^0.1.3",
-    "@astram/guard": "^0.5.0",
+    "@astram/core": "^1.3.0",
+    "@astram/engine": "^0.3.0",
+    "@astram/guard": "^0.7.0",
     "@astram/guide": "^0.1.0",
-    "@astram/identity": "^0.2.0",
+    "@astram/identity": "^0.4.0",
     "@astram/migrate": "^0.2.0",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.0.0",

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

@@ -36,11 +36,12 @@ import { DemoController } from './health/demo.controller';
  * no controllers to write. (Leaving `auth` off keeps the zero-config enforcement
  * boot; turning it on requires the config above, by design — fail-closed.)
  *
- * ── OPTIONAL: the identity ADMIN CONSOLE (companies/users/roles CRUD) ──────────
- * The framework also ships the identity management surface — company/user/role CRUD
- * (memberships, access, audit in later versions) — as controllers you mount by
- * importing ONE module. `@astram/guard` never imports `@astram/identity` (the
- * dependency graph is identity → guard), so the consumer wires it (ADR-0026):
+ * ── OPTIONAL: the identity ADMIN CONSOLE (companies/users/roles CRUD + authz) ───
+ * The framework also ships the identity management surface — company/user/role CRUD,
+ * memberships, access/grants, audit, cross-tenant grants, the GUIDED RULE-BUILDER
+ * (record-access policies), and OWNER SHARES — as controllers you mount by importing
+ * ONE module. `@astram/guard` never imports `@astram/identity` (the dependency graph is
+ * 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 pass `recordAuthorization` (so the decision guard actually
  *      GRANTS — without it, decide() denies every classified route):
@@ -51,19 +52,30 @@ import { DemoController } from './health/demo.controller';
  *          ShieldModule.forRoot({ auth: true,
  *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys,
  *            recordAuthorization: buildIdentityRecordAuthorization(authzPool) }),
- *          IdentityFeatureModule.forRoot(),   // mounts /identity/{companies,users,roles}
+ *          IdentityFeatureModule.forRoot(),   // mounts /identity/{companies,users,roles,…}
  *        ],
  *   `IdentityFeatureModule.forRoot()` self-wires the engine from your `APP_DB_*` env
  *   (no separate engine setup). Every route is `@Classified` — enforced by the same
  *   deny-by-default guard; `recordAuthorization` makes that guard render REAL decisions
  *   from your roles' grants. Omit the module and login still works; the admin pages 404.
+ *
+ *   ⛔ IF YOU REGISTER YOUR OWN OWNED OBJECT TYPES (e.g. a `Note`): pass them BOTH to
+ *   `buildIdentityRecordAuthorization(authzPool, [Note])` (so their action keys project
+ *   into gate-5 grants) AND to `IdentityFeatureModule.forRoot({ extraObjects: [Note] })`
+ *   (so the GUIDED RULE-BUILDER schema + the OWNER-SHARE resolver know them — else a
+ *   record of your type is NOT policy-authorable and NOT shareable: "type '…' is not
+ *   registered — cannot share"). The frontend ships the matching pages/widget
+ *   (RecordPoliciesPage, ShareDialog) already wired to `useAuth().recordPolicy` /
+ *   `.recordShare`.
  */
 @Module({
   // Enforcement-only by default (boots with no config). For real login + the identity
-  // admin console, use (see the OPTIONAL blocks above for the full form):
+  // 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(),
+  //     ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys,
+  //       recordAuthorization: buildIdentityRecordAuthorization(authzPool, [/* YourType */]) }),
+  //     IdentityFeatureModule.forRoot({ /* extraObjects: [YourType] */ }),
   //   ],
   imports: [ShieldModule.forRoot()],
   controllers: [HealthController, DemoController],

package/template/server/test/enforcement.e2e.spec.ts

@@ -1,5 +1,13 @@
-import type { INestApplication } from '@nestjs/common';
+import { Controller, Get, type INestApplication, type ModuleMetadata } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
 import { Test } from '@nestjs/testing';
+import { checkCompleteness, createModuleRegistry } from '@astram/core';
+import {
+  CatalogGatabilityError,
+  CatalogReconciler,
+  OperationInventoryScanner,
+  ShieldModule,
+} from '@astram/guard';
 import request from 'supertest';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { AppModule } from '../src/app.module';
@@ -46,11 +54,70 @@ describe('__APP_NAME__ — framework enforcement + health (e2e)', () => {
       message: expect.stringContaining('public route reachable'),
     });
   });
+});
+
+/**
+ * A deliberately UNCLASSIFIED controller (no @Public(), no @Classified()). It lives
+ * only in this test file — never in src/ — because a live unclassified route would
+ * abort a real boot (see demo.controller.ts). Used to prove both deny-by-default layers.
+ */
+@Controller('probe')
+class UnclassifiedProbeController {
+  @Get('unclassified')
+  unclassifiedRoute(): { message: string } {
+    return { message: 'this body must never be reached — the guard denies first' };
+  }
+}
+
+/** Reflect every mounted route of `imports`/`controllers` into an OperationInventory. */
+async function scanRoutes(opts: Pick<ModuleMetadata, 'imports' | 'controllers'>) {
+  const moduleRef = await Test.createTestingModule({
+    imports: [DiscoveryModule, ...(opts.imports ?? [])],
+    controllers: opts.controllers ?? [],
+    providers: [OperationInventoryScanner],
+  }).compile();
+  const inventory = moduleRef.get(OperationInventoryScanner).scan('app');
+  await moduleRef.close();
+  return inventory;
+}
 
-  it('GET /demo/unclassified is DENIED (403) — deny-by-default (ADR-0002)', async () => {
-    const res = await request(app.getHttpServer()).get('/demo/unclassified');
-    expect(res.status).toBe(403);
-    // The guard denies BEFORE the handler body runs.
-    expect(res.body.message).toContain('no access classification');
+describe('__APP_NAME__ — deny-by-default (ADR-0002)', () => {
+  it('BOOT layer: an unclassified route ABORTS boot via verifyGatable (fail-closed)', async () => {
+    const inventory = await scanRoutes({ controllers: [UnclassifiedProbeController] });
+    // The same check the identity boot provider runs: a forgotten declaration means the
+    // app refuses to start, not that the route silently serves traffic.
+    expect(() => new CatalogReconciler().verifyGatable(inventory, createModuleRegistry())).toThrow(
+      CatalogGatabilityError,
+    );
+    expect(() => new CatalogReconciler().verifyGatable(inventory, createModuleRegistry())).toThrow(
+      /UnclassifiedProbeController#unclassifiedRoute/,
+    );
+  });
+
+  it('BOOT layer: every route in YOUR AppModule is @Public() or @Classified() (none stranded)', async () => {
+    // Fails the moment a route is added without a classification — the same routes the
+    // boot check would strand. (Registering @Classified keys is the identity module's job,
+    // so only the "forgotten declaration" half is asserted here.)
+    const inventory = await scanRoutes({ imports: [AppModule] });
+    expect(inventory.operations.length).toBeGreaterThan(0);
+    const { strandedOperations } = checkCompleteness(inventory, createModuleRegistry());
+    expect(strandedOperations.map((o) => o.operationId)).toEqual([]);
+  });
+
+  it('REQUEST layer: an unclassified route is DENIED (403) before its handler runs', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [ShieldModule.forRoot()],
+      controllers: [UnclassifiedProbeController],
+    }).compile();
+    const probeApp = moduleRef.createNestApplication();
+    await probeApp.init();
+    try {
+      const res = await request(probeApp.getHttpServer()).get('/probe/unclassified');
+      expect(res.status).toBe(403);
+      // The guard denies BEFORE the handler body runs.
+      expect(res.body.message).toContain('no access classification');
+    } finally {
+      await probeApp.close();
+    }
   });
 });