Reference sections
Reference › Sessions and authentication
Kitten automatically manages sessions and authentication for you.
You can add a lock emoji (🔒) to the end of any route to make it an authenticated route.
Authenticated routes are only accessible by the owner of the site after they sign in using their secret.
If an authenticated route is a folder, any child routes also require authentication.
Kitten requires sign-in only when the route that responds to a request requires it. So a public route stays public next to an authenticated route that also matches its path (e.g., admin/help.page.js next to admin🔒/[section].page.js, or static files next to a root [slug]🔒.page.js). A visitor who isn’t signed in and requests an authenticated route is redirected to /💕/sign-in/ with a 303. For a GET request that isn’t an upgrade, and whose URL is at most 2,048 characters, the redirect includes the requested URL in the sign-in page’s return parameter, and signing in returns the visitor to it.
Kitten looks for 🔒 only in the part of a route’s path inside your app, so an app in a folder whose path contains 🔒 doesn’t require sign-in everywhere. Kitten removes every 🔒 from a route’s URL, so a🔒/b🔒.page.js responds at /a/b/.
You can also manually check if the owner of the site is signed in by checking if the request.session.authenticated property is true or not. The request.session.authenticated property is read-only, and assigning to it throws a TypeError.
Kitten keeps a session that isn’t signed in only in memory, at most 10,000 of them, and a new session replaces the oldest one at the cap. Its data does not survive a restart or a deploy. Kitten stores a session, and sets its cookie, the first time your route writes to request.session or reads request.session.id, when a live page renders, and when you sign in. This applies to pages, HTTP routes, routes that main.script.js adds through the router object, and middleware added with router.use(). Until then, each request has a new session, so a refusal, a 401 from authorise, a static file, and a route that never uses its session set no cookie. Use the session before your route starts its response: once the headers are sent, a session that is not yet stored cannot be stored, and Kitten prints a warning with the request’s method and URL. A property whose name starts with an underscore is not session data (Kitten never copies one on sign-in), so writing one stores nothing.
Signing in creates a new session, with a new id and the data of the session you signed in from, and ends that session. Kitten stores only a signed-in session’s id and createdAt properties, so the session survives a restart but the data your app stores on it does not.
Signing out ends the session. It takes two requests (the sign-out page’s script clears your identity from the browser and then posts to /💕/sign-out/), so signing out needs JavaScript.
A session expires eight hours after it is created. Kitten deletes a session when it expires, when you sign in from it or sign out, and when a new session replaces it at the cap. When Kitten deletes it, the session emits the kittenSessionDelete event. kittenSessionDelete is a reserved event name. A live page whose session is deleted reloads itself.
When listening for session events from components, use the addSessionEventHandler method, which removes the listener when the component disconnects. If you manually add a listener using the session.on method, remember to remove it with the session.off method in your component’s onDisconnect() handler, passing the same function you passed to the session.on method. A listener that is not removed stays active on the session until it expires and might constitute a leak.
Finally, you can manually direct people to sign in and out by redirecting them to the following routes:
/💕/sign-in/💕/sign-out
Remember that the Small Web – and therefore, Kitten – does not have the concept of users. There is only ever one owner of the site, who is a person. And only this owner can sign into the site. The site might be viewed by countless people over time but they cannot authenticate with it or create accounts on it.
(If you want to build this functionality yourself, for your app, you of course can but it is neither encouraged nor supported. Please see the FAQ for more details.)
The idea is that everyone has their own Small Web site and, when they want to communicate with each other, they do so in a peer-to-peer fashion.
This is the core difference between the Big Web – which is made of up of centralised silos often owned by trillion-dollar and multi-billion-dollar corporations that make their money by farming you for your data – and the Small Web, which is a peer-to-peer web of people who use technology as an everyday tool to communicate with each other and enrich their lives.
To understand the technical architecture of the Small Web better, please see the End-to-end encrypted peer-to-peer Small Web apps tutorial.
To learn more about sessions and authentication, please see the following two tutorials: