create-aelith-app 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# create-aelith-app
+
+Scaffold a Next.js starter wired for Aelith hosted auth and SDK wallet auth.
+
+## Usage
+
+```bash
+npm create aelith-app@latest my-app
+```
+
+Or run the local checkout directly while developing the CLI:
+
+```bash
+node ./bin/index.js my-app
+```
+
+## What it generates
+
+- Next.js 16 App Router starter with TypeScript and Tailwind CSS v4
+- Solana wallet adapter wiring for Phantom, Solflare, and Backpack
+- Hosted login callback route at `/api/auth/aelith/callback`
+- SDK session route at `/api/auth/aelith/session`
+- A small demo UI that shows both login modes and the verified session state
+
+## Local development
+
+```bash
+npm install
+node ./bin/index.js demo-app --skip-install
+```
+
+The scaffold replaces `__APP_NAME__` and `__APP_ID__` tokens throughout the template before writing the new project.

package/bin/index.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { cp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { createInterface } from 'node:readline/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'template')
+const TEXT_FILE_EXTENSIONS = new Set([
+  '.css',
+  '.example',
+  '.gitignore',
+  '.js',
+  '.json',
+  '.md',
+  '.mjs',
+  '.ts',
+  '.tsx',
+  '.txt',
+])
+
+function getErrorMessage(error, fallback) {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message
+  }
+
+  return fallback
+}
+
+function isTextFile(filePath) {
+  const extension = path.extname(filePath).toLowerCase()
+  return (
+    TEXT_FILE_EXTENSIONS.has(extension) ||
+    path.basename(filePath) === '.gitignore' ||
+    path.basename(filePath).startsWith('.env')
+  )
+}
+
+function slugifyAppId(value) {
+  const normalized = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50)
+
+  return normalized || 'aelith-app'
+}
+
+async function promptForProjectName() {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+
+  try {
+    const answer = await rl.question('Project name: ')
+    return answer.trim()
+  } finally {
+    rl.close()
+  }
+}
+
+async function ensureTargetDirectory(targetDir) {
+  if (!existsSync(targetDir)) {
+    return
+  }
+
+  const entries = await readdir(targetDir)
+  if (entries.length > 0) {
+    throw new Error(`Target directory already exists and is not empty: ${targetDir}`)
+  }
+}
+
+async function replaceTokensInDirectory(targetDir, replacements) {
+  const entries = await readdir(targetDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const absolutePath = path.join(targetDir, entry.name)
+
+    if (entry.isDirectory()) {
+      await replaceTokensInDirectory(absolutePath, replacements)
+      continue
+    }
+
+    if (!entry.isFile() || !isTextFile(absolutePath)) {
+      continue
+    }
+
+    let content = await readFile(absolutePath, 'utf8')
+    for (const [token, value] of Object.entries(replacements)) {
+      content = content.split(token).join(value)
+    }
+
+    await writeFile(absolutePath, content, 'utf8')
+  }
+}
+
+async function installDependencies(targetDir) {
+  await new Promise((resolve, reject) => {
+    const command = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+    const child = spawn(command, ['install'], {
+      cwd: targetDir,
+      stdio: 'inherit',
+    })
+
+    child.on('error', reject)
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve()
+        return
+      }
+
+      reject(new Error(`npm install exited with code ${code ?? 'unknown'}.`))
+    })
+  })
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const skipInstall = args.includes('--skip-install')
+  const rawProjectName = args.find((arg) => !arg.startsWith('-')) ?? await promptForProjectName()
+
+  if (!rawProjectName) {
+    throw new Error('Project name is required.')
+  }
+
+  const projectName = rawProjectName.trim()
+  const targetDir = path.resolve(process.cwd(), projectName)
+  const projectDirName = path.basename(targetDir)
+  const appId = slugifyAppId(projectDirName)
+
+  await ensureTargetDirectory(targetDir)
+  await mkdir(targetDir, { recursive: true })
+  await cp(TEMPLATE_DIR, targetDir, { recursive: true })
+  await replaceTokensInDirectory(targetDir, {
+    __APP_NAME__: projectDirName,
+    __APP_ID__: appId,
+  })
+
+  if (!skipInstall) {
+    console.log('')
+    console.log(`Installing dependencies in ${projectDirName}...`)
+    await installDependencies(targetDir)
+  }
+
+  console.log('')
+  console.log(`Aelith starter created at ${targetDir}`)
+  console.log('')
+  console.log('Next steps:')
+  console.log(`  cd ${projectName}`)
+  if (skipInstall) {
+    console.log('  npm install')
+  }
+  console.log('  cp .env.example .env.local')
+  console.log('  npm run dev')
+  console.log('')
+  console.log(
+    'Register http://localhost:3000/api/auth/aelith/callback at auth.aelith.ai -> your app -> redirect URIs'
+  )
+}
+
+main().catch((error) => {
+  console.error('')
+  console.error(getErrorMessage(error, 'Failed to create the Aelith starter.'))
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "create-aelith-app",
+  "version": "0.1.0",
+  "description": "CLI to scaffold a Next.js starter for Aelith authentication.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-aelith-app": "./bin/index.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "template/.env.example",
+    "template/.gitignore",
+    "template/next-env.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.9.0"
+  }
+}

package/template/.env.example

@@ -0,0 +1,6 @@
+NEXT_PUBLIC_AELITH_APP_ID=__APP_ID__
+NEXT_PUBLIC_AELITH_AUTH_ORIGIN=https://auth.aelith.ai
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+AELITH_API_KEY=replace_with_your_server_side_api_key
+AELITH_SESSION_COOKIE_NAME=__APP_ID___session

package/template/.gitignore

@@ -0,0 +1,8 @@
+node_modules
+.next
+out
+build
+.DS_Store
+.env.local
+next-env.d.ts
+tsconfig.tsbuildinfo

package/template/README.md

@@ -0,0 +1,49 @@
+# __APP_NAME__
+
+Starter project for Aelith hosted auth and SDK wallet auth with Next.js 16.
+
+Wallet support is wired with Phantom and Solflare adapters, and Wallet Standard wallets such as Backpack can still appear through the shared wallet-standard integration.
+
+## Setup
+
+```bash
+cp .env.example .env.local
+npm install
+npm run dev
+```
+
+Update `.env.local` before testing auth:
+
+```bash
+NEXT_PUBLIC_AELITH_APP_ID=__APP_ID__
+NEXT_PUBLIC_AELITH_AUTH_ORIGIN=https://auth.aelith.ai
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+AELITH_API_KEY=replace_with_your_server_side_api_key
+```
+
+## Portal wiring
+
+Register this redirect URI for your Aelith app:
+
+```text
+http://localhost:3000/api/auth/aelith/callback
+```
+
+The template demonstrates two paths:
+
+- Hosted mode: browser redirects to `auth.aelith.ai/login`, then returns to `/api/auth/aelith/callback`
+- SDK mode: the wallet signs locally, the browser exchanges the signature through `@aelith/auth-core`, then the app stores a verified session via `/api/auth/aelith/session`
+
+## Session route behavior
+
+`/api/auth/aelith/session` verifies tokens against `https://auth.aelith.ai/api/verify`, so `AELITH_API_KEY` must be set on the server side.
+
+## Useful files
+
+- `app/page.tsx`: starter landing page and setup notes
+- `app/api/auth/aelith/callback/route.ts`: hosted flow callback
+- `app/api/auth/aelith/session/route.ts`: local session store and verification route
+- `components/wallet-provider.tsx`: Solana wallet adapter wiring
+- `lib/aelith.ts`: public Aelith client config
+- `lib/session.ts`: server-only token verification helpers

package/template/app/api/auth/aelith/callback/route.ts

@@ -0,0 +1,36 @@
+import { NextRequest, NextResponse } from 'next/server'
+import {
+  buildAuthenticatedSessionState,
+  getSessionCookieName,
+  getSessionCookieOptions,
+  getSessionErrorMessage,
+} from '@/lib/session'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(request: NextRequest) {
+  const redirectUrl = new URL('/', request.url)
+  const token = request.nextUrl.searchParams.get('token')?.trim()
+  const onboarding = request.nextUrl.searchParams.get('onboarding')
+
+  if (!token) {
+    redirectUrl.searchParams.set('error', 'Hosted login did not include a token.')
+    return NextResponse.redirect(redirectUrl)
+  }
+
+  try {
+    await buildAuthenticatedSessionState(token)
+    redirectUrl.searchParams.set('flow', 'hosted')
+
+    if (onboarding === '1') {
+      redirectUrl.searchParams.set('onboarding', '1')
+    }
+
+    const response = NextResponse.redirect(redirectUrl)
+    response.cookies.set(getSessionCookieName(), token, getSessionCookieOptions())
+    return response
+  } catch (error) {
+    redirectUrl.searchParams.set('error', getSessionErrorMessage(error))
+    return NextResponse.redirect(redirectUrl)
+  }
+}

package/template/app/api/auth/aelith/session/route.ts

@@ -0,0 +1,91 @@
+import { NextRequest, NextResponse } from 'next/server'
+import {
+  buildAuthenticatedSessionState,
+  getBaseSessionState,
+  getClearedSessionCookieOptions,
+  getSessionCookieName,
+  getSessionCookieOptions,
+  getSessionErrorMessage,
+} from '@/lib/session'
+
+export const dynamic = 'force-dynamic'
+
+function json(body: unknown, init?: ResponseInit) {
+  return NextResponse.json(body, {
+    ...init,
+    headers: {
+      'Cache-Control': 'no-store',
+      ...(init?.headers ?? {}),
+    },
+  })
+}
+
+export async function GET(request: NextRequest) {
+  const token = request.cookies.get(getSessionCookieName())?.value
+  if (!token) {
+    return json(getBaseSessionState())
+  }
+
+  try {
+    const session = await buildAuthenticatedSessionState(token)
+    return json(session)
+  } catch (error) {
+    const response = json(
+      {
+        ...getBaseSessionState(),
+        error: getSessionErrorMessage(error),
+      },
+      { status: 200 }
+    )
+
+    response.cookies.set(getSessionCookieName(), '', getClearedSessionCookieOptions())
+    return response
+  }
+}
+
+export async function POST(request: NextRequest) {
+  const contentType = request.headers.get('content-type')?.toLowerCase() ?? ''
+  if (!contentType.includes('application/json')) {
+    return json(
+      {
+        ...getBaseSessionState(),
+        error: 'Expected an application/json request body.',
+      },
+      { status: 415 }
+    )
+  }
+
+  const body = (await request.json().catch(() => null)) as { token?: unknown } | null
+  const token = typeof body?.token === 'string' ? body.token.trim() : ''
+
+  if (!token) {
+    return json(
+      {
+        ...getBaseSessionState(),
+        error: 'token is required.',
+      },
+      { status: 400 }
+    )
+  }
+
+  try {
+    const session = await buildAuthenticatedSessionState(token)
+    const response = json(session)
+    response.cookies.set(getSessionCookieName(), token, getSessionCookieOptions())
+    return response
+  } catch (error) {
+    return json(
+      {
+        ...getBaseSessionState(),
+        error: getSessionErrorMessage(error),
+      },
+      { status: 400 }
+    )
+  }
+}
+
+export async function DELETE() {
+  const response = json(getBaseSessionState())
+  response.cookies.set(getSessionCookieName(), '', getClearedSessionCookieOptions())
+  return response
+}

package/template/app/globals.css

@@ -0,0 +1,170 @@
+@import 'tailwindcss';
+
+:root {
+  --font-sans: 'Avenir Next', 'Inter Tight', 'Segoe UI', sans-serif;
+  --font-mono: 'IBM Plex Mono', 'SFMono-Regular', 'Menlo', monospace;
+  --bg-0: #051019;
+  --bg-1: #0a1823;
+  --panel: rgba(7, 19, 29, 0.78);
+  --panel-strong: rgba(9, 24, 36, 0.92);
+  --border: rgba(255, 244, 228, 0.1);
+  --text-strong: #f9f5eb;
+  --text-soft: rgba(249, 245, 235, 0.72);
+  --signal: #ff936a;
+  --signal-soft: rgba(255, 147, 106, 0.18);
+  --mint: #73ffd1;
+  --mint-soft: rgba(115, 255, 209, 0.16);
+  --danger: #ff857d;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  color-scheme: dark;
+}
+
+body {
+  min-height: 100vh;
+  margin: 0;
+  background:
+    radial-gradient(circle at 18% 18%, rgba(255, 147, 106, 0.22), transparent 28%),
+    radial-gradient(circle at 80% 14%, rgba(115, 255, 209, 0.15), transparent 22%),
+    linear-gradient(180deg, var(--bg-0) 0%, var(--bg-1) 48%, #0b202c 100%);
+  color: var(--text-strong);
+  font-family: var(--font-sans), sans-serif;
+}
+
+body::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  opacity: 0.26;
+  background-image:
+    linear-gradient(rgba(255, 255, 255, 0.04) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.04) 1px, transparent 1px);
+  background-size: 96px 96px;
+  mask-image: radial-gradient(circle at center, black, transparent 82%);
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+::selection {
+  background: rgba(255, 147, 106, 0.28);
+  color: var(--text-strong);
+}
+
+.mono {
+  font-family: var(--font-mono), monospace;
+}
+
+.surface {
+  position: relative;
+  overflow: hidden;
+  border: 1px solid var(--border);
+  background: var(--panel);
+  box-shadow:
+    0 24px 80px rgba(0, 0, 0, 0.28),
+    inset 0 1px 0 rgba(255, 255, 255, 0.03);
+  backdrop-filter: blur(18px);
+}
+
+.hero-glow::after {
+  content: '';
+  position: absolute;
+  inset: auto -18% -44% auto;
+  width: 320px;
+  height: 320px;
+  border-radius: 999px;
+  background: radial-gradient(circle, rgba(255, 147, 106, 0.22), transparent 70%);
+  pointer-events: none;
+}
+
+.eyebrow {
+  font-family: var(--font-mono), monospace;
+  font-size: 0.76rem;
+  font-weight: 600;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: rgba(249, 245, 235, 0.55);
+}
+
+.meta-chip {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 999px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(255, 255, 255, 0.04);
+  padding: 0.65rem 0.9rem;
+  font-family: var(--font-mono), monospace;
+  font-size: 0.78rem;
+  color: rgba(249, 245, 235, 0.72);
+}
+
+.flow-card {
+  border-radius: 1.6rem;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: var(--panel-strong);
+  padding: 1.25rem;
+}
+
+.flow-card p:last-child {
+  margin-bottom: 0;
+}
+
+.notice {
+  border-radius: 1.2rem;
+  padding: 0.9rem 1rem;
+  font-size: 0.95rem;
+  line-height: 1.6;
+}
+
+.notice-success {
+  border: 1px solid rgba(115, 255, 209, 0.24);
+  background: rgba(115, 255, 209, 0.08);
+  color: #d9fff2;
+}
+
+.notice-error {
+  border: 1px solid rgba(255, 133, 125, 0.24);
+  background: rgba(255, 133, 125, 0.08);
+  color: #ffe3e0;
+}
+
+.session-grid {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 0.75rem 1rem;
+}
+
+.session-grid dt {
+  font-family: var(--font-mono), monospace;
+  font-size: 0.75rem;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: rgba(249, 245, 235, 0.46);
+}
+
+.session-grid dd {
+  margin: 0;
+  min-width: 0;
+  color: var(--text-strong);
+  word-break: break-word;
+}
+
+.wallet-button {
+  min-height: 48px !important;
+  border-radius: 999px !important;
+  background: linear-gradient(135deg, #ff936a 0%, #ffd165 100%) !important;
+  color: #041019 !important;
+  font-family: var(--font-sans), sans-serif !important;
+  font-size: 0.95rem !important;
+  font-weight: 700 !important;
+  line-height: 1 !important;
+  box-shadow: 0 20px 40px rgba(255, 147, 106, 0.22) !important;
+}

package/template/app/layout.tsx

@@ -0,0 +1,21 @@
+import './globals.css'
+import '@solana/wallet-adapter-react-ui/styles.css'
+
+import type { Metadata } from 'next'
+import type { ReactNode } from 'react'
+import { AelithWalletProvider } from '@/components/wallet-provider'
+
+export const metadata: Metadata = {
+  title: '__APP_NAME__',
+  description: 'Starter app for Aelith hosted auth and SDK wallet auth.',
+}
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <AelithWalletProvider>{children}</AelithWalletProvider>
+      </body>
+    </html>
+  )
+}

package/template/app/page.tsx

@@ -0,0 +1,81 @@
+import { AuthDemo } from '@/components/auth-demo'
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>
+
+function pickFirst(value: string | string[] | undefined) {
+  if (Array.isArray(value)) {
+    return value[0] ?? null
+  }
+
+  return value ?? null
+}
+
+export default async function Page({
+  searchParams,
+}: {
+  searchParams: SearchParams
+}) {
+  const params = await searchParams
+  const error = pickFirst(params.error)
+  const flow = pickFirst(params.flow)
+  const onboarding = pickFirst(params.onboarding)
+
+  const initialNotice = error
+    ? { tone: 'error' as const, message: error }
+    : flow === 'hosted'
+      ? {
+          tone: 'success' as const,
+          message:
+            onboarding === '1'
+              ? 'Hosted login finished and returned an onboarding token.'
+              : 'Hosted login finished and the callback route created a local session.',
+        }
+      : null
+
+  return (
+    <main className="mx-auto flex min-h-screen w-full max-w-7xl flex-col gap-8 px-6 pb-16 pt-10 sm:px-10 lg:px-12">
+      <section className="grid gap-6 lg:grid-cols-[1.2fr_0.8fr] lg:items-end">
+        <div className="surface hero-glow rounded-[2rem] p-8 sm:p-10">
+          <p className="eyebrow">Aelith Auth Starter</p>
+          <h1 className="mt-4 max-w-3xl text-4xl font-semibold tracking-[-0.04em] text-[var(--text-strong)] sm:text-6xl">
+            Ship wallet auth without rebuilding the boring parts.
+          </h1>
+          <p className="mt-5 max-w-2xl text-base leading-7 text-[var(--text-soft)] sm:text-lg">
+            This starter gives you a hosted login redirect, a local wallet signing flow,
+            and a server-verified demo session in one Next.js app.
+          </p>
+
+          <div className="mt-8 flex flex-wrap gap-3">
+            <span className="meta-chip">Next.js 16 App Router</span>
+            <span className="meta-chip">Tailwind CSS v4</span>
+            <span className="meta-chip">Phantom, Solflare, Backpack</span>
+          </div>
+        </div>
+
+        <aside className="surface rounded-[2rem] p-8">
+          <p className="eyebrow">First run</p>
+          <ol className="mt-5 space-y-4 text-sm leading-6 text-[var(--text-soft)]">
+            <li>
+              Copy <span className="mono">.env.example</span> to{' '}
+              <span className="mono">.env.local</span>.
+            </li>
+            <li>
+              Set <span className="mono">AELITH_API_KEY</span> so the session route can
+              verify returned tokens.
+            </li>
+            <li>
+              Register{' '}
+              <span className="mono">
+                http://localhost:3000/api/auth/aelith/callback
+              </span>{' '}
+              in the Aelith portal.
+            </li>
+            <li>Test hosted login, then test the SDK wallet flow after connecting a wallet.</li>
+          </ol>
+        </aside>
+      </section>
+
+      <AuthDemo initialNotice={initialNotice} />
+    </main>
+  )
+}

package/template/components/auth-demo.tsx

@@ -0,0 +1,325 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useWallet } from '@solana/wallet-adapter-react'
+import { WalletMultiButton } from '@solana/wallet-adapter-react-ui'
+import {
+  aelithClient,
+  getDefaultHostedRedirectUri,
+  getErrorMessage,
+  getHostedRedirectUri,
+  parseJson,
+  SESSION_ENDPOINT,
+  type AelithSessionState,
+  type NoticeState,
+} from '@/lib/aelith'
+import { LoginButton } from './login-button'
+
+type BusyState = 'session' | 'hosted' | 'sdk' | 'signout' | null
+
+async function requestSessionState() {
+  const response = await fetch(SESSION_ENDPOINT, {
+    method: 'GET',
+    credentials: 'include',
+    cache: 'no-store',
+  })
+
+  return parseJson<AelithSessionState>(response)
+}
+
+export function AuthDemo({
+  initialNotice,
+}: {
+  initialNotice: NoticeState | null
+}) {
+  const { connected, publicKey, signMessage } = useWallet()
+  const [session, setSession] = useState<AelithSessionState | null>(null)
+  const [notice, setNotice] = useState<NoticeState | null>(initialNotice)
+  const [busy, setBusy] = useState<BusyState>('session')
+
+  useEffect(() => {
+    let cancelled = false
+
+    void (async () => {
+      try {
+        const nextSession = await requestSessionState()
+        if (cancelled) {
+          return
+        }
+
+        setSession(nextSession)
+
+        if (nextSession.error && !nextSession.authenticated) {
+          setNotice({
+            tone: 'error',
+            message: nextSession.error,
+          })
+        }
+      } catch (error) {
+        if (cancelled) {
+          return
+        }
+
+        setNotice({
+          tone: 'error',
+          message: getErrorMessage(error, 'Failed to load the current session.'),
+        })
+      } finally {
+        if (!cancelled) {
+          setBusy(null)
+        }
+      }
+    })()
+
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  async function refreshSession() {
+    setBusy('session')
+
+    try {
+      const nextSession = await requestSessionState()
+      setSession(nextSession)
+
+      if (nextSession.error && !nextSession.authenticated) {
+        setNotice({
+          tone: 'error',
+          message: nextSession.error,
+        })
+      }
+    } catch (error) {
+      setNotice({
+        tone: 'error',
+        message: getErrorMessage(error, 'Failed to load the current session.'),
+      })
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  function startHostedLogin() {
+    setBusy('hosted')
+    window.location.assign(
+      aelithClient.buildHostedLoginUrl({
+        redirectUri: getHostedRedirectUri(),
+      })
+    )
+  }
+
+  async function handleSdkLogin() {
+    if (!publicKey || !signMessage) {
+      setNotice({
+        tone: 'error',
+        message: 'Connect a wallet with message signing before starting the SDK flow.',
+      })
+      return
+    }
+
+    setBusy('sdk')
+    setNotice(null)
+
+    try {
+      const result = await aelithClient.loginWithWallet({
+        walletAddress: publicKey.toBase58(),
+        signMessage,
+      })
+
+      const response = await fetch(SESSION_ENDPOINT, {
+        method: 'POST',
+        credentials: 'include',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ token: result.token }),
+      })
+
+      const nextSession = await parseJson<AelithSessionState>(response)
+      if (!response.ok || !nextSession.authenticated) {
+        throw new Error(nextSession.error ?? 'Failed to create a verified local session.')
+      }
+
+      setSession(nextSession)
+      setNotice({
+        tone: 'success',
+        message: result.isNew
+          ? 'SDK login finished and Aelith created a new identity for this wallet.'
+          : 'SDK login finished and the local session is now verified.',
+      })
+    } catch (error) {
+      setNotice({
+        tone: 'error',
+        message: getErrorMessage(error, 'SDK wallet login failed.'),
+      })
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  async function handleSignOut() {
+    setBusy('signout')
+
+    try {
+      const response = await fetch(SESSION_ENDPOINT, {
+        method: 'DELETE',
+        credentials: 'include',
+      })
+
+      const nextSession = await parseJson<AelithSessionState>(response)
+      setSession(nextSession)
+      setNotice({
+        tone: 'success',
+        message: 'The local demo session cookie has been cleared.',
+      })
+    } catch (error) {
+      setNotice({
+        tone: 'error',
+        message: getErrorMessage(error, 'Failed to clear the current session.'),
+      })
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  const callbackUri = getDefaultHostedRedirectUri()
+  const walletAddress = publicKey?.toBase58() ?? 'Wallet not connected'
+  const canUseSdk = Boolean(publicKey && signMessage)
+
+  return (
+    <section className="grid gap-6 lg:grid-cols-[1.1fr_0.9fr]">
+      <div className="surface rounded-[2rem] p-8">
+        <div className="flex flex-wrap items-center justify-between gap-4">
+          <div>
+            <p className="eyebrow">Live auth demo</p>
+            <h2 className="mt-3 text-2xl font-semibold tracking-[-0.03em] text-[var(--text-strong)]">
+              Compare hosted redirect against local wallet signing.
+            </h2>
+          </div>
+
+          <WalletMultiButton className="wallet-button" />
+        </div>
+
+        {notice ? (
+          <div
+            className={[
+              'notice mt-6',
+              notice.tone === 'success' ? 'notice-success' : 'notice-error',
+            ].join(' ')}
+          >
+            {notice.message}
+          </div>
+        ) : null}
+
+        <div className="mt-6 grid gap-4 md:grid-cols-2">
+          <article className="flow-card">
+            <p className="eyebrow">Hosted flow</p>
+            <h3 className="mt-3 text-xl font-semibold text-[var(--text-strong)]">
+              Redirect to the Aelith login app
+            </h3>
+            <p className="mt-3 text-sm leading-6 text-[var(--text-soft)]">
+              Uses the hosted login screen, returns to the callback route, then stores a
+              verified local session cookie.
+            </p>
+            <p className="mono mt-4 text-xs leading-6 text-[var(--text-soft)]">
+              callback: {callbackUri}
+            </p>
+            <LoginButton
+              className="mt-6 w-full"
+              onClick={startHostedLogin}
+              disabled={busy !== null}
+            >
+              {busy === 'hosted' ? 'Redirecting...' : 'Start hosted login'}
+            </LoginButton>
+          </article>
+
+          <article className="flow-card">
+            <p className="eyebrow">SDK flow</p>
+            <h3 className="mt-3 text-xl font-semibold text-[var(--text-strong)]">
+              Sign the challenge on your own origin
+            </h3>
+            <p className="mt-3 text-sm leading-6 text-[var(--text-soft)]">
+              Connect a wallet here, sign locally, exchange the signature through
+              <span className="mono"> @aelith/auth-core</span>, then verify and store the
+              session on the server.
+            </p>
+            <p className="mono mt-4 text-xs leading-6 text-[var(--text-soft)]">
+              wallet: {walletAddress}
+            </p>
+            <LoginButton
+              tone="mint"
+              className="mt-6 w-full"
+              onClick={handleSdkLogin}
+              disabled={busy !== null || !canUseSdk}
+            >
+              {busy === 'sdk' ? 'Signing and verifying...' : 'Run SDK wallet login'}
+            </LoginButton>
+          </article>
+        </div>
+
+        <div className="mt-6 rounded-[1.5rem] border border-white/10 bg-white/5 px-5 py-4 text-sm leading-6 text-[var(--text-soft)]">
+          {connected
+            ? 'Wallet connection is live. Use the SDK button when you are ready to sign the Aelith challenge.'
+            : 'Use the wallet button above to connect Phantom, Solflare, or Backpack before testing the SDK flow.'}
+        </div>
+      </div>
+
+      <aside className="surface rounded-[2rem] p-8">
+        <div className="flex items-start justify-between gap-4">
+          <div>
+            <p className="eyebrow">Verified session</p>
+            <h2 className="mt-3 text-2xl font-semibold tracking-[-0.03em] text-[var(--text-strong)]">
+              What the app currently knows
+            </h2>
+          </div>
+
+          <LoginButton
+            tone="ghost"
+            className="shrink-0"
+            onClick={() => void refreshSession()}
+            disabled={busy !== null}
+          >
+            {busy === 'session' ? 'Refreshing...' : 'Refresh'}
+          </LoginButton>
+        </div>
+
+        <div className="mt-6 session-grid text-sm leading-6">
+          <dt>Status</dt>
+          <dd>{session?.authenticated ? 'Authenticated' : 'Anonymous'}</dd>
+
+          <dt>Configured</dt>
+          <dd>{session?.configured ? 'Ready for verify calls' : 'Missing AELITH_API_KEY'}</dd>
+
+          <dt>User ID</dt>
+          <dd>{session?.userId ?? '-'}</dd>
+
+          <dt>Wallet</dt>
+          <dd>{session?.walletAddress ?? '-'}</dd>
+
+          <dt>Email</dt>
+          <dd>{session?.email ?? '-'}</dd>
+
+          <dt>App claim</dt>
+          <dd>{session?.app ?? '-'}</dd>
+
+          <dt>Auth origin</dt>
+          <dd className="mono text-xs">{session?.authOrigin ?? aelithClient.authOrigin}</dd>
+        </div>
+
+        <div className="mt-6 rounded-[1.5rem] border border-[var(--signal-soft)] bg-[var(--signal-soft)] px-5 py-4 text-sm leading-6 text-[var(--text-soft)]">
+          The local session route verifies tokens against{' '}
+          <span className="mono">/api/verify</span> using your server-side API key.
+        </div>
+
+        <LoginButton
+          tone="ghost"
+          className="mt-6 w-full"
+          onClick={handleSignOut}
+          disabled={busy !== null || !session?.authenticated}
+        >
+          {busy === 'signout' ? 'Clearing session...' : 'Clear local session'}
+        </LoginButton>
+      </aside>
+    </section>
+  )
+}

package/template/components/login-button.tsx

@@ -0,0 +1,38 @@
+'use client'
+
+import type { ButtonHTMLAttributes } from 'react'
+
+type LoginButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+  tone?: 'signal' | 'mint' | 'ghost'
+}
+
+function getToneClasses(tone: NonNullable<LoginButtonProps['tone']>) {
+  switch (tone) {
+    case 'mint':
+      return 'border-transparent bg-[var(--mint)] text-[#051019] shadow-[0_18px_40px_rgba(115,255,209,0.15)]'
+    case 'ghost':
+      return 'border-white/10 bg-white/5 text-[var(--text-strong)]'
+    case 'signal':
+    default:
+      return 'border-transparent bg-[var(--signal)] text-[#051019] shadow-[0_18px_40px_rgba(255,147,106,0.16)]'
+  }
+}
+
+export function LoginButton({
+  tone = 'signal',
+  className,
+  type = 'button',
+  ...props
+}: LoginButtonProps) {
+  return (
+    <button
+      type={type}
+      className={[
+        'inline-flex min-h-12 items-center justify-center rounded-full border px-5 py-3 text-sm font-semibold transition-transform duration-200 hover:-translate-y-0.5 disabled:cursor-not-allowed disabled:opacity-55',
+        getToneClasses(tone),
+        className ?? '',
+      ].join(' ')}
+      {...props}
+    />
+  )
+}

package/template/components/wallet-provider.tsx

@@ -0,0 +1,31 @@
+'use client'
+
+import {
+  PhantomWalletAdapter,
+  SolflareWalletAdapter,
+} from '@solana/wallet-adapter-wallets'
+import {
+  ConnectionProvider,
+  WalletProvider,
+} from '@solana/wallet-adapter-react'
+import { WalletModalProvider } from '@solana/wallet-adapter-react-ui'
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+
+const RPC_ENDPOINT =
+  process.env.NEXT_PUBLIC_SOLANA_RPC_URL?.trim() || 'https://api.mainnet-beta.solana.com'
+
+export function AelithWalletProvider({ children }: { children: ReactNode }) {
+  const [wallets] = useState(() => [
+    new PhantomWalletAdapter(),
+    new SolflareWalletAdapter(),
+  ])
+
+  return (
+    <ConnectionProvider endpoint={RPC_ENDPOINT}>
+      <WalletProvider wallets={wallets} autoConnect={false}>
+        <WalletModalProvider>{children}</WalletModalProvider>
+      </WalletProvider>
+    </ConnectionProvider>
+  )
+}

package/template/eslint.config.mjs

@@ -0,0 +1,17 @@
+import { defineConfig, globalIgnores } from 'eslint/config'
+import nextVitals from 'eslint-config-next/core-web-vitals'
+import nextTs from 'eslint-config-next/typescript'
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([
+    '.next/**',
+    'out/**',
+    'build/**',
+    'next-env.d.ts',
+    'tsconfig.tsbuildinfo',
+  ]),
+])
+
+export default eslintConfig

package/template/lib/aelith.ts

@@ -0,0 +1,59 @@
+import { AelithAuthClient } from '@aelith/auth-core'
+
+export type AelithSessionState = {
+  authenticated: boolean
+  configured: boolean
+  appId: string
+  authOrigin: string
+  userId?: string
+  walletAddress?: string | null
+  email?: string | null
+  app?: string | null
+  error?: string
+}
+
+export type NoticeState = {
+  tone: 'success' | 'error'
+  message: string
+}
+
+export const AELITH_APP_ID =
+  process.env.NEXT_PUBLIC_AELITH_APP_ID?.trim() || '__APP_ID__'
+
+export const AELITH_AUTH_ORIGIN =
+  process.env.NEXT_PUBLIC_AELITH_AUTH_ORIGIN?.trim() || 'https://auth.aelith.ai'
+
+export const DEFAULT_APP_ORIGIN =
+  process.env.NEXT_PUBLIC_APP_URL?.trim() || 'http://localhost:3000'
+
+export const HOSTED_CALLBACK_PATH = '/api/auth/aelith/callback'
+export const SESSION_ENDPOINT = '/api/auth/aelith/session'
+
+export const aelithClient = new AelithAuthClient({
+  appId: AELITH_APP_ID,
+  authOrigin: AELITH_AUTH_ORIGIN,
+})
+
+export function getDefaultHostedRedirectUri() {
+  return `${DEFAULT_APP_ORIGIN}${HOSTED_CALLBACK_PATH}`
+}
+
+export function getHostedRedirectUri() {
+  if (typeof window === 'undefined') {
+    return getDefaultHostedRedirectUri()
+  }
+
+  return `${window.location.origin}${HOSTED_CALLBACK_PATH}`
+}
+
+export function getErrorMessage(error: unknown, fallback: string) {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message
+  }
+
+  return fallback
+}
+
+export async function parseJson<T>(response: Response) {
+  return (await response.json().catch(() => ({}))) as T
+}

package/template/lib/session.ts

@@ -0,0 +1,94 @@
+import 'server-only'
+
+import { AELITH_APP_ID, AELITH_AUTH_ORIGIN, type AelithSessionState } from './aelith'
+
+type VerifyResponse = {
+  valid?: boolean
+  userId?: string
+  walletAddress?: string | null
+  email?: string | null
+  app?: string | null
+  error?: string
+}
+
+const SESSION_COOKIE_NAME =
+  process.env.AELITH_SESSION_COOKIE_NAME?.trim() || '__APP_ID___session'
+
+const SESSION_MAX_AGE_SECONDS = 60 * 60 * 24 * 7
+
+export function getSessionCookieName() {
+  return SESSION_COOKIE_NAME
+}
+
+export function getSessionCookieOptions() {
+  return {
+    httpOnly: true,
+    path: '/',
+    sameSite: 'lax' as const,
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: SESSION_MAX_AGE_SECONDS,
+  }
+}
+
+export function getClearedSessionCookieOptions() {
+  return {
+    ...getSessionCookieOptions(),
+    maxAge: 0,
+  }
+}
+
+export function getBaseSessionState(): AelithSessionState {
+  return {
+    authenticated: false,
+    configured: Boolean(process.env.AELITH_API_KEY?.trim()),
+    appId: AELITH_APP_ID,
+    authOrigin: AELITH_AUTH_ORIGIN,
+  }
+}
+
+export function getSessionErrorMessage(error: unknown) {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message
+  }
+
+  return 'Aelith token verification failed.'
+}
+
+export async function verifyAelithToken(token: string) {
+  const apiKey = process.env.AELITH_API_KEY?.trim()
+  if (!apiKey) {
+    throw new Error('Set AELITH_API_KEY in .env.local before using the session routes.')
+  }
+
+  const response = await fetch(new URL('/api/verify', AELITH_AUTH_ORIGIN), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+    },
+    body: JSON.stringify({ token }),
+    cache: 'no-store',
+  })
+
+  const body = (await response.json().catch(() => ({}))) as VerifyResponse
+  if (!response.ok || !body.valid || !body.userId) {
+    throw new Error(body.error ?? 'Aelith token verification failed.')
+  }
+
+  return body
+}
+
+export async function buildAuthenticatedSessionState(token: string): Promise<AelithSessionState> {
+  const verified = await verifyAelithToken(token)
+
+  return {
+    authenticated: true,
+    configured: true,
+    appId: AELITH_APP_ID,
+    authOrigin: AELITH_AUTH_ORIGIN,
+    userId: verified.userId,
+    walletAddress: verified.walletAddress ?? null,
+    email: verified.email ?? null,
+    app: verified.app ?? null,
+  }
+}

package/template/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/template/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {}
+
+export default nextConfig

package/template/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "__APP_ID__",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@aelith/auth-core": "^0.1.3",
+    "@solana/wallet-adapter-base": "latest",
+    "@solana/wallet-adapter-react": "latest",
+    "@solana/wallet-adapter-react-ui": "latest",
+    "@solana/wallet-adapter-wallets": "latest",
+    "@solana/web3.js": "^1.98.4",
+    "next": "16.2.2",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.2",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

package/template/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
+
+export default config

package/template/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}