A minimal reference app showing Kovo authentication and authorization: a bounded local-only auth fixture, sign-in/sign-out mutations with CSRF protection, role and authed guards on routes, and fixed Better Auth bindings for deployable apps.

Runnable Kovo example app under `examples/reference`. The authored source below shows what it demonstrates — the components, queries, mutations, and derived optimism that drive it (lowered IR / generated components are artifacts, not authored; SPEC §5.2).

```ts title="examples/reference/src/auth.ts"
import { guard, s, session, type Guard, type SessionProvider } from '@kovojs/server';

import { app, type ReferenceAppRequest } from './kovo.js';

export { referenceAuthCsrf } from './kovo.js';

export type ReferenceRole = 'admin' | 'member';

export interface ReferenceSession {
  id: string;
  user: {
    email: string;
    id: string;
    name: string;
    roles: string[];
  };
}

export interface ReferenceRequest {
  authCsrfId?: string | null;
  clientIp?: string;
  db: ReferenceAuthDb;
  headers: Headers;
  session?: ReferenceSession | null;
  url: string;
}

export interface ReferenceAuthFixture {
  readonly sessions: Map<string, { expiresAt: number; sessionId: string; userId: string }>;
  readonly signInRateLimit: Guard<ReferenceRequest>;
}

const referenceAuthFixtureBinding: unique symbol = Symbol('reference.auth.fixture');
const referenceAuthFixtureCapacity = 4_096;
const referenceAuthFixtures = new Map<string, WeakRef<ReferenceAuthFixture>>();
const referenceAuthFixtureFinalizer = new FinalizationRegistry<string>((fixtureId) => {
  referenceAuthFixtures.delete(fixtureId);
});

export interface ReferenceAuthDb {
  readonly [referenceAuthFixtureBinding]: string;
}

export interface ReferenceAuthBindings {
  readonly db: ReferenceAuthDb;
  readonly fixture: ReferenceAuthFixture;
  readonly sessionProvider: SessionProvider<ReferenceRequest, ReferenceSession>;
  readonly signIn: typeof signIn;
  readonly signOut: typeof signOut;
}

export const referenceSession = session(
  s.object({
    id: s.string(),
    user: s.object({
      email: s.string(),
      id: s.string(),
      name: s.string(),
      roles: s.array(s.string()),
    }),
  }),
);

const referenceCookieBaseName = 'kovo_reference_session';
const referenceSessionCapacity = 256;
const referenceSessionTtlSeconds = 60 * 60;
const optionalReferenceString = {
  parse(value: unknown): string | undefined {
    return value === undefined || value === null || value === ''
      ? undefined
      : s.string().parse(value);
  },
};

const referenceUsers = new Map<string, ReferenceSession['user']>([
  [
    'ada@example.com',
    {
      email: 'ada@example.com',
      id: 'u1',
      name: 'Ada Lovelace',
      roles: ['admin', 'member'],
    },
  ],
  [
    'grace@example.com',
    {
      email: 'grace@example.com',
      id: 'u2',
      name: 'Grace Hopper',
      roles: ['member'],
    },
  ],
]);

/** In-memory auth state that is usable only from a local test/development process. */
export function createReferenceAuthFixture(): ReferenceAuthFixture {
  return {
    sessions: new Map(),
    signInRateLimit: createReferenceSignInRateLimit(),
  };
}

const localReferenceSignInGuard = guard<ReferenceAppRequest>(
  'local reference auth fixture with app-owned rate limit',
  (request) => {
    assertReferenceFixtureRequest(request);
    return referenceFixtureFromDb(request.db).signInRateLimit(request);
  },
);

// SPEC §4.1/§10.3: these direct top-level exports are the app-authored source identities.
// `src/auth.ts` + `signIn`/`signOut` derives `auth/sign-in` and `auth/sign-out`.
export const signIn = app.mutation({
  access: [localReferenceSignInGuard],
  errors: { INVALID_CREDENTIALS: s.object({}) },
  input: s.object({
    email: s.string(),
    next: optionalReferenceString,
    password: s.string(),
  }),
  redirectTo: (result: { value: { redirectTo: string } }) => result.value.redirectTo,
  transaction(
    request: ReferenceAppRequest,
    run: (request: ReferenceAppRequest) => Promise<unknown>,
  ): Promise<unknown> {
    return run(request);
  },
  handler(input, request, context) {
    const secure = assertReferenceFixtureRequest(request);
    const user = referenceUsers.get(input.email);
    if (!user || input.password !== referenceFixturePassword()) {
      return context.fail('INVALID_CREDENTIALS', {});
    }
    const token = crypto.randomUUID();
    writeReferenceFixtureSession(referenceFixtureFromDb(request.db), token, user.id);
    context.setCookie?.(referenceCookieName(secure), token, referenceCookieOptions(secure));
    return {
      redirectTo: safeReferenceRedirect(input.next, '/account'),
      status: 'signed-in' as const,
    };
  },
});

const localReferenceSignOutGuard = app.all(
  guard<ReferenceAppRequest>('local reference auth fixture', (request) => {
    assertReferenceFixtureRequest(request);
    return true;
  }),
  app.authenticated,
);

export const signOut = app.mutation({
  access: [localReferenceSignOutGuard],
  input: s.object({}),
  redirectTo: (result: { value: { redirectTo: string } }) => result.value.redirectTo,
  transaction(
    request: ReferenceAppRequest,
    run: (request: ReferenceAppRequest) => Promise<unknown>,
  ): Promise<unknown> {
    return run(request);
  },
  handler(_input, request, context) {
    const secure = assertReferenceFixtureRequest(request);
    const token = readReferenceSessionCookie(request.headers, secure);
    if (token) referenceFixtureFromDb(request.db).sessions.delete(token);
    context.setCookie?.(referenceCookieName(secure), '', {
      ...referenceCookieOptions(secure),
      maxAge: 0,
    });
    return { redirectTo: '/login', status: 'signed-out' as const };
  },
});

export function createReferenceAuth(
  fixture: ReferenceAuthFixture = createReferenceAuthFixture(),
): ReferenceAuthBindings {
  reclaimReferenceAuthFixtures();
  if (referenceAuthFixtures.size >= referenceAuthFixtureCapacity) {
    throw new Error('Reference auth fixture application capacity exceeded.');
  }
  const fixtureId = crypto.randomUUID();
  referenceAuthFixtures.set(fixtureId, new WeakRef(fixture));
  referenceAuthFixtureFinalizer.register(fixture, fixtureId);
  const db = Object.create(null) as ReferenceAuthDb;
  Object.defineProperty(db, referenceAuthFixtureBinding, {
    configurable: false,
    enumerable: false,
    value: fixtureId,
    writable: false,
  });
  const sessionProvider = referenceSession.provider(
    (request: ReferenceRequest): ReferenceSession | null => {
      const secure = assertReferenceFixtureIngress(request);
      const token = readReferenceSessionCookie(request.headers, secure);
      const storedSession = token ? readReferenceFixtureSession(fixture, token) : undefined;
      const user = storedSession
        ? [...referenceUsers.values()].find((candidate) => candidate.id === storedSession.userId)
        : undefined;
      if (!storedSession || !user) return null;
      return {
        id: storedSession.sessionId,
        user: {
          email: user.email,
          id: user.id,
          name: user.name,
          roles: [...user.roles],
        },
      };
    },
  );
  return { db, fixture, sessionProvider, signIn, signOut };
}

export const referenceAuth = createReferenceAuth();
export const referenceSessionProvider = referenceAuth.sessionProvider;
export const referenceSignIn = signIn;
export const referenceSignOut = signOut;

function referenceCookieOptions(secure: boolean) {
  return {
    httpOnly: true,
    maxAge: referenceSessionTtlSeconds,
    path: '/' as const,
    sameSite: 'lax' as const,
    ...(secure ? { secure: true } : {}),
  };
}

function readReferenceSessionCookie(headers: Headers, secure: boolean): string | undefined {
  return readCookie(headers, referenceCookieName(secure));
}

function referenceCookieName(secure: boolean): string {
  return secure ? `__Host-${referenceCookieBaseName}` : referenceCookieBaseName;
}

function assertReferenceFixtureRequest(request: ReferenceRequest): boolean {
  const secure = assertReferenceFixtureIngress(request);
  if (!referenceAddressIsLoopback(request.clientIp)) {
    throw new TypeError(
      'The reference auth fixture requires a framework-resolved loopback client IP.',
    );
  }
  return secure;
}

function assertReferenceFixtureIngress(request: Pick<ReferenceRequest, 'url'>): boolean {
  if (
    process.env.NODE_ENV !== 'test' &&
    !(
      process.env.NODE_ENV === 'development' &&
      process.env.KOVO_ENABLE_LOCAL_AUTH_FIXTURE === 'I_UNDERSTAND_THIS_IS_LOCAL_ONLY'
    )
  ) {
    throw new TypeError(
      'The reference auth fixture requires test mode or the explicit local-only development capability.',
    );
  }
  const parsed = new URL(request.url);
  if (
    (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') ||
    !referenceAddressIsLoopback(parsed.hostname)
  ) {
    throw new TypeError('The reference auth fixture requires an exact loopback request URL.');
  }
  return parsed.protocol === 'https:';
}

function referenceFixturePassword(): string {
  if (process.env.NODE_ENV === 'test') return 'correct';
  const password = process.env.KOVO_LOCAL_AUTH_FIXTURE_PASSWORD;
  if (
    process.env.NODE_ENV === 'development' &&
    process.env.KOVO_ENABLE_LOCAL_AUTH_FIXTURE === 'I_UNDERSTAND_THIS_IS_LOCAL_ONLY' &&
    typeof password === 'string' &&
    password.length >= 16 &&
    password !== 'correct'
  ) {
    return password;
  }
  throw new TypeError(
    'The reference auth fixture requires a nondefault KOVO_LOCAL_AUTH_FIXTURE_PASSWORD of at least 16 characters.',
  );
}

function referenceAddressIsLoopback(value: string | undefined): boolean {
  if (!value) return false;
  if (value === 'localhost' || value === '::1' || value === '[::1]') return true;
  const match = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(value);
  return match !== null && match.slice(1).every((part) => Number(part) <= 255);
}

function referenceFixtureFromDb(db: ReferenceAuthDb): ReferenceAuthFixture {
  const fixtureId = db[referenceAuthFixtureBinding];
  const fixture =
    typeof fixtureId === 'string' ? referenceAuthFixtures.get(fixtureId)?.deref() : undefined;
  if (!fixture)
    throw new TypeError('Reference auth request is not bound to an application fixture.');
  return fixture;
}

function reclaimReferenceAuthFixtures(): void {
  for (const [fixtureId, fixture] of referenceAuthFixtures) {
    if (fixture.deref() === undefined) referenceAuthFixtures.delete(fixtureId);
  }
}

function createReferenceSignInRateLimit(): Guard<ReferenceRequest> {
  const attempts = new Map<string, { count: number; resetAt: number }>();
  return (request) => {
    const now = Date.now();
    for (const [key, entry] of attempts) {
      if (entry.resetAt <= now) attempts.delete(key);
    }
    const key = request.clientIp;
    if (!key) throw new TypeError('Reference auth rate limit requires a resolved client IP.');
    const existing = attempts.get(key);
    if (existing) {
      if (existing.count >= 5) {
        return {
          kind: 'rateLimited',
          retryAfter: Math.max(1, Math.ceil((existing.resetAt - now) / 1_000)),
        };
      }
      existing.count += 1;
      return true;
    }
    if (attempts.size >= 1_024) return { kind: 'rateLimited', retryAfter: 60 };
    attempts.set(key, { count: 1, resetAt: now + 60_000 });
    return true;
  };
}

function readReferenceFixtureSession(
  fixture: ReferenceAuthFixture,
  token: string,
): { sessionId: string; userId: string } | undefined {
  const entry = fixture.sessions.get(token);
  if (!entry) return undefined;
  if (entry.expiresAt <= Date.now()) {
    fixture.sessions.delete(token);
    return undefined;
  }
  return { sessionId: entry.sessionId, userId: entry.userId };
}

function writeReferenceFixtureSession(
  fixture: ReferenceAuthFixture,
  token: string,
  userId: string,
): void {
  const now = Date.now();
  for (const [candidate, entry] of fixture.sessions) {
    if (entry.expiresAt <= now) fixture.sessions.delete(candidate);
  }
  while (fixture.sessions.size >= referenceSessionCapacity) {
    const oldest = fixture.sessions.keys().next().value;
    if (typeof oldest !== 'string') break;
    fixture.sessions.delete(oldest);
  }
  fixture.sessions.set(token, {
    expiresAt: now + referenceSessionTtlSeconds * 1_000,
    sessionId: crypto.randomUUID(),
    userId,
  });
}

function safeReferenceRedirect(value: string | undefined, fallback: string): string {
  if (!value) return fallback;
  for (let index = 0; index < value.length; index += 1) {
    const code = value.charCodeAt(index);
    if (code <= 0x1f || code === 0x7f || code === 0x5c) return fallback;
  }
  return value.startsWith('/') && !value.startsWith('//') ? value : fallback;
}

export function referenceAuthRequest(
  cookie?: string,
  url = 'http://localhost/reference-auth-test',
  db: ReferenceAuthDb = referenceAuth.db,
): ReferenceRequest {
  const headers = new Headers({
    origin: new URL(url).origin,
    'user-agent': 'reference-auth-test',
  });
  if (cookie) headers.set('cookie', cookie);
  return {
    authCsrfId: 'login-csrf',
    clientIp: nextReferenceTestIp(),
    db,
    headers,
    url,
  };
}

let referenceTestRequestCount = 0;

function nextReferenceTestIp(): string {
  referenceTestRequestCount = (referenceTestRequestCount % 250) + 1;
  return `127.0.0.${referenceTestRequestCount}`;
}

function readCookie(headers: Headers, name: string): string | undefined {
  const raw = headers.get('cookie');
  if (!raw) return undefined;
  for (const cookie of raw.split(';')) {
    const [cookieName, ...valueParts] = cookie.trim().split('=');
    if (cookieName === name) return valueParts.join('=');
  }
  return undefined;
}
```
```tsx title="examples/reference/src/app.tsx"
/** @jsxImportSource @kovojs/server */
import { referenceSignIn, referenceSignOut, type ReferenceRequest } from './auth.js';
import { app } from './kovo.js';

export * from './auth.js';

export const accountRoute = app.route('/account', {
  access: [app.authenticated],
  page(_input, request) {
    return (
      <>
        account:{request.session.user.email}
        {renderReferenceLogoutForm()}
      </>
    );
  },
});

export const adminRoute = app.route('/admin', {
  access: [app.role('admin')],
  page(_input, request) {
    return (
      <>
        admin:{request.session?.user.id ?? 'anonymous'}
        {renderReferenceLogoutForm()}
      </>
    );
  },
});

export function renderReferenceLoginForm(
  _request: ReferenceRequest,
  options: { failure?: 'INVALID_CREDENTIALS'; next?: string } = {},
) {
  // SPEC §6.3/§6.5/§9.1: typed mutation forms are the complete public form path. Kovo
  // emits the mutation-bound CSRF field and canonical Kovo-Idem field together.
  return (
    <form mutation={referenceSignIn}>
      <input type="hidden" name="next" value={safeReferenceFormNext(options.next)} />
      <input name="email" type="email" autocomplete="email" required />
      <input name="password" type="password" autocomplete="current-password" required />
      {options.failure === 'INVALID_CREDENTIALS' ? (
        <output role="alert" data-error-code="INVALID_CREDENTIALS">
          Invalid email or password.
        </output>
      ) : (
        ''
      )}
      <button type="submit">Sign in</button>
    </form>
  );
}

export function renderReferenceLogoutForm() {
  return (
    <form mutation={referenceSignOut}>
      <button type="submit">Sign out</button>
    </form>
  );
}

function safeReferenceFormNext(value: string | undefined): string {
  if (!value || !value.startsWith('/') || value.startsWith('//')) return '/account';
  for (let index = 0; index < value.length; index += 1) {
    const code = value.charCodeAt(index);
    if (code <= 0x1f || code === 0x7f || code === 0x5c) return '/account';
  }
  return value;
}
```
```ts title="examples/reference/src/app-shell.ts"
import { createRequestHandler } from '@kovojs/server/custom-adapters';
import { renderRouteHtml } from '@kovojs/server/rendering';
import { toNodeHandler } from '@kovojs/server/node';
import { trustedHtml } from '@kovojs/browser';

import {
  accountRoute,
  adminRoute,
  createReferenceAuth,
  createReferenceAuthFixture,
  referenceSignIn,
  referenceSignOut,
  type ReferenceAuthBindings,
  type ReferenceRequest,
} from './app.js';
import { app } from './kovo.js';
import { registerReferenceApplicationContext } from './reference-context.js';
import { ReferenceShellLoginForm } from './shell-auth-form.js';

export type ReferenceShellRequest = Request & ReferenceRequest;

export interface ReferenceAppShellOptions {
  auth?: ReferenceAuthBindings;
}

export const referenceLoginRoute = app.route('/login', {
  // The sign-in page must be reachable before authentication — public by design
  // (KV436 access decision, SPEC §10.2).
  access: app.publicAccess('sign-in page reachable before authentication'),
  meta: {
    description: 'Sign in to the Kovo reference app.',
    title: 'Kovo Reference Sign In',
  },
  page(context) {
    const next = typeof context.search.next === 'string' ? context.search.next : '/account';
    return trustedHtml(`<main>${ReferenceShellLoginForm({ next })}</main>`, {
      reason: 'reference login route composes the reviewed login form renderer',
      source: 'examples/reference/src/app-shell.ts',
    });
  },
});

const referenceRuntimeApp = app.assemble({
  mutations: [referenceSignIn, referenceSignOut],
  routes: [referenceLoginRoute, accountRoute, adminRoute],
});

export function createReferenceAppShell(options: ReferenceAppShellOptions = {}) {
  const application = createReferenceApplication(options);
  const requestHandler = createRequestHandler(application.app);
  return {
    ...application,
    nodeHandler: toNodeHandler(requestHandler),
    requestHandler,
  };
}

export function createReferenceApplication(options: ReferenceAppShellOptions = {}) {
  const auth = options.auth ?? createReferenceAuth(createReferenceAuthFixture());
  registerReferenceApplicationContext(auth);
  return { app: referenceRuntimeApp, auth };
}

export function routeValueToHtml(value: unknown): string {
  return renderRouteHtml(value);
}

export const referenceAppShell = createReferenceApplication();

export default referenceAppShell.app;
```