create-astram-app 0.2.0 → 0.4.0

package/template/frontend/src/pages/cross-tenant/InboxPage.jsx

@@ -0,0 +1,179 @@
+/**
+ * InboxPage — my tenant's pending cross-tenant grant OFFERS: grants another tenant's
+ * admin has offered TO my tenant, not yet accepted/revoked, unexpired. Each row has
+ * Accept (`crossTenant.accept`) and Decline (`crossTenant.revoke` — the grantee side
+ * revoking an `offered` grant IS the decline action, per the locked design; no separate
+ * endpoint/status exists).
+ *
+ * Mirrors GrantsPage's list shape (custom-render columns + a themed ConfirmDialog for
+ * the destructive action — Decline is framed as a confirm, matching the "destructive
+ * operations MUST confirm first" rule, since declining an offer is a one-way action from
+ * the grantee's perspective).
+ *
+ * ⛔ No raw UUIDs: offering company name, type label, action chips, dates only;
+ * `row.uuid` is a key/API-arg only.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Inbox } from 'lucide-react';
+import { toast } from 'sonner';
+import { useAuth } from '@/auth/AuthContext';
+import AppShell from '@/shell/AppShell';
+import PageHeader from '@/components/PageHeader';
+import EntityList from '@/components/EntityList';
+import ConfirmDialog from '@/components/ConfirmDialog';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+
+/** Compact absolute date — e.g. "13 Jul 2026"; '—' when missing/invalid. */
+function formatDate(ms) {
+  if (!ms && ms !== 0) return '—';
+  const d = new Date(ms);
+  if (Number.isNaN(d.getTime())) return '—';
+  return d.toLocaleDateString(undefined, { day: 'numeric', month: 'short', year: 'numeric' });
+}
+
+function ActionChips({ actions }) {
+  if (!actions || actions.length === 0) return <span className="text-xs text-muted-foreground">—</span>;
+  return (
+    <div className="flex flex-wrap gap-1">
+      {actions.map((a) => (
+        <Badge key={a} variant="secondary" className="font-normal">
+          {a}
+        </Badge>
+      ))}
+    </div>
+  );
+}
+
+export default function InboxPage() {
+  const { tokens, crossTenant } = useAuth();
+  const token = tokens?.accessToken;
+
+  const [rows, setRows] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  const [busyUuid, setBusyUuid] = useState(null);
+  const [declineTarget, setDeclineTarget] = useState(null);
+  const [declineBusy, setDeclineBusy] = useState(false);
+
+  // Abort a superseded list request — mirrors UsersPage/AuditPage.
+  const loadAbortRef = useRef(/** @type {AbortController | null} */ (null));
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    loadAbortRef.current?.abort();
+    const controller = new AbortController();
+    loadAbortRef.current = controller;
+
+    setLoading(true);
+    const r = await crossTenant.listInbox(token, { signal: controller.signal });
+
+    if (controller.signal.aborted || loadAbortRef.current !== controller) return;
+
+    if (r.ok) {
+      setRows(r.rows || []);
+      setError('');
+    } else {
+      setRows([]);
+      setError(r.error || 'Could not load your inbox.');
+    }
+    setLoading(false);
+  }, [crossTenant, token]);
+
+  useEffect(() => {
+    load();
+    return () => loadAbortRef.current?.abort();
+  }, [load]);
+
+  const onAccept = async (row) => {
+    setBusyUuid(row.uuid);
+    const r = await crossTenant.accept(token, row.uuid);
+    setBusyUuid(null);
+    if (!r.ok) {
+      toast.error(r.error || 'Could not accept the offer.');
+      return;
+    }
+    toast.success(`Accepted the offer from ${row.owningTenantName}`);
+    await load();
+  };
+
+  const onConfirmDecline = async () => {
+    if (!declineTarget) return;
+    setDeclineBusy(true);
+    const r = await crossTenant.revoke(token, declineTarget.uuid);
+    setDeclineBusy(false);
+    if (!r.ok) {
+      toast.error(r.error || 'Could not decline the offer.');
+      return;
+    }
+    setDeclineTarget(null);
+    toast.success('Offer declined');
+    await load();
+  };
+
+  const columns = [
+    {
+      key: 'owningTenantName',
+      label: 'Offering company',
+      render: (row) => <span className="font-medium text-foreground">{row.owningTenantName}</span>,
+    },
+    { key: 'typeLabel', label: 'Object type' },
+    { key: 'actions', label: 'Actions', render: (row) => <ActionChips actions={row.allowedActions} /> },
+    { key: 'expiresAtMs', label: 'Expires', render: (row) => formatDate(row.expiresAtMs) },
+    { key: 'offeredByName', label: 'Offered by' },
+    {
+      key: 'rowActions',
+      label: '',
+      render: (row) => (
+        <div className="flex justify-end gap-1">
+          <Button
+            type="button"
+            size="sm"
+            disabled={busyUuid === row.uuid}
+            onClick={() => onAccept(row)}
+          >
+            Accept
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+            disabled={busyUuid === row.uuid}
+            onClick={() => setDeclineTarget(row)}
+          >
+            Decline
+          </Button>
+        </div>
+      ),
+    },
+  ];
+
+  return (
+    <AppShell section="Identity" title="Grant inbox">
+      <div className="p-4">
+        <PageHeader section="Identity" title="Grant inbox" icon={Inbox} />
+
+        <EntityList
+          columns={columns}
+          rows={rows}
+          loading={loading}
+          error={error}
+          emptyLabel="No pending cross-tenant grant offers."
+        />
+      </div>
+
+      <ConfirmDialog
+        open={!!declineTarget}
+        title={declineTarget ? `Decline the offer from “${declineTarget.owningTenantName}”?` : 'Decline this offer?'}
+        message="This revokes the offer. The offering tenant would need to offer again for you to reconsider. This cannot be undone."
+        confirmLabel="Decline"
+        destructive
+        busy={declineBusy}
+        onConfirm={onConfirmDecline}
+        onCancel={() => setDeclineTarget(null)}
+      />
+    </AppShell>
+  );
+}

