@aurostack/stacks 0.1.0

package/templates/react-app/overrides/src/routes/auth/signup.tsx

@@ -0,0 +1,117 @@
+import { useState } from 'react';
+import { Form, Formik } from 'formik';
+import { Link, useNavigate, useSearchParams } from 'react-router';
+import { toFormikValidationSchema } from 'zod-formik-adapter';
+import { getSafeRedirect } from '@/shared/auth';
+import { AuthLayout } from '@/shared/layouts';
+import { Alert, FormField } from '@/shared/ui';
+import { AuthCard } from '@/features/auth/components/auth-card';
+import { CheckboxField } from '@/features/auth/components/checkbox-field';
+import { GoogleButton } from '@/features/auth/components/google-button';
+import { OrDivider } from '@/features/auth/components/or-divider';
+import { PasswordField } from '@/features/auth/components/password-field';
+import { SubmitButton } from '@/features/auth/components/submit-button';
+import { signInWithGoogle, signupWithEmail } from '@/features/auth/lib/auth-actions';
+import { withRedirect } from '@/features/auth/lib/redirect';
+import { signupSchema } from '@/features/auth/lib/schemas';
+import { APP_ORIGIN } from '@/lib/env';
+import { PRIVACY_PATH, TERMS_PATH } from '@/lib/paths';
+
+/**
+ * Opened in a new tab rather than navigated to: a same-tab hop would discard a
+ * half-filled signup form, and asking someone to re-enter it to read what they
+ * are agreeing to is how consent gets clicked through unread. These two routes
+ * ship regardless of whether the marketing site is included, precisely so this
+ * link always resolves.
+ */
+const legalLinkClass = 'font-semibold text-ink-deep underline underline-offset-2';
+
+function TermsLabel() {
+	return (
+		<>
+			I agree to the{' '}
+			<a href={TERMS_PATH} target="_blank" rel="noopener noreferrer" className={legalLinkClass}>
+				Terms of Service
+			</a>{' '}
+			and{' '}
+			<a href={PRIVACY_PATH} target="_blank" rel="noopener noreferrer" className={legalLinkClass}>
+				Privacy Policy
+			</a>
+			.
+		</>
+	);
+}
+
+export function SignupRoute() {
+	const [params] = useSearchParams();
+	const redirect = params.get('redirect');
+	const navigate = useNavigate();
+	const [error, setError] = useState<string | null>(null);
+
+	return (
+		<AuthLayout>
+			<AuthCard
+				title="Create your free account"
+				description="No fees, no card — get started in a minute."
+				footer={
+					<>
+						Already have an account?{' '}
+						<Link to={withRedirect('/login', redirect)} className="font-semibold text-ink-deep">
+							Log in
+						</Link>
+					</>
+				}
+			>
+				{error ? (
+					<Alert variant="destructive" className="mb-4">
+						{error}
+					</Alert>
+				) : null}
+				<Formik
+					initialValues={{ name: '', email: '', password: '', acceptedTerms: false }}
+					validationSchema={toFormikValidationSchema(signupSchema)}
+					onSubmit={async ({ name, email, password }, helpers) => {
+						setError(null);
+						const { error: err } = await signupWithEmail({
+							name,
+							email,
+							password,
+							// Absolute, and it has to be: this lands in an email, where a
+							// path has nothing to resolve against.
+							callbackURL: `${APP_ORIGIN}/verified`
+						});
+						helpers.setSubmitting(false);
+						if (err) {
+							setError(err);
+							return;
+						}
+						navigate(withRedirect(`/verify-email?email=${encodeURIComponent(email)}`, redirect));
+					}}
+				>
+					{({ isSubmitting, values }) => (
+						<Form className="flex flex-col gap-4">
+							<FormField name="name" label="Full name" placeholder="Your name" autoComplete="name" />
+							<FormField name="email" label="Email" type="email" placeholder="you@example.com" autoComplete="email" />
+							<PasswordField
+								name="password"
+								label="Password"
+								placeholder="At least 8 characters"
+								autoComplete="new-password"
+								showStrength
+							/>
+							<CheckboxField name="acceptedTerms" label={<TermsLabel />} />
+							<SubmitButton loading={isSubmitting}>Create account</SubmitButton>
+							<OrDivider />
+							{/* Google is a second route to the same account, so the same gate applies —
+								    otherwise the consent is one click away from being skipped entirely. */}
+							<GoogleButton
+								onClick={() => void signInWithGoogle({ callbackURL: getSafeRedirect(redirect) })}
+								disabled={isSubmitting || !values.acceptedTerms}
+							/>
+						</Form>
+					)}
+				</Formik>
+			</AuthCard>
+		</AuthLayout>
+	);
+}

package/templates/react-app/overrides/src/routes/auth/verified.tsx

@@ -0,0 +1,31 @@
+import { useSearchParams } from 'react-router';
+import { Check } from 'lucide-react';
+import { getSafeRedirect } from '@/shared/auth';
+import { AuthLayout } from '@/shared/layouts';
+import { Button, Card } from '@/shared/ui';
+
+export function VerifiedRoute() {
+	const [params] = useSearchParams();
+	const redirect = params.get('redirect');
+
+	return (
+		<AuthLayout>
+			<Card className="items-center text-center">
+				<span className="flex size-16 items-center justify-center rounded-full bg-primary text-primary-foreground">
+					<Check className="size-8" strokeWidth={2.4} />
+				</span>
+				<div className="flex flex-col gap-2">
+					<h2 className="font-display text-2xl font-black text-foreground">You're verified</h2>
+					<p className="text-sm text-body">
+						Your email is confirmed. Continue to Acme Corp — everything is ready for you.
+					</p>
+				</div>
+				{/* No explicit fallback: `configureAuth({ defaultRedirect })` already
+				    knows where the app lives. */}
+				<Button className="w-full" onClick={() => window.location.assign(getSafeRedirect(redirect))}>
+					Continue
+				</Button>
+			</Card>
+		</AuthLayout>
+	);
+}

package/templates/react-app/overrides/src/routes/auth/verify-email.tsx

@@ -0,0 +1,97 @@
+import { useEffect, useState } from 'react';
+import { Link, useNavigate, useSearchParams } from 'react-router';
+import { Mail } from 'lucide-react';
+import { getAuthClient } from '@/shared/auth';
+import { AuthLayout } from '@/shared/layouts';
+import { Alert, Button, Card } from '@/shared/ui';
+import { SubmitButton } from '@/features/auth/components/submit-button';
+import { resendVerification, verifyEmailToken } from '@/features/auth/lib/auth-actions';
+import { APP_ORIGIN } from '@/lib/env';
+
+export function VerifyEmailRoute() {
+	const [params] = useSearchParams();
+	const navigate = useNavigate();
+	const email = params.get('email') ?? '';
+	const token = params.get('token');
+	const [error, setError] = useState<string | null>(null);
+	const [checking, setChecking] = useState(Boolean(token));
+	const [resent, setResent] = useState(false);
+
+	useEffect(() => {
+		if (!token) return;
+		let active = true;
+		void (async () => {
+			const { error: err } = await verifyEmailToken(token);
+			if (!active) return;
+			if (err) {
+				setError(err);
+				setChecking(false);
+				return;
+			}
+			navigate('/verified', { replace: true });
+		})();
+		return () => {
+			active = false;
+		};
+	}, [token, navigate]);
+
+	const handleClickedLink = async () => {
+		setError(null);
+		setChecking(true);
+		const { data } = await getAuthClient().getSession();
+		setChecking(false);
+		if (data?.user?.emailVerified) {
+			navigate('/verified');
+		} else {
+			setError("We can't confirm it yet — click the link in your email, then try again.");
+		}
+	};
+
+	const handleResend = async () => {
+		setError(null);
+		// Absolute: this lands in an email, where a path has nothing to resolve against.
+		const { error: err } = await resendVerification({ email, callbackURL: `${APP_ORIGIN}/verified` });
+		if (err) {
+			setError(err);
+			return;
+		}
+		setResent(true);
+	};
+
+	return (
+		<AuthLayout>
+			<Card className="items-center text-center">
+				<span className="flex size-16 items-center justify-center rounded-full bg-accent text-ink-deep">
+					<Mail className="size-7" />
+				</span>
+				<div className="flex flex-col gap-2">
+					<h2 className="font-display text-2xl font-black text-foreground">Check your inbox</h2>
+					<p className="text-sm text-body">
+						We sent a verification link to{' '}
+						<strong className="font-semibold text-foreground">{email || 'your email'}</strong>.
+					</p>
+					<p className="text-sm text-mute">The link expires in 24 hours. Check spam if you don't see it.</p>
+				</div>
+				{error ? (
+					<Alert variant="destructive" className="w-full text-left">
+						{error}
+					</Alert>
+				) : null}
+				<div className="flex w-full flex-col gap-2">
+					<SubmitButton type="button" loading={checking} onClick={handleClickedLink}>
+						I've clicked the link
+					</SubmitButton>
+					<Button type="button" variant="outline" className="w-full" onClick={handleResend} disabled={resent}>
+						{resent ? 'Verification email sent' : 'Resend email'}
+					</Button>
+				</div>
+				<p className="text-sm text-body">
+					Wrong address?{' '}
+					<Link to="/signup" className="font-semibold text-ink-deep">
+						Edit your email
+					</Link>
+				</p>
+			</Card>
+		</AuthLayout>
+	);
+}

package/templates/react-app/overrides/src/shared/auth/config.ts

@@ -0,0 +1,28 @@
+import { initAuthClient } from './client';
+import { configureRedirects } from './redirect';
+
+/**
+ * One-shot auth wiring, called once at startup (before rendering).
+ *
+ * There is no `authAppUrl` here, unlike the multi-app build of this stack: the
+ * auth screens are routes in this bundle, so login is a path within the same
+ * origin. `trustedOrigins` therefore defaults to this app's own origin — the
+ * complete answer unless you deliberately hand off to another host.
+ */
+export function configureAuth(options: {
+	/** Backend Better Auth base URL (e.g. https://api.example.com/auth). */
+	authApiBaseUrl: string;
+	/** Route the login screen is mounted at. Defaults to `/login`. */
+	loginPath?: string;
+	/** Origins allowed as a post-login redirect target. Defaults to this origin. */
+	trustedOrigins?: string[];
+	/** Where a login with no `?redirect=` lands. */
+	defaultRedirect?: string;
+}): void {
+	initAuthClient(options.authApiBaseUrl);
+	configureRedirects({
+		loginPath: options.loginPath,
+		trustedOrigins: options.trustedOrigins,
+		defaultRedirect: options.defaultRedirect
+	});
+}

package/templates/react-app/overrides/src/shared/auth/guards.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react';
+import { Navigate, Outlet, useLocation } from 'react-router';
+import { useAuth } from './hooks';
+import { loginRedirect } from './redirect';
+
+type GuardProps = {
+	children?: ReactNode;
+	/**
+	 * Shown while the session is resolving.
+	 *
+	 * Required on purpose. This used to default to `null`, which meant the app
+	 * rendered *nothing* for the entire session round trip — ~880 ms measured
+	 * against a deployed API, and worse on mobile. Pass the shell skeleton so the
+	 * frame is on screen while the session resolves; there is no correct case for
+	 * gating a whole app behind a blank screen.
+	 */
+	fallback: ReactNode;
+};
+
+/**
+ * Requires any authenticated session; otherwise sends the visitor to `/login`
+ * with a `?redirect=` back to where they were.
+ *
+ * `<Navigate>` rather than `window.location.assign`: the login screen is a route
+ * in this same bundle, so a full page load would re-download and re-boot the app
+ * to render a screen it already has. `replace` keeps the guarded URL out of
+ * history — without it, Back from the login screen bounces straight through the
+ * guard again.
+ */
+export function ProtectedRoute({ children, fallback }: GuardProps) {
+	const { status } = useAuth();
+	const location = useLocation();
+
+	if (status === 'loading') return <>{fallback}</>;
+	if (status === 'unauthenticated') {
+		return <Navigate to={loginRedirect(location.pathname + location.search)} replace />;
+	}
+	return <>{children ?? <Outlet />}</>;
+}
+
+type RoleRouteProps = GuardProps & {
+	/** Roles allowed to view (any match). Compared against session.user.role. */
+	allow: string[];
+	/**
+	 * Rendered when authenticated but lacking a required role (403). Required for
+	 * the same reason as `fallback` — a silent blank 403 looks like a broken app.
+	 */
+	forbidden: ReactNode;
+};
+
+/**
+ * Requires an authenticated session AND one of `allow` roles.
+ * 401 (no session) -> the login screen; 403 (wrong role) -> `forbidden`.
+ *
+ * This is a UI affordance, not a security boundary: the role it reads comes from
+ * the session the browser holds, so it decides what to *render*. Every endpoint
+ * behind it must enforce the same role server-side.
+ */
+export function RoleRoute({ allow, children, fallback, forbidden }: RoleRouteProps) {
+	const { status, user } = useAuth();
+	const location = useLocation();
+
+	if (status === 'loading') return <>{fallback}</>;
+	if (status === 'unauthenticated') {
+		return <Navigate to={loginRedirect(location.pathname + location.search)} replace />;
+	}
+
+	const roles = (user?.role ?? '')
+		.split(',')
+		.map((role) => role.trim())
+		.filter(Boolean);
+	if (!allow.some((role) => roles.includes(role))) return <>{forbidden}</>;
+
+	return <>{children ?? <Outlet />}</>;
+}

package/templates/react-app/overrides/src/shared/auth/index.ts

