create-mithaq 0.0.0-stage → 0.2.0

package/template/apps/asas-tanstack/src/routes/(screens)/portal/types.ts

@@ -0,0 +1,94 @@
+// Written by `mithaq generate screens`. Do not edit.
+import type { ScreenClient as Client } from 'mithaq/admin'
+export type { PageClient } from 'mithaq/admin'
+export type CoursesValues = {
+  id: string
+  updatedAt: Date
+  createdAt: Date
+  organization: unknown
+  title: string
+  summary: string | null
+  fee: number | null
+  currency: 'SAR' | 'USD' | null
+  level: number | null
+  notifications: boolean | null
+  delivery: 'live' | 'recorded' | null
+  audience: 'beginner' | 'advanced' | null
+  accessCode: string | null
+  archived: boolean | null
+  topics: string[] | null
+  opensOn: string | null
+  archiveReason: string | null
+  tags: unknown[] | null
+  scheduledSessions: Values['sessions'][]
+  _status: 'draft' | 'published' | null
+  details: { root: Record<string, unknown> } | null
+  cover: string | null
+  selfEnroll: boolean | null
+}
+export type EnrollmentsValues = {
+  id: string
+  updatedAt: Date
+  createdAt: Date
+  organization: unknown
+  session: string
+  student: string
+  deletedAt: Date | null
+}
+export type SessionsValues = {
+  id: string
+  updatedAt: Date
+  createdAt: Date
+  organization: unknown
+  course: string
+  startsAt: Date
+  capacity: number | null
+  venue: 'online' | 'campus' | null
+  format: 'workshop' | 'lecture' | null
+  archived: boolean | null
+  details: { root: Record<string, unknown> } | null
+  enrollments: Values['enrollments'][]
+  archiveReason: string | null
+}
+export type MediaValues = {
+  id: string
+  updatedAt: Date
+  createdAt: Date
+  organization: unknown
+  filename: string
+  mimeType: string
+  filesize: number
+  width: number | null
+  height: number | null
+  key: string
+  storage: string
+  alt: Record<'ar' | 'en', string>
+}
+export type UserValues = {
+  id: string
+  updatedAt: Date
+  createdAt: Date
+  name: string
+  email: string
+  emailVerified: boolean
+  image: string | null
+  role: string | null
+  banned: boolean | null
+  banReason: string | null
+  banExpires: Date | null
+}
+export type Values = {
+  courses: CoursesValues
+  enrollments: EnrollmentsValues
+  sessions: SessionsValues
+  media: MediaValues
+  user: UserValues
+}
+export type Pages = {
+  courses: 'list' | 'view'
+  enrollments: 'list' | 'create' | 'edit'
+  sessions: never
+  media: never
+  user: never
+}
+export type ScreenClient = Client<Pages>

package/template/apps/asas-tanstack/src/routes/(screens)/portal.$.tsx

@@ -0,0 +1,17 @@
+// Written by `mithaq generate screens`. Do not edit.
+import { createFileRoute } from '@tanstack/react-router'
+import { ScreenNotFound, ScreenPageView, askedFor, pageHead, pageLoader } from '@/screens.tsx'
+import { files } from './portal/files.ts'
+
+export const Route = createFileRoute('/(screens)/portal/$')({
+  validateSearch: askedFor,
+  loader: ({ location, params }) => pageLoader({ screen: 'portal', files, path: params._splat ?? '', query: location.search, href: location.href }),
+  head: ({ loaderData, match }) => pageHead(loaderData, match.context),
+  notFoundComponent: () => <ScreenNotFound files={files} screen={'portal'} />,
+  component: Page,
+})
+
+function Page() {
+  const navigate = Route.useNavigate()
+  return <ScreenPageView files={files} data={Route.useLoaderData()} query={Route.useSearch()} onQuery={(search) => void navigate({ search })} />
+}

package/template/apps/asas-tanstack/src/routes/(screens)/portal.index.tsx