package/template/frontend/src/shell/nav.js

@@ -16,11 +16,16 @@
  *                 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`)
+ *   - 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
+ *                 administration; the OFFER write is separately `cross_tenant_grant:share`)
  * Dashboard / Account are left UNGATED — self/owned surfaces every authenticated
  * caller may reach (no admin-only list route backs them).
  */
 import {
   Building2,
+  Handshake,
   History,
   KeyRound,
   LayoutDashboard,
@@ -69,6 +74,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: Handshake,
+        label: 'Cross-tenant',
+        path: '/cross-tenant',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:role:read',
+      },
       {
         icon: History,
         label: 'Audit',

package/template/server/package.json

@@ -19,12 +19,12 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "^1.0.0",
-    "@astram/engine": "^0.1.2",
-    "@astram/guard": "^0.4.1",
+    "@astram/core": "^1.2.0",
+    "@astram/engine": "^0.2.0",
+    "@astram/guard": "^0.6.0",
     "@astram/guide": "^0.1.0",
-    "@astram/identity": "^0.1.2",
-    "@astram/migrate": "^0.1.1",
+    "@astram/identity": "^0.3.1",
+    "@astram/migrate": "^0.2.0",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",

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

@@ -35,10 +35,48 @@ import { DemoController } from './health/demo.controller';
  * 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.)
+ *
+ * ── 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):
+ *        import { identityAuthActionKeys, identityControlPlaneKeys, IdentityFeatureModule,
+ *                 createIdentityAuthzPool, buildIdentityRecordAuthorization } from '@astram/identity';
+ *        const authzPool = createIdentityAuthzPool();
+ *        imports: [
+ *          ShieldModule.forRoot({ auth: true,
+ *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys,
+ *            recordAuthorization: buildIdentityRecordAuthorization(authzPool) }),
+ *          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, use:
-  //   imports: [ShieldModule.forRoot({ auth: true })],
+  // Enforcement-only by default (boots with no config). For real login + the identity
+  // 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,
+  //       recordAuthorization: buildIdentityRecordAuthorization(authzPool, [/* YourType */]) }),
+  //     IdentityFeatureModule.forRoot({ /* extraObjects: [YourType] */ }),
+  //   ],
   imports: [ShieldModule.forRoot()],
   controllers: [HealthController, DemoController],
 })

package/template/server/src/health/demo.controller.ts

@@ -2,15 +2,23 @@ import { Controller, Get } from '@nestjs/common';
 import { Public } from '@astram/guard';
 
 /**
- * Demonstration routes proving the deny-by-default enforcement seam (ADR-0002).
+ * Demonstration route proving the enforcement seam (ADR-0002).
  *
- * - `GET /demo/public`       → `@Public()`  → REACHABLE (200).
- * - `GET /demo/unclassified` → no metadata  → DENIED by the global guard (403).
+ * - `GET /demo/public` → `@Public()` → REACHABLE (200): an explicit opt-out of the
+ *   deny-by-default global guard.
  *
- * The second handler carries NO classification decorator on purpose: it shows
- * that forgetting to declare a route locks the door (deny-by-default) rather than
- * silently exposing it. This controller is illustrative — delete it once you've
- * seen enforcement work; a real feature would classify every route.
+ * Deny-by-default has TWO layers, and they differ in WHEN they bite:
+ *   1. **Boot-time (fail-closed, strongest):** the identity boot check (`verifyGatable`)
+ *      scans every route and ABORTS BOOT if any non-`@Public` route lacks `@Classified`.
+ *      A forgotten declaration doesn't just get denied at request time — the app won't
+ *      start. That is why the illustrative "unclassified route" below is a COMMENT, not a
+ *      live handler: a live one would prevent this app from booting. Uncomment it only to
+ *      SEE the boot abort, then re-comment (or classify it).
+ *   2. **Request-time (per-request):** even absent the boot check, the global guard denies
+ *      an unclassified route with 403.
+ *
+ * This controller is illustrative — delete it once you've seen enforcement work; a real
+ * feature classifies every route with `@Public()` or `@Classified(...)`.
  */
 @Controller('demo')
 export class DemoController {
@@ -20,9 +28,12 @@ export class DemoController {
     return { message: 'public route reachable — explicit @Public() opt-out' };
   }
 
-  // NOTE: intentionally NO @Public() / @Classified() — must be DENIED (403).
-  @Get('unclassified')
-  unclassifiedRoute(): { message: string } {
-    return { message: 'this body must never be reached — the guard denies first' };
-  }
+  // Intentionally NO @Public() / @Classified(). Kept as a COMMENT because the boot-time
+  // `verifyGatable` (fail-closed) aborts boot on any unclassified route — a live handler
+  // here would stop the app from starting. Uncomment to witness the boot abort, then
+  // re-comment or classify it.
+  // @Get('unclassified')
+  // unclassifiedRoute(): { message: string } {
+  //   return { message: 'this body must never be reached — the guard denies first' };
+  // }
 }