@voltro/cli 0.28.0 → 0.29.0

package/templates/apps/frontend-auth/README.md

@@ -0,0 +1,78 @@
+# {{capProjectName}} {{capAppName}} — auth surface
+
+A drop-in set of auth pages other apps in the project link to, so the login UI
+lives in ONE place. Every page is a real form POSTing to the sibling api's
+`/auth/*` routes (from [`@voltro/plugin-auth`](https://voltro.cloud/docs/plugins/auth))
+with CSRF. Bilingual (en/de).
+
+```bash
+voltro init my-app --api=api-auth --web=frontend-auth
+```
+
+## Pages
+
+| URL | Route it drives | Purpose |
+|---|---|---|
+| `/login` | `POST /auth/sign-in` | email + password |
+| `/signup` | `POST /auth/sign-up` | register + auto sign-in (with a strength meter) |
+| `/forgot` | `POST /auth/password-reset` | request a reset link (neutral 202) |
+| `/reset?token=` | `POST /auth/password-reset/confirm` | set a new password |
+| `/magic` | `POST /auth/magic-link` | request a passwordless sign-in link |
+| `/verify?token=` | `POST /auth/magic-link/callback` | consume the link / confirm email |
+| `/logout` | `POST /auth/sign-out` | revoke the session, back to /login |
+
+The emailed reset link points at `/reset?token=…`; the magic / verification link
+points at `/verify?token=…`. Delivery needs `sendEmail` wired on the api (via
+`@voltro/plugin-mail`) — without it those routes still mint tokens and return
+`202`, they just don't send.
+
+## Safety built in
+
+- **Open-redirect guard** (`lib/redirect.ts`) — after sign-in we only honour a
+  same-origin, absolute-path `?next=`; a cross-origin or protocol-relative value
+  falls back to `AUTH_HOME`. Unit-tested.
+- **CSRF** — `lib/auth.ts` fetches a token from `GET /auth/csrf` and echoes it on
+  every state-changing POST.
+- **No account enumeration** — `/forgot` and `/magic` always show the same
+  neutral "check your email" message.
+
+## Files
+
+```
+app.config.ts                 web app; apis.auth → @{{projectName}}/api
+src/lib/
+  auth.ts                     csrfToken() + postAuth() over /auth/*
+  redirect.ts(.test)          safeNext() open-redirect guard (unit-tested)
+src/components/
+  AuthShell.tsx               centered card + brand + locale switcher
+  PasswordStrength.tsx        advisory 0–4 meter
+src/pages/
+  page.tsx                    / → redirect to /login
+  login/ · signup/ · forgot/ · reset/ · magic/ · verify/ · logout/
+src/locales/{en,de}.ts        bilingual catalogs (parity-enforced)
+```
+
+## Opt-in: standalone auth subdomain (shared-cookie SSO)
+
+The default is a **path-based** auth surface mounted inside your app (`/login`,
+`/signup`, …) — cookies are same-origin and nothing extra is needed. If instead
+you want a dedicated `auth.acme.dev` that signs a cookie for the whole
+`.acme.dev` family (so `app.acme.dev` and `cms.acme.dev` share one session),
+deploy this app on its own subdomain and set the api's cookie domain
+(`authRoutesPlugin({ cookieDomain: '.acme.dev' })`). The pages are identical; only
+the deploy topology + cookie domain change.
+
+## Opt-in: OAuth / SSO providers
+
+The base `@voltro/plugin-auth` ships password + magic-link + reset. Third-party
+sign-in (Google, GitHub, WorkOS, Auth0, Kinde, Supabase, generic OIDC) is a
+SEPARATE provider plugin (`@voltro/plugin-auth-*`) with its own callback routes —
+add the plugin on the api, then render its buttons here. We don't ship dead
+OAuth buttons wired to routes that don't exist.
+
+## Out of scope (V2)
+
+- 2FA / passkeys — `@voltro/plugin-auth` has the primitives (`/auth/mfa/*`,
+  `/auth/passkey/*`); the pages follow.
+- Bot defence (hCaptcha / Turnstile) — behind an env flag, render the widget only
+  when configured.

package/templates/apps/frontend-auth/app.config.ts

@@ -0,0 +1,34 @@
+// Web app for the {{projectName}} project — the AUTH surface. Every page is a
+// static form that POSTs to the sibling api's `/auth/*` routes (contributed by
+// @voltro/plugin-auth), which set the HttpOnly session cookie. Other apps in the
+// project (dashboard, cms, portal) link here for sign-in so the auth UI lives in
+// ONE place.
+//
+// The `apis` mapping names the api whose `/auth/*` routes the dev/serve pipeline
+// proxies to and whose typed rpc surface codegen pulls (this template calls the
+// HTTP routes directly, so it needs no rpc — the mapping is what wires the proxy
+// + the shared origin the session cookie is set on).
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+  // Where a successful sign-in lands when the request carries no safelisted
+  // `?next=`. Public (build-time) — never a secret in the browser bundle.
+  VOLTRO_PUBLIC_AUTH_HOME: envVar.string({ access: 'public', default: '/' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  theme: 'system' as const,
+  env,
+  // Bilingual by default (cookie-driven <I18nProvider>, SSR too).
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  // The api whose /auth/* routes back these pages. Pair with the api-auth
+  // template: `voltro init my-app --api=api-auth --web=frontend-auth`.
+  apis: {
+    auth: { package: '@{{projectName}}/api' },
+  },
+}

package/templates/apps/frontend-auth/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@{{projectName}}/api": "0.29.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/ui-shadcn": "0.29.0",
+    "@voltro/web": "0.29.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@voltro/devtools": "0.29.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/frontend-auth/src/components/AuthShell.tsx

@@ -0,0 +1,35 @@
+// The centered auth card every page renders inside — brand, title, the form
+// (children), an optional message, a footer link row, and the locale switcher.
+import type { ReactNode } from 'react'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { APP_NAME } from '../config'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export interface AuthShellProps {
+  readonly titleId: string
+  readonly children: ReactNode
+  readonly footer?: ReactNode
+}
+
+export function AuthShell({ titleId, children, footer }: AuthShellProps): ReactNode {
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  return (
+    <div className="auth-wrap">
+      <div className="auth-card">
+        <div className="auth-head">
+          <span className="brand">{APP_NAME}</span>
+          <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+        </div>
+        <h1><T id={titleId} /></h1>
+        {children}
+        {footer ? <div className="auth-footer">{footer}</div> : null}
+      </div>
+    </div>
+  )
+}

package/templates/apps/frontend-auth/src/components/PasswordStrength.tsx

@@ -0,0 +1,33 @@
+// A tiny, dependency-free password strength meter. Purely advisory client-side
+// UX — the api is the authority on password policy. Scores 0–4 on length +
+// character-class variety and renders a labelled bar.
+import type { ReactNode } from 'react'
+import { useT } from '@voltro/i18n'
+
+const score = (pw: string): number => {
+  if (pw.length === 0) return 0
+  let s = 0
+  if (pw.length >= 8) s++
+  if (pw.length >= 12) s++
+  if (/[a-z]/.test(pw) && /[A-Z]/.test(pw)) s++
+  if (/\d/.test(pw) && /[^A-Za-z0-9]/.test(pw)) s++
+  return Math.min(s, 4)
+}
+
+const LEVEL_KEYS = ['pw.weak', 'pw.weak', 'pw.fair', 'pw.good', 'pw.strong'] as const
+
+export function PasswordStrength({ value }: { readonly value: string }): ReactNode {
+  const s = score(value)
+  const label = useT(LEVEL_KEYS[s] ?? 'pw.weak')
+  if (value.length === 0) return null
+  return (
+    <div className="pw-meter" aria-hidden={false}>
+      <div className="pw-bars">
+        {[0, 1, 2, 3].map((i) => (
+          <span key={i} className={i < s ? `bar on lvl${s}` : 'bar'} />
+        ))}
+      </div>
+      <span className="pw-label">{label}</span>
+    </div>
+  )
+}

package/templates/apps/frontend-auth/src/config.ts

@@ -0,0 +1,11 @@
+// Brand + defaults shown across the auth pages.
+//
+// Plain constants — not `publicEnv` — so the template typechecks BEFORE
+// `voltro dev` generates the env types. `VOLTRO_PUBLIC_APP_NAME` /
+// `VOLTRO_PUBLIC_AUTH_HOME` are still declared in app.config.ts (validated + in
+// the env manifest); to read them typed instead, after one `voltro dev` swap
+// these for `publicEnv.VOLTRO_PUBLIC_*` from '@voltro/env/public'.
+export const APP_NAME = '{{capProjectName}}'
+
+// Where a successful sign-in lands when no safelisted `?next=` is present.
+export const AUTH_HOME = '/'

package/templates/apps/frontend-auth/src/globals.css

@@ -0,0 +1,105 @@
+/* Plain CSS — no Tailwind, so there's no @source scanner to configure. */
+:root {
+  --bg: #ffffff;
+  --fg: #0a0a0a;
+  --muted: #6b7280;
+  --accent: #4f46e5;
+  --danger: #dc2626;
+  --border: #e5e7eb;
+  --panel: #f9fafb;
+}
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #9ca3af;
+  --accent: #818cf8;
+  --danger: #f87171;
+  --border: #1f2937;
+  --panel: #111827;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  line-height: 1.55;
+}
+a { color: inherit; }
+.muted { color: var(--muted); }
+.spacer { flex: 1; }
+
+/* Buttons + inputs */
+.btn {
+  display: inline-block; cursor: pointer; border: 0; border-radius: 8px;
+  background: var(--accent); color: #fff; padding: 0.55rem 1rem;
+  font: inherit; font-weight: 600; text-decoration: none;
+}
+.btn:disabled { opacity: 0.6; cursor: default; }
+.btn.ghost { background: transparent; color: var(--accent); border: 1px solid var(--border); }
+.link { background: none; border: 0; color: var(--accent); cursor: pointer; font: inherit; padding: 0; }
+input {
+  font: inherit; padding: 0.5rem 0.65rem; border: 1px solid var(--border);
+  border-radius: 8px; background: var(--bg); color: var(--fg); min-width: 0;
+}
+.error-text { color: var(--danger); }
+
+/* Marketing */
+.marketing header {
+  display: flex; align-items: center; gap: 1rem;
+  padding: 1rem 1.5rem; border-bottom: 1px solid var(--border);
+}
+.marketing .brand { font-weight: 700; text-decoration: none; }
+.hero { max-width: 40rem; margin: 0 auto; padding: 3rem 1.5rem; }
+.hero h1 { margin: 0 0 0.75rem; }
+.auth-form { display: flex; flex-direction: column; gap: 0.85rem; max-width: 22rem; margin-top: 1.25rem; }
+.auth-form label { display: flex; flex-direction: column; gap: 0.25rem; font-size: 0.9rem; }
+
+/* Dashboard shell */
+.dash { display: grid; grid-template-columns: 15rem 1fr; min-height: 100vh; }
+.dash aside { border-right: 1px solid var(--border); padding: 1.25rem; background: var(--panel); }
+.dash aside .brand { font-weight: 700; margin-bottom: 1rem; }
+.dash nav { display: flex; flex-direction: column; gap: 0.5rem; }
+.dash nav a { text-decoration: none; color: var(--muted); padding: 0.35rem 0; }
+.dash nav a[aria-current="page"] { color: var(--fg); font-weight: 600; }
+.dash main { padding: 1.5rem 2rem; }
+.topbar { display: flex; align-items: center; margin-bottom: 1rem; }
+@media (max-width: 40rem) { .dash { grid-template-columns: 1fr; } .dash aside { border-right: 0; border-bottom: 1px solid var(--border); } }
+
+/* Bits */
+.row { display: flex; gap: 0.6rem; align-items: center; flex-wrap: wrap; margin-top: 0.5rem; }
+.empty { color: var(--muted); margin-top: 1.5rem; }
+.cards { list-style: none; padding: 0; margin: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr)); gap: 0.75rem; }
+.card { border: 1px solid var(--border); border-radius: 10px; padding: 0.9rem 1rem; background: var(--panel); }
+.card .value { font-weight: 600; }
+.card .label { color: var(--muted); font-size: 0.85rem; margin-top: 0.2rem; }
+.paywall { border: 1px solid var(--accent); border-radius: 12px; padding: 1rem 1.25rem; margin-top: 1.25rem; background: color-mix(in oklab, var(--accent) 8%, transparent); }
+.paywall p { margin: 0.35rem 0 0.75rem; }
+.facts { display: grid; grid-template-columns: max-content 1fr; gap: 0.4rem 1.5rem; margin-top: 1rem; }
+.facts dt { color: var(--muted); }
+.facts dd { margin: 0; font-weight: 600; }
+.rows { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 0.4rem; }
+.rows li { display: flex; justify-content: space-between; align-items: center; border: 1px solid var(--border); border-radius: 8px; padding: 0.6rem 0.9rem; background: var(--panel); }
+.tag { font-size: 0.8rem; color: var(--muted); border: 1px solid var(--border); border-radius: 999px; padding: 0.05rem 0.55rem; }
+code { background: color-mix(in oklab, var(--fg) 8%, transparent); padding: 0.1em 0.35em; border-radius: 4px; }
+
+/* Auth card */
+.auth-wrap { min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 1.5rem; }
+.auth-card { width: 100%; max-width: 24rem; border: 1px solid var(--border); border-radius: 14px; background: var(--panel); padding: 1.5rem 1.5rem 1.25rem; }
+.auth-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 0.75rem; }
+.auth-head .brand { font-weight: 700; }
+.auth-card h1 { margin: 0 0 1rem; font-size: 1.35rem; }
+.auth-card .auth-form { max-width: none; margin-top: 0; }
+.auth-footer { display: flex; flex-wrap: wrap; gap: 0.75rem 1.25rem; margin-top: 1.1rem; padding-top: 0.9rem; border-top: 1px solid var(--border); font-size: 0.9rem; }
+.auth-footer a { color: var(--accent); text-decoration: none; }
+.ok { color: var(--accent); }
+
+/* Password strength meter */
+.pw-meter { display: flex; align-items: center; gap: 0.5rem; margin-top: -0.25rem; }
+.pw-bars { display: flex; gap: 3px; flex: 1; }
+.pw-bars .bar { height: 5px; flex: 1; border-radius: 3px; background: var(--border); }
+.pw-bars .bar.on { background: var(--danger); }
+.pw-bars .bar.on.lvl3 { background: #d97706; }
+.pw-bars .bar.on.lvl4 { background: var(--accent); }
+.pw-label { font-size: 0.8rem; color: var(--muted); min-width: 3.2rem; text-align: right; }

package/templates/apps/frontend-auth/src/globals.d.ts

@@ -0,0 +1,6 @@
+// Ambient declarations.
+//
+// `declare module '*.css'`: TypeScript with `moduleResolution: Bundler` rejects
+// a bare `import './globals.css'` unless the asset module is declared. Vite
+// resolves it at build time; the declaration is type-only.
+declare module '*.css'

package/templates/apps/frontend-auth/src/lib/auth.ts

@@ -0,0 +1,34 @@
+// Thin wrappers over the api's `/auth/*` HTTP routes (@voltro/plugin-auth).
+//
+// State-changing auth routes are CSRF-protected (double-submit): `GET /auth/csrf`
+// sets a cookie AND returns a token that must be echoed in the `x-csrf-token`
+// header on the following POST. `postAuth` does that round-trip so each page is
+// a one-liner. These call the SAME-ORIGIN api (the dev/serve pipeline proxies
+// `/auth/*` to the api named in app.config), so the HttpOnly session cookie the
+// api sets lands on this origin.
+
+export interface AuthResponse {
+  readonly ok: boolean
+  readonly status: number
+  readonly data: unknown
+}
+
+/** Fetch a CSRF token (also drops the csrf cookie into the jar). */
+export const csrfToken = async (): Promise<string> => {
+  const res = await fetch('/auth/csrf')
+  const body = (await res.json()) as { csrfToken?: string }
+  return body.csrfToken ?? ''
+}
+
+/** POST a JSON body to an `/auth/*` route with the CSRF token attached. */
+export const postAuth = async (path: string, body: Record<string, unknown>): Promise<AuthResponse> => {
+  const token = await csrfToken()
+  const res = await fetch(path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-csrf-token': token },
+    body: JSON.stringify(body),
+  })
+  let data: unknown = null
+  try { data = await res.json() } catch { /* some routes return 202 with no body */ }
+  return { ok: res.ok, status: res.status, data }
+}

