Technical Manual sections
Reference āŗ Technical Manual āŗ Sessions and sign-in
src/Sessions.ts manages sessions. The sessions middleware adds the personās session to each request as request.session without storing a new one. For a request that isnāt an upgrade, it wraps the session in a proxy (storeOnUse() in src/lib/storeOnUse.ts) that stores it (Sessions.store()) the first time a route uses it.
A sessionās id is 18 random bytes in hexadecimal, in a
sessionIdcookie that is HTTP-only, secure,SameSite=Strict, and lasts eight hours.Kitten stores a session that isnāt signed in only in memory: for at most eight hours, and at most 10,000 of them, deleting the oldest first.
Kitten stores a session, and sets its cookie, the first time a route (a page, an HTTP route, or a route added through the
routerobject) or middleware added withrouter.usewrites torequest.sessionor readsrequest.session.id. A live page stores its session before the page route creates the page (storeSessionNow()), so that its socket finds the same session, and signing in stores the new session. For any other request, including a WebSocket upgrade, a refusal byrequireSignIn(), a 401 fromauthorise, and a static file, Kitten creates a session that it doesnāt store and sets no cookie for.Writing a property whose name starts with an underscore stores nothing, as it is not session data. Once the response headers are sent, a session that is not yet stored cannot be stored: its first use after that stores nothing, and Kitten prints a warning with the requestās method and URL. A session that has ended (one that a sign-in replaced, or one that Kitten deleted on sign-out, expiry, or eviction at the cap) is never stored again (
Sessions.hasEnded()).Signing in (
Sessions.signIn()) creates a new session with a new id and the data of the previous session (except properties whose names start with an underscore), and deletes the previous session. Kitten persists only theidandcreatedAtproperties of each signed-in session inkitten._db.sessions, so a signed-in session survives a restart and the data an app stores on it does not.A session expires eight hours after Kitten creates it. Kitten deletes expired sessions once an hour, and deletes an expired session when a request uses it.
Deleting a session (on sign-out, on expiry, on eviction at the cap, or when a sign-in replaces it) calls the sessionās
kittenSessionDeletelisteners and emits thekittenSessionDeleteevent on thekitten.eventsevent emitter. Each live page of that session listens for it and reloads.
Each Kitten place has one owner, identified by an ed25519 key pair. Kitten stores only the public keys, in kitten._db.settings.id. When the owner creates their identity in the browser, the secret key never reaches the server, as the browser generates it.
Identity creation. On the first start, Kitten generates a
domainToken(or stores the one that a Catalyst instance passes with the--domain-tokenoption). On every start until the owner creates an identity, it prints a one-time link to /š/hello/<domainToken>/. That page (web/š/hello) callscreateKeys()from Kittenās crypto module in the browser, shows the secret encoded as KittenMoji (a string of emoji that the owner keeps, e.g., in a password manager), and sends the public keys over the pageās socket. The server stores them only if no identity exists yet and the token matches.The owner can also create their identity with the
.id createcommand in the interactive shell. In that case, Kitten generates the keys on the server, stores the public keys, displays the secret (which it doesnāt store), and asks the terminal to copy the secret to the clipboard (clipboardCopySequence()in src/lib/clipboardCopySequence.ts).Sign-in. The sign-in page (web/š/sign-in) includes a challenge from
issueSignInChallenge()(src/lib/signInChallenge.ts): a random nonce and an expiry five minutes ahead, authenticated with an HMAC (hash-based message authentication code) whose key Kitten generates when the process starts. The browser decodes the secret, signs the challenge, checks the signature against the public key from /š/id/, stores the identity as non-extractable Web Crypto keys in IndexedDB (src/lib/keyStore.ts), and posts the signature. ThePOSTroute verifies the signature, theuseSignInChallenge()function accepts each challenge only once, and the person is signed in.The sign-in page takes the path to return to from its
returnquery parameter (which therequireSignIn()function sets; see The route handler) or, if there isnāt one, from the referrer, and posts it with the signature. Once the person is signed in, thePOSTroute redirects them to that path, or to /š±/settings/ if there isnāt one. Both routes check the path with thesignInReturnPath()function in src/Utils.ts, which only accepts paths on the same site that are at most 2,048 characters long, and refuses the identity creation, sign-in, and sign-out paths and paths that end with.socket.Sign-out. /š/sign-out/ serves a page whose script clears the identity from the browserās key store and then posts to /š/sign-out/ to end the session.
Note that a restart creates a new HMAC key, so a sign-in page loaded before a restart sends the person back to the sign-in page when they submit it.
The build bundles crypto.ts and keyStore.ts for the browser as /š±/library/crypto-1.js and /š±/library/key-store-1.js. On the server, crypto.ts is kitten.crypto.
Source code: