create-astram-app 0.1.3 → 0.2.0

package/template/frontend/src/App.jsx

@@ -0,0 +1,167 @@
+/**
+ * App — routing + auth guards.
+ *
+ *   /login, /forgot-password  → public auth screens (redirect to /dashboard if
+ *                               already signed in)
+ *   /dashboard                → protected (RequireAuth bounces to /login, saving the
+ *                               return path)
+ */
+
+import { useEffect } from 'react';
+import { Navigate, Route, Routes, useLocation } from 'react-router-dom';
+import { useAuth, useCan } from './auth/AuthContext';
+import { saveReturnPath } from './platform/returnPathStore';
+import Login from './pages/Login';
+import ForgotPassword from './pages/ForgotPassword';
+import ResetPassword from './pages/ResetPassword';
+import Dashboard from './pages/Dashboard';
+import AccountLayout from './pages/account/AccountLayout';
+import ProfilePage from './pages/account/ProfilePage';
+import ChangePasswordPage from './pages/account/ChangePasswordPage';
+import TwoFactorPage from './pages/account/TwoFactorPage';
+import ReenrollPage from './pages/account/ReenrollPage';
+import CompaniesPage from './pages/companies/CompaniesPage';
+import CompanyForm from './pages/companies/CompanyForm';
+import RolesPage from './pages/roles/RolesPage';
+import RoleForm from './pages/roles/RoleForm';
+import UsersPage from './pages/users/UsersPage';
+import UserForm from './pages/users/UserForm';
+import AccessPage from './pages/access/AccessPage';
+import AccessForm from './pages/access/AccessForm';
+import AuditPage from './pages/audit/AuditPage';
+
+/** The single forced-re-enroll screen path (the enforcement's frontend twin). */
+const REENROLL_PATH = '/account/reenroll';
+
+/** Only-when-signed-out (auth screens bounce authenticated users to the app). */
+function PublicOnly({ children }) {
+  const { isAuthenticated } = useAuth();
+  return isAuthenticated ? <Navigate to="/dashboard" replace /> : children;
+}
+
+/**
+ * Only-when-signed-in (protected pages bounce to login, remembering where you were).
+ *
+ * ALSO the frontend twin of the server-side re-enroll gate: when the session is
+ * `mustReenroll` (recovery-code login), every protected route is pinned to the forced
+ * re-enroll screen — mirroring the server 403'ing every non-allowlisted route. The
+ * enforcement is server-side (this is UX, not the security boundary); it just spares
+ * the user a bounce-through-403 on each click until a device is confirmed.
+ *
+ * `gate` (Phase E slice 1, optional): a permission KEY required to render this route.
+ * When absent from the caller's auth-facts projection, redirect to `/dashboard` instead
+ * of rendering — sparing a direct-navigation bounce-through-403 the same way `mustReenroll`
+ * does above. UX ONLY: the server's decide() on the page's underlying @Classified route
+ * remains the real enforcement regardless of this check (a stale/tampered projection just
+ * means the user reaches the page and then gets 403'd by its data calls).
+ */
+function RequireAuth({ children, gate }) {
+  const { isAuthenticated, mustReenroll } = useAuth();
+  // Called UNCONDITIONALLY (Rules of Hooks) — `useCan(undefined)` simply resolves to
+  // `false` when no gate is set, so the ungated case is handled by short-circuiting on
+  // `gate &&` below rather than skipping the hook call itself.
+  const canGate = useCan(gate);
+  const allowed = !gate || canGate;
+  const location = useLocation();
+  // Remember where the user was so the next login returns them here. Persisted to
+  // localStorage (via saveReturnPath) so it survives a full reload / browser restart —
+  // the in-memory `from` router state below only helps within the same page session.
+  // Done in an effect (a render-time side-effect would be impure); path+search so a
+  // deep-linked list page (e.g. ?page=2) restores exactly.
+  const fullPath = location.pathname + location.search;
+  useEffect(() => {
+    if (!isAuthenticated) saveReturnPath(fullPath);
+  }, [isAuthenticated, fullPath]);
+
+  if (!isAuthenticated) {
+    return <Navigate to="/login" replace state={{ from: fullPath }} />;
+  }
+  if (mustReenroll && location.pathname !== REENROLL_PATH) {
+    return <Navigate to={REENROLL_PATH} replace />;
+  }
+  if (gate && !allowed) {
+    return <Navigate to="/dashboard" replace />;
+  }
+  return children;
+}
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<PublicOnly><Login /></PublicOnly>} />
+      <Route path="/forgot-password" element={<PublicOnly><ForgotPassword /></PublicOnly>} />
+      <Route path="/reset-password" element={<PublicOnly><ResetPassword /></PublicOnly>} />
+      <Route path="/dashboard" element={<RequireAuth><Dashboard /></RequireAuth>} />
+      {/* Forced re-enroll — a standalone full-screen flow (NOT an account tab). While
+          the session is `mustReenroll`, RequireAuth pins every other protected route
+          here; this path is the one RequireAuth lets through so the screen can load. */}
+      <Route path="/account/reenroll" element={<RequireAuth><ReenrollPage /></RequireAuth>} />
+      {/* Account — a persistent layout with per-tab child routes (bookmarkable, back
+          works). /account redirects to the Profile tab. */}
+      <Route path="/account" element={<RequireAuth><AccountLayout /></RequireAuth>}>
+        <Route index element={<Navigate to="/account/profile" replace />} />
+        <Route path="profile" element={<ProfilePage />} />
+        <Route path="password" element={<ChangePasswordPage />} />
+        <Route path="2fa" element={<TwoFactorPage />} />
+      </Route>
+      {/* Identity management — each list is a LAYOUT route; add/edit are child routes
+          that render as a routed-modal overlay (bookmarkable, back button closes).
+          `gate` (Phase E slice 1) mirrors the Sidebar's nav gating — VERIFIED against
+          each page's actual @Classified list route (see shell/nav.js's header doc). */}
+      <Route
+        path="/companies"
+        element={
+          <RequireAuth gate="identity:company:read">
+            <CompaniesPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<CompanyForm />} />
+        <Route path="edit/:uuid" element={<CompanyForm />} />
+      </Route>
+      <Route
+        path="/roles"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <RolesPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<RoleForm />} />
+        <Route path="edit/:uuid" element={<RoleForm />} />
+      </Route>
+      <Route
+        path="/users"
+        element={
+          <RequireAuth gate="identity:user:read">
+            <UsersPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<UserForm />} />
+        <Route path="edit/:uuid" element={<UserForm />} />
+      </Route>
+      <Route
+        path="/access"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <AccessPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<AccessForm />} />
+        <Route path="edit/:uuid" element={<AccessForm />} />
+      </Route>
+      {/* Audit — read-only, no child add/edit routes (audit events are immutable). */}
+      <Route
+        path="/audit"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <AuditPage />
+          </RequireAuth>
+        }
+      />
+      <Route path="*" element={<Navigate to="/dashboard" replace />} />
+    </Routes>
+  );
+}

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