@@ -0,0 +1,10 @@
+// Written by `mithaq generate screens`. Do not edit.
+import { createFileRoute } from '@tanstack/react-router'
+import { ScreenPageView, askedFor, pageHead, pageLoader } from '@/screens.tsx'
+import { files } from './portal/files.ts'
+
+export const Route = createFileRoute('/(screens)/portal/')({
+  loader: ({ location }) => pageLoader({ screen: 'portal', files, path: '', query: {}, href: location.href }),
+  head: ({ loaderData, match }) => pageHead(loaderData, match.context),
+  component: () => <ScreenPageView files={files} data={Route.useLoaderData()} query={askedFor({})} onQuery={() => {}} />,
+})

package/template/apps/asas-tanstack/src/routes/(screens)/portal.tsx

@@ -0,0 +1,13 @@
+// Written by `mithaq generate screens`. Do not edit.
+import { Outlet, createFileRoute } from '@tanstack/react-router'
+import { ScreenFrame, frameLoader } from '@/screens.tsx'
+import { files } from './portal/files.ts'
+
+export const Route = createFileRoute('/(screens)/portal')({
+  loader: ({ location }) => frameLoader({ screen: 'portal', files, href: location.href }),
+  component: () => (
+    <ScreenFrame files={files} data={Route.useLoaderData()}>
+      <Outlet />
+    </ScreenFrame>
+  ),
+})

package/template/apps/asas-tanstack/src/routes/__root.tsx

@@ -0,0 +1,99 @@
+import { HeadContent, Outlet, Scripts, createRootRoute } from '@tanstack/react-router'
+import { DirectionProvider } from '@/components/ui/direction'
+export { locales } from '../copy.ts'
+import { dirOf, documentHead, localeOf, translator } from '../copy.ts'
+import { ThemeProvider } from 'mithaq-admin/theme.tsx'
+import { themeStorageKey } from '../theme.ts'
+import appCss from '../styles.css?url'
+
+/**
+ * Puts the chosen theme on the document before the first paint, which React cannot do: it
+ * reads `localStorage` only after mount. Also reloads a page restored from the back-forward
+ * cache, so Back after signing out asks the server again instead of showing the signed-in page.
+ */
+const theme = `
+              (function() {
+                var storageKey = ${JSON.stringify(themeStorageKey)};
+                var defaultTheme = "system";
+                try {
+                  var theme = localStorage.getItem(storageKey) || defaultTheme;
+                  var systemTheme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+                  var root = document.documentElement;
+                  root.classList.remove("light", "dark");
+                  root.classList.add(theme === "system" ? systemTheme : theme);
+                } catch (e) {}
+                window.addEventListener("pageshow", function (event) {
+                  if (event.persisted) location.reload();
+                });
+              })()
+            `
+
+/**
+ * An unregistered request context is `never` in the router's types, so the shape is named
+ * here and read through a cast; `localeOf` turns it back into a declared locale.
+ */
+type FromRequest = { serverContext?: { locale?: unknown } }
+
+export const Route = createRootRoute({
+  // On the client the locale is the `lang` the server wrote on `<html>`, so the hydrated tree matches
+  // the one sent. `localeOf` on both sides refuses a hand-edited `lang` or cookie.
+  beforeLoad: (ctx) => {
+    const locale =
+      typeof document === 'undefined'
+        ? localeOf((ctx as unknown as FromRequest).serverContext?.locale as string | undefined)
+        : localeOf(document.documentElement.lang)
+    return { locale, dir: dirOf(locale), app: 'marketing.brand' }
+  },
+  head: ({ match }) => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      // `_notFound` is the router's mark on the root match it draws the not-found for.
+      ...documentHead(match.context, match._notFound ? (t) => t('admin.notFoundTitle', 'Page not found') : undefined).meta,
+    ],
+    links: [{ rel: 'stylesheet', href: appCss }, { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
+  }),
+  // Without it the router draws a development-only placeholder and warns.
+  notFoundComponent: NotFound,
+  component: RootDocument,
+})
+
+export const useCopy = () => {
+  const { dir, locale } = Route.useRouteContext()
+  return { dir, locale, t: translator(locale) }
+}
+
+function NotFound() {
+  const { t } = useCopy()
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-4 px-4 text-center">
+      <h1 className="text-2xl font-bold tracking-tight">{t('admin.notFoundTitle', 'Page not found')}</h1>
+      <p className="text-muted-foreground text-sm">{t('admin.notFound', 'That page does not exist.')}</p>
+      {/* An anchor, because `/` is no route here. */}
+      <a className="text-foreground text-sm underline underline-offset-4" href="/">
+        {t('admin.goHome', 'Go to the home page')}
+      </a>
+    </main>
+  )
+}
+
+function RootDocument() {
+  const { dir, locale } = useCopy()
+  return (
+    <html lang={locale} dir={dir} suppressHydrationWarning>
+      <head>
+        <HeadContent />
+        {/* Safe to write raw: the string is this module's own and carries no value from a request. */}
+        <script dangerouslySetInnerHTML={{ __html: theme }} />
+      </head>
+      <body>
+        <DirectionProvider direction={dir}>
+          <ThemeProvider defaultTheme="system" storageKey={themeStorageKey}>
+            <Outlet />
+          </ThemeProvider>
+        </DirectionProvider>
+        <Scripts />
+      </body>
+    </html>
+  )
+}