package/templates/apps/frontend-auth/src/lib/redirect.test.ts

@@ -0,0 +1,24 @@
+// Pure unit test of the open-redirect guard — no DOM needed. The safelist is
+// the security-load-bearing part of the auth flow, so it gets a direct test.
+import { describe, expect, test } from 'vitest'
+import { safeNext } from './redirect'
+
+describe('safeNext', () => {
+  test('passes a same-origin absolute path through', () => {
+    expect(safeNext('/dashboard', '/')).toBe('/dashboard')
+    expect(safeNext('/a/b?x=1', '/')).toBe('/a/b?x=1')
+  })
+
+  test('falls back to home for a missing value', () => {
+    expect(safeNext(null, '/home')).toBe('/home')
+    expect(safeNext(undefined, '/home')).toBe('/home')
+    expect(safeNext('', '/home')).toBe('/home')
+  })
+
+  test('rejects cross-origin + protocol-relative + absolute URLs', () => {
+    expect(safeNext('https://evil.example/login', '/')).toBe('/')
+    expect(safeNext('//evil.example', '/')).toBe('/')
+    expect(safeNext('/\\evil.example', '/')).toBe('/')
+    expect(safeNext('javascript:alert(1)', '/')).toBe('/')
+  })
+})

package/templates/apps/frontend-auth/src/lib/redirect.ts