@@ -0,0 +1,20 @@
+// @/shared/auth — authentication on Better Auth.
+export { configureAuth } from './config';
+export { initAuthClient, getAuthClient } from './client';
+export type { AuthClient } from './client';
+export { AuthProvider } from './provider';
+export { useAuth } from './hooks';
+export { ProtectedRoute, RoleRoute } from './guards';
+export { redirectToLogin, loginRedirect, getSafeRedirect, configureRedirects } from './redirect';
+export { signOut, broadcastAuthEvent, AUTH_BROADCAST_CHANNEL } from './logout';
+export {
+	authReducer,
+	sessionLoading,
+	sessionLoaded,
+	sessionCleared,
+	selectAuth,
+	selectAuthUser,
+	selectAuthStatus,
+	selectIsAuthenticated
+} from './slice';
+export type { AuthUser, AuthStatus } from './slice';

package/templates/react-app/overrides/src/shared/auth/redirect.ts

@@ -0,0 +1,65 @@
+// Redirect helpers with open-redirect protection.
+//
+// The multi-app build of this stack puts the auth screens on their own origin,
+// so an unauthenticated user is bounced across hosts and back. Here they are
+// routes in this same bundle, so login is a *path*, not a host — but the
+// allowlist stays exactly as it was: `?redirect=` is still attacker-controllable
+// and a monolith is no less vulnerable to being used as an open redirect than
+// four apps were.
+
+let loginPath = '/login';
+let trustedOrigins: string[] = [];
+let defaultRedirect = '/';
+
+export function configureRedirects(options: {
+	/** Route the auth screens are mounted at. */
+	loginPath?: string;
+	/**
+	 * Origins allowed as a post-login redirect target. Defaults to this app's
+	 * own origin, which is the whole answer for a single deployment; add to it
+	 * only if you deliberately hand off to another host.
+	 */
+	trustedOrigins?: string[];
+	/** Where a login with no `?redirect=` lands. */
+	defaultRedirect?: string;
+}): void {
+	if (options.loginPath) loginPath = options.loginPath;
+	trustedOrigins = (options.trustedOrigins ?? [window.location.origin]).map((origin) => origin.replace(/\/$/, ''));
+	if (options.defaultRedirect) defaultRedirect = options.defaultRedirect;
+}
+
+/** Validate a redirect target against the trusted-origin allowlist. */
+export function getSafeRedirect(target: string | null | undefined, fallback: string = defaultRedirect): string {
+	if (!target) return fallback;
+	try {
+		const url = new URL(target, window.location.origin);
+		if (trustedOrigins.includes(url.origin)) return url.toString();
+	} catch {
+		/* not a valid URL — fall through to fallback */
+	}
+	return fallback;
+}
+
+/**
+ * The login route, carrying where the user was heading.
+ *
+ * Returned as a path rather than navigated to, so the caller can decide: the
+ * route guard renders `<Navigate>` with it (a client-side transition), while the
+ * 401 handler below does a hard load.
+ */
+export function loginRedirect(returnTo: string = window.location.pathname + window.location.search): string {
+	const params = new URLSearchParams({ redirect: returnTo });
+	return `${loginPath}?${params.toString()}`;
+}
+
+/**
+ * Hard navigation to the login screen.
+ *
+ * This is the 401 chokepoint (`configureApi({ onUnauthorized })`), which fires
+ * from outside React — there is no router context to navigate with. A full load
+ * is also the right behaviour here: a 401 means the session died mid-session, so
+ * discarding in-memory state is the point, not a cost.
+ */
+export function redirectToLogin(returnTo?: string): void {
+	window.location.assign(loginRedirect(returnTo));
+}

package/templates/react-app/overrides/src/shared/hooks/index.ts

@@ -0,0 +1,6 @@
+// @/shared/hooks — cross-cutting React hooks.
+//
+// Deliberately empty. A hook that belongs to one feature belongs *in* that
+// feature; this is for the ones two features would otherwise each grow their own
+// copy of — a media query, a debounce, a BroadcastChannel wrapper.
+export {};

package/templates/react-app/overrides/src/shared/types/README.md

@@ -0,0 +1,28 @@
+# @/shared/types
+
+Generated TypeScript types + Zod schemas from the backend OpenAPI document.
+Imported by the API layer and by feature code, so a stale copy here shows up as
+a type error at build time rather than as a surprise at runtime.
+
+## Usage
+
+```ts
+import type { UserEntity, GetUsersResponse } from '@/shared/types';
+import { zUserEntity } from '@/shared/types/api/zod.gen';
+```
+
+## Regenerating
+
+Requires the backend's docs credentials in `.env` (see `.env.example`).
+
+```bash
+yarn gen
+```
+
+That fetches `openapi.json` from the running backend and runs
+`@hey-api/openapi-ts` over it, rewriting `src/shared/types/api/*`.
+**Commit the regenerated files** — they are the contract the app compiles
+against.
+
+`api/*` ships as an empty placeholder so a freshly scaffolded app
+typechecks before the backend exists. The first `gen` replaces it.