Kitten

Technical Manual sections

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.

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.

  1. Identity creation. On the first start, Kitten generates a domainToken (or stores the one that a Catalyst instance passes with the --domain-token option). On every start until the owner creates an identity, it prints a one-time link to /šŸ’•/hello/<domainToken>/. That page (web/šŸ’•/hello) calls createKeys() 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 create command 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).

  2. 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. The POST route verifies the signature, the useSignInChallenge() function accepts each challenge only once, and the person is signed in.

    The sign-in page takes the path to return to from its return query parameter (which the requireSignIn() 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, the POST route redirects them to that path, or to /🐱/settings/ if there isn’t one. Both routes check the path with the signInReturnPath() 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.

  3. 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:

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.