@@ -0,0 +1,29 @@
+// Open-redirect guard for the `?next=` parameter.
+//
+// After sign-in we send the browser to wherever it was headed — but a `next=`
+// an attacker controls is a phishing vector (`?next=https://evil.example/login`
+// that looks like us). So we accept ONLY same-origin, absolute-PATH targets:
+// a value must start with a single `/` and NOT with `//` (a protocol-relative
+// URL like `//evil.example` that browsers treat as cross-origin). Anything else
+// falls back to `home`.
+
+/** The safelisted redirect target, or `home` when `next` is missing/unsafe. */
+export const safeNext = (next: string | null | undefined, home: string): string => {
+  if (!next) return home
+  // Must be an absolute path, and not protocol-relative (`//host`) or a
+  // backslash-smuggled variant (`/\evil`).
+  if (!next.startsWith('/') || next.startsWith('//') || next.startsWith('/\\')) return home
+  return next
+}
+
+/** Read + safelist `?next=` from the current URL (browser only). */
+export const nextFromLocation = (home: string): string => {
+  if (typeof window === 'undefined') return home
+  return safeNext(new URLSearchParams(window.location.search).get('next'), home)
+}
+
+/** Read a `?token=` from the current URL (browser only). */
+export const tokenFromLocation = (): string | null => {
+  if (typeof window === 'undefined') return null
+  return new URLSearchParams(window.location.search).get('token')
+}

