Kernel Auth Contract

Hono Integration

// apps/api/src/middleware/auth.ts
import { auth } from "@your-org/auth";

// Mount Better-Auth handler — handles all /api/auth/* routes
app.on(["POST", "GET"], "/api/auth/**", (c) => auth.handler(c.req.raw));

// Session middleware — attaches session to context
export async function sessionMiddleware(c: Context, next: Next) {
  const session = await auth.api.getSession({ headers: c.req.raw.headers });
  c.set("session", session);
  await next();
}

// Auth guard — rejects unauthenticated requests
export async function requireAuth(c: Context, next: Next) {
  const session = c.get("session");
  if (!session) return c.json(ApiErrors.UNAUTHORIZED, 401);
  await next();
}

Authorization as a Separate Layer

Better-Auth handles authentication. Role checks are app-level middleware.

export function requireRole(...roles: string[]) {
  return async (c: Context, next: Next) => {
    const session = c.get("session");
    if (!session) return c.json(ApiErrors.UNAUTHORIZED, 401);
    if (!roles.some((r) => session.user.role === r)) {
      return c.json(ApiErrors.FORBIDDEN, 403);
    }
    await next();
  };
}

// Usage — middleware chain
app.post("/api/admin/users", requireAuth, requireRole("admin"), handler);

Never conflate authentication and authorization in the same middleware.

Client Setup

// packages/auth/src/client.ts
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_APP_URL,
});

export const { useSession, signIn, signOut, signUp } = authClient;

Protected Routes (Frontend)

import { useSession } from "@your-org/auth/client";

function RequireAuth({ children }: { children: React.ReactNode }) {
  const { data: session, isPending } = useSession();

  if (isPending) return <AuthSkeleton />;

  if (!session) {
    return <Navigate to={`/login?returnTo=${encodeURIComponent(location.pathname)}`} />;
  }

  return <>{children}</>;
}

Three states every auth guard must handle: loading, authenticated, unauthenticated.

Login and Logout

// Login
await signIn.email({ email, password, callbackURL: returnTo ?? "/dashboard" });

// Logout
await signOut();
queryClient.clear(); // purge all cached data after logout

Never POST to /auth/login manually — use Better-Auth's signIn.* methods. Never manage cookies manually.

Inter-Service Authentication

Better-Auth does not cover service-to-service auth. Use short-lived signed tokens for this case only.

// Service-to-service: short-lived signed token with service claim
const serviceToken = await signToken({
  sub: "service:worker",
  aud: "service:api",
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + 60, // 60-second lifetime
});

// Receiving service verifies aud claim
const payload = await verifyToken(token, { audience: "service:api" });

• Each service pair has unique credentials — never share credentials between services
• Rotate service credentials on a schedule, not only on breach

Guardrails

• Never implement custom session handling, JWT issuance, or password hashing — Better-Auth owns all of this
• Never store tokens in localStorage or sessionStorage — Better-Auth uses httpOnly cookies
• Never log tokens, session cookies, or credentials — even in debug mode
• Never store user identity in useState — use useSession() from Better-Auth
• Never call auth endpoints manually — use Better-Auth's typed client methods
• Every API endpoint must have an explicit auth requirement (even if it's public)
• Authorization (role checks) is app-level — never inside Better-Auth config