@@ -0,0 +1,338 @@
+/**
+ * AuthContext — the web app's session state + wiring of @astram/frontend-core's
+ * platform-agnostic auth logic to the WEB platform adapters (fetch + localStorage).
+ *
+ * The LOGIC (how login/refresh/logout talk to the framework API) lives in
+ * @astram/frontend-core — this file only injects the browser's fetch client +
+ * localStorage, holds the React state, and exposes `useAuth()` to the views. A future
+ * mobile app has its own AuthContext that injects RN adapters into the SAME shared
+ * services.
+ */
+
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { createShieldClient, systemClock } from '@astram/sdk';
+import {
+  createAccountService,
+  createAuditService,
+  createAuthService,
+  createIdentityService,
+  isAuthenticated,
+  principalOf,
+} from '@astram/frontend-core';
+import { createWebHttpClient } from '../platform/httpClient';
+import { createWebSessionStore } from '../platform/sessionStore';
+import { createWebShieldTransport } from '../platform/shieldTransport';
+
+const AuthContext = createContext(null);
+
+export function AuthProvider({ children }) {
+  // Whether the current session is server-side-restricted to re-securing the account
+  // (recovery-code login → `mustReenroll`). Held in a ref so the http-client interceptor
+  // (built once, below) can flip it without being re-created; mirrored into React state
+  // so the router re-renders. Until a fresh device is confirmed, the app forces the
+  // re-enroll screen (§4). Set on either (a) a `mfaRecoveryUsed:true` login result, or
+  // (b) the app-wide 403 `reenrollment_required` interceptor catching a blocked request.
+  const [mustReenroll, setMustReenroll] = useState(false);
+  const reenrollRef = useRef(false);
+  const markReenroll = () => {
+    if (reenrollRef.current) return; // already flagged — avoid redundant re-renders
+    reenrollRef.current = true;
+    setMustReenroll(true);
+  };
+  const clearReenroll = () => {
+    reenrollRef.current = false;
+    setMustReenroll(false);
+  };
+
+  // The CURRENT access token, read by the shield transport's `getToken` getter. A ref
+  // (not a captured value) so the transport — built ONCE below — always reads the LIVE
+  // token across login/refresh/logout without needing to be reconstructed (mirrors
+  // `reenrollRef` above for the identical reason).
+  const tokenRef = useRef(null);
+
+  // Build the shared services from the injected web platform adapters (once). The
+  // LOGIC is @astram/frontend-core; only the http client + storage are web-specific here.
+  const services = useRef(null);
+  if (!services.current) {
+    // The http client gets an app-wide interceptor: a 403 whose body is EXACTLY
+    // `{ error: 'reenrollment_required' }` (the enforced-re-enroll gate, §4) flips the
+    // app into the forced re-enroll flow. Matched narrowly so a future permission-deny
+    // 403 never triggers it.
+    const http = createWebHttpClient({ onReenrollRequired: () => markReenroll() });
+    const store = createWebSessionStore();
+    services.current = {
+      auth: createAuthService(http),
+      identity: createIdentityService(http),
+      audit: createAuditService(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`.
+      // NEVER the security boundary: the server's decide() on every @Classified route
+      // is the real enforcement (see shieldTransport.js's header doc). `getToken` reads
+      // `tokenRef.current` (not a closed-over value) so the SAME client instance always
+      // sees the CURRENT token across a refresh, without being rebuilt.
+      shield: createShieldClient({
+        transport: createWebShieldTransport({ http, getToken: () => tokenRef.current }),
+        clock: systemClock,
+        scheduler: { sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) },
+      }),
+      store,
+    };
+  }
+  const { auth, identity, audit, 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.
+  // Resolved server-side to NAMES (never UUIDs). null until fetched / when unavailable.
+  const [profile, setProfile] = useState(null);
+
+  // The caller's authorization-fact projection (Phase E slice 1) — `null` until fetched
+  // at least once for this session. Fail-closed: `useCan` treats `null` (not yet known)
+  // exactly like "the fact is absent" — hide/disable until a projection is in hand,
+  // never optimistically show.
+  const [authFacts, setAuthFacts] = useState(null);
+
+  // Keep `tokenRef` in lockstep with the persisted session's access token so the shield
+  // transport (built once, above) always reads the CURRENT token.
+  tokenRef.current = state?.tokens?.accessToken ?? null;
+
+  const persist = (value) => {
+    setState(value);
+    store.save(value);
+  };
+
+  // Fetch the display profile for the current access token. Best-effort: on any
+  // non-ok (401/404/501/unreachable) we simply clear it and the UI falls back to the
+  // interim identity hint — the profile is enrichment, never a gate.
+  const loadProfile = async (accessToken) => {
+    if (!accessToken) {
+      setProfile(null);
+      return;
+    }
+    const r = await auth.me(accessToken);
+    setProfile(r.ok ? r.profile : null);
+  };
+
+  // Re-fetch the display profile for the CURRENT session's token. Exposed via
+  // useAuth() so a self-service edit (PATCH /account/profile) can refresh the
+  // header/user card in place after a successful save. Best-effort like loadProfile.
+  const refreshProfile = async () => {
+    await loadProfile(state?.tokens?.accessToken);
+  };
+
+  // Fetch the caller's OWN authorization-fact projection. Called on login/mount, AND
+  // (Phase E slice 2 — ADR-0011 frontend twin) repeatedly via the focus + interval
+  // effect below, so a mid-session permission-version BUMP is picked up without a
+  // manual reload: `shield.getAuthFacts` re-checks staleness (via the transport's
+  // `currentVersion()` probe) on EVERY call and only refetches the full projection when
+  // the version actually moved — a poll that finds nothing stale costs one cheap
+  // version-probe request. `shield.getAuthFacts` is ITSELF fail-closed by construction:
+  // no transport / a terminal deny / a transient outage all resolve to a projection with
+  // NO allowed facts, or the last-good one held stale (see shieldTransport.js +
+  // client.ts's `fetchAndCacheProjection`) — never throws, so this never needs a
+  // try/catch to stay safe, and (no-flicker) `authFacts` is only ever set to a
+  // RESOLVED projection, never reset to `null` mid-poll. `principalId` absent (no
+  // session yet) → skip, leaving `authFacts` at its fail-closed `null` (useCan
+  // hides/denies until known).
+  const refreshAuthFacts = async (principalId) => {
+    if (!principalId) {
+      setAuthFacts(null);
+      return;
+    }
+    const projection = await shield.getAuthFacts(principalId);
+    setAuthFacts(projection);
+  };
+
+  // The shared post-authentication work: persist the session + fetch the display
+  // profile + the auth-facts projection. Both a plain login and an MFA-completed login
+  // end here, so the session is established identically regardless of which path
+  // authenticated the user.
+  const establishSession = async (session, tokens, identityHint) => {
+    // Keep the identity hint the user signed in with as an interim label; the real
+    // display profile is fetched from /auth/me right after (names, never UUIDs).
+    persist({ session, tokens, identityHint });
+    await Promise.all([
+      loadProfile(tokens?.accessToken),
+      refreshAuthFacts(session?.principalId ?? null),
+    ]);
+  };
+
+  const login = async (identityHint, password) => {
+    const r = await auth.login(identityHint, password);
+    if (r.ok === true) {
+      await establishSession(r.session, r.tokens, identityHint);
+    }
+    return r; // { ok:true } | { ok:'mfa', challengeToken } | { ok:false, error }
+  };
+
+  // Complete a pending MFA challenge (the second step after login returned
+  // { ok:'mfa', challengeToken }). `factor` is the second-factor kind ('totp' by
+  // default, or 'recovery_code' when the user signs in with a saved recovery code).
+  // `identityHint` is threaded through from the login step so the same interim label
+  // is kept when the session is established. On success the session is established
+  // exactly as a plain login would.
+  //
+  // NOTE (bug fix): the caller used to pass `identityHint` in the `factor` slot, so a
+  // TOTP verify sent `factor: <username>` — the recovery-code work needs a real
+  // `factor`, so it is now the third positional arg (default 'totp') and identityHint
+  // is fourth. When the login was completed with a recovery code the server returns
+  // `mfaRecoveryUsed:true`; we surface it AND flip the app into the forced re-enroll
+  // flow immediately (the enforcement gate would 403 the very next request anyway).
+  const completeMfa = async (challengeToken, code, factor = 'totp', identityHint) => {
+    const r = await auth.completeMfa(challengeToken, code, factor);
+    if (r.ok === true) {
+      await establishSession(r.session, r.tokens, identityHint);
+      if (r.mfaRecoveryUsed === true) markReenroll();
+      return { ok: true, mfaRecoveryUsed: r.mfaRecoveryUsed === true };
+    }
+    return r; // { ok:false, error }
+  };
+
+  const logout = async () => {
+    const sessionId = state?.session?.sessionId;
+    persist(null); // clear locally first — the UI must never wait on the server
+    setProfile(null);
+    setAuthFacts(null); // fail-closed: no session -> no cached facts to (mis)trust
+    clearReenroll(); // a fresh sign-in starts unrestricted
+    await auth.logout(sessionId);
+  };
+
+  // On mount (e.g. a page refresh that rehydrated a persisted session), fetch the
+  // profile + the auth-facts projection once for the stored session. Runs only when we
+  // have a token but haven't fetched yet (profile === null / authFacts === null).
+  useEffect(() => {
+    const token = state?.tokens?.accessToken;
+    if (token && profile === null) void loadProfile(token);
+    if (token && authFacts === null) void refreshAuthFacts(principalOf(state));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Phase E slice 2 (ADR-0011 frontend twin) — POKE `getAuthFacts` periodically + on
+  // window focus so the SDK's own version-staleness check (client.ts's
+  // `isProjectionFresh`, driven by shieldTransport's `currentVersion()`) actually RUNS.
+  // The SDK does NOT poll itself; without a repeated caller a mid-session permission
+  // change (or a version bump from any cause) would sit unnoticed until the next
+  // full page reload. This does NOT replace the login/mount fetches above — it adds a
+  // focus listener + a light interval on top, and fires regardless of `authFacts`
+  // being null-or-not (the whole point is to re-check an already-fetched, possibly now
+  // STALE projection — the mount effect's `authFacts === null` guard only covers the
+  // "never fetched yet" case).
+  //
+  // No-flicker: `refreshAuthFacts` only calls `setAuthFacts` on a resolved projection —
+  // it never resets to `null` first. `shield.getAuthFacts` is itself fail-closed and
+  // NEVER throws (see the refreshAuthFacts doc above): a transient version-probe/fetch
+  // failure resolves the last-good (now-marked-stale-internally) or empty projection,
+  // never a rejected promise — so there is nothing here to catch, and the UI never
+  // blanks out mid-poll.
+  useEffect(() => {
+    const token = state?.tokens?.accessToken;
+    if (!token) return undefined; // not authenticated — nothing to keep fresh
+
+    const principalId = principalOf(state);
+    const poke = () => {
+      if (principalId) void refreshAuthFacts(principalId);
+    };
+
+    const onFocus = () => poke();
+    window.addEventListener('focus', onFocus);
+
+    const POLL_MS = 60_000; // cheap: each tick is one version-probe request unless stale
+    const intervalId = setInterval(poke, POLL_MS);
+
+    return () => {
+      window.removeEventListener('focus', onFocus);
+      clearInterval(intervalId);
+    };
+    // Re-armed whenever the token/principal changes (login/logout/refresh) so a stale
+    // closure never keeps polling for a signed-out or since-replaced session.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state?.tokens?.accessToken, state?.session?.principalId]);
+
+  const value = useMemo(
+    () => ({
+      session: state?.session ?? null,
+      tokens: state?.tokens ?? null,
+      // The human-readable label the user signed in with (never the raw UUID).
+      identityHint: state?.identityHint ?? null,
+      // The signed-in user's display profile (name/email/company/roles) or null.
+      profile,
+      // Re-fetch the display profile for the current token (used after a self-service
+      // profile edit so the header/user card reflects the new name/email at once).
+      refreshProfile,
+      isAuthenticated: isAuthenticated(state),
+      // True while the current session is restricted to re-securing the account
+      // (recovery-code login). The router forces the re-enroll screen until cleared.
+      mustReenroll,
+      // Clear the restriction — called by the re-enroll screen after a device confirm
+      // succeeds (the server has already flipped the bound claim; this releases the UI).
+      clearReenroll,
+      login,
+      // Complete a pending MFA challenge (second factor) — same session-establish
+      // path as login. Consumed by the Login page's MFA code step.
+      completeMfa,
+      logout,
+      // The shared auth service — exposed so the PUBLIC pre-auth pages
+      // (ForgotPassword / ResetPassword) can call requestReset / resetPassword
+      // through the SAME injected web http client (no bespoke client per page).
+      auth,
+      // The shared identity service (for protected calls) — same injected client.
+      identity,
+      // The shared audit-log service (audit viewer) — same injected web http client.
+      audit,
+      // The shared self-scoped account service (change-password today; profile/MFA
+      // later) — same injected web http client.
+      account,
+      // The @astram/sdk ShieldClient (Phase E slice 1) — exposed for any page that needs
+      // direct access (e.g. a forced re-fetch). Most call sites should prefer `useCan`.
+      shield,
+      // The caller's raw auth-facts projection, or `null` before the first fetch
+      // resolves. Most call sites should prefer `useCan(key)` below; exposed for
+      // completeness / debugging.
+      authFacts,
+      // `can(permissionKey)` — is the given permission key present as an ALLOWED fact in
+      // the current projection? FAIL-CLOSED: an absent fact, OR no projection fetched
+      // yet (`authFacts === null`), both read as `false` (can't) — never optimistically
+      // `true`. This is a UX convenience only: hides/disables nav + page gates; it is
+      // NEVER the security boundary — the server's decide() on every @Classified route
+      // is the real enforcement (see shieldTransport.js's header doc).
+      can: (permissionKey) =>
+        Boolean(
+          authFacts?.facts?.some((f) => f.action === permissionKey && f.allowed === true),
+        ),
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [state, auth, identity, audit, account, shield, profile, mustReenroll, authFacts],
+  );
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+// Colocating the consumer hook with its Provider is the standard React pattern;
+// the fast-refresh "only export components" rule is advisory here (moving useAuth
+// to its own file would churn 19 import sites for no runtime benefit).
+// eslint-disable-next-line react-refresh/only-export-components
+export function useAuth() {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used within <AuthProvider>');
+  return ctx;
+}
+
+/**
+ * `useCan(permissionKey)` — Phase E slice 1: is the given permission key an ALLOWED
+ * fact in the caller's current auth-facts projection? Reads `can` off `useAuth()`, so
+ * it always sees the LATEST projection (re-renders when it changes).
+ *
+ * FAIL-CLOSED: `false` whenever the key is absent from the projection OR no projection
+ * has been fetched yet (loading) — never optimistically `true`. This is a UX
+ * convenience ONLY (hide/disable nav + page gates); it is NEVER the security boundary —
+ * a tampered/stale answer here just means the user sees an action they can't use, and
+ * the server's decide() on the underlying @Classified route still 403s it.
+ *
+ * @param {string} permissionKey
+ * @returns {boolean}
+ */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useCan(permissionKey) {
+  const { can } = useAuth();
+  return can(permissionKey);
+}

package/template/frontend/src/components/ConfirmDialog.jsx

@@ -0,0 +1,92 @@
+/**
+ * ConfirmDialog — a small, themed confirm gate for SENSITIVE / irreversible actions
+ * (disable 2FA, revoke, delete, …). Built on the shadcn AlertDialog primitive
+ * (`alert-dialog.tsx`) — the semantic confirm role — so it inherits the app's dialog
+ * theming in both light and dark and announces as an alert dialog to assistive tech.
+ * The action fires ONLY from the confirm handler — never on the initial click.
+ *
+ * Controlled: the parent owns `open` + the busy state. While `busy` is true both
+ * buttons are disabled so a slow request can't be double-fired or cancelled mid-flight.
+ * `children` renders BETWEEN the message and the buttons (e.g. a required code input),
+ * so the confirm can gather one last piece of input before committing.
+ */
+import { Loader2 } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { buttonVariants } from '@/components/ui/button';
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
+
+export default function ConfirmDialog({
+  open,
+  title = 'Are you sure?',
+  message,
+  confirmLabel = 'Confirm',
+  cancelLabel = 'Cancel',
+  destructive = false,
+  busy = false,
+  onConfirm,
+  onCancel,
+  children,
+}) {
+  return (
+    <AlertDialog
+      open={open}
+      onOpenChange={(next) => {
+        // Only allow closing via the dialog's own affordances when we're not mid-request.
+        if (!next && !busy) onCancel?.();
+      }}
+    >
+      <AlertDialogContent>
+        {/* A form wrapper so pressing Enter in a child input submits (fires onConfirm),
+            matching native dialog behavior. The confirm button is type="submit". */}
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (!busy) onConfirm?.();
+          }}
+        >
+          <AlertDialogHeader>
+            <AlertDialogTitle>{title}</AlertDialogTitle>
+            {message && <AlertDialogDescription>{message}</AlertDialogDescription>}
+          </AlertDialogHeader>
+
+          {/* Space the child input from the header above and the buttons below
+              so the field isn't flush against the footer. */}
+          {children && <div className="mt-4 mb-6">{children}</div>}
+
+          <AlertDialogFooter className="mt-4">
+            <AlertDialogCancel
+              type="button"
+              onClick={onCancel}
+              disabled={busy}
+              className="w-full sm:w-auto"
+            >
+              {cancelLabel}
+            </AlertDialogCancel>
+            {/* Use a plain submit button (not AlertDialogAction) so the confirm fires
+                via the form's onSubmit and busy-guard, not an auto-close. Styled with
+                buttonVariants so it reads as a real destructive-capable primary. */}
+            <button
+              type="submit"
+              disabled={busy}
+              className={cn(
+                buttonVariants({ variant: destructive ? 'destructive' : 'default' }),
+                'w-full sm:w-auto',
+              )}
+            >
+              {busy && <Loader2 className="size-4 animate-spin" />}
+              {confirmLabel}
+            </button>
+          </AlertDialogFooter>
+        </form>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}