package/template/apps/asas-tanstack/src/routes/api/$.ts

@@ -0,0 +1,11 @@
+// `server` is a module augmentation `@tanstack/start-client-core` declares; the erased type-only
+// import below loads it, so this app still ships `@tanstack/react-router` alone.
+import { createFileRoute } from '@tanstack/react-router'
+import type {} from '@tanstack/start-client-core'
+import { asas } from 'asas'
+
+// `/api/$` because one handler owns all of `/api`. The generated `routeTree.gen.ts` sits under
+// `src/` so the root `tsc` sees the `FileRoutesByPath` augmentation that types this path.
+export const Route = createFileRoute('/api/$')({
+  server: { handlers: { ANY: ({ request }) => asas.handler(request) } },
+})

package/template/apps/asas-tanstack/src/routes/auth.accept-invitation.tsx

@@ -0,0 +1,108 @@
+import { useEffect, useState } from 'react'
+import { Link, createFileRoute, useNavigate } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { authArm } from '../api.ts'
+import { documentHead } from '../copy.ts'
+import { AuthFrame, authGate, useHomeLabel, useRefusal } from '../auth-frame.tsx'
+import { useCopy } from './__root.tsx'
+import { landing } from '../redirect.ts'
+
+// Accepting is a POST the person presses, so following a link alone joins nobody to anything.
+// The provider decides whether the invitation is theirs.
+
+export const Route = createFileRoute('/auth/accept-invitation')({
+  head: ({ match }) => documentHead(match.context, (t) => t('auth.invitation')),
+  validateSearch: (search: Record<string, unknown>): { id?: string } => (typeof search.id === 'string' && search.id ? { id: search.id } : {}),
+  beforeLoad: () => authGate(),
+  component: AcceptInvitation,
+})
+
+function AcceptInvitation() {
+  const { t, locale } = useCopy()
+  const navigate = useNavigate()
+  const refused = useRefusal()
+  const { id } = Route.useSearch()
+  const { signedIn, home } = Route.useRouteContext()
+  const homeLabel = useHomeLabel()
+  const [organization, setOrganization] = useState<string>()
+  const [gone, setGone] = useState<string>()
+  const [pending, setPending] = useState(false)
+  const [refusal, setRefusal] = useState<string>()
+  const title = t('auth.invitation', 'Invitation')
+
+  useEffect(() => {
+    if (!signedIn || !id) return
+    fetch(`/api/auth/user/organization/get-invitation?id=${encodeURIComponent(id)}`)
+      .then(async (response) => {
+        const body = (await response.json().catch(() => null)) as { organizationName?: string; organizationNames?: Record<string, string>; code?: unknown } | null
+        if (response.ok) return setOrganization(body?.organizationNames?.[locale] || body?.organizationName || '')
+        // Better Auth answers a missing, spent or expired invitation 400 with no code.
+        setGone(refused({ status: response.status, body }, t('auth.invitationGone', 'This invitation has expired, was cancelled or was already accepted. Ask whoever invited you to send a new one.')))
+      })
+      .catch(() => setGone(t('auth.requestFailed', 'That request did not work.')))
+  }, [signedIn, id, locale])
+
+  const accept = async () => {
+    setPending(true)
+    setRefusal(undefined)
+    const answered = await authArm('organization/accept-invitation', { invitationId: id })
+    if (!answered.ok) {
+      setPending(false)
+      return setRefusal(refused(answered, t('auth.invitationAcceptFailed', 'That invitation could not be accepted.')))
+    }
+    // The provider made the organization active as it accepted, so the first screen is read as a member.
+    await navigate({ href: landing({ asked: undefined, screens: (await authGate()).screens }) })
+  }
+
+  if (!id) return <AuthFrame title={title} description={t('auth.invitationMissing', 'This link names no invitation.')}>{null}</AuthFrame>
+  if (!signedIn) {
+    const here = `/auth/accept-invitation?id=${encodeURIComponent(id)}`
+    return (
+      <AuthFrame title={title} description={t('auth.invitationSignedOut', 'Sign in, or make an account with the email address the invitation was sent to, to accept it.')}>
+        <div className="grid gap-2">
+          <Button nativeButton={false} render={<Link to="/auth/sign-in" search={{ redirect: here }} />}>
+            {t('auth.signIn', 'Sign in')}
+          </Button>
+          <Button variant="outline" nativeButton={false} render={<Link to="/auth/sign-up" search={{ redirect: here }} />}>
+            {t('auth.signUp', 'Sign up')}
+          </Button>
+        </div>
+      </AuthFrame>
+    )
+  }
+  if (gone) {
+    return (
+      <AuthFrame title={title}>
+        <div className="grid gap-4">
+          <p role="alert" data-invitation-gone="" className="text-sm">
+            {gone}
+          </p>
+          {/* A spent invitation is no dead end for someone already in: the way to their own first screen. An anchor,
+              because the path is the screen's own data, not a route the router knows. */}
+          <Button nativeButton={false} render={<a href={home.path} data-home="" />}>
+            {homeLabel(home, 'marketing.openScreen')}
+          </Button>
+          {/* The invitation may be another address's, which signing out and in again reaches. */}
+          <Button type="button" variant="outline" onClick={() => void authArm('sign-out').then(() => window.location.reload())}>
+            {t('admin.signOut', 'Sign out')}
+          </Button>
+        </div>
+      </AuthFrame>
+    )
+  }
+  if (organization === undefined) return <AuthFrame title={title} description={t('auth.invitationReading', 'Reading the invitation…')}>{null}</AuthFrame>
+  return (
+    <AuthFrame title={title} description={t('auth.invitationJoin', 'You are invited to join {organization}.')!.replace('{organization}', () => organization)}>
+      <div className="grid gap-4">
+        {refusal ? (
+          <p className="text-destructive text-sm" role="alert">
+            {refusal}
+          </p>
+        ) : null}
+        <Button type="button" data-button="accept-invitation" disabled={pending} onClick={() => void accept()}>
+          {pending ? t('auth.invitationAccepting', 'Accepting…') : t('auth.invitationAccept', 'Accept the invitation')}
+        </Button>
+      </div>
+    </AuthFrame>
+  )
+}

package/template/apps/asas-tanstack/src/routes/auth.first-run.tsx

@@ -0,0 +1,114 @@
+import { useState, type ComponentProps } from 'react'
+import { createFileRoute, redirect, useNavigate } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { authArm } from '../api.ts'
+import { AuthBox, AuthFrame, authGate, notAnEmail, useRefusal } from '../auth-frame.tsx'
+import { documentHead } from '../copy.ts'
+import { firstRun } from '../first-run.ts'
+import { useCopy } from './__root.tsx'
+
+// The first owner of an app of one organization, and the organization itself: open once,
+// to the holder of the setup code, and closed for good once the organization exists. The
+// organization's name lives in code (`organizationName` in `organizations.ts`), so none is asked.
+export const Route = createFileRoute('/auth/first-run')({
+  head: ({ match }) => documentHead(match.context, (t) => t('auth.firstRun')),
+  beforeLoad: async () => {
+    const state = await firstRun()
+    // `href`, not `to`: sign-in redirects here too, and two routes typed by each other's paths infer nothing.
+    if (!state.open) throw redirect({ href: '/auth/sign-in' })
+    return { code: state.code, password: (await authGate()).password }
+  },
+  component: FirstRun,
+})
+
+function FirstRun() {
+  const navigate = useNavigate()
+  const { t } = useCopy()
+  const refused = useRefusal()
+  const { code: asked, password: bounds } = Route.useRouteContext()
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [confirmation, setConfirmation] = useState('')
+  const [code, setCode] = useState('')
+  const [pending, setPending] = useState(false)
+  const [refusal, setRefusal] = useState<string | null>(null)
+  const [left, setLeft] = useState<ReadonlySet<string>>(() => new Set())
+  const required = t('auth.required', 'This field is required.')
+  const wrong = {
+    name: () => (name.trim() ? undefined : required),
+    email: () => (!email ? required : notAnEmail(email) ? t('auth.invalidEmail', 'Invalid email') : undefined),
+    password: () =>
+      !password ? required
+      : password.length < bounds.min ? t('auth.passwordTooShort', 'Password too short')
+      : password.length > bounds.max ? t('auth.passwordTooLong', 'Password too long')
+      : undefined,
+    confirmation: () => (!confirmation ? required : confirmation === password ? undefined : t('auth.passwordsDiffer', 'The two passwords are not the same.')),
+    code: () => (asked !== 'required' || code ? undefined : required),
+  }
+  const errorOf = (box: keyof typeof wrong) => (left.has(box) ? wrong[box]() : undefined)
+  const box = (id: keyof typeof wrong, label: string | undefined, props: ComponentProps<'input'> & { description?: string }) => (
+    <AuthBox id={id} label={label} error={errorOf(id)} onLeave={() => setLeft((already) => new Set(already).add(id))} {...props} />
+  )
+
+  const submit = async (event: React.FormEvent) => {
+    event.preventDefault()
+    setLeft(new Set(Object.keys(wrong)))
+    if (Object.values(wrong).some((check) => check())) return
+    setPending(true)
+    setRefusal(null)
+    const made = await authArm('first-run', { name, email, password, ...(asked === 'required' && { code }) })
+    setPending(false)
+    if (!made.ok) return setRefusal(refused(made, t('auth.firstRunFailed', 'That owner could not be made.')))
+    await navigate({ to: '/auth/sign-in' })
+  }
+
+  if (asked === 'unset') {
+    return (
+      <AuthFrame title={t('auth.firstRun', 'Set up this app')}>
+        <p className="text-sm" role="alert">
+          {t('auth.firstRunCodeUnset')}
+        </p>
+      </AuthFrame>
+    )
+  }
+  return (
+    <AuthFrame title={t('auth.firstRun', 'Set up this app')} description={t('auth.firstRunDescription', 'Nobody owns this app yet. The account made here becomes its owner and first administrator.')}>
+      <form className="grid gap-4" noValidate onSubmit={submit}>
+        {box('name', t('auth.name', 'Name'), { autoComplete: 'name', onChange: (event) => setName(event.target.value), type: 'text', value: name })}
+        {box('email', t('auth.email', 'Email'), { autoComplete: 'email', onChange: (event) => setEmail(event.target.value), type: 'email', value: email })}
+        {box('password', t('auth.password', 'Password'), {
+          autoComplete: 'new-password',
+          description: t('auth.passwordRule', 'At least {count} characters.')!.replace('{count}', String(bounds.min)),
+          onChange: (event) => setPassword(event.target.value),
+          type: 'password',
+          value: password,
+        })}
+        {box('confirmation', t('auth.confirmPassword', 'Confirm the password'), {
+          autoComplete: 'new-password',
+          onChange: (event) => setConfirmation(event.target.value),
+          type: 'password',
+          value: confirmation,
+        })}
+        {asked === 'required'
+          ? box('code', t('auth.setupCode', 'Setup code'), {
+              autoComplete: 'off',
+              description: t('auth.setupCodeDescription', 'The SETUP_CODE this server was started with.'),
+              onChange: (event) => setCode(event.target.value),
+              type: 'password',
+              value: code,
+            })
+          : null}
+        {/* `role="alert"` so a refusal is spoken when it appears; nothing moves the focus to it. */}
+        {refusal && (
+          <p className="text-destructive text-sm" role="alert">
+            {refusal}
+          </p>
+        )}
+        <Button disabled={pending} type="submit">
+          {pending ? t('auth.firstRunPending', 'Setting up…') : t('auth.firstRunSubmit', 'Set up the app')}
+        </Button>
+      </form>
+    </AuthFrame>
+  )
+}

