create-astram-app 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced consumer project (empty src/features/ + deny-by-default enforcement) that installs the immutable @astram/core, @astram/guard, and @astram/sdk framework.",
   "type": "module",

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node --test src/**/*.test.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.1.0",
+    "@astram/frontend-core": "^0.2.0",
     "@astram/sdk": "^0.2.0",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",

package/template/frontend/src/App.jsx

@@ -29,6 +29,9 @@ import UserForm from './pages/users/UserForm';
 import AccessPage from './pages/access/AccessPage';
 import AccessForm from './pages/access/AccessForm';
 import AuditPage from './pages/audit/AuditPage';
+import GrantsPage from './pages/cross-tenant/GrantsPage';
+import GrantForm from './pages/cross-tenant/GrantForm';
+import InboxPage from './pages/cross-tenant/InboxPage';
 
 /** The single forced-re-enroll screen path (the enforcement's frontend twin). */
 const REENROLL_PATH = '/account/reenroll';
@@ -152,6 +155,27 @@ export default function App() {
         <Route path="add" element={<AccessForm />} />
         <Route path="edit/:uuid" element={<AccessForm />} />
       </Route>
+      {/* Cross-tenant grants — the grant book (mine + incoming) is a LAYOUT route; the
+          Offer form (`offer`) renders as a routed-modal overlay under it. The pending
+          Inbox is a sibling route. All gated `identity:role:read` (mirrors nav.js). */}
+      <Route
+        path="/cross-tenant"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <GrantsPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="offer" element={<GrantForm />} />
+      </Route>
+      <Route
+        path="/cross-tenant/inbox"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <InboxPage />
+          </RequireAuth>
+        }
+      />
       {/* Audit — read-only, no child add/edit routes (audit events are immutable). */}
       <Route
         path="/audit"

package/template/frontend/src/auth/AuthContext.jsx