package/templates/apps/frontend-auth/src/locales/de.ts

@@ -0,0 +1,66 @@
+// German catalog. Mirrors every key in `en.ts` — `defineLocale<typeof en>()`
+// fails the build if a key is missing. Translate the prose only.
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.login.title':  'Anmelden',
+  'meta.signup.title': 'Konto erstellen',
+  'meta.forgot.title': 'Passwort zurücksetzen',
+  'meta.reset.title':  'Neues Passwort festlegen',
+  'meta.magic.title':  'Magischer Link',
+  'meta.verify.title': 'Wird geprüft',
+  'meta.logout.title': 'Abmeldung',
+
+  'lang.label': 'Sprache',
+
+  'auth.email':       'E-Mail',
+  'auth.password':    'Passwort',
+  'auth.newPassword': 'Neues Passwort',
+  'auth.pending':     'Bitte warten…',
+  'auth.error':       'Das hat nicht geklappt. Prüfe deine Angaben und versuche es erneut.',
+
+  'login.title':    'Anmelden',
+  'login.submit':   'Anmelden',
+  'login.forgot':   'Passwort vergessen?',
+  'login.magic':    'Link per E-Mail senden',
+  'login.toSignup': 'Konto erstellen',
+
+  'signup.title':   'Konto erstellen',
+  'signup.submit':  'Konto erstellen',
+  'signup.toLogin': 'Konto vorhanden? Anmelden',
+
+  'forgot.title':   'Passwort zurücksetzen',
+  'forgot.body':    'Gib deine E-Mail ein und wir senden dir einen Link zum Zurücksetzen.',
+  'forgot.submit':  'Link senden',
+  'forgot.sent':    'Falls zu dieser E-Mail ein Konto existiert, ist ein Link unterwegs.',
+  'forgot.toLogin': '← Zurück zur Anmeldung',
+
+  'reset.title':   'Neues Passwort festlegen',
+  'reset.body':    'Wähle ein neues Passwort für dein Konto.',
+  'reset.submit':  'Passwort aktualisieren',
+  'reset.done':    'Dein Passwort wurde aktualisiert. Du kannst dich jetzt anmelden.',
+  'reset.failed':  'Dieser Link ist ungültig oder abgelaufen. Fordere einen neuen an.',
+  'reset.toLogin': '← Zurück zur Anmeldung',
+
+  'magic.title':   'Mit einem Link anmelden',
+  'magic.body':    'Wir senden dir einen einmaligen Anmeldelink — kein Passwort nötig.',
+  'magic.submit':  'Link senden',
+  'magic.sent':    'Falls zu dieser E-Mail ein Konto existiert, ist ein Anmeldelink unterwegs.',
+  'magic.toLogin': '← Zurück zur Anmeldung',
+
+  'verify.title':   'Dein Link wird geprüft',
+  'verify.pending': 'Einen Moment, wir melden dich an…',
+  'verify.success': 'Geschafft — du wirst weitergeleitet…',
+  'verify.failed':  'Dieser Link ist ungültig oder abgelaufen. Fordere einen neuen an.',
+  'verify.noToken': 'Diesem Link fehlt sein Token. Fordere einen neuen an.',
+  'verify.toLogin': '← Zurück zur Anmeldung',
+
+  'logout.title': 'Abmeldung',
+  'logout.body':  'Du wirst abgemeldet…',
+
+  'pw.weak':   'Schwach',
+  'pw.fair':   'Mittel',
+  'pw.good':   'Gut',
+  'pw.strong': 'Stark',
+})

package/templates/apps/frontend-auth/src/locales/en.ts

@@ -0,0 +1,76 @@
+// Base catalog — the source of truth for this app's UI strings. Every key here
+// MUST be mirrored in `de.ts`; `defineLocale<typeof en>()` enforces that parity
+// at build time.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  // Browser tab titles — locale-aware via each page's `meta({ locale })`.
+  'meta.login.title':  'Sign in',
+  'meta.signup.title': 'Create account',
+  'meta.forgot.title': 'Reset password',
+  'meta.reset.title':  'Set a new password',
+  'meta.magic.title':  'Magic link',
+  'meta.verify.title': 'Verifying',
+  'meta.logout.title': 'Signing out',
+
+  'lang.label': 'Language',
+
+  // ---- Shared field labels ----
+  'auth.email':       'Email',
+  'auth.password':    'Password',
+  'auth.newPassword': 'New password',
+  'auth.pending':     'Please wait…',
+  'auth.error':       'That didn’t work. Check your details and try again.',
+
+  // ---- Sign in ----
+  'login.title':    'Sign in',
+  'login.submit':   'Sign in',
+  'login.forgot':   'Forgot password?',
+  'login.magic':    'Email me a link',
+  'login.toSignup': 'Create an account',
+
+  // ---- Sign up ----
+  'signup.title':   'Create your account',
+  'signup.submit':  'Create account',
+  'signup.toLogin': 'Have an account? Sign in',
+
+  // ---- Forgot password ----
+  'forgot.title':   'Reset your password',
+  'forgot.body':    'Enter your email and we’ll send you a reset link.',
+  'forgot.submit':  'Send reset link',
+  'forgot.sent':    'If that email has an account, a reset link is on its way.',
+  'forgot.toLogin': '← Back to sign in',
+
+  // ---- Reset password ----
+  'reset.title':   'Set a new password',
+  'reset.body':    'Choose a new password for your account.',
+  'reset.submit':  'Update password',
+  'reset.done':    'Your password has been updated. You can sign in now.',
+  'reset.failed':  'That reset link is invalid or has expired. Request a new one.',
+  'reset.toLogin': '← Back to sign in',
+
+  // ---- Magic link ----
+  'magic.title':   'Sign in with a link',
+  'magic.body':    'We’ll email you a one-time sign-in link — no password needed.',
+  'magic.submit':  'Send me a link',
+  'magic.sent':    'If that email has an account, a sign-in link is on its way.',
+  'magic.toLogin': '← Back to sign in',
+
+  // ---- Verify (link consumer) ----
+  'verify.title':   'Verifying your link',
+  'verify.pending': 'One moment while we sign you in…',
+  'verify.success': 'You’re in — redirecting…',
+  'verify.failed':  'That link is invalid or has expired. Request a new one.',
+  'verify.noToken': 'This link is missing its token. Request a new one.',
+  'verify.toLogin': '← Back to sign in',
+
+  // ---- Logout ----
+  'logout.title': 'Signing out',
+  'logout.body':  'Signing you out…',
+
+  // ---- Password strength meter ----
+  'pw.weak':   'Weak',
+  'pw.fair':   'Fair',
+  'pw.good':   'Good',
+  'pw.strong': 'Strong',
+} as const)