package/template/apps/asas-tanstack/src/routes/auth.forgot-password.tsx

@@ -0,0 +1,94 @@
+import { useState } from 'react'
+import { Link, createFileRoute } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { authArm } from '../api.ts'
+import { documentHead } from '../copy.ts'
+import { AlreadySignedIn, AuthBox, AuthFrame, authGate, notAnEmail, redirectSearch, useRefusal } from '../auth-frame.tsx'
+import { useCopy } from './__root.tsx'
+
+// The sentence after a request is the same whether or not the address has an account, so
+// nothing on this page says which it was.
+
+export const Route = createFileRoute('/auth/forgot-password')({
+  head: ({ match }) => documentHead(match.context, (t) => t('auth.forgotPassword')),
+  validateSearch: redirectSearch,
+  beforeLoad: () => authGate(),
+  component: ForgotPassword,
+})
+
+function ForgotPassword() {
+  const { t } = useCopy()
+  const search = Route.useSearch()
+  const { signedIn, home, screens } = Route.useRouteContext()
+  const refused = useRefusal()
+  const [email, setEmail] = useState('')
+  const [left, setLeft] = useState(false)
+  const [pending, setPending] = useState(false)
+  const [sent, setSent] = useState(false)
+  const [refusal, setRefusal] = useState<string | null>(null)
+  const wrong = () => (!email ? t('auth.required', 'This field is required.') : notAnEmail(email) ? t('auth.invalidEmail', 'Invalid email') : undefined)
+  const back = (
+    <p className="mt-4 text-center text-sm">
+      <Link className="text-primary underline underline-offset-4" to="/auth/sign-in" search={{ redirect: search.redirect }}>
+        {t('auth.backToSignIn', 'Back to login')}
+      </Link>
+    </p>
+  )
+
+  const submit = async (event: React.FormEvent) => {
+    event.preventDefault()
+    setLeft(true)
+    if (wrong()) return
+    setPending(true)
+    setRefusal(null)
+    const answered = await authArm('request-password-reset', { email })
+    setPending(false)
+    if (!answered.ok) return setRefusal(refused(answered, t('auth.requestFailed', 'That request did not work.')))
+    setSent(true)
+  }
+
+  if (signedIn) return <AlreadySignedIn redirect={search.redirect} home={home} screens={screens} />
+  if (sent) {
+    return (
+      <AuthFrame
+        title={t('auth.emailSent', 'Email sent')}
+        description={t('auth.checkYourEmail', "If the email address is associated with an account, you will receive instructions to reset your password shortly. Please check your spam or junk mail folder if you don't see the email in your inbox.")}
+      >
+        {import.meta.env?.DEV ? (
+          <p data-no-mailer="" className="text-muted-foreground rounded-md border px-3 py-2 text-sm">
+            {t('auth.noMailer', 'No mailer is configured, so no email was sent. In development the reset link is written to the server log.')}
+          </p>
+        ) : null}
+        {back}
+      </AuthFrame>
+    )
+  }
+  return (
+    <AuthFrame
+      title={t('auth.forgotPassword', 'Forgot password')}
+      description={t('auth.forgotPasswordInstructions', 'Please enter your email below. You will receive an email message with instructions on how to reset your password.')}
+    >
+      <form className="grid gap-4" noValidate onSubmit={submit}>
+        <AuthBox
+          autoComplete="email"
+          error={left ? wrong() : undefined}
+          id="email"
+          label={t('auth.email', 'Email')}
+          onChange={(event) => setEmail(event.target.value)}
+          onLeave={() => setLeft(true)}
+          type="email"
+          value={email}
+        />
+        {refusal && (
+          <p className="text-destructive text-sm" role="alert">
+            {refusal}
+          </p>
+        )}
+        <Button disabled={pending} type="submit">
+          {t('auth.submit', 'Submit')}
+        </Button>
+      </form>
+      {back}
+    </AuthFrame>
+  )
+}

