auth

Sign users in and out, protect pages, and check who can do what.

AuthClientServer

What it is

@kitr/auth gives the app one session, guards for pages, middleware for API routes and permissions written once as plain functions. Tokens are stored where the platform keeps them safest.

@kitr/auth/server runs without React and brings the server half: createCookieSession (signed HttpOnly cookies over a memory, storage or Redis store), hashPassword and verifyPassword, a UserProvider you implement over your database (a memory one for demos), and createSessionController for sign-in, sign-out, sign-up, password reset and email verification. Or connect to Better Auth or any identity provider through an adapter; there is no hosted sign-in service to subscribe to.

Install

kitr add auth

First time? Run npm i -g @kitr/kitr once. Inside a project, the global kitr runs your project's own version.

Adds @kitr/auth, its provider, config/auth.ts and app/abilities.ts. The guide's Install section lists the adapter flags.

Quick start

Every component can read the session. Show the signed-in user and a sign-out button:

// app/components/account_menu.tsx
import { useAuth, useUser } from '@kitr/auth'
import { Link } from '@kitr/router'
import type { User } from '#app/abilities'

export function AccountMenu() {
  const auth = useAuth()
  const user = useUser<User>()
  if (!user) return <Link to="/sign-in">Sign in</Link>
  return (
    <button type="button" onClick={() => auth.signOut()}>
      Sign out {user.email}
    </button>
  )
}

Before sign-in it shows "Sign in"; after Ada signs in it shows "Sign out [email protected]", and it re-renders on every sign-in and sign-out anywhere in the app. Protect a page with one line in the route table:

// app/routes.ts
r.page('/settings', { beforeLoad: requireAuth(), lazy: () => import('./pages/settings') })

Next in the guide: Show who is signed in.

Built on

@kitr/auth has no identity provider of its own. It is built on three things kitr already has:

Built on Role
An auth adapter you choose Signs in, signs out and refreshes. Better Auth and a generic token adapter are built in; the Extend section shows a custom one.
Storage and Secure storage Cookies on the web, the device vault in native shells, so the session survives a reload.
Router and API routes requireAuth, can and guards run in beforeLoad; authMiddleware runs in front of controllers.

kitr adds the session store, abilities, the React hooks, the router guards, the server middleware and the token plumbing for http.

Problems it solves

Further reading