@@ -15,6 +15,7 @@ import {
   createAccountService,
   createAuditService,
   createAuthService,
+  createCrossTenantService,
   createIdentityService,
   isAuthenticated,
   principalOf,
@@ -64,6 +65,7 @@ export function AuthProvider({ children }) {
       auth: createAuthService(http),
       identity: createIdentityService(http),
       audit: createAuditService(http),
+      crossTenant: createCrossTenantService(http),
       account: createAccountService(http),
       // The @astram/sdk ShieldClient (Phase E slice 1) — a UX-convenience projection of
       // the caller's OWN coarse grants, fetched once per session via `getAuthFacts`.
@@ -79,7 +81,7 @@ export function AuthProvider({ children }) {
       store,
     };
   }
-  const { auth, identity, audit, account, shield, store } = services.current;
+  const { auth, identity, audit, crossTenant, account, shield, store } = services.current;
 
   const [state, setState] = useState(() => store.load()); // SessionState | null
   // The signed-in user's DISPLAY profile (name/email/company/roles) from GET /auth/me.
@@ -279,6 +281,9 @@ export function AuthProvider({ children }) {
       identity,
       // The shared audit-log service (audit viewer) — same injected web http client.
       audit,
+      // The shared cross-tenant grant service (offer/accept/revoke + inbox/mine +
+      // offerable-types) — same injected web http client.
+      crossTenant,
       // The shared self-scoped account service (change-password today; profile/MFA
       // later) — same injected web http client.
       account,
@@ -301,7 +306,7 @@ export function AuthProvider({ children }) {
         ),
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [state, auth, identity, audit, account, shield, profile, mustReenroll, authFacts],
+    [state, auth, identity, audit, crossTenant, account, shield, profile, mustReenroll, authFacts],
   );
 
   return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;

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

@@ -0,0 +1,337 @@
+/**
+ * GrantForm — the "Offer a cross-tenant grant" form, rendered as a routed-modal overlay
+ * by `/cross-tenant/offer` under GrantsPage's layout (mirrors the identity add/edit
+ * forms' routed-modal shape: `useOutletContext` for `onRefresh`, closes via
+ * `navigate(-1)`).
+ *
+ * Composition (all EXISTING components — no new CSS):
+ *   - `SearchableSelect` for the grantee TENANT picker (over `identity.listCompanies`)
+ *   - a grantee-kind toggle (user/role) — plain Button variants
+ *   - `SearchableSelect` for the grantee user/role picker (over `identity.listUsers`/
+ *     `identity.listRoles`) — resets when the tenant OR kind changes
+ *   - a plain `Select` for the object type (from `crossTenant.listOfferableTypes` —
+ *     tenantScoped types ONLY, decision 1)
+ *   - a `Checkbox` per allowed-action (the type's action vocabulary) — at least one
+ *     required; NEVER a wildcard option is offered (the writer hard-rejects '*')
+ *   - a native `DateField` for the expiry, defaulting to now+90 days, converted to a
+ *     future epoch-ms on submit (decision 2: mandatory, default 90 days)
+ *
+ * ⛔ Object_type scope ONLY (decision 4): there is no recordId/scope field anywhere in
+ * this form — the server hard-codes `scope:'object_type'` from the authenticated
+ * principal's context; nothing here could send a record-scoped offer even if it tried.
+ *
+ * ⛔ `owningTenantId`/`offeredBy` are never sent from here — only
+ * `{ granteeTenantId, granteeKind, granteeUuid, typeKey, allowedActions, expiresAtMs }`.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useNavigate, useOutletContext } from 'react-router-dom';
+import { toast } from 'sonner';
+import { useAuth } from '@/auth/AuthContext';
+import EntityFormModal from '@/components/EntityFormModal';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { Checkbox } from '@/components/ui/checkbox';
+import { DateField } from '@/components/ui/date-field';
+import { SearchableSelect } from '@/components/ui/searchable-select';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+
+const DEFAULT_EXPIRY_DAYS = 90;
+
+/** now + N days, as a yyyy-mm-dd string for the native date input's default value. */
+function defaultExpiryDateString() {
+  const d = new Date(Date.now() + DEFAULT_EXPIRY_DAYS * 24 * 60 * 60 * 1000);
+  return d.toISOString().slice(0, 10);
+}
+
+/** A yyyy-mm-dd date string -> END-OF-DAY epoch-ms (so "today" is still a valid future expiry). */
+function dateStringToEndOfDayMs(dateStr) {
+  if (!dateStr) return NaN;
+  const d = new Date(`${dateStr}T23:59:59.999`);
+  return d.getTime();
+}
+
+export default function GrantForm() {
+  const { tokens, identity, crossTenant } = useAuth();
+  const token = tokens?.accessToken;
+  const navigate = useNavigate();
+  const { onRefresh } = useOutletContext() ?? {};
+
+  const [granteeTenantId, setGranteeTenantId] = useState(null);
+  const [granteeTenantLabel, setGranteeTenantLabel] = useState(null);
+
+  const [granteeKind, setGranteeKind] = useState('user');
+  const [granteeUuid, setGranteeUuid] = useState(null);
+  const [granteeLabel, setGranteeLabel] = useState(null);
+
+  const [types, setTypes] = useState([]);
+  const [typesLoading, setTypesLoading] = useState(true);
+  const [typeKey, setTypeKey] = useState('');
+  const [selectedActions, setSelectedActions] = useState(new Set());
+
+  const [expiryDate, setExpiryDate] = useState(defaultExpiryDateString());
+
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+
+  // Load the offerable (tenantScoped-only) object types once.
+  useEffect(() => {
+    if (!token) return undefined;
+    let active = true;
+    (async () => {
+      setTypesLoading(true);
+      const r = await crossTenant.listOfferableTypes(token);
+      if (!active) return;
+      if (r.ok) {
+        setTypes(r.types || []);
+        if (r.types?.length === 1) setTypeKey(r.types[0].typeKey);
+      } else {
+        setError(r.error || 'Could not load the offerable object types.');
+      }
+      setTypesLoading(false);
+    })();
+    return () => {
+      active = false;
+    };
+  }, [crossTenant, token]);
+
+  const currentType = useMemo(() => types.find((t) => t.typeKey === typeKey), [types, typeKey]);
+
+  // Reset the chosen actions whenever the object type changes (a prior type's actions
+  // don't necessarily apply to the new one).
+  const onTypeChange = (nextKey) => {
+    setTypeKey(nextKey);
+    setSelectedActions(new Set());
+  };
+
+  const toggleAction = (action) => {
+    setSelectedActions((prev) => {
+      const next = new Set(prev);
+      if (next.has(action)) next.delete(action);
+      else next.add(action);
+      return next;
+    });
+  };
+
+  // Reset the grantee user/role whenever the TENANT or KIND changes (a uuid from a
+  // different tenant/kind is meaningless).
+  const onTenantChange = (value) => {
+    setGranteeTenantId(value);
+    setGranteeUuid(null);
+    setGranteeLabel(null);
+  };
+  const onKindChange = (kind) => {
+    setGranteeKind(kind);
+    setGranteeUuid(null);
+    setGranteeLabel(null);
+  };
+
+  const fetchTenants = useCallback(
+    async ({ search: term, page, limit }) => {
+      const r = await identity.listCompanies(token, { page, limit, search: term, sortBy: 'name', sortOrder: 'asc' });
+      if (!r.ok) return { options: [], total: 0, page };
+      return {
+        options: (r.rows || []).map((row) => ({ value: row.id, label: row.fields?.name || '(unnamed)' })),
+        total: r.total ?? 0,
+        page: r.page ?? page,
+      };
+    },
+    [identity, token],
+  );
+
+  const fetchGrantees = useCallback(
+    async ({ search: term, page, limit }) => {
+      if (granteeKind === 'role') {
+        const r = await identity.listRoles(token, { page, limit, search: term, sortBy: 'name', sortOrder: 'asc' });
+        if (!r.ok) return { options: [], total: 0, page };
+        return {
+          options: (r.rows || []).map((row) => ({ value: row.id, label: row.fields?.name || '(unnamed)' })),
+          total: r.total ?? 0,
+          page: r.page ?? page,
+        };
+      }
+      const r = await identity.listUsers(token, { page, limit, search: term, sortBy: 'username', sortOrder: 'asc' });
+      if (!r.ok) return { options: [], total: 0, page };
+      return {
+        options: (r.rows || []).map((row) => ({ value: row.id, label: row.fields?.username || '(unnamed)' })),
+        total: r.total ?? 0,
+        page: r.page ?? page,
+      };
+    },
+    [identity, token, granteeKind],
+  );
+
+  const close = () => navigate(-1);
+
+  const onSubmit = async () => {
+    if (!granteeTenantId) {
+      setError('Pick a grantee tenant.');
+      return;
+    }
+    if (!granteeUuid) {
+      setError(`Pick a grantee ${granteeKind}.`);
+      return;
+    }
+    if (!typeKey) {
+      setError('Pick an object type.');
+      return;
+    }
+    const allowedActions = [...selectedActions];
+    if (allowedActions.length === 0) {
+      setError('Pick at least one allowed action.');
+      return;
+    }
+    const expiresAtMs = dateStringToEndOfDayMs(expiryDate);
+    if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now()) {
+      setError('Pick a future expiry date.');
+      return;
+    }
+
+    setError('');
+    setBusy(true);
+    const r = await crossTenant.offer(token, {
+      granteeTenantId,
+      granteeKind,
+      granteeUuid,
+      typeKey,
+      allowedActions,
+      expiresAtMs,
+    });
+    setBusy(false);
+    if (!r.ok) {
+      setError(r.error || 'Could not offer the grant.');
+      return;
+    }
+    toast.success('Grant offered');
+    onRefresh?.();
+    close();
+  };
+
+  return (
+    <EntityFormModal
+      title="Offer a cross-tenant grant"
+      description="Let another tenant's user or role reach into one of your object types, for a bounded set of actions until an expiry."
+      open
+      onClose={close}
+      onSubmit={onSubmit}
+      submitLabel="Offer grant"
+      busy={busy}
+      error={error}
+    >
+      <div className="space-y-1.5">
+        <Label htmlFor="grant-tenant" variant="field">
+          Grantee tenant
+        </Label>
+        <SearchableSelect
+          value={granteeTenantId}
+          selectedLabel={granteeTenantLabel}
+          onChange={onTenantChange}
+          onLabelChange={setGranteeTenantLabel}
+          fetchPage={fetchTenants}
+          placeholder="Select a tenant"
+          searchPlaceholder="Search tenants"
+        />
+      </div>
+
+      <div className="space-y-1.5">
+        <Label variant="field">Grant to</Label>
+        <div className="flex gap-2">
+          <Button
+            type="button"
+            variant={granteeKind === 'user' ? 'default' : 'outline'}
+            size="sm"
+            onClick={() => onKindChange('user')}
+          >
+            User
+          </Button>
+          <Button
+            type="button"
+            variant={granteeKind === 'role' ? 'default' : 'outline'}
+            size="sm"
+            onClick={() => onKindChange('role')}
+          >
+            Role
+          </Button>
+        </div>
+      </div>
+
+      <div className="space-y-1.5">
+        <Label htmlFor="grant-grantee" variant="field">
+          {granteeKind === 'role' ? 'Role' : 'User'}
+        </Label>
+        <SearchableSelect
+          key={`${granteeTenantId ?? ''}:${granteeKind}`}
+          value={granteeUuid}
+          selectedLabel={granteeLabel}
+          onChange={setGranteeUuid}
+          onLabelChange={setGranteeLabel}
+          fetchPage={fetchGrantees}
+          placeholder={granteeKind === 'role' ? 'Select a role' : 'Select a user'}
+          searchPlaceholder={granteeKind === 'role' ? 'Search roles' : 'Search users'}
+        />
+      </div>
+
+      <div className="space-y-1.5">
+        <Label htmlFor="grant-type" variant="field">
+          Object type
+        </Label>
+        <Select value={typeKey} onValueChange={onTypeChange} disabled={typesLoading || types.length === 0}>
+          <SelectTrigger id="grant-type">
+            <SelectValue placeholder={typesLoading ? 'Loading…' : 'Select an object type'} />
+          </SelectTrigger>
+          <SelectContent>
+            {types.map((t) => (
+              <SelectItem key={t.typeKey} value={t.typeKey}>
+                {t.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+        {!typesLoading && types.length === 0 && (
+          <p className="text-xs text-muted-foreground">No object types are available to offer yet.</p>
+        )}
+      </div>
+
+      {currentType && (
+        <div className="space-y-1.5">
+          <Label variant="field">Allowed actions</Label>
+          <div className="flex flex-col gap-2">
+            {currentType.actions.map((action) => (
+              <label key={action} className="flex items-center gap-2 text-sm">
+                <Checkbox
+                  checked={selectedActions.has(action)}
+                  onCheckedChange={() => toggleAction(action)}
+                />
+                <span className="capitalize">{action}</span>
+              </label>
+            ))}
+          </div>
+          <p className="text-xs text-muted-foreground">
+            Pick at least one. The grantee can never do more than this explicit set.
+          </p>
+        </div>
+      )}
+
+      <div className="space-y-1.5">
+        <Label htmlFor="grant-expiry" variant="field">
+          Expires on
+        </Label>
+        <DateField
+          id="grant-expiry"
+          value={expiryDate}
+          onChange={(e) => setExpiryDate(e.target.value)}
+          min={new Date().toISOString().slice(0, 10)}
+        />
+        <p className="text-xs text-muted-foreground">
+          Defaults to {DEFAULT_EXPIRY_DAYS} days out. The grant must have a future expiry — no
+          perpetual grants.
+        </p>
+      </div>
+    </EntityFormModal>
+  );
+}

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

@@ -0,0 +1,237 @@
+/**
+ * GrantsPage — my tenant's cross-tenant grant book: the OUTGOING grants my tenant OWNS
+ * (any status) + the INCOMING grants ACCEPTED into my tenant. Mirrors the shared
+ * identity-admin list shape (AppShell + PageHeader + a controlled `EntityList`), plus
+ * an `<Outlet context={{ onRefresh }} />` for the routed-modal offer form at
+ * `/cross-tenant/offer`.
+ *
+ * Two lists on one page (both server-scoped to MY tenant, never a client-chosen
+ * tenant): "Outgoing" (rows, any status — Revoke available while not already revoked)
+ * and "Incoming" (accepted grants reaching INTO my tenant — read-only here; the grantee
+ * side manages acceptance from the Inbox page).
+ *
+ * ⛔ No raw UUIDs: every column renders a resolved NAME/label (grantee tenant/user/role
+ * name, type label, offeredBy name); `row.uuid` is a key/API-arg only.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Outlet, useNavigate } from 'react-router-dom';
+import { Handshake, 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, { EntityListControls } 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 statusVariant(status) {
+  if (status === 'accepted') return 'success';
+  if (status === 'revoked') return 'destructive';
+  return 'info'; // 'offered'
+}
+
+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 GrantsPage() {
+  const { tokens, crossTenant } = useAuth();
+  const token = tokens?.accessToken;
+  const navigate = useNavigate();
+
+  const [rows, setRows] = useState([]);
+  const [incoming, setIncoming] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  const [revokeTarget, setRevokeTarget] = useState(null);
+  const [revokeBusy, setRevokeBusy] = useState(false);
+
+  // Abort a superseded list request (rapid refreshes) — 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.listGrants(token, { signal: controller.signal });
+
+    if (controller.signal.aborted || loadAbortRef.current !== controller) return;
+
+    if (r.ok) {
+      setRows(r.rows || []);
+      setIncoming(r.incoming || []);
+      setError('');
+    } else {
+      setRows([]);
+      setIncoming([]);
+      setError(r.error || 'Could not load your cross-tenant grants.');
+    }
+    setLoading(false);
+  }, [crossTenant, token]);
+
+  useEffect(() => {
+    load();
+    return () => loadAbortRef.current?.abort();
+  }, [load]);
+
+  const onConfirmRevoke = async () => {
+    if (!revokeTarget) return;
+    setRevokeBusy(true);
+    const r = await crossTenant.revoke(token, revokeTarget.uuid);
+    setRevokeBusy(false);
+    if (!r.ok) {
+      toast.error(r.error || 'Could not revoke the grant.');
+      return;
+    }
+    setRevokeTarget(null);
+    toast.success('Grant revoked');
+    await load();
+  };
+
+  const outgoingColumns = [
+    {
+      key: 'granteeTenantName',
+      label: 'Grantee tenant',
+      render: (row) => <span className="font-medium text-foreground">{row.granteeTenantName}</span>,
+    },
+    {
+      key: 'granteeName',
+      label: 'Grantee',
+      render: (row) => (
+        <span>
+          {row.granteeName}{' '}
+          <span className="text-xs text-muted-foreground">({row.granteeKind})</span>
+        </span>
+      ),
+    },
+    { key: 'typeLabel', label: 'Object type' },
+    { key: 'actions', label: 'Actions', render: (row) => <ActionChips actions={row.allowedActions} /> },
+    {
+      key: 'status',
+      label: 'Status',
+      render: (row) => (
+        <Badge variant={statusVariant(row.status)} className="font-normal capitalize">
+          {row.status}
+        </Badge>
+      ),
+    },
+    { key: 'expiresAtMs', label: 'Expires', render: (row) => formatDate(row.expiresAtMs) },
+    { key: 'offeredByName', label: 'Offered by' },
+    {
+      key: 'rowActions',
+      label: '',
+      render: (row) =>
+        row.status !== 'revoked' ? (
+          <div className="flex justify-end">
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+              onClick={() => setRevokeTarget(row)}
+            >
+              Revoke
+            </Button>
+          </div>
+        ) : null,
+    },
+  ];
+
+  const incomingColumns = [
+    {
+      key: 'owningTenantName',
+      label: 'Owning tenant',
+      render: (row) => <span className="font-medium text-foreground">{row.owningTenantName}</span>,
+    },
+    {
+      key: 'granteeName',
+      label: 'Granted to',
+      render: (row) => (
+        <span>
+          {row.granteeName}{' '}
+          <span className="text-xs text-muted-foreground">({row.granteeKind})</span>
+        </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' },
+  ];
+
+  return (
+    <AppShell section="Identity" title="Cross-tenant grants">
+      <div className="p-4">
+        <PageHeader
+          section="Identity"
+          title="Cross-tenant grants"
+          icon={Handshake}
+          actions={
+            <>
+              <Button type="button" variant="outline" size="sm" onClick={() => navigate('/cross-tenant/inbox')}>
+                <Inbox className="size-4" />
+                Inbox
+              </Button>
+              <EntityListControls addLabel="Offer grant" onAdd={() => navigate('/cross-tenant/offer')} />
+            </>
+          }
+        />
+
+        <div className="mb-2 text-sm font-medium text-foreground">Outgoing — grants you&apos;ve offered</div>
+        <EntityList
+          columns={outgoingColumns}
+          rows={rows}
+          loading={loading}
+          error={error}
+          emptyLabel="You haven't offered any cross-tenant grants yet."
+        />
+
+        <div className="mt-6 mb-2 text-sm font-medium text-foreground">
+          Incoming — grants accepted into your tenant
+        </div>
+        <EntityList
+          columns={incomingColumns}
+          rows={incoming}
+          loading={loading}
+          error={error}
+          emptyLabel="No cross-tenant grants have been accepted into your tenant."
+        />
+      </div>
+
+      <Outlet context={{ onRefresh: load }} />
+
+      <ConfirmDialog
+        open={!!revokeTarget}
+        title={revokeTarget ? `Revoke the grant to “${revokeTarget.granteeTenantName}”?` : 'Revoke grant?'}
+        message="This immediately revokes the grant. The grantee tenant will lose access. This cannot be undone."
+        confirmLabel="Revoke"
+        destructive
+        busy={revokeBusy}
+        onConfirm={onConfirmRevoke}
+        onCancel={() => setRevokeTarget(null)}
+      />
+    </AppShell>
+  );
+}

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,14 @@ export const NAV_SECTIONS = [
         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

@@ -20,11 +20,11 @@
   },
   "dependencies": {
     "@astram/core": "^1.0.0",
-    "@astram/engine": "^0.1.2",
-    "@astram/guard": "^0.4.1",
+    "@astram/engine": "^0.1.3",
+    "@astram/guard": "^0.5.0",
     "@astram/guide": "^0.1.0",
-    "@astram/identity": "^0.1.2",
-    "@astram/migrate": "^0.1.1",
+    "@astram/identity": "^0.2.0",
+    "@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,36 @@ 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) ──────────
+ * 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):
+ *   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.
  */
 @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, use (see the OPTIONAL blocks above for the full form):
+  //   imports: [
+  //     ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys }),
+  //     IdentityFeatureModule.forRoot(),
+  //   ],
   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' };
+  // }
 }