package/template/apps/asas-tanstack/src/routes/auth.handoff.ts

@@ -0,0 +1,39 @@
+// Trades the backoffice's one-time impersonation token for the session through the plugin's own
+// verify, then lands on the first screen the impersonated person may enter. The access report is
+// read with only the session the verify set, so the landing grants nothing. A spent, expired or
+// unknown token sets nothing and lands on sign-in.
+import { createFileRoute } from '@tanstack/react-router'
+import type {} from '@tanstack/start-client-core'
+
+const firstScreen = (targets: unknown, listed: readonly string[], backoffice: string) => {
+  const screens = targets as Record<string, { capability?: string; client?: { path: string } } | undefined>
+  const name = listed.find((one) => one !== backoffice && screens[one]?.capability === 'screen')
+  return name ? screens[name]!.client!.path : '/unauthorized'
+}
+
+export const Route = createFileRoute('/auth/handoff')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { asas, tenantURL, BACKOFFICE_SCREEN } = await import('asas')
+        // The deployment's own origin, never the request's, whose host a caller writes.
+        const own = new URL(tenantURL).origin
+        const verified = await asas.handler(
+          new Request(new URL('/api/auth/user/one-time-token/verify', own), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', origin: own },
+            body: JSON.stringify({ token: new URL(request.url).searchParams.get('token') ?? '' }),
+          }),
+        )
+        const cookies = verified.headers.getSetCookie()
+        const session = cookies.map((cookie) => cookie.split(';')[0]).join('; ')
+        const report = verified.ok
+          ? ((await (await asas.handler(new Request(new URL('/api/access', own), { headers: { cookie: session } }))).json().catch(() => ({}))) as { screens?: string[] })
+          : undefined
+        const headers = new Headers({ location: report ? firstScreen(asas.targets, report.screens ?? [], BACKOFFICE_SCREEN) : '/auth/sign-in' })
+        for (const cookie of cookies) headers.append('set-cookie', cookie)
+        return new Response(null, { status: 302, headers })
+      },
+    },
+  },
+})

package/template/apps/asas-tanstack/src/routes/auth.reset-password.tsx

@@ -0,0 +1,16 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { documentHead } from '../copy.ts'
+import { ChoosePassword, passwordGate, tokenSearch } from '../choose-password.tsx'
+
+// Where a forgotten password's link lands. A first password, chosen from a sign-up's or an added person's link, has a
+// page of its own, `/auth/set-password`, with the same form.
+export const Route = createFileRoute('/auth/reset-password')({
+  head: ({ match }) => documentHead(match.context, (t) => t('auth.resetPassword')),
+  validateSearch: tokenSearch,
+  beforeLoad: ({ search }: { search: { token?: string } }) => passwordGate(search),
+  component: ResetPassword,
+})
+
+function ResetPassword() {
+  return <ChoosePassword {...Route.useSearch()} {...Route.useRouteContext()} first={false} />
+}

package/template/apps/asas-tanstack/src/routes/auth.set-password.tsx

@@ -0,0 +1,16 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { documentHead } from '../copy.ts'
+import { ChoosePassword, passwordGate, tokenSearch } from '../choose-password.tsx'
+
+// Where a sign-up's or an added person's link lands: a brand-new account chooses its first password here, under a
+// title that says so, and never reads that it is resetting one.
+export const Route = createFileRoute('/auth/set-password')({
+  head: ({ match }) => documentHead(match.context, (t) => t('auth.setPassword')),
+  validateSearch: tokenSearch,
+  beforeLoad: ({ search }: { search: { token?: string } }) => passwordGate(search),
+  component: SetPassword,
+})
+
+function SetPassword() {
+  return <ChoosePassword {...Route.useSearch()} {...Route.useRouteContext()} first />
+}