package/templates/apps/frontend-auth/src/locales/index.ts

@@ -0,0 +1,14 @@
+// Catalog lookup OUTSIDE React — for a page's `meta({ locale })` locale-aware
+// <title>. This app is cookie-i18n (no `/<locale>` URL prefix), so @voltro/web
+// hands `meta` the active locale from the `voltro:lang` cookie. Inside React use
+// `<T>` / `useT()` via the framework's auto-wired <I18nProvider> instead.
+import en from './en'
+import de from './de'
+
+// Both catalogs share `en`'s keys (defineLocale enforces the mirror), so a
+// known-key lookup returns `string` — which is what `PageMeta.title` requires
+// under exactOptionalPropertyTypes.
+export type Messages = Record<keyof typeof en, string>
+
+export const getCatalog = (locale?: string): Messages =>
+  (locale === 'de' ? de : en) as Messages

package/templates/apps/frontend-auth/src/pages/forgot/page.tsx

@@ -0,0 +1,51 @@
+// Forgot password — URL `/forgot`. POST /auth/password-reset { email } always
+// returns 202 (no account enumeration — the same "check your email" whether or
+// not the address exists). The api emails a link to `/reset?token=…` (delivery
+// needs `sendEmail` wired on the api; without it the route still 202s).
+import type { ReactNode } from 'react'
+import { useState, type FormEvent } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useT } from '@voltro/i18n'
+import { AuthShell } from '../../components/AuthShell'
+import { postAuth } from '../../lib/auth'
+import { getCatalog } from '../../locales'
+
+export const renderMode = 'static' as const
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.forgot.title'],
+})
+
+export default function Forgot(): ReactNode {
+  const [email, setEmail] = useState('')
+  const [pending, setPending] = useState(false)
+  const [sent, setSent] = useState(false)
+  const emailLabel = useT('auth.email')
+
+  const onSubmit = (e: FormEvent): void => {
+    e.preventDefault()
+    setPending(true)
+    void postAuth('/auth/password-reset', { email })
+      .then(() => { setSent(true); setPending(false) })
+      .catch(() => { setSent(true); setPending(false) }) // still show the neutral message
+  }
+
+  return (
+    <AuthShell titleId="forgot.title" footer={<a href="/login"><T id="forgot.toLogin" /></a>}>
+      {sent ? (
+        <p className="ok" role="status"><T id="forgot.sent" /></p>
+      ) : (
+        <form className="auth-form" onSubmit={onSubmit}>
+          <p className="muted"><T id="forgot.body" /></p>
+          <label>
+            <span><T id="auth.email" /></span>
+            <input type="email" required aria-label={emailLabel} value={email} onChange={(e) => setEmail(e.target.value)} />
+          </label>
+          <button type="submit" className="btn" disabled={pending}>
+            <T id={pending ? 'auth.pending' : 'forgot.submit'} />
+          </button>
+        </form>
+      )}
+    </AuthShell>
+  )
+}

package/templates/apps/frontend-auth/src/pages/layout.tsx

@@ -0,0 +1,12 @@
+// Root layout — wraps EVERY page (marketing + dashboard). Thin: it loads the
+// stylesheet and lets each AREA layout ((marketing)/layout.tsx,
+// dashboard/layout.tsx) supply its own chrome. Layouts nest, so a dashboard
+// page is wrapped root → dashboard.
+//
+// Don't render <html>/<head>/<body> here — the framework shell owns them.
+import type { ReactNode } from 'react'
+import '../globals.css'
+
+export default function RootLayout({ children }: { readonly children: ReactNode }): ReactNode {
+  return <>{children}</>
+}